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

package/WORK_ORDERS.md

@@ -59,3 +59,4 @@ 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`. |

package/dev/entries.jsx

@@ -1,5 +1,10 @@
 import { useEffect, useState } from 'react';
+import ChatBubbleOutlineIcon from '@mui/icons-material/ChatBubbleOutline';
+import InboxIcon from '@mui/icons-material/Inbox';
+import MoreHorizIcon from '@mui/icons-material/MoreHoriz';
 import MoreVertIcon from '@mui/icons-material/MoreVert';
+import ScheduleIcon from '@mui/icons-material/Schedule';
+import ViewKanbanIcon from '@mui/icons-material/ViewKanban';
 import {
   Alert,
   Box,
@@ -28,6 +33,7 @@ import {
 } from '@mui/material';
 
 import { AuthContext } from '../src/auth/AuthContext';
+import { MobileBottomNav } from '../src/components/MobileBottomNav';
 import { BarChart } from '../src/components/charts/BarChart';
 import { ChartFrame } from '../src/components/charts/ChartFrame';
 import { LineChart } from '../src/components/charts/LineChart';
@@ -60,6 +66,33 @@ function NotificationBellEntry() {
   );
 }
 
+const MOBILE_NAV_DESTINATIONS = [
+  { route: '/triage', label: 'Triage', icon: InboxIcon, badgeCount: 7 },
+  { route: '/board', label: 'Board', icon: ViewKanbanIcon, badgeCount: 3 },
+  { route: '/chat', label: 'Chat', icon: ChatBubbleOutlineIcon },
+  { route: '/status', label: 'Status', icon: ScheduleIcon },
+  { route: '/more', label: 'Mehr', icon: MoreHorizIcon, emphasis: true },
+];
+
+function MobileBottomNavEntry() {
+  const [activeRoute, setActiveRoute] = useState('/triage');
+
+  return (
+    <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.
+      </Typography>
+      <MobileBottomNav
+        destinations={MOBILE_NAV_DESTINATIONS}
+        activeRoute={activeRoute}
+        onNavigate={setActiveRoute}
+      />
+    </Box>
+  );
+}
+
 function BarChartEntry() {
   return (
     <ChartFrame title="Monthly cases" subtitle="Standalone BarChart entry" minHeight={360}>
@@ -403,6 +436,7 @@ function MessagingScopeConfigEntry() { return <MessagingProvider api={messagingH
 
 export const entries = [
   { id: 'theme-baseline', label: 'Theme / Shared baseline', Component: ThemeBaselineEntry },
+  { id: 'mobile-bottom-nav', label: 'Navigation / Mobile bottom nav', Component: MobileBottomNavEntry },
   { id: 'notification-bell', label: 'Notifications / Bell', Component: NotificationBellEntry },
   { id: 'bar-chart', label: 'Charts / BarChart', Component: BarChartEntry },
   { id: 'time-series-chart', label: 'Charts / TimeSeriesChart', Component: TimeSeriesChartEntry },

package/dev/main.jsx

@@ -30,12 +30,14 @@ function Harness() {
   const [mode, setMode] = useState('light');
   const [width, setWidth] = useState('desktop');
   const entry = entries.find((item) => item.id === entryId) || entries[0];
-  const effectiveMode = entry.id === 'theme-baseline' ? 'light' : mode;
+  const usesBaselineTheme = ['theme-baseline', 'mobile-bottom-nav'].includes(entry.id);
+  const usesBrowserViewport = entry.id === 'mobile-bottom-nav';
+  const effectiveMode = usesBaselineTheme ? 'light' : mode;
   const theme = useMemo(
-    () => entry.id === 'theme-baseline'
+    () => usesBaselineTheme
       ? createAppTheme({ palette: { primary: { main: '#3D5A99' } } })
       : createTheme({ palette: { mode } }),
-    [entry.id, mode],
+    [mode, usesBaselineTheme],
   );
   const viewportWidth = width === 'mobile' ? 390 : width === 'tablet' ? 768 : 1180;
   const Entry = entry.Component;
@@ -47,8 +49,12 @@ function Harness() {
         <Stack direction={{ xs: 'column', md: 'row' }} spacing={2} sx={{ mb: 3 }} alignItems={{ md: 'center' }}>
           <Typography variant="h5" sx={{ mr: 'auto' }}>ui-core-micha harness</Typography>
           <FormControl size="small" sx={{ minWidth: 220 }}><InputLabel id="entry-label">Entry</InputLabel><Select labelId="entry-label" label="Entry" value={entryId} onChange={(event) => setEntryId(event.target.value)}>{entries.map((item) => <MenuItem key={item.id} value={item.id}>{item.label}</MenuItem>)}</Select></FormControl>
-          <ButtonGroup size="small"><Button variant={effectiveMode === 'light' ? 'contained' : 'outlined'} onClick={() => setMode('light')}>Light</Button><Button disabled={entry.id === 'theme-baseline'} variant={effectiveMode === 'dark' ? 'contained' : 'outlined'} onClick={() => setMode('dark')}>Dark</Button></ButtonGroup>
-          <ButtonGroup size="small">{['mobile', 'tablet', 'desktop'].map((size) => <Button key={size} variant={width === size ? 'contained' : 'outlined'} onClick={() => setWidth(size)}>{size}</Button>)}</ButtonGroup>
+          <ButtonGroup size="small"><Button variant={effectiveMode === 'light' ? 'contained' : 'outlined'} onClick={() => setMode('light')}>Light</Button><Button disabled={usesBaselineTheme} variant={effectiveMode === 'dark' ? 'contained' : 'outlined'} onClick={() => setMode('dark')}>Dark</Button></ButtonGroup>
+          {usesBrowserViewport ? (
+            <Typography variant="caption" color="text.secondary">Use the browser viewport for this specimen</Typography>
+          ) : (
+            <ButtonGroup size="small">{['mobile', 'tablet', 'desktop'].map((size) => <Button key={size} variant={width === size ? 'contained' : 'outlined'} onClick={() => setWidth(size)}>{size}</Button>)}</ButtonGroup>
+          )}
         </Stack>
         <Paper variant="outlined" sx={{ width: viewportWidth, maxWidth: '100%', mx: 'auto', p: 3, overflow: 'hidden', containerType: 'inline-size' }}>
           <Entry />

package/dist/components/MobileBottomNav.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Badge from '@mui/material/Badge';
+import BottomNavigation from '@mui/material/BottomNavigation';
+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, }) {
+    const theme = useTheme();
+    const isHidden = useMediaQuery(theme.breakpoints.up(hideAbove));
+    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) => {
+            var _a;
+            const Icon = destination.icon;
+            const selected = activeRoute === destination.route;
+            const icon = (_jsx(Icon, { sx: destination.emphasis ? {
+                    p: 0.8,
+                    borderRadius: '50%',
+                    backgroundColor: selected ? 'primary.main' : 'background.paper',
+                    color: selected ? 'primary.contrastText' : 'primary.main',
+                    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));
+        }) }));
+}

package/dist/index.js

@@ -30,6 +30,7 @@ export { RegistrationMethodsManager } from './components/RegistrationMethodsMana
 export { AuthFactorRequirementCard } from './components/AuthFactorRequirementCard';
 export { AccessCodeSingleUseToggle } from './components/AccessCodeSingleUseToggle';
 export { QrSignupManager } from './components/QrSignupManager';
+export { MobileBottomNav } from './components/MobileBottomNav';
 // --- 6. Charts ---
 export { ChartFrame } from './components/charts/ChartFrame';
 export { BarChart } from './components/charts/BarChart';

package/dist/theme/createAppTheme.js

@@ -100,6 +100,22 @@ function createPaletteAwareComponents(palette) {
                 outlined: { borderColor: palette.controlBorder.main },
             },
         },
+        MuiBottomNavigation: {
+            styleOverrides: {
+                root: {
+                    backgroundColor: palette.background.paper,
+                    borderColor: palette.divider,
+                },
+            },
+        },
+        MuiBottomNavigationAction: {
+            styleOverrides: {
+                root: {
+                    color: palette.text.secondary,
+                    '&.Mui-selected': { color: palette.primary.main },
+                },
+            },
+        },
         MuiOutlinedInput: {
             styleOverrides: {
                 root: {

package/dist/theme/themeCompleteness.js

@@ -72,6 +72,26 @@ 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'),
+    componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '& .MuiSvgIcon-root', 'height'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.root.color'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.fontSize'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.fontWeight'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.lineHeight'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.maxWidth'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.whiteSpace'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.overflow'),
+    componentPath('MuiBottomNavigationAction', 'styleOverrides.label.textOverflow'),
+    componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.label', '&.Mui-selected', 'fontSize'),
+    componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '&.Mui-selected', 'color'),
     componentPath('MuiTextField', 'defaultProps.variant'),
     componentPath('MuiTextField', 'styleOverrides.root.minHeight'),
     componentKeyLeaf('MuiTextField', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),

package/dist/theme/tokens.js

@@ -260,6 +260,32 @@ export const BASELINE_STATIC = {
                 },
             },
         },
+        MuiBottomNavigation: {
+            styleOverrides: {
+                root: { borderTop: '1px solid', boxShadow: 'none' },
+            },
+        },
+        MuiBottomNavigationAction: {
+            styleOverrides: {
+                root: {
+                    minWidth: 0,
+                    maxWidth: 'none',
+                    padding: '0 2px',
+                    gap: '2px',
+                    '& .MuiSvgIcon-root': { width: '22px', height: '22px' },
+                },
+                label: {
+                    fontSize: '12px',
+                    fontWeight: 500,
+                    lineHeight: 1.2,
+                    maxWidth: '100%',
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    '&.Mui-selected': { fontSize: '12px' },
+                },
+            },
+        },
         MuiTextField: {
             defaultProps: { variant: 'outlined' },
             styleOverrides: { root: Object.assign({ minHeight: 40 }, coarseHitArea) },

package/package.json

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

package/src/components/MobileBottomNav.jsx

@@ -0,0 +1,68 @@
+import Badge from '@mui/material/Badge';
+import BottomNavigation from '@mui/material/BottomNavigation';
+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,
+}) {
+  const theme = useTheme();
+  const isHidden = useMediaQuery(theme.breakpoints.up(hideAbove));
+
+  if (isHidden) return null;
+
+  return (
+    <BottomNavigation
+      value={activeRoute}
+      onChange={(_, route) => onNavigate(route)}
+      showLabels
+      sx={{
+        position: 'fixed',
+        left: 0,
+        right: 0,
+        bottom: 0,
+        zIndex,
+        paddingBottom: 'env(safe-area-inset-bottom)',
+      }}
+    >
+      {destinations.map((destination) => {
+        const Icon = destination.icon;
+        const selected = activeRoute === destination.route;
+        const icon = (
+          <Icon
+            sx={destination.emphasis ? {
+              p: 0.8,
+              borderRadius: '50%',
+              backgroundColor: selected ? 'primary.main' : 'background.paper',
+              color: selected ? 'primary.contrastText' : 'primary.main',
+              boxShadow: 'none',
+              transform: 'translateY(-4px)',
+            } : undefined}
+          />
+        );
+
+        return (
+          <BottomNavigationAction
+            key={destination.route}
+            value={destination.route}
+            label={destination.shortLabel ?? destination.label}
+            aria-label={destination.shortLabel != null ? destination.label : undefined}
+            aria-current={selected ? 'page' : undefined}
+            icon={destination.badgeCount ? (
+              <Badge badgeContent={destination.badgeCount} color="error" max={99}>
+                {icon}
+              </Badge>
+            ) : icon}
+          />
+        );
+      })}
+    </BottomNavigation>
+  );
+}

package/src/index.js

@@ -48,6 +48,7 @@ export { RegistrationMethodsManager } from './components/RegistrationMethodsMana
 export { AuthFactorRequirementCard } from './components/AuthFactorRequirementCard';
 export { AccessCodeSingleUseToggle } from './components/AccessCodeSingleUseToggle';
 export { QrSignupManager } from './components/QrSignupManager';
+export { MobileBottomNav } from './components/MobileBottomNav';
 
 // --- 6. Charts ---
 export { ChartFrame } from './components/charts/ChartFrame';

package/src/theme/createAppTheme.js

@@ -116,6 +116,22 @@ function createPaletteAwareComponents(palette) {
         outlined: { borderColor: palette.controlBorder.main },
       },
     },
+    MuiBottomNavigation: {
+      styleOverrides: {
+        root: {
+          backgroundColor: palette.background.paper,
+          borderColor: palette.divider,
+        },
+      },
+    },
+    MuiBottomNavigationAction: {
+      styleOverrides: {
+        root: {
+          color: palette.text.secondary,
+          '&.Mui-selected': { color: palette.primary.main },
+        },
+      },
+    },
     MuiOutlinedInput: {
       styleOverrides: {
         root: {

package/src/theme/themeCompleteness.js

@@ -96,6 +96,26 @@ 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'),
+  componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '& .MuiSvgIcon-root', 'height'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.root.color'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.fontSize'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.fontWeight'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.lineHeight'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.maxWidth'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.whiteSpace'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.overflow'),
+  componentPath('MuiBottomNavigationAction', 'styleOverrides.label.textOverflow'),
+  componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.label', '&.Mui-selected', 'fontSize'),
+  componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '&.Mui-selected', 'color'),
   componentPath('MuiTextField', 'defaultProps.variant'),
   componentPath('MuiTextField', 'styleOverrides.root.minHeight'),
   componentKeyLeaf('MuiTextField', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),

package/src/theme/tokens.js

@@ -306,6 +306,32 @@ export const BASELINE_STATIC = {
         },
       },
     },
+    MuiBottomNavigation: {
+      styleOverrides: {
+        root: { borderTop: '1px solid', boxShadow: 'none' },
+      },
+    },
+    MuiBottomNavigationAction: {
+      styleOverrides: {
+        root: {
+          minWidth: 0,
+          maxWidth: 'none',
+          padding: '0 2px',
+          gap: '2px',
+          '& .MuiSvgIcon-root': { width: '22px', height: '22px' },
+        },
+        label: {
+          fontSize: '12px',
+          fontWeight: 500,
+          lineHeight: 1.2,
+          maxWidth: '100%',
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+          '&.Mui-selected': { fontSize: '12px' },
+        },
+      },
+    },
     MuiTextField: {
       defaultProps: { variant: 'outlined' },
       styleOverrides: { root: { minHeight: 40, ...coarseHitArea } },

package/tests/MobileBottomNav.test.jsx

@@ -0,0 +1,220 @@
+// @vitest-environment jsdom
+import React from 'react';
+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 { createAppTheme } from '../src/theme/createAppTheme';
+
+const theme = createAppTheme({ palette: { primary: { main: '#0F62FE' } } });
+
+function Icon() {
+  return <svg aria-hidden="true" data-testid="destination-icon" />;
+}
+
+const destinations = [
+  { route: '/first', label: 'First', icon: Icon },
+  { route: '/second', label: 'Second', icon: Icon },
+  { route: '/third', label: 'Third', icon: Icon },
+];
+
+function setMediaQueryMatches(matches) {
+  window.matchMedia = vi.fn().mockImplementation((query) => ({
+    matches: typeof matches === 'function' ? matches(query) : matches,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+}
+
+function setViewportWidth(width) {
+  setMediaQueryMatches((query) => {
+    const minWidth = query.match(/min-width:(\d+)px/)?.[1];
+    return minWidth ? width >= Number(minWidth) : false;
+  });
+}
+
+function renderNav(props = {}) {
+  return render(
+    <ThemeProvider theme={theme}>
+      <MobileBottomNav
+        destinations={destinations}
+        activeRoute="/first"
+        onNavigate={vi.fn()}
+        {...props}
+      />
+    </ThemeProvider>,
+  );
+}
+
+describe('MobileBottomNav', () => {
+  beforeEach(() => setMediaQueryMatches(false));
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  it('renders one action per destination, in order, with visible labels', () => {
+    renderNav();
+
+    expect(screen.getAllByRole('button').map((action) => action.textContent)).toEqual([
+      'First',
+      'Second',
+      'Third',
+    ]);
+  });
+
+  it('selects exactly the matching route and tolerates no match', () => {
+    const { rerender } = renderNav({ activeRoute: '/second' });
+    const selected = () => screen.getAllByRole('button')
+      .filter((action) => action.classList.contains('Mui-selected'));
+
+    expect(selected()).toHaveLength(1);
+    expect(selected()[0].textContent).toBe('Second');
+    expect(selected()[0].getAttribute('aria-current')).toBe('page');
+    expect(screen.getAllByRole('button').filter((action) => action.hasAttribute('aria-current')))
+      .toHaveLength(1);
+
+    rerender(
+      <ThemeProvider theme={theme}>
+        <MobileBottomNav
+          destinations={destinations}
+          activeRoute="/not-in-the-bar"
+          onNavigate={vi.fn()}
+        />
+      </ThemeProvider>,
+    );
+    expect(selected()).toHaveLength(0);
+    expect(screen.getAllByRole('button').some((action) => action.hasAttribute('aria-current')))
+      .toBe(false);
+  });
+
+  it('calls onNavigate with the selected destination route', () => {
+    const onNavigate = vi.fn();
+    renderNav({ onNavigate });
+
+    fireEvent.click(screen.getByRole('button', { name: 'Second' }));
+
+    expect(onNavigate).toHaveBeenCalledOnce();
+    expect(onNavigate).toHaveBeenCalledWith('/second');
+  });
+
+  it('renders a positive badge only on its own destination', () => {
+    renderNav({
+      destinations: [
+        { route: '/inbox', label: 'Inbox', icon: Icon, badgeCount: 4 },
+        { route: '/empty', label: 'Empty', icon: Icon, badgeCount: 0 },
+        { route: '/unset', label: 'Unset', icon: Icon },
+      ],
+      activeRoute: '/inbox',
+    });
+
+    const actions = screen.getAllByRole('button');
+    expect(within(actions[0]).getByText('4')).toBeTruthy();
+    expect(actions[0].querySelectorAll('.MuiBadge-root')).toHaveLength(1);
+    expect(actions[1].querySelector('.MuiBadge-root')).toBeNull();
+    expect(actions[2].querySelector('.MuiBadge-root')).toBeNull();
+  });
+
+  it('uses shortLabel when present and label when it is absent', () => {
+    renderNav({
+      destinations: [
+        { route: '/registrations', label: 'My registrations', shortLabel: 'Mine', icon: Icon },
+        { route: '/messages', label: 'Messages', icon: Icon },
+      ],
+    });
+
+    expect(screen.getAllByRole('button').map((action) => action.textContent)).toEqual([
+      'Mine',
+      'Messages',
+    ]);
+    expect(screen.getByRole('button', { name: 'My registrations' }).textContent).toBe('Mine');
+  });
+
+  it('resolves its surface and action colours from both baseline and plain MUI themes', () => {
+    const themes = [
+      createAppTheme({
+        palette: {
+          primary: { main: '#123456' },
+          background: { paper: '#F1F2F3' },
+          text: { secondary: '#445566' },
+        },
+      }),
+      createTheme({
+        palette: {
+          primary: { main: '#654321' },
+          background: { paper: '#E7E8E9' },
+          text: { secondary: '#665544' },
+        },
+      }),
+    ];
+    const expected = [
+      { background: 'rgb(241, 242, 243)', selected: 'rgb(18, 52, 86)', rest: 'rgb(68, 85, 102)' },
+      { background: 'rgb(231, 232, 233)', selected: 'rgb(101, 67, 33)', rest: 'rgb(102, 85, 68)' },
+    ];
+
+    themes.forEach((currentTheme, index) => {
+      const { container } = render(
+        <ThemeProvider theme={currentTheme}>
+          <MobileBottomNav
+            destinations={destinations}
+            activeRoute="/first"
+            onNavigate={vi.fn()}
+          />
+        </ThemeProvider>,
+      );
+      const actions = screen.getAllByRole('button');
+
+      expect(getComputedStyle(container.firstElementChild).backgroundColor)
+        .toBe(expected[index].background);
+      expect(getComputedStyle(actions[0]).color).toBe(expected[index].selected);
+      expect(getComputedStyle(actions[1]).color).toBe(expected[index].rest);
+      cleanup();
+    });
+  });
+
+  it('renders nothing at and above hideAbove', () => {
+    setMediaQueryMatches((query) => query === '(min-width:900px)');
+    const { container } = renderNav();
+
+    expect(window.matchMedia).toHaveBeenCalledWith('(min-width:900px)');
+    expect(container.childElementCount).toBe(0);
+    expect(screen.queryByRole('navigation')).toBeNull();
+  });
+
+  it('declares safe-area bottom padding on the fixed bar', () => {
+    const { container } = renderNav();
+    const nav = container.firstElementChild;
+
+    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)');
+  });
+
+  it('renders the five-item, two-badge specimen at 375px and nothing at 1280px', () => {
+    const specimen = [
+      { route: '/triage', label: 'Triage', icon: Icon, badgeCount: 7 },
+      { route: '/board', label: 'Board', icon: Icon, badgeCount: 3 },
+      { route: '/chat', label: 'Chat', icon: Icon },
+      { route: '/status', label: 'Status', icon: Icon },
+      { route: '/more', label: 'More', icon: Icon, emphasis: true },
+    ];
+
+    setViewportWidth(375);
+    renderNav({ destinations: specimen, activeRoute: '/triage' });
+    expect(screen.getAllByRole('button')).toHaveLength(5);
+    expect(document.querySelectorAll('.MuiBadge-root')).toHaveLength(2);
+
+    cleanup();
+    setViewportWidth(1280);
+    renderNav({ destinations: specimen, activeRoute: '/triage' });
+    expect(screen.queryByRole('button')).toBeNull();
+  });
+});

package/tests/createAppTheme.test.js

@@ -12,6 +12,23 @@ describe('createAppTheme', () => {
     expect(theme.typography.body1.fontSize).toBe('14px');
     expect(theme.shape.borderRadius).toBe(3);
     expect(theme.components.MuiPaper.defaultProps).toMatchObject({ elevation: 0, variant: 'outlined' });
+    expect(theme.components.MuiBottomNavigationAction.styleOverrides.label).toMatchObject({
+      fontSize: '12px',
+      fontWeight: 500,
+      lineHeight: 1.2,
+      maxWidth: '100%',
+      whiteSpace: 'nowrap',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      '&.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.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

@@ -19,6 +19,28 @@ describe('theme completeness', () => {
     expect(assertThemeComplete(createTheme({ components: { MuiButton: {} } })).findings
       .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',
+      'components.MuiBottomNavigationAction.styleOverrides.root.& .MuiSvgIcon-root.height',
+      'components.MuiBottomNavigationAction.styleOverrides.root.color',
+      'components.MuiBottomNavigationAction.styleOverrides.label.fontSize',
+      'components.MuiBottomNavigationAction.styleOverrides.label.fontWeight',
+      'components.MuiBottomNavigationAction.styleOverrides.label.lineHeight',
+      'components.MuiBottomNavigationAction.styleOverrides.label.maxWidth',
+      'components.MuiBottomNavigationAction.styleOverrides.label.whiteSpace',
+      'components.MuiBottomNavigationAction.styleOverrides.label.overflow',
+      'components.MuiBottomNavigationAction.styleOverrides.label.textOverflow',
+      'components.MuiBottomNavigationAction.styleOverrides.label.&.Mui-selected.fontSize',
+      'components.MuiBottomNavigationAction.styleOverrides.root.&.Mui-selected.color',
+    ]));
     expect(baseline.findings).toEqual([]);
   });
 

package/work-orders/SHELL-3.md

@@ -0,0 +1,359 @@
+# SHELL-3 — Promote the mobile bottom navigation into the shared kit
+
+**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
+**Tier:** 3 (shared core)
+**Review:** independent `reviewer` **and** `ui_reviewer` — spawned concurrently, both mandatory before commit
+**Version target:** `2.33.0` — minor: a new public component plus additive theme defaults
+**Precondition of:** `cockpit/UI-3` and `jg-ferien/NAV-36`
+**Visual spec:** `cockpit/work-orders/assets/UI-3-nav-redesign.html` (sections 3 and 4)
+
+---
+
+## A. Envelope
+
+### Goal
+
+Two apps need a mobile bottom navigation. jg-ferien has one
+(`frontend/src/components/mobileShell/MobileBottomNav.jsx`, 107 lines) and cockpit is about to
+need one. Promote it, so cockpit does not hand-build a second and jg's copy can be deleted.
+
+The API is derived from **both** cases rather than from jg alone — that comparison is what
+`DS-6` asked for, and it is documented in the prototype's section 4. Each recorded promotion
+blocker in jg's version becomes a declarative field, and in each case cockpit is what proves the
+field is genuinely optional rather than a jg quirk.
+
+### Why this is a promotion and not a copy
+
+jg's structure is sound; its **presentation layer is not overridable**. Every value is an `sx`
+literal with no prop seam, app route literals drive the special visual treatment, and it depends
+directly on a jg-specific messaging hook. A consumer could only fork it. This work order splits
+that: **style defaults move into the theme baseline, structure and behaviour into the component,
+app specifics into props.**
+
+### Scope — two labelled parts, one release
+
+#### Part 1 — the baseline gains bottom-navigation defaults
+
+Add `MuiBottomNavigation` and `MuiBottomNavigationAction` to `src/theme/tokens.js`'s `components`
+block, and register the corresponding surfaces in `src/theme/themeCompleteness.js`.
+
+What the defaults must express, all from existing baseline tokens:
+
+- the bar surface is `background.paper` with a top `divider` border and **no resting shadow**
+  (baseline rule: resting surfaces are flat);
+- action colour `text.secondary`, selected `primary.main`;
+- label `12px` at weight `500` — this is the one value the prototype flagged as a delta, and it
+  is resolved **here**, as a component default, not as a new typography token;
+- `minWidth: 0` and `maxWidth: 'none'` on the action, so a five-item bar divides evenly at
+  375 px instead of hitting MUI's default `minWidth: 80`.
+
+**Two hard constraints of this file, both already enforced by existing tests:**
+
+- **Objects only.** No function may appear anywhere in the baseline `components` tree
+  (`tests/createAppTheme.test.js` asserts this). MUI's multi-arg deep merge treats a function as
+  a leaf in both directions, so a function default silently becomes unoverridable. jg's current
+  `zIndex: (theme) => theme.zIndex.drawer + 2` therefore **cannot** move into the theme — it
+  stays in the component (see part 2).
+- **Palette-first ordering.** Palette resolution happens before palette-aware component objects
+  are built, so any default that reads a palette value must follow that existing pattern in
+  `createAppTheme.js` rather than being added to the static block.
+
+#### Part 2 — the `MobileBottomNav` component
+
+Exported from `src/index.js`. Keep the name — it matches what jg already calls it, which keeps
+`NAV-36`'s migration a swap rather than a rename.
+
+Props:
+
+| Prop | Meaning |
+|---|---|
+| `destinations` | ordered array of `{ route, label, icon, shortLabel?, emphasis?, badgeCount? }` |
+| `activeRoute` | the currently active route; the app derives it, the component does not guess |
+| `onNavigate` | called with a destination's `route` |
+| `hideAbove` | breakpoint above which the bar renders nothing. Default `'md'` |
+| `zIndex` | default `theme.zIndex.drawer + 2`, overridable — SHELL-2 named the hardcoded-zIndex trap and this is the same class |
+
+Field semantics, each with its evidence:
+
+- **`label` is a finished string, not an i18n key.** jg translates inside the component today,
+  cockpit outside. Finished strings are what `SHELL-1` and `DS-11` already settled for shared
+  components — the kit must not know an app's key namespace.
+- **`shortLabel`** is optional and falls back to `label`. **Carry it for jg alone.** An earlier
+  draft of the prototype claimed cockpit independently proved the need; that claim was withdrawn
+  when Einstellungen moved behind Mehr. One consumer, one reason — do not document it as
+  twice-confirmed.
+- **`emphasis`** replaces jg's hardcoded check for `/my-registrations`. cockpit sets it on no
+  destination, which is what proves it optional.
+- **`badgeCount` is per destination.** jg has one badge from a messaging hook; cockpit has two
+  from its own data. The second case is what makes per-destination correct rather than a single
+  `unreadCount`.
+
+Behaviour the component owns: the fixed positioning, the top border, the breakpoint hide, and
+**`padding-bottom: env(safe-area-inset-bottom)`** so a notched phone's home indicator does not
+sit on the labels.
+
+Behaviour the component does **not** own:
+
+- **No auth gate.** jg's version returns `null` when there is no user. That is app logic; the app
+  decides whether to render the bar at all.
+- **No overflow logic.** The app passes the bar's own destination list. jg puts all five of its
+  destinations in; cockpit puts four of six plus a `Mehr` destination whose route leads to its own
+  page. "Mehr" is an ordinary destination as far as the kit is concerned. This is what keeps the
+  component thin, and it was a deliberate decision against an overlay sheet, which would have
+  added open/close state, a scrim, a focus trap, Escape handling and a reduced-motion path to a
+  shared component on the strength of two consumers.
+
+### Design-agnosticism: what the bar derives from, and what it does not guarantee
+
+**No hex value appears in the component.** The bar is composed entirely from tokens —
+`background.paper` for its surface, `divider` for its top edge, `text.secondary` for the label,
+`primary.main` for the selected state — so an app with a different surface colour gets a different
+bar without touching the kit. A second seam exists above that: an app may override
+`MuiBottomNavigation` / `MuiBottomNavigationAction` in **its own** theme. That is not an escape
+hatch, it is the mechanism, and it is the reason part 1 puts the defaults in the theme rather than
+in the component. Values inside the component are exactly jg's current problem.
+
+Three limits must be stated rather than discovered:
+
+- **Contrast is not guaranteed, and nothing checks it.** `assertThemeComplete`'s contrast surfaces
+  are hardcoded to `#FFFFFF` and `background.default`; **`background.paper` is never a contrast
+  surface, and `text.secondary` is never checked against anything.** An app with a dark or
+  saturated `background.paper` therefore gets a correctly-rendered, unreadable bar and **zero
+  findings**. For baseline apps this is comfortable — `#5B6670` on `#FFFFFF` measures 5.87:1 and on
+  `#FAFAFA` 5.62:1 (MUI's own `getContrastRatio`) — so this is a limit for deviating apps, not a
+  defect in the default. **Do not extend the shared contrast assertion inside this WO**: adding a
+  surface changes what every adopting app is measured against, which is a deliberate governance
+  decision belonging to `DS-18` (invariant-scoped coverage), not a side effect of shipping a
+  component.
+- **The separation from the page depends on `background.paper` differing from
+  `background.default`.** The bar has no resting shadow by baseline rule, so its edge comes from
+  one tonal step (`#FFFFFF` against `#FAFAFA`) plus a 1 px divider. In an app where those two
+  tokens are the same colour, only the divider carries it and the bar reads as glued to the page.
+  That is an acceptable outcome, but it must be a known one.
+- **A tooling trap for anyone verifying the above:** MUI's `getContrastRatio` ignores alpha —
+  `rgba(0, 0, 0, 0.6)` on white returns `21.00`, the figure for pure black. jg-ferien keeps its own
+  `createTheme` and therefore MUI's alpha-based `text.secondary`, so a contrast check against jg's
+  theme is meaningless. Verify jg by looking, not by computing.
+
+### Non-goals / do not touch
+
+- **No `AppHeaderMobile` promotion.** jg's is mostly app wiring around already-shared pieces.
+- No change to `UserMenu`, `NotificationBell`, `ChartFrame` or any chart wrapper.
+- No change to any existing baseline token value. Part 1 **adds** two component keys; it does not
+  edit typography, palette, shape, spacing or the `shadows` array.
+- No dark-mode work (`DS-12` owns that, on its own trigger).
+- No migration of jg-ferien — that is `NAV-36`, deliberately separate.
+
+### Risks
+
+- **No staging net.** A version bump on `main` publishes to npm; the independent review is the
+  only gate and cannot be back-filled. Publishing is version-gated, so the release happens when
+  `package.json`'s version exceeds the live one — not on every push.
+- **Adding assertion surfaces raises the bar for every adopting app.** The values come from the
+  baseline, so `assertThemeComplete` stays green for apps built through `createAppTheme` — but
+  verify that explicitly rather than assuming it, because a missed surface would turn an unrelated
+  app's suite red on its next pin bump.
+- **`minWidth: 0` on the action is a deliberate deviation from MUI's default.** It is what makes a
+  five-item bar work at 375 px; it also means a six-item bar will truncate labels rather than
+  scroll. That is the intended failure mode — the prototype's measurement shows six items do not
+  fit — but it must be a conscious default, not a surprise.
+
+### Required tests to WRITE
+
+1. `destinations` renders one action per entry, in order, with `label` as the visible text.
+2. `activeRoute` marks exactly the matching action selected; a route matching nothing selects
+   none and does not throw.
+3. `onNavigate` fires with the destination's `route`.
+4. `badgeCount` renders on the destination that has it and **not** on the others; a count of `0`
+   or `undefined` renders no badge.
+5. `shortLabel` is used when present, `label` when absent.
+5b. **Theme-agnosticism, asserted rather than assumed.** Render the same bar under two themes whose
+   `background.paper`, `text.secondary` and `primary.main` differ, and assert the resolved computed
+   values follow the theme in both. This is what proves no colour is baked into the component — the
+   single most likely regression, because an `sx` literal looks correct in the app it was written
+   for. Include one theme that is **not** built by `createAppTheme`, since jg-ferien is exactly that
+   case and `NAV-36` depends on it working.
+6. Above `hideAbove` the component renders nothing.
+7. `assertThemeComplete(createAppTheme({ palette: { primary: { main: '#0F62FE' } } })).findings`
+   stays `[]` with the new surfaces registered — and **prove non-vacuity**: a theme missing the
+   new component defaults must produce findings naming them.
+
+Plus `tsc -p tsconfig.build.json --noEmit` clean. **No full-suite run** — the affected set is the
+new component's spec plus `tests/themeCompleteness.test.js` and `tests/createAppTheme.test.js`.
+
+### Verification
+
+The rendered two-width side-by-side per `DS-1`, against the prototype's sections 3 and 4. Add a
+harness specimen to `dev/entries.jsx` — no existing specimen has a bottom navigation, and
+`CHART-7` set the precedent of adding one rather than declaring the gate unmeetable. Show a
+five-item bar with two badges at 375 px, and confirm it renders nothing at 1280 px.
+
+State in the register note whether real screenshots were obtained or DOM inspection substituted.
+**The safe-area padding cannot be verified either way** — a desktop 375 px viewport always
+reports an inset of zero, the same wall `TPL-1` hit. Specify it, assert the CSS is present, and
+record it as unverified rather than done.
+
+### Parity guardrail
+
+For jg-ferien this must be a behavioural no-op once `NAV-36` swaps to it: same destinations, same
+active-route derivation, same badge, same raised treatment on its emphasised destination. Two
+known differences are intended and belong in `NAV-36`'s note, not here: the German literal
+fallback `'Meine'` disappears (the app passes finished strings), and `background.white` — a
+jg-only palette extension — is replaced by the baseline surface.
+
+---
+
+## B. Implementation map
+
+*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
+
+### Execution directive (read this first)
+
+> **If you are the implementer reading this work order as your own specification: this section is
+> NOT addressed to you.** It tells the Orchestrator how to invoke you. **You ARE that invocation —
+> do NOT shell out to `codex exec`.**
+>
+> Implement through `codex exec` in the background — invoked directly via Bash (never the
+> `debugger`/`*_coder` Agent wrappers) with BOTH flags `--skip-git-repo-check` and
+> `--dangerously-bypass-approvals-and-sandbox`. **Pass the WO via stdin, not as a positional
+> argument** (a positional arg hits Windows' command-line length limit — proven repeatedly in this
+> repo). Fallback to direct Claude implementation only on Codex quota/rate-limit/non-zero exit —
+> and note that the fallback flips authorship, so both reviewers stay mandatory either way.
+
+### Context package
+
+**Reference implementation to promote from (read-only, do not edit):**
+`C:\Users\biglmi\Documents\webapps\jg-ferien\frontend\src\components\mobileShell\MobileBottomNav.jsx`
+(107 lines) — the source of every field/behaviour named in the Envelope. Note its hardcoded
+`zIndex: (navTheme) => navTheme.zIndex.drawer + 2` (stays a component default, cannot move to the
+theme per the "objects only" constraint), its `/my-registrations` special-case (becomes
+`emphasis`), its messaging-hook badge (becomes generic `badgeCount`), and its inline `t()` calls
+(become finished-string `label`/`shortLabel` props — do not import `react-i18next` into the new
+component).
+
+**Files to change, in ucm:**
+
+1. **`src/theme/tokens.js`** — add to `BASELINE_STATIC.components` (palette-*independent* values
+   only; this file is deep-merged as static objects and MUST NOT contain functions —
+   `tests/createAppTheme.test.js` asserts this):
+   ```js
+   MuiBottomNavigation: {
+     styleOverrides: {
+       root: { borderTop: '1px solid', boxShadow: 'none' },
+     },
+   },
+   MuiBottomNavigationAction: {
+     styleOverrides: {
+       root: { minWidth: 0, maxWidth: 'none' },
+       label: { fontSize: '12px', fontWeight: 500 },
+     },
+   },
+   ```
+   Follow the existing `MuiButton`/`MuiChip` entries immediately above as the pattern to match.
+
+2. **`src/theme/createAppTheme.js`** — the *palette-dependent* half (background.paper, divider
+   border colour, text.secondary / primary.main action colours) belongs in
+   `createPaletteAwareComponents(palette)`, not in tokens.js — this is the existing
+   "palette-first ordering" pattern already used there for `MuiDivider`/`MuiButton.outlined`
+   (see lines 93-95 and 87-91 of the current file). Add, inside the object that function returns:
+   ```js
+   MuiBottomNavigation: {
+     styleOverrides: {
+       root: {
+         backgroundColor: palette.background.paper,
+         borderColor: palette.divider,
+       },
+     },
+   },
+   MuiBottomNavigationAction: {
+     styleOverrides: {
+       root: {
+         color: palette.text.secondary,
+         '&.Mui-selected': { color: palette.primary.main },
+       },
+     },
+   },
+   ```
+   `createAppTheme`'s deep-merge (bottom of the file) already layers this object after the static
+   `BASELINE_STATIC.components` block, so both halves land on the same MUI component slot — do not
+   duplicate a key across both files.
+
+3. **`src/theme/themeCompleteness.js`** — register the new surfaces in
+   `COMPONENT_SURFACES` (around line 90, alongside the existing `MuiChip`/`MuiPaper` entries), using
+   the same `componentPath()` / `componentKeyLeaf()` helpers already imported/defined in this file:
+   - `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.color')`
+   - `componentPath('MuiBottomNavigationAction', 'styleOverrides.label.fontSize')`
+   - `componentPath('MuiBottomNavigationAction', 'styleOverrides.label.fontWeight')`
+   - `componentKeyLeaf('MuiBottomNavigationAction', 'styleOverrides.root', '&.Mui-selected', 'color')`
+   These are what test 7 (non-vacuity) exercises: MUI's own `MuiBottomNavigation`/
+   `MuiBottomNavigationAction` defaults must differ from every one of these values, or the
+   completeness assertion is vacuously green (the existing `sameValue()` check in this file already
+   handles the comparison — no new logic needed here beyond registering the surfaces).
+
+4. **New file `src/components/MobileBottomNav.jsx`** (sibling of `src/components/UserListComponent.jsx`
+   etc. — this is a shared, non-auth component so it does not belong in `src/auth/`). Structure:
+   `Paper`-free — apply the fixed positioning, top-border and `env(safe-area-inset-bottom)` padding
+   directly via `sx` on `BottomNavigation` itself (do not rely on `MuiPaper`'s theme entry, which
+   already carries an unrelated `borderRadius: 8` default that would need overriding). Props exactly
+   as the Envelope's table: `destinations`, `activeRoute`, `onNavigate`, `hideAbove = 'md'`,
+   `zIndex = (theme) => theme.zIndex.drawer + 2` — default via a plain JS default parameter *value*
+   passed to `sx`, not stored in the theme (this is the one place the WO explicitly keeps a function,
+   component-local, matching jg's original). Each destination renders a `BottomNavigationAction` with
+   `icon` = `<Icon />` optionally wrapped in `<Badge badgeContent={...} />` when `badgeCount` is
+   truthy (`0`/`undefined` must render no `Badge` wrapper at all — a `Badge` with `badgeContent={0}`
+   still renders a dot with `showZero` unset only if MUI's default differs; simplest correct
+   implementation is to skip the `Badge` wrapper entirely when there is no count). `emphasis` applies
+   jg's raised-icon treatment (`backgroundColor: selected ? primary.main : background.paper`, `color`
+   inverted, `borderRadius: '50%'`, `transform: translateY(-4px)`) to that one destination's icon only
+   — reuse `theme.palette.background.paper`, not jg's `background.white` (a jg-only palette
+   extension not present in the ucm baseline — this is the intended parity difference the Envelope
+   names). Breakpoint hide: `useMediaQuery(theme.breakpoints.up(hideAbove))` → return `null` (mirror
+   jg's `useMediaQuery(theme.breakpoints.down('md'))` inverted for a configurable `hideAbove`).
+
+5. **`src/index.js`** — export `{ MobileBottomNav }` from `./components/MobileBottomNav`, placed in
+   the `--- 5. Components ---` section (after `QrSignupManager`, before `--- 6. Charts ---`).
+
+6. **`dev/entries.jsx`** — add one specimen entry, following the existing `NotificationBellEntry`
+   pattern (small wrapper function + one line in the `entries` array). Five destinations, two with
+   `badgeCount` set, one with `emphasis: true`, mirroring the Envelope's "Verification" section.
+   Import `MobileBottomNav` from `'../src/components/MobileBottomNav'` alongside the other `../src/`
+   imports at the top of the file.
+
+7. **New test file `tests/MobileBottomNav.test.jsx`** — follow `tests/UserMenu.test.jsx`'s structure
+   (jsdom environment pragma, `render`/`screen`/`fireEvent` from testing-library, `afterEach(cleanup)`).
+   Wrap the component in `ThemeProvider` with `createAppTheme({ palette: { primary: { main: '#0F62FE' } } })`
+   (check `tests/createAppTheme.test.js` for the exact call shape already used elsewhere in this
+   suite) since the component's selected-state colour comes from the theme, not inline `sx`. Cover
+   the seven "Required tests to WRITE" items from the Envelope verbatim — they are numbered 1-7
+   above and map 1:1 to test cases; item 7 (non-vacuity) belongs in
+   `tests/themeCompleteness.test.js` or `tests/createAppTheme.test.js` instead, wherever the existing
+   "missing surface produces a named finding" pattern already lives (see `themeCompleteness.test.js`
+   lines ~15-20 for the shape: `bare.findings.map(({ surface }) => surface)).toContain('...')`) —
+   do not duplicate that assertion pattern inside the new component test file.
+
+**Invariants / do-not-touch:** no edits to `BASELINE_PALETTE`, `typography`, `shape`, `spacing`, or
+the `shadows` array in `tokens.js` (Envelope non-goal). No edits to jg-ferien (separate `NAV-36` WO).
+No new i18n keys — `label`/`shortLabel` are finished strings per-prop, not translation keys.
+
+**Pitfalls already known:**
+- A function anywhere in `tokens.js`'s `components` tree fails `tests/createAppTheme.test.js`
+  immediately — the palette-aware colours MUST go in `createAppTheme.js`, not `tokens.js`.
+- `assertThemeComplete`'s non-vacuity depends on MUI's own `createTheme()` default for
+  `MuiBottomNavigation`/`MuiBottomNavigationAction` genuinely differing from the new baseline values
+  — verify this holds (MUI's stock action `minWidth` is `80`, not `0`, and stock has no
+  `borderTop`/`boxShadow: 'none'` on `MuiBottomNavigation` root, so all listed surfaces should clear
+  safely, but confirm rather than assume).
+- `env(safe-area-inset-bottom)` cannot be verified as "working" from a desktop viewport (Envelope
+  Verification section) — assert the CSS declaration is present, do not assert a computed non-zero
+  value.
+
+### Mini-handover
+
+Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.
+WO: `work-orders/SHELL-3.md`. Follow `orchestrate-codex`.