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

package/docs/components/dialog.md

@@ -0,0 +1,95 @@
+# Dialog
+
+General-purpose modal on the shared card shell — dismissable, with an optional circular close button.
+
+## When to use
+
+- Focused tasks and forms that interrupt the page: edit a watchlist, review order details, settings sub-flows.
+
+**When not:** For destructive confirmations that must not be casually dismissed use [Alert Dialog](./alert-dialog.md). On mobile, edge-anchored flows belong to [Drawer](./drawer.md).
+
+## Anatomy
+
+- `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.
+- `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"`.
+
+## API
+
+### Dialog (root)
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `open` / `defaultOpen` | `boolean` | — | Controlled / uncontrolled. |
+| `onOpenChange` | `(open) => void` | — | Radix callback. |
+| `modal` | `boolean` | `true` | Radix modality. |
+
+### DialogContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `showCloseButton` | `boolean` | `true` | Renders the circular top-right X. |
+
+### DialogFooter
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `showCloseButton` | `boolean` | `false` | Appends a `secondary` md Close button wired to `DialogPrimitive.Close`. |
+
+## Variants & sizes
+
+One size (`sm:max-w-lg`, `max-w-[calc(100%-2rem)]` on small screens); override via `className`.
+
+```tsx
+import {
+  Dialog, DialogTrigger, DialogContent, DialogHeader,
+  DialogTitle, DialogDescription, DialogFooter, Button,
+} from "@trading-game/design-intelligence-layer"
+
+<Dialog>
+  <DialogTrigger asChild><Button variant="secondary">Order details</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Order details</DialogTitle>
+      <DialogDescription>Filled 2 Sep 2026, 14:02.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter showCloseButton>
+      <Button>Download receipt</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## 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).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--dialog-title-*` | 18 / semibold (600) / 24 |
+| `--dialog-description-*` | 14 / regular (400) / 20 |
+
+## 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}`.
+- `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.
+
+## Do / Don't
+
+**Do**
+- Keep titles at 18/semibold/24 — semibold is the maximum weight.
+- Use `DialogTrigger asChild` around a Button rather than a bare trigger.
+- Turn off the X (`showCloseButton={false}`) only when the footer offers an explicit exit.
+
+**Don't**
+- Don't add shadows or change the 18px radius.
+- Don't use Dialog for irreversible confirmations — Alert Dialog exists so overlay-dismiss cannot destroy work.
+- Don't stack dialogs on top of dialogs.

package/docs/components/drawer.md

@@ -0,0 +1,97 @@
+# Drawer
+
+Edge-anchored panel built on vaul — the mobile-first modal that slides from the bottom (or any edge) with a drag-to-dismiss handle.
+
+## When to use
+
+- Mobile flows: amount entry, filters, detail sheets — anything a thumb should be able to swipe away.
+- Side directions for narrow desktop panels when Sheet-style behaviour is wanted with drag physics.
+
+**When not:** Centred desktop tasks belong to [Dialog](./dialog.md); hard confirmations to [Alert Dialog](./alert-dialog.md).
+
+## Anatomy
+
+- `Drawer` / `DrawerTrigger` / `DrawerPortal` / `DrawerClose` — vaul plumbing with `data-slot` names (`drawer`, `drawer-trigger`, `drawer-portal`, `drawer-close`).
+- `DrawerOverlay` — scrim in `background-overlay-default`; `data-slot="drawer-overlay"`.
+- `DrawerContent` — the panel; direction-aware chrome via `data-vaul-drawer-direction`; `data-slot="drawer-content"`. Bottom drawers show the grab handle: a 100×8px `rounded-full` bar in `bg-border-default-default`.
+- `DrawerHeader` — `p-4`, centred for top/bottom, left from `md`; `data-slot="drawer-header"`.
+- `DrawerTitle` / `DrawerDescription` — `type-drawer-title` / `-description`.
+- `DrawerFooter` — bottom-pinned (`mt-auto`), stacked full-width children; `data-slot="drawer-footer"`.
+
+## API
+
+### Drawer (root — vaul props)
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `direction` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | Sets edge, radius, and handle. |
+| `open` / `defaultOpen` / `onOpenChange` | vaul props | — | Controlled / uncontrolled. |
+| `snapPoints`, `dismissible`, `modal`, … | vaul props | — | Pass through untouched. |
+
+### DrawerContent / others
+
+Standard vaul/element props plus `className`; no additional props of their own.
+
+## Variants & sizes
+
+Direction is the axis.
+
+```tsx
+import {
+  Drawer, DrawerTrigger, DrawerContent, DrawerHeader,
+  DrawerTitle, DrawerDescription, DrawerFooter, DrawerClose, Button,
+} from "@trading-game/design-intelligence-layer"
+
+<Drawer>
+  <DrawerTrigger asChild><Button>Set amount</Button></DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Trade amount</DrawerTitle>
+      <DrawerDescription>Balance: 1,240.50</DrawerDescription>
+    </DrawerHeader>
+    <DrawerFooter>
+      <Button>Confirm</Button>
+      <DrawerClose asChild><Button variant="tertiary">Cancel</Button></DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+
+<Drawer direction="right">…</Drawer>
+```
+
+| Direction | Chrome |
+| --- | --- |
+| `bottom` | `rounded-t-2xl`, top hairline, `max-h-[80vh]`, grab handle |
+| `top` | `rounded-b-2xl`, bottom hairline, `max-h-[80vh]`, no handle |
+| `left` / `right` | square corners, side hairline, `w-3/4` capped at `sm:max-w-sm` |
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` (panel), `background-overlay-default` (scrim), `border-border-default-default` (edge hairline and the grab handle fill), `text-prominent-default` (title), `text-subtle-default` (description).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--drawer-title-*` | 18 / semibold (600) / 24 |
+| `--drawer-description-*` | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- vaul provides the drag/velocity dismissal, snap points, and background scaling; direction is read from `data-vaul-drawer-direction` at render.
+- Only the detached edge is rounded (`rounded-t-2xl` bottom, `rounded-b-2xl` top — the 18px card radius); side drawers stay square because they meet two screen edges.
+- The grab handle renders only on bottom drawers — the direction users can actually drag from comfortably.
+- Top/bottom drawers cap at 80vh and reserve 96px (`mb-24`/`mt-24`) of visible page.
+- `DrawerFooter` forces every child full-width (`[&>*]:w-full`) — the mobile button stack.
+- Header text centres on top/bottom drawers and left-aligns from `md`.
+
+## Do / Don't
+
+**Do**
+- Default to `direction="bottom"` on mobile; the handle plus swipe is the primary dismissal.
+- Put actions in `DrawerFooter` so they pin to the bottom and go full-width.
+- Keep titles at 18/semibold/24.
+
+**Don't**
+- Don't add your own rounding to side drawers — square is deliberate.
+- Don't recolour the grab handle; it is `bg-border-default-default` by contract.
+- Don't exceed 80vh with content — let the body scroll inside the panel instead.

package/docs/components/dropdown-menu.md

@@ -0,0 +1,92 @@
+# Dropdown Menu
+
+Trigger-anchored action menu with items, checkboxes, radios, labels, shortcuts, and nested submenus.
+
+## When to use
+
+- Overflow ("⋯") actions, account menus, per-row operations — a short list of commands behind a visible trigger.
+
+**When not:** For right-click actions use [Context Menu](./context-menu.md). For picking a form value use Select. For searchable long lists use [Command](./command.md).
+
+## Anatomy
+
+- `DropdownMenu` / `DropdownMenuTrigger` / `DropdownMenuPortal` / `DropdownMenuGroup` / `DropdownMenuRadioGroup` / `DropdownMenuSub` — Radix plumbing, each with its `data-slot` (`dropdown-menu`, `dropdown-menu-trigger`, …).
+- `DropdownMenuContent` / `DropdownMenuSubContent` — panel: `rounded-lg` (10px), hairline border, surface fill, `p-1`, `min-w-[8rem]`; scrolls within the Radix available height.
+- `DropdownMenuItem` — action row, `rounded-md` (8px); `data-inset`, `data-variant`.
+- `DropdownMenuCheckboxItem` / `DropdownMenuRadioItem` — `pl-8` rows with left indicators (16px check / 8px filled circle).
+- `DropdownMenuLabel` — heading row; `DropdownMenuSeparator` — 1px hairline; `DropdownMenuShortcut` — right-aligned hint; `DropdownMenuSubTrigger` — row with trailing chevron.
+
+## API
+
+### DropdownMenuContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `sideOffset` | `number` | `4` | Gap from the trigger. |
+| `align`, `side`, … | Radix props | — | Positioning pass-through. |
+
+### DropdownMenuItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "destructive"` | `"default"` | Destructive = error ink; focus paints the error tint. |
+| `inset` | `boolean` | — | `pl-8` alignment with indicator rows. |
+| `onSelect`, `disabled` | Radix props | — | Standard item behaviour. |
+
+### DropdownMenuCheckboxItem / DropdownMenuRadioItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `checked` | `boolean \| "indeterminate"` | — | Checkbox item. |
+| `value` | `string` | — | Radio item within `DropdownMenuRadioGroup`. |
+
+`DropdownMenuSubTrigger` and `DropdownMenuLabel` also take `inset`.
+
+## Variants & sizes
+
+One panel size; rows vary by kind.
+
+```tsx
+import {
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
+  DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator,
+  DropdownMenuShortcut, Button,
+} from "@trading-game/design-intelligence-layer"
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="secondary" size="icon-sm" aria-label="More"><MoreHorizontal /></Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuLabel>Position</DropdownMenuLabel>
+    <DropdownMenuItem>Edit alert<DropdownMenuShortcut>⌘E</DropdownMenuShortcut></DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">Close position</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` + `border-border-default-default` (panel), `text-prominent-default` (rows, labels), `background-hover-default` (focused/open row), `icon-subtle-default` (row icons), `text-subtle-default` (shortcuts), `text-error-default` + `background-error-default` (destructive row and its focus tint), `bg-border-default-default` (separator).
+**Type (private):** shared `--menu-*` family — item 14/regular/20, heading 12/medium/16, trigger 14/medium/20, shortcut 12/regular/16.
+
+## Behaviour
+
+- Radix manages open state, positioning, collision, typeahead, and keyboard navigation; the panel portals with fade/zoom/slide-per-side animation.
+- Row focus uses the hover glaze (`focus:bg-background-hover-default`), never a brand-selected fill; an open sub-trigger holds the glaze.
+- Destructive rows force error ink on their icons (`*:[svg]:text-text-error-default!`).
+- Disabled rows: `pointer-events-none opacity-24`.
+- Radius contract: panel `rounded-lg` 10px, rows `rounded-md` 8px.
+
+## Do / Don't
+
+**Do**
+- Wrap the trigger around a real Button with `asChild`; icon triggers are circles.
+- Use `align="end"` when the trigger sits at a row's right edge.
+- Use `inset` on plain items sharing a menu with checkbox/radio rows.
+
+**Don't**
+- Don't use a dropdown menu as a value picker in forms — that is Select.
+- Don't restyle focused rows with brand-selected tokens; menus highlight with the hover glaze.
+- Don't exceed one submenu level or bury the destructive action mid-list — last, after a separator.

