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

package/docs/components/spinner.md

@@ -0,0 +1,52 @@
+# Spinner
+
+Eight-blade fading loading indicator that inherits `currentColor`.
+
+## When to use
+
+- Indeterminate waits tied to an action or small region — button loading states, inline fetches.
+
+**When not:** For content placeholders with a known shape use [Skeleton](./skeleton.md). For measured progress use Progress.
+
+## Anatomy
+
+- `Spinner` — a `size-4` `text-current` div with `role="status"` / `aria-label="Loading"`; renders 8 absolutely-positioned pill blades at 45° increments. No `data-slot` attribute.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `className` | `string` | — | Size via `size-*`, colour via `text-*`; all other div props pass through. |
+
+## Variants & sizes
+
+No variants and no size prop — scale with `className`, colour with text utilities.
+
+```tsx
+import { Spinner } from "@trading-game/design-intelligence-layer"
+
+<Spinner />                          {/* 16px, inherits text colour */}
+<Spinner className="size-6" />       {/* 24px */}
+<Spinner className="size-8 text-text-subtle-default" />
+```
+
+## Tokens
+
+**Colour (semantic):** none hard-coded — blades are `currentColor`, so the spinner takes whatever semantic text token the context sets (e.g. white inside a primary button).
+**Type (private):** none.
+
+## Behaviour
+
+- 8 blades animate `opacity 1 → 0.15` over 0.8s (`linear`), each offset by 0.1s, producing the rotating-fade effect with no transform animation.
+- The `spinner-fade` keyframes ship once in `src/styles.css` (no per-instance `<style>` tags).
+- `role="status"` + `aria-label="Loading"` announce it to screen readers; no visible text.
+
+## Do / Don't
+
+**Do**
+- Size with `size-*` utilities and let `currentColor` pick up the surrounding ink — this is how it stays correct inside buttons of every variant.
+- Keep the default 16px in inline/button contexts; step up (`size-6`, `size-8`) only for region-level loading.
+
+**Don't**
+- Don't hard-code a colour on the blades; set a semantic `text-*` token on the spinner or its parent instead.
+- Don't use a Spinner where a Skeleton would preserve layout — spinners give no shape hint.

package/docs/components/stepper.md

@@ -0,0 +1,68 @@
+# Stepper
+
+Numeric amount entry with pill +/− buttons and a centered input, built entirely on Input Group; carries a fixed USDT suffix.
+
+## When to use
+
+- Trade and stake amount entry where the user nudges by a fixed step — the primary amount control in order tickets.
+
+**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.
+
+## 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"`.
+
+## 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
+
+```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} />
+```
+
+## 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).
+
+## 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.
+
+## 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`).
+
+**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`.

package/docs/components/switch.md

@@ -0,0 +1,57 @@
+# Switch
+
+Binary on/off toggle (Radix Switch) with a sliding white thumb.
+
+## When to use
+
+- 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).
+
+## Anatomy
+
+- `Switch` — Radix root, `rounded-full` pill track with 3px inner padding; `data-slot="switch"`, `data-size`, `data-state`.
+- Thumb — internal `rounded-full` static-white circle; `data-slot="switch-thumb"`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "default"` | `"default"` | default: 24px tall (`h-6 w-11`, 18px thumb); sm: 20px tall (`h-5 w-9`, 14px thumb). |
+| `checked` / `defaultChecked` | `boolean` | — | Controlled / uncontrolled. |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Radix callback. |
+| `disabled` | `boolean` | — | `cursor-not-allowed opacity-24` (the system disabled strength). |
+
+## Variants & sizes
+
+Two sizes, one visual style.
+
+```tsx
+import { Switch } from "@trading-game/design-intelligence-layer"
+
+<Switch defaultChecked />
+<Switch size="sm" checked={enabled} onCheckedChange={setEnabled} />
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-brand-default` (checked track), `bg-border-default-default` (unchecked track), `bg-background-static-white` (thumb — static in both themes), `ring-ring-focus-strong` at 3px + `border-ring-focus-default` (focus).
+**Type (private):** none — the component renders no text; pair it with `Label`.
+
+## Behaviour
+
+- The thumb translates `calc(100% + 1px)` when checked; movement is a pure transform transition, `ring-0` and no shadow on the thumb.
+- The track border is transparent by default and only colours on focus-visible.
+- Fully controlled or uncontrolled via the Radix props.
+
+## Do / Don't
+
+**Do**
+- Use the default 24px size on the standard rail; reserve `sm` (20px) for dense rows and table cells.
+- Pair every Switch with a visible `Label` or an `aria-label` — it has no text of its own.
+- Apply the change immediately on toggle; a switch that needs a Save button should be a Checkbox.
+
+**Don't**
+- Don't tint the thumb — it is `background-static-white` in both themes by design.
+- Don't add shadows to track or thumb; the checked brand fill is the entire state signal.
+- Don't invent intermediate sizes; sm and default are the only two.

