Design System

🎨 UI/UX Guidelines

Tokens, components, patterns, and accessibility rules powering a consistent, accessible, and Arabic-first experience.

Design Principles

🎯 Clarity over cleverness

Every screen has one primary action. Hierarchy is unambiguous. Labels are plain Arabic / plain English — no jargon.

🌐 Locale-equal

Arabic is the default; English mirrors it perfectly. Layouts flip with the language — they don't degrade.

📱 Mobile-first

The student majority uses mobile. We design for touch, then scale up to desktop dashboards.

⏱️ Perceived speed

Skeleton loaders, optimistic UI on reactions / cart, and progressive image loading.

♿ Inclusive

WCAG AA contrast, focus rings, keyboard support, screen reader semantics.

🤝 Forgiving

Destructive actions ask for confirmation. Undo where possible. Errors are descriptive and recoverable.

Color System

The primary brand color is iSpeaker Blue. Semantic colors signal status and severity consistently across web, mobile, and admin.

Brand scale

Brand 50

#eef4ff — surfaces, badges

Brand 100

#dbe7ff

Brand 300

#93b3ff

Brand 500

#3977f6 — primary actions

Brand 700

#2649ad — hover/pressed

Brand 900

#1f366d — text on light

Semantic colors

Success

#10b981 — confirmations, paid status, completed lessons

Warning

#f59e0b — pending, drafts, attention needed

Danger

#ef4444 — destructive, errors, rejections

Info

#06b6d4 — neutral hints, scheduled, public

Purple

#8b5cf6 — courses module accent

Pink

#ec4899 — books module accent

💡

Use semantic colors for meaning only. Never use red for a delete button "just because" — use it because the action is destructive.

Dark mode

All surfaces, borders, and shadows have dark equivalents. Brand colors stay the same; backgrounds shift to a deep navy palette. Toggle this site's theme via the moon/sun icon in the top bar to preview.

Typography

Type families

Locale	Family	Weights
Arabic (RTL)	Tajawal · fallback: Cairo, IBM Plex Sans Arabic, system	400, 500, 700, 800
English (LTR)	Inter · fallback: SF Pro, Segoe UI, system	400, 500, 600, 700, 800
Code	JetBrains Mono · fallback: Fira Code, monospace	400, 500

Type scale

Role	Size	Weight	Line height	Use
Display	2.5 – 3 rem	800	1.1	Marketing hero only
H1	2 rem	700	1.15	Page title
H2	1.5 rem	700	1.25	Section title
H3	1.15 rem	600	1.35	Subsection
Body	0.9375 rem	400	1.65	Default
Small	0.85 rem	400	1.5	Captions, helper
Eyebrow	0.75 rem	700	1.4	UPPERCASE labels

Spacing & Layout

Spacing scale (4 px base)

4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 — always pick from this scale.

Grid & breakpoints

Breakpoint	Min width	Layout
Mobile	0	Single column, full-bleed cards
Tablet	640 px	2-column grids where useful
Laptop	900 px	Sidebar + content for dashboards
Desktop	1200 px	Max content width 1200 px

Radii & elevation

Pills & chips: 999 px
Buttons & inputs: 10–12 px
Cards: 12 px default, 16 px for hero / spotlight
Shadows: only on hover/elevated states; never under input fields.

Component Library

The web app uses shadcn/ui-style components on top of Tailwind. The mobile app mirrors them with custom Flutter widgets in core/widgets/. The Filament admin uses Filament's native components themed to brand.

Buttons

Primary, secondary, ghost, destructive. Loading state shows spinner; disabled is fully non-interactive.

Inputs

Label above, helper below, error inline. Required marker. RTL-aware icons.

Modals / Bottom sheets

Modal on desktop; bottom sheet on mobile. ESC closes; backdrop click closes destructive only via confirm.

Cards

Used for posts, courses, books, rooms, speakers. Consistent thumbnail aspect 16:9.

Avatars

Circular, with fallback to initials on brand gradient. Online dot on profiles.

Badges

Status pills: published, draft, archived, paid, free, pending, scheduled, completed.

Tabs

For dashboard sub-sections; underline indicator; preserves URL state.

Tables & lists

Sticky header on dashboards; pagination at bottom; row hover.

Toasts

Top-right (LTR) / top-left (RTL). Auto-dismiss 4 s. Success / info / warning / error.

Snackbars (mobile)

Bottom of screen, single line, optional action.

Skeletons

Shape-matched skeleton for every list/detail card.

Date / Time picker

Locale-aware (Hijri optional later); 24h or 12h per locale convention.

UI Patterns

Navigation

Web (student): top bar + side dashboard for "My X" pages.
Web (speaker): persistent left sidebar with section grouping.
Mobile: bottom tab bar (5 tabs) + per-feature internal navigation.

Forms

Single-column layout, labels above fields.
Inline validation on blur, summary on submit.
Submit button is sticky on long mobile forms.

Lists & feeds

Infinite scroll on feed; cursor-based pagination on API.
Pull-to-refresh on mobile.
"Load more" button as accessible fallback.

Media

Always render a placeholder aspect ratio to prevent layout shift.
Lazy-load below-fold images.
Use signed URLs for protected media (books, paid lessons).

Empty, Loading & Error States

Every list view must define all four states

State	What to show
Loading	Skeleton matching final shape, ≥ 3 placeholders.
Empty (first time)	Illustration + reason + CTA ("Start browsing courses").
Empty (filtered)	Acknowledge filter + button to clear ("No results — clear filters").
Error	Friendly title, retry button, contact support link.

⚠️

Testers: verify every empty / error / loading state — these are the easiest to miss in code reviews.

Accessibility

Targets

WCAG 2.1 AA conformance.
Color contrast ≥ 4.5:1 for body, ≥ 3:1 for large text.
Touch targets ≥ 44 × 44 dp / px.
Visible focus indicator on every focusable element.

Keyboard

Logical tab order, no traps.
Esc closes modals; Enter submits primary form.
Skip-to-content link on every page.

Screen readers

Semantic landmarks (<header>, <nav>, <main>, <footer>).
Form fields have labels (or aria-label when visually hidden is intentional).
Icon-only buttons carry aria-label.
Live regions for toasts & chat messages.

Motion

Respect prefers-reduced-motion on web.
No autoplay video with sound.

Mobile-Specific Guidelines

Bottom tab bar is the primary navigation; never collapse it inside flows.
Safe-area insets on iOS — header and FAB must respect notch & home indicator.
Pull-to-refresh on feed, notifications, chat conversations, marketplace.
Use platform-native dialogs (Cupertino on iOS, Material on Android) where it improves familiarity.
Image uploads must compress > 1 MB; long uploads show progress & allow cancel.
Background fetches should not block UI; show offline banner if connection drops.

UI/UX QA Checklist

Use this list during every UI test pass. See Test Cases for the formal versions.

Per screen

☐ Title is meaningful and translatable.
☐ Loading skeleton matches final layout.
☐ Empty & error states present and helpful.
☐ Primary action is unambiguous & reachable on small screens.
☐ Tab order is logical (Tab forward, Shift-Tab back).
☐ Focus styles visible on every interactive element.
☐ All icons have accessible names.
☐ Long content scrolls — nothing is cut off.
☐ RTL: layout mirrors; numbers stay LTR; arrows flip; punctuation correct.
☐ Dark mode: contrast preserved; no near-white surfaces.
☐ All copy in en and ar files; no hard-coded strings.
☐ Forms validate inline; errors readable; field receives focus on first error.
☐ Destructive actions confirm; result of action is communicated.
☐ Performance: page is interactive < 3 s on 3G simulation.