@trading-game/design-intelligence-layer 0.17.3 → 1.0.0

package/docs/components/accordion.md

@@ -0,0 +1,85 @@
+# Accordion
+
+Vertically stacked disclosure sections that expand one panel of content at a time.
+
+## When to use
+
+- Progressive disclosure of secondary content — FAQs, settings groups, order details — where the page should stay short.
+- Content the user scans by heading first and opens selectively.
+
+**When not:** For switching between peer views of equal importance use Tabs. For a single modal confirmation use [Dialog](./dialog.md).
+
+## Anatomy
+
+- `Accordion` — Radix root, pass-through; `data-slot="accordion"`.
+- `AccordionItem` — one section; bottom hairline `border-border-default-default`, removed on the last item; `data-slot="accordion-item"`.
+- `AccordionTrigger` — the heading row inside a Radix `Header`; chevron rotates 180° when open; `data-slot="accordion-trigger"`.
+- `AccordionContent` — animated panel (`animate-accordion-down/up`), inner wrapper carries `pb-4`; `data-slot="accordion-content"`.
+
+## API
+
+### Accordion
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `type` | `"single" \| "multiple"` | — | Radix prop; required. |
+| `collapsible` | `boolean` | `false` | With `type="single"`, allows closing the open item. |
+| `value` / `defaultValue` | `string \| string[]` | — | Controlled / uncontrolled open state. |
+| `onValueChange` | `(value) => void` | — | Radix change callback. |
+
+### AccordionItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Required item identity. |
+
+`AccordionTrigger` and `AccordionContent` take standard Radix props plus `className`.
+
+## Variants & sizes
+
+One variant, no size prop.
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "@trading-game/design-intelligence-layer"
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="fees">
+    <AccordionTrigger>What are the fees?</AccordionTrigger>
+    <AccordionContent>No commission on demo trades.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Tokens
+
+**Colour (semantic):** `border-border-default-default` (item hairline), `icon-prominent-default` (chevron), `ring-focus-strong` (focus ring).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--accordion-trigger-*` | 14 / medium (500) / 20 |
+| `--accordion-content-*` | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- Open state is controlled via Radix `value`/`onValueChange`; `type="single"` closes siblings automatically.
+- The trigger is `rounded-md`, underlines on hover, and takes the standard control focus ring (`focus-visible:ring-[3px] ring-ring-focus-strong`).
+- Disabled triggers get `pointer-events-none opacity-24`.
+- Expand/collapse uses the `accordion-down`/`accordion-up` keyframes; the chevron transition is 200 ms.
+
+## Do / Don't
+
+**Do**
+- Keep trigger copy to a single line at 14/medium/20 — the `.type-accordion-trigger` class wins over `font-*` utilities.
+- Rely on the item's built-in hairline; do not add your own dividers.
+- Use `type="single" collapsible` for FAQ-style lists.
+
+**Don't**
+- Don't bold the trigger — medium (500) is the trigger weight; semibold 600 is the system maximum anywhere.
+- Don't add shadows or background fills to items — accordion rows sit flat on the page surface.
+- Don't nest interactive controls inside `AccordionTrigger`; it is already a button.

package/docs/components/alert-dialog.md

@@ -0,0 +1,98 @@
+# Alert Dialog
+
+Interrupting modal that demands an explicit decision — confirm or cancel — before anything else can happen.
+
+## When to use
+
+- Destructive or irreversible actions: closing a position, deleting a watchlist, discarding an unsaved order.
+- Any flow where dismissing by clicking the overlay would be dangerous — the alert dialog has no close X and no overlay dismiss.
+
+**When not:** For informational or form-bearing modals that may be freely dismissed use [Dialog](./dialog.md). For mobile flows that slide from an edge use [Drawer](./drawer.md).
+
+## Anatomy
+
+- `AlertDialog` — Radix root; `data-slot="alert-dialog"`.
+- `AlertDialogTrigger` / `AlertDialogPortal` / `AlertDialogOverlay` — plumbing; overlay paints `background-overlay-default`; `data-slot` on each.
+- `AlertDialogContent` — the centred card shell, `rounded-2xl` (18px), no shadow; `data-slot="alert-dialog-content"`, `data-size`.
+- `AlertDialogHeader` — grid that centres content (or left-aligns at `sm` for `size="default"`); `data-slot="alert-dialog-header"`.
+- `AlertDialogMedia` — optional 64px icon square (`bg-background-secondary-surface`, `rounded-md`); `data-slot="alert-dialog-media"`.
+- `AlertDialogTitle` / `AlertDialogDescription` — typed via `type-alert-dialog-title` / `-description`.
+- `AlertDialogFooter` — stacked buttons, row at `sm`; two-column grid in `size="sm"`; `data-slot="alert-dialog-footer"`.
+- `AlertDialogAction` / `AlertDialogCancel` — Radix actions rendered through `Button` via `asChild`.
+
+## API
+
+### AlertDialogContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"default" \| "sm"` | `"default"` | `sm` = `max-w-xs`, centred copy, two-up full-width footer buttons; `default` = `sm:max-w-lg`. |
+
+### AlertDialogAction / AlertDialogCancel
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | Button variant | `"primary"` (Action) / `"tertiary"` (Cancel) | Any [Button](./button.md) variant. |
+| `size` | Button size | `"md"` | 40px rail default. |
+
+`AlertDialog` root takes Radix `open` / `defaultOpen` / `onOpenChange`.
+
+## Variants & sizes
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from "@trading-game/design-intelligence-layer"
+
+<AlertDialog>
+  <AlertDialogTrigger>Close position</AlertDialogTrigger>
+  <AlertDialogContent size="sm">
+    <AlertDialogHeader>
+      <AlertDialogTitle>Close this position?</AlertDialogTitle>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Keep it</AlertDialogCancel>
+      <AlertDialogAction>Close position</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-overlay-default` (scrim), `background-primary-surface` (card), `border-border-default-default` (hairline), `text-text-subtle-default` (description), `background-secondary-surface` (media square); action/cancel inherit Button tokens.
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--alert-dialog-title-*` | 18 / semibold (600) / 24 |
+| `--alert-dialog-description-*` | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- Content is `p-6`, `gap-6`, `max-w-[calc(100%-2rem)]`, centred with translate; open/close animates fade + 95% zoom.
+- There is deliberately no close X — the only exits are Action and Cancel.
+- `AlertDialogMedia` shifts the header into a media grid; at `sm` viewport with `size="default"` the title moves to column 2 beside the media square.
+- `size="sm"` forces both footer buttons full-width in a 2-column grid.
+- Action and Cancel are real Buttons (`asChild` onto the Radix primitives), so `loading`/`shimmer` are unavailable on them.
+
+## Do / Don't
+
+**Do**
+- Keep the title at 18/semibold/24 — semibold 600 is the system maximum weight.
+- Use `size="sm"` for one-line confirmations; `default` for anything with media or longer copy.
+- Make the destructive verb the Action label ("Close position", not "OK").
+
+**Don't**
+- Don't add a shadow or a close X — the shell is flat and non-dismissable by design.
+- Don't override the `rounded-2xl` 18px radius; dialogs and cards share it.
+- Don't reach for AlertDialog for routine content — it traps focus and blocks the page.

