libra/docs/ux-design.md

UX / Design Reference — Libra Law Firm

Retrospective documentation of the design system as it is currently built and live. This is not a proposal — it describes what shipped, so a dev/QA agent picking up a new task can match existing patterns rather than invent new ones. Synthesized from docs/brand.md, epics 9/10/12/13/14/16, and the root CLAUDE.md.

Brand colors (current — source of truth: docs/brand.md)

The palette has changed twice since the original PRD. Use the values below, from docs/brand.md, for any new work — they are the most recent and match what Epic 12 shipped.

Token	Hex	Usage
Primary — Dark Forest Green	#2D3624	Header/footer backgrounds
CTA — Warm Gold	#A68966	Buttons, links, accents
Background — Warm Cream	#F4F1EA	Main page background
Text — Forest Green	#2D322A	Headings, body text
Card — Pure White	#FFFFFF	Card backgrounds
Active — Olive Green	#4A5D23	Active states, language toggle
Primary Light	#3D4634	Primary hover state
CTA Hover	#8A7555	Button hover state
CTA Light	#C4A882	Light accents
Active Hover	#5A7030	Active-state hover
Deep Black	#1A1A1A	Logo artwork, headline emphasis

History (do not use these for new work, they are superseded):

• Epic 1 / PRD / Epic 9 originally specified Navy Blue #0A1F44 + Gold #D4AF37.
• Epic 10 ("Brand Color Refresh") replaced that with Charcoal #4A4A42 + Warm Gray #C9C4BA.
• Epic 12 ("Branding Refresh") replaced that with the Dark Forest Green + Warm Gold palette above, which is what docs/brand.md documents and what is currently live. Epic 9's own stories (button/form/card specs) still reference the original Navy+Gold hex values — treat those as structural/pattern guidance only (border-radius, padding, states) and substitute the current hex values from the table above.

Typography

• Arabic: Cairo or Tajawal (Google Fonts), weights Light 300 / Regular 400 / SemiBold 600 / Bold 700.
• English: Montserrat or Lato, same weight set.
• docs/brand.md additionally suggests a serif (Playfair Display / Libre Baskerville) for the organization name/headline treatment and an italic serif for taglines, with a sans body (Source Sans Pro / Open Sans / Inter) — this is brand-identity guidance; the app itself implements the Cairo/Tajawal + Montserrat/Lato pairing from Epic 9.2.
• Hierarchy: H1 Bold 2.5rem/40px · H2 SemiBold 2rem/32px · H3 SemiBold 1.5rem/24px · Body Regular 1rem/16px · Small Regular 0.875rem/14px.
• Line height: 1.6 body, 1.3 headings.
• font-display: swap, critical fonts preloaded, loaded via Google Fonts + Tailwind font-family config with @font-face fallbacks.

Layout system

• Container max-width: 1200px.
• Card padding: 24px; card border-radius: 8px; card shadow 0 2px 8px rgba(0,0,0,0.1), with a subtle lift + shadow increase on hover.
• Button padding 12px 24px, border-radius 6px; input/textarea padding 12px 16px, border-radius 6px, textarea min-height 120px.
• Breakpoints: Mobile <576px · Tablet 576–991px · Desktop 992–1199px · Large Desktop >=1200px. Mobile-first: single-column + collapsible sections on mobile, two-column/collapsible sidebar on tablet, full multi-column grid + sidebars on desktop. Touch targets >= 44px. Tables scroll horizontally on small screens; calendar and forms must remain usable on mobile.
• Transitions are short and subtle: button hover 150ms ease, card hover 200ms ease, modal open/close 200ms, all under 300ms — and must respect prefers-reduced-motion (no auto-playing animations).

Component patterns (Epic 9 stories 9.4–9.7)

