@trading-game/design-intelligence-layer 1.0.1 → 1.0.2

package/docs/components/bottom-navigation.md

@@ -52,7 +52,7 @@ import { Home, LineChart, User } from "lucide-react"
 
 ## 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).
+**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 / blue-100 dark), `background-chrome-selected` (the bubble's layered top-lit gloss — over `background-brand-selected` in light, over a richer blue-400 45% mix in dark so the blue glows on the dark bar — 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).
 

package/docs/components/breadcrumb.md

@@ -57,7 +57,7 @@ import {
 
 ## Tokens
 
-**Colour (semantic):** `text-text-subtle-default` (trail), `text-text-prominent-default` (link hover), `text-text-brand-default` (current page).
+**Colour (semantic):** `text-text-subtle-default` (trail), `text-text-prominent-default` (link hover), `text-text-brand-selected` (current page).
 **Type (private):**
 
 | Token | Value |

package/docs/components/calendar.md

@@ -13,7 +13,7 @@ Date and date-range picker built on react-day-picker, restyled with circular day
 - `Calendar` — configured `DayPicker`; root gets `data-slot="calendar"`, panel is `w-fit`, `p-3`, cell size `--cell-size` = 32px. Background goes transparent inside `card-content` and `popover-content`.
 - Nav — an absolute strip over the caption using `pointer-events-none`, with the arrow Buttons re-enabling their own hits so clicks pass through to the caption dropdowns beneath.
 - `CalendarDropdown` (internal `components.Dropdown`) — themed Select replacing the native month/year `<select>`; popper-positioned panel, `max-h-64`.
-- `CalendarDayButton` — exported day cell: a tertiary icon Button, circular, with today/selected/range modifiers via data attributes.
+- `CalendarDayButton` — exported day cell: a tertiary icon Button, circular, with today/selected/range modifiers via data attributes (`data-today`, `data-selected-single`, `data-range-start`, `data-range-middle`, `data-range-end`).
 
 ## API
 
@@ -43,7 +43,7 @@ import { Calendar } from "@trading-game/design-intelligence-layer"
 
 ## Tokens
 
-**Colour (semantic):** `background-primary-surface` (panel), `text-text-prominent-default` (caption, days), `text-text-subtle-default` (weekdays, week numbers), `text-text-disabled-default` (outside/disabled days), `background-hover-default` (day hover glaze), `--background-brand-container` + `text-text-brand-container-static` (selected day and range band — the static icy recipe, painted via `[background:var(…)]`), `text-text-brand-default` + `background-brand-default` (today's number and dot), `icon-subtle-default` (dropdown chevron), `ring-focus-strong` (focus).
+**Colour (semantic):** `background-primary-surface` (panel), `text-text-prominent-default` (caption, days), `text-text-subtle-default` (weekdays, week numbers), `text-text-disabled-default` (outside/disabled days), `background-hover-default` (day hover glaze), `background-brand-default` + `text-text-on-brand-static` (a picked date — selected single day and both range endpoints), `background-brand-selected` + `text-text-brand-selected` (the range band between the endpoints), `text-text-brand-selected` + `border-border-brand-selected` (today's ring and numeral), `icon-subtle-default` (dropdown chevron), `ring-focus-strong` (focus).
 **Type (private):**
 
 | Token | Value |
@@ -54,9 +54,9 @@ import { Calendar } from "@trading-game/design-intelligence-layer"
 
 ## Behaviour
 
-- Day cells are circular (tertiary icon Buttons). Selection paints the static icy `--background-brand-container` via arbitrary `background` — a `bg-*` utility cannot override it — with `text-brand-container-static` ink and semibold numerals.
-- Ranges: circular start/end (rounded-l/r-full, semibold), square middles (`rounded-none`), all on the same icy band; first/last cells in a row re-round via row selectors.
-- Today (unselected) keeps the regular cell but takes brand ink, semibold, and a 4px brand dot centred below the numeral.
+- Day cells are circular (tertiary icon Buttons). A **picked date** — the selected single day, or either range endpoint — is a solid `background-brand-default` disc with `text-on-brand-static` ink and semibold numerals. Single and endpoint share one recipe deliberately: they mean the same thing, so they must not diverge.
+- Ranges: solid discs at both endpoints, square middles (`rounded-none`) on the quieter `background-brand-selected` band with `text-brand-selected` ink; first/last cells in a row re-round via row selectors. The band rides `brand-selected`, not the static `brand-container`, because that token is one value in both themes and reads as a pale strip on the dark canvas.
+- Today (unselected) keeps the regular cell but takes brand ink, semibold, and a 1.5px `border-brand-selected` ring. The ring — not a heavier weight — is what makes today legible, since components cap at semibold 600 and 600-vs-400 doesn't read at this size.
 - `CalendarDropdown` replaces the native selects with the themed Select: `position="popper"` content so the panel scrolls in place, and fixed trigger widths — `w-20` for months, `w-24` for years — so the `w-fit` panel never resizes between "Jan" and "Sep" or 999 and 2026.
 - The nav strip overlays the caption with `pointer-events-none`; only the arrow buttons (`pointer-events-auto`) catch clicks, so the dropdowns underneath stay clickable.
 - Focused days are programmatically focused (`modifiers.focused` → `ref.focus()`), and RTL flips the nav chevrons.
@@ -69,6 +69,6 @@ import { Calendar } from "@trading-game/design-intelligence-layer"
 - Host in a Popover or Card — the calendar background auto-clears there.
 
 **Don't**
-- Don't restyle selected days with `bg-*` utilities — the icy container is painted via `background` and will win.
-- Don't theme the selection per colour scheme by hand; `--background-brand-container` is the static recipe on purpose.
+- Don't give the selected single day and the range endpoints different fills — one picked-date recipe covers both.
+- Don't put the range band back on `--background-brand-container`; that token is static by design and can't carry a dark theme.
 - Don't square the day cells; circles (and square range middles) are the system shape.

package/docs/components/card.md

@@ -5,7 +5,7 @@ The shared surface shell — card surface, hairline border, 18px radius, flat
 ## When to use
 
 - Grouping related content on a page: positions, game tiles, stats, settings sections.
-- `variant="frosted-on-brand"` for cards sitting over hero or game artwork.
+- `variant="frosted"` for a tinted card on a plain page surface. `variant="frosted-on-brand"` for cards sitting over hero or game artwork.
 
 **When not:** For modal content use [Dialog](./dialog.md). For a painted promotional panel use [Banner](./banner.md).
 
@@ -25,7 +25,7 @@ The shared surface shell — card surface, hairline border, 18px radius, flat
 
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `variant` | `"default" \| "frosted-on-brand"` | `"default"` | Glass = white-alpha-80 + blur-xl + white-alpha-64 hairline, static black ink, identical in both themes. |
+| `variant` | `"default" \| "frosted" \| "frosted-on-brand"` | `"default"` | frosted = solid brand-selected tint + brand-selected ink, for plain page surfaces. frosted-on-brand = white-alpha-80 + blur-xl + white-alpha-64 hairline, static black ink, identical in both themes — for art/brand surfaces only. |
 | `interactive` | `boolean` | `false` | Desktop-only hover lift: `sm:hover:-translate-y-0.75`, disabled under `motion-reduce`. |
 
 All slots take `div` props plus `className`.

package/docs/components/dialog.md

@@ -13,7 +13,7 @@ General-purpose modal on the shared card shell — dismissable, with an optional
 - `Dialog` / `DialogTrigger` / `DialogPortal` / `DialogClose` — Radix plumbing with `data-slot` names (`dialog`, `dialog-trigger`, `dialog-portal`, `dialog-close`).
 - `DialogOverlay` — scrim in `background-overlay-default`; `data-slot="dialog-overlay"`.
 - `DialogContent` — centred card: `rounded-2xl` (18px), hairline border, `p-6`, `gap-6`, `sm:max-w-lg`, no shadow; `data-slot="dialog-content"`. Includes the close X unless disabled.
-- Close X — 32px circle, top-right, subtle icon at 70% opacity, hover = full opacity + `background-hover-default` glaze.
+- Close X — a [NavigationButton](./navigation-button.md) (`size="sm"`), top-right, wired to `DialogPrimitive.Close` via `asChild`.
 - `DialogHeader` — column, centred text, left at `sm`; `data-slot="dialog-header"`.
 - `DialogTitle` / `DialogDescription` — `type-dialog-title` / `-description`.
 - `DialogFooter` — reverse-stacked buttons, row right-aligned at `sm`; can append its own Close button; `data-slot="dialog-footer"`.
@@ -66,7 +66,7 @@ import {
 
 ## Tokens
 
-**Colour (semantic):** `background-overlay-default` (scrim), `background-primary-surface` (card), `border-border-default-default` (hairline), `text-prominent-default` (title), `text-subtle-default` (description), `icon-subtle-default` + `background-hover-default` (close X), `ring-focus-strong` (focus).
+**Colour (semantic):** `background-overlay-default` (scrim), `background-primary-surface` (card), `border-border-default-default` (hairline), `text-prominent-default` (title), `text-subtle-default` (description), `ring-focus-strong` (focus). The close X inherits [NavigationButton](./navigation-button.md)'s own tokens.
 **Type (private):**
 
 | Token | Value |
@@ -77,7 +77,7 @@ import {
 ## Behaviour
 
 - Radix handles focus trap, Escape, and overlay dismissal; open/close animates fade + 95% zoom over `duration-base`.
-- The close X is circular (`rounded-full`, 32px) with the hover glaze — the icon-button rule applied to a built-in control; it stops rendering with `showCloseButton={false}`.
+- The close X is a composed `NavigationButton` rather than a hand-rolled circle, so it tracks that component's resting tint, hover step, and focus ring automatically; it stops rendering with `showCloseButton={false}`.
 - `DialogFooter showCloseButton` gives you a standard Cancel/Close without wiring `DialogClose` manually.
 - The shell is flat: no shadow, `rounded-2xl` 18px, matching [Card](./card.md).
 - `CommandDialog` composes this component with `p-0` content.

package/docs/components/empty.md

@@ -62,7 +62,7 @@ import { InboxIcon } from "lucide-react"
 - `border-border-default-default` (dashed container border)
 - `bg-background-secondary-surface` + `text-icon-prominent-default` (icon tile)
 - `text-text-prominent-default` (title)
-- `text-text-subtle-default` (description), links hover to `text-text-brand-default`
+- `text-text-subtle-default` (description), links hover to `text-text-brand-selected`
 
 **Type (private):**
 - `--empty-title-*`: 18 / semibold / 24

package/docs/components/input-otp.md

@@ -12,7 +12,7 @@ Segmented one-time-code entry — one visual slot per character over a single hi
 
 - `InputOTP` — wrapper around the `input-otp` library's `OTPInput`; owns `maxLength`, value, and the hidden real input. `data-slot="input-otp"`.
 - `InputOTPGroup` — visually joins consecutive slots (first slot `rounded-l-sm`, last `rounded-r-sm`). `data-slot="input-otp-group"`.
-- `InputOTPSlot` — one character cell, 40px (`size-10`, the md rail); renders the char and a fake blinking caret. `data-slot="input-otp-slot"`, `data-active`.
+- `InputOTPSlot` — one character cell, 48px (`size-12`, the lg rail); renders the char and a fake blinking caret. `data-slot="input-otp-slot"`, `data-active`.
 - `InputOTPSeparator` — `role="separator"` dash (`MinusIcon`) between groups. `data-slot="input-otp-separator"`.
 
 ## API
@@ -32,7 +32,7 @@ Segmented one-time-code entry — one visual slot per character over a single hi
 
 ## Variants & sizes
 
-No variants; one 40px slot size.
+No variants; one 48px slot size.
 
 ```tsx
 import {
@@ -65,7 +65,7 @@ import {
 - caret: `bg-text-prominent-default` (`animate-caret-blink`, 1s)
 - invalid (`aria-invalid`): `border-border-error-default` + `ring-ring-error-soft`, active or not
 
-**Type (private):** `--input-otp-*`: 14 / regular / 20 (`type-input-otp`).
+**Type (private):** `--input-otp-*`: 20 / semibold / 28 (`type-input-otp`).
 
 ## Behaviour
 

package/docs/components/item.md

@@ -76,7 +76,7 @@ import { BellIcon } from "lucide-react"
 ## Tokens
 
 **Colour (semantic):**
-- title `text-text-prominent-default`; description `text-text-subtle-default` (links underline, hover `text-text-brand-default`)
+- title `text-text-prominent-default`; description `text-text-subtle-default` (links underline, hover `text-text-brand-selected`)
 - outline: `border-border-default-default`, hover `bg-background-hover-default`; muted: `bg-background-secondary-surface`
 - group divider: `bg-border-default-default`
 - focus: `border-ring-focus-default` + 3px `ring-ring-focus-strong` (control ring)

package/docs/components/link.md

@@ -40,7 +40,7 @@ import { ArrowRightIcon } from "lucide-react"
 ## Tokens
 
 **Colour (semantic):**
-- brand: `text-text-brand-default`, hover `text-text-brand-hover` (ink darkens one step)
+- brand: `text-text-brand-selected`, hover `text-text-brand-hover` (ink darkens one step)
 - on-brand: `text-text-on-brand-static`, hover `--primitive-white-alpha-80` (alpha primitive, sanctioned for on-brand surfaces)
 - focus: 3px `ring-ring-focus-strong`
 

package/docs/components/navigation-button.md

@@ -20,7 +20,7 @@ Circular icon-only control for moving through UI — back arrows, carousel stepp
 
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `variant` | `"default" \| "frosted-on-brand"` | `"default"` | default = transparent circle, hover fill; glass = frosted circle for art/hero/brand surfaces. |
+| `variant` | `"default" \| "frosted-on-brand"` | `"default"` | default = tinted circle at rest, deeper tint on hover; glass = frosted circle for art/hero/brand surfaces. |
 | `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"lg"` | xs 24px (16px icon), sm 32px (20px icon), md 40px (20px icon), lg 48px (24px icon). |
 | `asChild` | `boolean` | `false` | Render as `<a>` etc. via Radix Slot. |
 
@@ -42,7 +42,7 @@ import { ChevronLeftIcon } from "lucide-react"
 ## Tokens
 
 **Colour (semantic):**
-- default: transparent, `text-icon-prominent-default`, hover `bg-background-hover-default`
+- default: `bg-background-hover-default` at rest, `text-icon-prominent-default`, hover steps to `bg-background-pressed-default` — the circle is always visibly tinted, not just on hover.
 - focus: 3px `ring-ring-focus-strong`
 - glass (alpha primitives — the sanctioned glass use): fill + border `--primitive-white-alpha-24` with `backdrop-blur-md`, ink `text-text-on-brand-static`; hover thickens to `--primitive-white-alpha-32`, press thins to `--primitive-white-alpha-16`
 

package/docs/components/progress.md

@@ -1,6 +1,18 @@
 # Progress
 
-Determinate progress bar — a brand wash track with a solid brand indicator.
+Determinate progress in the design file's four shapes: the linear bar (with an optional setup-meter label row), pill-segment dots, and the circular ring — whose `xl` size is exactly the avatar verification ring's geometry.
+
+## Variants
+
+| Variant | Notes |
+| --- | --- |
+| `bar` (default) | Sizes sm 4 / md 8 / lg 12; add `label` + `valueLabel` for the setup-meter row |
+| `dots` | `segments` pill segments (24×4 at md; widths 16/24/32 by size), filled in value order |
+| `ring` | Circular arc, rounded caps; sizes sm 24 / md 32 / lg 48 / xl 112 (`xl` = ProfilePhoto's verification-ring geometry); `children` render centred (countdown number, `--progress-value-*` type) |
+
+Any variant can also **self-run**: pass `timer` (ms) + `direction` and the value animates smoothly — `down` is a countdown drain, `up` a countup fill.
+
+**Tokens:** track `background-secondary-surface` (ring track: `border-default-default` hairline), fill `background-brand-default`, meter labels `--progress-label-*` (12/semibold), ring value `--progress-value-*` (14/semibold, tabular). Fill motion rides `duration-slow ease-linear` per the progress motion role.
 
 ## When to use
 
@@ -10,51 +22,56 @@ Determinate progress bar — a brand wash track with a solid brand indicator.
 
 ## Anatomy
 
-- `Progress` — Radix `Progress.Root` track: `h-2` (8px), `rounded-2xs`, overflow hidden. `data-slot="progress"`.
-- Indicator — full-size bar translated left by the remaining percentage. `data-slot="progress-indicator"`.
+- `Progress` — the track (`bar`: Radix `Progress.Root`, rounded-full, overflow hidden; `dots`: segment row; `ring`: SVG arc pair). `data-slot="progress"`, `data-variant`.
+- Fill — solid brand: the translated indicator (`data-slot="progress-indicator"`), the filled dots (`data-slot="progress-dot"`), or the dashoffset arc (`data-slot="progress-ring-fill"`).
 
 ## API
 
-### Progress
-
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `value` | `number \| null` | — | 0–100. `null`/`undefined` renders as 0 (indicator fully translated out). |
-
-Other Radix `Progress.Root` props (`max`, `getValueLabel`, …) pass through; note the fill math reads `value` directly against 100.
-
-## Variants & sizes
-
-No variants; one 8px bar. Width is fluid (`w-full`).
+| `value` | `number \| null` | — | 0–100; clamped. Ignored while `timer` runs. |
+| `variant` | `"bar" \| "dots" \| "ring"` | `"bar"` | |
+| `size` | `"sm" \| "md" \| "lg"` (+ `"xl"` ring) | `"md"` | |
+| `label` / `valueLabel` | `ReactNode` | — | bar only — the setup-meter row. |
+| `segments` | `number` | `5` | dots only. |
+| `timer` | `number` (ms) | — | Self-running mode: the value animates smoothly over `timer` ms. Remount (change `key`) to restart. |
+| `direction` | `"down" \| "up"` | `"down"` | Timer direction — `down` drains 100 → 0 (countdown), `up` fills 0 → 100 (countup). |
+| `onTimerEnd` | `() => void` | — | Fires once when the timer finishes. |
+| `children` | `ReactNode \| (pct) => ReactNode` | — | ring only — centred content. Pass a function to render from the live value (the countdown number). |
 
 ```tsx
 import { Progress } from "@trading-game/design-intelligence-layer"
 
 <Progress value={66} />
-<Progress value={verifiedSteps * 25} className="max-w-xs" />
+<Progress value={40} label="Account setup" valueLabel="2 of 5" />
+<Progress variant="dots" segments={5} value={40} />
+<Progress variant="ring" size="lg" value={62} />
+
+// 5s countdown ring with a live seconds number — remount with `key` to restart
+<Progress variant="ring" size="lg" timer={5000} direction="down" onTimerEnd={settle}>
+  {(pct) => Math.ceil((pct / 100) * 5)}
+</Progress>
 ```
 
 ## Tokens
 
-**Colour (semantic):**
-- track: `bg-background-secondary-surface` — the shared track spec (h-2, rounded-full), same as Slider
-- indicator: `bg-background-brand-default`, solid
+**Colour (semantic):** track `background-secondary-surface` (ring track: `border-default-default` hairline), fill `background-brand-default`, ring value ink `text-prominent-default`, meter label inks `text-prominent-default` / `text-subtle-default`.
 
-**Type (private):** none.
+**Type (private):** `--progress-label-*` (12 / semibold / 16), `--progress-value-*` (14 / semibold / 20, tabular).
 
 ## Behaviour
 
-- The indicator is always full-width and is moved with `translateX(-(100 - value)%)`, so value changes animate smoothly via `transition-all`.
-- `value || 0` means null/undefined/0 all show an empty bar — there is no indeterminate animation in this component.
-- Radix provides the `progressbar` role and aria value attributes.
+- One geometry, three drivers: pass `value` for real progress, or `timer` + `direction` for time (countdown drain / countup fill) — how it's driven is the consumer's choice.
+- `value` changes ease on `duration-slow ease-linear` (the progress motion role); in timer mode the animation is frame-driven and the CSS transition is off.
+- At 0 the ring paints no arc at all — no stray round-cap dot at 12 o'clock.
+- The `progressbar` role and aria value attributes are on every variant.
 
 ## Do / Don't
 
 **Do**
-- Keep the track as the 20% brand wash — track and fill are the same hue by design, separated by alpha.
-- Constrain width with layout (`max-w-*`) rather than restyling the bar.
+- Constrain width with layout (`max-w-*`) rather than restyling the track.
+- Use the `children` render function for countdown numbers so the figure stays in sync with the arc.
 
 **Don't**
-- Don't repaint the pair with grey tracks or gradient fills; brand wash + solid brand is the recipe.
-- Don't fake indeterminate state by animating `value`; use Spinner for unknown durations.
-- Don't change the 8px height or `rounded-2xs` radius per screen; it is a fixed primitive.
+- Don't repaint tracks or fills; secondary-surface track + solid brand fill is the recipe.
+- Don't use a timer for unknown-length waits — that's [Spinner](./spinner.md) or [Skeleton](./skeleton.md).

package/docs/components/radio-group.md

@@ -55,7 +55,7 @@ import {
 
 **Colour (semantic):**
 - rest: `border-border-default-default` hairline on `bg-background-primary-surface`
-- checked: `border-background-brand-default` ring + `fill-background-brand-default` dot (surface stays primary — no filled disc)
+- checked: `border-border-brand-selected` ring + `fill-background-brand-default` dot (surface stays primary — no filled disc)
 - focus: `border-ring-focus-default` + 3px `ring-ring-focus-strong` (control ring)
 - error (`aria-invalid`): `border-border-error-default` + `ring-ring-error-soft`
 

package/docs/components/select.md

@@ -7,7 +7,7 @@ Single-choice dropdown (Radix Select) with a form-input trigger and a menu-style
 - Choosing one value from 5–15 options inside a form — account currency, leverage, market.
 - When the current value must read like an input, sitting on the 32/40/48 field rail.
 
-**When not:** For 2–4 always-visible options use [Toggle Group](./toggle-group.md) or Tabs. For command-style search over long lists use Command. For native mobile pickers use Native Select.
+**When not:** For 2–4 always-visible options use [Toggle Group](./toggle.md) or Tabs. For command-style search over long lists use Command. For native mobile pickers use Native Select.
 
 ## Anatomy
 

package/docs/components/sheet.md

@@ -63,7 +63,7 @@ import {
 
 ## Tokens
 
-**Colour (semantic):** `bg-background-overlay-default` (scrim), `bg-background-primary-surface` (panel), `border-border-default-default` (hairline on the attached edge: `border-l` for right, `border-r` for left, `border-b` for top, `border-t` for bottom), `text-text-prominent-default` (title), `text-text-subtle-default` (description), `text-icon-subtle-default` + `bg-background-hover-default` hover glaze (close button), `ring-ring-focus-strong` at 3px (close focus).
+**Colour (semantic):** `bg-background-overlay-default` (scrim), `bg-background-primary-surface` (panel), `border-border-default-default` (hairline on the attached edge: `border-l` for right, `border-r` for left, `border-b` for top, `border-t` for bottom), `text-text-prominent-default` (title), `text-text-subtle-default` (description). The close button inherits [NavigationButton](./navigation-button.md)'s own tokens, including its focus ring.
 **Type (private):**
 
 | Token | Value |
@@ -75,7 +75,7 @@ import {
 
 - Enter/exit are directional slides (`slide-in-from-*` / `slide-out-to-*`) on the overlay motion role: `--motion-overlay-open` (320ms, `ease-enter`) in and `--motion-overlay-close` (250ms, `ease-exit`) out; the overlay fades.
 - Left/right sheets are 75% viewport width capped at `sm:max-w-sm`; top/bottom size to content.
-- The built-in close is a `size-8` circle (`rounded-full`) at 70% opacity that gains the `background-hover-default` glaze on hover — the icon-buttons-are-circles rule.
+- The built-in close is a composed `NavigationButton` (`size="sm"`, 32px) rather than a hand-rolled circle, so it tracks that component's resting tint, hover step, and focus ring automatically.
 - The panel has a hairline only on its attached edge and no rounded corners on any side — it meets the viewport edges flush.
 
 ## Do / Don't

package/docs/components/slide-to-confirm.md

@@ -0,0 +1,68 @@
+# Slide to Confirm
+
+Swipe-to-commit control for irreversible money actions — withdrawals, transfers. A pill track with a draggable brand handle: drag past ~90% to confirm; release earlier and the handle springs back on the liquid spring.
+
+## When to use
+
+- Confirming an action with real consequences where an accidental tap is costly (withdraw, transfer out).
+
+**When not:** ordinary submissions use [Button](./button.md); blocking decisions use [Alert Dialog](./alert-dialog.md).
+
+## Anatomy
+
+- Track — `h-14 rounded-full` (56px), secondary surface, **borderless** — the fill and the handle carry the shape; becomes the solid brand fill when confirmed. `data-slot="slide-to-confirm"`, `data-confirmed`.
+- Handle — `size-11.5` (46px) brand circle with an arrow, 5px inset all round, lifted by the `--shadow-brand-glow` glow. At rest it runs the `slide-confirm-nudge` idle animation. `data-slot="slide-to-confirm-handle"`.
+- Brand sweep — the solid `background-brand-default` fill riding just ahead of the handle. `data-slot="slide-to-confirm-progress"`.
+- Label reveal — the label is painted twice: subtle ink on the track, white ink revealed from behind the handle. The grey→white switch line sits under the handle's centre, so text ahead of the button always reads grey and text behind it white — the change itself is never visible. `data-slot="slide-to-confirm-reveal"`.
+- Confirmed state — brand fill, `on-brand-static` label, check pops in on `--motion-pop` × `ease-overshoot`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `onConfirm` | `() => void` | — | Fires once when the handle crosses the threshold (or Enter/Space). |
+| `label` | `ReactNode` | `"Slide to confirm"` | Track label; fades as the handle travels. |
+| `confirmedLabel` | `ReactNode` | `"Confirmed"` | |
+| `confirmed` | `boolean` | — | Controlled confirmed state — pass `false` to reset from outside. |
+| `disabled` | `boolean` | `false` | `opacity-24`, pointer events off. |
+
+```tsx
+import { SlideToConfirm } from "@trading-game/design-intelligence-layer"
+
+<SlideToConfirm
+  label="Slide to withdraw 250 USDT"
+  confirmedLabel="Withdrawal requested"
+  onConfirm={submitWithdrawal}
+/>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-secondary-surface` + `border-default-default` (track), `background-brand-default` + `text-on-brand-static` (handle and the confirmed fill — the brand flip in dark is the design), `text-subtle-default` (track label) and `text-on-brand-static` (the revealed label behind the handle), `ring-focus-strong` (focus).
+
+**Motion:** snap-back rides `--primitive-ease-spring` at `duration-slow`; the confirmed check pops on `--motion-pop` × `--primitive-ease-overshoot`.
+
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--slide-to-confirm-label-*` | 14 / medium / 20; confirmed steps up to semibold via the data-attribute rule |
+
+## Behaviour
+
+- Pointer drag with capture; below the 90% threshold the handle springs back to rest.
+- Keyboard: the control is focusable — Enter or Space confirms directly (the drag is a pointer affordance, not an accessibility gate).
+- `onConfirm` fires exactly once; reset by controlling `confirmed` and passing `false`.
+- 56px tall (`h-14`), full-width by default — constrain with `className`.
+- The handle nudges 10px and back on a 1.8s loop **only at rest** — it stops the moment you drag, and `motion-reduce` disables it entirely, per the foundations rule that infinite loops must honour reduced motion.
+- The glow (`--shadow-brand-glow`) is the second sanctioned shadow in the system, after floating chrome. It exists because this handle must read as liftable off its track; don't reuse it for ordinary buttons.
+
+## Do / Don't
+
+**Do**
+- Say what confirming does in the label ("Slide to withdraw 250 USDT").
+- Reset via the `confirmed` prop after your async action settles or fails.
+
+**Don't**
+- Don't use it for reversible actions — the friction is the point.
+- Don't stack two on one screen.

package/docs/components/stepper.md

@@ -1,68 +1,60 @@
 # Stepper
 
-Numeric amount entry with pill +/− buttons and a centered input, built entirely on Input Group; carries a fixed USDT suffix.
+The mobile amount tray — a centred amount with frosted − / + circles either side. The product's stake control. Not to be confused with [Steps](./steps.md), the progress rail.
 
 ## When to use
 
-- Trade and stake amount entry where the user nudges by a fixed step — the primary amount control in order tickets.
+- Adjusting a numeric amount in coarse steps: stake, multiplier, quantity.
 
-**When not:** For free-form numeric fields use Input. For picking along a visual scale use [Slider](./slider.md). For on-screen mobile digit entry pair with Numpad.
+**When not:** free-form numeric entry belongs to [Input](./input.md) (or [Numpad](./numpad.md) on mobile); multi-stage progress is [Steps](./steps.md).
 
 ## Anatomy
 
-Composed from Input Group parts; the root is an `InputGroup` with `data-slot="stepper"` and `data-disabled` when disabled.
-
-- Decrement addon — `InputGroupButton` (Secondary, `icon-xs`/`icon-sm`) with a Minus icon, `aria-label="Decrease value"`.
-- Input — `InputGroupInput`, `type="text" inputMode="numeric" role="spinbutton"`, text-centered, native spin buttons stripped.
-- Suffix — `InputGroupText` hard-coded to `USDT`.
-- Increment addon — `InputGroupButton` with a Plus icon, `aria-label="Increase value"`.
+- Container — full-width row, `data-slot="stepper"`, `data-disabled`.
+- − / + — composed `<Button variant="frosted" size="icon-lg">` (48px brand-selected tint circles); each disables at its bound.
+- Centre — optional uppercase `label` over the editable amount (`role="spinbutton"`, tabular semibold figure).
 
 ## API
 
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `value` | `number` | — | Controlled mode (`value !== undefined`). |
-| `defaultValue` | `number` | `0` | Uncontrolled initial value, clamped to `[min, max]`. |
-| `onValueChange` | `(value: number) => void` | — | Fires with the committed (clamped + rounded) value. |
-| `min` / `max` | `number` | `-Infinity` / `Infinity` | Buttons disable at the bounds; omitted bounds drop the `aria-valuemin/max`. |
-| `step` | `number` | `1` | Also sets display precision: decimal places of `step` drive `toFixed`. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | h-8 / h-10 / h-12 — the 32/40/48 rail; lg upgrades buttons to `icon-sm` and icons to `size-4`. |
-| `disabled` | `boolean` | — | Disables input and both buttons. |
-| `placeholder` / `id` / `name` / `aria-label` | `string` | — | Pass through to the input. |
-| `className` | `string` | — | On the group; default width `w-32`. |
-
-## Variants & sizes
+| `label` | `ReactNode` | — | Uppercase label above the amount, e.g. `"Stake (USDT)"`. |
+| `value` / `defaultValue` | `number` | `0` | Controlled / uncontrolled. |
+| `onValueChange` | `(n: number) => void` | — | |
+| `min` / `max` | `number` | ±∞ | Buttons disable at the bounds; typed values clamp on commit. |
+| `step` | `number` | `1` | Decimal steps set the display precision (0.5 → "2.50"). |
+| `disabled` | `boolean` | `false` | Pointer events off; the `+`/`−` render Button's own disabled state and the label and amount switch to `text-disabled-default`. No wash on the wrapper — stacking one over the Buttons' own dim multiplied to ~6% and made them invisible. |
+| `placeholder`, `id`, `name`, `aria-label` | | — | Pass-through to the amount input. |
 
 ```tsx
 import { Stepper } from "@trading-game/design-intelligence-layer"
 
-<Stepper size="sm" defaultValue={10} step={5} min={0} max={100} />
-<Stepper defaultValue={1} step={0.25} min={0} />   {/* md; shows 2 decimals from step 0.25... */}
-<Stepper size="lg" value={amount} onValueChange={setAmount} min={0} />
+<Stepper label="Stake (USDT)" defaultValue={2} step={0.5} min={0.5} max={100} />
 ```
 
 ## Tokens
 
-**Colour (semantic):** inherited entirely from Input Group and the Secondary Button — no colour classes of its own. The group carries the input hairline/surface/focus tokens; the pill buttons carry Secondary button tokens.
-**Type (private):** none of its own — the Input Group's `--input-*` ladder applies via `[data-slot="input-group"][data-size]` (sm 12/16, md 14/20, lg 16/24, regular).
+**Colour (semantic):** the circles are Button `frosted` (`background-brand-selected` + `text-brand-selected`, state-layer glazes); label `text-subtle-default`; amount `text-prominent-default`. Disabled swaps both text roles to `text-disabled-default` and leaves the circles to Button. No colour of its own — everything is composed.
+
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--stepper-stake-label-*` | 12 / medium / 16, tracked uppercase |
+| `--stepper-stake-amount-*` | 24 / semibold / 32, tabular |
 
 ## Behaviour
 
-- Controlled when `value` is set, otherwise internal state seeded from `defaultValue` clamped to bounds.
-- Every commit (button click, blur, Enter) clamps to `[min, max]`, then rounds: `toFixed(decimalPlaces(step))` when the step is fractional, `Math.round` otherwise. `onValueChange` receives the committed number.
-- While focused, the raw typed string is preserved; on blur/Enter an unparseable string reverts to the last committed value.
-- ArrowUp / ArrowDown increment / decrement by `step` (default prevented).
-- Decrement disables at `value <= min`, increment at `value >= max`.
-- The `USDT` suffix is hard-coded — there is no currency prop.
+- The amount is directly editable: type, then blur or Enter commits (clamped to min/max, rounded to the step's precision); ArrowUp/ArrowDown step the value.
+- `onValueChange` fires with the committed number.
+- Full-width by default — constrain with `className` (`max-w-90` in the demo).
 
 ## Do / Don't
 
 **Do**
-- Set real `min`/`max` so the buttons self-disable at the bounds and `aria-valuemin/max` are exposed.
-- Choose `step` to match the asset's precision — display precision follows the step's decimal places exactly.
-- Keep the control on the rail via `size`; widen with `className` (default is `w-32`).
+- Put the unit in the `label` ("Stake (USDT)").
+- Pair with [Numpad](./numpad.md) on mobile amount screens.
 
 **Don't**
-- Don't compose your own +/− input for amounts — this is the canonical Input Group composition.
-- Don't try to relabel the suffix via props; it is fixed to USDT in the source.
-- Don't listen to keystrokes for the value — only committed values reach `onValueChange`.
+- Don't use it for long-range values — that's [Slider](./slider.md).
+- Don't hide the label on money amounts; the unit matters.

package/docs/components/steps.md

@@ -0,0 +1,77 @@
+# Steps
+
+Progress rail — numbered indicators, onboarding timelines, and live status timelines. Fully generic composition: the consumer supplies the steps (any count), each with optional icon, title, description, and tag. Not to be confused with [Stepper](./stepper.md), the numeric +/− input.
+
+## When to use
+
+- Multi-stage flows (onboarding, KYC, checkout) — horizontal.
+- Live progress of a process (withdrawal status, transfer pipeline) — vertical.
+
+**When not:** for a value the user adjusts use [Stepper](./stepper.md); for page position use [Pagination](./pagination.md) or [Breadcrumb](./breadcrumb.md).
+
+## Anatomy
+
+- `Steps` — the `<ol>` rail; sets shape, orientation and size for its children and auto-numbers them. `data-slot="steps"`, `data-shape`, `data-orientation`, `data-size`.
+- `Step` — one `<li>`: indicator (number, icon, or check when done) + optional title / description / tag, joined by hairline connectors. `data-slot="step"`, `data-state`; `aria-current="step"` when active.
+
+## API
+
+### Steps
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `shape` | `"circle" \| "square"` | `"circle"` | circle = dots; square = `rounded-md` tiles (the onboarding look). |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Vertical puts the rail left, content right. |
+| `size` | `"sm" \| "md"` | `"md"` | md = 32px indicators, 14/20 type; sm = 24px indicators, 12/16 type, tighter spacing. Works with both shapes and orientations. |
+
+### Step
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `state` | `"done" \| "active" \| "upcoming"` | `"upcoming"` | done = success fill + check; active = brand fill; upcoming = muted surface. |
+| `icon` | `ReactNode` | — | Replaces the automatic step number. |
+| `title` | `ReactNode` | — | |
+| `description` | `ReactNode` | — | |
+| `tag` | `ReactNode` | — | Small uppercase marker beside the title (e.g. "Start here"), selected-family ink. |
+
+```tsx
+import { Step, Steps } from "@trading-game/design-intelligence-layer"
+
+<Steps orientation="vertical" shape="square">
+  <Step state="done" icon={<ArrowDownLeft />} title="Deposit" description="Send any crypto — it lands as USDT." />
+  <Step state="active" icon={<ArrowLeftRight />} title="Transfer" tag="You are here" />
+  <Step title="Trade" />
+</Steps>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-success-solid` + `text-on-status-static` (done), `background-brand-default` + `text-on-brand-static` (active — the fill flips to the dark brand by design), `background-secondary-surface` + `text-subtle-default` (upcoming), `border-neutral-default` (connectors — the stronger hairline so the rail stays visible in both themes), `text-prominent-default` / `text-subtle-default` (title/description), `text-brand-selected` (tag ink).
+
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--steps-indicator-*` | 14 / semibold / 20, tabular |
+| `--steps-title-*` | 14 / semibold / 20 |
+| `--steps-description-*` | 14 / regular / 20 |
+| `--steps-tag-*` | 10 / semibold / 16, tracked uppercase |
+
+`size="sm"` re-points the indicator/title/description tokens at the 12/16 primitives via the `[data-size="sm"]` scope — weights unchanged, tag stays 10/16.
+
+## Behaviour
+
+- Numbering is automatic from child order; add or remove steps freely (5–8 render comfortably in a content column).
+- `done` always shows the check — an `icon` is overridden in that state.
+- Indicators are 32px (`size-8`) at md, 24px (`size-6`) at sm.
+- Vertical steps keep a minimum row height (`min-h-14` md / `min-h-11` sm) so title-only steps always show a stretch of rail; steps with descriptions outgrow it naturally.
+
+## Do / Don't
+
+**Do**
+- Mark exactly one step `active`.
+- Use `square` + icons for onboarding, `circle` for numbered/status rails.
+
+**Don't**
+- Don't use it as navigation — steps aren't links.
+- Don't put long copy in `description`; one line per step.

package/docs/components/switch.md

@@ -6,7 +6,7 @@ Binary on/off toggle (Radix Switch) with a sliding white thumb.
 
 - Settings that take effect immediately — notifications on/off, dark mode, one-click trading.
 
-**When not:** For options submitted with a form use Checkbox. For selecting one of several visible options use [Toggle Group](./toggle-group.md).
+**When not:** For options submitted with a form use Checkbox. For selecting one of several visible options use [Toggle Group](./toggle.md).
 
 ## Anatomy
 

package/docs/components/tabs.md

@@ -6,7 +6,7 @@ Peer-view switcher (Radix Tabs) with a filled-pill default variant and a brand-u
 
 - Switching between sibling views of equal weight — Buy/Sell, chart intervals, account sections.
 
-**When not:** For navigation between routes use Navigation Menu or [Sidebar](./sidebar.md). For toggling values that stay on screen use [Toggle Group](./toggle-group.md).
+**When not:** For navigation between routes use Navigation Menu or [Sidebar](./sidebar.md). For toggling values that stay on screen use [Toggle Group](./toggle.md).
 
 ## Anatomy