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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 3.8.0 — UCM-THEME-15
+
+`createAppTheme` can now derive baseline status `main` colours and control-border colours against the theme's own
+page background when their WCAG contrast would otherwise fail. Values that already pass remain byte-identical, and
+app-supplied values are unchanged. When a status `main` is derived, its `light` and `dark` shades move with it too,
+so components using `error.dark` for hover may change on tinted pages.
+
 Only notable, user-facing changes. Not every version — see `WORK_ORDERS.md` for the full history.
 
 ## 3.6.0 — AUTH-8

package/DESIGN.md

@@ -6,6 +6,14 @@ These principles are the spec a **prototype** encodes and the implementation mat
 
 ## Identity
 
+The baseline's page-derived colours are `success.main`, `warning.main`, `error.main`, `info.main`,
+`controlBorder.main`, `controlBorder.hover`, and `controlBorder.error`, alongside the existing
+`controlBorder.focus`: a fixed colour cannot promise WCAG contrast on every page background. The baseline therefore
+tries for a passing colour rather than a fixed hex that must appear unchanged on every site — derivation is capped
+(the same bounded darken/alpha steps `controlBorder.focus` already used) and can still leave a contrast finding on a
+page extreme enough that no derived shade clears the threshold; values that already pass remain byte-identical,
+while baseline values that fail are derived against the theme's own page.
+
 1. **Honor the shared baseline and the app's identity; don't invent a parallel system.** `ui-core-micha`'s `createAppTheme` deliberately owns the complete visual baseline. Each app supplies its identity through `palette.primary` and `fontFamily`, plus reviewed overrides where its real design requires them (hram: primary blue `#468AB2`). **Match first, then elevate.** Never invent a parallel language — a made-up teal / pills / breadcrumb vocabulary was the v1 mistake.
 2. **One accent, deliberately placed.** Interactive = the app's one accent colour. **Data colours are a separate layer with a shared default that apps may override.** Status (green / amber / red) is semantic and is NEVER repurposed as a series colour. Restraint over decoration.
 3. **Commit to the app's theme reality — with intent.** If the app is single-theme (hram is light-only), commit to that deliberately rather than bolting on dark mode as an afterthought — a decision, not an omission. The estate does NOT mandate light-only; it is per-app — but whichever it is, it is on purpose.

package/WORK_ORDERS.md

@@ -27,6 +27,7 @@ prefixed ID; never reuse a bare flat number across workstreams.
 
 | ID | Titel | Beschreibung | Datum | Status | Commit(s) | Notiz |
 |---|---|---|---|---|---|---|