package/docs/components/table.md

@@ -0,0 +1,86 @@
+# Table
+
+Data table with hairline row borders, hover glaze rows, and a solid-surface footer.
+
+## When to use
+
+- Tabular data the user scans and compares — positions, order history, market lists.
+
+**When not:** For mixed-media row layouts use Item or Card lists. For key-value pairs inside a card, a simple grid is lighter.
+
+## Anatomy
+
+- `Table` — `<table>` wrapped in an `overflow-x-auto` container; carries `type-table`; `data-slot="table"` (wrapper: `data-slot="table-container"`).
+- `TableHeader` — `<thead>`; its rows get the bottom hairline; `data-slot="table-header"`.
+- `TableBody` — `<tbody>`; strips the border from the last row; `data-slot="table-body"`.
+- `TableFooter` — `<tfoot>`; `type-table-head` weight on a solid secondary surface with a top hairline; `data-slot="table-footer"`.
+- `TableRow` — hairline bottom border, hover glaze, selected fill via `data-state="selected"`; `data-slot="table-row"`.
+- `TableHead` — `<th>`, `h-10 px-2`, left-aligned prominent ink; `data-slot="table-head"`.
+- `TableCell` — `<td>`, `p-2`, middle-aligned, `whitespace-nowrap`; `data-slot="table-cell"`.
+- `TableCaption` — subtle ink, `mt-4`; `data-slot="table-caption"`.
+
+## API
+
+All parts take their native element props plus `className` — no cva variants, no size props. Row selection styling is driven by `data-state="selected"` on `TableRow`.
+
+## Variants & sizes
+
+One density.
+
+```tsx
+import {
+  Table, TableHeader, TableBody, TableFooter,
+  TableRow, TableHead, TableCell, TableCaption,
+} from "@trading-game/design-intelligence-layer"
+
+<Table>
+  <TableCaption>Open positions</TableCaption>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Market</TableHead>
+      <TableHead>Size</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow data-state="selected">
+      <TableCell>BTC/USDT</TableCell>
+      <TableCell>0.50</TableCell>
+    </TableRow>
+  </TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell>Total</TableCell>
+      <TableCell>0.50</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+## Tokens
+
+**Colour (semantic):** `border-border-default-default` (row hairlines, footer top border), `bg-background-hover-default` (row hover glaze), `bg-background-brand-selected` (selected rows — the selection family, correct in both themes), `bg-background-secondary-surface` (footer surface), `text-text-prominent-default` (heads), `text-text-subtle-default` (caption).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--table-*` (cells, via `.type-table`) | 14 / regular (400) / 20 |
+| `--table-head-font-weight` (heads and footer, via `.type-table-head`) | medium (500), same 14/20 metrics |
+
+## Behaviour
+
+- The root always renders inside a `relative w-full overflow-x-auto` container, so wide tables scroll horizontally instead of breaking the page.
+- The last body row drops its border (`[&_tr:last-child]:border-0`); the footer re-introduces separation with its own top hairline and solid secondary fill.
+- Hover glaze and selected fill apply per `TableRow`; selection state is your responsibility via `data-state="selected"`.
+- Cells with a `[role=checkbox]` get `pr-0` and a 2px vertical nudge for optical alignment.
+
+## Do / Don't
+
+**Do**
+- Keep heads at medium (500) via the built-in `type-table-head` — that is the header/body hierarchy.
+- Use `data-state="selected"` for selected rows; the solid secondary surface is the selection treatment here (not the brand-selected family).
+- Right-align numeric columns with `className="text-right"` on head and cell together.
+
+**Don't**
+- Don't bold cells or heads — medium is the table maximum; semibold 600 is the system-wide ceiling.
+- Don't add zebra striping or shadows; hairlines plus hover glaze carry the row rhythm.
+- Don't wrap `Table` in another horizontal scroll container — it ships its own.

