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

package/work-orders/UCM-SHELL-7.md

@@ -0,0 +1,134 @@
+# UCM-SHELL-7 — User-menu avatar initials fail contrast
+
+# A. Envelope — authored by the Expertenchat
+
+## Goal & expected outcome
+
+- Goal: the initials in the header avatar are readable.
+- Expected outcome: initials reach at least 4.5:1 against the avatar background, using the consuming
+  app's theme tokens rather than MUI's default grey.
+
+## Context — measured 2026-09-29 in jg-ferien's local browser test (ucm 3.5.0 installed there)
+
+- `UserMenu` (imported in jg-ferien's `Header.jsx`) renders the MUI default avatar: white initials on
+  light grey, **1.83:1**, on every page of the app.
+
+## Scope + non-goals
+
+- In scope: avatar colours in `UserMenu` from theme tokens (e.g. primary surface with its
+  contrastText), with a fallback that passes when a consumer defines nothing.
+- Explicit non-goals / do-not-touch: no layout change of the user menu.
+
+## Tier · gates
+
+- **Tier 3** — shared-core component (small).
+- Reviewer: `ui_reviewer` (no new logic beyond the colour choice).
+- **Done means released and jg-ferien's pin bumped.**
+
+## Risks
+
+- `createAppTheme` baseline: if the chosen token is optional, `assertThemeComplete` must require it or
+  the fallback must pass on its own.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the orchestrator's run is the gate)
+
+1. With jg-ferien's theme values the avatar pair is at least 4.5:1.
+2. With a theme defining nothing extra the fallback pair is at least 4.5:1.
+
+---
+
+# B. Implementation map — filled by the Orchestrator — ADDRESSED TO THE IMPLEMENTER
+
+## Context package
+
+- File: `src/auth/UserMenu.jsx`. The avatar is rendered at line 60:
+  `<Avatar src={avatarSrc} sx={{ width: 32, height: 32, fontSize: '0.8rem' }}>` — no `bgcolor`/`color`
+  is set today, so it falls through to MUI's default grey Avatar styling (1.83:1, the measured
+  defect). Only this one JSX element changes; nothing else in the file.
+- **Pitfall — do not just reach for `theme.palette.primary.contrastText`.** MUI's own
+  `createTheme`/`augmentColor` computes `contrastText` with `contrastThreshold: 3` (tuned for large
+  text/graphics, AA), not the 4.5:1 this WO requires for normal-size initials text. A consumer's
+  `primary.main` that legitimately passes MUI's own 3:1 threshold can still fail 4.5:1, and nothing
+  here re-validates it — so `contrastText` alone is not a fallback that "passes when a consumer
+  defines nothing", it is a fallback that USUALLY passes.
+- **Design to implement instead** (uses the kit's own exported contrast helper, satisfies both
+  required tests meaningfully since both actually depend on the consumer's `primary.main`):
+  1. Import `{ calculateContrastRatio }` from `'../theme'` (already exported from
+     `src/theme/index.js` → re-exported at `src/index.js`) and `useTheme` from
+     `'@mui/material/styles'`.
+  2. Inside `UserMenu`, read `const theme = useTheme();`.
+  3. Background: `theme.palette.primary.main` (the "primary surface" the Envelope names).
+  4. Text colour: compute
+     `calculateContrastRatio(theme.palette.background.paper, theme.palette.primary.main) >= 4.5
+        ? theme.palette.background.paper : theme.palette.ink.primary`.
+     This is not an arbitrary heuristic: for any background colour, the higher of
+     (contrast against white) and (contrast against near-black) is mathematically always ≥ √21 ≈
+     4.58 — i.e. picking whichever of the kit's own light (`background.paper`, white) or dark
+     (`ink.primary`, near-black) ink token has the higher measured contrast against
+     `primary.main` is GUARANTEED to clear 4.5:1 for every possible `primary.main`, including one
+     a consumer hasn't customised at all (the untouched baseline `primary.main` MUI ships). That is
+     what makes this "a fallback that passes when a consumer defines nothing" instead of "usually
+     passes".
+  5. Apply as `sx={{ ..., bgcolor: theme.palette.primary.main, color: <computed> }}` on the same
+     `Avatar` element — keep the existing `width`/`height`/`fontSize` untouched.
+  6. Do NOT introduce a new literal hex/rgb anywhere — `theme.palette.background.paper` and
+     `theme.palette.ink.primary` are both resolved theme values, and referencing them via
+     `theme.palette.<path>` (not writing their hex value as a string literal) keeps
+     `reportOffPaletteColours` clean, same as every other component in the kit.
+- Test file: new `tests/UserMenu.test.jsx` (none exists yet — check with `Glob` before assuming;
+  if a `UserMenu` test already exists under a different name, extend it instead of creating a
+  duplicate). Pattern after `tests/StatTile.test.jsx`: `@vitest-environment jsdom`,
+  `createAppTheme(...)`, wrap `UserMenu` in the theme provider AND `AuthContext.Provider` (it reads
+  `user`/`logout` via `useContext(AuthContext)` at line 32 — a minimal `{ user: { username: 'ab' },
+  logout: () => {} }` value is enough to render the avatar).
+  1. With a theme built from jg-ferien's actual `primary.main` — `#367964` (measured directly from
+     `jg-ferien/frontend/src/theme.js:25`, a mid-brightness teal-green), assert
+     `calculateContrastRatio(<resolved avatar text colour>, <resolved avatar bg colour>) >= 4.5`
+     by reading the rendered `Avatar`'s computed `backgroundColor`/`color` via
+     `window.getComputedStyle` (see `tests/StatTile.test.jsx`'s `accent` border test for the
+     `getComputedStyle` pattern) and feeding both into `calculateContrastRatio` directly — do not
+     hardcode an expected hex, assert the ratio.
+  2. With `createAppTheme({})` (no consumer overrides — MUI's own baseline `primary.main`), assert
+     the same ≥4.5 computed-style contrast check.
+
+## Do-not-touch / invariants
+
+- No layout change to the user menu (Envelope non-goal) — only the two `sx` colour values change.
+- Do not touch `assertThemeComplete`/`THEME_COMPLETENESS_SURFACES` — this fix reads existing
+  required surfaces (`primary.main`, `background.paper`, `ink.primary`), it does not need a new one.
+
+## 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; `ui_reviewer`; release; jg-ferien pin bump; register rows here and in jg (`JG-DL-12`).)*

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

@@ -0,0 +1,69 @@
+# UCM-THEME-13: Freeze a dark-mode baseline token set
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+The central token file `src/theme/tokens.js` has one light baseline palette and no dark one. This order
+produces the **decided** dark token set as a committed reference sheet, `docs/DARK-TOKENS.md`. The
+operator freezes it before `UCM-THEME-14` puts those values into code. The output is a document. No
+source file changes here.
+
+Operator decision (2026-09-29): dark mode gets its own work order in the kit, rather than one app keeping
+a raw `createTheme` for it.
+
+## Context the operator established
+
+- **One consumer today: `webshop-guenter`.** It has a light/dark switch (`frontend/src/App.jsx:96`)
+  and a hand-built `darkTheme` from its operator design handoff (background `#0E0B08`, paper
+  `#171209`, primary `#D49040`, secondary `#A88868`). Its adoption, `WSG-THEME-1`, is blocked on this
+  order and on `UCM-THEME-14`. No other app in the estate renders a dark theme (measured 2026-09-29).
+- The light baseline covers: the palette (primary is app identity; secondary, the status family
+  `success/warning/error/info/stale` with `main/light/dark/contrastText` plus `text/fill/bg`,
+  `background.default/subtle/paper`, the text inks, `divider`, `controlBorder`), `dataSeries` (six
+  categorical colours) and `shadow.rest/overlay`. Typography, radii, spacing, density and motion do not
+  depend on the mode.
+
+## Scope + non-goals
+
+In scope: `docs/DARK-TOKENS.md` with a value for every **mode-dependent** light token class listed
+above, each with a one-line reason, and a contrast table: every text/fill pair and every
+`main`-on-surface pair at 3:1 or better against the dark `background.default` and `background.paper`.
+Follow the `design-language` skill's process: inventory first, then a structural round, then values
+decided in an instrument, then the freeze.
+
+Non-goals:
+- No change to any light value.
+- No code, no tests. `UCM-THEME-14` implements.
+- No per-app dark identity. An app's dark primary stays that app's own, just as its light one does.
+- No automatic switching (`prefers-color-scheme`) and no toggle component. Apps own their switch.
+
+## Tier · precondition / gate
+
+- **Tier 2 · tests: none (document only).** It decides the future content of shared-core, but it does
+  not change shared-core. The code change is `UCM-THEME-14`, which is Tier 3.
+- Precondition: none.
+- Gate: **the operator freezes the sheet**, and the sheet itself says so with a dated section. Until
+  then `UCM-THEME-14` does not start.
+
+## Risks
+
+- **A dark palette drawn from a single app's handoff becomes that app's palette for everyone.**
+  webshop-guenter's values are one input to the inventory, not the answer. It keeps its own values as
+  identity in any case (`WSG-THEME-1`).
+- **Status tints (`bg`) are the class that breaks first on dark.** A light tint over a dark page fails
+  contrast in the other direction.
+
+---
+
+# B. Implementation map
+
+*Not applicable. This is an Expertenchat document order, authored in-session with the operator.*
+
+---
+
+# C. Orchestrator only, NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this: STOP.** There is no implementer for this order.
+
+Register: row -> `done` with the commit of the frozen sheet. Downstream: `UCM-THEME-14` unblocks.

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

@@ -0,0 +1,140 @@
+# UCM-THEME-14: Dark mode in `createAppTheme`, from the central token file
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+`createAppTheme({ palette: { mode: 'dark', primary }, ... })` builds a complete dark theme whose
+mode-dependent values come from a dark baseline palette in `src/theme/tokens.js`, next to the light
+one. `assertThemeComplete` judges a dark theme against its own surfaces. **The light output does not
+change by a single value.**
+
+Afterwards an app with a light/dark switch (today only `webshop-guenter`, `WSG-THEME-1`) can compose
+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.
+
+## Context the operator established
+
+- `createAppTheme` (`src/theme/createAppTheme.js`) resolves the palette in three layers: the app's
+  palette, then `BASELINE_PALETTE`, then the app's palette again. It then derives
+  `controlBorder.focus`, builds the palette-aware component slots, and merges `BASELINE_STATIC`, those
+  components and the app config. `palette.mode` is not read anywhere today.
+- **Two places assume a white page:**
+  - `deriveFocusColour` checks 3:1 against `'#FFFFFF'` and `background.default`, and only ever
+    **darkens** the primary. On a dark page it would have to lighten.
+  - `contrastFindings` in `src/theme/themeCompleteness.js` checks against a fixed
+    `white: '#FFFFFF'` (line 298) plus `page: background.default`.
+- `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.
+- 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.
+
+## Scope + non-goals
+
+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.
+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.
+   Switching one to an existing token is in scope. Anything that needs a new token is a finding.
+5. `DESIGN.md` (a dark-mode section), `CHANGELOG.md`, and a **minor** version bump. The change is
+   additive: light output is unchanged, and dark is new.
+
+Non-goals:
+- No change to any light value or light behaviour.
+- No automatic `prefers-color-scheme` switching and no toggle component.
+- No consumer adoption. `WSG-THEME-1` does that in its own repo, after its own pin bump.
+- No change to chart components beyond reading palette tokens they already read.
+
+## Tier · precondition / gate
+
+- **Tier 3 · tests: light-output regression guard, dark completeness, focus contrast in both modes,
+  and the kit's existing theme tests.** A change inside shared-core (`AGENTS.md` -> Tiering).
+- Precondition: **`UCM-THEME-13` frozen.**
+- Downstream: `webshop-guenter`/`WSG-THEME-1` waits for this release and for its own pin bump.
+
+## Risks
+
+- **Ten adopted apps consume the light path.** A light regression reaches all of them on their next
+  bump. That is why the regression guard is a required test, not a nice-to-have.
+- **The three-layer palette merge interacts with augmentation** (the comment at the top of `tokens.js`:
+  only the first `createTheme` argument is augmented). A dark status entry missing
+  `main`/`contrastText` would silently keep MUI's light hue.
+- **Contrast in the other direction.** Light status tints (`bg`) over a dark page, and a focus colour
+  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.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the Orchestrator's run is the gate)
+
+Kit test suite, narrow, next to the existing theme tests:
+
+1. **Light regression guard.** For a fixed light app config, the fully resolved theme (palette,
+   typography, shape, components, exemptions) equals the output from before this change. Show that the
+   test fails when one light value is altered by hand. A structural test that cannot fail is
+   decoration.
+2. **Dark completeness.** `assertThemeComplete(createAppTheme({ palette: { mode: 'dark', primary } }))`
+   has zero findings, or only exemptions with a true reason. The same check with a primary that has to be
+   **lightened** to clear contrast.
+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.
+
+Run, do not write: the kit's existing theme and `kitSxRegistry` tests.
+
+## Parity guardrail
+
+No light-mode change of any kind. No behaviour, API or data-contract change beyond the new `mode`
+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.*
+
+---
+
+# 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.
+
+### Review routing
+
+Tier 3: independent `reviewer` (all configured lenses) and `ui_reviewer`, concurrent, one batch,
+before the commit. No `sec_reviewer`.
+
+### Verification
+
+Render a kit demo surface in both modes at 375 px and 1280 px (`dev/`), and name the screenshots in
+the register Notiz. No prototype is in scope.
+
+### Register + commit + release
+
+Row -> `done` with the review Notiz in the `AGENTS.md` shape. The publish runs on push to `main` when
+`package.json`/`src/**` change (`.github/workflows/publish.yml`). Then add a planned row in
+`webshop-guenter/WORK_ORDERS.md` for the pin bump to this version, and unblock `WSG-THEME-1`.
+
+### Mini-handover
+
+`Orchestrator: implement work-orders/UCM-THEME-14.md in ui-core-micha (main). git pull first, confirm
+UCM-THEME-13 is frozen, read the WO, then follow orchestrate-codex.`