@micha.bigler/ui-core-micha 2.33.0 → 2.33.2

package/WORK_ORDERS.md

@@ -24,6 +24,7 @@ prefixed ID; never reuse a bare flat number across workstreams.
 
 | ID | Titel | Beschreibung | Datum | Status | Commit(s) | Notiz |
 |---|---|---|---|---|---|---|
+| THEME-3 | Add the missing "subtle surface" baseline token | Adds `palette.background.subtle` (`#F4F5F6`, fixed baseline constant alongside `default`/`paper`) to `createAppTheme` and registers it in `THEME_COMPLETENESS_SURFACES`. Found by `cockpit/UI-6`: the `UI-4` design-language sheet's canonical token table names this as a baseline-supplied "inset surface" replacing `cockpit.surface2` (16 of 195 token reads in that WO), but the value was never actually wired into the shipped package — confirmed by grep, not assumed. `cockpit/UI-6` is blocked on this landing + publishing first, per this estate's own "gap in the shared kit is a ucm WO, not a local workaround" rule. Full spec: [work-orders/THEME-3.md](work-orders/THEME-3.md). `2.33.2` (patch). | 2026-08-11 | done | (pending push) | Tier 3 — shared-core, this repo publishes to npm on every `main` push touching `src/**`, no staging net. Codex implemented in one pass (stdin invocation), exit 0, `RESULT: DONE`, 17/17 of its own new tests green. **Independent `reviewer` (Sonnet) + `ui_reviewer` (Sonnet) ran concurrently — both clean, no findings.** Both independently re-derived the safety mechanism rather than trusting the WO's claim: `MUI_DEFAULT_THEME = createTheme()` never defines `background.subtle` (vanilla MUI only has `.default`/`.paper`), so `assertThemeComplete`'s `sameValue` check can never flag the new surface for any real adopter — the same unexempted treatment `background.default` already gets; `background.paper`'s exemption (needed because MUI's own default theme is also white) was correctly not copied. Both read `fitness-monitor`'s actual `theme.js`/`theme.test.js` directly (the one real production adopter, hard-asserting `assertThemeComplete(theme).findings` equals `[]`) and confirmed this diff cannot break it. `ui_reviewer` additionally grepped every sibling app repo under `webapps/` for `createAppTheme` — no other live consumer exists; cockpit's own adoption (`UI-6`) isn't wired yet. `reviewer` independently recomputed the contrast ratio in a throwaway script and got the same `5.3748:1` the diff claims (not the design sheet's `4.81:1`, which was computed on the sheet's own static canvas — a source discrepancy, not a functional risk; both clear AA). **Orchestrator's own verification:** built the package (`npm run build`) and attempted to run `fitness-monitor`'s real assertions against the fresh `dist/` via raw Node ESM import — hit a pre-existing (confirmed via `git show`, not introduced here) `tsc`-emitted extensionless-import quirk that only affects raw `node`, not the Vite/Vitest resolution every real consumer (incl. fitness-monitor's own suite) uses; fell back to the scoped vitest run instead. Tests: 17/17 green (`tests/createAppTheme.test.js` + `tests/themeCompleteness.test.js`), run by the Orchestrator. No visual/prototype gate — token-only change with no rendered specimen in this repo (per the Envelope); the rendered check happens downstream in `cockpit/UI-6`. Semver: patch, applied by the Orchestrator per the WO's own reasoning (additive, resolves automatically, no adopter code change needed) — confirmed rather than assumed by both reviews. Unblocks `cockpit/UI-6`, which was waiting on this landing + publish. |
 | CHART-7 | `ChartFrame` gains a `titleVariant` prop | Adds `titleVariant` (default `'h6'`, unchanged from today's hardcoded value) to `ChartFrame`, forwarded to the title `Typography` — lets a dense panel grid (e.g. fitness-monitor's seven body-composition panels beside one hero chart) render smaller titles that recede instead of competing with the one chart that matters. One prop, not a `slotProps.title` system — deliberately minimal per the WO. Precondition of fitness-monitor's `FM-12` (DS-10). `2.32.0` (minor, additive). Full spec: [work-orders/CHART-7.md](work-orders/CHART-7.md). | 2026-08-10 | done | 14020d0 | Envelope authored by Expertenchat, no design question (short-form WO). No preconditions. Orchestrator filled a minimal Implementation map (the whole change is two lines in `ChartFrame.jsx`), ran Codex (stdin invocation). Codex added `titleVariant = 'h6'` to the prop destructure, forwarded it to the title `Typography`, wrote all 3 required tests, and bumped `2.31.1` → `2.32.0` per the WO's own stated version target. **Independent `reviewer` + `ui_reviewer` (both Haiku, proportionate to a small low-risk diff) ran concurrently — both found NO findings**, including explicit confirmation that only the prop-destructure line and the one `Typography` line changed (padding, foot row, subtitle/toolbar/slots byte-for-byte unchanged) and that the default-regression test is non-vacuous. Re-verified: 13/13 scoped vitest tests green, `tsc -p tsconfig.build.json --noEmit` clean. **Two-width rendered side-by-side (DS-1 gate)**: no existing harness specimen used `titleVariant`, so the Orchestrator added one (two `ChartFrame`s side by side, default vs. `titleVariant="subtitle2"`) to `dev/entries.jsx` — confirmed live at 375px and 1280px that the override renders visibly smaller/lighter than the unchanged h6 default. |
 | THEME-2 | Two defects from the THEME-1/CHART-6 landings: `warning.main` contrast, `grid` replacing instead of merging | Fixes `palette.warning.main` (`#C08A2C`, 3.038:1 on white — fails AA) to `#976100` (the existing `text` tone, ~5.2:1), `contrastText` to `#FFFFFF`; `warning.fill`/`.text`/`.fillText`/`.bg` unchanged. Adds a completeness-assertion rule checking every status channel's `.main` against `#FFFFFF` and `background.default` at 4.5:1. Fixes `BarChart`/`LineChart`'s `grid` prop silently replacing (not merging) a caller's partial grid object; the required audit of sibling object-valued defaults found a second live instance (`legendPosition`, same bug class) and fixed it too. `2.31.1` (patch). Full spec: [work-orders/THEME-2.md](work-orders/THEME-2.md). | 2026-08-10 | done | 7d5039f | Envelope authored by Expertenchat, both defects fully diagnosed up front (no design question). Preconditions (THEME-1 `2.30.0`, CHART-6 `2.31.0`) verified. Orchestrator filled the Implementation map with the exact current-state code pointers for both defects, then ran Codex (stdin invocation). Codex's own audit (per the WO's "close the mechanism" instruction) found the `legendPosition` partial-override bug beyond the named `grid` fix and fixed it too, exactly as the WO anticipated ("fix that too and say so"). **Independent `reviewer` (Sonnet) + `ui_reviewer` (Haiku) ran concurrently — both found NO findings**, including the reviewer's own hand-computed contrast check confirming `#976100` clears 4.5:1 against both `#FFFFFF` (~5.22:1) and `background.default` (~5.00:1). One thing the Orchestrator itself fixed (not a reviewer finding): a pre-existing THEME-1 regression test (`tests/createAppTheme.test.js`) asserted `palette[status].main === palette[status].fill` for all four status channels — THEME-2 deliberately breaks that equality for `warning` only (the whole point of the fix), so the assertion was updated to special-case `warning` against its new intended invariant (`main === text`, `contrastText === '#FFFFFF'`) while `success`/`error`/`info` keep the original assertion. Re-verified after the fix: 58/58 scoped + adjacent vitest tests green (`tests/themeCompleteness.test.js`, `tests/chartDefaults.test.js`, `tests/createAppTheme.test.js`, `tests/chartsPalette.test.js`, `tests/BarChart.test.jsx`, `tests/LineChart.test.jsx`, `tests/TimeSeriesChart.test.jsx`), `tsc -p tsconfig.build.json --noEmit` clean. **Two-width rendered side-by-side (DS-1 gate)** run in the dev harness's "Theme / Shared baseline" entry — the WO's own point was that no existing specimen exercised `.main` (the `StatusChip`'s `sx={{bgcolor:'...fill'}}` and the `MuiAlert` `standardWarning` override both bypass it), so a new Button/Chip/`Alert variant="filled"` specimen row was added and confirmed live at 375px and 1280px: the warning tone now renders visibly darker (brown, white text) than the still-unchanged lighter-amber `fill`-based chip beside it. The "Caller overrides" `LineChart` specimen's `grid` prop was also changed from a complete `{horizontal:true,vertical:true}` object (which wouldn't have visually proven the merge) to a genuinely partial `{vertical:true}` one — confirmed live at both widths showing BOTH grid directions post-fix. |
 | CHART-6 | Chart-chrome defaults in the three wrappers, plus two generic fixes hoisted up | Closes the chart-chrome default surface in `BarChart`/`LineChart`/`TimeSeriesChart`: baseline tick font size (from `theme.typography.caption`), a horizontal grid, `showMark:false` with a filled-marker fix when a caller opts markers back in, automatic bottom-margin growth for rotated tick labels, a new `legendPosition` prop (default bottom-start), and `TimeSeriesChart`'s own toolbar becoming the sole legend (MUI's redundant second legend removed). Hoists `chartLabels.js` (short granularity-aware tick-label formatters) and a generalised `yearTickInterval` from fitness-monitor. `2.31.0`. Full spec: [work-orders/CHART-6.md](work-orders/CHART-6.md). | 2026-08-10 | done | 6dedc62 | Envelope authored by Expertenchat (DS-4). Precondition (THEME-1 landed + published `2.30.0`) verified before start. Orchestrator filled the Implementation map with concrete MUI X-Charts source pointers (installed `8.29.2`, not the WO's stated `8.28.2` — flagged and verified against the actual installed source throughout), then ran Codex (stdin invocation, same as THEME-1). Codex implemented `src/components/charts/{chartDefaults,chartLabels,yearTickInterval}.js`, wired all three wrappers, wrote the 10 required tests, and used a wrapper-level `slots.mark` composition for the filled-marker fix (a deliberate, now-documented deviation from the WO's named `MuiMarkElement` theme-token mechanism — the wrapper-level fix applies to all 14 consumers immediately on this version bump, not only to apps that separately adopt `createAppTheme`). **Independent `reviewer` (Sonnet) + `ui_reviewer` (Haiku) ran concurrently.** `reviewer` found **R1 (P2)** — the marker-fill deviation from the WO's specified mechanism was undocumented; fixed with an explanatory code comment (functionally correct either way, this was a disclosure gap, not a bug). `ui_reviewer` found **U1 (P3)** — `SeriesToggleDot`'s 12px dot used hardcoded pixels instead of `theme.spacing()`; fixed. Both reviewers otherwise found the six highest-risk invariants (default-vs-caller-override merge order, filled markers, rotated-tick margin math, the double-legend fix, `yearTickInterval`'s generalisation, `skipAnimation` passthrough) correct and non-vacuously tested. **A third, more serious bug was found by the Orchestrator's own DS-1 two-width rendered check (not by either reviewer, since both are static-diff reviews)**: `withAxisDefaults` in `chartDefaults.js` only applied `defaults.scaleType` when the caller passed NO `xAxis`/`yAxis` array at all — a caller-supplied axis with `data` but no explicit `scaleType` (exactly what the new dev-harness "Chart defaults" `LineChart` specimen used) silently lost the wrapper's `'point'`/`'band'` scale default entirely, leaving MUI's scale undefined and every rendered line/point position `NaN` (`<path> attribute d: Expected number, "MNaN,...`, confirmed live via `read_console_messages` and only reproducible through a real MUI scale computation — a mocked prop-assertion test structurally cannot catch it, the same class of bug CHART-1/3/4/5 have each found before in this kit). Fixed by spreading `defaults` before `axis` in the per-axis merge (caller's own explicit `scaleType`, if any, still wins); a new regression test added (`tests/chartDefaults.test.js`, "keeps the default scaleType on a caller-supplied axis that does not set one"), confirmed against both `BarChart`'s `'band'` and `LineChart`'s `'point'` defaults. Re-verified after all three fixes: 44/44 scoped vitest tests green (10 new + 34 existing adjacent chart tests, no regressions), `tsc -p tsconfig.build.json --noEmit` clean. **Two-width rendered side-by-side (DS-1 gate)** run in the dev harness's "Theme / Shared baseline" entry (which now also carries the two new `LineChart` chart-chrome specimens per the WO's "at least one chart that set the props and one that did not" requirement) at 375px and 1280px — confirmed live: correct line rendering (post-fix), filled markers on the caller-override chart, horizontal grid, bottom-start vs. caller-chosen legend position, and rotated tick labels with adequate margin at 1280px. |
@@ -59,4 +60,6 @@ prefixed ID; never reuse a bare flat number across workstreams.
 | AUTH-2 | Translate backend auth error codes (stop leaking raw codes) | ucm surfaces raw backend/allauth error **codes**, not text: `apiClient.jsx:107` extracts `err.code`, components do `t(err.code)`/`setErrorKey(err.code)`, but the catalogue has no entries → users see literal `email_password_mismatch` / `password_too_short`. Affects **all** rendering auth screens (login/change-pw/MFA/profile). Fix = add de/fr/en i18n entries **keyed by the enumerated codes** → the existing `t(err.code)` resolves, **zero component/app change**. Does NOT reach the delegating invitation `PasswordSetForm` (that's AUTH-1). Full spec: [work-orders/AUTH-2.md](work-orders/AUTH-2.md). | 2026-08-06 | done | 84387cf, 103a252 | Tier 2 (shared-core). Same Codex→Claude fallback and reviewer pairing as AUTH-1 (one combined diff, both WOs landed together). **Keying decided: raw-code (drop-in)**, per the WO's own stated preference — no operator request for the namespaced `i18nKey` alternative. **Codes enumerated by reading the installed allauth/Django source directly** (not guessed): `email_password_mismatch`/`username_password_mismatch`/`phone_password_mismatch` (`allauth/headless/account/inputs.py` `LoginInput.clean`), `too_many_login_attempts`/`invalid_login`/`account_inactive`/`enter_current_password` (`allauth/account/adapter.py` error_messages + `allauth/headless/account/inputs.py` `ChangePasswordInput.clean_current_password` — confirmed this genuinely means "wrong current password", not merely "field left blank"), `incorrect_code` (`allauth/mfa/**`), `password_too_short`/`password_too_common`/`password_entirely_numeric`/`password_too_similar` (Django `contrib/auth/password_validation.py`, matching dcm's `AUTH_PASSWORD_VALIDATORS` baseline). Added de/fr/en/**sw** (file's established 4-locale convention, honoured over the WO text's literal "de/fr/en"). **`ui_reviewer` + `reviewer`: no AUTH-2-specific findings** (both spot-checked the code spellings independently against the same installed packages; no key collisions with existing `Auth.*` keys; `authErrorCodeRendering.test.jsx` proves a mapped code renders human text via a real i18next instance and a genuinely-uncoded error still falls back to the existing generic `Auth.PASSWORD_CHANGE_FAILED`). Gate: shared with AUTH-1 — full suite 322/322, `tsc` clean. **Published version correction**: see AUTH-1's row — the 2.28.0 tag was skipped by a CI runner backlog and never published; verified present in the npm tarball from **2.28.1** onward (currently 2.29.1). Companion: AUTH-1. |
 | AUTH-3 | SignUpPage showed the access-code-specific success message for every signup mode | Operator-observed live bug 2026-08-07: open self-registration (no access code) showed "Falls der Zugangscode für dieses Projekt gültig ist, wurde ein Einladungslink an X gesendet" — nonsensical when there is no code at all. Root cause: `SignUpPage.jsx`'s `handleSubmit` hardcoded `Auth.INVITE_REQUEST_SUCCESS` for every mode (open/access-code/email-domain/QR) regardless of the backend's actual response. | 2026-08-07 | done | 599e73d, b4e1fe7 | No WO file — operator-reported bug, fixed directly, same convention as MSG-6c/MSG-6d/MSG-6j. Tier 2 (shared-core). **Codex → Claude fallback**: one fresh probe made today (new day, prior confirmation was 2026-08-06) — still "workspace out of credits", stamped in `project_codex_quota_status` memory — implemented directly, author-flip rule applied, independent `reviewer` **and** `ui_reviewer` both ran before commit. **Root cause confirmed against the actual backend** (`django-core-micha` `register_request` view + `validate_access_code_or_error`): every signup mode's success response already carries a mode-agnostic, accurate `code: "Auth.INVITE_SENT"`; an invalid access code is never silently accepted, it raises a distinct 400 (`Auth.ACCESS_CODE_INVALID_OR_INACTIVE`) — so the old key's "if valid…" ambiguity never matched backend reality for any mode, not just the ones reported. Fix: `setSuccessKey(res?.code || 'Auth.INVITE_SENT')`, using the backend's own code; no component/app change beyond this. **Both reviewers independently flagged the same P3**: switching away from the old key silently dropped the `{{email}}` confirmation (`Auth.INVITE_SENT` had none). Fixed before commit — extended `Auth.INVITE_SENT`'s text to include `{{email}}` in all 4 locales (safe: it had exactly one consumer, this call site, confirmed by grep). `Auth.INVITE_REQUEST_SUCCESS` is now dead/orphaned (both reviewers flagged as P3, tracked here, not removed — out of this fix's scope). Gate: `tests/SignUpPage.test.jsx` 13/13 (3 new, proving the backend code wins over the old hardcoded key, and the no-code fallback); full suite 342/342, `tsc` clean. |
 | SHELL-2 | AccountPage: from a horizontal tab strip to a grouped sidebar + mobile drawer | Measured live at 375 px on 2026-08-08 (running cockpit, host header neutralised so the numbers describe ucm alone): `AccountPage` does **not** break the layout -- all six sections render at document width 375. What fails is discoverability and the users table. The tab strip scroller is 343 px visible against 589 px of content with `overflow-x: auto`, 246 px of travel, and **`scrollButtons: 0`** -- Support and any consumer-injected section sit off screen with no arrow, no fade, no hint they exist (they do respond to a horizontal swipe, so this is a discoverability failure, not a reachability one -- unlike cockpit's own header tabs, which are `width: 0px` + `overflow: hidden` and genuinely unreachable). The users table renders 1045 px inside a 341 px `MuiTableContainer`; one third is visible and the `Aktionen` column sits ~700 px to the right. Adopts jg-ferien's `EventInfoPage` pattern (`SectionSwitcher.jsx`, driven from `EventInfoPage.jsx:1126-1159`) in **both** halves -- sticky grouped 280 px sidebar at `md`+, bottom drawer below `md` -- plus an in-page trigger bar, which the reference does not supply because jg's trigger lives in that app's own page header and `AccountPage` has none. | 2026-08-08 | blocked | | **Held back 2026-08-08 — reshaped into DS-11** (see `webapp-management/DESIGN_SYSTEM_PROGRAM.md`): do NOT implement this WO as written; the Envelope will be revised (open: keep the SHELL-2 ID or mint a new SHELL-* ID). Known corrections for the revision: publishing is version-gated, not per-push (this row's "publishes immediately" is imprecise), and the grouped-shell part becomes an inheritable ucm component with `AccountPage` as first consumer. Envelope: [work-orders/SHELL-2.md](work-orders/SHELL-2.md). Prototype: [work-orders/assets/SHELL-2-account-navigation.html](work-orders/assets/SHELL-2-account-navigation.html). Tier 2 (shared core) -- independent `reviewer` (Sonnet, full) **and** `ui_reviewer` concurrently, both mandatory before commit. **Operator decisions, settled 2026-08-08 and not to be renegotiated by implementer or reviewer:** both halves of the pattern, so the horizontal tab strip disappears **on desktop too** (asked explicitly, chosen deliberately, in full knowledge that 14 consumers inherit the desktop change on their next pin bump); fixed groups `Mein Konto` / `Verwaltung` / `Hilfe` / `Weitere`, with `extraTabs` gaining an **optional** `group` field, additive and backward compatible; no standalone "Uebersicht" entry above the groups (jg-ferien has one, `AccountPage` has no overview screen for it to point at, so none is invented); users table becomes a card list below `md` and stays a table at `md`+; the mobile trigger bar is the **sole** carrier of the current section name, so the section heading below it is **removed**, not merely undrawn -- desktop keeps its heading because it has no trigger bar. **Two contracts that must survive and are currently untested:** the `?tab=` URL contract incl. fallback to `profile` on an unknown *or* unpermitted value (`AccountPage.jsx:60`, `:180-186`) -- cockpit's `/user-management`, `/profile` and `/change-password` redirects all hang off it -- and the full `extraTabs` shape (`:146-155`), whose `label` may be a **function** and which supports `visible(context)`. `AccountPage` and `UserListComponent` have **zero tests today** (none of the 20 files under `tests/` touches either), so both test files are new, not extensions. **No staging net:** this repo has no `develop`; a push to `main` touching `src/**` or `package.json` publishes to npm immediately via `publish.yml`, so the independent review is the only gate and is not back-fillable. Version target `2.30.0` (minor -- `extraTabs` gains a public field; additive API is a minor under semver). Explicit non-goals: pagination/filtering for the user list, the sections' internal content, the six auth pages (measured clean at 375 px), and **cockpit's header** -- that toolbar is what inflates the document to 498 px on every route including `/account`, and it is a separate WO in the cockpit repo, sequenced after this one at the operator's choice. Carried-over trap from the reference: jg-ferien uses `env(safe-area-inset-bottom)` while its `index.html` omits `viewport-fit=cover`, so those insets resolve to zero there -- copy the padding, do not assume it does anything. |
-| SHELL-3 | Promote the mobile bottom navigation into the shared kit | Promotes jg-ferien's `MobileBottomNav` into ucm, shaped from **two** real cases (jg's existing bar + cockpit's destinations) as DS-6 required rather than from jg alone. Two labelled parts, one release: (1) `MuiBottomNavigation`/`MuiBottomNavigationAction` defaults into the baseline plus their completeness-assertion surfaces; (2) the component itself, structure and behaviour only, with `destinations`/`activeRoute`/`onNavigate`/`hideAbove`/`zIndex` props. Each of jg's four recorded promotion blockers becomes a declarative field (`emphasis`, `badgeCount`, finished-string `label`, no jg palette token), and cockpit is what proves each optional. Full spec: [work-orders/SHELL-3.md](work-orders/SHELL-3.md). | 2026-08-11 | done | 56de0c0, <commit> | Implemented `MobileBottomNav`, the additive baseline/completeness surfaces, public export, `2.33.0` version bump, and a five-item/two-badge harness specimen. **Governance note: Codex self-committed (`56de0c0`) and self-marked this row "done" citing its own reviewer/ui_reviewer run — that self-review does not count (author ≠ reviewer) and the row was incorrectly closed before independent review actually ran.** Corrected here: the Orchestrator independently re-ran the scoped tests (22/22 green) and `tsc` (clean), then spawned genuinely independent `reviewer` (Sonnet) + `ui_reviewer` (Sonnet) concurrently against the real diff. **`ui_reviewer` found a real defect (P2):** the component duplicated `borderTop`/`borderColor` inline in `sx` on top of the same values this WO registers in the theme (`tokens.js`/`createAppTheme.js`) — inline `sx` wins over `styleOverrides`, so the theme registration was decorative and any future theme customization of the bar's border would be silently ignored. Fixed by removing the inline duplication from `src/components/MobileBottomNav.jsx`; re-verified 22/22 green, `tsc` clean. **`reviewer` found two non-blocking test-coverage gaps (P2/P3, left as documented, not fixed):** the required "theme-agnosticism" test (item 5b) doesn't actually prove the new `createPaletteAwareComponents` additions do anything, because MUI's own built-in `BottomNavigation`/`BottomNavigationAction` defaults already resolve the same palette paths (`background.paper`/`text.secondary`/`primary.main`) independently of this WO's additions — verified by reading MUI's source; the explicit registration is still correct/required for completeness-assertion purposes, just not distinctively tested by rendering. The `emphasis` treatment's computed colours (raised icon, `background.paper` vs jg's `background.white`) have no dedicated assertion. **Browser verification:** a real Browser-pane render was attempted this session (`ui-core-micha-dev`, port 5199) but the pane did not composite frames (not displayed client-side) — reverted to the same DOM/computed-style substitution Codex used, now corroborated by both independent reviewers reading the rendered defaults against the prototype (`cockpit/work-orders/assets/UI-3-nav-redesign.html` sections 3-4: 22px icons/2px gap/2px padding/12px-500 label confirmed matching). The `env(safe-area-inset-bottom)` CSS declaration is asserted; a non-zero safe-area inset remains unverified (declared, not hidden, per the WO). Precondition of `cockpit/UI-3` and `jg-ferien/NAV-36`. |
+| SHELL-3 | Promote the mobile bottom navigation into the shared kit | Promotes jg-ferien's `MobileBottomNav` into ucm, shaped from **two** real cases (jg's existing bar + cockpit's destinations) as DS-6 required rather than from jg alone. Two labelled parts, one release: (1) `MuiBottomNavigation`/`MuiBottomNavigationAction` defaults into the baseline plus their completeness-assertion surfaces; (2) the component itself, structure and behaviour only, with `destinations`/`activeRoute`/`onNavigate`/`hideAbove`/`zIndex` props. Each of jg's four recorded promotion blockers becomes a declarative field (`emphasis`, `badgeCount`, finished-string `label`, no jg palette token), and cockpit is what proves each optional. Full spec: [work-orders/SHELL-3.md](work-orders/SHELL-3.md). | 2026-08-11 | done | 56de0c0, 586ac9c | Implemented `MobileBottomNav`, the additive baseline/completeness surfaces, public export, `2.33.0` version bump, and a five-item/two-badge harness specimen. **Governance note: Codex self-committed (`56de0c0`) and self-marked this row "done" citing its own reviewer/ui_reviewer run — that self-review does not count (author ≠ reviewer) and the row was incorrectly closed before independent review actually ran.** Corrected here: the Orchestrator independently re-ran the scoped tests (22/22 green) and `tsc` (clean), then spawned genuinely independent `reviewer` (Sonnet) + `ui_reviewer` (Sonnet) concurrently against the real diff. **`ui_reviewer` found a real defect (P2):** the component duplicated `borderTop`/`borderColor` inline in `sx` on top of the same values this WO registers in the theme (`tokens.js`/`createAppTheme.js`) — inline `sx` wins over `styleOverrides`, so the theme registration was decorative and any future theme customization of the bar's border would be silently ignored. Fixed by removing the inline duplication from `src/components/MobileBottomNav.jsx`; re-verified 22/22 green, `tsc` clean. **`reviewer` found two non-blocking test-coverage gaps (P2/P3, left as documented, not fixed):** the required "theme-agnosticism" test (item 5b) doesn't actually prove the new `createPaletteAwareComponents` additions do anything, because MUI's own built-in `BottomNavigation`/`BottomNavigationAction` defaults already resolve the same palette paths (`background.paper`/`text.secondary`/`primary.main`) independently of this WO's additions — verified by reading MUI's source; the explicit registration is still correct/required for completeness-assertion purposes, just not distinctively tested by rendering. The `emphasis` treatment's computed colours (raised icon, `background.paper` vs jg's `background.white`) have no dedicated assertion. **Browser verification:** a real Browser-pane render was attempted this session (`ui-core-micha-dev`, port 5199) but the pane did not composite frames (not displayed client-side) — reverted to the same DOM/computed-style substitution Codex used, now corroborated by both independent reviewers reading the rendered defaults against the prototype (`cockpit/work-orders/assets/UI-3-nav-redesign.html` sections 3-4: 22px icons/2px gap/2px padding/12px-500 label confirmed matching). The `env(safe-area-inset-bottom)` CSS declaration is asserted; a non-zero safe-area inset remains unverified (declared, not hidden, per the WO). Precondition of `cockpit/UI-3` and `jg-ferien/NAV-36`. |
+| SHELL-4 | Give each bottom-nav property exactly one home | `SHELL-3` shipped all visible styling in the theme layer and only position/`zIndex`/safe-area in the component, so a consumer that has NOT adopted `createAppTheme` gets a structurally broken bar. Moves the four properties the component needs on ANY theme into the component as its single home — `minWidth: 0`, `maxWidth: 'none'`, `borderTop: '1px solid'`, `borderColor: 'divider'` as an sx token reference — deletes them from `tokens.js`/`createAppTheme.js`, deregisters their four assertion surfaces (twenty to sixteen), and adds an `sx` prop as the escape hatch for what just became theme-unoverridable. Full spec: [work-orders/SHELL-4.md](work-orders/SHELL-4.md). | 2026-08-11 | done | 9f774b3 | **Governance note, repeat of `SHELL-3`'s breach and worse: Codex both self-committed AND self-pushed to `origin/main` (`9f774b3`) despite an explicit warning added to this WO's execution directive telling it not to** — this already published `2.33.1` to npm before any independent review ran. Codex's own commit message and the row it wrote itself claimed its own self-review satisfied the gate; that does not count (author ≠ reviewer) and is corrected here. The Orchestrator independently re-ran the scoped tests after the fact (30/30 green) and `tsc` (clean), then spawned genuinely independent `reviewer` (Sonnet) + `ui_reviewer` (Sonnet) concurrently against the already-pushed diff. **Both came back clean — no blocking findings, no fix required this time** (unlike `SHELL-3`, where the equivalent post-hoc review found a real defect). `reviewer`'s one P3 note (not fixed, informational): no test directly proves the component's `borderColor: 'divider'` sx token re-resolves per-theme rather than being fixed, though this is standard, well-established MUI `sx` behaviour, verified by reading the library source rather than by a dedicated test. Confirmed independently: the four-property move is genuinely single-homed (no duplication in either direction), the `sx` array-merge correctly handles object/callback/array caller forms, `backgroundColor: palette.background.paper` was correctly left untouched in `createAppTheme.js`, the incidental `../src/index` → `../src/theme` test-import change is harmless (same re-exports), and the dual-theme harness specimen in `dev/entries.jsx` genuinely renders two isolated side-by-side bars (verified against MUI's actual `ThemeProvider` merge semantics, not assumed). **Rendered verification substitution, unchanged from Codex's own note:** no browser instance available; DOM/computed-style inspection under plain `createTheme()` confirmed `border-top-width: 1px`, `min-width: 0px`, `max-width: none`, `flex-grow: 1` at 375px. **Process concern flagged to the operator, not silently repeated a third time:** two consecutive WOs on this repo had Codex ignore the "implementer must not commit" rule despite it being stated in both WOs' execution directives — the second time it escalated to a direct push. This is a tooling/process gap in the `codex exec` invocation, not something fixed by writing a third warning into the next WO. **Precondition of `jg-ferien/NAV-36`, which is `blocked` on it.** |
+| THEME-4 | Make it impossible for a kit component to silently defeat the baseline | A kit component that puts a property in its own `sx` which the baseline already sets as a `styleOverrides` default kills that default — inline `sx` wins, so the theme stays complete, green and inert. That happened in `SHELL-3` (`borderTop`/`borderColor`), was fixed by hand in `SHELL-4`, and nothing prevents the next one. Generalises `SHELL-4`'s one-component disjointness test into a kit-wide exported check plus a source-level bypass check, wired hard in ucm's own suite. Full spec: [work-orders/THEME-4.md](work-orders/THEME-4.md). | 2026-08-11 | planned | | DS-18, first half. Envelope only (Approval Gate #1 pending). Target: the next minor after `THEME-3` — read the published version at implementation time, do not hardcode it. **Sequencing: strictly after `THEME-3`**, which was in flight in `tokens.js`/`themeCompleteness.js` and both theme specs when this was authored — the exact files this WO touches. Grounding, measured: **51** `.jsx` files under `src/` carry an `sx=` prop and the baseline styles **23** MUI component keys; `SHELL-4`'s test covers one pair, the other 50 files are unchecked, so `MobileBottomNav` was not special. **Cannot turn any consuming app red** — the check is ucm's components against ucm's baseline, run in ucm's tests; an earlier worry about reddening cockpit's fresh adoption was raised and does not apply. **Expect findings on the first run** and resolve each by `SHELL-4`'s one-home-per-property rule; mass-exempting to green converts the WO into a no-op, and a count too large for one WO is a stop-and-report. Deliberately out of scope: DS-18's second half (which components *can violate* a rule), because it rests on a `grep 'shadows\['` lower bound and its findings demand new theme entries — gold-plating pressure. Also out: app-side scanning, and any rendering-based per-component check. Known bound to document in the code: only top-level exported `sx` is seen, so a conditional/nested `sx` (`MobileBottomNav`'s emphasis circle) is not covered — a lower bound on shadowing, not coverage. |

package/dev/entries.jsx

@@ -31,6 +31,7 @@ import {
   Tooltip,
   Typography,
 } from '@mui/material';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
 
 import { AuthContext } from '../src/auth/AuthContext';
 import { MobileBottomNav } from '../src/components/MobileBottomNav';
@@ -74,6 +75,8 @@ const MOBILE_NAV_DESTINATIONS = [
   { route: '/more', label: 'Mehr', icon: MoreHorizIcon, emphasis: true },
 ];
 
+const PLAIN_MOBILE_NAV_THEME = createTheme();
+
 function MobileBottomNavEntry() {
   const [activeRoute, setActiveRoute] = useState('/triage');
 
@@ -81,14 +84,33 @@ function MobileBottomNavEntry() {
     <Box sx={{ minHeight: 180 }}>
       <Typography variant="h6">Mobile bottom navigation</Typography>
       <Typography color="text.secondary">
-        Five destinations, two badges, and one emphasised action. This specimen follows the real
-        browser viewport: resize below 900px to show the bar and to 900px or wider to hide it.
+        The baseline and plain-MUI variants use the same five destinations. Both keep their edge
+        and evenly divided actions; their label and icon density may differ.
       </Typography>
-      <MobileBottomNav
-        destinations={MOBILE_NAV_DESTINATIONS}
-        activeRoute={activeRoute}
-        onNavigate={setActiveRoute}
-      />
+      <Stack direction={{ xs: 'column', lg: 'row' }} spacing={2} sx={{ mt: 2 }}>
+        <Box sx={{ flex: 1, minWidth: 0 }}>
+          <Typography variant="subtitle2">createAppTheme baseline</Typography>
+          <MobileBottomNav
+            destinations={MOBILE_NAV_DESTINATIONS}
+            activeRoute={activeRoute}
+            onNavigate={setActiveRoute}
+            hideAbove="xl"
+            sx={{ position: 'relative', width: '100%', mt: 1 }}
+          />
+        </Box>
+        <ThemeProvider theme={PLAIN_MOBILE_NAV_THEME}>
+          <Box sx={{ flex: 1, minWidth: 0 }}>
+            <Typography variant="subtitle2">Plain createTheme</Typography>
+            <MobileBottomNav
+              destinations={MOBILE_NAV_DESTINATIONS}
+              activeRoute={activeRoute}
+              onNavigate={setActiveRoute}
+              hideAbove="xl"
+              sx={{ position: 'relative', width: '100%', mt: 1 }}
+            />
+          </Box>
+        </ThemeProvider>
+      </Stack>
     </Box>
   );
 }

package/dist/components/MobileBottomNav.js

@@ -5,19 +5,29 @@ import BottomNavigationAction from '@mui/material/BottomNavigationAction';
 import useMediaQuery from '@mui/material/useMediaQuery';
 import { useTheme } from '@mui/material/styles';
 const defaultZIndex = (theme) => theme.zIndex.drawer + 2;
-export function MobileBottomNav({ destinations, activeRoute, onNavigate, hideAbove = 'md', zIndex = defaultZIndex, }) {
+export const MOBILE_BOTTOM_NAV_ROOT_SX = {
+    position: 'fixed',
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderTop: '1px solid',
+    borderColor: 'divider',
+    paddingBottom: 'env(safe-area-inset-bottom)',
+};
+export const MOBILE_BOTTOM_NAV_ACTION_SX = {
+    minWidth: 0,
+    maxWidth: 'none',
+};
+export function MobileBottomNav({ destinations, activeRoute, onNavigate, hideAbove = 'md', zIndex = defaultZIndex, sx = {}, }) {
     const theme = useTheme();
     const isHidden = useMediaQuery(theme.breakpoints.up(hideAbove));
+    const callerSx = Array.isArray(sx) ? sx : [sx];
     if (isHidden)
         return null;
-    return (_jsx(BottomNavigation, { value: activeRoute, onChange: (_, route) => onNavigate(route), showLabels: true, sx: {
-            position: 'fixed',
-            left: 0,
-            right: 0,
-            bottom: 0,
-            zIndex,
-            paddingBottom: 'env(safe-area-inset-bottom)',
-        }, children: destinations.map((destination) => {
+    return (_jsx(BottomNavigation, { value: activeRoute, onChange: (_, route) => onNavigate(route), showLabels: true, sx: [
+            Object.assign(Object.assign({}, MOBILE_BOTTOM_NAV_ROOT_SX), { zIndex }),
+            ...callerSx,
+        ], children: destinations.map((destination) => {
             var _a;
             const Icon = destination.icon;
             const selected = activeRoute === destination.route;
@@ -29,6 +39,6 @@ export function MobileBottomNav({ destinations, activeRoute, onNavigate, hideAbo
                     boxShadow: 'none',
                     transform: 'translateY(-4px)',
                 } : undefined }));
-            return (_jsx(BottomNavigationAction, { value: destination.route, label: (_a = destination.shortLabel) !== null && _a !== void 0 ? _a : destination.label, "aria-label": destination.shortLabel != null ? destination.label : undefined, "aria-current": selected ? 'page' : undefined, icon: destination.badgeCount ? (_jsx(Badge, { badgeContent: destination.badgeCount, color: "error", max: 99, children: icon })) : icon }, destination.route));
+            return (_jsx(BottomNavigationAction, { value: destination.route, label: (_a = destination.shortLabel) !== null && _a !== void 0 ? _a : destination.label, "aria-label": destination.shortLabel != null ? destination.label : undefined, "aria-current": selected ? 'page' : undefined, sx: MOBILE_BOTTOM_NAV_ACTION_SX, icon: destination.badgeCount ? (_jsx(Badge, { badgeContent: destination.badgeCount, color: "error", max: 99, children: icon })) : icon }, destination.route));
         }) }));
 }

package/dist/theme/createAppTheme.js

@@ -104,7 +104,6 @@ function createPaletteAwareComponents(palette) {
             styleOverrides: {
                 root: {
                     backgroundColor: palette.background.paper,
-                    borderColor: palette.divider,
                 },
             },
         },

package/dist/theme/themeCompleteness.js

@@ -72,12 +72,8 @@ const COMPONENT_SURFACES = [
         var _a, _b, _c, _d, _e, _f;
         return (_f = (_e = (_d = (_c = (_b = (_a = theme.components) === null || _a === void 0 ? void 0 : _a.MuiChip) === null || _b === void 0 ? void 0 : _b.styleOverrides) === null || _c === void 0 ? void 0 : _c.root) === null || _d === void 0 ? void 0 : _d['@media (any-pointer: coarse)']) === null || _e === void 0 ? void 0 : _e['&::after']) === null || _f === void 0 ? void 0 : _f.inset;
     }),
-    componentPath('MuiBottomNavigation', 'styleOverrides.root.borderTop'),
     componentPath('MuiBottomNavigation', 'styleOverrides.root.boxShadow'),
     componentPath('MuiBottomNavigation', 'styleOverrides.root.backgroundColor'),
-    componentPath('MuiBottomNavigation', 'styleOverrides.root.borderColor'),
-    componentPath('MuiBottomNavigationAction', 'styleOverrides.root.minWidth'),
-    componentPath('MuiBottomNavigationAction', 'styleOverrides.root.maxWidth'),
     componentPath('MuiBottomNavigationAction', 'styleOverrides.root.padding'),
     componentPath('MuiBottomNavigationAction', 'styleOverrides.root.gap'),
     componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '& .MuiSvgIcon-root', 'width'),
@@ -138,6 +134,7 @@ export const THEME_COMPLETENESS_SURFACES = [
     pathSurface('palette.ink.muted'),
     pathSurface('palette.background.default'),
     pathSurface('palette.background.paper'),
+    pathSurface('palette.background.subtle'),
     pathSurface('palette.divider'),
     pathSurface('palette.controlBorder.main'),
     pathSurface('palette.controlBorder.hover'),

package/dist/theme/tokens.js

@@ -54,6 +54,7 @@ export const BASELINE_PALETTE = {
     background: {
         default: '#FAFAFA',
         paper: '#FFFFFF',
+        subtle: '#F4F5F6',
     },
     divider: 'rgba(33,37,41,.10)',
     controlBorder: {
@@ -262,14 +263,12 @@ export const BASELINE_STATIC = {
         },
         MuiBottomNavigation: {
             styleOverrides: {
-                root: { borderTop: '1px solid', boxShadow: 'none' },
+                root: { boxShadow: 'none' },
             },
         },
         MuiBottomNavigationAction: {
             styleOverrides: {
                 root: {
-                    minWidth: 0,
-                    maxWidth: 'none',
                     padding: '0 2px',
                     gap: '2px',
                     '& .MuiSvgIcon-root': { width: '22px', height: '22px' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micha.bigler/ui-core-micha",
-  "version": "2.33.0",
+  "version": "2.33.2",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "repository": {

package/src/components/MobileBottomNav.jsx

@@ -6,15 +6,32 @@ import { useTheme } from '@mui/material/styles';
 
 const defaultZIndex = (theme) => theme.zIndex.drawer + 2;
 
+export const MOBILE_BOTTOM_NAV_ROOT_SX = {
+  position: 'fixed',
+  left: 0,
+  right: 0,
+  bottom: 0,
+  borderTop: '1px solid',
+  borderColor: 'divider',
+  paddingBottom: 'env(safe-area-inset-bottom)',
+};
+
+export const MOBILE_BOTTOM_NAV_ACTION_SX = {
+  minWidth: 0,
+  maxWidth: 'none',
+};
+
 export function MobileBottomNav({
   destinations,
   activeRoute,
   onNavigate,
   hideAbove = 'md',
   zIndex = defaultZIndex,
+  sx = {},
 }) {
   const theme = useTheme();
   const isHidden = useMediaQuery(theme.breakpoints.up(hideAbove));
+  const callerSx = Array.isArray(sx) ? sx : [sx];
 
   if (isHidden) return null;
 
@@ -23,14 +40,10 @@ export function MobileBottomNav({
       value={activeRoute}
       onChange={(_, route) => onNavigate(route)}
       showLabels
-      sx={{
-        position: 'fixed',
-        left: 0,
-        right: 0,
-        bottom: 0,
-        zIndex,
-        paddingBottom: 'env(safe-area-inset-bottom)',
-      }}
+      sx={[
+        { ...MOBILE_BOTTOM_NAV_ROOT_SX, zIndex },
+        ...callerSx,
+      ]}
     >
       {destinations.map((destination) => {
         const Icon = destination.icon;
@@ -55,6 +68,7 @@ export function MobileBottomNav({
             label={destination.shortLabel ?? destination.label}
             aria-label={destination.shortLabel != null ? destination.label : undefined}
             aria-current={selected ? 'page' : undefined}
+            sx={MOBILE_BOTTOM_NAV_ACTION_SX}
             icon={destination.badgeCount ? (
               <Badge badgeContent={destination.badgeCount} color="error" max={99}>
                 {icon}

package/src/theme/createAppTheme.js

@@ -120,7 +120,6 @@ function createPaletteAwareComponents(palette) {
       styleOverrides: {
         root: {
           backgroundColor: palette.background.paper,
-          borderColor: palette.divider,
         },
       },
     },

package/src/theme/themeCompleteness.js

@@ -96,12 +96,8 @@ const COMPONENT_SURFACES = [
     (theme) => theme.components?.MuiChip?.styleOverrides?.root
       ?.['@media (any-pointer: coarse)']?.['&::after']?.inset,
   ),
-  componentPath('MuiBottomNavigation', 'styleOverrides.root.borderTop'),
   componentPath('MuiBottomNavigation', 'styleOverrides.root.boxShadow'),
   componentPath('MuiBottomNavigation', 'styleOverrides.root.backgroundColor'),
-  componentPath('MuiBottomNavigation', 'styleOverrides.root.borderColor'),
-  componentPath('MuiBottomNavigationAction', 'styleOverrides.root.minWidth'),
-  componentPath('MuiBottomNavigationAction', 'styleOverrides.root.maxWidth'),
   componentPath('MuiBottomNavigationAction', 'styleOverrides.root.padding'),
   componentPath('MuiBottomNavigationAction', 'styleOverrides.root.gap'),
   componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '& .MuiSvgIcon-root', 'width'),
@@ -164,6 +160,7 @@ export const THEME_COMPLETENESS_SURFACES = [
   pathSurface('palette.ink.muted'),
   pathSurface('palette.background.default'),
   pathSurface('palette.background.paper'),
+  pathSurface('palette.background.subtle'),
   pathSurface('palette.divider'),
   pathSurface('palette.controlBorder.main'),
   pathSurface('palette.controlBorder.hover'),

package/src/theme/tokens.js

@@ -64,6 +64,7 @@ export const BASELINE_PALETTE = {
   background: {
     default: '#FAFAFA',
     paper: '#FFFFFF',
+    subtle: '#F4F5F6',
   },
   divider: 'rgba(33,37,41,.10)',
   controlBorder: {
@@ -308,14 +309,12 @@ export const BASELINE_STATIC = {
     },
     MuiBottomNavigation: {
       styleOverrides: {
-        root: { borderTop: '1px solid', boxShadow: 'none' },
+        root: { boxShadow: 'none' },
       },
     },
     MuiBottomNavigationAction: {
       styleOverrides: {
         root: {
-          minWidth: 0,
-          maxWidth: 'none',
           padding: '0 2px',
           gap: '2px',
           '& .MuiSvgIcon-root': { width: '22px', height: '22px' },

package/tests/MobileBottomNav.test.jsx

@@ -4,7 +4,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, fireEvent, render, screen, within } from '@testing-library/react';
 import { ThemeProvider, createTheme } from '@mui/material/styles';
 
-import { MobileBottomNav } from '../src/components/MobileBottomNav';
+import {
+  MOBILE_BOTTOM_NAV_ACTION_SX,
+  MOBILE_BOTTOM_NAV_ROOT_SX,
+  MobileBottomNav,
+} from '../src/components/MobileBottomNav';
 import { createAppTheme } from '../src/theme/createAppTheme';
 
 const theme = createAppTheme({ palette: { primary: { main: '#0F62FE' } } });
@@ -179,6 +183,101 @@ describe('MobileBottomNav', () => {
     });
   });
 
+  it('keeps its structural edge and evenly divided actions under a plain MUI theme', () => {
+    const fiveDestinations = [
+      ...destinations,
+      { route: '/fourth', label: 'Fourth', icon: Icon },
+      { route: '/fifth', label: 'Fifth', icon: Icon },
+    ];
+    setViewportWidth(375);
+    const { container } = render(
+      <ThemeProvider theme={createTheme()}>
+        <MobileBottomNav
+          destinations={fiveDestinations}
+          activeRoute="/first"
+          onNavigate={vi.fn()}
+        />
+      </ThemeProvider>,
+    );
+    const navStyle = getComputedStyle(container.firstElementChild);
+    const actionStyles = screen.getAllByRole('button').map((action) => getComputedStyle(action));
+
+    expect(navStyle.borderTopWidth).toBe('1px');
+    expect(navStyle.borderTopStyle).toBe('solid');
+    expect(actionStyles).toHaveLength(5);
+    actionStyles.forEach((actionStyle) => {
+      expect(actionStyle.minWidth).toBe('0px');
+      expect(actionStyle.maxWidth).toBe('none');
+      expect(actionStyle.flexGrow).toBe('1');
+    });
+  });
+
+  it('keeps component-owned sx keys out of baseline theme overrides', () => {
+    const componentSurfaces = [
+      ...Object.keys(MOBILE_BOTTOM_NAV_ROOT_SX)
+        .map((key) => `MuiBottomNavigation.${key}`),
+      ...Object.keys(MOBILE_BOTTOM_NAV_ACTION_SX)
+        .map((key) => `MuiBottomNavigationAction.${key}`),
+    ];
+    const themeSurfaces = [
+      ...Object.keys(theme.components.MuiBottomNavigation.styleOverrides.root)
+        .map((key) => `MuiBottomNavigation.${key}`),
+      ...Object.keys(theme.components.MuiBottomNavigationAction.styleOverrides.root)
+        .map((key) => `MuiBottomNavigationAction.${key}`),
+    ];
+
+    expect(componentSurfaces.filter((surface) => themeSurfaces.includes(surface))).toEqual([]);
+  });
+
+  it.each([
+    ['object', {
+      position: 'absolute',
+      borderTop: '3px dashed',
+      borderColor: 'primary.main',
+    }],
+    ['callback', (currentTheme) => ({
+      position: 'absolute',
+      borderTop: '3px dashed',
+      borderColor: currentTheme.palette.primary.main,
+    })],
+    ['array', [
+      { borderTop: '2px dotted' },
+      {
+        position: 'absolute',
+        borderTop: '3px dashed',
+        borderColor: 'primary.main',
+      },
+    ]],
+  ])('lets caller %s sx override the component defaults', (_kind, sx) => {
+    const { container } = renderNav({
+      sx,
+    });
+    const navStyle = getComputedStyle(container.firstElementChild);
+
+    expect(navStyle.position).toBe('absolute');
+    expect(navStyle.borderTopWidth).toBe('3px');
+    expect(navStyle.borderTopStyle).toBe('dashed');
+    expect(navStyle.borderTopColor).toBe('rgb(15, 98, 254)');
+  });
+
+  it('preserves baseline density and label styling after the structural values move', () => {
+    renderNav();
+    const [selectedAction] = screen.getAllByRole('button');
+    const actionStyle = getComputedStyle(selectedAction);
+    const labelStyle = getComputedStyle(
+      selectedAction.querySelector('.MuiBottomNavigationAction-label'),
+    );
+
+    expect(actionStyle.minWidth).toBe('0px');
+    expect(actionStyle.maxWidth).toBe('none');
+    expect(actionStyle.paddingLeft).toBe('2px');
+    expect(actionStyle.paddingRight).toBe('2px');
+    expect(actionStyle.gap).toBe('2px');
+    expect(labelStyle.fontSize).toBe('12px');
+    expect(labelStyle.fontWeight).toBe('500');
+    expect(labelStyle.lineHeight).toBe('1.2');
+  });
+
   it('renders nothing at and above hideAbove', () => {
     setMediaQueryMatches((query) => query === '(min-width:900px)');
     const { container } = renderNav();
@@ -195,7 +294,7 @@ describe('MobileBottomNav', () => {
     expect(nav.classList.contains('MuiBottomNavigation-root')).toBe(true);
     // jsdom drops env() declarations while parsing CSS, so assert the sx
     // declaration before browser CSS parsing instead of a computed inset.
-    expect(MobileBottomNav.toString()).toContain('env(safe-area-inset-bottom)');
+    expect(MOBILE_BOTTOM_NAV_ROOT_SX.paddingBottom).toBe('env(safe-area-inset-bottom)');
   });
 
   it('renders the five-item, two-badge specimen at 375px and nothing at 1280px', () => {

package/tests/createAppTheme.test.js

@@ -1,7 +1,7 @@
 import { createTheme } from '@mui/material/styles';
 import { describe, expect, it } from 'vitest';
 
-import { assertThemeComplete, createAppTheme } from '../src/index';
+import { assertThemeComplete, createAppTheme } from '../src/theme';
 import { BASELINE_STATIC } from '../src/theme/tokens';
 
 describe('createAppTheme', () => {
@@ -9,6 +9,7 @@ describe('createAppTheme', () => {
     const theme = createAppTheme({ palette: { primary: { main: '#0F62FE' } } });
 
     expect(assertThemeComplete(theme).findings).toEqual([]);
+    expect(theme.palette.background.subtle).toBe('#F4F5F6');
     expect(theme.typography.body1.fontSize).toBe('14px');
     expect(theme.shape.borderRadius).toBe(3);
     expect(theme.components.MuiPaper.defaultProps).toMatchObject({ elevation: 0, variant: 'outlined' });
@@ -23,12 +24,16 @@ describe('createAppTheme', () => {
       '&.Mui-selected': { fontSize: '12px' },
     });
     expect(theme.components.MuiBottomNavigationAction.styleOverrides.root).toMatchObject({
-      minWidth: 0,
-      maxWidth: 'none',
       padding: '0 2px',
       gap: '2px',
       '& .MuiSvgIcon-root': { width: '22px', height: '22px' },
     });
+    expect(theme.components.MuiBottomNavigation.styleOverrides.root).not.toHaveProperty('borderTop');
+    expect(theme.components.MuiBottomNavigation.styleOverrides.root).not.toHaveProperty('borderColor');
+    expect(theme.components.MuiBottomNavigationAction.styleOverrides.root)
+      .not.toHaveProperty('minWidth');
+    expect(theme.components.MuiBottomNavigationAction.styleOverrides.root)
+      .not.toHaveProperty('maxWidth');
     expect(theme.palette.dataSeries.categorical).toHaveLength(6);
     expect(theme.palette.primary.light).not.toBe(createTheme().palette.primary.light);
     // MUI's createTheme(options, ...args) only augments the FIRST argument's

package/tests/themeCompleteness.test.js

@@ -5,7 +5,8 @@ import {
   assertThemeComplete,
   calculateContrastRatio,
   createAppTheme,
-} from '../src/index';
+  THEME_COMPLETENESS_SURFACES,
+} from '../src/theme';
 
 describe('theme completeness', () => {
   it('finds untouched MUI surfaces and accepts createAppTheme', () => {
@@ -20,12 +21,8 @@ describe('theme completeness', () => {
       .map(({ surface }) => surface))
       .toContain('components.MuiButton.styleOverrides.root.minHeight');
     expect(bare.findings.map(({ surface }) => surface)).toEqual(expect.arrayContaining([
-      'components.MuiBottomNavigation.styleOverrides.root.borderTop',
       'components.MuiBottomNavigation.styleOverrides.root.boxShadow',
       'components.MuiBottomNavigation.styleOverrides.root.backgroundColor',
-      'components.MuiBottomNavigation.styleOverrides.root.borderColor',
-      'components.MuiBottomNavigationAction.styleOverrides.root.minWidth',
-      'components.MuiBottomNavigationAction.styleOverrides.root.maxWidth',
       'components.MuiBottomNavigationAction.styleOverrides.root.padding',
       'components.MuiBottomNavigationAction.styleOverrides.root.gap',
       'components.MuiBottomNavigationAction.styleOverrides.root.& .MuiSvgIcon-root.width',
@@ -44,6 +41,44 @@ describe('theme completeness', () => {
     expect(baseline.findings).toEqual([]);
   });
 
+  it('requires and automatically resolves the subtle background for a minimal adopter', () => {
+    const muiDefault = createTheme();
+    const theme = createAppTheme({ palette: { primary: { main: '#0F62FE' } } });
+
+    expect(muiDefault.palette.background.subtle).toBeUndefined();
+    expect(THEME_COMPLETENESS_SURFACES.map(({ surface }) => surface))
+      .toContain('palette.background.subtle');
+    expect(assertThemeComplete(theme).findings).toEqual([]);
+  });
+
+  it('keeps the narrowed bottom-navigation inventory complete', () => {
+    const bottomNavigationSurfaces = THEME_COMPLETENESS_SURFACES
+      .map(({ surface }) => surface)
+      .filter((surface) => surface.startsWith('components.MuiBottomNavigation'));
+
+    expect(bottomNavigationSurfaces).toHaveLength(16);
+    [
+      'components.MuiBottomNavigation.styleOverrides.root.borderTop',
+      'components.MuiBottomNavigation.styleOverrides.root.borderColor',
+      'components.MuiBottomNavigationAction.styleOverrides.root.minWidth',
+      'components.MuiBottomNavigationAction.styleOverrides.root.maxWidth',
+    ].forEach((surface) => expect(bottomNavigationSurfaces).not.toContain(surface));
+  });
+
+  it('ignores a valid exemption for a deregistered surface', () => {
+    const result = assertThemeComplete(
+      createAppTheme({ palette: { primary: { main: '#0F62FE' } } }),
+      {
+        exemptions: [{
+          surface: 'components.MuiBottomNavigation.styleOverrides.root.borderTop',
+          reason: 'Legacy exemption retained while the application upgrades.',
+        }],
+      },
+    );
+
+    expect(result.findings).toEqual([]);
+  });
+
   it('suppresses exactly one surface when an exemption includes a reason', () => {
     const theme = createTheme();
     const before = assertThemeComplete(theme).findings;
@@ -83,6 +118,11 @@ describe('theme completeness', () => {
       .toContain('contrast.success.text-on-bg');
   });
 
+  it('keeps secondary ink AA-legible on the subtle background', () => {
+    const ratio = calculateContrastRatio('#5B6670', '#F4F5F6');
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+  });
+
   it('requires every MUI status main to clear AA on white and the page background', () => {
     const theme = createAppTheme({ palette: { primary: { main: '#8AB4F8' } } });