package/docs/components/tabs.md

@@ -0,0 +1,95 @@
+# Tabs
+
+Peer-view switcher (Radix Tabs) with a filled-pill default variant and a brand-underline line variant.
+
+## When to use
+
+- 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).
+
+## Anatomy
+
+- `Tabs` — Radix root, `group/tabs`, column layout when horizontal; `data-slot="tabs"`, `data-orientation`.
+- `TabsList` — the track; carries `data-variant` and `data-size` which drive trigger type via CSS; `data-slot="tabs-list"`.
+- `TabsTrigger` — one tab; `data-slot="tabs-trigger"`, `data-icon-position`, `data-state`.
+- `TabsContent` — the panel; `data-slot="tabs-content"`.
+
+## API
+
+### Tabs (root)
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | — | Controlled / uncontrolled active tab. |
+| `onValueChange` | `(value: string) => void` | — | Radix callback. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Vertical stacks the list and moves the line-variant underline to the right edge. |
+
+### TabsList
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "line"` | `"default"` | default: secondary-surface track with an active primary-surface pill; line: transparent track with a brand underline. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | sm `h-8 rounded-md p-[2px]`, md `h-10 rounded-lg p-1`, lg `h-12 rounded-xl p-1.5` — the 32/40/48 rail. |
+
+### TabsTrigger
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Required tab identity. |
+| `iconPosition` | `"inline" \| "top"` | `"inline"` | `top` stacks icon over label (`flex-col`, auto height). |
+
+## Variants & sizes
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@trading-game/design-intelligence-layer"
+
+<Tabs defaultValue="buy">
+  <TabsList size="md">
+    <TabsTrigger value="buy">Buy</TabsTrigger>
+    <TabsTrigger value="sell">Sell</TabsTrigger>
+  </TabsList>
+  <TabsContent value="buy">…</TabsContent>
+  <TabsContent value="sell">…</TabsContent>
+</Tabs>
+
+<Tabs defaultValue="1h">
+  <TabsList variant="line" size="sm">
+    <TabsTrigger value="1h">1H</TabsTrigger>
+    <TabsTrigger value="1d">1D</TabsTrigger>
+  </TabsList>
+</Tabs>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-secondary-surface` (default track), `bg-background-primary-surface` (active pill), `text-text-subtle-default` (resting), `text-text-brand-selected` (active ink, both variants), `text-text-prominent-default` / `text-text-brand-hover` (hover ink — default / line variant), `bg-background-hover-default` (default-variant hover), `border-border-brand-selected` (line-variant underline via `after:bg-border-brand-selected`, 2px, offset 5px below), focus `border-ring-focus-default` + `ring-ring-focus-strong` at 3px.
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--tabs-trigger-*-sm` | 12 / regular (400) / 16 |
+| `--tabs-trigger-*-md` | 14 / regular (400) / 20 |
+| `--tabs-trigger-*-lg` | 16 / regular (400) / 24 |
+| `--tabs-trigger-active-font-weight` | semibold (600) |
+
+The trigger type ladder is applied in CSS off the **list's** `data-size` (`[data-slot="tabs-list"][data-size=…] [data-slot="tabs-trigger"]`), and the active semibold via `[data-state="active"]` — because `.type-*` classes are plain CSS that Tailwind variants can't gate.
+
+## Behaviour
+
+- Active state: default variant lifts the trigger onto a primary-surface pill (`rounded-md`/`sm`/`lg` matching list size, no shadow); line variant keeps the background transparent and fades in the 2px brand underline (`after:opacity-100`).
+- Active ink is `text-brand-selected` and the weight jumps to semibold 600 through the CSS data-state rule — no `font-*` utility involved.
+- Sizing cascades from the list: triggers read the list's `data-size` for type, gap, radius, and padding; `iconPosition="top"` switches to a stacked column and lets the list grow (`has-[[data-icon-position=top]]:h-auto`).
+- Vertical orientation makes triggers full-width/left-justified and moves the line underline to a 2px right-edge bar.
+
+## Do / Don't
+
+**Do**
+- Set `size` on `TabsList` only — triggers inherit everything from the list's `data-size`.
+- Use `variant="line"` where the track would fight a busy surface; the underline carries selection alone.
+- Keep tab labels to one or two words; triggers are `whitespace-nowrap`.
+
+**Don't**
+- Don't apply `font-semibold` to the active trigger — the `data-state="active"` CSS rule already does, and it beats `font-*` utilities.
+- Don't add shadows to the active pill; both variants explicitly force `shadow-none`.
+- Don't mix `iconPosition` values within one list — the whole list stretches to the tallest trigger.

package/docs/components/textarea.md

@@ -0,0 +1,58 @@
+# Textarea
+
+Multi-line text field mirroring the md Input treatment, with content-driven auto-sizing.
+
+## When to use
+
+- Free-form text longer than one line — notes, feedback, support messages.
+
+**When not:** For single-line values use Input. For numeric amounts use [Stepper](./stepper.md).
+
+## Anatomy
+
+- `Textarea` — a single `<textarea>` with hairline border, solid primary surface, and `type-textarea`; `data-slot="textarea"`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `className` | `string` | — | All native `<textarea>` props pass through (`value`, `onChange`, `disabled`, `aria-invalid`, `rows`, …). |
+
+No variants, no size prop — one md-equivalent density.
+
+## Variants & sizes
+
+```tsx
+import { Textarea } from "@trading-game/design-intelligence-layer"
+
+<Textarea placeholder="Add a note…" />
+<Textarea aria-invalid value={note} onChange={(e) => setNote(e.target.value)} />
+```
+
+## Tokens
+
+**Colour (semantic):** `border-border-default-default` (hairline), `bg-background-primary-surface` (solid surface), `text-text-prominent-default` (value), `text-text-subtle-default` (placeholder), `bg-background-brand-default` + `text-text-on-brand-static` (text selection), `border-ring-focus-default` + `ring-ring-focus-soft` at 3px (soft text-field focus ring), `border-border-error-default` + `ring-error-soft` ring (invalid).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--textarea-*` (via `.type-textarea`) | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- `field-sizing-content` grows the field with its content, floored at `min-h-16` (64px) — no JS auto-resize needed.
+- Focus uses the soft text-field ring (`ring-focus-soft`), matching Input, not the 50% control ring.
+- Error state is attribute-driven: set `aria-invalid` and the border/ring switch to the error tokens.
+- Disabled renders `cursor-not-allowed opacity-24`.
+
+## Do / Don't
+
+**Do**
+- Drive errors through `aria-invalid` (typically via Field) so styling and a11y stay in sync.
+- Let `field-sizing-content` handle height; constrain with `max-h-*` + your own overflow if needed.
+- Pair with `Label`; the placeholder is not a label.
+
+**Don't**
+- Don't recreate the focus ring at 50% opacity — text fields take the soft `ring-focus-soft` ring.
+- Don't override the surface with tints or shadows; inputs are hairline + solid surface.
+- Don't bump the type — 14/regular/20 matches the md Input exactly.