package/docs/components/empty.md

@@ -0,0 +1,87 @@
+# Empty
+
+Centered empty-state block for pages, panels, and lists that currently have nothing to show.
+
+## When to use
+
+- A list, table, or search result set has no rows and you need to explain why and offer a next step.
+- First-run surfaces where the user has not created anything yet.
+
+**When not:** For inline row content inside a populated list use [Item](./item.md). For transient status feedback use a banner or toast, not an empty state.
+
+## Anatomy
+
+- `Empty` — dashed-border container, `rounded-2xl`, `p-6 md:p-12`, centered column. `data-slot="empty"`.
+- `EmptyHeader` — stacks media, title, description (`max-w-sm`, `gap-2`). `data-slot="empty-header"`.
+- `EmptyMedia` — icon or illustration slot above the text. `data-slot="empty-icon"`.
+- `EmptyTitle` — heading line. `data-slot="empty-title"`.
+- `EmptyDescription` — supporting copy; nested links get an underline and brand hover ink. `data-slot="empty-description"`.
+- `EmptyContent` — action area (buttons, links), `max-w-sm`, `gap-4`. `data-slot="empty-content"`.
+
+## API
+
+### EmptyMedia
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "icon"` | `"default"` | `icon` renders a 40px (`size-10`) `rounded-lg` tile on `bg-background-secondary-surface` with `text-icon-prominent-default`; inner svg is `size-6`. `default` is transparent, for illustrations. |
+
+All other parts accept only standard `div`/`p` props plus `className`.
+
+## Variants & sizes
+
+```tsx
+import {
+  Empty,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+  EmptyDescription,
+  EmptyContent,
+  Button,
+} from "@trading-game/design-intelligence-layer"
+import { InboxIcon } from "lucide-react"
+
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <InboxIcon />
+    </EmptyMedia>
+    <EmptyTitle>No open positions</EmptyTitle>
+    <EmptyDescription>Your trades will appear here once you place one.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Start trading</Button>
+  </EmptyContent>
+</Empty>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- `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`
+
+**Type (private):**
+- `--empty-title-*`: 18 / semibold / 24
+- `--empty-description-*`: 14 / regular / 20 (used by both `EmptyDescription` and `EmptyContent`)
+
+## Behaviour
+
+- Purely presentational; no state.
+- Container padding steps from `p-6` to `p-12` at the `md` breakpoint.
+- Links inside `EmptyDescription` are underlined at rest (`underline-offset-4`) — the one place this system underlines at rest, because the surrounding copy gives no other affordance.
+
+## Do / Don't
+
+**Do**
+- Use `EmptyMedia variant="icon"` for glyphs — the 40px secondary-surface tile is the standard treatment.
+- Keep the title at the token size (18/semibold/24); semibold 600 is the system's maximum weight.
+- Put actions in `EmptyContent`, not loose under the header.
+
+**Don't**
+- Don't add a shadow or solid fill to the container — the dashed hairline on a transparent ground is the design.
+- Don't exceed semibold on the title; no bold anywhere in components.
+- Don't swap the icon tile's colours to raw primitives; the semantic pair is the contract.