• Buttons: primary = CTA-gold background / dark text, hover to CTA-hover; secondary = transparent with gold border + gold text, hover fills gold with dark text; disabled = flat gray background/text, no hover, cursor: not-allowed; danger = solid red (#E74C3C) with white text. Loading state shows a spinner; all buttons have a visible focus state. Built by extending Flux UI's button component with Tailwind component classes.
• Forms: inputs/textareas/selects share consistent border + radius, gold border on focus; selects and checkboxes/radios are custom-styled (not native) with gold accents on checked/selected state; labels are SemiBold with a * required indicator; errors show a red border plus a message rendered directly below the field. Built on Flux UI form components with explicit RTL alignment handling.
• Cards/containers: off-white/cream background, optional gold top/left accent border for featured or important cards; dashboard stat cards add a gold-accented icon, a large number, and a trend indicator; list cards use consistent item spacing and clear click targets. Implemented as a reusable Blade card component with variant props.
• Navigation/footer: fixed-top nav, brand-primary background, logo left on desktop / centered on mobile, gold link text with an active-link indicator, styled language toggle, and a full-width slide/dropdown mobile menu (Alpine.js) with 44px+ touch targets. Footer shares the brand-primary background and carries logo + firm info, contact details, Terms/Privacy links, and copyright; it stays pinned to the bottom of short pages (sticky footer).

Bilingual / RTL–LTR rules

• Arabic is primary and renders RTL; English is secondary, LTR. dir="rtl" is set on <html> for Arabic; layout uses Tailwind's RTL support and logical properties (start/end rather than left/right) so components flip automatically rather than needing per-direction overrides.
• In RTL: text aligns right, navigation mirrors (logo moves to the right), form labels sit on the right, directional icons/arrows flip, and margins/paddings swap sides.
• Switching language must not break layout — calendars and tables must render correctly in both directions, and every component is expected to be tested in both.
• All user-facing strings live in language files (ar/en); there is no hardcoded UI copy.

Key page layouts

• Home (Epic 14): Navigation → Hero (tagline + intro + CTA buttons, Warm Cream background) → About (Huda Armouche's photo + bio) → Services (4 cards: Consultations, Representation, Litigation, Contracts) → Values (6 icon cards) → Latest Posts (3 most recent published posts, pulled live via Post::where('status','published')->latest()->take(3)->get(), with a "View All" link) → Footer (phone + address + links). Sections alternate between Warm Cream and White backgrounds; CTAs use Warm Gold.
• About Us (Epic 16, new page at /about): Navigation → Hero (title + identity statement) → Vision & Mission (three-fold: For Itself / For Society / For Diaspora, card layout) → Values (6 core values: Integrity, Justice, Knowledge, Women's Empowerment, Professionalism, Social Innovation) → Goals (7 goals, numbered/scannable) → Legal Services (grouped by category: consultations, litigation, family law, business services) → Footer. (A Scholarship Aspiration section was built under this epic but removed from /about entirely on 2026-01-11 at Naser's request — do not re-add without confirming; see docs/tasks/16-6.md.)
• Auth pages (Epic 13 — login, forgot/reset password, confirm-password, email verify): the 2FA challenge page exists in code but is currently dormant — 2FA has been disabled in production since 2026-01-17 (see root CLAUDE.md Authentication section). Split-screen layout. Left panel: Dark Forest Green (#2D3624) background with the LIBRA logo centered. Right panel: Warm Cream background with a subtle SVG botanical/geometric background pattern (low-opacity brand colors) behind the form. On mobile, only the form side shows, with the logo displayed above it. The language toggle's light variant was darkened (text-primary instead of text-body/70) specifically for visibility on this light panel, without changing its appearance on the dark public-nav background.
• Dashboards (Epics 6 admin / 7 client): standard authenticated-app shell — nav/sidebar + content area using the same card, button, and table components as the rest of the app. Admin dashboard emphasizes stat cards, Chart.js analytics, and data tables with export actions; client dashboard is read-mostly (consultations, timelines, profile) with a single primary action (submit new booking) and a booking-limit indicator.

Accessibility (WCAG AA — Epic 9.10)

• Color contrast: body text >= 4.5:1, large text (18px+ bold or 24px+ regular) >= 3:1, UI elements (buttons, borders, icons) >= 3:1. The gold-on-dark-forest-green and text-on-cream combinations must be verified against these ratios whenever a color changes.
• Focus indicators must be visible (a gold outline), never conveyed by color change alone.
• Full keyboard navigation: every interactive element reachable, logical tab order, a skip-to-main-content link.
• Screen readers: correct heading hierarchy (h1 > h2 > h3), alt text on all images, ARIA labels where needed, form labels programmatically associated with their fields.
• Motion: respect prefers-reduced-motion; no auto-playing animations.