package/docs/components/toast.md

@@ -0,0 +1,66 @@
+# Toast
+
+Transient notification system — a themed wrapper around `sonner` on the inverse surface.
+
+## When to use
+
+- Short-lived confirmations and alerts that need no reply — order placed, copied to clipboard, connection lost.
+
+**When not:** For persistent contextual status use [Section Message](./section-message.md). For blocking decisions use Alert Dialog.
+
+## Anatomy
+
+- `Toaster` — the mount point (place once at the app root); wraps sonner's `<Sonner>` with theme, position, icons, and token styling. No `data-slot` attribute (markup is sonner's).
+- `toast` — re-exported sonner imperative API (`toast(...)`, `toast.success(...)`, `toast.error(...)`, …).
+
+## API
+
+### Toaster
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| ...props | sonner `ToasterProps` | — | All pass through; the wrapper presets the values below (overridable). |
+
+Preset defaults: `theme` from `next-themes` (`useTheme`, fallback `"system"`); `position` `"top-center"` on mobile / `"bottom-right"` on desktop (`useIsMobile`); `visibleToasts` 1 mobile / 3 desktop; `duration` 4000ms; status icons CircleCheck / Info / TriangleAlert / OctagonX / spinning Loader2, all `size-4`.
+
+## Variants & sizes
+
+No cva variants — severity comes from the `toast.*` method used.
+
+```tsx
+import { Toaster, toast } from "@trading-game/design-intelligence-layer"
+
+// once, at the app root
+<Toaster />
+
+// anywhere
+toast.success("Order placed")
+toast.error("Deposit failed", {
+  action: { label: "Retry", onClick: retry },
+})
+```
+
+## Tokens
+
+**Colour (semantic, applied via CSS variables / class overrides):** `--background-inverse-surface` (toast surface, borderless), `--text-prominent-inverse` (title), `--text-subtle-inverse` (description — a real mixed ink, AA on the inverse surface), `--background-static-white` + `--text-brand-container-static` (action button — static white fill with brand-container ink in both themes), `--radius` (corner radius).
+**Type (private):** none of its own — title is `font-display` semibold, description `font-body` regular, set through sonner `classNames`.
+
+## Behaviour
+
+- Renders on the inverse surface: dark card on the light theme, light card on dark — with no border and no shadow class of its own.
+- Position and stack depth adapt to viewport: mobile shows a single toast top-center; desktop stacks up to three bottom-right.
+- Theme sync comes from `next-themes`, so the app must be inside a `ThemeProvider` for correct light/dark toasts.
+- Every toast auto-dismisses after 4 seconds unless overridden per call.
+- All sonner options (promise toasts, custom duration, `richColors` off by default) remain available through the `toast` API and `Toaster` props.
+
+## Do / Don't
+
+**Do**
+- Mount exactly one `Toaster` at the root; call `toast.*` from anywhere.
+- Keep messages to one line plus an optional short description; 4 seconds is the reading budget.
+- Use the built-in action slot for the follow-up ("Retry", "Undo") — it renders as the static-white/brand-ink button.
+
+**Don't**
+- Don't restyle toasts onto ordinary surfaces — the inverse surface is what separates them from page content without a shadow.
+- Don't use toasts for errors requiring user action to resolve; those belong in a [Section Message](./section-message.md) next to the failed control.
+- Don't stack meaning into colour alone — the icon set (check/info/triangle/octagon) carries severity.