package/docs/components/aspect-ratio.md

@@ -0,0 +1,55 @@
+# Aspect Ratio
+
+Constrains its child to a fixed width-to-height ratio regardless of container width.
+
+## When to use
+
+- Game artwork, chart thumbnails, video embeds, or any media that must hold 16/9, 4/3, or 1/1 while the layout flexes.
+
+**When not:** For circular imagery of a person use [Avatar](./avatar.md). If the media already has intrinsic dimensions and can reflow freely, plain `max-width:100%` is enough.
+
+## Anatomy
+
+- `AspectRatio` — the only export; a direct pass-through to the Radix primitive with `data-slot="aspect-ratio"`. No styling of its own.
+
+## API
+
+### AspectRatio
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `ratio` | `number` | `1` | Width / height, e.g. `16 / 9`. |
+
+All other props pass through to the underlying `div`.
+
+## Variants & sizes
+
+No variants or sizes — the ratio is the only knob.
+
+```tsx
+import { AspectRatio } from "@trading-game/design-intelligence-layer"
+
+<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-2xl">
+  <img src="/art/crash-game.png" alt="Crash game" className="size-full object-cover" />
+</AspectRatio>
+```
+
+## Tokens
+
+**Colour (semantic):** none — the component paints nothing.
+**Type (private):** none.
+
+## Behaviour
+
+- Purely presentational; the child is absolutely positioned by Radix to fill the ratio box.
+- Rounding, borders, and `object-cover` are the consumer's responsibility via `className` on the wrapper or child.
+
+## Do / Don't
+
+**Do**
+- Pair with `overflow-hidden` and a system radius (`rounded-2xl` for card-like media) when clipping imagery.
+- Give the child `size-full object-cover` so it fills the box.
+
+**Don't**
+- Don't fix a pixel height on the wrapper — that defeats the ratio.
+- Don't add shadows to media frames; surfaces stay flat system-wide.

