baya-monorepo/archive/post-phase/ui/ui-phase-0-design-language.md

# UI Phase 0 — Design language & theme foundation

> **Mission:** kill the default-MUI/starter look at the token + theme layer in one pass and establish the
> brand's visual system — a `theme.components` pass, a semantic palette, a real Persian type scale, one icon
> family, a designed Balinyaar logomark, extended tokens (elevation/motion/focus/rating/trust/money), and a
> purge of starter residue — so every later phase composes on a system that already looks designed. **No page
> redesigns here**: this phase changes what every screen inherits, not any screen's layout.
>
> **Track:** frontend · **Depends on:** — (first phase of the [UI chain](README.md)) · **Unlocks:**
> [Phase 1](ui-phase-1-primitives-and-states.md), [Phase 2](ui-phase-2-shells-and-navigation.md), and every
> later phase — they all inherit the de-startered look built here.
> **Before you start, read [../../phases/_shared/agent-operating-rules.md](../../phases/_shared/agent-operating-rules.md)
> and invoke the frontend-designer skill — both are mandatory.**

## 1. Context — where this sits

Balinyaar's feature layer is unusually disciplined — 331 `var(--bal-*)` usages across 103 files, effectively
zero hard-coded hexes, correct RTL/Shamsi/BigInt-money plumbing — but the *visual system underneath it is
still the karpolan react-mui starter*. Diagnosed root causes (all verified in code):

1. **`createTheme` has zero `components` overrides** — `client/src/theme/theme.ts:19-36` passes only
   `cssVariables`/`colorSchemes`/`typography`/`shape`/`direction`; every Button/Card/TextField/AppBar/Chip/
   Dialog/Alert renders stock Material with recolored primaries. The single biggest cause of the starter feel.
2. **No semantic palette** — `theme/colors.ts` defines only primary/secondary/background/text/divider, so
   inline `<Alert severity>` surfaces render stock MUI green/red while toasts (`lib/toast/NotistackProvider.tsx`)
   use the brand `--bal-*` feedback tokens — two feedback systems for one semantic state. Worse, a bare
   `<AppAlert>` defaults to a **filled stock-red error** (`components/config.ts:10-11`).
3. **Persian typography is Roboto metrics** — `TYPOGRAPHY_RTL` (`theme/typography.ts:43-52`) sets only
   `fontFamily` + weights: non-zero letter-spacing on a joined script, tight heading leading, and a requested
   weight **600** (h6, button) that the Mikhak loader (`app/[locale]/layout.tsx:39-48`, weights 400/500/700)
   renders as full Bold — repeated in 68 `fontWeight: 600` sx usages across 42 files (verified). Space
   Grotesk (`--font-space-grotesk`) is declared for EN but never loaded.
4. **The brand mark is the starter's Twemoji cartoon pencil** — `AppIcon/config.ts:115` registers
   `logo: PencilIcon`; `components/auth/BrandMark.tsx:21` renders it at 56px on every auth screen and passes
   `color="var(--bal-primary)"`, which the hard-coded fills (`#EA596E`, `#FFCC4D`, …) silently ignore.
5. **The icon system is broken and incoherent** — `AppIcon.tsx:38-46` passes `size` as SVG `width`/`height`
   *attributes*, which MUI `SvgIcon`'s `1em` class CSS overrides, so every `size={14..56}` call-site renders
   24px. The ~87-entry registry mixes filled starter icons against `*Outlined` feature icons, carries eight
   dead entries (zero usages, verified), and has **no back/chevron icon at all** (only `expand`).
6. **Starter residue everywhere else:** `AppButton`'s `DEFAULT_SX_VALUES = { margin: 1 }` neutralized by
   **213 `m: 0` occurrences across 82 files**; dead `theme/light.ts`/`dark.ts` exported from `theme/index.ts`
   incl. `LIGHT_THEME as default` (nothing else imports them); the 17-line starter `globals.css`; the wrong
   `CONTENT_MIN_WIDTH` comment (`components/config.ts:5`); unused `AppImage` (all verified); a cookie-less
   OS-dark first visit paints light first (`lib/cookies/server.ts:46` returns `'light'`, no pre-paint script
   exists — acknowledged doc drift in `client/CLAUDE.md`); `viewport.themeColor` hard-coded to light teal
   (`layout.tsx:50-52`); `public/site.webmanifest` still ships starter `#000000`/`#ffffff` and references
   `img/favicon/*.png` files that don't exist.

