From b16ab3c294cddcd0e39cc2da17eb65d81ad27b59 Mon Sep 17 00:00:00 2001
From: Mao Nakamoto <41178744+maonakamoto@users.noreply.github.com>
Date: Tue, 28 Jul 2026 09:50:19 +0200
Subject: [PATCH] refactor(chrome): one SSOT per chrome shape (Panel,
 BottomNav, nav-state)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Header/footer/nav/panels now follow one design + code pattern instead of
~30 hand-rolled variants. Establishes three primitives and migrates the
highest-value duplications onto them.

New SSOT primitives:
- lib/design/nav.ts — NAV_STATE + navLinkClass(): the ONE definition of
  active/inactive per nav shape (sidebar/bottomTab/pill). Kills the
  ring-action/20-vs-/30-vs-inline fragmentation. admin-ui.navActive
  re-exports from it.
- components/ui/Panel.tsx — titled card-shell surface (title/subtitle/
  icon/action header slot). Replaces hand-rolled
  "bg-surface-base rounded-lg border p-5" + bespoke <h2>.
- components/layout/BottomNav.tsx — the byte-identical admin+dashboard
  mobile tab bar, in a neutral home (dashboard can't import app/admin).

Consolidations:
- Fold redundant ResponsiveHero into PageHero (1 consumer migrated; drops
  its inline-style dot-pattern, from-black gradient, color-ladder). Deleted.
- 6 panels -> <Panel>; RequestSidebar/TimecardHistorySidebar -> <Card>.
- Both bottom navs -> <BottomNav>; dashboard sheet pills -> navLinkClass('pill').
- AdminSidebar: 4x-repeated item -> navLinkClass('sidebar'); harmonize Hirn drift.
- NavItem: consume designPrimitive.focus (drop divergent inline ring).
- Fix duplicate-class "border border" typos in Contributions/Needs panels.

Docs: CLAUDE.md "Chrome & Navigation SSOT" section + audit greps.

Net -174 lines. verify green (typecheck, lint 0 err, i18n 16/16). Hero
migration visually confirmed light+dark.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  49 ++++++
 src/app/admin/AdminSidebar.tsx                |  25 +--
 src/app/admin/decisions/[id]/ResultsPanel.tsx |   7 +-
 .../services/open-source-solutions/page.tsx   |   8 +-
 src/components/admin/MobileBottomNav.tsx      |  61 ++-----
 .../admin/projects/ContributionsPanel.tsx     |  18 +-
 src/components/admin/projects/NeedsPanel.tsx  |  23 ++-
 src/components/admin/teams/TeamWorkPanels.tsx |  35 ++--
 .../dashboard/DashboardMobileNav.tsx          |  55 ++----
 .../timecards/TimecardHistorySidebar.tsx      |   9 +-
 src/components/decisions/VotingPanel.tsx      |  10 +-
 .../it-hilfe/detail/RequestSidebar.tsx        |  21 +--
 src/components/layout/BottomNav.tsx           |  73 ++++++++
 src/components/layout/ResponsiveHero.tsx      | 162 ------------------
 src/components/layout/header/NavItem.tsx      |   7 +-
 src/components/ui/Panel.tsx                   |  72 ++++++++
 src/lib/admin-ui.ts                           |   5 +-
 src/lib/design-system.ts                      |   3 +
 src/lib/design/nav.ts                         |  54 ++++++
 19 files changed, 361 insertions(+), 336 deletions(-)
 create mode 100644 src/components/layout/BottomNav.tsx
 delete mode 100644 src/components/layout/ResponsiveHero.tsx
 create mode 100644 src/components/ui/Panel.tsx
 create mode 100644 src/lib/design/nav.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index e89460701..3d2642c4f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -137,6 +137,46 @@ brand.*:   social (mastodon, linkedin, facebook) — bg-brand-mastodon etc.
 | Section BG white | `bg-white` (dark auto-handled) | `bg-white dark:bg-neutral-950` (unless deeper black needed) |
 | Card hover | `hover:border-neutral-300` | `hover:shadow-xl` |
 
+### Chrome & Navigation — one primitive per shape (SSOT)
+
+"Chrome" = the repeated structural shells: headers, footers, nav bars, panels,
+sidebars, bottom nav. Each SHAPE has exactly ONE primitive. Never hand-roll a
+card shell (`bg-surface-base rounded-lg border p-…`) or an active-nav class
+(`bg-action/10 … ring-action/20`, `text-action`, `border-action bg-action-muted`)
+inline — those are defined once and consumed everywhere. Retheming chrome = edit
+the primitive, not N components.
+
+| Need | Use | File | Never hand-roll |
+|---|---|---|---|
+| Titled bordered surface (title + subtitle + right action + body) | `<Panel title subtitle icon action>` | `components/ui/Panel.tsx` | `<div className="bg-surface-base rounded-lg border p-5">` + own `<h2>` |
+| Untitled surface | `<Card>` | `components/ui/card.tsx` | `<div className="card-shell p-6">` / `rounded-xl border bg-surface-base` |
+| Header row *inside* a card | `<AdminSectionHeader>` | `components/admin/AdminSectionHeader.tsx` | bespoke `flex justify-between` + divider |
+| Full-bleed page hero (centered) | `<PageHero theme title subtitle>` | `components/layout/PageHero.tsx` | a one-off `<section>` with a bespoke `<h1>` type string |
+| Page-section vertical rhythm / tinted band | `<Section density tone>` | `components/layout/Section.tsx` | hardcoded `py-16 sm:py-20 …` |
+| Mobile bottom tab bar (`<lg`) | `<BottomNav items ariaLabel more>` | `components/layout/BottomNav.tsx` | a `fixed bottom-0 … flex` `<nav>` + tab loop |
+| Active/inactive nav item classes | `navLinkClass(shape, active)` / `NAV_STATE` | `lib/design/nav.ts` | inline `text-action` / `ring-action/20` ladders |
+
+Rules:
+- **Nav state is one definition.** `NAV_STATE` (`sidebar` / `bottomTab` / `pill`)
+  is the ONLY place "current page" is styled. `adminInteractive.navActive`
+  re-exports `NAV_STATE.sidebar.active` — the value lives in `nav.ts`, not admin.
+  Need a new nav shape? Add it to `NAV_STATE`, don't hand-roll a sixth encoding.
+- **Neutral home for shared chrome.** Dashboard must not import from `app/admin/*`
+  (see SoC rule). `BottomNav` + `nav.ts` live in neutral `components/layout` /
+  `lib/design` so admin, dashboard, and public all consume them.
+- **One primitive per shape.** If you find yourself building a second "hero" or a
+  second "bottom bar," extend the existing primitive with a prop — don't fork it.
+  (This is why `ResponsiveHero` was folded into `PageHero`.)
+- **Card shell = `card-shell` only** (rounded-xl + border + surface, NO shadow).
+  `<Card>`/`<Panel>` both resolve to it. `rounded-lg`, missing border, or
+  `shadow-xs` on a static card is drift — fix it, don't copy it.
+
+Deliberately NOT unified (yet): the right-edge **drawer/sheet** overlay
+(MessageSidebar, MobileMenu, DashboardMobileNav sheet) — a shared `<Drawer>`
+with focus-trap + scroll-lock is the next chrome primitive; until it lands,
+match MobileMenu's implementation (scrim `bg-black/40 backdrop-blur-xs`, focus
+trap via `useFocusTrap`, body scroll-lock) and never `bg-opacity-*`.
+
 ### Mobile-first = ACTION-first, not stats-first
 
 On a phone, the user opened the page to DO the one thing the page is for —