package/docs/components/avatar.md

@@ -0,0 +1,88 @@
+# Avatar
+
+Circular representation of a user — image with initials fallback, optional status badge, and stacked groups.
+
+## When to use
+
+- Account entry points, leaderboards, comments, or anywhere a person needs a compact visual identity.
+
+**When not:** For arbitrary media at a fixed ratio use [Aspect Ratio](./aspect-ratio.md). For status or counts on their own use [Badge](./badge.md).
+
+## Anatomy
+
+- `Avatar` — circular root with size states; `data-slot="avatar"`, `data-size`.
+- `AvatarImage` — the photo, `aspect-square`, `rounded-full`; `data-slot="avatar-image"`.
+- `AvatarFallback` — initials on `background-secondary-surface`; `data-slot="avatar-fallback"`.
+- `AvatarBadge` — brand dot pinned bottom-right with a 2px surface ring; scales per size, hides its icon at `sm`; `data-slot="avatar-badge"`.
+- `AvatarGroup` — overlapping stack (`-space-x-2`), each avatar ringed in `background-primary-surface`; `data-slot="avatar-group"`.
+- `AvatarGroupCount` — the "+N" tail circle, sized to match the group's avatars; `data-slot="avatar-group-count"`.
+
+## API
+
+### Avatar
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "default" \| "lg" \| "xl"` | `"default"` | 24 / 32 / 40 / `var(--avatar-size-xl)` px. |
+
+All parts also accept Radix/`div` props and `className`.
+
+## Variants & sizes
+
+| Size | Diameter | Badge |
+| --- | --- | --- |
+| `sm` | 24px | 8px dot, icon hidden |
+| `default` | 32px | 10px, 8px icon |
+| `lg` | 40px | 12px, 8px icon |
+| `xl` | `--avatar-size-xl` | 14px, 10px icon |
+
+```tsx
+import {
+  Avatar, AvatarImage, AvatarFallback, AvatarBadge,
+  AvatarGroup, AvatarGroupCount,
+} from "@trading-game/design-intelligence-layer"
+
+<Avatar size="lg">
+  <AvatarImage src="/u/fahad.png" alt="Fahad" />
+  <AvatarFallback>MF</AvatarFallback>
+  <AvatarBadge />
+</Avatar>
+
+<AvatarGroup>
+  <Avatar><AvatarFallback>MF</AvatarFallback></Avatar>
+  <Avatar><AvatarFallback>JS</AvatarFallback></Avatar>
+  <AvatarGroupCount>+3</AvatarGroupCount>
+</AvatarGroup>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-secondary-surface` + `text-text-subtle-default` (fallback and group count), `background-brand-default` + `text-text-on-brand-static` (badge), `background-primary-surface` (badge ring and group rings).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--avatar-fallback-*-sm` | 12 / 16 |
+| `--avatar-fallback-*` (default) | 14 / 20 |
+| `--avatar-fallback-*-xl` | 16 / 24 |
+| `--avatar-fallback-font-weight` | regular (400) |
+| `--avatar-group-count-*` | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- Radix handles the image-load fallback cascade: `AvatarFallback` shows until `AvatarImage` loads.
+- Size cascades via `data-size` group selectors — the badge and group count read the avatar's size, so `AvatarGroupCount` matches whatever size the group's avatars use (`group-has-data-[size=…]`).
+- `xl` sizing is token-driven (`--avatar-size-xl`), not a Tailwind step.
+- The whole component is `select-none`.
+
+## Do / Don't
+
+**Do**
+- Always provide `AvatarFallback` with 1–2 initials.
+- Keep group overlap at the built-in `-space-x-2`; the surface rings depend on it.
+- Put `AvatarGroupCount` last in the group.
+
+**Don't**
+- Don't put more than one `AvatarBadge` on an avatar.
+- Don't square the shape — avatars are circles, full stop.
+- Don't bold the initials; fallback weight is regular 400.