**What already exists (do not rebuild):**

- The **two-layer token system** — `theme/tokens.css` (`--bal-*`, scheme-keyed on `data-mui-color-scheme`)
  mirrored by `theme/colors.ts`, sync rule in both headers. Extend it; never bypass it.
- The **MUI v9 RTL dual-theme setup** (`APP_THEME_LTR`/`APP_THEME_RTL` built once at module load,
  `stylis-plugin-rtl` Emotion cache in `ThemeProvider.tsx`) and the **cookie-SSR color-scheme sync**
  (`getThemeMode()` → `data-mui-color-scheme` stamped server-side; explicit `colorSchemeSelector`).
- **Per-locale font loading** (Mikhak via `next/font/local`, `preload: false`, attached only on `fa`),
  the **AppIcon string registry** with its snake_case domain names (the exact indirection that makes this
  phase's icon swap a config-level change), **brand-styled notistack toasts**, and the correct global
  decisions already made: `shape.borderRadius: 10`, `textTransform: 'none'`, the lifted dark-teal palette.

## 2. Required reading (do this first)

- The audits: [audit/theme-and-brand.md](audit/theme-and-brand.md),
  [audit/component-primitives.md](audit/component-primitives.md),
  [audit/cross-cutting-ux.md](audit/cross-cutting-ux.md) — the full file/line evidence and the
  **Keep (do not regress)** lists this phase must honor.
- [../../../.claude/skills/frontend-designer/SKILL.md](../../../.claude/skills/frontend-designer/SKILL.md) —
  the design contract you are extending (invoke the skill; this phase also *updates* it — see 3.10).
- `client/CLAUDE.md` — "Golden rules", "Theme System" (the cookie/no-flash machinery and the MUI v9 traps:
  explicit `colorSchemeSelector`, never `InitColorSchemeScript`, never `storageWindow`), and "Fonts".
- Code, in this order: all of `client/src/theme/`, `components/config.ts`, `components/common/AppIcon/`
  (+ `icons/PencilIcon.tsx`), `components/common/AppButton/AppButton.tsx`, `components/auth/BrandMark.tsx`,
  `lib/toast/NotistackProvider.tsx`, `app/[locale]/layout.tsx`, `app/globals.css`, `lib/cookies/server.ts`
  (`getThemeMode`), `public/site.webmanifest`.
- `product/overview/platform-summary.md` — the tone (trust-first, calm, clinical-but-human) every visual
  decision here must serve.

## 3. Scope — build this

### 3.1 The `theme.components` pass (the highest-leverage change in the app)

Add a `components` block inside `createAppTheme` (`theme/theme.ts`) that encodes the brand once. Reference
colors as `var(--bal-*)` tokens (or `theme.vars.palette.*`) so every override is scheme-correct — never a
hex. Overrides must be direction-safe (logical properties only — both theme directions share them). Cover at
least: **MuiButton** (`disableElevation`, comfortable `paddingInline`, weight per the 3.3 decision, keep
`textTransform: 'none'`); **MuiPaper/MuiCard** (hairline `1px solid var(--bal-divider)` border + soft
**teal-tinted** shadows from the 3.4 elevation tokens instead of MUI's grey stack on warm cream);
**MuiAppBar** (paper/cream surface + hairline bottom divider, **not** solid primary — shells are rebuilt in
phase 2, this stops the default bar screaming "starter" now); **MuiOutlinedInput/MuiTextField** (house
radius, calmer resting border, brand focus ring); **MuiChip / MuiToggleButton(Group) / MuiListItemButton**
(soft `--bal-primary-soft`/`--bal-secondary-soft` tonal fills; `selected` = primary-soft + primary text —
tokens already exist in both schemes); **MuiDialog** (radius 16, sane mobile margins); **MuiTabs** (thicker
indicator, comfortable min-height); **MuiAlert** (severities from the 3.2 semantic palette so inline alerts
match toasts); **MuiStepper/MuiStepIcon** (brand-colored active/completed steps — the trust flows live on
these); **MuiSkeleton** (warm tint per scheme); **MuiTooltip** (ink/cream inversion, house radius); and
**MuiCssBaseline** carrying a global `:focus-visible` treatment off `--bal-focus-ring` (2px ring + offset —
today exactly **one** `:focus-visible` style exists in the app, in `NurseResultCard.tsx`; after this,
keyboard focus is uniform everywhere).

### 3.2 Semantic palette — one feedback language

- Add `success`/`error`/`warning`/`info` (main + contrastText, light **and** dark) to
  `LIGHT_PALETTE`/`DARK_PALETTE` in `colors.ts`, sourced from the existing `--bal-*` feedback values in
  `tokens.css` (light: `#1f6b50`/`#a8392a`/`#8a6418`/`#1d4a40`; dark: the lifted set). Keep the two files
  mirror-synced. Alert, `Chip color="success"`, Badge, LinearProgress become brand-harmonized automatically.
- Fix the `AppAlert` footgun in `components/config.ts`: first make severity explicit at any call-site that
  genuinely means error, then change the defaults to a calm baseline (`severity="info"`,
  `variant="standard"` on the new tinted severities — decide and document in the config file).

### 3.3 A real Persian type scale

In `theme/typography.ts` `TYPOGRAPHY_RTL`:

- **`letterSpacing: 0` on every variant** — Persian is a joined script; tracking breaks Mikhak's glyph
  connections (MUI's Latin defaults set non-zero spacing on body1/body2/button/caption/overline).
- **Body line-height ≥ 1.7; headings ~1.4–1.5** (room for Persian ascenders/descenders) plus **responsive
  heading sizes** (MUI's default 6rem h1 is unusable; grep confirms zero h1/h2 usages today).
- **Resolve the weight-600 problem.** Mikhak loads 400/500/700 only, so every requested 600 silently renders
  700. Decide: (a) adopt **500/700 semantics** — map the theme's h6/button and the 68 `fontWeight: 600` sx
  usages across 42 files to loaded weights (recommended: 700 headings/buttons, 500 in-text emphasis; the
  sweep is mechanical) — or (b) add a genuine Mikhak DemiBold face to `src/app/fonts/` + the loader. Pick
  one, do it fully, **document the decision in `typography.ts` and the skill (3.10)**.
- **Settle the EN display font**: wire Space Grotesk via `next/font` in `app/[locale]/layout.tsx` (attached
  only on `en`, mirroring the Mikhak pattern, `preload: false`) **or** delete the dead
  `BRAND_FONT_VARIABLE_EN` variable and its fallback stack. Decide and do it — no vaporware comment left.

### 3.4 Token extension — beyond color

Extend `theme/tokens.css` (**both scheme blocks — always**), mirroring palette-level values in `colors.ts`:

- **Elevation/shadow tokens** — 2–3 steps of teal-tinted shadows (light: `rgba(29,74,64,α)` stacks; dark:
  black-teal), consumed by 3.1's Paper/Card/Dialog overrides.
- **Radius scale** — document the house scale (e.g. 4 / 10 / 16: controls / cards / dialogs) as tokens or
  constants next to `shape.borderRadius`; stop inventing radii per component.
- **Motion tokens** — durations (e.g. 120/200/300ms) + easings; defined once here, consumed by phase 12 —
  and **`--bal-focus-ring`**, the global focus ring used by 3.1's `:focus-visible` treatment.
- **`--bal-rating` + `--bal-rating-empty`** — proper star gold + empty color per scheme (`RatingInput`'s
  muddy `--bal-warning` stars are fixed in **phase 1** using these); **`--bal-money-emphasis`** — a
  contrast-safe money-text emphasis per scheme, retiring terracotta as a small-text money color (`#d98c6a`
  on white fails AA contrast); **`--bal-trust` + `--bal-trust-soft`** — a distinct trust identity for
  verified marks (not generic primary/success), consumed by phases 1/4/8. All define-only here.
- Update the stale `tokens.css` header (it cites `product/balinyaar.html`, which no longer exists in the
  repo) to point at the frontend-designer skill as the brand source of truth (3.10).

### 3.5 A real brand mark — kill the pencil

- Design the Balinyaar logomark per the identity the skill records (the `product/balinyaar.html` seed deck
  is **gone from the repo** — recreate from the tokens + the skill's description): deep-teal ground, cream
  lowercase glyph, a single terracotta dot. Build two SVGs under `AppIcon/icons/`: a **monochrome
  `currentColor` logomark** (so `color="var(--bal-primary)"` finally works and it recolors in dark mode for
  free) and a **full lockup** (mark + wordmark) for `BrandMark`/auth.
- Register the mark as `ICONS.logo` (replacing `PencilIcon`), update `components/auth/BrandMark.tsx` to the
  new lockup, **delete `icons/PencilIcon.tsx`** (the last hard-coded-hex SVG in the app), regenerate
  `src/app/favicon.ico` from the mark, and fix `public/site.webmanifest` — brand
  `theme_color`/`background_color` (currently starter `#000000`/`#ffffff`) and icon entries that actually
  exist (generate the referenced PNG sizes from the mark, or trim the manifest — today it points at missing
  `img/favicon/*.png`).

### 3.6 Icon system — one family, working sizes, full vocabulary

- **Fix the size bug** in `AppIcon.tsx`: drive `fontSize` via `style`/`sx` instead of `width`/`height`
  attributes (which MUI `SvgIcon`'s `1em` class CSS beats) — all ~40 existing `size={14..56}` call-sites
  start working simultaneously. Stop spreading the invalid `size` attribute onto the DOM `<svg>`; make the
  unknown-name `console.warn` **dev-only**; keep the custom-SVG path (the new logomark) scaling correctly.
- **Normalize the ~87-entry registry to ONE visual family** — recommend the **Rounded** variants of
  `@mui/icons-material` (zero new deps, warmer than the current filled/outlined mix, fits
  clinical-but-human). A `config.ts`-only sweep thanks to the registry indirection. Delete the eight dead
  starter entries (`daynight`/`night`/`day`/`visibilityon`/`visibilityoff`/`signup`/`login`/`settings` —
  re-verify zero usages before each delete).
- **Add the missing vocabulary**: `back`/`chevron_start` (no directional nav glyph exists today except
  `expand`), `share`, `copy`, `phone` (non-emergency call), `navigate` (directions), `sort`, `attachment`,
  `star_half`. Note `camera`, `calendar`, `wallet`, and `tune` (filter) are **already registered** — they
  only need family normalization. **Directional icons auto-mirror**: register `back`/`chevron_start` as the
  LTR glyph, mirrored via a `[dir="rtl"]` `scaleX(-1)` rule applied by `AppIcon` for a declared
  `DIRECTIONAL_ICONS` set in `config.ts`; write the rule into the registry comment and the skill — later
  phases must not hand-roll flips.

### 3.7 AppButton de-startering

- Remove `DEFAULT_SX_VALUES` (`margin: 1`), then sweep the now-no-op **213 `sx={{ m: 0 }}` neutralizations
  across 82 files** (mechanical: remove the key; drop `sx` when it becomes empty). Outer spacing becomes the
  parent's job (Stack/Box gaps). Clean the starter prop cruft: duplicate `label`/`text` props (pick one,
  migrate the loser's call-sites), the false "Box around to specify margins" JSDoc, the `// Missing props`
  comment, and the `underline` spread onto non-link buttons (`AppButton.tsx:85`).
- **Do not break the public API**: `to`/`href` auto-link composition, icon-name `startIcon`/`endIcon`, and
  non-MUI-color-becomes-text-color all stay (238 call-sites). Leave the `color='inherit'` default as-is —
  changing every unspecified button's color is a per-screen decision for later phases. Update
  `AppButton.test.tsx` (and every other touched shared component's test) in the same change.

### 3.8 Starter residue purge

- Delete `theme/light.ts` + `theme/dark.ts` and their exports from `theme/index.ts` (verified: nothing else
  imports them; drop `LIGHT_THEME`/`DARK_THEME`/`APP_THEME`/`LIGHT_THEME as default` — keep `ThemeProvider`,
  `getDirection`, `APP_THEME_LTR/RTL`). Delete the deprecated `TYPOGRAPHY` alias in `typography.ts` once
  nothing imports it.
- Rewrite `app/globals.css` as an intentional minimal base: keep the `box-sizing` reset, **drop
  `max-height: 100vh`** and the `max-width: 100vw; overflow-x: hidden` mask, add `::selection` in brand
  colors, and a commented decision on the `a { color: inherit }` reset (AppLink owns link affordance).
- Fix the wrong `CONTENT_MIN_WIDTH` comment (`components/config.ts:5`), prune the starter
  commented-out-alternatives style there into owned decisions, and delete the unused `AppImage` + its test +
  barrel export (verified: zero product usages).

### 3.9 No-flash color-scheme boot

- A cookie-less OS-dark first visit paints light, then flips. Implement the **`ColorSchemeScript`** that
  `client/CLAUDE.md`'s Theme System section already documents (acknowledged doc drift): an inline `<head>`
  script in `app/[locale]/layout.tsx` that reads the `color-scheme` cookie, falls back to
  `matchMedia('(prefers-color-scheme: dark)')` when absent, and sets `data-mui-color-scheme` before first
  paint — plus the documented `Storage.prototype` patch. **Never** MUI's `InitColorSchemeScript` (banned in
  `client/CLAUDE.md` — it reads localStorage, which diverges from the cookie). The script must agree with
  `getThemeMode()` on every path. Switch `viewport.themeColor` (`layout.tsx:50-52`) to the media-query array
  form: light → `BRAND.teal`, `(prefers-color-scheme: dark)` → `BRAND.tealDeep`, so browser chrome matches
  the page in both schemes.

### 3.10 Keep the design contract honest

Update `.claude/skills/frontend-designer/SKILL.md` **in the same change**: the new tokens (elevation, radius,
motion, focus, rating, trust, money-emphasis) and when to use each; the type-scale + weight decision (its
"buttons weight 600" rule becomes wrong the moment 3.3 lands); the normalized icon family + directional-
mirroring rule + a corrected registered-icons note (it lists ~19 of ~87 icons and still names the dead
starter entries); and the brand-mark construction as the written source of truth now that
`product/balinyaar.html` is gone (fix its reference; `tokens.css`'s header points here too).

**(DEFERRED → phase 1):** all new shared primitives — EmptyState/ErrorState, PageHeader, `<Money>`, Jalali
picker, StatusChip v2, RatingInput's star fix, skeleton twins, route-level `loading.tsx`/`error.tsx`/404.
**(DEFERRED → phase 2):** the shells — TopBar/SideBar chrome, `UserInfo`, nav grouping, SSR mobile-first flash.
**(DEFERRED → phase 12):** the app-wide motion pass that consumes 3.4's motion tokens.

## 4. Mocks & seams in this phase

None. This phase is pure client theming — no service seams, no mock flags. The chain's REQ posture: if a
backend gap surfaces (none is expected here), append a REQ entry to
[../../shared-working-context/frontend/requests/for-backend.md](../../shared-working-context/frontend/requests/for-backend.md)
— REQ-001…038 are taken (verified: the tracker ends at REQ-038); number onward from **REQ-039**. UI stays
mock-tolerant behind the existing `services/{domain}` seams; never edit `server/`.

## 5. Critical rules you must not get wrong

- **The two-layer token sync is law** — every color added/changed lands in `tokens.css` (**both** scheme
  blocks) *and* `colors.ts` in the same commit — and **zero hex regressions**: feature code has effectively
  no hard-coded hexes; the theme pass must not reintroduce literals outside the theme layer (deleting
  `PencilIcon` removes the last offender).
- **Do not break the RTL dual-theme/Emotion setup** (`APP_THEME_LTR`/`APP_THEME_RTL` stay module-load-built;
  `createTheme()` never in a component; overrides use logical properties only) **or the cookie-SSR
  color-scheme sync** (`colorSchemeSelector` stays the explicit `'data-mui-color-scheme'`, never `'data'`;
  no `InitColorSchemeScript`; no `storageWindow`).
- **The AppIcon registry indirection stays** — keep the `<AppIcon icon="name">` API, the snake_case domain
  names, the lowercase keys. **AppButton's composition API stays** (`to`/`href` → AppLink, icon-name
  `startIcon`/`endIcon`) — 238 call-sites; the margin removal is a default change, not an API change.
- **Keep the keep-lists.** Notably: `textTransform: 'none'`, radius 10 as the house radius, the lifted
  dark-teal palette, per-locale font loading (Mikhak never ships to `/en`; mirror that discipline if you
  wire Space Grotesk), and `NotistackProvider` staying token-driven.
- **Design-contract non-negotiables:** any new user-facing string (e.g. the logo's aria/alt) goes in
  **both** `messages/en.json` and `messages/fa.json`; MUI v9 API only; co-located `*.test.tsx` updated for
  every touched shared component (`AppIcon`, `AppButton`, `BrandMark`, …); fetch/cookies rules untouched.
- **Update the skill and `client/CLAUDE.md` in the same change** (3.10 + §8) — stale design docs are how the
  next phase reintroduces the starter.

## 6. Definition of Done

On top of the shared [definition-of-done.md](../../phases/_shared/definition-of-done.md):

- [ ] `npm run check` green; `npm run test:ci` green incl. updated tests for every touched shared component;
      `en.json`/`fa.json` in sync.
- [ ] `theme.ts` has a `components` block covering at least the 3.1 list; no override uses a raw hex or a
      physical direction property.
- [ ] `LIGHT_PALETTE`/`DARK_PALETTE` define success/error/warning/info; an inline
      `<Alert severity="success">` and a success toast are visibly the same color family in both schemes.
- [ ] `TYPOGRAPHY_RTL` has `letterSpacing: 0` everywhere + the new line-heights and responsive heading
      sizes; no `fontWeight: 600` remains in `src` (or a real 600 face is loaded — per the documented
      decision); the Space Grotesk question is resolved (wired or deleted).
- [ ] `tokens.css` (both blocks) carries elevation, radius, motion, focus-ring, rating, money-emphasis, and
      trust tokens, mirrored in `colors.ts` where palette-level.
- [ ] `ICONS.logo` is the new Balinyaar mark; `PencilIcon.tsx`, `light.ts`, `dark.ts`, `AppImage`, and the
      eight dead icon entries are deleted; favicon + webmanifest rebuilt with brand colors and only real
      files referenced.
- [ ] `<AppIcon icon="verified" size={48} />` actually renders 48px; the registry is one visual family;
      `back`/`chevron_start` mirror correctly under `dir="rtl"`; `AppButton` has no default margin and
      **zero** `sx={{ m: 0 }}` neutralizations remain in `src`.
- [ ] First visit with OS dark preference and no cookie paints dark with no light flash; browser
      `theme-color` matches the scheme in both modes.
- [ ] Visual verification on the four axes — `/fa` + `/en` × light + dark — and mobile + desktop widths on
      the §7 walk, with screenshots in the report; skill + `client/CLAUDE.md` updated to match reality.

## 7. How to test (what a human can verify after this phase)

1. Open `/fa/login` (private window, OS set to dark, no cookies): the page paints **dark immediately** — no
   light flash — and shows the **new Balinyaar logomark** (not a pencil), recoloring correctly in dark mode.
2. On the customer home `/fa`: buttons are flat (no elevation) with comfortable padding; cards show hairline
   borders + soft teal-tinted shadows (not grey); chips are soft-tinted; nothing renders stock-MUI grey/blue.
   Tab through: every focusable element shows the same 2px brand focus ring.
3. Visit `/fa/nurse` and `/fa/admin` (seeded accounts): the top bar is a cream/paper surface with a hairline
   divider — **not** a solid teal slab; sidebar icons are one visual family (all Rounded); the selected nav
   item uses the soft-primary fill.
4. Trigger an inline alert (e.g. a form error state) and a toast on the same screen: both use the same
   brand-harmonized semantic colors, in light and dark.
5. On `/fa`, inspect Persian text: no letter-spacing gaps inside joined words, headings don't clip
   ascenders, bold shows a real weight hierarchy (not everything Bold). Compare `/en`: headings render per
   the 3.3 decision (Space Grotesk or the documented system stack).
6. Check the browser tab: the favicon is the new mark; toggling OS dark mode flips the browser chrome
   (`theme-color`) to the deep-teal value.

## 8. Hand off & document (close the phase)

- Update `client/CLAUDE.md`: the Theme System section (`ColorSchemeScript` now real — remove the doc-drift
  note; new tokens; the weight decision), the theme entries in "Project Structure" (`light.ts`/`dark.ts`
  removed, new icon assets), and the Fonts table if Space Grotesk was wired. Update
  `.claude/skills/frontend-designer/SKILL.md` per 3.10 (part of the phase, not optional).
- Write the frontend report at `dev/shared-working-context/reports/ui-phase-0-report.md`: what changed at the
  theme layer, the type-scale + weight + icon-family decisions, before/after screenshots on the four axes,
  what later phases must know (new token names, directional-icon rule), and any REQs filed (expected: none).
- Save a memory note per operating-rules §8: the theme/token/icon/brand decisions, the size-bug fix, the
  margin-default removal, and the no-flash boot mechanism — later UI phases build on all of them.