# Design-language conformance & theming audit (P16.9) — 2026-07-19

## What was audited

Every page and component built by the ideation initiative (P2–P16), plus the
pre-existing workbench pages they sit beside — the sweep covered all 57 `.tsx`
sources under `src/`, because a theme that stops at "new pages" leaves the app
half-dark and wholly broken.

## Conformance against the oshun web design language

The reference is `apps/oshun/web/src/design-system/tokens.ts`
(`@oshun/design-tokens`). Findings:

- **Accent scale — conformant by structure.** The workbench's `hathor` scale
  (50–900, warm umber) plays the same role as the web app's domain accent scales
  (`oshunDomainAccents`): one branded accent over a neutral base, accent-600/700
  for primary actions, accent-100/800 for chips. No off-scale accent hexes were
  found in pages or panels.
- **Neutrals — conformant with a naming deviation, recorded.** New panels use
  Tailwind `slate`, older pages `gray`. Both map onto the web foundation's
  neutral ramp; the dark mapping below normalises both to one dark neutral
  family (`slate`) so the deviation cannot produce two different darks. Full
  renaming of light-mode `gray` → `slate` was deliberately NOT done: it would
  churn ~40 files for identical pixels.
- **Status tones — conformant.** red=blocking, amber=advisory/draft, green=pass,
  blue=info matches the web app's trust-signal behavior
  (`oshunTrustSignalUiBehavior`) tone assignments.
- **Raw hexes** exist only where they are data, not style: plotline color
  hashing (Corkboard), presence cursor palette (IdeaBoard), node kind colors
  (CoreLoop/GraphCanvas), palette swatches (style-consistency). These are domain
  colors; tokenising them would couple canon visuals to UI theming.

## Dark/light parity

Implemented, not merely audited:

- `dark:` variants added across all 57 sources (1,347 utilities) via a reviewed
  mapping (light surfaces → `slate-900/800/700`, tonal 50/100 backgrounds →
  950/900 of the same hue, text ramps inverted, borders `slate-700/600`), plus a
  page-level base in `index.css`.
- The `dark:` variant keys off `html[data-theme='dark']` — the same
  data-attribute theming the web app uses (`[data-lilith-theme]`) — stamped by
  `src/lib/theme.ts`: system-following by default (`prefers-color-scheme`,
  live-synced), manual override via the header `ThemeToggle`, persisted;
  toggling flips from the RESOLVED theme. Spec'd in `theme.spec.ts`.
- **Deliberate exceptions (paper surfaces):** the GraphCanvas SVG stays light in
  both schemes — node/edge labels are fixed dark ink and the four graph editors
  (quests, dialogues, story graphs, relationship web) read it as a document, not
  chrome. The idea-board canvas keeps its amber-tinted surface via a 950-tinted
  dark variant instead.
- Chrome-verified live in BOTH schemes on the ideation hub (board,
  notifications, generator console, interop) and the develop ladder (rungs, core
  loop, comps, blockout brief, kit sheets incl. lint colors and the
  disabled-input surface, which needed a `dark:disabled:` variant the sweep's
  modifier-skipping missed).

## Axe pass (11.4) re-run

`src/pages/accessibility.spec.tsx` — 9/9 green after theming. The gate runs on
rendered DOM with the severity-mapped adapter (the one whose "teeth" are proven
by a deliberate known-bad input), and it caught two real violations during this
phase's work (unlabeled interop textareas) before they shipped — evidence it
audits the pages as built, not a checkbox.

## How to keep it

- New surfaces: use `slate` neutrals with the `dark:` pairs from the mapping
  above; anything tonal gets its 950/900 dark sibling; never introduce a
  light-only surface outside the declared paper exceptions.
- `html[data-theme]` has exactly one writer (`lib/theme.ts`). Do not stamp it
  elsewhere.