package/docs/components/field.md

@@ -0,0 +1,117 @@
+# Field
+
+Form-row scaffolding: label, control, helper text, and error wiring, with one `size` prop that sizes the whole frame.
+
+## When to use
+
+- Any labelled form control — wrap the control in `Field` and it gets label typography, spacing, description, and error display for free.
+- Grouped choices: wrap `RadioGroup`/checkbox groups in `FieldSet` + `FieldLegend`; use `FieldLabel` as a choice card around a whole `Field`.
+
+**When not:** For a bare label with no field frame use [Label](./label.md). For the text control itself see [Input](./input.md), [Input Group](./input-group.md), or [Native Select](./native-select.md).
+
+## Anatomy
+
+- `FieldSet` — `<fieldset>` wrapper, `gap-6` (`gap-3` when it directly contains a checkbox/radio group). `data-slot="field-set"`.
+- `FieldLegend` — `<legend>`; `variant="legend"` (16/medium/24) or `"label"` (14/medium/20). `data-slot="field-legend"`.
+- `FieldGroup` — vertical stack of Fields, `gap-7`, container-query scope for responsive orientation. `data-slot="field-group"`.
+- `Field` — the row itself; provides `FieldSizeContext`. `role="group"`, `data-slot="field"`, `data-orientation`, `data-size`.
+- `FieldContent` — flex column for label + description beside a checkbox/radio. `data-slot="field-content"`.
+- `FieldLabel` — a `Label` sized by the field context; becomes a bordered choice card when it wraps a nested `Field`. `data-slot="field-label"`.
+- `FieldTitle` — non-`<label>` title with the same ladder. `data-slot="field-label"`.
+- `FieldDescription` — helper copy, fixed 12/16. `data-slot="field-description"`.
+- `FieldSeparator` — hairline with optional centred text chip. `data-slot="field-separator"`.
+- `FieldError` — `role="alert"` error text, fixed 12/16. `data-slot="field-error"`.
+- `useFieldSize` — hook controls call to read the cascade.
+
+## API
+
+### Field
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Cascades via `FieldSizeContext` to Input, Input Group, and Native Select inside; an explicit `size` on the control wins. Also picks the label ladder and row gap (sm `gap-2`, md/lg `gap-3`). |
+| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | `responsive` switches to horizontal at the `@md` width of the enclosing `FieldGroup` container. |
+
+### FieldLegend
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"legend" \| "label"` | `"legend"` | Chooses `type-field-legend` (16/medium/24) vs `type-field-legend-label` (14/medium/20). The class is picked in JSX because `.type-*` classes are plain CSS — Tailwind `data-[]` variants cannot gate them. |
+
+### FieldError
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `errors` | `Array<{ message?: string } \| undefined>` | — | Deduplicated by `message`; one error renders inline, several render as a `list-disc` `<ul>`. `children` overrides. Renders nothing when both are empty. |
+
+### ItemGroup-style parts
+
+`FieldSet`, `FieldGroup`, `FieldContent`, `FieldTitle`, `FieldDescription`, `FieldSeparator` take only standard element props plus `className`; `FieldSeparator` additionally accepts `children` for the text chip.
+
+## Variants & sizes
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  Input,
+} from "@trading-game/design-intelligence-layer"
+
+// One prop sizes label + control together: sm = 32px input + 12/16 label.
+<Field size="sm" data-invalid={hasError || undefined}>
+  <FieldLabel htmlFor="stake">Stake</FieldLabel>
+  <Input id="stake" inputMode="decimal" aria-invalid={hasError} />
+  <FieldDescription>Minimum stake is 0.35 USD.</FieldDescription>
+  <FieldError errors={[error]} />
+</Field>
+```
+
+```tsx
+// Choice card: FieldLabel wrapping a Field grows a border and lights up
+// with the brand-selected tokens when the control inside is checked.
+<FieldLabel>
+  <Field orientation="horizontal">
+    <RadioGroupItem value="rise" id="rise" />
+    <FieldContent>
+      <FieldTitle>Rise</FieldTitle>
+      <FieldDescription>Win if the exit spot is above the entry spot.</FieldDescription>
+    </FieldContent>
+  </Field>
+</FieldLabel>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- `text-text-error-default` — painted on the whole Field via `data-[invalid=true]`; label and error inherit it
+- `text-text-prominent-default` (legend), `text-text-subtle-default` (description, separator chip)
+- Choice card: `border-border-default-default` at rest; checked = `border-border-brand-selected` + `bg-background-brand-selected`
+- Separator chip sits on `bg-background-primary-surface`
+
+**Type (private):**
+- `--field-label-*` per size: sm 12/16, md 14/20, lg 16/24 — all medium (`--field-label-font-weight`)
+- `--field-description-*`: 12 / regular / 16 — fixed at every field size (description, error, and separator chip all use it)
+- `--field-legend-*`: 16 / medium / 24; `--field-legend-label-*`: 14 / medium / 20
+
+## Behaviour
+
+- `size` cascades through `FieldSizeContext`; `Input`, `InputGroup`, and `NativeSelect` default to it, and an explicit size on the control always wins.
+- `data-invalid` on `Field` sets `text-text-error-default` on the group; `Label` deliberately inherits colour, so the label turns red with no extra wiring.
+- Helper text never scales: description/error/separator stay 12/16 at sm, md, and lg.
+- `FieldLabel` wrapping a nested `Field` becomes a `rounded-md` bordered card (`p-4`); `has-data-[state=checked]` switches it to the brand-selected border + fill.
+- Disabled state (`data-disabled=true` on Field) dims labels to 50% opacity.
+- `FieldError` dedupes repeated messages and returns `null` with no content.
+
+## Do / Don't
+
+**Do**
+- Set size once on `Field` — `<Field size="sm">` gives you the 32px control and the 12/16 label together.
+- Pass `aria-invalid` to the control and `data-invalid` to the Field so ink and border agree.
+- Use `FieldLegend variant="label"` when a radio group sits among plain fields and the 16px legend would shout.
+
+**Don't**
+- Don't force an ink on the label — colour inheritance is how the error state reaches it.
+- Don't gate `.type-*` classes with Tailwind variants; they are plain CSS and lose to nothing — pick the class in JSX as `FieldLegend` does.
+- Don't restyle the checked choice card: `bg-background-brand-selected` / `border-border-brand-selected` are the selection contract (light: 10% brand tint + blue-600 ink; dark: solid #121A55 + blue-200/blue-300).

package/docs/components/hover-card.md

@@ -0,0 +1,77 @@
+# Hover Card
+
+Pointer-hover preview card — rich content that appears when hovering a trigger, for sighted mouse users.
+
+## When to use
+
+- Previewing an entity behind a link or avatar (a trader profile, an instrument summary) without navigating.
+
+**When not:** For click-opened content use [Popover](./popover.md). For a short text hint use Tooltip. Hover cards do not open on touch or keyboard — never put essential actions or information in one.
+
+## Anatomy
+
+- `HoverCard` — Radix root, state owner. `data-slot="hover-card"`.
+- `HoverCardTrigger` — the hoverable element. `data-slot="hover-card-trigger"`.
+- `HoverCardContent` — portalled card, 256px (`w-64`), `rounded-2xl`, `p-4`. `data-slot="hover-card-content"` (portal: `data-slot="hover-card-portal"`).
+
+## API
+
+### HoverCard (root)
+
+Standard Radix `HoverCard.Root` props: `open`, `defaultOpen`, `onOpenChange`, `openDelay`, `closeDelay`.
+
+### HoverCardContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Radix alignment. |
+| `sideOffset` | `number` | `4` | Gap to the trigger in px. |
+
+All other Radix `HoverCard.Content` props pass through.
+
+## Variants & sizes
+
+No variants. One card shell at `w-64`; override width via `className` when the preview needs more room.
+
+```tsx
+import {
+  HoverCard,
+  HoverCardTrigger,
+  HoverCardContent,
+} from "@trading-game/design-intelligence-layer"
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <a href="/traders/aisha">@aisha</a>
+  </HoverCardTrigger>
+  <HoverCardContent>
+    {/* compose your own content; the shell sets surface, border, radius */}
+  </HoverCardContent>
+</HoverCard>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- `bg-background-primary-surface` (solid card surface)
+- `border-border-default-default` (hairline)
+- `text-text-prominent-default` (default ink)
+
+**Type (private):** none — the shell sets no type; compose content with the system's `.type-*` classes or sibling parts (e.g. Popover's title/description pattern).
+
+## Behaviour
+
+- Opens on pointer hover after Radix's `openDelay`; closes on hover-out. No touch or keyboard path — treat the content as strictly supplementary.
+- Content is portalled and animated (fade + 95% zoom, side-aware slide).
+- Card shell is `rounded-2xl` (18px) with a hairline border and no shadow — surfaces are solid in this system.
+
+## Do / Don't
+
+**Do**
+- Keep it to previews the user can live without; the same information must be reachable by click or navigation.
+- Keep the shell defaults: solid primary surface, hairline border, 18px radius, 16px padding.
+
+**Don't**
+- Don't put buttons or form controls inside — they are unreachable for keyboard and touch users.
+- Don't add a shadow or translucent backdrop; the system's overlay depth cue is the hairline on a solid surface.
+- Don't shrink the radius; overlay cards are `rounded-2xl` by law (menus are the 10px tier, not cards).

