@micha.bigler/ui-core-micha 3.9.1 → 3.11.0

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

@@ -0,0 +1,80 @@
+# 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
+
+*(placeholder — no context package yet, no progress contract yet; the Orchestrator fills this
+part on `git pull` and appends the preamble below to the invocation. Do not dispatch on this
+placeholder.)*
+
+## 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.**
+
+*(to be filled by the Orchestrator: execution directive; `reviewer` (all lenses) + `ui_reviewer`; release; jg-ferien pin bump; register rows here and in jg.)*

package/work-orders/UCM-TEST-1.md

@@ -0,0 +1,304 @@
+# UCM-TEST-1: A kit integration check every app runs in its own suite
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+The kit's auth screens are the same code in every app, so their behaviour is accepted once, in the kit.
+What differs per app is **how the app wires the kit in**: its i18n setup, its providers around the kit's
+pages, the `i18next` instance the kit reads. Today each bump order writes its own tests for that, app by
+app, and the operator walked the same auth flows by hand in every app.
+
+After this order the kit ships **one exported check**, `checkKitIntegration`, that an app calls from a
+single test in its own suite. It returns findings in the style of `assertThemeComplete`: an empty list
+means the app's wiring is sound. Every later bump in every app then re-checks the wiring automatically.
+
+**Operator decisions (2026-10-01):** the check lives centrally in the kit, not as copies per app; a
+separate, automated staging smoke covers the runtime (`workflow-templates` `WFT-CI-31`); bumps already
+in flight are not held up, and apps adopt the check with their next bump.
+
+## Context the operator established
+
+- **Precedent for the shape:** `assertThemeComplete(theme)` returns `{ findings }`, is exported from the
+  package root (`src/index.js:12`), and apps assert `findings` equals `[]`.
+- **What apps load from the kit for i18n:** `uiCoreTranslations` (`src/i18n/uiCoreTranslations.js`),
+  which spreads the auth, charts, messaging, notifications, onboarding, section-nav and user-menu
+  catalogues. Apps spread it into their own i18next resources at start-up, **kit keys last** (e.g.
+  `survey_app/frontend/i18n/index.js`).
+- **Which `i18next` the kit reads:** `apiClient` imports the **default** `i18next` instance
+  (`src/auth/apiClient.jsx:2,13`) to send `Accept-Language`. Kit components read `t` and `i18n` from
+  `useTranslation()` (e.g. `src/pages/LoginPage.jsx:30`). `i18next`/`react-i18next` are peer
+  dependencies.
+- **What the per-app bump orders tested by hand** (`survey_app` `SVA-DEP-1`/`SVA-DEP-2`): the kit's
+  `SignUpPage` and `PasswordInvitePage` render inside the app's providers
+  (`survey_app/frontend/src/AuthRoutesIntegration.test.jsx`), and `i18n.exists('Auth.field.email.invalid')`
+  holds in the app's own i18n.
+- **The defect this guards against end to end:** a login with a malformed e-mail showed the raw code
+  `invalid` (`UCM-AUTH-10`). The kit's resolver fixes it, but only if the app's i18n carries the kit's
+  keys and the kit's pages run on the app's instance.
+- **Consumers measured 2026-09-30:** every consumer runs `vitest` with jsdom. Some mount `LoginPage`
+  twice (`webshop-guenter` also in `src/pages/pwa/StaffLoginPage.jsx`). Several mock `react-i18next`
+  globally in some test files.
+
+## The check (decided)
+
+`checkKitIntegration({ i18n, wrapper, pages })` -> `Promise<{ findings }>`, exported from the package
+root. `i18n` is the app's own instance, `wrapper` the app's own provider component (whatever the app
+puts around its routes), `pages` the kit pages the app mounts (default: the kit's auth pages that the
+app imports). Each finding names its check and a reason. Four checks:
+
+1. **Catalogue.** Every key in `uiCoreTranslations` resolves through the app's `i18n` in every language
+   that both the kit ships (`de`/`en`/`fr`/`sw`) and the app supports. A missing key is one finding,
+   with key and language.
+2. **Instance.** The default `i18next` instance is initialised and is the instance the app passed in.
+   Otherwise the finding says what will break: `Accept-Language` is missing or wrong.
+3. **Render.** Each page in `pages` renders inside `wrapper` without throwing, and no rendered text
+   node is a raw kit key (`Auth.*` or another key of the kit's catalogues) or a bare backend code. The
+   check stubs the kit's `apiClient` transport for its own duration, so no request leaves the test, and
+   restores it afterwards.
+4. **Error text.** `LoginPage` inside `wrapper` receives, through that stub, exactly the allauth response
+   from the original defect (`400`, `errors[0] = {code: "invalid", param: "email", message: ...}`). The
+   shown text equals the app-language text of `Auth.field.email.invalid`.
+
+## Scope + non-goals
+
+In scope: the function and its four checks; its export from the package root; a `README.md` section
+"Consumer integration check" with the one-line test an app writes; `CHANGELOG.md`; a **minor** release.
+
+Non-goals:
+- No change in any app. Adoption happens per app with its next bump, as its own row.
+- No runtime dependency added for consumers. Rendering uses the existing peers (`react`, `react-dom`).
+- No check of the app's test mocks. A suite whose mocks lack `i18n` still fails in that suite, as today.
+- No replacement for the kit's own tests. They keep owning the kit's behaviour.
+- No staging or browser check (`WFT-CI-31`).
+
+## Tier · precondition / gate
+
+- **Tier 3 · tests: each of the four checks with a passing and a failing case; the kit's existing auth
+  and i18n tests.** A change inside shared-core, on the auth surface.
+- Precondition: none.
+- Downstream: every app adopts it with its next kit bump. `WFT-CI-31` is independent of this order.
+
+## Risks
+
+- **A check that cannot fail is decoration.** Each check needs a test showing it reports the specific
+  defect: a missing key, a second `i18next` instance, a wrapper that throws, a raw code on screen.
+- **The transport stub must not leak.** If it is not restored, it silently swallows the requests of the
+  tests that run after it. Restore it even when a check throws.
+- **Kit keys that the app intentionally leaves untranslated** for a language it does not offer must not
+  become findings. Hence "languages both support" in check 1.
+- **Locally, importing the kit's root module crashes vitest's worker pool on this workstation**
+  (`fitness-monitor` `FM-15`). That is an environment issue: CI is the evidence. The check itself must not
+  add to the import weight of tests that do not call it.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the Orchestrator's run is the gate)
+
+Kit test suite, one new file:
+
+1. A correctly wired fixture app (own `i18n` with `uiCoreTranslations`, a provider wrapper) -> `findings`
+   equals `[]`.
+2. One key removed from the fixture's resources -> exactly one catalogue finding naming that key and
+   language.
+3. The fixture passes a separate `i18next` instance -> an instance finding.
+4. A wrapper that throws -> a render finding naming the page.
+5. The resolver bypassed (a fixture that shows `err.code`) -> an error-text finding.
+6. After the check, a request through `apiClient` is no longer stubbed.
+
+Run, do not write: the kit's existing auth and i18n tests.
+
+## Parity guardrail
+
+No change to any existing export, component or behaviour. The function is new and test-only in purpose.
+
+---
+
+# B. Implementation map, filled by the Orchestrator and ADDRESSED TO THE IMPLEMENTER
+
+## Context package
+
+### Where this lives, and what it may depend on
+
+- New file `src/testing/checkKitIntegration.js` (new subdirectory, mirroring how `src/theme/` groups
+  `assertThemeComplete`). Export `checkKitIntegration` from `src/index.js` at the root, next to the
+  existing theme-completeness exports (line ~10-21) — same section-style comment, same pattern.
+- **Hard constraint from the Non-goals: "Rendering uses the existing peers (react, react-dom)" —
+  this explicitly does NOT include `@testing-library/react`.** Every existing kit test uses RTL, but
+  RTL is a devDependency of THIS repo, not a declared peer dependency — if the shipped function
+  imported it, every consuming app would need RTL in its own `node_modules` at the exact version
+  this kit expects, silently, which is exactly the "no runtime dependency added for consumers" this
+  WO forbids. Render with plain `react-dom/client` (`createRoot`) and `act` from `react` — verified
+  now: `import { act } from 'react'` resolves and is a function on this repo's installed React
+  `19.2.6` (`node -e "console.log(typeof require('react').act)"` → `function`), so use that import,
+  not the legacy `react-dom/test-utils` path. Read rendered output via plain
+  DOM (`container.textContent`, `document.createTreeWalker`), not `screen`/`within`.
+- `react-router-dom` (`^7.15.1`) and `axios` (`^1.16.1`) ARE existing peers — safe to import
+  `MemoryRouter` and to manipulate the shared `apiClient` axios instance directly.
+
+### The four checks, in the order the Envelope lists them
+
+1. **Catalogue.** Import `{ uiCoreTranslations }` from `'../i18n/uiCoreTranslations'`. For each key,
+   for each language in the INTERSECTION of the kit's shipped languages
+   (`['de','en','fr','sw']`) and the app's own supported languages, assert
+   `i18n.exists(key, { lng: lang })` — **not** `i18n.exists(key)` alone, which only checks the
+   CURRENT active language; i18next's `exists`/`t` both accept an `lng` option to check a specific
+   language without switching the instance's active one (verify this against the installed
+   `i18next` version's own typings/source before relying on it — do not assume from memory).
+   Derive "the app's own supported languages" with this priority (first one that yields a
+   non-empty array): `i18n.options?.supportedLngs` (filter out falsy entries and the literal
+   string `'cimode'`, which i18next auto-adds) → `Object.keys(i18n.options?.resources || {})` →
+   `i18n.languages` (least reliable, only the currently-resolved fallback chain — last resort).
+   One finding per missing `(key, lang)` pair, naming both.
+2. **Instance.** Import the kit's OWN default `i18next` singleton (`import i18next from 'i18next'`
+   — the exact same import `src/auth/apiClient.jsx` already uses). Finding if `!i18next.isInitialized`
+   OR `i18n !== i18next` (reference inequality — the whole point is catching an app that created a
+   SEPARATE instance via `i18next.createInstance()` and wrapped its tree in its own
+   `I18nextProvider`, which is exactly the Risk `UCM-AUTH-10` named: the kit's `apiClient` would then
+   send `Accept-Language` from an uninitialized, different instance). Name what breaks in the
+   reason text (`Accept-Language` will be missing or wrong) — do not just say "mismatch".
+3. **Render.** For each page component in `pages` (default: `[LoginPage, SignUpPage,
+   PasswordInvitePage]` — the three pages `UCM-AUTH-9`/`UCM-AUTH-10` actually touched, and the same
+   set `survey_app`'s own `AuthRoutesIntegration.test.jsx` already covers by hand), render
+   `<MemoryRouter><Wrapper><Page /></Wrapper></MemoryRouter>` into a fresh detached `div` (own
+   `createRoot` per page, `root.unmount()` after each, even on failure — use try/finally per page,
+   not one try around the whole loop, so one page's render failure doesn't skip scanning the rest).
+   Wrap the render in `act(async () => { ... })` so effects/microtasks settle before you scan.
+   Catch a throw during render → one finding naming the page's display name (`Page.displayName ||
+   Page.name || 'page'`) and the error message; do NOT let it abort the whole check (catch per-page,
+   continue the loop). If it didn't throw, walk every text node
+   (`document.createTreeWalker(container, NodeFilter.SHOW_TEXT)`) and flag any whose TRIMMED content
+   either (a) exactly equals a key in `uiCoreTranslations` (a literal untranslated key leaking to
+   screen — the i18next missing-key echo), or (b) matches a bare lowercase/snake_case single-token
+   shape with no spaces, e.g. `/^[a-z][a-z0-9_]*$/` and length > 2 (the exact shape of the original
+   defect, a raw backend code like `invalid` — tune this pattern against Required Test #5's fixture
+   until it fires on that fixture and not on ordinary rendered prose; do not accept the first regex
+   that merely compiles). One finding per offending text node, naming the page and the text found.
+4. **Error text.** This check is not driven by the `pages` array — it ALWAYS specifically exercises
+   `LoginPage` (imported directly by this module), because it is testing the kit's resolver wiring
+   through a real submit flow, not generic rendering. Render `LoginPage` the same way as check 3.
+   Stub the credentials-login POST specifically — exact path, verified now:
+   `/api/auth/browser/v1/auth/login` (`src/auth/authConfig.jsx`'s `HEADLESS_BASE` +
+   `src/auth/authApi.jsx:99`'s `loginWithPassword`) — to reject with EXACTLY
+   the operator's original defect shape:
+   `{ response: { status: 400, data: { errors: [{ code: 'invalid', param: 'email', message: '<some
+   backend text>' }] } } }` (a plain object is sufficient — `resolveErrorText`/`extractErrorInfo`
+   only ever read `.response?.status`/`.response?.data` off the rejected value, nothing
+   AxiosError-specific). Fill the email/password inputs via plain DOM (`input.value = '...'` +
+   dispatching a real `input`/`change` `Event` so React's controlled-input `onChange` fires —
+   `Object.getOwnPropertyDescriptor` trick may be needed to set a native input value in a way React
+   notices; this is a well-known React-testing gotcha independent of any test-utility library, look
+   it up if the naive `input.value = x; input.dispatchEvent(new Event('input'))` doesn't trigger the
+   controlled state update) and submit (dispatch a `submit` Event on the form, or `.click()` the
+   submit button). `await act(async () => { ...await flush... })` until the error text renders.
+   Assert the rendered text equals `i18n.t('Auth.field.email.invalid')` evaluated in the APP's
+   current active language (`i18n.language`), read via the SAME walk-and-scan helper check 3 uses
+   (do not duplicate the scanning logic — factor it into one shared helper both checks call).
+
+### Stubbing `apiClient` — must never leak, must restore even on throw
+
+`apiClient` (`src/auth/apiClient.jsx`, default export, an axios instance) is shared, module-singleton
+state — the SAME instance every kit page uses. Capture `const originalAdapter =
+apiClient.defaults.adapter;` BEFORE check 3 starts, install a replacement
+(`apiClient.defaults.adapter = async (config) => { ... }`) that, by default, REJECTS every request
+(so check 3's page renders — which must not make real network calls at all — fail loudly if they
+accidentally do, rather than hanging on a real fetch), and for check 4 specifically, additionally
+matches on `config.url` to return the fixture rejection ONLY for the login endpoint
+(`HEADLESS_BASE`-relative, check `src/auth/authApi.jsx`'s `loginWithPassword` for the exact path) and
+the default reject-everything behaviour for anything else. **Wrap the ENTIRE checks 3+4 body in a
+`try { ... } finally { apiClient.defaults.adapter = originalAdapter; }`** — the restore must run even
+if a render throws an error this code doesn't catch, even if an `expect`-shaped helper you write
+itself throws. This is Required Test #6's whole point and the Risk note's explicit warning.
+
+### `README.md` — "Consumer integration check" section
+
+One short section with the one-line test an app writes, e.g.:
+```js
+import { checkKitIntegration } from '@micha.bigler/ui-core-micha';
+import i18n from '../i18n'; // the app's own initialised default i18next instance
+import { AppProviders } from '../AppProviders'; // whatever the app wraps its routes in
+
+it('kit integration is sound', async () => {
+  const { findings } = await checkKitIntegration({ i18n, wrapper: AppProviders });
+  expect(findings).toEqual([]);
+});
+```
+Name the default `pages` set explicitly (`LoginPage`, `SignUpPage`, `PasswordInvitePage`) and that an
+app can pass its own `pages` array to cover more/fewer pages.
+
+### Test file — new, next to the existing kit tests (e.g. `tests/checkKitIntegration.test.js`)
+
+Build ONE minimal fixture i18next instance + a trivial `Wrapper` (e.g. just renders `children`, or a
+thin `AuthContext.Provider` with a fake user so `LoginPage`'s own context read doesn't throw) reused
+across the 6 Required Tests, each test mutating ONE thing away from "correctly wired":
+1. Correctly wired fixture (own real `i18next.createInstance()` seeded with `uiCoreTranslations` in
+   all 4 kit languages, THIS instance also assigned as the global default — i.e. do not create a
+   second competing instance for the "passing" case, since check 2 would then always fail; for a
+   realistic "app's own instance IS the default" fixture either call `i18next.init(...)` on the
+   real default singleton directly, matching how an app actually does it, or structure the fixture
+   so the "instance" check specifically is satisfiable) → `findings` is `[]`.
+2. Remove one key's resources for one language from the fixture → exactly one catalogue finding
+   naming that key and language.
+3. Pass a SEPARATE `i18next.createInstance()` as `i18n` instead of the default singleton → an
+   instance finding.
+4. A `wrapper` that throws during render → a render finding naming the page.
+5. **The actual regression proof:** stub the login POST to reject with the operator's exact shape
+   but WITHOUT going through the kit's resolver (simulate "the resolver bypassed" by using a fixture
+   `LoginPage`-equivalent harness only if you must — more directly: this is best proven by reverting
+   `resolveErrorText`'s field-key step locally, confirming check 4 then reports an error-text
+   finding instead of passing, then restoring — narrate this in `PROGRESS` as the transient
+   mutation proof, same pattern as `UCM-AUTH-11`/`UCM-THEME-15` in this repo, rather than leaving a
+   permanently reverted copy in the committed suite).
+6. After calling `checkKitIntegration(...)` once, assert `apiClient.defaults.adapter` is back to
+   whatever it was before the call (capture the reference beforehand) — proves restoration even on
+   the success path; also add a case that makes an internal step throw (e.g. a page whose render
+   throws) and still assert the adapter was restored afterwards (the `try/finally` must cover the
+   failure path too, not just the happy path).
+
+Run, do not write: the kit's existing auth and i18n tests (grep `tests/` for
+`i18nAggregate`/`authErrors`/`resolveErrorText`/`loginPageErrorResolution` — these are the
+directly-dependent set the Orchestrator re-runs as the gate).
+
+## Do-not-touch / invariants
+
+- No change to any existing export, component, or behaviour (Parity guardrail) — this is a new,
+  additive, test-only function.
+- Do not add `@testing-library/react` (or any other new package) to `dependencies`,
+  `peerDependencies`, or `devDependencies` for this function's own sake.
+- Do not touch `apiClient.jsx`'s actual interceptors/exports — only reach into
+  `apiClient.defaults.adapter` from the NEW module, temporarily, with a guaranteed restore.
+
+---
+
+# 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 `git add`/`commit`/`push`.
+
+### Execution directive
+
+Check `.claude/codex-status.md` first (newest-first; read it with `head`). No line for today means use
+Codex. Before `git push`, run `git log origin/main..HEAD` and push only if every listed commit is this
+order's (parallel sessions share this checkout).
+
+### Review routing
+
+Tier 3: independent `reviewer` (all configured lenses) and `ui_reviewer`, concurrent, one batch, before
+the commit. No `sec_reviewer`: the function adds no runtime path, it only reads what is already there.
+
+### Verification
+
+Run the check once against a real consumer before release. `survey_app` is on `3.9.x` and has the closest
+existing test (`frontend/src/AuthRoutesIntegration.test.jsx`). Do it from a scratch copy or a local pack,
+never by committing to that repo. Name the result in the register Notiz.
+
+### Register + commit + release
+
+Row -> `done` with the review Notiz in the `AGENTS.md` shape and the published version. The publish
+runs on push to `main` when `package.json`/`src/**` change; verify it through the job log
+(`npm view` lags for provenance publishes). Adoption rows per app are added by the Expertenchat when
+each app's next bump is scoped.
+
+### Mini-handover
+
+`Orchestrator: implement work-orders/UCM-TEST-1.md in ui-core-micha (main). git pull first, read the WO,
+then follow orchestrate-codex.`

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.
 
 ---