baya-monorepo/archive/build-chain/working-context/reports/ui-phase-0-report.md

UI Phase 0 — Design language & theme foundation — Report (2026-07-17)

What was built

theme.components pass (the highest-leverage change)

client/src/theme/theme.ts now carries a components block covering MuiCssBaseline (global :focus-visible → 2px var(--bal-focus-ring)), MuiButton (disableElevation, --bal-radius-sm, comfortable padding), MuiPaper (hairline var(--bal-divider) border, backgroundImage: none), MuiAppBar (cream/paper surface + hairline bottom border, color="transparent" default — no more solid teal slab), MuiOutlinedInput (house radius + calmer resting border + primary hover), MuiChip (soft --bal-primary-soft fill for default-color filled chips only — ownerState-scoped so color="success"/"error" chips are untouched), MuiToggleButton/MuiListItemButton (.Mui-selected → primary-soft fill + primary text), MuiDialog (--bal-radius-lg, tighter mobile margins), MuiTabs/MuiTab (3px indicator, 48px min-height), MuiAlert (house radius — severities now come from the palette, see below), MuiStepIcon (brand active/completed), MuiSkeleton (warm primary-soft tint), MuiTooltip (ink/cream inversion). Every value is var(--bal-*) or a logical CSS property — zero raw hex, zero physical direction props.

A theme.shadows array (TEAL_SHADOWS, 25 entries tiered onto --bal-shadow-1/2/3) replaces MUI's default grey stack globally — every component that reads theme.shadows[n] (Dialog, Menu, Popover, AppBar elevation, Autocomplete…) gets teal-tinted shadows for free, not just the ones this file overrides directly. Both themes are wrapped in responsiveFontSizes() for per-breakpoint heading scaling.

Semantic palette

LIGHT_PALETTE/DARK_PALETTE (colors.ts) now define success/error/warning/info (main + contrastText), sourced from the same values as the --bal-* feedback tokens — an inline <Alert severity="success"> and a success toast are now the same color family in both schemes. AppAlert's defaults flipped from the footgun (severity="error" variant="filled") to a calm baseline (severity="info" variant="standard") — every existing call-site already passed an explicit severity+variant, so this was a safe default change with zero call-site migration needed (verified by grep before changing).

Persian type scale

typography.ts rewritten: letterSpacing: 0 on every TYPOGRAPHY_RTL variant, a shared size/line-height scale (SIZE_SCALE — body line-height 1.7, headings 1.4–1.5, no more 6rem default h1), and the weight decision: 700 for headings/buttons, 500 for in-text emphasis, 400 body — never 600 (neither Mikhak nor Space Grotesk loads a 600 face; a requested 600 silently rendered full Bold). Swept 64 fontWeight: 600 sx call-sites across 42 files to 500/700 by this rule (9→700, 55→500; judgment calls documented in the commit — e.g. selection-card titles → 700, chip/row labels → 500). LTR keeps its original split (Space Grotesk headings, system-font body); RTL keeps Mikhak everywhere (full glyph coverage). Space Grotesk is now genuinely wired via next/font/google in app/[locale]/layout.tsx (self-hosted at build time, preload: false, attached only on en — mirrors the Mikhak/fa discipline exactly); the dead "not currently wired" comment is gone.

Token extension (tokens.css + colors.ts mirror where palette-level)

Added, both scheme blocks: --bal-radius-sm/md/lg (4/10/16 — controls/cards/dialogs), --bal-motion-fast/base/slow + --bal-easing-standard (for phase 12), --bal-shadow-1/2/3 (teal-tinted light, black-teal dark), --bal-focus-ring, --bal-rating/--bal-rating-empty (retiring the muddy --bal-warning star fill — phase 1 wires this into RatingInput), --bal-trust/--bal-trust-soft (a distinct blue identity for verified marks, separate from primary/success — phases 1/4/8 consume this), --bal-money-emphasis (AA-contrast-safe; --bal-secondary fails AA at small sizes on white, ~2:1). tokens.css's header now points at the frontend-designer skill instead of the deleted product/balinyaar.html.

Brand mark — the pencil is gone