package/docs/components/badge.md

@@ -0,0 +1,75 @@
+# Badge
+
+Non-interactive status pill — emphasis (solid or tint) crossed with meaning (brand, demo, neutral, success, fail, warning).
+
+## When to use
+
+- Labelling state on data: trade result, account mode, market status, counts.
+- Anywhere a compact, read-only classification rides alongside other content.
+
+**When not:** For pressable filter/amount pills use [Chip](./chip.md) — Badge never handles selection. For a full-width promotional panel use [Banner](./banner.md).
+
+## Anatomy
+
+- `Badge` — a single `span` (or `Slot` with `asChild`); `data-slot="badge"`, `data-variant`. Icons inside are fixed at 12px (`[&>svg]:size-3`).
+- `badgeVariants` — exported cva function for composing the classes elsewhere.
+
+## API
+
+### Badge
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"solid" \| "solid-demo" \| "solid-neutral" \| "solid-success" \| "solid-fail" \| "solid-warning" \| "tint" \| "tint-demo" \| "tint-neutral" \| "tint-success" \| "tint-fail" \| "tint-warning"` | `"solid"` | Emphasis + meaning grid; brand is the unsuffixed default. |
+| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | Heights 20 / 24 / 32 / 40. |
+| `asChild` | `boolean` | `false` | Render onto a caller element. Badges are read-only markers — no hover states exist (interactive pills are Chips). |
+
+The `glass` variant was removed (breaking change); there is no replacement — use `tint` on imagery-free surfaces.
+
+## Variants & sizes
+
+```tsx
+import { Badge } from "@trading-game/design-intelligence-layer"
+
+<Badge>Live</Badge>                          {/* solid brand */}
+<Badge variant="solid-success">+2.4%</Badge>
+<Badge variant="solid-fail">-1.1%</Badge>
+<Badge variant="tint">Featured</Badge>
+<Badge variant="tint-warning" size="sm">Delayed</Badge>
+<Badge variant="solid-demo" size="xs">Demo</Badge>
+```
+
+| Size | Height | Padding | Type |
+| --- | --- | --- | --- |
+| `xs` | 20px | `px-2 py-0.5` | 10/16 |
+| `sm` | 24px | `px-2.5 py-0.5` | 12/16 |
+| `md` | 32px | `px-3 py-1` | 14/20 |
+| `lg` | 40px | `px-4 py-1.5` | 16/24 |
+
+## Tokens
+
+**Colour (semantic):**
+- Solid: `background-brand-default` + `text-on-brand-static`; `background-demo-solid`; `background-inverse-surface` + `text-prominent-inverse`; `background-success-solid` / `background-error-solid` / `background-warning-solid`, all with `text-on-status-static`.
+- Tint: `--background-brand-container` (layered static recipe, painted via `[background:…]`) + `text-brand-container-static`; `background-demo-default` + `text-demo-default`; `background-secondary-surface` + `border-neutral-default` + `text-prominent-default`; `background-success/error/warning-default` + matching `border-*` and `text-*` status tokens.
+- Focus: `ring-focus-strong`.
+
+**Type (private):** `--badge-font-size/line-height-{xs,sm,md,lg}` = 10/16, 12/16, 14/20, 16/24; `--badge-font-weight` = semibold (600).
+
+## Behaviour
+
+- Status solids use the bright 600 fills with shared static white ink (`text-on-status-static`) — deliberately below AA on green and amber; a style call, not an oversight.
+- `tint` (brand) paints the layered `--background-brand-container` value via arbitrary `background`, so a `bg-*` utility cannot override it — replace the whole `[background:…]` if you must.
+- No hover states — badges are read-only markers; if it needs to be clickable, it's a [Chip](./chip.md).
+- `rounded-full`, `border-transparent` base (tints add their own status borders), no shadow.
+
+## Do / Don't
+
+**Do**
+- Use `solid-success` / `solid-fail` for P&L pills; ink is static white by design.
+- Pick `tint-*` when the badge sits on busy or dense surfaces and needs less weight.
+- Keep icons at the built-in 12px.
+
+**Don't**
+- Don't use Badge as a button — it has no press states; that job is [Chip](./chip.md)'s.
+- Don't recreate the removed `glass` variant with alpha overrides.
+- Don't restyle text weight; semibold 600 is fixed and is the system maximum.

package/docs/components/banner.md

@@ -0,0 +1,84 @@
+# Banner
+
+Editorial gradient panel — a coloured promotional surface with art, white copy, and a white pill CTA.
+
+## When to use
+
+- Promotions, bonuses, feature announcements, and cross-sells that deserve a full-width painted panel.
+
+**When not:** For inline status messaging use Section Message; for compact state labels use [Badge](./badge.md).
+
+## Anatomy
+
+- Wrapper — a `@container` div so the panel stacks whenever the banner itself (not the viewport) is narrow.
+- `Banner` — the panel; `data-slot="banner"`, `data-clickable` when `onClick` is set; `rounded-2xl`, `p-4` (the card/panel class), horizontal at `@sm`, stacked below.
+- Art slot — 56px frosted square (`--primitive-white-alpha-16`), defaults to a Gift glyph.
+- Copy — title + description, both on static white ink.
+- CTA slot — a string becomes a composed `<Button variant="primary-on-brand" size="sm">` wired to `onAction`; an element takes the slot over.
+- Dismiss — absolute top-right 32px X, rendered only when `onDismiss` is provided.
+
+## API
+
+### Banner
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `color` | `string` (any CSS colour) | `var(--background-brand-default)` | Solid base; the gradient derives automatically. |
+| `title` | `ReactNode` | — | Required in spirit; renders null (with dev warning) if both title and description are missing. |
+| `description` | `ReactNode` | — | Secondary copy at white 80% alpha. |
+| `art` | `ReactNode \| null` | Gift icon | `null` omits the art square entirely. |
+| `action` | `ReactNode` | — | String → Button primary-on-brand sm (needs `onAction`); element → passes through untouched. |
+| `onAction` | `() => void` | — | Click handler for a string `action` — dev-warns if missing. |
+| `onClick` | `() => void` | — | Whole panel becomes the click target (role="button", Enter/Space). Mutually exclusive with `action`. |
+| `onDismiss` | `() => void` | — | Shows the close X; padding switches to `pr-12`. |
+| `dismissLabel` | `string` | `"Dismiss"` | aria-label for the X. |
+
+## Variants & sizes
+
+One variant; the colour is the customisation axis.
+
+```tsx
+import { Banner } from "@trading-game/design-intelligence-layer"
+
+<Banner
+  title="Weekly tournament"
+  description="Top 100 traders share the prize pool."
+  action="Join now"
+  onDismiss={() => setHidden(true)}
+/>
+
+<Banner color="#0AA060" title="Jade promo" onClick={openPromo} art={null} />
+```
+
+## Tokens
+
+**Colour (semantic/alpha):** `text-text-on-brand-static` (title, art ink, dismiss), `--primitive-white-alpha-80` (description), `--primitive-white-alpha-16` (frosted art square — an allowed alpha glaze), Button `primary-on-brand` tokens (CTA), `ring-focus-strong` (focus).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--banner-title-*` | 18 / semibold (600) / 24 |
+| `--banner-description-*` | 12 / medium (500) / 16 |
+| `--banner-action-*` | 12 / semibold (600) / 16 |
+
+
+## Behaviour
+
+- The fill is a two-layer Figma-style stack: the consumer's solid `color` underneath, a fixed black fade on top (`linear-gradient(120deg, transparent → black 50%)`). Any colour darkens correctly with zero tuning; the default lands on the design file's jade `#0AA060 → #04512E` when given `#0AA060`.
+- The panel is art, not a status surface — it renders identically in light and dark.
+- `onClick` and `action` are mutually exclusive: with both set, the button is suppressed and a dev warning logs; the whole banner is the CTA.
+- With `onDismiss`, `pr-12` reserves the top-right corner so copy never runs under the X; the X stops propagation so it never triggers `onClick`.
+- Clickable banners get hover/active opacity fades and a keyboard-activatable role="button" with the standard focus ring.
+- Layout is container-driven: stacked below `@sm` (CTA goes full-width), horizontal at `@sm+`.
+
+## Do / Don't
+
+**Do**
+- Pass game-accent primitives or any hex through `color`; the black fade layer handles contrast.
+- Pass `art={null}` when there is no artwork — do not leave the default Gift on non-gift content.
+- Keep the string CTA with `onAction`; the composed primary-on-brand Button is the standard. The dismiss X is a composed `NavigationButton` (circular per the icon-button law).
+
+**Don't**
+- Don't set both `onClick` and `action` — the action is ignored.
+- Don't theme the panel per colour scheme; it is intentionally static in both themes.
+- Don't put a second button inside a clickable banner.