package/docs/components/toggle-group.md

@@ -0,0 +1,77 @@
+# Toggle Group
+
+A set of related toggles (Radix ToggleGroup) sharing size/variant, rendered joined by default.
+
+## When to use
+
+- Exclusive or multi-select among a few peer options that stay visible — chart interval (1m/5m/1h), order side, view density.
+
+**When not:** For switching content panels use [Tabs](./tabs.md). For a single independent control use [Toggle](./toggle.md). For 5+ options use [Select](./select.md).
+
+## Anatomy
+
+- `ToggleGroup` — Radix root; publishes `variant`/`size`/`spacing` through context and sets `--gap`; `data-slot="toggle-group"` with `data-variant`, `data-size`, `data-spacing`.
+- `ToggleGroupItem` — one segment, styled by the shared `toggleVariants` from Toggle; `data-slot="toggle-group-item"`, `data-state="on|off"`.
+
+## API
+
+### ToggleGroup
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `type` | `"single" \| "multiple"` | — | Radix prop; required. |
+| `variant` | `"default" \| "outline"` | — | Inherited by every item via context. |
+| `size` | `"default" \| "sm" \| "lg"` | — | Same rail as Toggle (36/32/40px). |
+| `spacing` | `number` | `0` | Tailwind spacing units between items; `0` = joined segments. |
+| `value` / `defaultValue`, `onValueChange` | Radix props | — | `string` for single, `string[]` for multiple. |
+
+### ToggleGroupItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Required item identity. |
+| `variant` / `size` | as Toggle | — | Context wins: group-level values override per-item ones. |
+
+## Variants & sizes
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@trading-game/design-intelligence-layer"
+
+// joined segments (default)
+<ToggleGroup type="single" variant="outline" defaultValue="1h">
+  <ToggleGroupItem value="1m">1M</ToggleGroupItem>
+  <ToggleGroupItem value="5m">5M</ToggleGroupItem>
+  <ToggleGroupItem value="1h">1H</ToggleGroupItem>
+</ToggleGroup>
+
+// spaced multiple-select
+<ToggleGroup type="multiple" spacing={2} size="sm">
+  <ToggleGroupItem value="ema">EMA</ToggleGroupItem>
+  <ToggleGroupItem value="vol">VOL</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Tokens
+
+**Colour (semantic):** everything from Toggle (`bg-background-hover-default` on-fill/hover, `text-text-brand-selected` on-ink, `border-border-prominent-default` outline), plus `border-border-brand-selected` on an on-segment's border in joined outline groups.
+**Type (private):** shared `--toggle-*` family — 14 / medium (500) / 20.
+
+## Behaviour
+
+- `spacing={0}` (default) joins segments: items lose their own radius (`rounded-none`), the first/last regain `rounded-l-md`/`rounded-r-md`, and outline items share borders by dropping `border-l` on all but the first.
+- In a joined outline group, an on segment restores its left border and colours its full border `border-border-brand-selected`, so the selected segment reads as outlined in brand.
+- Group-level `variant`/`size` override per-item props through context (`context.variant || variant`).
+- Items are `w-auto min-w-0 shrink-0 px-3` and raise `z-10` on focus so the ring is never clipped by neighbours.
+- Any positive `spacing` separates the items and each keeps its own `rounded-md` shape.
+
+## Do / Don't
+
+**Do**
+- Keep the default `spacing={0}` for segmented-control semantics; use spacing only when items act as independent toggles.
+- Set `variant`/`size` on the group once; per-item overrides are ignored when the group sets them.
+- Use `type="single"` with a `defaultValue` for interval/side pickers so one option is always on.
+
+**Don't**
+- Don't give on-segments a solid brand fill — selection is glaze + `text-brand-selected` ink, with `border-brand-selected` in joined outline groups.
+- Don't mix sizes inside one group; the shared border geometry assumes uniform height.
+- Don't use a joined group for navigation — that is [Tabs](./tabs.md).

