@micha.bigler/ui-core-micha 3.10.0 → 3.11.1

package/tests/userScreenTranslations.test.jsx

@@ -22,6 +22,9 @@ import { UserListComponent } from '../src/components/UserListComponent';
 const germanResources = Object.fromEntries(
   Object.entries(authTranslations).map(([key, value]) => [key, value.de]),
 );
+const englishResources = Object.fromEntries(
+  Object.entries(authTranslations).map(([key, value]) => [key, value.en]),
+);
 const i18n = i18next.createInstance();
 i18n.init({
   lng: 'de',
@@ -31,12 +34,22 @@ i18n.init({
   nsSeparator: false,
   interpolation: { escapeValue: false },
 });
+const englishI18n = i18next.createInstance();
+englishI18n.init({
+  lng: 'en',
+  fallbackLng: 'en',
+  resources: { en: { translation: englishResources } },
+  keySeparator: false,
+  nsSeparator: false,
+  interpolation: { escapeValue: false },
+});
 
 const ENGLISH_DEFAULTS = [
   'All Users',
   'Search',
   'Search users...',
   'Rows per page:',
+  'of 1',
   'Successful Login',
   'Are you sure you want to delete this user?',
   'Invite a new user',
@@ -51,6 +64,10 @@ function withGermanI18n(children) {
   return <I18nextProvider i18n={i18n}>{children}</I18nextProvider>;
 }
 
+function withEnglishI18n(children) {
+  return <I18nextProvider i18n={englishI18n}>{children}</I18nextProvider>;
+}
+
 function expectNoEnglishDefaults() {
   const text = document.body.textContent;
   for (const english of ENGLISH_DEFAULTS) {
@@ -112,6 +129,7 @@ describe('German user and invite screen translations', () => {
     await waitFor(() => expect(screen.getByText('Alle Benutzer')).toBeTruthy());
     expect(screen.getByLabelText('Suche')).toBeTruthy();
     expect(screen.getByPlaceholderText('Benutzer suchen...')).toBeTruthy();
+    expect(screen.getByText('1–1 von 1')).toBeTruthy();
     for (const german of ['Neu', 'Erfolgreiche Anmeldung', 'Rolle', 'Aktionen', 'Zeilen pro Seite:', 'Löschen']) {
       expect(screen.getByText(german)).toBeTruthy();
     }
@@ -124,6 +142,41 @@ describe('German user and invite screen translations', () => {
     expectNoEnglishDefaults();
   });
 
+  it('renders the pagination range in English when the locale is English', async () => {
+    render(withEnglishI18n(<UserListComponent currentUser={{ id: 99, is_superuser: true, role: 'admin' }} />));
+
+    await waitFor(() => expect(screen.getByText('1–1 of 1')).toBeTruthy());
+  });
+
+  it('actually goes through the translation key, not a coincidental match with MUI\'s own default', async () => {
+    // The real English wording is deliberately identical to MUI's own hardcoded default text
+    // (both "{from}-{to} of {count}"), so the assertion above would still pass even if
+    // labelDisplayedRows were reverted to unset entirely. Swap in a distinctive marker for just
+    // this one key to prove the render genuinely resolves it through i18next, not MUI's fallback
+    // (UCM-I18N-5 review, tests lens).
+    const markerI18n = i18next.createInstance();
+    markerI18n.init({
+      lng: 'en',
+      fallbackLng: 'en',
+      resources: {
+        en: {
+          translation: { ...englishResources, 'UserList.DISPLAYED_ROWS': '__MARKER__ {{from}}-{{to}}/{{count}}' },
+        },
+      },
+      keySeparator: false,
+      nsSeparator: false,
+      interpolation: { escapeValue: false },
+    });
+
+    render(
+      <I18nextProvider i18n={markerI18n}>
+        <UserListComponent currentUser={{ id: 99, is_superuser: true, role: 'admin' }} />
+      </I18nextProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText('__MARKER__ 1-1/1')).toBeTruthy());
+  });
+
   it('renders UserInviteComponent in German and translates the success message', async () => {
     render(withGermanI18n(<UserInviteComponent />));
 

package/work-orders/UCM-I18N-5.md

@@ -0,0 +1,211 @@
+# UCM-I18N-5 — User-list pagination range text is hard-coded English
+
+# A. Envelope — authored by the Expertenchat
+
+## Goal & expected outcome
+
+- Goal: the user list's pagination reads in the user's language.
+- Expected outcome: `UserListComponent`'s `TablePagination` renders its "1–4 of 4" text through a
+  translation key (de/en/fr and every locale the bundles carry), the way `labelRowsPerPage`
+  already does.
+
+## Context — measured 2026-10-01 in jg-ferien's local browser (ucm 3.7.0 installed there)
+
+- `/account?tab=users` in German: "Zeilen pro Seite: 25 ▾ · **1–4 of 4**". `UserListComponent.jsx`
+  (~l.589-600) sets `labelRowsPerPage={t('UserList.ROWS_PER_PAGE', …)}` but no
+  `labelDisplayedRows`, so MUI's English default renders. It is the only `TablePagination` in ucm.
+- Follows `UCM-I18N-4` (hard-coded English in the user list).
+
+## Scope + non-goals
+
+- In scope: `labelDisplayedRows` via a key with count interpolation; tests; release.
+- Explicit non-goals / do-not-touch: no other change to the user list.
+
+## Tier · gates
+
+- **Tier 3** — change inside shared-core (small).
+- Done means released AND jg-ferien's pin bumped.
+
+## Risks
+
+- The "more than" form (`count === -1`) must have a wording too, or it renders "of -1".
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the orchestrator's run is the gate)
+
+1. In `de`, the pagination shows the German range text; in `en` the English one.
+2. Key-parity: every locale bundle has the new key.
+
+---
+
+# B. Implementation map — filled by the Orchestrator — ADDRESSED TO THE IMPLEMENTER
+
+## Context package
+
+### The call site
+
+`src/components/UserListComponent.jsx:589-601`:
+```jsx
+<TablePagination
+  component="div"
+  count={sortedUsers.length}
+  page={page}
+  onPageChange={(_, newPage) => setPage(newPage)}
+  rowsPerPage={pageSize}
+  onRowsPerPageChange={(event) => {
+    setPageSize(Number(event.target.value));
+    setPage(0);
+  }}
+  labelRowsPerPage={t('UserList.ROWS_PER_PAGE', 'Rows per page:')}
+  rowsPerPageOptions={[10, 25, 50, 100]}
+/>
+```
+`t`/`i18n` come from `useTranslation()` (`react-i18next`), already in scope at l.53.
+
+### MUI's `labelDisplayedRows` contract
+
+MUI's own default (`node_modules/@mui/material/TablePagination/TablePagination.js:119-124`,
+for reference only — do not import it):
+```js
+function defaultLabelDisplayedRows({ from, to, count }) {
+  return `${from}–${to} of ${count !== -1 ? count : `more than ${to}`}`;
+}
+```
+The prop signature is `({ from, to, count, page }) => ReactNode`. `count` is `-1` when the total
+is unknown/unbounded — this component always passes a real `sortedUsers.length`, but the prop
+contract still has to handle `-1` defensively (the Risk note): MUI itself would call the function
+with `-1` only if `count={-1}` were passed, which this component doesn't do — handle it anyway
+since the function must satisfy the full contract, not just this component's current call site.
+
+### The translation bundle has FOUR locales, not three
+
+`src/i18n/authTranslations.ts` (flat `export const authTranslations = { "Key.NAME": { de, fr, en,
+sw }, ... }`) carries `de`/`fr`/`en`/`sw` for every existing key, confirmed by grepping all locale
+codes in the file — **sw (Swahili) is real and already translated throughout, not a stub**. "every
+locale the bundles carry" in the Envelope means these four, not jg-ferien's usual three. Add the
+new key(s) in the same shape, next to `UserList.ROWS_PER_PAGE` (~l.2050-2055) for locality.
+
+Proposed keys (interpolated, i18next `{{var}}` syntax — do not reserialize the whole file through
+`JSON.parse`/`JSON.stringify`, this is a `.ts` module, not JSON; a plain text insert keeps every
+other entry byte-identical):
+```ts
+"UserList.DISPLAYED_ROWS": {
+  "de": "{{from}}–{{to}} von {{count}}",
+  "fr": "{{from}}–{{to}} sur {{count}}",
+  "en": "{{from}}–{{to}} of {{count}}",
+  "sw": "{{from}}–{{to}} ya {{count}}"
+},
+"UserList.DISPLAYED_ROWS_MORE_THAN": {
+  "de": "{{from}}–{{to}} von mehr als {{to}}",
+  "fr": "{{from}}–{{to}} sur plus de {{to}}",
+  "en": "{{from}}–{{to}} of more than {{to}}",
+  "sw": "{{from}}–{{to}} ya zaidi ya {{to}}"
+}
+```
+The `sw` wording reuses "ya" for "of"/possessive, already used this way elsewhere in the same file
+(e.g. l.57 `"ruhusa ya kutuma mialiko"`, l.114 `"barua pepe ya kuweka upya"`) and "zaidi ya" ("more
+than") as a plain compositional phrase — a reasonable best-effort construction, NOT a
+native-speaker-verified translation; say so plainly in your own report rather than presenting it as
+settled, same as you would for any other claim you can't independently verify.
+
+Call site becomes:
+```jsx
+labelDisplayedRows={({ from, to, count }) =>
+  count === -1
+    ? t('UserList.DISPLAYED_ROWS_MORE_THAN', '{{from}}–{{to}} of more than {{to}}', { from, to })
+    : t('UserList.DISPLAYED_ROWS', '{{from}}–{{to}} of {{count}}', { from, to, count })
+}
+```
+
+### Existing test harness to extend, not duplicate
+
+`tests/userScreenTranslations.test.jsx` already renders `UserListComponent` through a REAL
+`i18next` instance pinned to German (`withGermanI18n`, ~l.22-30, built from
+`authTranslations.*.de`) and asserts rendered German strings plus `expectNoEnglishDefaults()`
+(~l.34-39, checks `document.body.textContent` against an `ENGLISH_DEFAULTS` list, ~l.33-46). The
+test `'renders UserListComponent in German, including pagination and action feedback'` (~l.97-125)
+already fetches exactly 1 user, so the pagination currently renders English "1–1 of 1" — add that
+literal string (or your chosen German text) to the existing `for (const german of [...])` loop
+(~l.115) to assert the real rendered pagination text, and add the English range phrasing (e.g.
+`'of 1'` or similar, whatever actually changes) to `ENGLISH_DEFAULTS` so `expectNoEnglishDefaults()`
+(already called at line 124) starts actually catching a regression here — today it does NOT, since
+no "of N" string is in that list, which is why this bug shipped unnoticed.
+
+Required test 1 (German vs English) is naturally satisfied by extending this file: German via the
+existing `withGermanI18n` harness, English via a parallel small i18next instance (or reuse the
+`en` resources the same way `germanResources` is built from `.de`) rendering the same component and
+asserting the English range text.
+
+Required test 2 (key-parity across all four locales) — check whether a generic "every key has
+every locale" structural test already exists in this repo (grep `authTranslations` test files for
+something like `Object.values(...).every(...)` or a locale-set check) before writing a new one;
+extend it if so, add a small standalone one for just these two new keys if not.
+
+## Target repo working directory (absolute)
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`)
+
+## Preamble — a REQUIRED block IN this file, not something appended at invocation
+
+> 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 edit `WORK_ORDERS.md` — the register
+> row and the review verdicts are the orchestrator's alone.** **Your tools are for editing source
+> and test files and for running the tests you wrote — nothing else.** Do NOT install dependencies,
+> touch a lockfile, run a package manager, or tidy up stray files; if something in the repo state
+> blocks you, stop and report it as `RESULT: BLOCKED <reason>` instead of fixing it. 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>`.
+
+---
+
+# 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.**
+
+**Execution directive:** dispatch via `codex exec --skip-git-repo-check
+--dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna - < work-orders/UCM-I18N-5.md` (today,
+2026-10-02, already recorded `available` in `webapps/.claude/codex-status.md`), cwd =
+`C:\Users\biglmi\Documents\webapps\ui-core-micha`. Monitor for `RESULT: DONE|BLOCKED`.
+
+**Review routing:** Tier 3 (shared-core) — full `reviewer` lens set (`envelope`, `regression`,
+`duplication`, `tests`, codex/gpt-5.6-luna, one concurrent batch, diff inline) PLUS `ui_reviewer`
+(frontend-adjacent: a rendered component's i18n text). `duplication` should specifically check
+whether any OTHER app already patched around this same MUI default locally (a local workaround that
+this shared-core fix should make redundant, worth naming even if out of this WO's scope to remove).
+
+**Tests:** the Orchestrator re-runs `tests/userScreenTranslations.test.jsx` (and any new/renamed
+key-parity test file) as the gate — not ucm's full suite (Tier 3 but a small, local-only change;
+no cross-app ripple to justify a full run per `AGENTS.md` → Test scope).
+
+**Release:** patch bump (3.11.0 → 3.11.1) — this extends `UCM-I18N-4`'s existing i18n-gap category
+in the same component, not a new capability area, per the project convention (version bump reflects
+scope, not mere newness). Update `package.json` + `CHANGELOG.md`, then the repo's normal publish
+path (check `.github/workflows/` or `package.json` scripts for how a previous release like
+`UCM-THEME-14`/3.11.0 or `UCM-AUTH-11`/3.9.1 actually published, don't assume `npm publish` by
+hand — follow the established mechanism).
+
+**jg-ferien pin bump:** after the release is live, bump `ui-core-micha`'s pin in
+`jg-ferien/frontend/package.json`, install, run jg-ferien's own affected tests (anything touching
+`UserListComponent` consumption, if jg-ferien renders it at all — check first; if jg-ferien doesn't
+use `UserListComponent`, the pin bump itself plus jg-ferien's existing suite staying green is the
+evidence), commit + push to jg-ferien's `develop`.
+
+**Register:** `done` only once BOTH halves land — the release AND the jg-ferien pin bump (the WO's
+own Tier line: "Done means released AND jg-ferien's pin bumped"). Row here (ui-core-micha's
+`WORK_ORDERS.md`) AND a row in jg-ferien's own `WORK_ORDERS.md` noting the pin bump, per the
+Envelope's own closing instruction.
+
+**Commit:** ui-core-micha lands on `main` (no `develop` branch here, confirmed in `AGENTS.md`'s
+branch table). jg-ferien's pin bump lands on `develop` as usual.

package/work-orders/UCM-THEME-14.md

@@ -14,9 +14,38 @@ both of its themes through the factory.
 
 ## Value source
 
-**`docs/DARK-TOKENS.md`, frozen by the operator in `UCM-THEME-13`.** Every dark value in code comes
-from that sheet. A value the implementation needs that the sheet does not carry is a stop-and-report.
-Do not improvise it.
+**`docs/DARK-TOKENS.md`, frozen by the operator in `UCM-THEME-13` (2026-10-02, `7330f91`).** Every dark
+value in code comes from that sheet. A value the implementation needs that the sheet does not carry is a
+stop-and-report. Do not improvise it.
+
+## Decided rules (operator, 2026-10-01 and 2026-10-02; amended into this order 2026-10-02)
+
+1. **Complete baseline.** Every mode-dependent token class has its dark value from the sheet, including
+   `ink.*`, `text.*`, `background.default/paper/subtle`, `divider`, `controlBorder.*`, all five status keys
+   (`main/light/dark/contrastText` via `withMainShades`, plus `text/fill/fillText/bg`), `dataSeries` and
+   `shadow.*`.
+2. **Outlined first, as in light.** Resting surfaces keep `shadow.rest: none`. **Overlays get their own,
+   lighter surface in dark**: the sheet's overlay surface (`#232A31`) is the paper of `MuiDialog`,
+   `MuiMenu`, `MuiPopover` and `MuiDrawer` in dark, with the sheet's overlay shadow; the modal backdrop
+   (`MuiBackdrop`) uses the sheet's scrim. Light has no such surface and does not change.
+3. **Primary in dark: derived only when it fails.** An app always passes `palette.primary` (the factory
+   requires it). In dark, that value is kept if it clears 4.5:1 on the dark page, and otherwise lightened in
+   0.05 steps until it does. Its `contrastText` is whichever of `#FFFFFF` and the dark page colour
+   contrasts more. This is how "derived unless the app sets its own" is expressed in an API where every
+   app sets one: an app that wants a particular dark primary passes one that already clears the floor
+   (webshop-guenter `#D49040`, 7.35:1, stays). Worked examples are in the sheet.
+4. **Status safety net, the dark counterpart of `UCM-THEME-15`.** On a dark page other than the baseline
+   page, a **baseline-supplied** status `main` (and `controlBorder.error`) that would fail against the page or
+   its own `bg` is lightened until it passes. App-supplied values are never altered (`UCM-THEME-15` rule 3,
+   read per key off `appConfig.palette`). Never throws; capped like the darkening.
+5. **Data series follow a rule, not only a list.** In dark, each light series colour is lightened until it
+   clears 3:1 on the theme's own `background.paper`. On the baseline paper that yields exactly the sheet's
+   list; on an app's own paper (webshop-guenter `#171209`) it adapts.
+6. **Contrast surfaces are the theme's own.** In dark, every derivation and `contrastFindings` judge against
+   the theme's page and paper, never a fixed `#FFFFFF`. Light keeps today's pair.
+7. **Autofill needs no new code path.** The palette-aware block (`src/theme/createAppTheme.js:97-108`)
+   already resolves from `background.paper` and `ink.primary` and wins over the static light block in
+   `tokens.js`. It is correct in dark once the dark palette is in place; confirm it in a test.
 
 ## Context the operator established
 
@@ -32,7 +61,10 @@ Do not improvise it.
 - `BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS` includes `palette.background.paper` with the reason "The
   canonical surface is deliberately MUI white". That reason is false for a dark theme.
 - The palette-aware slots use palette values (for example the autofill inset uses `background.paper`),
-  so they follow the resolved palette once it is right.
+  so they follow the resolved palette once it is right. `tokens.js` also carries a static light `autofill`
+  block (`#FFFFFF`, `#212529`); it is shadowed by the palette-aware one (measured 2026-10-02).
+- `UCM-THEME-15` (3.8.0) added `deriveDarkenedPageColour`/`deriveAlphaPageColour` next to
+  `deriveFocusColour`; the dark branch extends those, it does not add a parallel set.
 - The kit has components registered against the baseline (`src/theme/kitSxRegistry.js`, `THEME-4`/
   `THEME-5`). A kit component that hard-codes a light value would show that value only in dark mode.
 
@@ -42,7 +74,9 @@ In scope:
 1. `tokens.js`: a dark baseline palette with the sheet's values, and whatever exemption entries a
    dark theme needs, each with a true reason.
 2. `createAppTheme`: select the baseline palette by `palette.mode`. Make the focus derivation work in
-   both directions against the mode's surfaces.
+   both directions against the mode's surfaces. Rules 2 to 6 above: the overlay surface, scrim and overlay
+   shadow on the four overlay components in dark; the primary derivation; the status safety net; the
+   series rule.
 3. `themeCompleteness.js`: contrast checks against the theme's own surfaces, not a fixed white. Mode-
    specific exemptions.
 4. Kit components that resolve a hard-coded light value instead of a token: **list** every one.
@@ -76,6 +110,11 @@ Non-goals:
   derived by darkening, both fail on dark.
 - **The `background.paper` exemption reason is currently mode-blind.** Leaving it would record a false
   statement as the reason in every dark theme.
+- **Rule 3 cannot keep a dark primary that fails the floor.** An app that deliberately wants one gets it
+  lightened. That is intended (an accessibility floor), not a defect.
+- **Two sheet values sit close to their threshold** (`controlBorder.main` 3.14:1 on paper, series slot 1
+  3.07:1). Build them from the rules, not as literals, so a later paper change re-derives instead of
+  silently failing.
 
 ## Required tests to WRITE (you write them and run YOUR OWN new ones; the Orchestrator's run is the gate)
 
@@ -91,6 +130,18 @@ Kit test suite, narrow, next to the existing theme tests:
 3. **Focus contrast.** `controlBorder.focus` clears 3:1 against both page surfaces in each mode.
 4. **Status family on dark.** Each status key resolves `main/light/dark/contrastText` from the dark
    baseline, not MUI's defaults.
+5. **Primary in dark (rule 3).** On the baseline dark page: `#468AB2` stays, `#2F4F96` resolves to
+   `#6D84B6`, `#432CA1` to `#8576C2`, each with `#14181B` as `contrastText`; `#D49040` stays.
+6. **Status net (rule 4).** On webshop-guenter's page `#0E0B08` no baseline status colour moves; on a
+   page chosen so that one fails, that one is lightened and passes; an app-supplied status `main` that
+   fails stays exactly as supplied.
+7. **Overlay surface (rule 2).** In dark, the paper of `MuiDialog`, `MuiMenu`, `MuiPopover` and `MuiDrawer`
+   resolves to the sheet's overlay surface and `MuiBackdrop` to its scrim; the light theme's values for
+   the same slots are unchanged (covered by test 1).
+8. **Series rule (rule 5).** On the baseline paper the dark series equal the sheet's list; on
+   `#171209` every slot clears 3:1.
+9. **Autofill (rule 7).** In dark, the resolved autofill inset is the dark paper and the text is
+   `ink.primary`.
 
 Run, do not write: the kit's existing theme and `kitSxRegistry` tests.
 
@@ -103,9 +154,128 @@ branch.
 
 # B. Implementation map, filled by the Orchestrator and ADDRESSED TO THE IMPLEMENTER
 
-*Placeholder. The Orchestrator fills the context package, the absolute working directory, the
-progress contract and the preamble block on `git pull`, per `AGENTS.md` -> "Work Order". Do not
-dispatch while this placeholder stands, and not before `UCM-THEME-13` is frozen.*
+Work from this package; do not explore broadly from scratch; open only the named files to verify. If
+you must dig deeper, delegate to a read-only Explore sub-agent.
+
+## Target working directory (absolute)
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`). Never the workspace root.
+
+## Context package
+
+Value source for every dark value: `docs/DARK-TOKENS.md` (read it fully first). Do not invent a value;
+one the sheet lacks is `RESULT: BLOCKED <value>`.
+
+**`src/theme/tokens.js`**
+- `BASELINE_PALETTE` (l.~52-123) is the light baseline. Add `BASELINE_PALETTE_DARK` next to it with the
+  same shape, every key from the sheet: `ink`, `text`, `background`, `divider`, `controlBorder`
+  (`main`/`hover`/`error`), the five status keys (use `withMainShades(main, '#14181B')` for
+  success/warning/error/info, plus `text`/`fill`/`fillText`/`bg`; `stale` has no `main`, as in light),
+  `dataSeries.categorical`. Do NOT hardcode series slots 1 and 5, `controlBorder.main/hover`, or the
+  primary as literals: those are rule-derived (see below); the sheet's numbers are the expected OUTPUT.
+  The dark `dataSeries` base is the light `SERIES_COLOURS`, lightened by the factory.
+- Export a dark overlay surface (`#232A31`), a dark overlay shadow (`0 8px 28px rgba(0,0,0,.45)`) and the
+  scrim (`rgba(0,0,0,.55)`) as named constants.
+- `BASELINE_STATIC.shadow` (~l.200) carries `rest`/`overlay`; the dark theme needs the dark overlay value
+  there. `BASELINE_STATIC.components` has static `MuiDialog.paper`/`MuiDrawer.paper`/`MuiMenu.paper`
+  boxShadow `OVERLAY_SHADOW` (~l.340-355): in dark these are overridden, never edited for light.
+- The static light `autofill` block (~l.147) is shadowed by the palette-aware one; leave it, confirm by test.
+- `BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS` (end of file): the `palette.background.paper` entry says "MUI
+  white". Provide the list by mode: in dark, drop that entry (the dark paper differs from MUI's default, so
+  no exemption is needed), keep the others. The light list stays byte-identical.
+
+**`src/theme/createAppTheme.js`**
+- `createAppTheme` (l.~176): the three-layer `createTheme(app, BASELINE_PALETTE, app)` resolution. Read
+  `appConfig.palette.mode`; `'dark'` selects `BASELINE_PALETTE_DARK` and passes `mode: 'dark'` through to the
+  theme; anything else is the unchanged light path. Do not read `prefers-color-scheme`.
+- `contrastSurfaces = ['#FFFFFF', background.default]` (l.~186): in dark this must be the theme's own
+  `[background.default, background.paper]`; light stays exactly `['#FFFFFF', default]`.
+- `deriveFocusColour`/`clearsContrast` (l.~48-60) only darken and use MUI `getContrastRatio`. In dark add a
+  lightening counterpart (lighten in 0.05 steps, same 0.9 cap) alongside, not a rewrite. Same for
+  `deriveDarkenedPageColour`: add a lightened sibling next to it. For dark `controlBorder.main/hover`:
+  `rgba(230, 235, 239, a)` from `ink.primary`, `a` = the smallest alpha (0.01 steps) that clears 3:1 on
+  page and paper, hover = main + 0.15; the sheet's 0.38 / 0.53 are the expected result.
+- Rule 3 (primary), rule 4 (status net: baseline-supplied status `main` and `controlBorder.error`, judged
+  against page AND its own `bg`, lightened; per-key check off `appConfig.palette` exactly as the existing
+  light loops do), rule 5 (series: each baseline light series colour lightened in 0.05 steps until it clears
+  3:1 on the theme's own `background.paper`; app-supplied series untouched, the final merge argument already
+  lets them win), rule 6 (own surfaces) are all computed here, dark branch only. Primary `contrastText` =
+  whichever of `#FFFFFF` / `background.default` contrasts more. The app may pass `primary` as `{ main }`.
+- `createPaletteAwareComponents(palette)` (l.~84): add dark-only overlay slots: `MuiDialog`, `MuiMenu`,
+  `MuiPopover`, `MuiDrawer` `paper` -> background colour = overlay surface `#232A31`, `boxShadow` = dark
+  overlay shadow; `MuiBackdrop.root` -> scrim. Keep the overlay surface a local constant unless a palette
+  key is clearly cleaner and trips no completeness check. Emitted only when mode is dark, so the light
+  component tree is untouched.
+- Preserve the final merge order (BASELINE_STATIC, palette-aware components, `appConfig`, the dataSeries
+  re-merge). The dark theme's `shadow.overlay` = the dark value.
+
+**`src/theme/themeCompleteness.js`**
+- `contrastFindings` (l.~268-345): `backgrounds = { white: '#FFFFFF', page: default }` (~l.298). In dark use
+  the theme's own page and paper instead of a fixed white. Light keeps the exact same keys
+  (`...-on-white`, `...-on-page`) and values; existing tests assert those surface names. For dark name them
+  `...-on-paper` / `...-on-page`.
+- `assertThemeComplete` (~l.620): `MUI_DEFAULT_THEME` is the light MUI default. Verify a dark theme neither
+  produces a false "still MUI default" finding nor a false pass; fix only what is wrong.
+
+**Kit components with hard-coded light values:** `src/components/QrSignupManager.jsx` has an inline CSS
+block (l.~225-274: `#f5f7fb`, `#122033`, `#d9e2f2`, `#ffffff`, `#e8f0ff`, `#23408e`, `#f8faff`) and
+`bgcolor: '#ffffff'` at l.361. **The l.361 white is a QR quiet zone and stays.** List every hard-coded
+light colour under `src/` outside `src/theme/` and tests in your final report. Switching one to an existing
+palette token is in scope (check its consumers and `tests/QrSignupManager.registrationContext.test.jsx`
+first); a spot that would need a new token is reported, not built. `src/auth/UserMenu.jsx:44` and
+`src/components/charts/chartLabels.js` only mention colours in comments.
+
+**Docs / release:** `DESIGN.md` gets a concise dark-mode section (how to opt in, primary rule, status net,
+overlay surface, series rule, what an app owns in dark). `CHANGELOG.md` entry. `package.json` version
+`3.10.0` -> `3.11.0` (and `package-lock.json` where the version appears for this package).
+
+**Existing tests to follow** (style, imports): `tests/createAppTheme.test.js`,
+`tests/createAppThemePageContrast.test.js` (imports `assertThemeComplete`, `createAppTheme` from
+`../src/theme`), `tests/themeCompleteness.test.js`. New dark tests go in `tests/createAppThemeDark.test.js`,
+the light guard in `tests/createAppThemeLightGuard.test.js`.
+
+**Light regression guard (required test 1):** BEFORE editing any source, capture the output of
+`createAppTheme({ palette: { primary: { main: '#0F62FE' } } })` and of one overriding app config (fontFamily,
+a custom page background, an app-supplied status main) as a JSON fixture
+(`tests/fixtures/light-theme-baseline.json`, stable serialization, functions as strings), from the
+unmodified code, and assert equality afterwards. Prove it can fail: one test mutates a light value in a
+clone of the snapshot and asserts the comparison reports a difference.
+
+**Invariants / pitfalls**
+- Light output byte-identical: no key-order change that alters serialization, no new keys on the light theme.
+- Only the first `createTheme` argument is augmented (comment at the top of `tokens.js`): every status
+  entry needs explicit `main/light/dark/contrastText`.
+- MUI `getContrastRatio` vs the kit's alpha-aware `calculateContrastRatio`: use the kit's for anything with
+  alpha, as THEME-15 did.
+- Build `controlBorder.main/hover`, the series and the primary from the rules, not literals; the tests
+  assert the rules reproduce the sheet's values.
+- Do not touch auth, CI, dependencies, `WORK_ORDERS.md`, or `docs/DARK-TOKENS.md` (read-only here).
+
+## Required tests, restated
+
+The nine tests of Part A, in the new files named above. Run only the tests you wrote.
+
+## Preamble
+
+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 edit `WORK_ORDERS.md`: the register row and the review
+verdicts are the orchestrator's alone.** **Your tools are for editing source and test files and for running
+the tests you wrote, nothing else.** Do NOT install dependencies, touch a lockfile (the version line in
+`package-lock.json` is the one exception, a plain text edit), run a package manager, or tidy up stray
+files; if something in the repo state blocks you, stop and report it as `RESULT: BLOCKED <reason>` instead
+of fixing it. 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
+affected/full suite, NOT any review). Run them with `npx vitest run <your test files>`. The orchestrator
+re-runs the authoritative set and does the independent review after you finish; those are 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>`. Your final report must also list every hard-coded light colour found under
+`src/` outside the theme folder.
 
 ---