@micha.bigler/ui-core-micha 3.14.4 → 4.0.0

package/work-orders/THEME-2.md

@@ -1,339 +0,0 @@
-# THEME-2 — Two defects from the THEME-1/CHART-6 landings: `warning.main` contrast, and `grid` replacing instead of merging
-
-**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
-**Tier:** 2 (shared core — `ui-core-micha` is named in AGENTS.md's Tier-2 forcing list)
-**Review:** independent `reviewer` **and** `ui_reviewer` — spawned concurrently, both mandatory before commit
-**Version target:** `2.31.1` (patch — one palette value corrected, one merge bug fixed, one assertion rule added; no API change)
-**Decision record:** `webapp-management/DESIGN_SYSTEM_PROGRAM.md` → "Open follow-ups from the two landings"
-
-Short-form WO: both defects are fully diagnosed and measured. There is no design question in either.
-
----
-
-## A. Envelope
-
-### Goal
-
-Fix the two defects found after `THEME-1` (`96992cf`) and `CHART-6` (`6dedc62`) landed, and in each
-case close the **mechanism** rather than only the instance — both are the same failure class as
-something already fixed, which is why they recurred.
-
-### Defect 1 — `warning.main` fails AA as a foreground
-
-THEME-1's R1 fix gave every status channel an explicit `main`/`light`/`dark`/`contrastText` (correct
-— MUI was otherwise filling its stock hues for `color="success"` and friends). It put the **fill**
-tone in `main`. Measured against `#FFFFFF`:
-
-| Channel | `main` | as foreground | |
-|---|---|---|---|
-| success | `#1B8038` | 5.010 | passes |
-| error | `#BF3227` | 5.674 | passes |
-| **warning** | `#C08A2C` | **3.038** | **fails AA (4.5)** |
-
-`main`/`contrastText` pairs are all fine (warning 5.078 with dark ink). The failure is only when
-`main` is used as a **foreground on a light surface** — `<Typography color="warning.main">`,
-`color="warning"` on an icon, and an outlined warning chip, whose border and label both come from
-`main`.
-
-**Why warning specifically, and why this is not carelessness:** green and red can serve both roles
-with one value. Amber cannot. A legible amber **fill** needs dark text on it and must therefore stay
-light; a legible amber **text** must be dark. The two requirements pull in opposite directions.
-Warning is the one channel where "one hex for both roles" is impossible in principle — so the
-pattern that works for success and error had to break here.
-
-**Fix:** `warning.main` = `#976100` (the text tone already in the same token block, 5.216 on white),
-`contrastText` = `#FFFFFF`. The light amber stays available as `warning.fill` for deliberate fill
-use, unchanged.
-
-**Accepted visual consequence, stated so nobody treats it as a regression:** a filled
-`color="warning"` Button/Chip becomes a darker brown with white text instead of a lighter amber with
-dark text. That is the price of one token serving MUI's `main` contract, and it is the operator's
-call already recorded in the programme doc.
-
-**Close the mechanism, not just the value:** add an assertion rule that checks **every** status
-channel's `main` against `#FFFFFF` and `background.default` at 4.5:1. Without it the next channel
-added repeats this exactly — the existing contrast checks were designed before R1 introduced `main`,
-which is why they did not catch it.
-
-### Defect 2 — `grid` is replaced, not merged
-
-`LineChart` and `BarChart` declare `grid = { horizontal: true }` as a plain default parameter and
-pass it straight through. A caller writing `grid={{ vertical: true }}` — intending to *add* vertical
-lines — silently loses the horizontal ones.
-
-This is the same class as the `scaleType` bug the rendered gate caught during CHART-6: **a partial
-caller object erases a default.** `xAxis`, `yAxis`, `margin` and `slotProps` all go through merge
-helpers; `grid` alone does not.
-
-**Fix:** merge `grid` with the default the way the sibling props already do, so a caller adds to it
-rather than replacing it.
-
-**Close the mechanism:** audit the remaining object-valued props the wrappers default or forward
-(`slots`, `tickLabelStyle` and anything CHART-6 introduced) for the same replace-instead-of-merge
-shape, and state the result — either "all others already merge" or a named list. **Audit and report;
-do not refactor beyond `grid`** unless the audit finds another live instance, in which case fix that
-too and say so.
-
-### Non-goals / do not touch
-
-- The other status channels' `main` values — success and error measure fine and stay.
-- `warning.fill` / `warning.text` / `warning.bg` — unchanged.
-- The reference sheet's committed HTML artifact. It is the frozen spec of the accepted baseline;
-  `warning.main` is a channel the sheet never depicted (see Verification).
-- Anything in `CHART-6`'s scope beyond the `grid` merge and the audit.
-- No behaviour, permission or data-contract change.
-
-### Risks
-
-- **A palette value change is visible.** Any app already using `color="warning"` sees a darker
-  filled control. No app has an adoption WO yet, so the blast radius today is ucm's own harness — but
-  say it in the release note rather than let someone find it.
-- **Adding an assertion rule can turn a green suite red.** Safe today by the ratchet: the
-  completeness check is a hard failure only for an app whose adoption WO has landed, and none has.
-  It must stay that way — the new rule must not become hard for non-adopters.
-- **No staging net.** A push to `main` touching `src/**` publishes to npm at once; the independent
-  review is the only gate and is not back-fillable.
-- **The `grid` merge changes behaviour for any caller who passes a partial `grid` today.** That is
-  the point, but it means the rendered check should look at a chart that passes `grid` explicitly if
-  one exists.
-
-### Required tests to WRITE
-
-Narrow. Extend the existing files rather than adding new ones.
-
-**`tests/themeCompleteness.test.js`**
-
-1. Every status channel's `main` clears 4.5:1 against `#FFFFFF` **and** against
-   `background.default`. **Prove non-vacuity** by restoring `warning.main` to `#C08A2C` and
-   confirming this test fails — that is the whole point of the rule.
-2. The new rule reports, and does not hard-fail, for a theme belonging to an app without a landed
-   adoption WO (the ratchet stays intact).
-
-**`tests/chartDefaults.test.js`**
-
-3. A caller passing `grid={{ vertical: true }}` receives **both** `vertical: true` and the default
-   `horizontal: true`. **Prove non-vacuity** by reverting to the plain default parameter and
-   confirming the test fails.
-4. A caller passing `grid={false}` (or the documented way to switch the grid off entirely) still
-   gets no grid — merging must not make the default un-removable.
-
-Plus `tsc -p tsconfig.build.json --noEmit` clean.
-
-**No full-suite run.** Affected-areas set is the two test files above.
-
-### Verification
-
-- The rendered two-width side-by-side per DS-1, **and this time it must cover what changed**: the
-  harness needs a specimen row rendering `color="success|warning|error|info"` on **Button, Chip and
-  Alert** — the components where `main` actually resolves. It has none today, which is precisely why
-  the gate could not catch defect 1 the first time. Adding that row is part of this WO.
-- A chart specimen that passes a partial `grid`, to show the merge.
-
-### Preconditions
-
-- `THEME-1` (`2.30.0`) and `CHART-6` (`2.31.0`) landed and published.
-
-### Parity guardrail
-
-No behaviour, permission or data-contract change. One palette value moves deliberately and visibly;
-everything else must render identically.
-
----
-
-## B. Implementation map
-
-*Filled by the Orchestrator on `git pull` — see AGENTS.md → "Work Order".*
-
-### Execution directive (read this first)
-
-> **If you are the implementer reading this work order as your own specification: this section is
-> NOT addressed to you.** It tells the Orchestrator how to invoke you. **You ARE that invocation —
-> do NOT shell out to `codex exec`.**
->
-> Implement through `codex exec` in the background — invoked directly via Bash (never the
-> `debugger`/`*_coder` Agent wrappers) with BOTH flags `--skip-git-repo-check` and
-> `--dangerously-bypass-approvals-and-sandbox`. **Pass the WO via stdin, not as a positional
-> argument** — `cat work-orders/THEME-2.md | codex exec --skip-git-repo-check
-> --dangerously-bypass-approvals-and-sandbox -` (a positional arg hits Windows' command-line length
-> limit on a WO this size — proven on THEME-1/CHART-6). Fallback to direct Claude implementation
-> only on Codex quota/rate-limit/non-zero exit.
-
-### Context package
-
-**Preconditions verified 2026-08-10:** `THEME-1` (`96992cf`) and `CHART-6` (`6dedc62`) are both
-landed on `main` and published (`2.30.0`, `2.31.0`).
-
-**Defect 1 — exact current state, verified in `src/theme/tokens.js:81-87`:**
-```js
-warning: {
-  ...withMainShades('#C08A2C', '#212529'),
-  text: '#976100',
-  fill: '#C08A2C',
-  fillText: '#212529',
-  bg: '#FBF0DC',
-},
-```
-`withMainShades(main, contrastText)` (defined near the top of `tokens.js`) sets `main`/`light`/`dark`/
-`contrastText` via MUI's own `lighten`/`darken` at 0.2/0.3 tonal offsets. **Fix:** change the call to
-`withMainShades('#976100', '#FFFFFF')` — reusing the existing `text` value as the new `main`, and
-`'#FFFFFF'` as `contrastText` (verify this actually clears 4.5:1 — the WO states 5.216 on white
-already for `#976100`, and `contrastText` white-on-`#976100` is the same ratio by symmetry). Leave
-`text`/`fill`/`fillText`/`bg` untouched — `fill` stays the lighter amber for deliberate fill use
-(THEME-1's own `MuiAlert` `standardWarning` styleOverride already reads `palette.warning.text`/`.bg`,
-NOT `.main`, so that specimen is unaffected by this change — see the harness note below for why a
-NEW specimen is needed to actually exercise `.main`).
-
-**Defect 1's assertion rule — add to `src/theme/themeCompleteness.js`'s `contrastFindings(theme)`
-function (~line 249).** Alongside the existing per-status `text`-vs-`bg` and `fillText`-vs-`fill`
-loops, add a third: for each `status` in `STATUS_KEYS` (`['success','warning','error','info',
-'stale']`, from `tokens.js`) that HAS a `.main` property (**`stale` does not** — it's a custom
-augmented namespace, never passed through MUI's `createPalette`/`augmentColor`, so
-`theme.palette.stale.main` is `undefined` — skip it, don't push a spurious finding for a channel
-that was never supposed to have one), check `calculateContrastRatio(tokens.main, '#FFFFFF')` and
-`calculateContrastRatio(tokens.main, theme.palette.background.default)`, both `>= 4.5`, pushing a
-`contrast.<status>.main-on-<white|page>` finding (matching the existing naming convention,
-`contrast.controlBorder.<state>-on-<surface>`) on failure. This is a REPORT via the existing
-`findings` array — `assertThemeComplete` never throws or hard-fails on its own (confirm this by
-reading the function; the "ratchet stays a report, not a hard fail for non-adopters" is structural
-here, not a flag to add — a consuming app's OWN test suite decides whether to assert
-`findings.length === 0`, ucm's export just returns data either way).
-
-**Defect 2 — exact current state, verified in `src/components/charts/BarChart.jsx:26` and
-`LineChart.jsx:43`:** `grid = { horizontal: true }` as a bare JS default parameter, then
-`grid={grid}` passed straight through (`BarChart.jsx:65`, `LineChart.jsx:88`) — a caller-supplied
-`grid` object REPLACES the default wholesale rather than merging per-key, unlike every sibling prop
-in this file (compare `withAxisDefaults`'s `tickLabelStyle` merge, `withChartSlotDefaults`'s
-`tooltip`/`legend` merge — both spread the default first, caller second, so the caller only
-overrides the keys it actually sets). **Fix:** add a `withGridDefaults(grid)` helper to
-`src/components/charts/chartDefaults.js` following the SAME pattern (`{ horizontal: true, ...grid }`
-— MUI's `grid` prop type is `Pick<ChartsGridProps, 'vertical'|'horizontal'>`, plain optional
-booleans, no special `false`/`true` shorthand at the type level, so spreading a caller's object
-after the default is sufficient: a caller wanting no grid at all passes
-`grid={{ horizontal: false, vertical: false }}` explicitly, which the spread correctly honours since
-it's a later key overriding an earlier one — do not add special-casing for a literal `grid={false}`
-unless you find MUI's actual runtime prop handling treats a boolean differently from the declared
-type, which the WO's own phrasing ("or the documented way to switch the grid off entirely") already
-anticipates might not be a literal `false`). Wire it into both `BarChart.jsx` and `LineChart.jsx`
-the same way the other `chartDefaults.js` helpers are used.
-
-**Defect 2's audit — read `src/components/charts/chartDefaults.js` in full and check each
-object-valued prop the wrappers default or forward against the same replace-vs-merge question:**
-- `withAxisDefaults`'s `tickLabelStyle: { fontSize: tickFontSize, ...axis.tickLabelStyle }` —
-  ALREADY merges correctly (default first, caller's own `tickLabelStyle` fields win per-key).
-- `withChartSlotDefaults`'s `{ ...slotProps, tooltip: {...}, legend: {...} }` — the outer
-  `...slotProps` spread preserves any OTHER slot key a caller sets (e.g. `slotProps.axisHighlight`),
-  and the `tooltip`/`legend` sub-objects are themselves merged default-first. ALREADY correct.
-- `LineChart.jsx`'s `slots={{ mark: FilledMarkElement, ...slots }}` — default first, caller's own
-  `slots` spread after, so a caller's own `slots.mark` wins and other slot keys survive. ALREADY
-  correct.
-- `spaceForRotatedTicks`'s `margin` handling is NOT a "default object caller can partially override"
-  shape at all (it only computes `margin.bottom` when rotation is detected AND the caller hasn't set
-  one) — not the same bug class, nothing to fix there, but confirm this reading is right by re-reading
-  the function rather than trusting this summary.
-**Verify each of these four independently rather than trusting this list — this map is a starting
-point for the audit, not a substitute for it.** If the audit finds anything actually broken beyond
-`grid`, fix it and say so explicitly in the PR/commit, per the WO's "fix that too and say so." If the
-audit confirms all four are already correct, state that explicitly too — "audited and confirmed
-correct" is a valid, expected outcome per the WO ("either... or a named list").
-
-**Harness — why a new specimen row is required, not optional (verified 2026-08-10):** the current
-`ThemeBaselineEntry` (`dev/entries.jsx`) has TWO status-colour specimens today, and NEITHER exercises
-`palette.<status>.main`:
-1. `StatusChip` (`dev/entries.jsx:71-78`) sets `sx={{ bgcolor: '${tone}.fill', color:
-   '${tone}.fillText' }}` directly — bypasses `.main` entirely by design.
-2. `<Alert severity="warning">` etc. (`dev/entries.jsx:136-140`) — THEME-1's `MuiAlert`
-   `styleOverrides.standardWarning` (`src/theme/createAppTheme.js`'s `createPaletteAwareComponents`)
-   already overrides the STANDARD variant's `color`/`backgroundColor` to `palette.warning.text`/
-   `.bg` directly, NOT `.main` — so this existing Alert row was already immune to defect 1 and would
-   not have caught it even now.
-   Add: a row of `<Button color="success|warning|error|info" variant="contained">` (MUI's contained
-   Button reads `palette[color].main` for its background and `.contrastText` for its label — this is
-   the most direct `.main` exposure in the kit), a row of native `<Chip color="warning">` (not
-   `StatusChip` — MUI's own `color` prop on `Chip`, filled variant, also reads `.main`/
-   `.contrastText` directly), and an `<Alert severity="warning" variant="filled">` (MUI's `filled`
-   Alert variant is NOT covered by THEME-1's `standardWarning`-only override, so it still resolves
-   `.main` — confirm this by checking `createPaletteAwareComponents`'s `alertStyles` only sets
-   `standard${Status}` keys, never `filled${Status}` or `outlined${Status}`). These three together
-   are what the WO's Verification section means by "Button, Chip and Alert — the components where
-   `main` actually resolves."
-
-**Chart specimen for the `grid` merge:** the existing "Caller overrides" `LineChart` specimen
-(`dev/entries.jsx`, added in CHART-6) already sets `grid={{ horizontal: true, vertical: true }}` — a
-COMPLETE object, which happens to already include `horizontal: true`, so it would not visibly
-demonstrate the bug even pre-fix. Change it to a genuinely PARTIAL grid, e.g. `grid={{ vertical:
-true }}` alone — pre-fix this would have shown ONLY vertical lines (losing the horizontal default);
-post-fix it must show both. This is the specimen the WO's Verification section calls for ("A chart
-specimen that passes a partial `grid`, to show the merge").
-
-### Named files to change
-
-- `src/theme/tokens.js` — the `warning` entry's `withMainShades(...)` call (line 82).
-- `src/theme/themeCompleteness.js` — `contrastFindings` (~line 249), add the `main`-vs-white/page
-  loop, skipping any `STATUS_KEYS` entry without a `.main`.
-- `src/components/charts/chartDefaults.js` — new `withGridDefaults` export.
-- `src/components/charts/BarChart.jsx:26,65`, `src/components/charts/LineChart.jsx:43,88` — wire in
-  `withGridDefaults`.
-- `dev/entries.jsx` — new Button/Chip/Alert `.main`-exercising specimen row; fix the existing
-  "Caller overrides" LineChart's `grid` prop to a genuinely partial object.
-- `package.json` — version `2.31.0` → `2.31.1` (patch).
-- `tests/themeCompleteness.test.js` — extend with the 2 required tests (main contrast + non-vacuity
-  proof by temporarily reverting `warning.main`; ratchet/report-not-hard-fail confirmation).
-- `tests/chartDefaults.test.js` — extend with the 2 required tests (partial-grid merge + non-vacuity
-  proof by temporarily reverting to the bare default parameter; grid-off-via-explicit-false-object
-  still works).
-
-### Do-not-touch / invariants
-
-- `success`/`error`/`info`/`stale` palette values — untouched, they measure fine.
-- `warning.fill`/`.text`/`.bg` — untouched.
-- The committed reference-sheet HTML artifact (`work-orders/assets/THEME-1-baseline-reference-sheet.html`)
-  — frozen spec, never depicted `warning.main` as a foreground, not touched by this WO.
-- Anything in CHART-6's scope beyond the `grid` merge and the audit — no new chart-chrome feature
-  work here.
-- No behaviour, permission, or data-contract change.
-
-### Pitfalls (verified against landed code 2026-08-10)
-
-- `withMainShades` is defined once near the top of `tokens.js` and used for
-  `success`/`warning`/`error`/`info` — changing ONLY the `warning` call site, not the helper itself
-  (the helper's `lighten`/`darken` derivation logic is correct and unrelated to this bug).
-- `STATUS_KEYS` includes `'stale'`, which has no MUI-augmented `.main` — a naive loop over all
-  `STATUS_KEYS` reading `tokens.main` will hit `undefined` for `stale`; guard it (`if (!tokens?.main)
-  continue`, matching the existing loop's `if (!tokens) continue` pattern one function up).
-- Don't confuse this WO's `contrastFindings` addition with `THEME_COMPLETENESS_SURFACES`'s existing
-  `STATUS_SURFACES` (`text`/`fill`/`fillText`/`bg` presence-vs-default check) — the new rule is a
-  CONTRAST check (numeric ratio), same family as the existing `contrast.<status>.text-on-bg` /
-  `contrast.controlBorder.*` findings, not a "surface is deliberately defined" presence check.
-
-### Target repo working directory (absolute)
-
-`C:\Users\biglmi\Documents\webapps\ui-core-micha`
-
-### Required tests to WRITE (Codex writes them; the Orchestrator runs them)
-
-Exactly the 4 tests enumerated in Envelope § "Required tests to WRITE" above, extending
-`tests/themeCompleteness.test.js` and `tests/chartDefaults.test.js` (no new files), plus
-`tsc -p tsconfig.build.json --noEmit` clean. Do not add more, do not run the full suite. Affected-areas
-set is exactly those two files.
-
-### Preamble (append verbatim)
-
-> The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there
-> is no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and the
-> app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
-> unless the spec says so; do not update `MEMORY.md`. Do NOT `git add`/`commit`/`push` — leave every
-> change uncommitted in the working tree for the orchestrator's independent review. WRITE the tests
-> the `Required tests` section calls for AND **RUN the tests you just wrote** to confirm they execute
-> and pass — that is the ONLY test run you do (NOT the app's affected/full suite, NOT any review).
-> The orchestrator re-runs the authoritative set + does the independent review after you finish —
-> those are the gate; your own run does not count as the gate.
->
-> Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
-> `PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
-> completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
-> `RESULT: DONE|BLOCKED <reason>`.
-
-### Mini-handover
-
-Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`. WO:
-`work-orders/THEME-2.md`. Follow `orchestrate-codex`.

package/work-orders/THEME-3.md

@@ -1,210 +0,0 @@
-# THEME-3 — Add the missing "subtle surface" baseline token
-
-**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`; a push touching
-`src/**`/`package.json` publishes to npm immediately via `publish.yml`)
-**Tier:** 3 — shared-core theme baseline, consumed by every `createAppTheme` adopter.
-**Review:** independent `reviewer` **and** `ui_reviewer`, concurrently, both mandatory before commit
-(no staging net in this repo — the independent review is the only gate and is not back-fillable).
-**Found by:** `cockpit/UI-6` (adopting `createAppTheme` with the frozen `UI-4` token table). The
-sheet's canonical token table (section 8, "what cockpit stops owning") lists an *inset surface*
-`#F4F5F6` as a baseline-supplied value, replacing `cockpit.surface2` (16 of 195 token reads in that
-WO). It does not exist anywhere in the shipped package — confirmed by grepping
-`src/theme/tokens.js`/`themeCompleteness.js` for the hex and for any "surface"/"inset" key. The value
-was one of the design-language instrument's *own* internal comparison-stack entries
-(`cockpit/work-orders/assets/UI-4-design-language.html:681`), never actually wired into
-`createAppTheme`. Per this estate's own rule ("a gap in the shared kit discovered mid-adoption is a
-`ui-core-micha` work order and cockpit's item waits — not a local workaround"), `UI-6` is blocked on
-this landing and publishing first.
-
----
-
-## A. Envelope
-
-### Goal
-
-Add a third baseline background tier — `palette.background.subtle` — to `createAppTheme`'s shared
-palette, for panels/table stripes/excerpt boxes that need to read as slightly recessed from
-`background.paper` without a bespoke per-app colour. Register it in the completeness-assertion
-surface inventory so every adopter (present and future) gets the same guarantee the other baseline
-surfaces already have.
-
-### Scope
-
-1. **`src/theme/tokens.js`** — add `background.subtle: '#F4F5F6'` to `BASELINE_PALETTE.background`
-   (alongside the existing `default`/`paper`). This is a **fixed baseline constant**, not
-   accent-derived — the same treatment as `default`/`paper`, not the accent-tint derivation used for
-   `cockpit.accentTint`.
-2. **`src/theme/themeCompleteness.js`** — add `pathSurface('palette.background.subtle')` to
-   `THEME_COMPLETENESS_SURFACES`.
-3. **Recompute the contrast claim independently** — the frozen sheet's "muted ink on it: 4.81" was
-   computed on the sheet's own static comparison canvas, not via this package's
-   `calculateContrastRatio`. Recompute `calculateContrastRatio('#5B6670', '#F4F5F6')` (baseline
-   `ink.secondary`, the tone most likely to sit on this surface) directly against the shipped
-   function before treating the sheet's number as confirmed.
-4. Publish (version bump — see Risks for the semver call).
-
-### Non-goals / do not touch
-
-- Renaming or removing any existing palette token.
-- `CHART-*`/`SHELL-*`/`AUTH-*` surfaces — unrelated to this addition.
-- `fitness-monitor` or any other consuming app's own repo — this WO lands and publishes the token
-  only; `cockpit/UI-6` consumes it afterward, in its own repo, as a separate step.
-- Any accent-derived tint/shade math — this token is a fixed baseline value, structurally unlike
-  `cockpit.accentTint`/`accentLight`/`accentDark`.
-
-### Risks
-
-- **`fitness-monitor` is a real, already-shipped adopter** (`frontend/src/theme.js` +
-  `frontend/src/theme.test.js`) that hard-asserts `assertThemeComplete(theme).findings` equals `[]`.
-  A new *required* completeness surface must resolve automatically for every adopter with zero
-  app-level action — the same guarantee `background.default`/`background.paper` already give,
-  **not** an opt-in the app must declare. Concretely: the new key must come from
-  `BASELINE_PALETTE` so every real `createAppTheme(...)` output has it defined, and MUI's own
-  default theme must never define `background.subtle` itself (a novel key — verify this, don't
-  assume it), so `descriptor.get(MUI_DEFAULT_THEME)` returns `undefined` and the "still equals MUI's
-  untouched default" branch never fires. If either assumption is wrong, `fitness-monitor`'s CI
-  breaks on its next pin bump and this WO must not ship that way.
-- **Semver classification** — additive to the factory's *output* (no adopter passes anything new to
-  get it), which argues for a patch, mirroring `SHELL-4`'s "narrows the contract, cannot turn
-  cockpit red" precedent in the opposite direction (widens the contract, but resolves automatically,
-  so it also cannot turn an adopter red). Confirm no adopter needs a code change before treating
-  this as settled rather than asserting it.
-- **Do not silently rename cockpit's `surface2` in this repo** — this WO adds the baseline token;
-  cockpit's own re-point of 16 call sites from `cockpit.surface2` to the new baseline token is
-  `UI-6`'s job, in cockpit's repo, not this one's.
-
-### Required tests to WRITE
-
-1. `assertThemeComplete` stays empty-findings for a minimal adopter call —
-   `createAppTheme({ palette: { primary: { main: '#0F62FE' } } })` (mirroring `fitness-monitor`'s
-   real usage) — proving the new surface resolves with zero adopter action, not just for a theme
-   that happens to declare it.
-2. `theme.palette.background.subtle` equals `'#F4F5F6'` on an unconfigured `createAppTheme(...)`
-   call.
-3. `calculateContrastRatio('#5B6670', '#F4F5F6')` (baseline `ink.secondary` on the new surface)
-   passes AA (≥ 4.5:1) — computed via the shipped function, not asserted from the sheet's number.
-4. Existing `tests/createAppTheme.test.js` and `tests/themeCompleteness.test.js` stay green
-   unmodified in intent (only extended where the new surface must appear in an enumeration they
-   already assert against, e.g. a surface-count or key-list check if one exists).
-
-### Verification
-
-No visual/prototype gate — this is a token-level palette addition with no rendered specimen of its
-own in this repo. The rendered check for what this token actually looks like on real cockpit
-surfaces happens downstream, in `cockpit/UI-6`'s own two-width verification.
-
----
-
-## B. Implementation map
-
-*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
-
-### Context package
-
-- **`src/theme/tokens.js`** — `BASELINE_PALETTE.background` currently reads:
-  ```js
-  background: {
-    default: '#FAFAFA',
-    paper: '#FFFFFF',
-  },
-  ```
-  Add `subtle: '#F4F5F6'` as a third key. This is the ONLY change needed in this file for the new
-  value itself — do not touch `SERIES_COLOURS`, `STATUS_KEYS`, `BASELINE_STATIC`, or the exemptions
-  list.
-- **`src/theme/themeCompleteness.js`** — `THEME_COMPLETENESS_SURFACES` (around line 155-192) already
-  has `pathSurface('palette.background.default')` and `pathSurface('palette.background.paper')` in
-  its list. Add `pathSurface('palette.background.subtle')` immediately next to them — same helper,
-  same pattern, no new machinery needed.
-- **Why this can't collide with an existing adopter (verified, not assumed):** `MUI_DEFAULT_THEME =
-  createTheme()` (line 5 of `themeCompleteness.js`) is vanilla MUI with no `background.subtle` key —
-  MUI's own palette only ever defines `background.default`/`.paper`. So for every real
-  `createAppTheme(...)` output, `descriptor.get(theme)` resolves to `'#F4F5F6'` (defined) while
-  `descriptor.get(MUI_DEFAULT_THEME)` resolves to `undefined` — the `sameValue` check in
-  `assertThemeComplete` (around line 354) therefore never flags it, with no exemption required. This
-  is exactly why `background.default` needs no exemption today; `background.subtle` gets the same
-  treatment. `background.paper` is the one that DOES need an exemption, because MUI's own default
-  theme also happens to be white — do not copy that exemption pattern here, it does not apply.
-- **`calculateContrastRatio` is already exported** from `src/theme/themeCompleteness.js` and
-  re-exported from `src/theme/index.js` — use it directly for the required contrast test, do not
-  reimplement contrast math.
-- **Test file conventions** (read `tests/themeCompleteness.test.js` and
-  `tests/createAppTheme.test.js` for the existing style before writing new assertions — minimal
-  `createAppTheme({ palette: { primary: { main: '#0F62FE' } } })` is the repo's own established
-  "minimal adopter" fixture, already used in both files; reuse it rather than inventing a new one).
-- Directive: work from this package; do not explore broadly from scratch; open only the two named
-  source files plus the two named test files to verify. If you must dig deeper, delegate to a
-  read-only Explore sub-agent (Haiku).
-
-### Target repo working directory (absolute)
-
-`C:\Users\biglmi\Documents\webapps\ui-core-micha`
-
-### Preamble
-
-> The text of this whole file is the COMPLETE spec — not a plan to refine; there is no separate plan
-> file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and this repo's
-> own `DESIGN.md`/conventions ONLY for conventions. Stay in scope; do not touch
-> `CHART-*`/`SHELL-*`/`AUTH-*` surfaces or any file outside `src/theme/` and `tests/` unless this
-> spec says so; do not update any `MEMORY.md`. Do NOT `git add` / `commit` / `push` — leave every
-> change uncommitted in the working tree for the orchestrator's independent review; do NOT bump
-> `package.json`'s version yourself — the Orchestrator decides and applies the semver bump after
-> review, per the Risks section's still-open patch/minor question. WRITE the tests the "Required
-> tests to WRITE" section calls for AND **RUN the tests you just wrote** (plus the two named existing
-> spec files, to confirm no regression) to confirm they execute and pass — that is the ONLY test run
-> you do (NOT this repo's full suite, NOT any review). The orchestrator re-runs the authoritative set
-> + does the independent review after you finish — those are the gate; your own run does not count
-> as the gate.
->
-> Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
-> `PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
-> completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
-> `RESULT: DONE|BLOCKED <reason>`.
-
----
-
-## C. Orchestrator only — NOT ADDRESSED TO THE IMPLEMENTER
-
-> **If you are the implementer reading this work order as your own specification: STOP at this line.
-> Everything below describes what the Orchestrator does AFTER you finish. You do none of it — no
-> reviewers, no verification run, no register edit, no commit.** You ARE the invocation described
-> below; do NOT shell out to `codex exec`.
-
-### Execution directive
-
-Implement through `codex exec` in the background — invoked directly via Bash (never the
-`debugger`/`*_coder` Agent wrappers) with BOTH flags `--skip-git-repo-check` and
-`--dangerously-bypass-approvals-and-sandbox`. **Pass the work order via stdin, not as a positional
-argument** (this repo's own `THEME-1` row already documents the Windows command-line length limit
-hitting this via the npm shim). Fallback to direct Claude implementation only on Codex
-quota/rate-limit/non-zero exit — the fallback flips authorship, so both reviewers stay mandatory
-either way.
-
-### Review routing
-
-Tier 3: `reviewer` (Sonnet) + `ui_reviewer` (Sonnet), concurrent, same background batch, before
-commit. No `sec_reviewer` — no auth/security surface in scope. `ui_reviewer`'s job here is narrow
-(no rendered surface to review) — focus it on the completeness-contract and adopter-safety question
-rather than visual design.
-
-### Verification
-
-No rendered two-width check — token-only change with no specimen in this repo (per the Envelope).
-The authoritative check is: the two new/extended test files pass, `tests/createAppTheme.test.js` +
-`tests/themeCompleteness.test.js` stay green, and a direct read of `fitness-monitor`'s
-`frontend/src/theme.test.js` assertion confirms it would still pass unmodified against the new
-package version (do not just reason about it — actually run `fitness-monitor`'s own scoped theme
-test against the locally-built `ui-core-micha` if practical, or explain why not).
-
-### Register + commit
-
-Decide and apply the semver bump (patch, per the Risks section's reasoning, unless the
-implementation reveals an adopter needs a code change — then escalate to minor and say why). Update
-the `WORK_ORDERS.md` THEME-3 row to `done` with the named review verdicts and version, then commit +
-push to `main` on green (this push publishes to npm — confirm everything is green first, there is no
-staging net here).
-
-### Mini-handover
-
-Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.
-WO: `work-orders/THEME-3.md`. **Ready to run** — no preconditions, small well-bounded addition.
-Follow `orchestrate-codex`.