package/docs/components/input-group.md

@@ -0,0 +1,105 @@
+# Input Group
+
+Input frame with addons — prefixes, suffixes, kbd hints, and inline buttons share one border and one focus ring.
+
+## When to use
+
+- A text control that needs a currency prefix, unit suffix, leading icon, keyboard hint, or an inline action button.
+- Block addons above/below a textarea (e.g. a toolbar row).
+
+**When not:** For a plain control use [Input](./input.md). For code entry use [Input OTP](./input-otp.md).
+
+## Anatomy
+
+- `InputGroup` — the frame; owns border, background, size, variant, and the focus ring. `role="group"`, `data-slot="input-group"`, `data-variant`, `data-size`.
+- `InputGroupInput` — an `Input` stripped of its own frame (`data-slot="input-group-control"`); inherits the group's size/variant via context.
+- `InputGroupTextarea` — same idea for `Textarea`. `data-slot="input-group-control"`.
+- `InputGroupAddon` — addon container; clicking it focuses the input. `data-slot="input-group-addon"`, `data-align`.
+- `InputGroupButton` — a real `Button` compressed to fit the frame.
+- `InputGroupText` — muted inline text/icon span.
+
+## API
+
+### InputGroup
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "on-brand" \| "inverse"` | `"default"` | Mirrors Input: `on-brand` = `--primitive-black-alpha-32` fill + `--primitive-white-alpha-24` border. `inverse` @deprecated — alias of `on-brand`, removed at v1.0. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` (or the enclosing Field's size) | Frame heights `h-8`/`h-10`/`h-12` (32/40/48). |
+
+### InputGroupAddon
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Block aligns stack the group vertically (for textareas/toolbars). The input's padding shrinks to `pl-2`/`pr-2` only on the side an addon touches. |
+
+### InputGroupButton
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | `"xs"` | xs = 24px pill, sm = 32px pill; icon variants are 24/32px circles. Always renders the underlying Button at `size="sm"` type (14/semibold) with height compressed. |
+| `variant` | Button variants | `"secondary"` | Passed straight to `Button`. |
+| `type` | button types | `"button"` | Prevents accidental form submit. |
+
+### InputGroupInput
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` / `variant` | as InputGroup | group's values | Context-fed; explicit props win. |
+
+## Variants & sizes
+
+```tsx
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+  InputGroupText,
+  InputGroupButton,
+} from "@trading-game/design-intelligence-layer"
+
+// Currency prefix + max button, on the 40px rail.
+<InputGroup>
+  <InputGroupAddon>
+    <InputGroupText>USD</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput inputMode="decimal" placeholder="0.00" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton>Max</InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+
+// Brand surface.
+<InputGroup variant="on-brand" size="lg"> … </InputGroup>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- default: `border-border-default-default`, `bg-background-primary-surface`; focus (via `:has` on the control) `border-ring-focus-default` + `ring-ring-focus-soft`
+- error: `border-border-error-default` + `ring-ring-error-soft` when any slot is `aria-invalid`
+- addon/text ink: `text-text-subtle-default`; inside on-brand groups it swaps to `--primitive-white-alpha-64`
+- on-brand (alpha primitives): fill `--primitive-black-alpha-32`, border `--primitive-white-alpha-24`, focus border `background-static-white` + ring `--primitive-white-alpha-40`
+
+**Type (private):** the group inherits the `--input-*` ladder via `data-size` CSS — sm 12/16, md 14/20, lg 16/24 regular; addons and `InputGroupText` ride the same ladder. Buttons keep Button's sm type (14/semibold).
+
+## Behaviour
+
+- The frame carries the border, background, focus ring, and error ring; the inner control is transparent, borderless, ring-less (`rounded-none border-0 bg-transparent focus-visible:ring-0`).
+- Size and variant flow to `InputGroupInput` through `InputGroupSizeContext`/`InputGroupVariantContext`; inside a [Field](./field.md), the Field's size supplies the group default. Explicit props win at every level.
+- Clicking anywhere on an addon focuses the input, unless the click landed on a button.
+- Block addons (`block-start`/`block-end`) switch the group to `h-auto` column layout.
+- Icon sizes track the rail: sm addons get `size-3.5` (14px) icons, md/lg `size-4` (16px).
+- `inverse` is a deprecated render-identical alias of `on-brand`; deleted at v1.0.
+
+## Do / Don't
+
+**Do**
+- Use `InputGroupInput`, never a raw `Input`, inside the frame — otherwise you get two borders and two rings.
+- Use `InputGroupButton` for inline actions: real Button semantics at xs 24px / sm 32px, pills and circles only.
+- Put `aria-invalid` on the control; the frame paints the error border and 20% ring for you.
+
+**Don't**
+- Don't add padding to the input to make room for addons — the frame already trims to `pl-2`/`pr-2` on the addon side and keeps 12px on the free side.
+- Don't restyle addon ink on brand surfaces by hand; the group's `data-variant` does the white-alpha-64 swap.
+- Don't use `variant="inverse"` in new code.