@micha.bigler/ui-core-micha 3.7.0 → 3.9.0

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

@@ -0,0 +1,356 @@
+# UCM-THEME-15: Derive status and control-border colours against the theme's own page
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+`createAppTheme` already derives one colour against the page it will sit on: `controlBorder.focus`
+(`deriveFocusColour`, `src/theme/createAppTheme.js`). Every other page-sensitive baseline colour is
+fixed. So an app or site whose `background.default` is not near-white gets baseline status and
+border colours that fail WCAG on its own page.
+
+After this order, the **baseline-supplied** status `main` colours and control-border colours are
+derived the same way, and only when they would otherwise fail. A theme on the baseline's own page
+resolves exactly as today. A theme on a tinted page gets colours that pass on that page.
+`assertThemeComplete` then returns zero contrast findings for every baseline-supplied colour on the
+estate's real site backgrounds.
+
+**Operator decision (2026-09-29):** option (a) of three. The factory derives the colours. Contrast
+findings do **not** become exemptible (option b, which would hide real accessibility failures on
+customer sites), and sites do not get their own status colours (option c, new per-customer design
+decisions).
+
+## Context the operator established
+
+- **What the check measures** (`src/theme/themeCompleteness.js`, `contrastFindings`): for each status
+  key, `main` against `#FFFFFF` **and** `background.default` at **4.5:1**; `controlBorder.main/hover/
+  focus/error` against the same two surfaces at **3:1**. The pairs `text`-on-`bg` and
+  `fillText`-on-`fill` are self-contained and do not depend on the page. Contrast findings are appended
+  after exemption filtering (`themeCompleteness.js:371`), so no exemption can cover them. That stays.
+- **The baseline values** (`src/theme/tokens.js`, `BASELINE_PALETTE`): `success.main` `#1B8038`,
+  `warning.main` `#976100`, `error.main` `#BF3227`, `info.main` `#01579B` (`stale` has no `main`), each
+  built by `withMainShades`. `controlBorder.main` `rgba(33,37,41,.50)`, `.hover` `rgba(33,37,41,.65)`,
+  `.error` `#BF3227`. `focus` is derived.
+- **Measured on the estate's real site backgrounds (2026-09-29),** baseline colours only:
+
+  | Page `background.default` | Fails | Darkening needed (MUI `darken`) |
+  |---|---|---|
+  | baseline `#FAFAFA` | nothing | none |
+  | `hafen` `#D8E4E1` | success 3.84, warning 4.00, error 4.35; border.main 2.91 | 0.10 / 0.08 / 0.03; border alpha 0.52 |
+  | `jg-fegbern` `#eceae2` | success 4.16, warning 4.33; border.main 2.98 | 0.05 / 0.03; alpha 0.51 |
+  | `routing` `#E8EAF6` | success 4.18, warning 4.35; border.main 2.98 | 0.05 / 0.03; alpha 0.51 |
+  | `uph` `#E6EAF0` | success 4.15, warning 4.32; border.main 2.97 | 0.05 / 0.03; alpha 0.51 |
+  | `ygbs` `#E398C7` | success 2.29, warning 2.38, error 2.59, info 3.38; border.main 2.50, border.error 2.59 | 0.40 / 0.38 / 0.34 / 0.21; alpha 0.59 |
+
+  Sites are `survey_app/frontend/src/sites/*/theme.js`; `ygbs` also lives in `survey_contact_app`.
+- **Every adopted app already passes.** All ten apps on `createAppTheme` assert
+  `assertThemeComplete(theme).findings` equals `[]`, so none of them has a contrast finding today.
+
+## The rule (decided)
+
+1. **Scope of derivation:** `success/warning/error/info.main`, and `controlBorder.main/hover/error`.
+   The derived `main` also re-derives its `light`/`dark`/`contrastText` through `withMainShades`, so a
+   status entry stays internally consistent. `text`, `fill`, `fillText`, `bg` are untouched.
+2. **Only when it fails.** A value that already clears its threshold against both `#FFFFFF` and
+   `background.default` is returned **unchanged, byte for byte**. So no theme that passes today moves.
+3. **Only baseline-supplied values.** If the app's own config sets a status `main` or a
+   `controlBorder` state, that value is the app's decision. It is never altered, and its finding
+   stays.
+4. **Direction and method:** status `main` and `controlBorder.error` are darkened with MUI `darken` in
+   the smallest steps that clear the threshold, as `deriveFocusColour` does. `controlBorder.main/hover`
+   keep their ink hue and raise their alpha instead, so they stay a translucent ink.
+5. **Same surfaces as the check:** `#FFFFFF` and `background.default`, exactly the two that
+   `contrastFindings` uses, just as the existing comment at `deriveFocusColour` insists.
+6. **Unreachable stays visible:** if the maximum step does not clear the threshold, the loop stops,
+   returns the last value and the finding remains. It never throws and always terminates. Dark pages
+   are `UCM-THEME-14`'s subject, not this order's.
+
+## Scope + non-goals
+
+In scope: the derivation in `createAppTheme` (next to `deriveFocusColour`, which may be generalised
+into one helper); `DESIGN.md` (one paragraph: which baseline colours are page-derived, and why);
+`CHANGELOG.md`; a **minor** release. It is a changed default, but only for themes that currently fail,
+and none of the adopted apps does.
+
+Non-goals:
+- No change to any baseline token value in `tokens.js`.
+- No exemption path for contrast findings.
+- No change to `text`/`fill`/`fillText`/`bg`, to `dataSeries`, or to anything the app sets itself.
+- No dark-mode handling (`UCM-THEME-14`).
+- No consumer change. `survey_app` and `survey_contact_app` adopt it through their own pin bump.
+
+## Tier · precondition / gate
+
+- **Tier 3 · tests: derivation on the six measured pages, byte-identical output on the baseline page,
+  app-supplied values untouched, termination; the kit's existing theme tests.** A change inside
+  shared-core.
+- Precondition: none.
+- **Order with `UCM-THEME-14`:** this lands first. Both touch the focus derivation and the surface
+  pair, and 14 is waiting on a design round (`UCM-THEME-13`) anyway.
+- Downstream: `survey_app`/`SVA-THEME-1` and `survey_contact_app`/`SCA-THEME-1` (site half) wait for
+  this release **and** for their own pin bump.
+
+## Risks
+
+- **`ygbs` will look different.** Its status colours darken by up to 40 % (success `#1B8038` becomes
+  roughly `#104D22`). That is the price of legibility on a mid-pink page. It is visible on the customer
+  site, and the operator sees it in `SVA-THEME-1`'s acceptance.
+- **Silent change for a future app on a tinted page.** Expected and intended: the baseline promises a
+  passing colour, not a fixed hex. `DESIGN.md` has to say so, or someone will read the hex in
+  `tokens.js` and expect it on screen.
+- **Rule 3 needs to know what the app set.** The merged palette alone cannot tell baseline from app
+  values. Read the app's config (`appConfig.palette`) before deciding, not the resolved theme.
+- **`light`/`dark` shades shift with a derived `main`.** Components using `error.dark` for hover move
+  with it. Correct, but name it in the changelog.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the Orchestrator's run is the gate)
+
+Kit test suite, next to the existing theme tests:
+
+1. **Six measured pages.** For each `background.default` in the table, with only `palette.primary`
+   given, `assertThemeComplete` has no `contrast.*.main-on-*` and no `contrast.controlBorder.*`
+   finding.
+2. **No movement where nothing fails.** On the baseline page, the resolved status entries and
+   `controlBorder` equal today's values exactly. Show that the test fails when one baseline hex is
+   altered by hand.
+3. **App values are untouched.** A config that sets `success.main` to a failing colour on a tinted
+   page keeps exactly that colour, and the finding remains.
+4. **Termination.** A page on which the maximum step cannot reach the threshold (a mid-grey such as
+   `#767676`) returns without throwing and keeps the finding.
+
+Run, do not write: the kit's existing theme and `kitSxRegistry` tests.
+
+## Parity guardrail
+
+No change for any theme that passes today. No API change, no new option.
+
+---
+
+# B. Implementation map, filled by the Orchestrator and ADDRESSED TO THE IMPLEMENTER
+
+## Context package
+
+### Current shape (`src/theme/createAppTheme.js`, read in full before editing)
+
+- `clearsContrast(colour, surfaces)` (line ~39): `surfaces.every((s) => getContrastRatio(colour, s) >= 3)`
+  — hardcoded to 3:1 and to MUI's own `getContrastRatio`. Used ONLY by `deriveFocusColour`.
+- `deriveFocusColour(primary, surfaces)` (line ~47): darkens in `0.05` steps (MUI `darken`), capped at
+  coefficient `0.9`, stops and returns the last value if unreached (never throws).
+- `createAppTheme(appConfig)` (line ~170): throws if `!appConfig?.palette?.primary`. Builds
+  `paletteTheme = createTheme({palette: appConfig.palette}, {palette: BASELINE_PALETTE}, {palette:
+  appConfig.palette})` (app layered, then baseline, then app again — this is why an app-set value
+  always wins in `finalPalette`, and why a value present in `BASELINE_PALETTE` but absent from
+  `appConfig.palette` is a baseline value). `finalPalette = paletteTheme.palette`. Then:
+  ```js
+  const computedPalette = {
+    controlBorder: {
+      ...finalPalette.controlBorder,
+      focus: deriveFocusColour(finalPalette.primary.main, ['#FFFFFF', finalPalette.background.default]),
+    },
+  };
+  const resolvedPalette = { ...finalPalette, ...computedPalette };
+  ```
+  This is the exact seam this WO extends — do not restructure the surrounding merge order,
+  `validateStyleOverrides`, or the final `createTheme(...)` call's argument layering.
+
+### Do NOT touch `clearsContrast`/`deriveFocusColour` — add parallel, separate logic instead
+
+- The byte-identical-on-baseline-page requirement (test #2) and "no change to anything not
+  described here" mean the existing focus derivation must keep behaving exactly as it does today.
+  Do not generalise `clearsContrast` into a shared threshold-aware helper by EDITING it in place —
+  add new, separate functions for this WO's derivations. (You may factor out a shared shape later if
+  you can prove byte-for-byte equivalence, but the safe, required path is: leave the existing two
+  functions untouched, add new ones alongside.)
+- **Use `calculateContrastRatio` from `./themeCompleteness`** (already exported, already used by
+  `contrastFindings` — the same function the check itself uses) for every NEW contrast test in this
+  WO, not MUI's `getContrastRatio`. This matters concretely for `controlBorder.main`/`.hover`: their
+  baseline values are translucent (`rgba(33,37,41,.50)`), and `calculateContrastRatio` alpha-composites
+  over the background before computing luminance (see its own docstring) — `getContrastRatio` is not
+  documented to do this. Using the wrong function here would silently pick the wrong alpha.
+
+### The two derivation shapes (rule 4)
+
+1. **Darken-based** (status `main` for success/warning/error/info; `controlBorder.error`): same
+   step/cap shape as `deriveFocusColour` (start `coefficient = 0.05`, `darken(original, min(coefficient,
+   0.9))`, step `+0.05`, stop and return the last value if `coefficient >= 0.9` without clearing) but
+   parameterised by threshold (`4.5` for status `main`, `3` for `controlBorder.error`) and using
+   `calculateContrastRatio`.
+2. **Alpha-raising** (`controlBorder.main`, `.hover`): the baseline values are the fixed shape
+   `rgba(33, 37, 41, <alpha>)` (`.50` and `.65`). Parse `r`,`g`,`b`,`a` (a small regex is enough — this
+   path is NEVER invoked on an app-supplied value, see rule 3 below, so it never needs to handle an
+   arbitrary CSS colour format). Step `alpha` up by `0.05`, capped at `1`, producing
+   `rgba(${r}, ${g}, ${b}, ${alpha})` each step, stopping when `calculateContrastRatio` clears `3`
+   against both surfaces or `alpha` reaches `1` (never throws; if unreached at `alpha = 1`, return that
+   last candidate and the finding remains — same "give up, stay visible" contract as the darken path).
+
+### Rule 3 — baseline vs app-supplied, decided from `appConfig.palette`, not the resolved theme
+
+Before deriving anything, for each of the 6 targets check the RAW input, not `finalPalette`:
+- Status keys: `appConfig.palette?.[statusKey]?.main !== undefined` → app-supplied, skip entirely
+  (leave `finalPalette[statusKey]` exactly as merged, findings stay if any).
+- `controlBorder.main`/`.hover`/`.error`: `appConfig.palette?.controlBorder?.[state] !== undefined` →
+  app-supplied, skip.
+- Only when NOT app-supplied: read the value off `finalPalette` (the merged/baseline value), check it
+  against `['#FFFFFF', finalPalette.background.default]` at the relevant threshold, and derive only if
+  it fails. **A value that already clears both thresholds is returned unchanged, byte for byte** — do
+  not run it through `darken`/alpha-step at all if it already passes (this is what keeps the baseline
+  page byte-identical: on `#FAFAFA`, everything already clears, so nothing here ever fires).
+
+### Re-deriving a status entry consistently (rule 1)
+
+When a status `main` is derived, rebuild that status's `main`/`light`/`dark`/`contrastText` via the
+existing `withMainShades` (`src/theme/tokens.js`, already exported — import it, or re-derive the same
+shades inline using `lighten`/`darken` exactly as `withMainShades` does; prefer importing the real
+function over duplicating its formula) called as `withMainShades(derivedMain, existingContrastText)`
+— `existingContrastText` is `finalPalette[statusKey].contrastText`, unchanged (every baseline status
+already carries `'#FFFFFF'`; do not hardcode `'#FFFFFF'` here, read it off the entry so an
+app-overridden `contrastText` on an otherwise-baseline `main` is respected). `text`/`fill`/`fillText`/
+`bg` on that same status object are spread through unchanged — merge shape:
+`{ ...finalPalette[statusKey], ...withMainShades(derivedMain, finalPalette[statusKey].contrastText) }`.
+
+### Wiring it into `createAppTheme`
+
+Extend the existing `computedPalette` object (do not add a second, separate merge step) so
+`resolvedPalette` picks up both the existing `controlBorder.focus` line and the new derivations, e.g.
+(shape, not literal code to paste — adapt to how you factor the helper functions):
+```js
+const computedPalette = {
+  ...derivedStatusEntries,           // { success?, warning?, error?, info? } — only keys that were derived
+  controlBorder: {
+    ...finalPalette.controlBorder,
+    ...derivedControlBorderEntries,  // { main?, hover?, error? } — only keys that were derived
+    focus: deriveFocusColour(finalPalette.primary.main, ['#FFFFFF', finalPalette.background.default]),
+  },
+};
+```
+`stale` has no `main` (`tokens.js`) — `contrastFindings` already skips it via `if (!main) continue;`;
+do not add derivation logic for `stale`.
+
+### Test file
+
+New file next to the existing theme tests (`tests/createAppTheme.test.js` already exists — read it
+first; extend it if its structure fits, or add `tests/createAppThemePageContrast.test.js`).
+Use the six real background values from the Envelope's table directly (already verified against
+`survey_app/frontend/src/sites/*/theme.js` — `hafen` `#D8E4E1`, `jg-fegbern` `#eceae2`, `routing`
+`#E8EAF6`, `uph` `#E6EAF0`, `ygbs` `#E398C7`, plus the baseline `#FAFAFA`). Any valid `primary.main`
+works for these (the check is independent of primary) — reuse the kit's own test convention, e.g.
+`'#0F62FE'` (see `tests/StatTile.test.jsx`).
+
+1. For each of the 6 pages: `createAppTheme({ palette: { primary: { main: '#0F62FE' }, background: {
+   default: <page hex> } } })`, then `assertThemeComplete(theme).findings` has no entry whose
+   `surface` starts with `contrast.` for any status `main-on-*` or any `contrast.controlBorder.*`
+   (other, unrelated findings — e.g. undeclared surfaces this WO doesn't touch — are not this test's
+   concern; assert on the specific surface-name prefixes, not on the whole array being empty, unless
+   this repo's fixture already guarantees a clean baseline call is fully empty — check
+   `tests/createAppTheme.test.js`/`tests/themeCompleteness.test.js` for the existing convention here).
+2. On the baseline page (`background.default` left at its `BASELINE_STATIC`/`BASELINE_PALETTE`
+   default, i.e. no override given), `theme.palette.success.main` (and `.light`/`.dark`/
+   `.contrastText`), `.warning.main`, `.error.main`, `.info.main`, `.controlBorder.main`, `.hover`,
+   `.error` all equal today's exact `BASELINE_PALETTE`/derived values (read them from `tokens.js`,
+   do not hand-copy hexes into the test — import `BASELINE_PALETTE` and compare against it directly
+   so the test can't drift from the source of truth). Then, per the Envelope's own instruction, show
+   this test actually pins something: temporarily hand-edit one baseline hex in a throwaway local copy
+   (or otherwise demonstrate) that the assertion fails if the value moved — narrate how you did this
+   in your `PROGRESS` line rather than leaving a permanently-broken toggle in the committed test.
+3. A config that sets e.g. `palette.success.main` to a colour that fails on a tinted page (construct
+   one deliberately, e.g. a light green on `ygbs`'s pink) keeps EXACTLY that colour after
+   `createAppTheme` (`theme.palette.success.main === appConfig.palette.success.main`), and
+   `assertThemeComplete` still reports that specific `contrast.success.main-on-*` finding (proving
+   rule 3's app-supplied values are never touched AND their findings are never silently hidden).
+4. `createAppTheme({ palette: { primary: { main: '#0F62FE' }, background: { default: '#767676' } } })`
+   does not throw, returns a defined `theme.palette.success.main` (etc.), and
+   `assertThemeComplete(theme).findings` still contains the relevant `contrast.*` entries (mid-grey
+   `#767676` is deliberately unreachable within the darken cap — confirm this numerically before
+   relying on it: `calculateContrastRatio('#FFFFFF', '#767676')` and the darkened-`main` variants
+   should stay below `4.5` even at the `0.9` darken cap; if your arithmetic says otherwise, pick
+   another representative unreachable grey and say which and why in `PROGRESS`).
+
+Run, do not write: `tests/createAppTheme.test.js` (existing) and `tests/themeCompleteness.test.js`
+(existing) as the directly-dependent regression set — your own focused run only, the Orchestrator
+re-runs both as the gate.
+
+### `DESIGN.md` and `CHANGELOG.md`
+
+- `DESIGN.md`: one paragraph — which baseline colours are page-derived (`success`/`warning`/`error`/
+  `info.main`, `controlBorder.main`/`.hover`/`.error`, alongside the existing `controlBorder.focus`)
+  and why (a fixed hex cannot promise WCAG on every page background; the baseline promises a passing
+  colour, not a fixed one — state this explicitly so a future reader doesn't expect the `tokens.js`
+  hex to appear unmodified on every site). If `DESIGN.md` does not exist at the repo root, check for
+  an equivalent doc (grep for "baseline" or "token" in root `*.md` files) before creating a new one.
+- `CHANGELOG.md`: entry naming the changed default (derived colours are possible now, "byte identical
+  when passing today"), and explicitly naming that `light`/`dark` shades move WITH a derived `main`
+  (Risk note: a component styled with `error.dark` for hover moves too).
+
+## Do-not-touch / invariants
+
+- No change to any literal in `BASELINE_PALETTE`/`BASELINE_STATIC` (`tokens.js`).
+- No exemption path added anywhere in `themeCompleteness.js`.
+- `text`/`fill`/`fillText`/`bg` on every status object, `dataSeries`, and anything the app sets itself
+  (beyond the 6 targets named here) are untouched.
+- No dark-mode handling (`UCM-THEME-14`'s subject).
+- Do not touch `survey_app`/`survey_contact_app` — this WO is entirely inside `ui-core-micha`.
+
+## 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 `DESIGN.md`/`CHANGELOG.md` as named above) 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 `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`. Ask `ui_reviewer` specifically about rule 3: can a
+baseline-supplied value be told apart from an app-supplied one in every merge path?
+
+### Verification
+
+The contrast values in the Envelope table are the acceptance data: re-derive them from the built
+themes and put the derived hex per site in the register Notiz. No prototype is in scope. The visual
+consequence is accepted per site in `SVA-THEME-1`, not here.
+
+### 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 (`.github/workflows/publish.yml`). Then add
+`planned` pin-bump rows in `survey_app/WORK_ORDERS.md` and `survey_contact_app/WORK_ORDERS.md` (from
+`2.41.3`; classify each by the dependency-bump test in `AGENTS.md` -> Tiering, reading the changelog
+from `2.41.3` on) and unblock `SVA-THEME-1` / `SCA-THEME-1` against them.
+
+### Mini-handover
+
+`Orchestrator: implement work-orders/UCM-THEME-15.md in ui-core-micha (main). git pull first, read the
+WO, then follow orchestrate-codex.`