Master Frontend Guide

Live screenshot from the SOQ beauty demo (aiacademy.aiee.dev).

SOQ International Academy TMS “ UI/UX designer handover ” AI coding agent ready — Updated 2026-09-14

On this page

• How to use this guide
• Product overview
• Three frontend surfaces
• Roles & vocabulary
• Design system
• Component patterns
• Screen map
• Redesign priority
• User journeys
• Feature gates & stubs
• Assets & build
• AI coding rules
• Figma structure
• Open questions

How to use this document

1. Read Product + Surfaces + Roles first — do not invent a fourth surface without product approval.
2. Use Design system + Components — prefer tokens over one-off hex colours.
3. Use Screen map + Journeys — match business logic before changing IA.
4. Use AI coding rules when generating Blade/Sass/JS — wrong paths break Mix builds.
5. Always check business logic in Technical Master before redesigning purchase, payout, quiz, attendance, or org seats.

Sibling documents

Demo tip logins

Toggle SOQ_DEMO_TIPS=true for in-app tips, and DEMO_ONE_CLICK_LOGIN=true for 1-click buttons on /login plus the header Demo dropdown. Full credentials: Demo Accounts — Beauty Demo Pack.

0. Product in one page

SOQ International Academy is a Singapore PEI delivering AI & Business, Beauty & Wellness, Retail & Soft Skills, and workshops — campus + online.

Platform promise: Discover ? Learn ? Credential ? Career

Nine product areas

UX principles (locked)

• Role-based dashboards — never show Admin chrome to students; never put Admin users in Panel
• No unnecessary friction — clear wizards; show package limits early
• Mobile-ready — responsive design_1; Mobile API is separate
• Brand / PEI trust — public site must feel like SOQ Academy
• Self-serve help — Support Widget shipped; extend KB / tips as needed
• Security visible when needed — explain payout approval, offline pending, device limits

1. Three frontend surfaces (critical)

The product is not one app. It is three UIs sharing one Laravel backend.

Admin URL prefix is configurable — use getAdminPanelUrl(), never hardcode /admin/....

Tech stack

Implication: Redesigns should stay Blade-compatible unless product approves an SPA rewrite. Prefer evolving design_1 + Admin module-by-module.

2–3. Vocabulary & role matrix

Panel sidebar logic: Source/app/Mixins/Panel/SidebarItems.php — filtered by permissions and feature settings. Do not design a static mega-nav that ignores permissions.

Also see: User Roles, Become Instructor, Organization Users.

4–5. Design system

New and redesigned UI uses the SOQ Edu navy + gold Tailwind system: docs/engineering/product/brand-guide.md, tokens in resources/views/design_1/web/home/soq-home-tailwind.input.css, compiled to public/assets/design_1/css/soq-edu-home.css (npm run build:soq-home). Reference screens: public home and the /panel dashboards. A redesign changes visuals only and keeps every partial, data point, link, form field, JS hook and permission condition of the old view.

The table below is the legacy blue + lime palette (soq-theme.css), still used by screens not yet redesigned. Do not use it for new UI.

Rule: Prefer CSS variables from soq-theme.css / theme helpers. Lime / .bg-accent uses foreground #111 (never white). Blue fills use white text. Ignore leftover --soq-pink / purple stock. New UI icons: inline Lucide-style SVG (legacy screens: Iconsax linear).

Operator pages: Colors, Fonts, Personalization, Custom CSS & JS.

6. Component & interaction grammar

~70% of Panel/Admin screens follow the same pattern — reuse it unless replacing system-wide.

Panel list page

1. Extend panel layout
2. Optional top stats (card-statistic)
3. White rounded container (bg-white rounded-24)
4. Filters (Select2 + DateRangePicker)
5. Table (panel-table) + row partial
6. AJAX pagination (get_view_data.js)
7. Empty state (no-result)

Feedback: toast showToast “ destructive confirm SweetAlert2 ” demo tips Tippy — status badges bg-success-30 text-success.

7. Screen map (key paths)

~1,500 Blade views under Source/resources/views/.

Related: Create a Course, Quizzes & Certificates, Live Classes, Certificate Validation.

8. Redesign priority

9. User journeys

Full diagrams (master + each role): User Flows & Role Diagrams.

Student

Browse ? Course page ? Cart ? Pay ? Learning page ? Quiz ? Certificate ? (Jobs/support)

Instructor

Become instructor ? Package ? Admin accept ? Create course (8 steps) ? Live ? Sales ? Payout

Create course steps: 1 Basic “ 2 Extra ” 3 Pricing “ 4 Content ” 5 Prerequisites “ 6 FAQ ” 7 Quiz & certificate — 8 Message to reviewer

Organization

Org package ? Add instructors/students ? Org classes ? Financial (show seat limits early)

Admin

Users/roles ? Review classes ? Sales & offline ? Payouts ? Settings/theme

Attendance

Panel ? Courses ? Attendances ? Session ? present / late / absent

Live join

Learning page ? join ? BBB | Agora | Zoom | Jitsi (entitlement required)

10. Feature gates & stubs

Do not redesign blindly: Admin Enrollment depends on features + permissions. Jobs/Events/Attendance depend on settings + permissions.

11. Assets & build

AJAX lists: resources/js/design_1/parts/get_view_data.js — CSRF: app_includes/ajax_setup.js

12–14. Copy rules & AI coding rules

Copy

• Say “Class/Course” to learners “ not ”Webinar — (code-only term)
• SGD formatting; Singapore English
• Explain pending offline payment & payout approval

Always

1. Check business logic before changing a flow
2. Preserve three surfaces + role matrix
3. Gate UI with @can / feature settings
4. Use theme CSS variables
5. Reuse list/filter/table/toast/SweetAlert patterns
6. Keep domain routes unless backend changes in same PR
7. Add demo tips for new primary actions
8. Compile assets with Mix after Sass/JS edits

Never

• Put Admin users into Panel IA
• Hardcode Admin URL prefix
• Assume stub Admin features are live
• Introduce React/Vue for one screen without API + architecture decision
• Ship learner-facing “webinar” wording

Definition of done

• Role visibility correct — Desktop + mobile checked
• Empty / loading / error / pending states
• Permissions & feature-off considered — Strings via trans()
• Theme variables used — AJAX list pattern intact if list page

15. Suggested Figma structure

SOQ TMS Design/
 00 Foundation/ tokens, type, icons, components
 01 Web/ marketing, catalogue, course, cart, auth, learning
 02 Panel Student/
 03 Panel Instructor/
 04 Panel Organization/
 05 Admin/
 06 Flows/ purchase, create course, payout, quiz, attendance
 07 Specs/ redlines + notes for AI agents

Annotate each frame: Role “ Surface ” Permission “ Feature flag ” Empty state — Blade path

17. Open questions (confirm before big redesign)

1. Full SOQ brand redesign of public site, or theme-token restyle of design_1?
2. Should Admin stay Stisla-like, or unify with Panel visual language?
3. Is Product 9 (in-app help) in Lyn's first milestone?
4. Which modules are Mode A only vs marketplace Mode B for launch?
5. Which Admin stubs (e.g. Enrollment) must be unblocked vs hidden?