package/docs/components/bottom-navigation.md

@@ -0,0 +1,90 @@
+# Bottom Navigation
+
+Floating mobile navigation pill — a chrome frost bar holding up to four destinations as icon + label stacks, with a liquid selection bubble. The mobile counterpart of the desktop Sidebar, and the carrier of the system's one sanctioned shadow.
+
+## When to use
+
+- Top-level mobile navigation between 3–4 primary destinations (3 is the norm: Home, Trade, You).
+
+**When not:** On desktop use Sidebar. For hierarchical trails use [Breadcrumb](./breadcrumb.md). For per-page actions use [Button](./button.md).
+
+## Anatomy
+
+- `BottomNavigation` — the bar: `h-15` (60px, deliberately off the control rail — floating chrome), `rounded-full`, `px-1`, chrome frost material with the ambient lift; `data-slot="bottom-navigation"`. Rendered as `<nav>`.
+- `BottomNavigationItem` — flex-1 icon + label stack, `rounded-full`, 20px default icon; `data-slot="bottom-navigation-item"`, `data-active`, `aria-current="page"` when active.
+- The liquid bubble — a single `aria-hidden` span (`data-slot="bottom-navigation-bubble"`) that travels to the active item.
+- `BottomNavigationAI` — the optional AI circle (`data-slot="bottom-navigation-ai"`): identical chrome material and lift, circular (`size-15`), Sparkles icon by default (pass children to replace), `active:scale-[0.93]` press squash, default `aria-label="AI assistant"`. Sits beside the bar in a `flex items-center gap-2.5` row; show/hide = render it or not.
+
+## API
+
+### BottomNavigation
+
+Standard `nav` props — no variants; the chrome frost is the one material. Dev-only warning when given more than 4 children.
+
+### BottomNavigationItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `active` | `boolean` | `false` | Marks the current destination — the liquid bubble travels to it. |
+| `asChild` | `boolean` | `false` | Render as the child (e.g. a router `<Link>`). |
+
+### BottomNavigationAI
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` | `false` | Render as the child (e.g. a router link). |
+
+```tsx
+import { BottomNavigation, BottomNavigationAI, BottomNavigationItem } from "@trading-game/design-intelligence-layer"
+import { Home, LineChart, User } from "lucide-react"
+
+<div className="fixed inset-x-4 bottom-4 flex items-center justify-center gap-2.5">
+  <BottomNavigation className="max-w-90">
+    <BottomNavigationItem active><Home />Home</BottomNavigationItem>
+    <BottomNavigationItem><LineChart />Trade</BottomNavigationItem>
+    <BottomNavigationItem asChild>
+      <a href="/account"><User />You</a>
+    </BottomNavigationItem>
+  </BottomNavigation>
+  <BottomNavigationAI onClick={openAssistant} />
+</div>
+```
+
+## Tokens
+
+**Colour (chrome family — see the Colors page's Chrome group):** `background-chrome-default` (heavy near-solid frost: white 78% light / navy 72% dark, with `blur(20px) saturate(1.4)`), `border-chrome-default`, `shadow-chrome-default` (the one sanctioned shadow — floating chrome over scrolling content), `text-chrome-subtle` (idle ink, resolves through `text-subtle-default`), `text-chrome-selected` (blue-600 light / white dark), `background-chrome-selected` (the bubble's layered top-lit gloss over `background-brand-selected` — paint via `background:`), `chrome-highlight-default` (the bubble's 1px inset specular edge — material rendering, not elevation).
+
+**Motion:** travel timing reads the tokens at runtime — `--motion-travel-lead` (200ms leading edge), `--motion-travel-trail` (380ms trailing edge) on `--primitive-ease-spring`; the arriving icon pops on `--motion-pop` × `--primitive-ease-overshoot` (a CSS rule in styles.css — stacked arbitrary variants can't reach descendant svgs).
+
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--bottom-navigation-label-*` | 12 / medium (500) / 16 |
+
+## Behaviour
+
+- Controlled: the consumer sets `active` on exactly one item; the component holds no state of its own.
+- The component is only the bar — the consumer docks it, typically `fixed inset-x-4 bottom-4`.
+- More than 4 children logs a development warning ("a phone fits at most 4").
+- Items are buttons by default; `asChild` swaps in router links while keeping the styling and `aria-current`.
+- Labels never change size or weight on selection — the bubble and ink swap carry the state.
+
+### The liquid bubble
+
+- Selection travels as a single bubble: the leading edge darts ahead on `--motion-travel-lead`, the trailing edge is pulled after on `--motion-travel-trail` — the water-drop absorb. Direction-aware.
+- Geometry: the bubble keeps an equal 4px gap on every side (the bar's `px-1` is the horizontal gap, `inset-y-1` the vertical), so its full-pill radius nests concentrically inside the bar's corners.
+- First paint and resizes re-place the bubble without animating; travel animates only on selection change.
+
+## Do / Don't
+
+**Do**
+- Cap at 4 destinations; 3 is the norm and gives the bubble breathing room.
+- Give every item both an icon and a 12px label.
+- Dock with `fixed inset-x-4 bottom-4` so the bar floats above the bottom edge.
+- Render `BottomNavigationAI` beside the bar when the product wants the assistant entry point.
+
+**Don't**
+- Don't mark more than one item `active`.
+- Don't add any other shadow — `shadow-chrome-default` is the one exception, already built in.
+- Don't use it on desktop layouts; that is Sidebar territory.

package/docs/components/breadcrumb.md

@@ -0,0 +1,85 @@
+# Breadcrumb
+
+Hierarchical trail showing where the current page sits, with links back up the tree.
+
+## When to use
+
+- Pages three or more levels deep (Markets → Crypto → BTC/USD) where users need one-click ascent.
+
+**When not:** For primary mobile navigation use [Bottom Navigation](./bottom-navigation.md). For step-by-step flows use Stepper.
+
+## Anatomy
+
+- `Breadcrumb` — `<nav aria-label="breadcrumb">`; `data-slot="breadcrumb"`.
+- `BreadcrumbList` — the `<ol>`, wraps and gaps items, subtle ink; `data-slot="breadcrumb-list"`.
+- `BreadcrumbItem` — one `<li>`; `data-slot="breadcrumb-item"`.
+- `BreadcrumbLink` — ancestor link, hover shifts to prominent ink; `data-slot="breadcrumb-link"`.
+- `BreadcrumbPage` — the current page, brand ink, `aria-current="page"`, `aria-disabled`; `data-slot="breadcrumb-page"`.
+- `BreadcrumbSeparator` — presentation `<li>`, defaults to a 14px ChevronRight; `data-slot="breadcrumb-separator"`.
+- `BreadcrumbEllipsis` — collapsed-levels marker with sr-only "More"; `data-slot="breadcrumb-ellipsis"`.
+
+## API
+
+### BreadcrumbLink
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` | `false` | Render a router link instead of `<a>`. |
+
+### BreadcrumbSeparator
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | `<ChevronRight />` | Custom separator glyph. |
+
+Other parts take standard element props plus `className`.
+
+## Variants & sizes
+
+One variant, one size.
+
+```tsx
+import {
+  Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink,
+  BreadcrumbSeparator, BreadcrumbPage, BreadcrumbEllipsis,
+} from "@trading-game/design-intelligence-layer"
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/markets">Markets</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbEllipsis /></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbPage>BTC/USD</BreadcrumbPage></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+## Tokens
+
+**Colour (semantic):** `text-text-subtle-default` (trail), `text-text-prominent-default` (link hover), `text-text-brand-default` (current page).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--breadcrumb-*` | 14 / regular (400) / 20 |
+| `--breadcrumb-page-font-weight` | medium (500) |
+
+## Behaviour
+
+- Entirely static markup — no state; the consumer builds the trail.
+- `BreadcrumbPage` is a `span` with `role="link" aria-disabled="true" aria-current="page"` — it is not clickable.
+- Separators are `role="presentation" aria-hidden` and never announced.
+- The list wraps (`flex-wrap`) with gap 6px, 10px at `sm`.
+
+## Do / Don't
+
+**Do**
+- End every trail with `BreadcrumbPage`, never a link.
+- Collapse deep trails with `BreadcrumbEllipsis` rather than shrinking type below 14.
+- Put a `BreadcrumbSeparator` between items, outside the `BreadcrumbItem`.
+
+**Don't**
+- Don't style the current page heavier than medium 500.
+- Don't make the current page clickable.
+- Don't use breadcrumbs as tabs or primary navigation.