+| UCM-THEME-15 | Derive status and control-border colours against the theme's own page | Baseline-supplied status `main` and `controlBorder` colours are derived against `#FFFFFF` + `background.default` (like `controlBorder.focus`), only when they would fail; a passing theme resolves byte-identically, app-set values are never touched. Full order [`work-orders/UCM-THEME-15.md`](work-orders/UCM-THEME-15.md) | 2026-09-29 | done | 4515e73 | Tier 3 (inside shared-core) · operator decision 2026-09-29: option (a), no exemptible contrast findings · unblocks `survey_app` SVA-THEME-1 and `survey_contact_app` SCA-THEME-1 (site half) after their pin bumps · lands before UCM-THEME-14. Gate #1 carried by the committed Envelope + mini-handover. Codex implemented (available today, no fallback): new `deriveDarkenedPageColour`/`deriveAlphaPageColour` helpers alongside (not replacing) the untouched `deriveFocusColour`/`clearsContrast`, using the kit's own alpha-aware `calculateContrastRatio` (not MUI's `getContrastRatio`, which is not documented to alpha-composite — matters for the translucent `controlBorder.main`/`.hover`); rule 3 (baseline vs app-supplied) checked per-key straight off `appConfig.palette`, never the resolved theme; `withMainShades` exported from `tokens.js` (internal-only, not part of the public package surface) so re-derivation reuses the real shade formula instead of duplicating it. Independent `reviewer` (all 4 lenses) + `ui_reviewer` (Codex gpt-5.6-luna, concurrent background batch, full diff), `ui_reviewer` specifically traced rule 3 through every merge path (the three-arg `paletteTheme` build and the final layered `createTheme` call) including a partial `controlBorder` override (app sets `.hover` only) — confirmed no defect, per-key checks hold: **review: codex/gpt-5.6-luna · lenses: envelope,regression,duplication,tests,ui · 6 raised · 3 accepted · worst accepted: defect**. Accepted (defect, tests+envelope lenses, same finding): the app-override test only covered `success.main`/`controlBorder.main`, leaving `warning`/`error`/`info` and `controlBorder.hover`/`.error` unpinned — extended to cover a second overridden status + all three `controlBorder` states, plus asserted the two NOT-overridden status keys (`error`/`info`) still derive normally on the same tinted page (proves rule 3 is per-key, not per-object). (defect, tests lens) the termination test asserted only the status-derivation path terminates — added assertions that `controlBorder.main/hover/error` are also defined (not thrown) on the unreachable page. (nit, ui_reviewer) `DESIGN.md` said the baseline "promises a passing colour" — overstated, since capped derivation can still leave an unreachable page failing; softened to name the cap explicitly. Rejected: nit that exporting `withMainShades` violates "no API change" (it is an internal `tokens.js`↔`createAppTheme.js` module export, never re-exported from the public `src/index.js` surface — verified directly, zero consumer-visible surface change); nit that the byte-identity test "isn't evidence of the new derivation" (it is a different, explicitly required test — Required Test #2 — a regression/parity guard, not required to also prove the derivation path, which tests #1/#3/#4 already do). Orchestrator's own scoped run: `tests/createAppThemePageContrast.test.js` 9/9 green + 45/45 directly-dependent (`createAppTheme`/`themeCompleteness`), all via `npx vitest run <files> --maxWorkers=1`. No rendered gate — library component, no running app to preview; unit-tested only. **Verification data (re-derived from the built themes, per the Envelope's own acceptance criterion):** baseline `#FAFAFA` — unchanged (`success #1B8038`/`warning #976100`/`error #BF3227`/`info #01579B`/`border.main rgba(33,37,41,.50)`/`border.hover rgba(33,37,41,.65)`/`border.error #BF3227`). `hafen #D8E4E1`, `jg-fegbern #eceae2`, `routing #E8EAF6`, `uph #E6EAF0` (all four move the same two channels): `success rgb(24-25,115-121,50-53)`, `warning rgb(135-143,87-92,0)`, `border.main rgba(33,37,41,0.55)`; `error`/`info`/`border.hover`/`border.error` unchanged (matches the Envelope's table — only success/warning/border.main failed on these). `ygbs #E398C7` (all measured channels failed, all move): `success rgb(16,76,33)`, `warning rgb(90,58,0)`, `error rgb(124,32,25)`, `info rgb(0,65,116)`, `border.main rgba(33,37,41,0.6)`, `border.error rgb(171,45,35)`; `border.hover` unchanged (`.65` alpha already clears 3:1 even on this page). **Released as `3.8.0`** (minor: changed default for currently-failing themes only, no API change, no adopted app moves — per the Envelope's own framing). `npm view @micha.bigler/ui-core-micha version` should read `3.8.0` once `publish.yml` runs on this push. Next: add `planned` pin-bump rows in `survey_app/WORK_ORDERS.md` and `survey_contact_app/WORK_ORDERS.md` (from `2.41.3`, classify via the dependency-bump test in `AGENTS.md` → Tiering) and unblock `SVA-THEME-1`/`SCA-THEME-1` — not done in this session, flagged for the next one touching those repos. |
 | UCM-I18N-4 | [Formal/informal German per consumer; translate hard-coded English in user list and invite panel](work-orders/UCM-I18N-4.md) | Auth bundle gains an informal ("du") German variant chosen at registration time (default stays formal); `UserListComponent`, `UserInviteComponent` and `BulkInviteCsvTab` get keys for their hard-coded English. | 2026-09-29 | done | f4dfbe6 | Raised from jg-ferien's local browser test 2026-09-29; operator 2026-09-29: generic fixes go to ucm. From jg `JG-UX-10`. Tier 3 (inside shared-core). Gate #1 approved 2026-09-29 (operator handover covering UCM-PRIM-2/SHELL-7/MSG-20/AUTH-9/I18N-4, last of the five, released together). Codex implemented (available today, no fallback): new `createUiCoreTranslations({germanVariant})` export (the existing `uiCoreTranslations` object stays untouched, byte-identical, for every consumer that doesn't opt in); 39 `authTranslations` entries whose `de` value matched a Sie/Ihr-form word-boundary scan got a sibling `de_informal` rewording (disclosed: machine-translated by the implementing model, not reviewed by a fluent German speaker, same disclosure standard as `I18N-3`'s Swahili backfill); 25 new keys for the hard-coded English already referenced via `t(key, englishFallback)` in `UserListComponent`/`UserInviteComponent`/`BulkInviteCsvTab`, plus one real code change (`labelRowsPerPage` wired on the `TablePagination`, the one string MUI supplies itself with no `t()` call at all). Independent `reviewer` (all 4 lenses) + `ui_reviewer` (Codex gpt-5.6-luna, concurrent background batch, full diff): **review: codex/gpt-5.6-luna · lenses: envelope,regression,duplication,tests,ui · 9 raised · 2 accepted · worst accepted: defect**. Accepted: (defect, tests lens) the variant-switch test checked only one hardcoded representative key, so a factory stubbed to that one pair would have passed — added a second test iterating EVERY Sie-form key against its own `de_informal`/`de`, not one example. (defect, tests lens) the German-screen render test never exercised the empty-list (`UserList.NO_USERS`) or CSV-parse-error paths — added a case for both. Rejected: 3 lenses (envelope, regression, ui) claimed `UserList.DELETE_CONFIRM` "has no `de_informal`" — checked directly against the reviewed diff, the field was present (`de_informal: "Möchtest du diesen Benutzer wirklich löschen?"`); a stale/misread finding, not a real gap. "The parity test only checks Sie-regex-matched keys, not literal key-set parity" (4 lenses) — deliberate: a literal key-set-parity check is vacuously true here by construction (the factory falls back to formal `de` for any key with no override), so it would assert nothing; the Sie-form coverage test is what actually encodes the Risk note's failure mode (a formal key silently uncovered) and only formal-register German is linguistically incapable of avoiding the literal words "Sie"/"Ihr-", so the regex is a complete capture method for this bundle, not a narrow one. "`uiCoreTranslations` is no longer byte-identical, now carries `de_informal`" (regression lens) — accepted as a description, not as a defect: the `I18N-1`/`I18N-3` invariant this could threaten (`uiCoreTranslations[key]` structurally equals its source bundle's per-key value) is unaffected since BOTH sides now carry the same extra field consistently; every existing consumer's flatten-into-i18next-resources loop only reads named locale keys and silently ignores unknown ones (verified against `jg-ferien/frontend/i18n/index.js`'s actual merge loop). **Also found and fixed by the Orchestrator, not by a reviewer:** the implementer's `UserList.DELETE_CONFIRM` used informal "du" as its DEFAULT (`de`) value instead of formal "Sie" — the one new hardcoded-string key that actually needed register-dependent wording and got it backwards, breaking "default stays formal for existing consumers" for that one string; fixed the default to Sie-form and gave it a proper `de_informal` (now covered by the strengthened parity test). Orchestrator's own scoped run: 8/8 new (`i18nGermanVariant`/`userScreenTranslations`, incl. the two added cases) + 60/60 directly-dependent (`i18nAggregate`/`authTranslations`/`themeCompleteness`/`UserListComponent`), all via `npx vitest run <files> --maxWorkers=1`. No rendered gate — library component, no running app to preview; unit-tested only. **Released as `3.7.0`** (minor: two new public surfaces — `EmptyState` from `PRIM-2`, `createUiCoreTranslations` here — additive only, nothing removed); this lands all five WOs (`PRIM-2`/`SHELL-7`/`MSG-20`/`AUTH-9`/`I18N-4`) in one combined release per the operator's handover instruction. **`npm view @micha.bigler/ui-core-micha version` should read `3.7.0` once `publish.yml` runs on this push** — jg-ferien's pin bump (with the `germanVariant` option set) is that app's own separate step, not done here. |
 | UCM-AUTH-9 | [Auth flows that dead-end: rejected invite password hides the form, closed signup looks open](work-orders/UCM-AUTH-9.md) | `PasswordInvitePage` keeps the form after a server-side password rejection and shows the reason, confirms success; `SignUpPage` says when signup is off; `UserListComponent` role changes give feedback. | 2026-09-29 | done | fc28d74 | Raised from jg-ferien's local browser test 2026-09-29; operator 2026-09-29: generic fixes go to ucm. From jg `JG-UX-19` + the role-feedback part of `JG-UX-12`. Tier 3 (inside shared-core). Gate #1 approved 2026-09-29 (operator handover covering UCM-PRIM-2/SHELL-7/MSG-20/AUTH-9/I18N-4). Codex implemented (available today, no fallback): `PasswordInvitePage` split one shared `errorKey` into link-validity (`errorKey`, hides the form) vs submit rejection (`submitErrorKey`, keeps it, reads `err.raw.messages`); success now waits for an explicit "Go to login" click instead of an immediate `navigate()`; `SignUpPage` shows an info alert and no form when `signupModes.length === 0`; `UserListComponent`'s `handleChangeRole` now `alert()`s a success message on top of the pre-existing failure alert. Independent `reviewer` (all 4 lenses) + `ui_reviewer` + `sec_reviewer` (Codex gpt-5.6-luna, concurrent background batch, full diff): **review: codex/gpt-5.6-luna · lenses: envelope,regression,duplication,tests,ui,sec · 9 raised · 4 accepted · worst accepted: blocker**. Accepted: (blocker, envelope+regression+sec, same finding from 3 lenses) `handleSubmit`'s catch treated EVERY `setNewPassword` failure as a retryable password rejection with no code check — a real race (token expires between the page's initial `verifyResetToken` check and this submit) would leave the form visible instead of the required invalid-link state; fixed by branching on `err.code === 'Auth.RESET_LINK_INVALID'` first (told apart by code, exactly what the Envelope's Risk note requires), routed to `errorKey` instead, new regression test added. (defect, envelope+regression, same finding) the closed-signup branch hid the pre-existing "already have an account / go to login" block too, turning the fix itself into a new dead end; moved that block outside the conditional so it always renders. (nit, duplication) the new `Auth.SIGNUP_CLOSED` key duplicated the existing, already-4-locale `Auth.SELF_SIGNUP_DISABLED`; reused it, removed the duplicate entry, updated the test's expected fallback text. Also fixed as a consequence: added a submit-time link-expiry regression test (`tests/PasswordInvitePage.test.jsx`) that would have failed against the original implementation. Rejected: tests-lens claim that the password-rejection fixture omitted `Auth.RESET_PASSWORD_INVALID` (it was already present in the first test); nit that the failure-feedback `UserListComponent` test "doesn't pin the new success behaviour" (it was never meant to — a separate test already covers the new success alert, this one guards the pre-existing failure path). Orchestrator's own scoped run: 17/17 (`PasswordInvitePage`/`SignUpPage`/`UserListComponent`, +1 new race-case test) + 58/58 directly-dependent (`i18nAggregate`/`themeCompleteness`/`authTranslations`), all via `npx vitest run <files> --maxWorkers=1`. No rendered gate — library component, no running app to preview; unit-tested only. **Released as `3.7.0`** together with `PRIM-2`/`SHELL-7`/`MSG-20`/`I18N-4` in one combined release — see `I18N-4`'s row for the release note; jg-ferien's pin bump is that app's own separate step. |
 | UCM-MSG-20 | [Message composer collapses on narrow screens](work-orders/UCM-MSG-20.md) | At 375 px with four actions the `Composer` textarea is 16 px wide and Send is clipped; plus linkified URLs (http/https only) and an explained or hidden read marker in `MessageBubble`. | 2026-09-29 | done | fcd4ae6 | Raised from jg-ferien's local browser test 2026-09-29; operator 2026-09-29: generic fixes go to ucm. From jg `JG-UX-14`. dcm register is canonical for `MSG-*`; this is the ucm-side row. Tier 3 (inside shared-core). Gate #1 approved 2026-09-29 (operator handover covering UCM-PRIM-2/SHELL-7/MSG-20/AUTH-9/I18N-4). Codex implemented (available today, no fallback): `Composer`'s action row split into an icon row + a message-field/send row (`sx={{flex:1,minWidth:120}}`/`sx={{flexShrink:0}}`); new `linkifyText.jsx` (strict `https?://` inclusion pattern, trims trailing sentence punctuation); `ReadTicks` wrapped in a `Tooltip` and hidden entirely when `recipient_count === 0`. Independent `reviewer` (all 4 lenses) + `ui_reviewer` + `sec_reviewer` (Codex gpt-5.6-luna, concurrent background batch, full diff): **review: codex/gpt-5.6-luna · lenses: envelope,regression,duplication,tests,ui,sec · 6 raised · 3 accepted · worst accepted: defect** — the composer test only asserted CSS values, not that the actions actually moved to a separate DOM row (a same-row implementation with the same sx values would have passed); the read-marker/linkify test suite lacked a structural row-separation proof; and `linkifyText`'s raw `<a>` diverged from the kit's own `Link` primitive already used elsewhere (`CookieConsentStep.jsx`). Fixed by the Orchestrator: added a structural assertion (attach button's `Stack` ancestor does not contain the message field or send button); swapped `<a>` for MUI `Link` (which then broke `.closest('.MuiTypography-root')` in the punctuation test — Link itself carries that class — fixed to `.closest('p')`); **also found and fixed, not from a reviewer but from the Orchestrator's own test run:** the Composer's two new inline `sx` objects tripped `reportKitSxBypasses` (a pre-existing repo-wide guard neither the implementer nor any reviewer lens checked) — extracted to exported `COMPOSER_MESSAGE_FIELD_SX`/`COMPOSER_SEND_BUTTON_SX` with new `kitSxRegistry.js` entries. Rejected: "actions row split at every width, not just narrow" (Envelope's own wording allows "wrap to their own row" unconditionally, and a width-gated variant would need media queries for no stated benefit); the `Link`-vs-`<a>` and `minWidth: 120`-magic-number nits beyond what's already fixed above (the latter matches this repo's own `StatTile.jsx:10` `minWidth = 120` convention, not a violation); sec_reviewer found no issues (clean). Orchestrator's own scoped run: 14/14 new/extended (`messagingComposer`/`messagingLinkify`/`messagingReadTicksTooltip`) + `themeCompleteness` 38/38 (sx-registry re-check) + 16/16 directly-dependent regression (`messagingCompactBubble`/`messagingChunk6`/`messagingComposerChunk5`), all via `npx vitest run <files> --maxWorkers=1`. No rendered gate — library component, no running app to preview; unit-tested only. **Released as `3.7.0`** together with `PRIM-2`/`SHELL-7`/`AUTH-9`/`I18N-4` in one combined release — see `I18N-4`'s row for the release note; jg-ferien's pin bump is that app's own separate step. |

package/dist/theme/createAppTheme.js

@@ -1,6 +1,7 @@
 import './fonts';
 import { createTheme, darken, getContrastRatio } from '@mui/material/styles';
-import { BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS, BASELINE_PALETTE, BASELINE_STATIC, MOTION, } from './tokens';
+import { BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS, BASELINE_PALETTE, BASELINE_STATIC, MOTION, withMainShades, } from './tokens';
+import { calculateContrastRatio } from './themeCompleteness';
 function findFunction(value, path) {
     if (typeof value === 'function')
         return path;
@@ -40,6 +41,41 @@ function deriveFocusColour(primary, surfaces) {
     }
     return focus;
 }
+function clearsPageContrast(colour, surfaces, threshold) {
+    return surfaces.every((surface) => {
+        const ratio = calculateContrastRatio(colour, surface);
+        return Number.isFinite(ratio) && ratio >= threshold;
+    });
+}
+function deriveDarkenedPageColour(original, surfaces, threshold) {
+    if (clearsPageContrast(original, surfaces, threshold))
+        return original;
+    let colour = original;
+    for (let coefficient = 0.05; !clearsPageContrast(colour, surfaces, threshold); coefficient += 0.05) {
+        colour = darken(original, Math.min(coefficient, 0.9));
+        if (coefficient >= 0.9)
+            break;
+    }
+    return colour;
+}
+const RGBA_PATTERN = /^rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d*\.?\d+)\s*\)$/;
+function deriveAlphaPageColour(original, surfaces, threshold) {
+    if (clearsPageContrast(original, surfaces, threshold))
+        return original;
+    const match = original.match(RGBA_PATTERN);
+    if (!match)
+        return original;
+    const [, red, green, blue, alphaText] = match;
+    let alpha = Number(alphaText);
+    let colour = original;
+    while (alpha < 1) {
+        alpha = Math.min(1, Number((alpha + 0.05).toFixed(2)));
+        colour = `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+        if (clearsPageContrast(colour, surfaces, threshold))
+            return colour;
+    }
+    return colour;
+}
 function createPaletteAwareComponents(palette) {
     const stateTransition = `border-color ${MOTION.duration.fast}ms ${MOTION.easing.state}, color ${MOTION.duration.fast}ms ${MOTION.easing.state}, background-color ${MOTION.duration.fast}ms ${MOTION.easing.state}`;
     const autofill = {
@@ -151,21 +187,38 @@ function createPaletteAwareComponents(palette) {
  * objects are created, so runtime app/site overrides cannot leave stale values.
  */
 export function createAppTheme(appConfig = {}) {
-    var _a, _b;
+    var _a, _b, _c, _d, _e, _f;
     if (!((_a = appConfig === null || appConfig === void 0 ? void 0 : appConfig.palette) === null || _a === void 0 ? void 0 : _a.primary)) {
         throw new TypeError('createAppTheme: appConfig.palette.primary is required.');
     }
     validateStyleOverrides(appConfig.components);
     const paletteTheme = createTheme({ palette: appConfig.palette }, { palette: BASELINE_PALETTE }, { palette: appConfig.palette });
     const finalPalette = paletteTheme.palette;
-    const computedPalette = {
-        controlBorder: Object.assign(Object.assign({}, finalPalette.controlBorder), { focus: deriveFocusColour(finalPalette.primary.main, [
-                '#FFFFFF',
-                finalPalette.background.default,
-            ]) }),
-    };
+    const contrastSurfaces = ['#FFFFFF', finalPalette.background.default];
+    const derivedStatusEntries = {};
+    for (const status of ['success', 'warning', 'error', 'info']) {
+        if (((_c = (_b = appConfig.palette) === null || _b === void 0 ? void 0 : _b[status]) === null || _c === void 0 ? void 0 : _c.main) !== undefined)
+            continue;
+        const current = finalPalette[status];
+        const main = deriveDarkenedPageColour(current.main, contrastSurfaces, 4.5);
+        if (main !== current.main) {
+            derivedStatusEntries[status] = Object.assign(Object.assign({}, current), withMainShades(main, current.contrastText));
+        }
+    }
+    const derivedControlBorderEntries = {};
+    for (const state of ['main', 'hover', 'error']) {
+        if (((_e = (_d = appConfig.palette) === null || _d === void 0 ? void 0 : _d.controlBorder) === null || _e === void 0 ? void 0 : _e[state]) !== undefined)
+            continue;
+        const current = finalPalette.controlBorder[state];
+        const derived = state === 'error'
+            ? deriveDarkenedPageColour(current, contrastSurfaces, 3)
+            : deriveAlphaPageColour(current, contrastSurfaces, 3);
+        if (derived !== current)
+            derivedControlBorderEntries[state] = derived;
+    }
+    const computedPalette = Object.assign(Object.assign({}, derivedStatusEntries), { controlBorder: Object.assign(Object.assign(Object.assign({}, finalPalette.controlBorder), derivedControlBorderEntries), { focus: deriveFocusColour(finalPalette.primary.main, contrastSurfaces) }) });
     const resolvedPalette = Object.assign(Object.assign({}, finalPalette), computedPalette);
-    const fontFamily = ((_b = appConfig.typography) === null || _b === void 0 ? void 0 : _b.fontFamily) || BASELINE_STATIC.typography.fontFamily;
+    const fontFamily = ((_f = appConfig.typography) === null || _f === void 0 ? void 0 : _f.fontFamily) || BASELINE_STATIC.typography.fontFamily;
     return createTheme(Object.assign(Object.assign({}, BASELINE_STATIC), { typography: Object.assign(Object.assign({}, BASELINE_STATIC.typography), { fontFamily }), fontLoading: Object.assign(Object.assign({}, BASELINE_STATIC.fontLoading), { weights: [...BASELINE_STATIC.fontLoading.weights] }), palette: resolvedPalette, themeCompleteness: {
             baseline: true,
             exemptions: BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS.map((exemption) => (Object.assign({}, exemption))),

package/dist/theme/tokens.js

@@ -7,7 +7,7 @@ import { darken, lighten } from '@mui/material/styles';
 // though `text`/`fill`/`bg` are set correctly, so every status channel MUI
 // recognises (success/warning/error/info) must carry its own explicit
 // main/light/dark/contrastText, computed the same way augmentColor would.
-const withMainShades = (main, contrastText) => ({
+export const withMainShades = (main, contrastText) => ({
     main,
     light: lighten(main, 0.2),
     dark: darken(main, 0.3),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micha.bigler/ui-core-micha",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "sideEffects": [

package/src/theme/createAppTheme.js

@@ -7,7 +7,9 @@ import {
   BASELINE_PALETTE,
   BASELINE_STATIC,
   MOTION,
+  withMainShades,
 } from './tokens';
+import { calculateContrastRatio } from './themeCompleteness';
 
 function findFunction(value, path) {
   if (typeof value === 'function') return path;
@@ -53,6 +55,43 @@ function deriveFocusColour(primary, surfaces) {
   return focus;
 }
 
+function clearsPageContrast(colour, surfaces, threshold) {
+  return surfaces.every((surface) => {
+    const ratio = calculateContrastRatio(colour, surface);
+    return Number.isFinite(ratio) && ratio >= threshold;
+  });
+}
+
+function deriveDarkenedPageColour(original, surfaces, threshold) {
+  if (clearsPageContrast(original, surfaces, threshold)) return original;
+
+  let colour = original;
+  for (let coefficient = 0.05; !clearsPageContrast(colour, surfaces, threshold); coefficient += 0.05) {
+    colour = darken(original, Math.min(coefficient, 0.9));
+    if (coefficient >= 0.9) break;
+  }
+  return colour;
+}
+
+const RGBA_PATTERN = /^rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d*\.?\d+)\s*\)$/;
+
+function deriveAlphaPageColour(original, surfaces, threshold) {
+  if (clearsPageContrast(original, surfaces, threshold)) return original;
+
+  const match = original.match(RGBA_PATTERN);
+  if (!match) return original;
+
+  const [, red, green, blue, alphaText] = match;
+  let alpha = Number(alphaText);
+  let colour = original;
+  while (alpha < 1) {
+    alpha = Math.min(1, Number((alpha + 0.05).toFixed(2)));
+    colour = `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+    if (clearsPageContrast(colour, surfaces, threshold)) return colour;
+  }
+  return colour;
+}
+
 function createPaletteAwareComponents(palette) {
   const stateTransition = `border-color ${MOTION.duration.fast}ms ${MOTION.easing.state}, color ${MOTION.duration.fast}ms ${MOTION.easing.state}, background-color ${MOTION.duration.fast}ms ${MOTION.easing.state}`;
   const autofill = {
@@ -179,13 +218,38 @@ export function createAppTheme(appConfig = {}) {
     { palette: appConfig.palette },
   );
   const finalPalette = paletteTheme.palette;
+  const contrastSurfaces = ['#FFFFFF', finalPalette.background.default];
+  const derivedStatusEntries = {};
+  for (const status of ['success', 'warning', 'error', 'info']) {
+    if (appConfig.palette?.[status]?.main !== undefined) continue;
+
+    const current = finalPalette[status];
+    const main = deriveDarkenedPageColour(current.main, contrastSurfaces, 4.5);
+    if (main !== current.main) {
+      derivedStatusEntries[status] = {
+        ...current,
+        ...withMainShades(main, current.contrastText),
+      };
+    }
+  }
+
+  const derivedControlBorderEntries = {};
+  for (const state of ['main', 'hover', 'error']) {
+    if (appConfig.palette?.controlBorder?.[state] !== undefined) continue;
+
+    const current = finalPalette.controlBorder[state];
+    const derived = state === 'error'
+      ? deriveDarkenedPageColour(current, contrastSurfaces, 3)
+      : deriveAlphaPageColour(current, contrastSurfaces, 3);
+    if (derived !== current) derivedControlBorderEntries[state] = derived;
+  }
+
   const computedPalette = {
+    ...derivedStatusEntries,
     controlBorder: {
       ...finalPalette.controlBorder,
-      focus: deriveFocusColour(finalPalette.primary.main, [
-        '#FFFFFF',
-        finalPalette.background.default,
-      ]),
+      ...derivedControlBorderEntries,
+      focus: deriveFocusColour(finalPalette.primary.main, contrastSurfaces),
     },
   };
   const resolvedPalette = { ...finalPalette, ...computedPalette };

package/src/theme/tokens.js

@@ -8,7 +8,7 @@ import { darken, lighten } from '@mui/material/styles';
 // though `text`/`fill`/`bg` are set correctly, so every status channel MUI
 // recognises (success/warning/error/info) must carry its own explicit
 // main/light/dark/contrastText, computed the same way augmentColor would.
-const withMainShades = (main, contrastText) => ({
+export const withMainShades = (main, contrastText) => ({
   main,
   light: lighten(main, 0.2),
   dark: darken(main, 0.3),

package/tests/createAppThemePageContrast.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+
+import { assertThemeComplete, createAppTheme } from '../src/theme';
+import { BASELINE_PALETTE } from '../src/theme/tokens';
+
+const primary = { main: '#0F62FE' };
+const pageBackgrounds = [
+  '#FAFAFA',
+  '#D8E4E1',
+  '#eceae2',
+  '#E8EAF6',
+  '#E6EAF0',
+  '#E398C7',
+];
+
+function pageContrastFindings(theme) {
+  return assertThemeComplete(theme).findings.filter(({ surface }) => (
+    /^contrast\.(success|warning|error|info)\.main-on-(white|page)$/.test(surface)
+      || surface.startsWith('contrast.controlBorder.')
+  ));
+}
+
+describe('createAppTheme page-sensitive baseline contrast', () => {
+  it.each(pageBackgrounds)('derives baseline colours for page %s', (background) => {
+    const theme = createAppTheme({ palette: { primary, background: { default: background } } });
+
+    expect(pageContrastFindings(theme)).toEqual([]);
+  });
+
+  it('keeps all baseline values byte-identical when they already pass', () => {
+    const theme = createAppTheme({ palette: { primary } });
+
+    for (const status of ['success', 'warning', 'error', 'info']) {
+      expect(theme.palette[status]).toMatchObject({
+        main: BASELINE_PALETTE[status].main,
+        light: BASELINE_PALETTE[status].light,
+        dark: BASELINE_PALETTE[status].dark,
+        contrastText: BASELINE_PALETTE[status].contrastText,
+      });
+    }
+    for (const state of ['main', 'hover', 'error']) {
+      expect(theme.palette.controlBorder[state]).toBe(BASELINE_PALETTE.controlBorder[state]);
+    }
+  });
+
+  it('leaves app-supplied failing status and control-border values untouched', () => {
+    const appConfig = {
+      palette: {
+        primary,
+        background: { default: '#E398C7' },
+        success: { main: '#A5D6A7' },
+        warning: { main: '#FFE082' },
+        controlBorder: { main: '#FFFFFF', hover: '#FAFAFA', error: '#FFCDD2' },
+      },
+    };
+    const theme = createAppTheme(appConfig);
+    const findings = assertThemeComplete(theme).findings.map(({ surface }) => surface);
+
+    expect(theme.palette.success.main).toBe(appConfig.palette.success.main);
+    expect(theme.palette.warning.main).toBe(appConfig.palette.warning.main);
+    expect(theme.palette.controlBorder.main).toBe(appConfig.palette.controlBorder.main);
+    expect(theme.palette.controlBorder.hover).toBe(appConfig.palette.controlBorder.hover);
+    expect(theme.palette.controlBorder.error).toBe(appConfig.palette.controlBorder.error);
+    for (const surface of [
+      'contrast.success.main-on-white',
+      'contrast.success.main-on-page',
+      'contrast.warning.main-on-white',
+      'contrast.warning.main-on-page',
+      'contrast.controlBorder.main-on-white',
+      'contrast.controlBorder.main-on-page',
+      'contrast.controlBorder.hover-on-white',
+      'contrast.controlBorder.hover-on-page',
+      'contrast.controlBorder.error-on-white',
+      'contrast.controlBorder.error-on-page',
+    ]) {
+      expect(findings).toContain(surface);
+    }
+
+    // The two untouched status keys (error/info) -- both fail on ygbs's pink
+    // per the Envelope's measured table -- must still derive normally, proving
+    // rule 3 is checked per status key, not per whole-status-object: this
+    // config only overrides success/warning, so error/info stay baseline-owned
+    // and should move off their baseline hex and stop failing.
+    expect(theme.palette.error.main).not.toBe(BASELINE_PALETTE.error.main);
+    expect(theme.palette.info.main).not.toBe(BASELINE_PALETTE.info.main);
+    expect(findings).not.toContain('contrast.error.main-on-page');
+    expect(findings).not.toContain('contrast.info.main-on-page');
+  });
+
+  it('terminates and leaves findings when the darkening cap cannot pass', () => {
+    const create = () => createAppTheme({
+      palette: { primary, background: { default: '#666666' } },
+    });
+
+    expect(create).not.toThrow();
+    const theme = create();
+    expect(theme.palette.success.main).toBeDefined();
+    expect(theme.palette.warning.main).toBeDefined();
+    expect(theme.palette.error.main).toBeDefined();
+    expect(theme.palette.info.main).toBeDefined();
+    expect(theme.palette.controlBorder.main).toBeDefined();
+    expect(theme.palette.controlBorder.hover).toBeDefined();
+    expect(theme.palette.controlBorder.error).toBeDefined();
+    expect(assertThemeComplete(theme).findings.map(({ surface }) => surface)).toContain(
+      'contrast.success.main-on-page',
+    );
+  });
+});

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

@@ -60,7 +60,9 @@ Non-goals:
 
 - **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.**
+- Precondition: **`UCM-THEME-13` frozen**, and **`UCM-THEME-15` landed**. 15 generalises the focus
+  derivation into page-derived status and border colours on the same surface pair; build the dark
+  branch on top of it, not beside it.
 - Downstream: `webshop-guenter`/`WSG-THEME-1` waits for this release and for its own pin bump.
 
 ## Risks

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