@@ -207,5 +247,14 @@ grep -rn 'shadow-lg\|shadow-xl\|shadow-2xl' src/app/[locale]/ src/components/
 
 # Gradient backgrounds that should be flat
 grep -rn 'bg-gradient-to' src/app/[locale]/ src/components/ | grep -v 'from-black\|to-transparent'
+
+# Hand-rolled card shells — should be <Card>/<Panel> (resolve to card-shell)
+grep -rnE 'bg-surface-base rounded-(lg|xl) border' src/components src/app
+
+# Nav-active drift — active state must come from NAV_STATE / navLinkClass
+grep -rn 'ring-action/30' src/components src/app
+
+# Deprecated opacity utility on scrims (use bg-black/NN)
+grep -rn 'bg-opacity-' src/components src/app
 ```
 
diff --git a/src/app/admin/AdminSidebar.tsx b/src/app/admin/AdminSidebar.tsx
index dbc1495b4..ae452a13d 100644
--- a/src/app/admin/AdminSidebar.tsx
+++ b/src/app/admin/AdminSidebar.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useMemo } from 'react'
 import { adminInteractive } from '@/lib/admin-ui'
+import { navLinkClass } from '@/lib/design/nav'
 import { useTranslations } from 'next-intl'
 import Link from 'next/link'
 import { Link as PublicLink } from '@/i18n/navigation'
@@ -212,11 +213,7 @@ export function AdminSidebar({
                   key={section.path}
                   href={section.path}
                   onClick={() => { setMobileMenuOpen(false); setFilterQuery('') }}
-                  className={`flex items-center gap-2.5 rounded-lg px-2 py-3 lg:py-1.5 transition-colors ${
-                    isActive(section.path)
-                      ? adminInteractive.navActive
-                      : `text-text-tertiary ${adminInteractive.rowHoverSubtle} hover:text-text-primary`
-                  }`}
+                  className={navLinkClass('sidebar', isActive(section.path))}
                 >
                   <Icon className="h-4 w-4 shrink-0 text-text-muted dark:text-text-secondary" />
                   <span className="flex-1 text-sm font-medium">
@@ -250,13 +247,7 @@ export function AdminSidebar({
                 <Link
                   href={only.path}
                   onClick={() => setMobileMenuOpen(false)}
-                  className={`flex items-center gap-2.5 rounded-lg px-2 py-3 lg:py-1.5 transition-colors ${
-                    sidebarCollapsed ? 'justify-center' : ''
-                  } ${
-                    onlyActive
-                      ? adminInteractive.navActive
-                      : `text-text-tertiary ${adminInteractive.rowHoverSubtle} hover:text-text-primary`
-                  }`}
+                  className={navLinkClass('sidebar', onlyActive, sidebarCollapsed ? 'justify-center' : '')}
                   title={sidebarCollapsed ? sectionLabel(tSections, only) : undefined}
                 >
                   <OnlyIcon className={`shrink-0 ${sidebarCollapsed ? 'h-5 w-5' : 'h-4 w-4'} ${onlyActive ? 'text-action' : 'text-text-muted dark:text-text-secondary'}`} />
@@ -299,13 +290,7 @@ export function AdminSidebar({
                         key={section.path}
                         href={section.path}
                         onClick={() => setMobileMenuOpen(false)}
-                        className={`flex items-center gap-2.5 rounded-lg px-2 py-3 lg:py-1.5 transition-colors ${
-                          sidebarCollapsed ? 'justify-center' : ''
-                        } ${
-                          active
-                            ? adminInteractive.navActive
-                            : `text-text-tertiary ${adminInteractive.rowHoverSubtle} hover:text-text-primary`
-                        }`}
+                        className={navLinkClass('sidebar', active, sidebarCollapsed ? 'justify-center' : '')}
                         title={sidebarCollapsed ? `${sectionLabel(tSections, section)}${sensitive ? ` (${t('sensitiveLabel')})` : ''}` : sensitivityReason}
                       >
                         {/* Larger icon when collapsed so it's easier to tap and recognise at a glance */}
@@ -340,7 +325,7 @@ export function AdminSidebar({
                 sidebarCollapsed ? 'justify-center' : ''
               } ${
                 isActive(hirnSection.path)
-                  ? 'bg-action/10 text-action ring-1 ring-action/30'
+                  ? adminInteractive.navActive
                   : 'text-text-secondary hover:bg-action/10'
               }`}
               title={sidebarCollapsed ? t('hirnTitle') : undefined}
diff --git a/src/app/admin/decisions/[id]/ResultsPanel.tsx b/src/app/admin/decisions/[id]/ResultsPanel.tsx
index ca63640b2..955330f96 100644
--- a/src/app/admin/decisions/[id]/ResultsPanel.tsx
+++ b/src/app/admin/decisions/[id]/ResultsPanel.tsx
@@ -8,7 +8,7 @@ import {
   type ConsentResponse,
   type SimpleMajorityResponse,
 } from '@/config/decisions';
