@teamblind-chorus/ui 1.0.0

package/agents/components/switch/switch.spec.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Switch",
+  "family": "switch",
+  "description": "Pill-shaped track (52 × 32) with a circular thumb (28 × 28) that translates between the two ends. Inactive paints a `scrimSubtle` track (inverse-tone ~8% tint that stays distinct on any host surface) with an `outlineVariant` hairline stroke and a fixed-white thumb (`ref.palette.white.1000`, identical in light and dark); active paints the track in `primary` and the thumb in `onPrimary` so the active state reads chromatically. Whole control is the click target — the thumb is decorative. Instant commit: `onCheckedChange` fires the moment the thumb moves.",
+  "element": "button",
+  "props": {
+    "checked": {
+      "type": "boolean",
+      "optional": true,
+      "description": "Controlled value. When provided, the consumer owns the state; pair with `onCheckedChange`."
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "default": false,
+      "description": "Uncontrolled initial value. Ignored when `checked` is also passed."
+    },
+    "onCheckedChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Called with `(nextChecked, event)` the moment the user flips the switch."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label. Required when the Switch is not paired with a visible label via `aria-labelledby` or a wrapping `<label>`."
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "optional": true,
+      "description": "ID of the element that names this Switch. Mutually exclusive with `aria-label`."
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": ["hovered", "pressed", "focused"],
+      "optional": true,
+      "description": "Docs-only — pins the switch to a single visual state via `data-force-state`. Not for production use."
+    }
+  },
+  "slots": {
+    "track": {
+      "required": true,
+      "description": "Pill-shaped container. 52 × 32, fully rounded. Carries the click handler, the focus ring, and the state-overlay paint. `role='switch'`, `aria-checked` reflects active/inactive.",
+      "intrinsic": true
+    },
+    "thumb": {
+      "required": true,
+      "description": "Circular knob inside the track. 28 × 28, fully rounded. Translates between the leading and trailing ends on toggle. Decorative — never a separate hit target.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "trackWidth": "52px",
+    "trackHeight": "ref.space.400",
+    "trackRadius": "sys.radius.full",
+    "thumbSize": "28px",
+    "thumbInset": "ref.space.25",
+    "thumbTravel": "ref.space.250",
+    "thumbRadius": "sys.radius.full",
+    "outlineWidth": "sys.borderWidth.hairline",
+    "outlineColor": "sys.color.outlineVariant",
+    "transitionDuration": "120ms",
+    "transitionTiming": "ease-out"
+  },
+  "appearances": {
+    "inactive": {
+      "trackBackground": "sys.color.scrimSubtle",
+      "trackOutline": "sys.color.outlineVariant",
+      "thumbBackground": "ref.palette.white.1000",
+      "note": "Resting state. The track fills with `scrimSubtle` — an inverse-tone ~8% tint (black in light, white in dark) — so it stays distinct on every host surface tier without binding to a fixed neutral step, reinforced by the hairline outline. The thumb is fixed white (`ref.palette.white.1000`) so it reads identically in light and dark rather than dimming to a surface tone."
+    },
+    "active": {
+      "trackBackground": "sys.color.primary",
+      "trackOutline": "transparent",
+      "thumbBackground": "sys.color.onPrimary",
+      "note": "Chromatic active state. The outline disappears so the filled track reads as one solid block. Thumb steps to `onPrimary` so the contrast against the filled track stays legible."
+    }
+  },
+  "states": {
+    "default": { "overlay": null },
+    "hovered": {
+      "overlay": { "color": "label", "opacity": "sys.state.hover" }
+    },
+    "pressed": {
+      "overlay": { "color": "label", "opacity": "sys.state.pressed" }
+    },
+    "disabled": {
+      "containerOpacity": "sys.state.disabled",
+      "pointerEvents": "none",
+      "note": "Both the active and inactive appearance fade to `sys.state.disabled`. The thumb stays at the position dictated by `checked`."
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual painted as a three-layer outward ring on the track's outer edge.",
+    "composition": "outward",
+    "compositionReason": "Switch sits inline next to siblings with whitespace around it (form rows, settings list trailing slots); an outward ring reads cleanly without colliding with neighbouring affordances.",
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "implementation": "outset box-shadow on the track's `::after` overlay."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "instantCommit": "`onCheckedChange` fires the moment the user releases the click / Space / Enter. No confirmation step.",
+    "clickTarget": "Whole track is clickable. The thumb is decorative — never a separate hit target.",
+    "keyboardActivation": "Space and Enter both toggle the value when the switch holds focus."
+  },
+  "forbidden": [
+    "switch used for an action that needs confirmation (a destructive commit, an action with an undo) — wrap that in a Button + Dialog instead",
+    "track outline removed in the inactive state — the `scrimSubtle` fill and the hairline outline work together to hold the affordance on any host surface; dropping the outline weakens the edge on tiers where the tint reads faint",
+    "inactive thumb dimmed to a surface tone — it stays fixed white (`ref.palette.white.1000`) so it reads the same in light and dark",
+    "thumb rendered as a separate focusable / clickable element — only the track carries focus and click",
+    "trailing label or icon painted inside the track — the active/inactive contract is the whole control; any label sits outside the Switch (in a List row label, a FormField label, etc.)",
+    "switch laid out next to its label without a 12px / `sys.layout.inline.md` gap — the gap stops the label from reading as if it were part of the control"
+  ]
+}

package/agents/components/tab-bar/tab-bar.family.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "tab-bar",
+  "name": "TabBar",
+  "description": "Bottom-anchored primary navigation \u2014 a horizontal row of icon + label items, one per top-level destination (Home / Company / Explore / Jobs / Notifications), pinned to the bottom of the app surface. Single-spec family. The row carries the system's standard 56 min-height with 8 block padding; items are distributed with optical alignment (start padding = inter-item gap = end padding) so the icons read as evenly placed across the row.",
+  "useCases": [
+    "bottom primary navigation",
+    "top-level destination switcher",
+    "app-shell chrome \u2014 bottom"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline padding internally. Place as a direct child of the page-shell <main> (or any host that pays the gutter once). Do NOT wrap in a padding-inline div, className=\"px-*\", or style={{ padding }} \u2014 the page rail is paid once at the shell, never on the full-bleed child. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "spec": "tab-bar.md",
+  "usage": {
+    "note": "Export is `TabBar`; destinations thread through the `items` array (each `{ value, label, icon, activeIcon }`) — there is NO `<Tab>` child element.",
+    "example": "<TabBar aria-label=\"…\" value={value} onChange={setValue} items={[{ value, label, icon, activeIcon }]} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "tab-bar",
+      "spec": "tab-bar.spec.json",
+      "md": "tab-bar.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/tab-bar/tab-bar.md

@@ -0,0 +1,178 @@
+# Tab bar
+
+The bottom tab bar — a horizontal strip pinned to the bottom of the app exposing top-level destinations (Home / Company / Explore / Jobs / Notifications) in one tap. Each item stacks a 24px glyph above a 10/Regular label; active items show the filled companion glyph at `onSurface`, inactive render the outline at `onSurfaceVariant`. An item may opt into `appearance="primary"` to render a tile-shaped commit affordance — the conventional **Create** entry at the trailing end.
+
+**Reach for this when** you need persistent top-level navigation on a mobile-shaped viewport. **Skip when** the destinations belong inside a single surface — use [Tabs](../tabs/underline.md) — or when the chrome must float — use [FAB](../button/fab.md).
+
+**Layout inset.** full-bleed — pinned chrome at the bottom of the page shell, stretching edge-to-edge. The bar owns its internal padding and tile geometry; do **not** wrap in another padding div. Sits *outside* the `<main>` that pays `sys.layout.page.*` — TabBar is a sibling of NavigationBar in the page shell skeleton, not a `<main>` child. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+**Viewport safe area.** The bar's block-bottom padding pays `env(safe-area-inset-bottom)` so its `surface` background extends through the device home-indicator / gesture zone below the 56-tall content row; on non-mobile viewports `env()` resolves to 0 and the bar collapses to its original 56-tall footprint. The page shell MUST NOT add its own `padding-bottom: env(safe-area-inset-bottom)` when a TabBar is rendered — the bar already pays it, and stacking double-insets by the gesture-zone height.
+
+## Default
+
+The canonical five-destination bar; first item is active.
+
+```preview
+tab-bar/default
+---
+import { TabBar } from '@teamblind-chorus/ui';
+import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, BriefcaseIcon, BriefcaseFillIcon, BellIcon, BellFillIcon } from '@teamblind-chorus/ui/icons';
+
+<TabBar
+  aria-label="Primary"
+  value="home"
+  items={[
+    { value: 'home',          label: 'Home',          icon: <HomeIcon />,         activeIcon: <HomeFillIcon /> },
+    { value: 'company',       label: 'Company',       icon: <BuildingIcon />,      activeIcon: <BuildingFillIcon /> },
+    { value: 'explore',       label: 'Explore',       icon: <SearchIcon />,       activeIcon: <SearchFillIcon /> },
+    { value: 'jobs',          label: 'Jobs',          icon: <BriefcaseIcon />,    activeIcon: <BriefcaseFillIcon /> },
+    { value: 'notifications', label: 'Notifications', icon: <BellIcon />, activeIcon: <BellFillIcon /> },
+  ]}
+/>
+```
+
+## Use cases
+
+### With a primary "Create" item
+
+A bar including a primary-coloured Create affordance at the trailing end. The icon ([`PlusSquareFillIcon`](../../icons/svg/PlusSquareFill.svg)) is painted in `sys.color.brand` via `appearance="primary"` and still occupies one equal-width slot.
+
+```preview
+tab-bar/with-primary
+---
+import { TabBar } from '@teamblind-chorus/ui';
+import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, SearchFillIcon, BriefcaseIcon, BriefcaseFillIcon, BellIcon, BellFillIcon, PlusSquareFillIcon } from '@teamblind-chorus/ui/icons';
+
+<TabBar
+  aria-label="Primary"
+  value="home"
+  items={[
+    { value: 'home',          label: 'Home',          icon: <HomeIcon />,         activeIcon: <HomeFillIcon /> },
+    { value: 'company',       label: 'Company',       icon: <BuildingIcon />,      activeIcon: <BuildingFillIcon /> },
+    { value: 'explore',       label: 'Explore',       icon: <SearchIcon />,       activeIcon: <SearchFillIcon /> },
+    { value: 'jobs',          label: 'Jobs',          icon: <BriefcaseIcon />,    activeIcon: <BriefcaseFillIcon /> },
+    { value: 'notifications', label: 'Notifications', icon: <BellIcon />, activeIcon: <BellFillIcon /> },
+    { value: 'create',        label: 'Create',        icon: <PlusSquareFillIcon />, appearance: 'primary' },
+  ]}
+/>
+```
+
+### Three-destination bar
+
+A bar with a smaller destination set — `space-evenly` distribution scales to any item count.
+
+```preview
+tab-bar/three-destinations
+---
+import { TabBar } from '@teamblind-chorus/ui';
+import { HomeIcon, HomeFillIcon, SearchIcon, SearchFillIcon, ProfileIcon, ProfileFillIcon } from '@teamblind-chorus/ui/icons';
+
+<TabBar
+  aria-label="Primary"
+  value="explore"
+  items={[
+    { value: 'home',    label: 'Home',    icon: <HomeIcon />,    activeIcon: <HomeFillIcon /> },
+    { value: 'explore', label: 'Explore', icon: <SearchIcon />,  activeIcon: <SearchFillIcon /> },
+    { value: 'profile', label: 'Profile', icon: <ProfileIcon />, activeIcon: <ProfileFillIcon /> },
+  ]}
+/>
+```
+
+### Truncation
+
+Labels exceeding their slot truncate with a single-line ellipsis — a safety net for long i18n strings.
+
+```preview
+tab-bar/truncation
+---
+import { TabBar } from '@teamblind-chorus/ui';
+import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, SearchFillIcon, ChatIcon, ChatFillIcon, BellIcon, BellFillIcon } from '@teamblind-chorus/ui/icons';
+
+<TabBar
+  aria-label="Primary"
+  value="messages"
+  items={[
+    { value: 'home',          label: 'Home',                icon: <HomeIcon />,         activeIcon: <HomeFillIcon /> },
+    { value: 'company',       label: 'My organization',     icon: <BuildingIcon />,      activeIcon: <BuildingFillIcon /> },
+    { value: 'explore',       label: 'Explore communities', icon: <SearchIcon />,       activeIcon: <SearchFillIcon /> },
+    { value: 'messages',      label: 'Direct messages',     icon: <ChatIcon />,         activeIcon: <ChatFillIcon /> },
+    { value: 'notifications', label: 'All notifications',   icon: <BellIcon />, activeIcon: <BellFillIcon /> },
+  ]}
+/>
+```
+
+### Focus indicator
+
+Static specimen — pins the keyboard-focus ring to a single destination. See top-level [Focus indicator](#focus-indicator).
+
+```preview
+tab-bar/focused
+---
+import { TabBar } from '@teamblind-chorus/ui';
+import { HomeIcon, HomeFillIcon, BuildingIcon, BuildingFillIcon, SearchIcon, SearchFillIcon, BriefcaseIcon, BriefcaseFillIcon, BellIcon, BellFillIcon } from '@teamblind-chorus/ui/icons';
+
+<TabBar
+  aria-label="Primary"
+  value="home"
+  items={[
+    { value: 'home',          label: 'Home',          icon: <HomeIcon />,         activeIcon: <HomeFillIcon /> },
+    { value: 'company',       label: 'Company',       icon: <BuildingIcon />,      activeIcon: <BuildingFillIcon /> },
+    { value: 'explore',       label: 'Explore',       icon: <SearchIcon />,       activeIcon: <SearchFillIcon />, forcedState: 'focused' },
+    { value: 'jobs',          label: 'Jobs',          icon: <BriefcaseIcon />,    activeIcon: <BriefcaseFillIcon /> },
+    { value: 'notifications', label: 'Notifications', icon: <BellIcon />, activeIcon: <BellFillIcon /> },
+  ]}
+/>
+```
+
+## Slots
+
+- **container** — horizontal `<nav>` landmark.
+- **item** — a destination. `<a href>` when an `href` is supplied, else `<button>`.
+- **icon** — outline glyph at rest; filled `activeIcon` when active (falls back to `icon`).
+- **label** — single line; truncates with ellipsis.
+
+## Anatomy
+
+| Slot      | Token bindings                                                                                       |
+|-----------|------------------------------------------------------------------------------------------------------|
+| container | `surface` fill; top hairline `outlineVariant` divider (inset shadow); `display: flex` + `justify-content: space-evenly` |
+| item      | Flex column, icon over label; `flex: 1 1 0` with `max-width: 80px`; tap target is the full slot. State layer is a `sys.radius.md` rounded rectangle filling the slot |
+| icon      | `sys.color.onSurfaceVariant` → `sys.color.onSurface` (active) |
+| label     | `sys.typo.caption` (10 / Semibold); `onSurfaceVariant` → `onSurface` (active) |
+| primary   | When `appearance="primary"`, only the icon paints in `sys.color.brand`; the label stays in the bar's default `sys.color.onSurfaceVariant` so every label across the row reads as one rung. Pair with a filled-tile glyph (e.g. [`PlusSquareFillIcon`](../../icons/svg/PlusSquareFill.svg)) |
+
+## Sizes
+
+A single fixed rung.
+
+| Property             | Value          | Token                              |
+|----------------------|----------------|-------------------------------------|
+| Min-height           | 56px           | raw — system bar floor             |
+| Item block padding   | 4px            | `sys.layout.container.2xs`         |
+| Item max-width       | 80px           | per-slot cap                       |
+| Icon size            | 24px           | `sys.icon.lg`                      |
+| Icon ↔ label gap     | 2px            | `sys.layout.stack.3xs`             |
+
+## States
+
+The container has no interactive state. Each item carries the lifecycle below — hover/pressed paint a `sys.radius.md` rounded rectangle filling the slot. Focus is separate — see [Focus indicator](#focus-indicator).
+
+| State      | Treatment                                                                                          |
+|------------|----------------------------------------------------------------------------------------------------|
+| `default`  | Outline `icon`, label at `onSurfaceVariant`. Cursor `pointer`.                                     |
+| `hovered`  | State layer fills the slot, painted with `onSurface` at `sys.state.hover` (8%).                    |
+| `pressed`  | State layer fills the slot, painted with `onSurface` at `sys.state.pressed` (12%).                 |
+| `active`   | Filled `activeIcon`, label at `onSurface`. Item carries `aria-current="page"`. No persistent state layer. |
+| `disabled` | Item at `sys.state.disabled` (40%) opacity; pointer events suppressed.                              |
+
+## Focus indicator
+
+**Composition: Inward** — adjacent items are flush under `flex: 1 1 0`, so outward would overlap the neighbour. Ring paints as inset shadows flush at the slot edge; state layer beneath is `onSurface`. Single-focus — at most one item holds the ring. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Behavior
+
+- **Tap an item → navigate.** Selected item swaps to filled `activeIcon`; icon + label flip to `onSurface`. No reflow on selection.
+- **`appearance="primary"` items don't swap.** Primary invokes a screen-covering overlay rather than navigating; never receives `aria-current="page"`.
+- **Single-select.** `value` names the active item; `onChange` fires after the item's `onClick`. Component owns no internal state.
+- **Items are anchors or buttons.** `href` → `<a>`; no `href` → `<button>`. Routing belongs to the host framework.
+- **Fixed row.** Never wraps, never scrolls. Author to a five- or six-item ceiling. Bar pays its own `env(safe-area-inset-bottom)` via block-bottom padding so the surface fill extends through the gesture zone; pinning (`position: fixed` / `sticky`) is still the host's job.

package/agents/components/tab-bar/tab-bar.spec.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "TabBar",
+  "family": "tab-bar",
+  "exportAlias": "BottomNav",
+  "description": "Bottom tab bar — a horizontal strip pinned to the bottom of the app surface that exposes the top-level destinations (Home / Company / Explore / Jobs / Notifications) in one tap. Each item stacks a 24px glyph above a 10/Regular label; the active item is signalled by the filled companion glyph at `onSurface` while inactive items render the outline glyph at `onSurfaceVariant`. Distribution is a capped equal-grow split plus optical alignment: items grow from a zero basis at the same rate up to an 80-wide cap, then the container's `justify-content: space-evenly` paints start padding, inter-item gap, and end padding as the same visible whitespace. Labels that exceed their slot truncate with an ellipsis. Hover / pressed / focus paint a `sys.radius.md` rounded rectangle filling the slot. An item may opt into `appearance='primary'` to render a tile-shaped commit affordance (the conventional 'Create' / 'Compose' entry).",
+  "element": "nav",
+  "props": {
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of destinations: { value, label, icon, activeIcon?, href?, onClick?, appearance? }."
+    },
+    "value": {
+      "type": "string",
+      "optional": true,
+      "description": "Currently active destination's `value`. The matching item renders with the active treatment (filled icon + onSurface)."
+    },
+    "onChange": {
+      "type": "function",
+      "optional": true,
+      "description": "(value) => void. Fires when an item is tapped, after the item's own onClick (suppressed if the click was default-prevented)."
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible name for the nav landmark. Defaults to 'Primary'."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Horizontal nav landmark over a `surface` fill. 56 min-height; no padding (block and inline); items distributed via `justify-content: space-evenly`."
+    },
+    "item": {
+      "required": true,
+      "intrinsic": true,
+      "description": "One destination. Rendered as `<a href>` when an href is supplied, otherwise as a `<button>`. `flex: 1 1 0` with `max-width: 80px`; the whole slot is the click target."
+    },
+    "icon": {
+      "required": true,
+      "description": "24px glyph centred above the label. Outline form when inactive; falls back to `activeIcon` (the filled companion) when active.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "label": {
+      "required": true,
+      "description": "Destination name. caption / Semibold. Single line; truncates with an ellipsis when the slot is narrower than the label.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerMinHeight": "56px",
+    "containerPaddingBlock": "0",
+    "containerPaddingBlockEnd": "env(safe-area-inset-bottom, 0px)",
+    "containerPaddingInline": "0",
+    "viewportSafeArea": "Bar's block-bottom padding pays env(safe-area-inset-bottom) so its surface fill extends through the device home-indicator / gesture zone below the 56-tall content row. Bar is the owner of the viewport-bottom inset; page shell MUST NOT re-pay it via its own padding-bottom.",
+    "containerJustifyContent": "space-evenly",
+    "containerTopDivider": {
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.outlineVariant",
+      "implementation": "inset box-shadow on the container (does not contribute to layout)"
+    },
+    "itemFlex": "1 1 0",
+    "itemMaxWidth": "ref.space.1000",
+    "itemPaddingBlock": "sys.layout.container.2xs",
+    "itemPaddingInline": "0",
+    "itemIconLabelGap": "sys.layout.stack.3xs",
+    "iconSize": "sys.icon.lg",
+    "labelTypo": "sys.typo.caption",
+    "labelOverflow": "ellipsis (overflow: hidden; text-overflow: ellipsis; white-space: nowrap)",
+    "stateLayerInset": "0",
+    "stateLayerRadius": "sys.radius.md"
+  },
+  "appearance": {
+    "itemInactiveColor": "sys.color.onSurfaceVariant",
+    "itemActiveColor": "sys.color.onSurface",
+    "itemPrimaryIconColor": "sys.color.brand",
+    "itemPrimaryLabelColor": "sys.color.onSurfaceVariant",
+    "note": "Primary (`appearance='primary'`) items paint only the icon in `sys.color.brand`; the label stays in the bar's default `onSurfaceVariant` so every label across the row reads as one rung."
+  },
+  "itemProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "label": {
+      "type": "string",
+      "required": true
+    },
+    "icon": {
+      "type": "node",
+      "required": true,
+      "description": "Outline glyph used in the inactive state."
+    },
+    "activeIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Filled companion glyph used when the item is active. Falls back to `icon` when absent."
+    },
+    "href": {
+      "type": "string",
+      "optional": true
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true
+    },
+    "appearance": {
+      "type": "literal",
+      "values": [
+        "primary"
+      ],
+      "optional": true,
+      "description": "Paint the icon in `sys.color.brand` — the 'Create' / 'Compose' commit affordance. Pair with a filled-tile glyph (e.g. PlusSquareFillIcon) so the icon's own shape provides the tile and the brand fill paints it as the commit colour. The label stays in the bar's default `onSurfaceVariant` so the row's labels read as one rung — only the icon carries the brand emphasis. Primary items invoke a screen-covering overlay, NOT a sibling destination — they render in the fill glyph by default, never receive `aria-current='page'`, and never animate outline → fill (no resting/active states inside the bar)."
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": [
+        "hovered",
+        "pressed",
+        "focused"
+      ],
+      "optional": true,
+      "description": "Docs-only — pins the item to a single visual state via `data-force-state` so the contract can be inspected in a static preview. Not for production use."
+    }
+  },
+  "states": {
+    "default": {
+      "description": "Inactive destination. Outline glyph + label, both at `onSurfaceVariant`."
+    },
+    "hovered": {
+      "description": "Pointer over the item. State layer fills the slot, painted with `onSurface` at `sys.state.hover` (8%).",
+      "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.hover)"
+    },
+    "pressed": {
+      "description": "Active press on the item. State layer fills the slot, painted with `onSurface` at `sys.state.pressed` (12%).",
+      "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.pressed)"
+    },
+    "active": {
+      "description": "Currently selected destination. Filled glyph (`activeIcon`) + label, both at `onSurface`. Carries `aria-current='page'`. No persistent state layer — only hover / pressed / focus paint."
+    },
+    "disabled": {
+      "containerOpacity": "sys.state.disabled",
+      "pointerEvents": "none"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the item is in. The state layer beneath is filled with `onSurface` at `sys.state.focus` (12%). Single-focus: at most one item holds the ring at a time, arriving via `:focus-visible` (keyboard `Tab` / programmatic focus).",
+    "composition": "inward",
+    "compositionReason": "Adjacent items are flush under `flex: 1 1 0`; an outward ring would overlap the neighbouring slot. The ring is constrained strictly inside the slot's bounding box and never exceeds it.",
+    "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.focus)",
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the slot edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the slot edge (the counter-ring just inside the outer stroke)",
+      "composition": "inward — inset box-shadow on the ::after at `inset: 0`. Adjacent items are flush under `flex: 1 1 0`, so an outward ring would overlap a neighbour; the ring is forced inside the slot bounds without exceeding them."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "selectionNavigates": "Tapping a destination item routes the app to that destination's page; `value` updates to mark the new active item. The selected item swaps its glyph from the outline form to the filled companion (`activeIcon`) to signal 'you are here' — the icon fill, paired with the `onSurface` colour swap on icon + label, is the bar's primary current-location indicator.",
+    "primaryItemIsAnOverlayAction": "Items with `appearance='primary'` (the conventional Create / Compose affordance) invoke a screen-covering overlay rather than navigating to a sibling destination, so they have no resting/active distinction inside the bar. They render in the fill-type glyph by default (painted in `sys.color.brand`) and never receive `aria-current='page'` or the outline→fill transition. Activation dismisses or replaces the current view via the host framework's overlay/modal route, not via tab-bar selection.",
+    "distribution": "Capped equal-grow plus optical alignment. Every item uses `flex: 1 1 0` with `max-width: 80px`, so items grow at the same rate up to an 80-wide cap. Once every item has hit the cap, the row's leftover inline space is handed to the container's `justify-content: space-evenly`, which paints start padding, inter-item gap, and end padding as the same visible whitespace. `min-width: 0` on the item lets the label's ellipsis truncation actually take effect inside the slot.",
+    "labelTruncation": "Labels that exceed their slot truncate with a single-line ellipsis (`overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). The row never wraps or scrolls.",
+    "fixedRow": "Author destinations to a five- or six-item ceiling so the per-slot width stays wide enough for the destination's short name to read without ellipsis at the system's narrowest mobile breakpoint.",
+    "selectionModel": "Single-select. `value` is the active item's `value`; `onChange` fires after the item's own `onClick`. The component owns no internal state — host page is the source of truth.",
+    "noNativeHomeBar": "The component renders just the bar itself; it does not draw or reserve space for an OS-level home indicator. The host shell handles safe-area inset and pinning."
+  },
+  "forbidden": [
+    "Create item not styled with sys.color.brand fill — the Create entry is the single brand-marked instance per screen",
+    "more than one Create / brand-marked item — brand instance cap on this row is exactly 1",
+    "tab-bar height different from the spec'd geometry — the row geometry is fixed across all routes",
+    "active state for non-Create items painted with brand color — non-Create items use sys.color.onSurface for both rest and active (active darkens via state overlay, not by color swap)"
+  ]
+}