@micha.bigler/ui-core-micha 2.33.0 → 2.33.2

package/work-orders/SHELL-4.md

@@ -0,0 +1,351 @@
+# SHELL-4 — Give each bottom-nav property exactly one home
+
+**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
+**Tier:** 3 (shared core)
+**Review:** independent `reviewer` **and** `ui_reviewer` — spawned concurrently, both mandatory before commit
+**Version target:** `2.33.1` — patch. See "Why patch" below.
+**Precondition of:** `jg-ferien/NAV-36`, which is `blocked` on this
+**Follows:** `SHELL-3` (`2.33.0`) and its fix `586ac9c`
+
+---
+
+## A. Envelope
+
+### Goal
+
+`SHELL-3` shipped `MobileBottomNav` with **all** visible styling in the theme layer and only
+position, `zIndex` and safe-area padding in the component. For an app that has adopted
+`createAppTheme` that is correct and renders as specified. For an app that has **not**, the bar
+arrives structurally broken — and jg-ferien, the migration consumer the promotion exists for, is
+exactly that app.
+
+Fix the layer split so the component works on any theme, without reintroducing the shadowing bug
+that `586ac9c` removed.
+
+### How this happened, because the reasoning matters more than the diff
+
+`SHELL-3`'s `ui_reviewer` found the component duplicating `borderTop` and `borderColor` inline in
+`sx` — the same properties the same work order had just registered as theme defaults. Inline `sx`
+beats `styleOverrides`, so the new defaults were inert. The fix removed the component's copies.
+
+**That resolved the duplication by deleting the wrong copy.** The defect was the *duplication*, not
+the *location*. For a property a component needs in order to function on an arbitrary theme, the
+component is the correct home — and the fix moved exactly those into a layer that only baseline apps
+have.
+
+### What a non-baseline consumer loses today
+
+Read against MUI's installed source, not assumed. Every item below currently lives **only** in the
+baseline theme:
+
+| Property | MUI's default | Consequence |
+|---|---|---|
+| `MuiBottomNavigationAction` `minWidth: 0` | **`minWidth: 80`** | **layout break** — see below |
+| `maxWidth: 'none'` | `maxWidth: 168` | actions cannot fill a wide bar |
+| `MuiBottomNavigation` `borderTop: '1px solid'` | MUI sets **no border** | the bar has no top edge |
+| `borderColor: palette.divider` | — | same |
+| label `fontSize: '12px'` + the `&.Mui-selected` pin | `12px`, **`14px` when selected** | the label jumps on tap |
+| label `fontWeight: 500` | unset | thinner |
+| label `lineHeight: 1.2` | unset | taller label row |
+| action `padding: '0 2px'`, `gap: '2px'` | MUI's own | looser density |
+| icon `22px` | MUI's `24px` | slightly larger icons |
+
+`backgroundColor` and the action/selected colours are **not** losses — MUI sets equivalents itself.
+
+**The first row is not cosmetic.** jg has five destinations: `5 × 80 = 400px` against a 375 px
+viewport, and `min-width` overrides `flex-shrink`, so the container overflows. jg's current code sets
+`minWidth: 0` explicitly for exactly this reason. **Computed from MUI's source, not rendered** —
+confirm it in the rendered check rather than trusting the arithmetic.
+
+### The rule to apply
+
+**Each property gets exactly one home, chosen by who needs it:**
+
+- **The component owns what keeps it functional on any theme.** These are deliberately *not*
+  theme-overridable, and that is a feature: overriding them breaks the bar.
+- **The theme owns what makes it look like this estate.** These stay overridable per app, which is
+  what makes the component design-agnostic.
+
+**And the distinction that was missed the first time:** a **token reference** in the component's `sx`
+(`borderColor: 'divider'`) is not the same thing as a hex literal and not the same thing as a
+duplicate. It resolves against *whatever* theme is mounted — every app still gets its own divider
+colour — while a duplicate of a theme default silently shadows it. Reference without duplication is
+the correct pattern; "contains no hex values" is the wrong test for it.
+
+### Scope
+
+**Move into the component, and delete from `tokens.js`:**
+
+- `MuiBottomNavigationAction`: `minWidth: 0`, `maxWidth: 'none'`
+- `MuiBottomNavigation`: `borderTop: '1px solid'`, and `borderColor: 'divider'` as an `sx` token
+  reference (delete `borderColor: palette.divider` from `createAppTheme.js`'s palette-aware block)
+
+**Leave in the theme, unchanged:** the label `fontSize` / `fontWeight` / `lineHeight` and its
+selected pin, the action and selected `color`, `backgroundColor`, `boxShadow: 'none'`, `padding`,
+`gap`, and the icon size. A bar with MUI's density and 24 px icons still works; a bar with
+`minWidth: 80` does not.
+
+**Deregister the four moved surfaces** from `themeCompleteness.js`:
+`components.MuiBottomNavigation.styleOverrides.root.borderTop`, `…root.borderColor`,
+`components.MuiBottomNavigationAction.styleOverrides.root.minWidth`, `…root.maxWidth`. Six of the ten
+`SHELL-3` surfaces remain. **This cannot turn any app red**: the assertion validates that each
+declared exemption names a surface and a reason, and then ignores exemptions that match no
+registered surface — verified in `themeCompleteness.js`, not assumed.
+
+**Add an `sx` prop to the component**, merged **after** its own defaults. This is the honest
+mitigation for the properties that just became theme-unoverridable: a call site that genuinely needs
+a different edge can still get one, without the theme layer being the escape route.
+
+### Non-goals / do not touch
+
+- **No new props beyond `sx`.** `destinations`, `activeRoute`, `onNavigate`, `hideAbove`, `zIndex`
+  and the destination field shape stay exactly as `SHELL-3` shipped them.
+- **No visual change for baseline apps.** The values are identical; only their layer moves. If a
+  baseline app renders differently, that is a defect in this WO.
+- No other component, no other baseline token, no palette or typography change.
+- No change to `emphasis`, `badgeCount`, `shortLabel` semantics.
+- No migration of jg-ferien — that stays `NAV-36`.
+
+### Risks
+
+- **Reintroducing the shadow.** The whole point is that a property lives in one layer. Deleting from
+  `tokens.js` and adding to the component must happen together; doing half leaves either a shadow or
+  a gap. The test below makes this checkable rather than a matter of care.
+- **No staging net.** A version bump on `main` publishes to npm; the independent review is the only
+  gate and cannot be back-filled.
+- **A property moved into `sx` is no longer theme-configurable**, which is a real capability
+  reduction for the four moved properties. Accepted deliberately: three of the four break the
+  component when changed, and the `sx` prop covers the fourth.
+
+### Why patch, not minor
+
+No new capability: this relocates existing values and adds one escape-hatch prop. Baseline apps
+render byte-identically. The narrowed assertion contract asks adopting apps for **less**, not more.
+Per the estate's rule that a version bump follows scope rather than novelty, that is a patch.
+
+The one argument for minor — a capability reduction, since four properties stop being
+theme-overridable — is noted and rejected: `MobileBottomNav` is one release old with **no** consumer
+yet on any published version, so no app can be relying on that override path.
+
+### Required tests to WRITE
+
+Extend `tests/MobileBottomNav.test.jsx` and `tests/themeCompleteness.test.js`.
+
+1. **The non-baseline case, which is the whole point.** Render under a plain `createTheme()` and
+   assert the bar has a top border and its actions resolve `minWidth: 0` — the two failures that
+   block `NAV-36`. Prove non-vacuity: this test must fail against `2.33.0`'s arrangement.
+2. **No property lives in two layers.** Assert the intersection of the component's own `sx` keys and
+   the baseline's `MuiBottomNavigation` / `MuiBottomNavigationAction` `styleOverrides` keys is
+   **empty**. This is the mechanical guard for the regression class `SHELL-3` hit, and it is the
+   reason to prefer it over a reviewer noticing.
+3. `sx` passed by the caller wins over the component's own defaults.
+4. Baseline rendering is unchanged: the same assertions `SHELL-3`'s spec makes about a
+   `createAppTheme` theme still hold, including test 5b's cross-theme colour resolution.
+5. `assertThemeComplete(createAppTheme({ palette: { primary: { main: '#0F62FE' } } })).findings`
+   stays `[]` with six surfaces registered instead of ten.
+6. An exemption naming one of the four deregistered surfaces produces **no** finding — the
+   forward-compatibility claim above, asserted rather than trusted.
+
+Plus `tsc -p tsconfig.build.json --noEmit` clean. **No full-suite run** — the affected set is those
+two specs plus `tests/createAppTheme.test.js`.
+
+### Verification
+
+The rendered two-width side-by-side per `DS-1`. `SHELL-3` added a bottom-nav specimen to
+`dev/entries.jsx`; extend it with **a second instance mounted under a plain `createTheme` theme**
+side by side with the baseline one. That comparison is the actual deliverable of this WO made
+visible: both bars must have an edge and evenly divided actions, and they may legitimately differ in
+label size and density.
+
+State in the register note whether real screenshots were obtained or DOM inspection substituted.
+`SHELL-3`'s session could not composite frames and fell back to computed-style inspection — if that
+recurs, the computed `min-width` and `border-top-width` on the plain-theme instance are the two
+values that carry this WO's claim.
+
+### Parity guardrail
+
+Byte-identical rendering for baseline apps. The only intended change is that a non-baseline
+consumer's bar gains its edge and its evenly divided actions.
+
+---
+
+## 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** (a positional arg hits Windows' command-line length limit — proven repeatedly in this
+> repo). Fallback to direct Claude implementation only on Codex quota/rate-limit/non-zero exit —
+> and note that the fallback flips authorship, so both reviewers stay mandatory either way.
+>
+> **`SHELL-3` note for the Orchestrator:** on that WO Codex committed its own change and marked the
+> register row `done` with a self-reported review. That is a breach (`AGENTS.md`: author ≠ reviewer,
+> a spawned implementer never commits). Read `git log origin/main..HEAD` before your own review and
+> treat any implementer commit as a blocker to surface, not something to build on.
+
+### Context package
+
+**Note on the Envelope's "ten to six" arithmetic:** the actually-landed `SHELL-3` surface count in
+`themeCompleteness.js` is **twenty**, not ten (SHELL-3's own scope grew mid-implementation to cover
+icon size/padding/gap/label truncation, beyond the ten originally sketched). This does not change
+the instruction — deregister exactly the four surfaces named below, no more, no less — but do not
+be thrown by the stale count in the prose above.
+
+**Files to change, with current line numbers (verified against the landed `SHELL-3` + `586ac9c`
+state, may drift slightly if Codex edits top-to-bottom — re-grep `MuiBottomNavigation` if a line
+number is off by a few):**
+
+1. **`src/theme/tokens.js:309-334`** — the current `BASELINE_STATIC.components` entries:
+   ```js
+   MuiBottomNavigation: {
+     styleOverrides: {
+       root: { borderTop: '1px solid', boxShadow: 'none' },
+     },
+   },
+   MuiBottomNavigationAction: {
+     styleOverrides: {
+       root: {
+         minWidth: 0,
+         maxWidth: 'none',
+         padding: '0 2px',
+         gap: '2px',
+         '& .MuiSvgIcon-root': { width: '22px', height: '22px' },
+       },
+       label: { /* fontSize/fontWeight/lineHeight/... unchanged, leave as-is */ },
+     },
+   },
+   ```
+   Remove `borderTop: '1px solid'` from `MuiBottomNavigation.styleOverrides.root` (keep
+   `boxShadow: 'none'` — it stays per the Envelope's "leave in the theme" list). Remove
+   `minWidth: 0, maxWidth: 'none'` from `MuiBottomNavigationAction.styleOverrides.root` (keep
+   `padding`, `gap`, the icon-size entry, and the entire `label` block unchanged).
+
+2. **`src/theme/createAppTheme.js:119-134`** — the current `createPaletteAwareComponents()` entries:
+   ```js
+   MuiBottomNavigation: {
+     styleOverrides: {
+       root: {
+         backgroundColor: palette.background.paper,
+         borderColor: palette.divider,
+       },
+     },
+   },
+   MuiBottomNavigationAction: {
+     styleOverrides: {
+       root: {
+         color: palette.text.secondary,
+         '&.Mui-selected': { color: palette.primary.main },
+       },
+     },
+   },
+   ```
+   Remove `borderColor: palette.divider` (keep `backgroundColor: palette.background.paper` — not a
+   loss per the Envelope's own table, MUI sets an equivalent). `MuiBottomNavigationAction` here is
+   untouched — `color`/`.Mui-selected` stay exactly as-is.
+
+3. **`src/theme/themeCompleteness.js:99-118`** (`COMPONENT_SURFACES` array) — delete exactly these
+   four lines:
+   ```js
+   componentPath('MuiBottomNavigation', 'styleOverrides.root.borderTop'),
+   componentPath('MuiBottomNavigation', 'styleOverrides.root.borderColor'),
+   componentPath('MuiBottomNavigationAction', 'styleOverrides.root.minWidth'),
+   componentPath('MuiBottomNavigationAction', 'styleOverrides.root.maxWidth'),
+   ```
+   Leave every other `MuiBottomNavigation`/`MuiBottomNavigationAction` line untouched (boxShadow,
+   backgroundColor, padding, gap, icon width/height, color, all label surfaces, both `.Mui-selected`
+   pins).
+
+4. **`src/components/MobileBottomNav.jsx`** (current full file, 69 lines, reproduced above in this
+   session) — add a `sx` prop (default `{}`), and merge these four properties into the root
+   `BottomNavigation`'s `sx`, with the caller's `sx` applied **last** so it wins:
+   ```js
+   export function MobileBottomNav({
+     destinations,
+     activeRoute,
+     onNavigate,
+     hideAbove = 'md',
+     zIndex = defaultZIndex,
+     sx,
+   }) {
+     ...
+     <BottomNavigation
+       ...
+       sx={{
+         position: 'fixed',
+         left: 0,
+         right: 0,
+         bottom: 0,
+         zIndex,
+         borderTop: '1px solid',
+         borderColor: 'divider',
+         paddingBottom: 'env(safe-area-inset-bottom)',
+         ...sx,
+       }}
+     >
+   ```
+   `borderColor: 'divider'` here is a **string token reference** (MUI resolves `'divider'` against
+   `theme.palette.divider` at render time on whatever theme is mounted) — this is NOT the same
+   pattern as the `586ac9c` regression, which duplicated an already-*resolved* hex-bearing default.
+   The `BottomNavigationAction`'s own `sx` (not the top-level prop) needs `minWidth: 0,
+   maxWidth: 'none'` added directly — these are per-action, not per-bar, so they do NOT go through
+   the new `sx` prop. Today the `emphasis` styling sits on the inner `<Icon sx={...}>`, not on
+   `<BottomNavigationAction>` itself — leave that untouched, and simply add a new
+   `sx={{ minWidth: 0, maxWidth: 'none' }}` prop directly on the `<BottomNavigationAction>` element,
+   independent of the `icon` prop's own conditional emphasis styling.
+
+5. **`tests/MobileBottomNav.test.jsx`** — extend with the six numbered tests from the Envelope.
+   Test 2 (no property in two layers) should import `BASELINE_STATIC` (or the theme object) and the
+   component's rendered/declared `sx` keys and assert
+   `intersection(Object.keys(componentSxDefaults), Object.keys(theme.components.MuiBottomNavigation
+   .styleOverrides.root)).length === 0` — read the existing test file's structure first
+   (`createAppTheme`/`createTheme` imports are already there from `SHELL-3`'s test 5b) and follow its
+   conventions rather than introducing a new test-setup style.
+
+6. **`tests/themeCompleteness.test.js`** — the existing `SHELL-3` assertion (added at line ~19-40,
+   the `expect(bare.findings...).toEqual(expect.arrayContaining([...20 surfaces...]))` block) needs
+   its four now-deregistered entries removed from that array, plus the Envelope's test 5 (findings
+   stays `[]` with six surfaces) and test 6 (an exemption naming a deregistered surface produces no
+   finding — because `assertThemeComplete` ignores exemptions matching no registered surface, this
+   is provable without special-casing: declare an exemption for e.g.
+   `'components.MuiBottomNavigation.styleOverrides.root.borderTop'` against a theme built without
+   that surface and assert no finding names it, since the surface list itself no longer contains it).
+
+7. **`dev/entries.jsx:69-94`** (`MobileBottomNavEntry`) — add a second `MobileBottomNav` instance
+   wrapped in its own `<ThemeProvider theme={createTheme()}>` (plain MUI, no `createAppTheme`),
+   rendered side-by-side with the existing baseline-themed one (which is already inside the harness's
+   own `createAppTheme` root — no need to wrap that one again). Import `ThemeProvider`, `createTheme`
+   from `@mui/material/styles` (createTheme is likely already imported elsewhere in this file — grep
+   first). Keep both bars visible at once (e.g. stacked in a `Stack`) so the two-width verification
+   can compare them directly: both need a visible top edge and evenly divided actions; they may
+   legitimately differ in label size/density.
+
+**Invariants / do-not-touch:** no change to `destinations`/`activeRoute`/`onNavigate`/`hideAbove`/
+`zIndex` prop semantics, `emphasis`/`badgeCount`/`shortLabel` behaviour, or any other baseline token.
+No visual change for a `createAppTheme` consumer — the four relocated properties must render
+byte-identically before and after.
+
+**Pitfalls already known:**
+- Deleting from `tokens.js`/`createAppTheme.js` and adding to the component must land in the SAME
+  commit/chunk — a partial move reintroduces either a gap (non-baseline still broken) or a shadow
+  (the exact `586ac9c` bug, just with the copies swapped).
+- `boxShadow: 'none'` and `backgroundColor` are explicitly NOT part of this move — re-reading the
+  Envelope's table, only `borderTop`, `borderColor`, `minWidth`, `maxWidth` relocate.
+- Version target is `2.33.1` (patch) — confirm `package.json` reads `2.33.1` after Codex is done, not
+  a minor bump.
+- **Per `SHELL-3`'s own execution-directive note added to this WO: verify no implementer self-commit
+  happened before doing anything else** — `git log --oneline -3` should show the Orchestrator's own
+  `1106f51`-style "fill Implementation map" commit as the most recent, not a Codex-authored `feat(...)`
+  commit. If a self-commit is present, treat it as a breach per `AGENTS.md`, not as a base to build on.
+
+### Mini-handover
+
+Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.
+WO: `work-orders/SHELL-4.md`. Follow `orchestrate-codex`.

package/work-orders/THEME-3.md

@@ -0,0 +1,210 @@
+# 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`.