-import Heading from '@/components/admin/AdminHeading';
+import { Panel } from '@/components/ui/Panel';
 
 interface RankedOption {
   id: string;
@@ -103,8 +103,7 @@ export default function ResultsPanel({ outcome, outcomeSummary, votingMethod, ai
   if (!data) return null;
 
   return (
-    <div className="rounded-lg bg-surface-base p-6 shadow-xs">
-      <Heading level={2} className="mb-4 text-lg font-semibold text-text-primary">Ergebnis</Heading>
+    <Panel title="Ergebnis" className="p-6">
 
       {/* AI Outcome Narrative — Beschluss hero */}
       {aiOutcomeNarrative && (
@@ -284,6 +283,6 @@ export default function ResultsPanel({ outcome, outcomeSummary, votingMethod, ai
           <p className="mt-1 text-sm text-action">{outcomeSummary}</p>
         </div>
       )}
-    </div>
+    </Panel>
   );
 }
diff --git a/src/app/services/open-source-solutions/page.tsx b/src/app/services/open-source-solutions/page.tsx
index c9ccabc56..c121765a2 100644
--- a/src/app/services/open-source-solutions/page.tsx
+++ b/src/app/services/open-source-solutions/page.tsx
@@ -1,5 +1,5 @@
 import { Metadata } from 'next'
-import { ResponsiveHero } from '@/components/layout/ResponsiveHero'
+import { PageHero } from '@/components/layout/PageHero'
 import { BenefitsSection } from './components/BenefitsSection'
 import { ServicesSection } from './components/ServicesSection'
 import { ComparisonSection } from './components/ComparisonSection'
@@ -24,10 +24,10 @@ export default function OpenSourceSolutionsPage() {
   return (
     <main>
       {/* Hero Section */}
-      <ResponsiveHero
+      <PageHero
+        theme="services"
         title="Open-Source-Lösungen"
-        description="Professionelle Implementierung von Open-Source-Software, die proprietären Alternativen entspricht oder diese übertrifft."
-        backgroundColor="green"
+        subtitle="Professionelle Implementierung von Open-Source-Software, die proprietären Alternativen entspricht oder diese übertrifft."
       />
 
       {/* Benefits Section */}
diff --git a/src/components/admin/MobileBottomNav.tsx b/src/components/admin/MobileBottomNav.tsx
index f27e1aaec..43e5e4236 100644
--- a/src/components/admin/MobileBottomNav.tsx
+++ b/src/components/admin/MobileBottomNav.tsx
@@ -1,9 +1,8 @@
 'use client'
 
 import { useTranslations } from 'next-intl'
-import { Link, usePathname } from '@/i18n/navigation'
-import { Menu } from 'lucide-react'
-import { Button } from '@/components/ui/button'
+import { usePathname } from '@/i18n/navigation'
+import { BottomNav } from '@/components/layout/BottomNav'
 import { getMobileBottomNavSections } from '@/config/sections'
 import { sectionShortLabel } from '@/lib/section-labels'
 
@@ -24,49 +23,25 @@ interface MobileBottomNavProps {
  */
 export function MobileBottomNav({ accessibleSections, onMenuClick }: MobileBottomNavProps) {
   const pathname = usePathname()
-  const items = getMobileBottomNavSections(accessibleSections)
+  const sections = getMobileBottomNavSections(accessibleSections)
   const t = useTranslations('admin.sidebar')
   const tSections = useTranslations('admin.sections')
 
-  return (
-    <nav
-      className="fixed bottom-0 left-0 right-0 z-50 flex border-t border bg-surface-base safe-area-inset-bottom lg:hidden"
-      aria-label={t('navAria')}
-    >
-      {items.map(section => {
-        // Dashboard ("/admin") needs exact-match so it isn't lit for
-        // every /admin/* page; everything else uses prefix-match.
-        const exact = section.path === '/admin'
-        const active = exact ? pathname === section.path : pathname.startsWith(section.path)
-        const Icon = section.ui.icon
-        const label = sectionShortLabel(tSections, section)
-        return (
-          <Link
-            key={section.id}
-            href={section.path}
-            className={`flex-1 flex flex-col items-center justify-center gap-0.5 py-2 min-h-[56px] text-xs transition-colors ${
-              active
-                ? 'text-action'
-                : 'text-text-tertiary dark:text-text-tertiary hover:text-text-secondary'
-            }`}
-            aria-current={active ? 'page' : undefined}
-          >
-            <Icon className="w-5 h-5" aria-hidden="true" />
-            <span>{label}</span>
-          </Link>
-        )
-      })}
+  const items = sections.map(section => ({
+    key: section.id,
+    href: section.path,
+    label: sectionShortLabel(tSections, section),
+    icon: section.ui.icon,
+    // Dashboard ("/admin") needs exact-match so it isn't lit for every
+    // /admin/* page; everything else uses prefix-match.
+    active: section.path === '/admin' ? pathname === section.path : pathname.startsWith(section.path),
+  }))
 
-      {/* Mehr — opens sidebar */}
-      <Button
-        variant="ghost"
-        onClick={onMenuClick}
-        className="flex-1 flex flex-col items-center justify-center gap-0.5 py-2 min-h-[56px] h-auto text-xs text-text-tertiary hover:text-text-secondary rounded-none"
-        aria-label={t('openAria')}
-      >
-        <Menu className="w-5 h-5" aria-hidden="true" />
-        <span>{t('mobileMore')}</span>
-      </Button>
-    </nav>
+  return (
+    <BottomNav
+      items={items}
+      ariaLabel={t('navAria')}
+      more={{ label: t('mobileMore'), ariaLabel: t('openAria'), onClick: onMenuClick }}
+    />
   )
 }
diff --git a/src/components/admin/projects/ContributionsPanel.tsx b/src/components/admin/projects/ContributionsPanel.tsx
index 8a83e9f2f..9f920ca53 100644
--- a/src/components/admin/projects/ContributionsPanel.tsx
+++ b/src/components/admin/projects/ContributionsPanel.tsx
@@ -12,6 +12,7 @@ import { toast } from 'sonner'
 import { apiFetch } from '@/lib/api/client'
 import { cn } from '@/lib/utils'
 import { designPrimitive } from '@/lib/design-system'
+import { Panel } from '@/components/ui/Panel'
 import { Button } from '@/components/ui/button'
 import { Select } from '@/components/ui/select'
 import { Textarea } from '@/components/ui/textarea'
@@ -82,12 +83,10 @@ export function ContributionsPanel({ slug, initialContributions, needs }: Props)
   }
 
   return (
-    <section className={cn(designPrimitive.surface.card, 'p-4 sm:p-5')}>
-      <div className="flex flex-wrap items-start justify-between gap-3 mb-4">
-        <div className="min-w-0">
-          <h2 className="text-base font-semibold text-text-primary">{t('contributions.title')}</h2>
-          <p className="text-xs text-text-tertiary mt-0.5">{t('contributions.subtitle')}</p>
-        </div>
+    <Panel
+      title={t('contributions.title')}
+      subtitle={t('contributions.subtitle')}
+      action={
         <Select
           value={filter}
           onChange={e => setFilter(e.target.value as ContributionStatus | 'all')}
@@ -98,7 +97,8 @@ export function ContributionsPanel({ slug, initialContributions, needs }: Props)
             <option key={s} value={s}>{t(`contributionStatusLabels.${s}`)}</option>
           ))}
         </Select>
-      </div>
+      }
+    >
 
       {filtered.length === 0 ? (
         <p className="text-sm text-text-tertiary text-center py-8">
@@ -111,7 +111,7 @@ export function ContributionsPanel({ slug, initialContributions, needs }: Props)
           {filtered.map(c => {
             const need = c.needId ? needById[c.needId] : null
             return (
-              <div key={c.id} className="rounded-lg border border p-3 sm:p-4">
+              <div key={c.id} className="rounded-lg border p-3 sm:p-4">
                 <div className="flex flex-wrap items-start justify-between gap-2 mb-3">
                   <div className="min-w-0">
                     <div className="flex flex-wrap items-center gap-2 mb-1">
@@ -187,6 +187,6 @@ export function ContributionsPanel({ slug, initialContributions, needs }: Props)
           })}
         </div>
       )}
-    </section>
+    </Panel>
   )
 }
diff --git a/src/components/admin/projects/NeedsPanel.tsx b/src/components/admin/projects/NeedsPanel.tsx
index b0278c507..d89ae7005 100644
--- a/src/components/admin/projects/NeedsPanel.tsx
+++ b/src/components/admin/projects/NeedsPanel.tsx
@@ -11,8 +11,7 @@ import { useState, useTransition, type FormEvent } from 'react'
 import { useTranslations } from 'next-intl'
 import { toast } from 'sonner'
 import { apiFetch } from '@/lib/api/client'
-import { cn } from '@/lib/utils'
-import { designPrimitive } from '@/lib/design-system'
+import { Panel } from '@/components/ui/Panel'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Select } from '@/components/ui/select'
@@ -108,12 +107,10 @@ export function NeedsPanel({ slug, initialNeeds }: Props) {
   }
 
   return (
-    <section className={cn(designPrimitive.surface.card, 'p-4 sm:p-5 mb-5')}>
-      <div className="flex flex-wrap items-start justify-between gap-3 mb-4">
-        <div className="min-w-0">
-          <h2 className="text-base font-semibold text-text-primary">{t('needs.title')}</h2>
-          <p className="text-xs text-text-tertiary mt-0.5">{t('needs.subtitle')}</p>
-        </div>
+    <Panel
+      title={t('needs.title')}
+      subtitle={t('needs.subtitle')}
+      action={
         <Button
           type="button"
           variant="primary"
@@ -124,12 +121,14 @@ export function NeedsPanel({ slug, initialNeeds }: Props) {
           <Plus className="h-3.5 w-3.5" />
           {t('needs.new')}
         </Button>
-      </div>
+      }
+      className="mb-5"
+    >
 
       {adding && (
         <form
           onSubmit={handleAdd}
-          className="grid gap-3 grid-cols-1 sm:grid-cols-2 mb-5 p-3 rounded-lg border border bg-surface-raised dark:bg-surface-base/3"
+          className="grid gap-3 grid-cols-1 sm:grid-cols-2 mb-5 p-3 rounded-lg border bg-surface-raised dark:bg-surface-base/3"
         >
           <Select name="type" variant="elevated">
             {Object.values(NEED_TYPES).map(v => (
@@ -169,7 +168,7 @@ export function NeedsPanel({ slug, initialNeeds }: Props) {
           {needs.map(need => (
             <div
               key={need.id}
-              className="rounded-lg border border p-3 space-y-2"
+              className="rounded-lg border p-3 space-y-2"
             >
               {/* Row 1 — main editable line. Stacks on mobile, lays out responsively on larger screens */}
               <div className="grid grid-cols-1 sm:grid-cols-12 gap-2">
@@ -252,6 +251,6 @@ export function NeedsPanel({ slug, initialNeeds }: Props) {
           ))}
         </div>
       )}
-    </section>
+    </Panel>
   )
 }
diff --git a/src/components/admin/teams/TeamWorkPanels.tsx b/src/components/admin/teams/TeamWorkPanels.tsx
index a97fe62c0..b25ac4920 100644
--- a/src/components/admin/teams/TeamWorkPanels.tsx
+++ b/src/components/admin/teams/TeamWorkPanels.tsx
@@ -1,5 +1,6 @@
 import Link from 'next/link'
 import { ClipboardList, FileText, Plus } from 'lucide-react'
+import { Panel } from '@/components/ui/Panel'
 import { buttonClass } from '@/components/ui/button-class'
 import { ROUTES } from '@/config/routes'
 import { TASK_PRIORITY_LABELS, TASK_PRIORITY_COLORS, type TaskPriority } from '@/config/tasks'
@@ -19,13 +20,15 @@ export function TeamTasksPanel({ teamId, tasks, total }: {
   total: number
 }) {
   return (
-    <section className="bg-surface-base rounded-lg border p-5">
-      <div className="flex items-center justify-between mb-3">
-        <h2 className="text-sm font-semibold text-text-primary flex items-center gap-1.5">
-          <ClipboardList className="w-4 h-4 text-text-tertiary" aria-hidden />
+    <Panel
+      icon={ClipboardList}
+      title={
+        <>
           Offene Aufgaben
           {total > 0 && <span className="text-text-tertiary font-normal">({total})</span>}
-        </h2>
+        </>
+      }
+      action={
         <Link
           href={`${ROUTES.admin.taskNew}?team=${teamId}`}
           className={buttonClass({ variant: 'secondary', size: 'sm' })}
@@ -33,8 +36,8 @@ export function TeamTasksPanel({ teamId, tasks, total }: {
           <Plus className="w-4 h-4" />
           Neue Aufgabe
         </Link>
-      </div>
-
+      }
+    >
       {tasks.length === 0 ? (
         <p className="text-sm text-text-tertiary">
           Keine offenen Aufgaben — dieses Team hat gerade nichts Pendentes.
@@ -68,7 +71,7 @@ export function TeamTasksPanel({ teamId, tasks, total }: {
           ))}
         </ul>
       )}
-    </section>
+    </Panel>
   )
 }
 
@@ -77,12 +80,10 @@ export function TeamProtocolsPanel({ teamId, protocols }: {
   protocols: TeamProtocolItem[]
 }) {
   return (
-    <section className="bg-surface-base rounded-lg border p-5">
-      <div className="flex items-center justify-between mb-3">
-        <h2 className="text-sm font-semibold text-text-primary flex items-center gap-1.5">
-          <FileText className="w-4 h-4 text-text-tertiary" aria-hidden />
-          Protokolle
-        </h2>
+    <Panel
+      icon={FileText}
+      title="Protokolle"
+      action={
         <Link
           href={`${ROUTES.admin.protocolNew}?team=${teamId}`}
           className={buttonClass({ variant: 'secondary', size: 'sm' })}
@@ -90,8 +91,8 @@ export function TeamProtocolsPanel({ teamId, protocols }: {
           <Plus className="w-4 h-4" />
           Neues Protokoll
         </Link>
-      </div>
-
+      }
+    >
       {protocols.length === 0 ? (
         <p className="text-sm text-text-tertiary">
           Noch keine Protokolle — Sitzungsnotizen landen hier, wenn beim Protokoll dieses Team gewählt ist.
@@ -118,6 +119,6 @@ export function TeamProtocolsPanel({ teamId, protocols }: {
           ))}
         </ul>
       )}
-    </section>
+    </Panel>
   )
 }
diff --git a/src/components/dashboard/DashboardMobileNav.tsx b/src/components/dashboard/DashboardMobileNav.tsx
index a74300ac0..1f9a54e3c 100644
--- a/src/components/dashboard/DashboardMobileNav.tsx
+++ b/src/components/dashboard/DashboardMobileNav.tsx
@@ -2,9 +2,11 @@
 
 import { useEffect, useMemo, useState } from 'react'
 import { createPortal } from 'react-dom'
-import { Menu, X } from 'lucide-react'
+import { X } from 'lucide-react'
 import { Link, usePathname } from '@/i18n/navigation'
 import { Button } from '@/components/ui/button'
+import { BottomNav } from '@/components/layout/BottomNav'
+import { navLinkClass } from '@/lib/design/nav'
 import { useFocusTrap } from '@/hooks/useFocusTrap'
 import {
   DASHBOARD_CATEGORIES,
@@ -86,39 +88,18 @@ export function DashboardMobileNav({
 
   return (
     <>
-      {/* Bottom tab bar */}
-      <nav
-        aria-label="Dashboard"
-        className="fixed bottom-0 left-0 right-0 z-40 flex border-t border-subtle bg-surface-base lg:hidden"
-      >
-        {barItems.map(item => {
-          const active = isActive(pathname, item.href)
-          const Icon = item.icon
-          return (
-            <Link
-              key={item.id}
-              href={item.href}
-              aria-current={active ? 'page' : undefined}
-              className={`flex min-h-[56px] flex-1 flex-col items-center justify-center gap-0.5 py-2 text-xs transition-colors ${
-                active ? 'text-action' : 'text-text-tertiary hover:text-text-secondary'
-              }`}
-            >
-              <Icon className="h-5 w-5 shrink-0" aria-hidden="true" />
-              <span className="max-w-full truncate px-1">{item.shortLabel ?? item.title}</span>
-            </Link>
-          )
-        })}
-        <Button
-          variant="ghost"
-          onClick={() => setMoreOpen(true)}
-          aria-label="Mehr anzeigen"
-          aria-expanded={moreOpen}
-          className="flex min-h-[56px] flex-1 flex-col items-center justify-center gap-0.5 rounded-none py-2 text-xs text-text-tertiary hover:text-text-secondary h-auto"
-        >
-          <Menu className="h-5 w-5" aria-hidden="true" />
-          <span>Mehr</span>
-        </Button>
-      </nav>
+      {/* Bottom tab bar — SSOT bar chrome; the "Mehr" sheet is dashboard-specific. */}
+      <BottomNav
+        ariaLabel="Dashboard"
+        items={barItems.map(item => ({
+          key: item.id,
+          href: item.href,
+          label: item.shortLabel ?? item.title,
+          icon: item.icon,
+          active: isActive(pathname, item.href),
+        }))}
+        more={{ label: 'Mehr', ariaLabel: 'Mehr anzeigen', onClick: () => setMoreOpen(true), expanded: moreOpen }}
+      />
 
       {/* "Mehr" bottom sheet */}
       {mounted && moreOpen && createPortal(
@@ -160,11 +141,7 @@ export function DashboardMobileNav({
                           key={card.id}
                           href={card.href}
                           aria-current={active ? 'page' : undefined}
-                          className={`flex items-center gap-2 rounded-lg border px-3 py-2.5 text-sm transition-colors ${
-                            active
-                              ? 'border-action bg-action-muted text-action'
-                              : 'border-subtle text-text-secondary hover:border-strong hover:text-text-primary'
-                          }`}
+                          className={navLinkClass('pill', active)}
                         >
                           <Icon className="h-4 w-4 shrink-0" aria-hidden="true" />
                           <span className="min-w-0 truncate">{card.title}</span>
diff --git a/src/components/dashboard/timecards/TimecardHistorySidebar.tsx b/src/components/dashboard/timecards/TimecardHistorySidebar.tsx
index 7dce338c3..0a82d2e68 100644
--- a/src/components/dashboard/timecards/TimecardHistorySidebar.tsx
+++ b/src/components/dashboard/timecards/TimecardHistorySidebar.tsx
@@ -12,6 +12,7 @@ import { useLocale, useTranslations } from 'next-intl'
 import { TIMECARD_STATUS_COLORS, TIMECARD_STATUSES } from '@/config/timecards'
 import type { TimecardStatus } from '@/config/timecards'
 import { ROUTES } from '@/config/routes'
+import { Card } from '@/components/ui/card'
 import { formatDateShort } from '@/lib/date-formats'
 import { Clock } from 'lucide-react'
 import { TIMECARD_STATUS_ICONS } from '@/lib/team/timecard-display'
@@ -38,17 +39,17 @@ export function TimecardHistorySidebar({ history }: Props) {
 
   if (history.length === 0) {
     return (
-      <div className="rounded-xl border bg-surface-base p-5">
+      <Card className="p-5">
         <h2 className="text-sm font-semibold text-text-primary mb-2">{t('historyTitle')}</h2>
         <p className="text-sm text-text-tertiary">
           {t('historyEmpty')}
         </p>
-      </div>
+      </Card>
     )
   }
 
   return (
-    <div className="rounded-xl border bg-surface-base overflow-hidden">
+    <Card className="overflow-hidden">
       <div className="px-5 py-4 border-b border">
         <h2 className="text-sm font-semibold text-text-primary">{t('historyTitle')}</h2>
         <p className="text-xs text-text-tertiary">
@@ -100,6 +101,6 @@ export function TimecardHistorySidebar({ history }: Props) {
           )
         })}
       </ul>
-    </div>
+    </Card>
   )
 }
diff --git a/src/components/decisions/VotingPanel.tsx b/src/components/decisions/VotingPanel.tsx
index 575dbb3b8..8bccc896d 100644
--- a/src/components/decisions/VotingPanel.tsx
+++ b/src/components/decisions/VotingPanel.tsx
@@ -5,7 +5,7 @@ import { DECISION_STATUS, type VotingMethod } from '@/config/decisions';
 import { apiFetch } from '@/lib/api/client';
 import { Button } from '@/components/ui/button';
 import { useVoteState } from '@/hooks/useVoteState';
-import Heading from '@/components/admin/AdminHeading';
+import { Panel } from '@/components/ui/Panel';
 import { DeadlineCountdown } from './voting/DeadlineCountdown';
 import { ConsentVote } from './voting/ConsentVote';
 import { ApprovalVote } from './voting/ApprovalVote';
@@ -111,17 +111,13 @@ export default function VotingPanel({
         />
       )}
 
-      <div className="rounded-lg bg-surface-base p-6 shadow-xs">
+      <Panel title="Deine Stimme" className="p-6">
       {votingDeadline && status === DECISION_STATUS.VOTING && (
         <div className="mb-4">
           <DeadlineCountdown deadline={votingDeadline} />
         </div>
       )}
 
-      <Heading level={2} className="mb-4 text-lg font-semibold text-text-primary">
-        Deine Stimme
-      </Heading>
-
       {error && (
         <div className="mb-4 rounded-md bg-error-50 dark:bg-error-900/20 p-3 text-sm text-error-700 dark:text-error-300">{error}</div>
       )}
@@ -180,7 +176,7 @@ export default function VotingPanel({
       >
         {submitting ? 'Wird gesendet...' : 'Stimme abgeben'}
       </Button>
-      </div>
+      </Panel>
     </div>
   );
 }
diff --git a/src/components/it-hilfe/detail/RequestSidebar.tsx b/src/components/it-hilfe/detail/RequestSidebar.tsx
index 5209f13c9..e1c5c8deb 100644
--- a/src/components/it-hilfe/detail/RequestSidebar.tsx
+++ b/src/components/it-hilfe/detail/RequestSidebar.tsx
@@ -4,6 +4,7 @@ import { useState } from 'react'
 import { Link } from '@/i18n/navigation'
 import { useTranslations } from 'next-intl'
 import Heading from '@/components/ui/Heading'
+import { Card } from '@/components/ui/card'
 import { Button } from '@/components/ui/button'
 import {
   MapPin,
@@ -60,7 +61,7 @@ export function RequestSidebar({
   return (
     <div className="space-y-6">
       {/* Request Info */}
-      <div className="card-shell p-6">
+      <Card className="p-6">
         <Heading level={3} className="text-sm font-medium text-text-tertiary uppercase tracking-wider mb-4">
           {t('sidebarDetails')}
         </Heading>
@@ -138,11 +139,11 @@ export function RequestSidebar({
             </div>
           </div>
         </div>
-      </div>
+      </Card>
 
       {/* Preferred technician (owner only) */}
       {request.isOwner && request.preferredTechnicianId && request.preferredTechnicianName && (
-        <div className="card-shell p-6">
+        <Card className="p-6">
           <Heading level={3} className="text-sm font-medium text-text-tertiary uppercase tracking-wider mb-4">
             {t('preferredTechnicianSidebar.title')}
           </Heading>
@@ -164,11 +165,11 @@ export function RequestSidebar({
               </Link>
             </div>
           </div>
-        </div>
+        </Card>
       )}
 
       {/* Requester Info */}
-      <div className="card-shell p-6">
+      <Card className="p-6">
         <Heading level={3} className="text-sm font-medium text-text-tertiary uppercase tracking-wider mb-4">
           {t('requesterSection')}
         </Heading>
@@ -183,21 +184,21 @@ export function RequestSidebar({
             )}
           </div>
         </div>
-      </div>
+      </Card>
 
       {/* Message Button */}
       {conversationId && hasSession && (
-        <div className="card-shell p-6">
+        <Card className="p-6">
           <Button onClick={onShowMessages} variant="primary" className="w-full">
             <MessageSquare className="w-4 h-4" aria-hidden="true" />
             {t('sendMessage')}
           </Button>
-        </div>
+        </Card>
       )}
 
       {/* Owner Actions */}
       {request.isOwner && (
-        <div className="card-shell p-6">
+        <Card className="p-6">
           <Heading level={3} className="text-sm font-medium text-text-tertiary uppercase tracking-wider mb-4">
             {t('actionsSection')}
           </Heading>
@@ -222,7 +223,7 @@ export function RequestSidebar({
               {t('allMyRequests')}
             </Button>
           </div>
-        </div>
+        </Card>
       )}
     </div>
   )
diff --git a/src/components/layout/BottomNav.tsx b/src/components/layout/BottomNav.tsx
new file mode 100644
index 000000000..2840a6a5b
--- /dev/null
+++ b/src/components/layout/BottomNav.tsx
@@ -0,0 +1,73 @@
+'use client'
+
+import type { LucideIcon } from 'lucide-react'
+import { Menu } from 'lucide-react'
+import { Link } from '@/i18n/navigation'
+import { Button } from '@/components/ui/button'
+import { navLinkClass } from '@/lib/design/nav'
+
+export interface BottomNavItem {
+  key: string
+  href: string
+  label: string
+  icon: LucideIcon
+  active: boolean
+}
+
+interface BottomNavProps {
+  items: BottomNavItem[]
+  /** Accessible name for the <nav>. */
+  ariaLabel: string
+  /** Optional trailing "more" button (opens a sheet or the full sidebar). */
+  more?: { label: string; ariaLabel: string; onClick: () => void; expanded?: boolean }
+}
+
+/**
+ * BottomNav — the SSOT mobile bottom tab bar (`<lg` only).
+ *
+ * The admin shell and the user dashboard rendered this bar as two byte-identical
+ * copies (differing only by an accidental `z-40` vs `z-50` and `border` vs
+ * `border-subtle`). Both now feed items into this one component; item state
+ * comes from the nav-state SSOT (`navLinkClass('bottomTab', …)`).
+ *
+ * Neutral location (`components/layout`) so the dashboard can use it without
+ * importing from `app/admin/*` (forbidden by CLAUDE.md). Pair it with
+ * `.has-bottom-nav` on the shell so `--bottom-nav-clearance` keeps content clear
+ * of the bar (see globals.css).
+ */
+export function BottomNav({ items, ariaLabel, more }: BottomNavProps) {
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className="fixed bottom-0 left-0 right-0 z-50 flex border-t border bg-surface-base safe-area-inset-bottom lg:hidden"
+    >
+      {items.map(item => {
+        const Icon = item.icon
+        return (
+          <Link
+            key={item.key}
+            href={item.href}
+            aria-current={item.active ? 'page' : undefined}
+            className={navLinkClass('bottomTab', item.active)}
+          >
+            <Icon className="h-5 w-5 shrink-0" aria-hidden="true" />
+            <span className="max-w-full truncate px-1">{item.label}</span>
+          </Link>
+        )
+      })}
+
+      {more && (
+        <Button
+          variant="ghost"
+          onClick={more.onClick}
+          aria-label={more.ariaLabel}
+          aria-expanded={more.expanded}
+          className={navLinkClass('bottomTab', false, 'h-auto rounded-none')}
+        >
+          <Menu className="h-5 w-5 shrink-0" aria-hidden="true" />
+          <span>{more.label}</span>
+        </Button>
+      )}
+    </nav>
+  )
+}
diff --git a/src/components/layout/ResponsiveHero.tsx b/src/components/layout/ResponsiveHero.tsx
deleted file mode 100644
index b72fbb476..000000000
--- a/src/components/layout/ResponsiveHero.tsx
+++ /dev/null
@@ -1,162 +0,0 @@
-/**
- * ResponsiveHero Component
- * 
- * A reusable hero section component with consistent responsive styling.
- * Replaces manual hero implementations across pages.
- * 
- * Created: 2025-01-27
- * Last Modified: 2025-01-27
- * Last Modified Summary: Created reusable responsive hero component
- */
-
-import { ReactNode } from 'react'
-import { responsiveSpacing, responsiveTypography, responsiveButtons } from '@/lib/responsive'
-import { cn } from '@/lib/utils'
-import { getTextColor, getBackgroundColor, getButtonVariant } from '@/lib/design-system'
-import Link from 'next/link'
-import { HERO_PATTERN_BACKGROUND } from '@/config/ui-colors'
-
-export interface ResponsiveHeroProps {
-  title: string
-  subtitle?: string
-  description?: string
-  children?: ReactNode
-  className?: string
-  backgroundColor?: 'green' | 'blue' | 'gray' | 'white'
-  backgroundPattern?: boolean
-  ctas?: Array<{
-    text: string
-    href: string
-    variant?: 'primary' | 'secondary' | 'outline'
-  }>
-}
-
-export function ResponsiveHero({
-  title,
-  subtitle,
-  description,
-  children,
-  className,
-  backgroundColor = 'green',
-  backgroundPattern = true,
-  ctas,
-}: ResponsiveHeroProps) {
-  const bgClasses = {
-    green: cn(
-      'bg-action',
-      getTextColor('primary', 'primary')
-    ),
-    blue: cn(
-      'bg-surface-overlay',
-      getTextColor('dark', 'primary')
-    ),
-    gray: cn(
-      'bg-surface-overlay',
-      getTextColor('dark', 'primary')
-    ),
-    white: cn(
-      getBackgroundColor('white'),
-      getTextColor('white', 'primary')
-    ),
-  }
-
-  const buttonClasses = {
-    primary: cn(
-      'bg-surface-base text-action hover:bg-action-muted',
-      responsiveButtons.primary,
-      'rounded-lg font-semibold transition-colors duration-300 text-center min-h-touch'
-    ),
-    secondary: cn(
-      getButtonVariant('primary').bg,
-      getButtonVariant('primary').text,
-      getButtonVariant('primary').hover,
-      responsiveButtons.secondary,
-      'rounded-lg font-semibold transition-colors duration-300 text-center min-h-touch'
-    ),
-    outline: cn(
-      'bg-transparent border-2 border-white text-white hover:bg-surface-base/20',
-      responsiveButtons.secondary,
-      'rounded-lg font-semibold transition-colors duration-300 text-center min-h-touch'
-    ),
-  }
-
-  return (
-    <section
-      className={cn(
-        'relative overflow-hidden',
-        responsiveSpacing.sectionLarge,
-        bgClasses[backgroundColor],
-        className
-      )}
-    >
-      {backgroundPattern && (
-        <>
-          <div
-            className="absolute inset-0 opacity-10"
-            style={{
-              backgroundImage: HERO_PATTERN_BACKGROUND,
-              backgroundSize: '20px 20px',
-            }}
-          />
-          <div className="absolute inset-0 bg-linear-to-r from-black/50 to-transparent" />
-        </>
-      )}
-      
-      <div className={cn('container mx-auto relative', responsiveSpacing.container)}>
-        <div className="max-w-3xl">
-          <h1 className={cn(responsiveTypography.hero, 'font-bold mb-4 sm:mb-6 leading-tight')}>
-            {title}
-          </h1>
-          
-          {subtitle && (
-            <h2 className={cn(
-              responsiveTypography.subsection,
-              'font-semibold mb-4 sm:mb-6 md:mb-8',
-              backgroundColor === 'white' 
-                ? getTextColor('white', 'secondary')
-                : backgroundColor === 'green'
-                ? 'text-action-text'
-                : backgroundColor === 'blue'
-                ? 'text-text-muted'
-                : 'text-text-muted'
-            )}>
-              {subtitle}
-            </h2>
-          )}
-          
-          {description && (
-            <p className={cn(
-              responsiveTypography.lead,
-              'mb-6 sm:mb-8',
-              backgroundColor === 'white' 
-                ? getTextColor('white', 'muted')
-                : backgroundColor === 'green'
-                ? 'text-action-text'
-                : backgroundColor === 'blue'
-                ? 'text-text-muted'
-                : 'text-text-muted'
-            )}>
-              {description}
-            </p>
-          )}
-
-          {ctas && ctas.length > 0 && (
-            <div className="flex flex-col sm:flex-row gap-3 sm:gap-4">
-              {ctas.map((cta, index) => (
-                <Link
-                  key={index}
-                  href={cta.href}
-                  className={buttonClasses[cta.variant || 'primary']}
-                >
-                  {cta.text}
-                </Link>
-              ))}
-            </div>
-          )}
-
-          {children}
-        </div>
-      </div>
-    </section>
-  )
-}
diff --git a/src/components/layout/header/NavItem.tsx b/src/components/layout/header/NavItem.tsx
index 41f383694..b2fcab8b0 100644
--- a/src/components/layout/header/NavItem.tsx
+++ b/src/components/layout/header/NavItem.tsx
@@ -17,6 +17,7 @@ import { ChevronDown } from 'lucide-react'
 import { Link, usePathname } from '@/i18n/navigation'
 import { useTranslations } from 'next-intl'
 import { cn } from '@/lib/utils'
+import { designPrimitive } from '@/lib/design-system'
 import type { NavigationItem } from '@/config/navigation'
 import { groupItemsBySection } from './utils'
 import { MegaMenuContent } from './MegaMenuContent'
@@ -134,9 +135,9 @@ export function NavItem({ item, onAnyOpen, onAnyClose }: NavItemProps) {
         href={item.href}
         aria-current={pathname === item.href ? 'page' : undefined}
         className={cn(
-          "relative px-4 py-2 text-sm font-medium whitespace-nowrap",
+          "relative px-4 py-2 text-sm font-medium whitespace-nowrap rounded-lg",
           "transition-colors duration-200",
-          "focus:outline-hidden focus-visible:ring-2 focus-visible:ring-action focus-visible:ring-offset-2 dark:focus-visible:ring-offset-neutral-950 rounded-lg",
+          designPrimitive.focus,
           isActive
             ? "text-text-primary after:absolute after:left-4 after:right-4 after:-bottom-0.5 after:h-0.5 after:rounded-full after:bg-text-primary/50"
             : "text-text-secondary hover:text-text-primary"
@@ -173,7 +174,7 @@ export function NavItem({ item, onAnyOpen, onAnyClose }: NavItemProps) {
             : "text-text-secondary hover:text-text-primary dark:text-text-muted",
           isActive && !isOpen &&
             "text-text-primary after:absolute after:left-4 after:right-4 after:-bottom-0.5 after:h-0.5 after:rounded-full after:bg-text-primary/50",
-          "focus:outline-hidden focus-visible:ring-2 focus-visible:ring-action focus-visible:ring-offset-2 dark:focus-visible:ring-offset-neutral-950"
+          designPrimitive.focus
         )}
         aria-expanded={isOpen}
         aria-haspopup="true"
diff --git a/src/components/ui/Panel.tsx b/src/components/ui/Panel.tsx
new file mode 100644
index 000000000..7c2755ca7
--- /dev/null
+++ b/src/components/ui/Panel.tsx
@@ -0,0 +1,72 @@
+import type { LucideIcon } from 'lucide-react'
+import type { ReactNode } from 'react'
+import { cn } from '@/lib/utils'
+import { designPrimitive } from '@/lib/design-system'
+
+/**
+ * Panel — a titled content surface. The SSOT for "a bordered card with a
+ * header row (title + optional subtitle + optional right-aligned action) and a
+ * body".
+ *
+ * Before this primitive, ~7 components hand-rolled the same shape:
+ * `<section className="bg-surface-base rounded-lg border p-5">` plus a
+ * `<h2 …>` / `<p text-xs text-text-tertiary>` / right-action header block —
+ * each drifting on radius (`rounded-lg` vs `rounded-xl`), border presence, and
+ * stray `shadow-xs`. Panel resolves the surface from `card-shell` (the same
+ * class `<Card>` uses) and the title from `designPrimitive.type.panelTitle`, so
+ * every titled panel is identical and retheming happens in one place.
+ *
+ * For an untitled surface use `<Card>`. For a header row *inside* an existing
+ * card use `<AdminSectionHeader>`. For a full-bleed page hero use `<PageHero>`.
+ */
+interface PanelProps {
+  /** Panel heading. Omit for a body-only surface (prefer <Card> then). */
+  title?: ReactNode
+  /** Secondary line under the title. */
+  subtitle?: ReactNode
+  /** Small icon rendered inline before the title. */
+  icon?: LucideIcon
+  /** Right-aligned header slot — buttons, selects, badges. */
+  action?: ReactNode
+  /** Extra classes on the panel surface (padding override, margins, etc.). */
+  className?: string
+  /** Extra classes on the header row. */
+  headerClassName?: string
+  /** Semantic element. Defaults to <section>. */
+  as?: 'section' | 'div'
+  id?: string
+  children?: ReactNode
+}
+
+export function Panel({
+  title,
+  subtitle,
+  icon: Icon,
+  action,
+  className,
+  headerClassName,
+  as: Tag = 'section',
+  id,
+  children,
+}: PanelProps) {
+  const hasHeader = title != null || action != null
+  return (
+    <Tag id={id} className={cn('card-shell p-4 sm:p-5', className)}>
+      {hasHeader && (
+        <div className={cn('flex items-start justify-between gap-3', children != null && 'mb-4', headerClassName)}>
+          <div className="flex items-start gap-2 min-w-0">
+            {Icon && <Icon className="mt-0.5 h-4 w-4 shrink-0 text-text-tertiary" aria-hidden="true" />}
+            {title != null && (
+              <div className="min-w-0">
+                <h2 className={designPrimitive.type.panelTitle}>{title}</h2>
+                {subtitle != null && <p className="mt-0.5 text-xs text-text-tertiary">{subtitle}</p>}
+              </div>
+            )}
+          </div>
+          {action != null && <div className="shrink-0">{action}</div>}
+        </div>
+      )}
+      {children}
+    </Tag>
+  )
+}
diff --git a/src/lib/admin-ui.ts b/src/lib/admin-ui.ts
index 512a6a7d6..49e5a7787 100644
--- a/src/lib/admin-ui.ts
+++ b/src/lib/admin-ui.ts
@@ -1,5 +1,6 @@
 import { UI_STATUS } from '@/config/ui/status'
 import { designPrimitive } from '@/lib/design-system'
+import { NAV_STATE } from '@/lib/design/nav'
 
 /**
  * Admin UI Design Tokens — SSOT
@@ -181,8 +182,8 @@ export const adminInteractive = {
   rowHoverFaint:   'hover:bg-surface-raised dark:hover:bg-surface-base/2',
   /** Checkbox-selected or active leave-period row */
   rowSelected:     'bg-action-muted/40',
-  /** Sidebar nav item — current route */
-  navActive:       'bg-action/10 text-action ring-1 ring-action/20',
+  /** Sidebar nav item — current route. Value lives in the nav-state SSOT. */
+  navActive:       NAV_STATE.sidebar.active,
   /** Command palette / typeahead keyboard highlight */
   pickerActive:    'bg-action-muted text-action',
   /** Unread notification row tint */
diff --git a/src/lib/design-system.ts b/src/lib/design-system.ts
index dfb3e7531..6a9f0fb46 100644
--- a/src/lib/design-system.ts
+++ b/src/lib/design-system.ts
@@ -331,7 +331,10 @@ export const designPrimitive = {
   // x.ai style: tight tracking, high contrast, scale discipline
   type: {
     pageTitle:   'text-2xl font-bold tracking-tight text-text-primary',
+    // Header row *inside* a card (AdminSectionHeader). Compact.
     sectionTitle:'text-sm font-semibold tracking-tight text-text-primary',
+    // Title of a standalone titled surface (<Panel>). One step up from sectionTitle.
+    panelTitle:  'text-base font-semibold tracking-tight text-text-primary',
     subTitle:    'text-sm font-medium text-text-secondary',
     body:        'text-sm text-text-secondary',
     meta:        'text-xs text-text-tertiary',
diff --git a/src/lib/design/nav.ts b/src/lib/design/nav.ts
new file mode 100644
index 000000000..990b40e67
--- /dev/null
+++ b/src/lib/design/nav.ts
@@ -0,0 +1,54 @@
+/**
+ * Navigation-state SSOT.
+ *
+ * The ONE definition of how a navigation item looks in each of its shapes and
+ * states. Every nav surface — top header, vertical sidebar, mobile bottom tab
+ * bar, bottom-sheet grid — resolves its active/inactive classes from here, so
+ * "the current page" has exactly one visual meaning across the whole product.
+ *
+ * Neutral module (NOT admin-scoped): dashboard, public, and admin chrome all
+ * consume it. `src/lib/admin-ui.ts` re-exports `NAV_STATE.sidebar.active` as
+ * `adminInteractive.navActive` so the value is defined once, here.
+ *
+ * Before this file, the "active nav item" was encoded five different ways
+ * (`ring-action/20` vs `ring-action/30` vs inline `bg-action-muted text-action`
+ * vs `border-action …` vs bare `text-action`). Add a shape here rather than
+ * hand-rolling a sixth.
+ */
+import { cn } from '@/lib/utils'
+
+export type NavShape = 'sidebar' | 'bottomTab' | 'pill'
+
+/**
+ * base     — layout/shape classes shared by both states
+ * active   — current route
+ * inactive — resting + hover
+ */
+export const NAV_STATE: Record<NavShape, { base: string; active: string; inactive: string }> = {
+  /** Vertical sidebar link (admin shell, detail sidebars). */
+  sidebar: {
+    base: 'flex items-center gap-2.5 rounded-lg px-2 py-3 lg:py-1.5 transition-colors',
+    active: 'bg-action/10 text-action ring-1 ring-action/20',
+    inactive:
+      'text-text-tertiary hover:bg-surface-raised hover:text-text-primary dark:hover:bg-surface-base/4',
+  },
+  /** Mobile bottom-tab item (icon stacked over label). 56px thumb target. */
+  bottomTab: {
+    base: 'flex min-h-[56px] flex-1 flex-col items-center justify-center gap-0.5 py-2 text-xs transition-colors',
+    active: 'text-action',
+    inactive: 'text-text-tertiary hover:text-text-secondary',
+  },
+  /** Bordered chip/pill (bottom-sheet grid, secondary nav clusters). */
+  pill: {
+    base: 'flex items-center gap-2 rounded-lg border px-3 py-2.5 text-sm transition-colors',
+    active: 'border-action bg-action-muted text-action',
+    inactive:
+      'border-subtle text-text-secondary hover:border-strong hover:text-text-primary',
+  },
+}
+
+/** Resolve the full class string for a nav item of the given shape + state. */
+export function navLinkClass(shape: NavShape, active: boolean, className?: string): string {
+  const s = NAV_STATE[shape]
+  return cn(s.base, active ? s.active : s.inactive, className)
+}