Two new SVGs under AppIcon/icons/: LogoMark.tsx (monochrome currentColor "b" glyph — stem + a true evenodd-ring bowl, no background square — registered as ICONS.logo, used anywhere via <AppIcon icon="logo">, recolors for free in dark mode) and LogoLockup.tsx (the full-color mark: deep-teal rounded-square ground, cream glyph, terracotta dot, all var(--bal-*)-driven) used directly by BrandMark.tsx next to the (still translated, never-baked-into-SVG) wordmark. PencilIcon.tsx (the Twemoji starter pencil, the app's last hard-coded-hex SVG) is deleted. Favicon + webmanifest regenerated from the same construction via a one-off sharp script (fixed brand hex — the one place a literal hex is correct, since it's a static binary asset, not app code): src/app/favicon.ico (real multi-size PNG-in-ICO, 16/32/48) and public/img/favicon/{16,32,48,180,192,512}.png all now render the actual mark; site.webmanifest's theme_color/background_color are the real brand teal/cream (were starter #000000/#ffffff), and every referenced icon file now genuinely exists.

Icon system

• Size bug fixed: AppIcon.tsx drives size via style.fontSize (which MUI SvgIcon's 1em-based CSS actually respects) instead of width/height attributes (which that same CSS silently beat) — all ~40 existing size={14..56} call-sites now render at the requested size. The invalid size DOM attribute is no longer spread onto the SVG; the unknown-icon console.warn is dev-only.
• One visual family: the ~90-entry registry (AppIcon/config.ts) is now 100% MUI *Rounded — every filled/outlined starter icon was swapped. The 8 dead starter entries (daynight/night/day/visibilityon/visibilityoff/signup/login/settings) are deleted (re-verified zero usages before deleting).
• New vocabulary: back/chevron_start, share, copy, phone, navigate, sort, attachment, star_half.
• Directional mirroring: back/chevron_start are registered in a new DIRECTIONAL_ICONS set; AppIcon stamps data-icon-directional on those, and one CSS rule (app/globals.css) does the flip ([dir='rtl'] [data-icon-directional] { transform: scaleX(-1) }) — adding a future directional icon is a one-line registry addition, never a per-component flip.

AppButton de-startering

Removed DEFAULT_SX_VALUES = { margin: 1 } and the dead underline/label/text prop cruft (text/label duplicate props stay — 238 call-sites use them — only the invalid underline spread onto non-link buttons and the false "Box around to specify margins" JSDoc were removed). Swept the now-redundant sx={{ m: 0 }} neutralization at 192 call sites across ~68 files (6 parallel batches, verified against the original 213-occurrence/82-file audit count — the ~21 difference is re-count timing, not missed sites); 3 genuine non-AppButton m: 0 uses (on FormControlLabel, an unrelated real layout decision) were correctly left alone. Outer spacing is now the parent's job (Stack/Box gaps), as intended.

Starter residue purge

Deleted theme/light.ts + theme/dark.ts (+ their theme/index.ts exports: APP_THEME/LIGHT_THEME/DARK_THEME/LIGHT_THEME as default — nothing imported them) and the deprecated TYPOGRAPHY alias. Deleted the unused AppImage component + its test + barrel exports (zero product usages, verified). Rewrote globals.css as an intentional minimal base: kept the box-sizing reset, dropped max-height: 100vh and the max-width: 100vw; overflow-x: hidden mask, added ::selection in brand colors + the directional-icon CSS rule, and a commented decision on the a { color: inherit } reset. Fixed the false CONTENT_MIN_WIDTH comment and the starter commented-alternatives style in components/config.ts.

No-flash color-scheme boot — CSS only, no boot script

The original phase spec called for an inline pre-paint <script> (a ColorSchemeScript, matching what client/CLAUDE.md's Theme System section had — inaccurately — already documented). Built, then deliberately reverted per explicit user direction mid-session: a hand-rolled script (cookie parsing + Storage.prototype patching) didn't fit a codebase where every other theme decision is CSS-variable-driven. The shipped mechanism is pure CSS:

• Returning visitor (cookie present): unchanged — server stamps data-mui-color-scheme, the explicit tokens.css blocks match immediately.
• First-ever visitor (no cookie): getThemeMode() now returns colorScheme: undefined, so the server renders <html> without the attribute at all. tokens.css gained a @media (prefers-color-scheme: dark) block scoped to :root:not([data-mui-color-scheme]) that paints the OS-preferred scheme immediately, zero JS. Once React hydrates, defaultMode="system" resolves the same media query and MUI stamps the attribute itself — the CSS values already match, so nothing visibly flips.
• Known trade-off (documented in client/CLAUDE.md): this covers every --bal-* token (the dominant visual surface — page/paper background, text, dividers, all brand colors). MUI's own --mui-palette-* variables don't get the same free fallback (MUI's colorSchemeSelector supports attribute-based or 'media'-based generation, not both), so a bare color="primary" fill (e.g. a contained Button) can very briefly show the light value on a cookie-less dark-OS first visit before hydration — self-corrects same frame, never animates (disableTransitionOnChange). Acceptable trade-off given the alternative was a hand-rolled script the codebase's own conventions argue against.

viewport.themeColor is now the media-query array form (light → BRAND.teal, dark → BRAND.tealDeep) so browser chrome matches the page in both schemes.

What is now testable (and exactly how)

1. npm run dev, open /fa/login in a private window with OS dark on and no cookies: dark paint from first frame (no light flash on the --bal-* surface), the new Balinyaar mark (not a pencil) on the auth splash, recoloring correctly if you toggle dark/light.
2. /fa customer home: flat buttons with comfortable padding, hairline-bordered cards with soft teal shadows (not grey), soft-tinted chips. Tab through the page — every focusable element shows the same 2px brand focus ring.
3. /fa/nurse and /fa/admin (seeded accounts): top bar is a cream/paper surface with a hairline divider, not a solid teal slab; sidebar icons are one Rounded family; selected nav item uses the soft-primary fill.
4. Trigger an inline form-error AppAlert and a toast on the same screen — same brand-harmonized color family, both schemes.
5. /fa Persian text: no letter-spacing gaps inside joined words, headings don't clip; compare /en — Space Grotesk headings render (network tab shows the self-hosted font file only on /en, never on /fa).
6. Browser tab: favicon is the new mark; toggling OS dark mode flips theme-color (deep-teal) in supporting browsers.
7. npm run check (type + lint) and npm run test:ci — both green (see Gate below).

What is mocked / waiting on a real service

None — this phase is pure client theming, no service seams, no mock flags (per the phase's own §4).

Docs updated

• .claude/skills/frontend-designer/SKILL.md — brand-mark construction (now the source of truth, product/balinyaar.html is gone), the new token categories + when to use each, the weight-500/700 decision (the old "buttons weight 600" line was wrong the moment this phase landed), the Rounded icon family + directional-mirroring rule + the size-bug fix, dropped the stale ~19-icon "currently registered" list (pointed at AppIcon/config.ts directly instead — it drifts too fast for a skill doc to enumerate reliably).
• client/CLAUDE.md — Theme System section rewritten for the CSS-only no-flash mechanism (replacing the doc-drift ColorSchemeScript description that never matched reality), the Fonts table (Space Grotesk now wired), the theme/ entries in Project Structure (light.ts/dark.ts removed).

Follow-ups for later phases

• Phase 1: wire --bal-rating/--bal-rating-empty into RatingInput (currently still uses --bal-warning), build EmptyState/ErrorState/PageHeader/<Money>/Jalali picker/skeleton twins/route-level loading.tsx/error.tsx/404 — all deferred here per the phase's own scope boundary.
• Phase 2: TopBar/SideBar chrome, UserInfo, nav grouping, SSR mobile-first flash — the physical paddingLeft/paddingRight in TopBarAndSideBarLayout.tsx and the hard-coded English "Open Sidebar" tooltip are pre-existing shell issues, deliberately untouched here (no page/shell redesigns in phase 0).
• Phase 4/8: --bal-trust/--bal-trust-soft are defined but not yet consumed by TrustBadge/verification UI — that's a content decision for those phases, not a token gap.
• Phase 12: the app-wide motion pass consumes --bal-motion-*/--bal-easing-standard, defined but unused here (define-only per this phase's scope).
• No REQs filed — this phase never touches server/ or any contract.

Gate

• npm run check (type + lint): green, zero errors/warnings.
• npm run test:ci: 329/329 tests, 79/79 suites green. Three pre-existing shared-component tests (AppIcon.test.tsx, AppIconButton.test.tsx, AppButton.test.tsx) asserted the exact bugs this phase fixes (an invalid size DOM attribute; the pre-Rounded-swap MoreHorizIcon testid) — updated in the same change to assert the corrected behavior (style.fontSize, MoreHorizRoundedIcon) rather than the old bug.
• en.json/fa.json: untouched — this phase added no new user-facing strings (the brand mark's alt text reuses the existing common.brand key via BrandMark's adjacent <Typography>; the SVG itself is aria-hidden).