package/docs/components/toggle.md

@@ -0,0 +1,60 @@
+# Toggle
+
+Two-state pressable button (Radix Toggle) whose on-state uses the hover glaze plus brand-selected ink.
+
+## When to use
+
+- A single on/off tool control — bold in an editor, favourite a market, show/hide an overlay.
+
+**When not:** For exclusive or multiple selection across several options use [Toggle Group](./toggle-group.md). For settings that apply immediately use [Switch](./switch.md).
+
+## Anatomy
+
+- `Toggle` — Radix root styled by `toggleVariants` (cva, exported and reused by Toggle Group); `data-slot="toggle"`, `data-state="on|off"`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "outline"` | `"default"` | default is transparent at rest; outline adds `border-border-prominent-default`. |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | default `h-10 min-w-10 px-2.5` (40px), sm `h-8 min-w-8 px-1.5` (32px), lg `h-12 min-w-12 px-3` (48px) — on the 32/40/48 rail. |
+| `pressed` / `defaultPressed` | `boolean` | — | Controlled / uncontrolled. |
+| `onPressedChange` | `(pressed: boolean) => void` | — | Radix callback. |
+
+## Variants & sizes
+
+```tsx
+import { Toggle } from "@trading-game/design-intelligence-layer"
+import { Star } from "lucide-react"
+
+<Toggle aria-label="Favourite"><Star /></Toggle>
+<Toggle variant="outline" size="sm">1H</Toggle>
+<Toggle size="lg" pressed={on} onPressedChange={setOn}>Overlay</Toggle>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-hover-default` (hover fill, and the on-state fill — the glaze does double duty), `text-text-prominent-default` (hover ink, outline resting ink), `text-text-brand-selected` (on-state ink), `border-border-prominent-default` (outline variant border; on-state sets `border-transparent`), focus `border-ring-focus-default` + `ring-ring-focus-strong` at 3px, `border-border-error-default` + `ring-error-soft` ring (aria-invalid).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--toggle-*` (via `.type-toggle`) | 14 / medium (500) / 20 |
+
+## Behaviour
+
+- On-state = `bg-background-hover-default` fill + `text-text-brand-selected` ink + transparent border. There is no separate pressed surface token — the hover glaze is reused deliberately.
+- Radius is `rounded-md` (8px, the row radius); icons default to `size-4`.
+- Disabled: `pointer-events-none opacity-24`.
+
+## Do / Don't
+
+**Do**
+- Give icon-only toggles an `aria-label`.
+- Use `outline` when the toggle sits on a busy surface and needs a resting boundary.
+- Let the exported `toggleVariants` style any custom toggle-like control instead of re-deriving classes.
+
+**Don't**
+- Don't give the on-state a solid brand fill — the system on-state is glaze + brand-selected ink only.
+- Don't exceed medium 500 for the label; the type token is fixed at 14/medium/20.
+- Don't use a Toggle where the action navigates or submits — that is a Button.