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

package/guides/design-system-guide/trading-game-ds-guide.md

@@ -1,933 +0,0 @@
-# Trading Game Design System Guide
-
-> **Package:** `@trading-game/design-intelligence-layer`
-> **Audience:** AI agents and developers building UI for the Trading Game. This is the single source of truth for setting up and using the design system in any project.
-
----
-
-## MANDATORY RULES — READ FIRST
-
-### Rule 1 — Component existence check
-
-```
-BEFORE using any component:
-1. Check the Component Catalogue (Section 8). Does it exist?
-   YES → Import it from the npm package exactly as documented. Do NOT re-implement it.
-   NO  → STOP. Tell the user:
-         "The [ComponentName] component does not exist in the Trading Game design system.
-          Options:
-          (a) Build a custom one using design system tokens only (no hardcoded colors or values)
-          (b) Use a different component that exists in the system
-          (c) Skip this component entirely"
-         Wait for the user to choose. Do NOT proceed without confirmation.
-```
-
-### Rule 2 — Token-only styling
-
-```
-NEVER use:
-  ❌ Hardcoded hex: #2323FF, #FFFFFF, etc.
-  ❌ Raw Tailwind palette: bg-gray-100, text-zinc-500, text-slate-400, bg-black, bg-white
-  ❌ Raw opacity on non-tokens: bg-black/50 (use bg-overlay instead)
-  ❌ Arbitrary color values: bg-[#FF6600], text-[rgba(0,0,0,0.5)]
-  ❌ hsl(var(--token)) syntax — this is Tailwind v3. This project uses Tailwind v4.
-  ❌ Non-existent tokens: bg-hover, bg-badge-rank, text-primary-foreground, text-on-decorative
-  ❌ border-border — deprecated alias; use border-border-subtle or border-border-prominent
-
-ALWAYS use semantic tokens:
-  ✅ bg-prominent, bg-card, bg-popover, bg-subtle, bg-overlay
-  ✅ text-on-prominent, text-on-subtle
-  ✅ border-border-subtle, border-border-prominent, ring-ring
-  ✅ bg-primary, bg-primary-hover, bg-secondary-hover
-  ✅ text-semantic-win, text-semantic-loss, text-semantic-warning
-  ✅ Opacity on a token IS allowed: bg-primary/20, border-border-subtle/50, ring-primary/10
-```
-
-### Rule 3 — Layout utilities are exempt
-
-```
-Tailwind layout/spacing utilities are freely usable for structural layout:
-  ✅ flex, grid, gap-4, p-6, m-2, w-full, h-screen, max-w-lg, col-span-2, etc.
-  ✅ z-50, overflow-hidden, transition-all, etc.
-
-Token rules apply ONLY to:
-  - Color (background, text, border, ring, shadow color)
-  - Border radius (use the design system's radius scale — see Section 5)
-  - Typography (font family must use font-display or font-body, never raw font names)
-```
-
-### Rule 4 — Do NOT install or import these separately
-
-```
-❌ lucide-react — already bundled in the npm package
-❌ tailwindcss — the package ships its own Tailwind v4 config
-❌ @apply with hsl(var(--token)) — Tailwind v4 uses CSS variables directly
-❌ tailwind.config.js — configuration is handled by the package via CSS
-❌ Manual font-family in CSS — use font-display and font-body utility classes
-```
-
-### Rule 5 — Complexity-aware implementation
-
-```
-Each component in the catalogue is tagged:
-  [simple]   → Drop in, one import, works immediately
-  [composed] → Has required sub-components; use the full pattern shown
-  [complex]  → Has significant state or setup; ask clarifying questions first
-```
-
----
-
-## 1 — Quick Start
-
-### Step 1 — Install the package
-
-```bash
-npm install @trading-game/design-intelligence-layer@latest --safe-chain-skip-minimum-package-age
-```
-
-### Step 2 — Add CSS imports
-
-In your main CSS file (e.g. `globals.css` or `index.css`):
-
-```css
-@import url("https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&display=swap");
-@import "tailwindcss";
-@import "@trading-game/design-intelligence-layer/styles";
-@source "../node_modules/@trading-game/design-intelligence-layer/dist";
-```
-
-> **Note:** Fonts are loaded via a direct Google Fonts `@import` URL. Do NOT use `next/font`.
-
-### Step 3 — Set base HTML class
-
-The design system is light-first. No extra class is required on `<html>` for the default light theme. A `.dark` class is reserved for future dark theme support but not yet styled.
-
-### Step 4 — Import components
-
-```tsx
-import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
-```
-
----
-
-## 2 — Design Tokens
-
-> This is the single authoritative token reference. All tokens are defined as CSS variables in the package and mapped to Tailwind utility classes automatically.
-
-### 2.1 — Backgrounds
-
-| CSS Variable     | Tailwind Class   | Usage                     |
-| ---------------- | ---------------- | ------------------------- |
-| `--prominent`    | `bg-prominent`   | Main page background      |
-| `--card`         | `bg-card`        | Cards, panels, modals     |
-| `--popover`      | `bg-popover`     | Popovers, elevated cards  |
-| `--subtle`       | `bg-subtle`      | Muted / secondary surfaces|
-| `--overlay`      | `bg-overlay`     | Modal/dialog/drawer/sheet backdrop (semi-transparent) |
-| `--tabs`         | `bg-tabs`        | Tab container / tab bar background (`variant="default"`) — 4% black alpha, adapts to any surface |
-| `--tabs-active`  | `bg-tabs-active` | Active / selected tab background — solid white |
-
-### 2.2 — Primary (Brand Blue)
-
-| CSS Variable          | Tailwind Class      | Usage                     |
-| --------------------- | ------------------- | ------------------------- |
-| `--primary`           | `bg-primary` / `text-primary` | Primary CTA, brand color, interactive elements |
-| `--on-primary`        | `text-on-primary`             | Text/icon color paired with `bg-primary` (always white) |
-| `--primary-hover`     | `bg-primary-hover`  | Hover & pressed states on primary elements |
-| `--primary-inverse`   | `bg-primary-inverse`          | Inverted primary surface — white bg for use on dark/coloured areas |
-| `--on-primary-inverse`| `text-on-primary-inverse`     | Text/icon color paired with `bg-primary-inverse` (always blue) |
-
-### 2.3 — Semantic (Trading Status)
-
-> **Naming convention:** every surface token has a paired `--on-<name>` foreground (text/icon) token. Use the pair together (`bg-semantic-X` + `text-on-semantic-X`) for guaranteed legibility on the saturated surface.
-
-| CSS Variable               | Tailwind Class                              | Usage                                         |
-| -------------------------- | ------------------------------------------- | --------------------------------------------- |
-| `--semantic-win`           | `bg-semantic-win` / `text-semantic-win`     | Win / Profit / Positive outcomes              |
-| `--on-semantic-win`        | `text-on-semantic-win`                      | Text/icon on `bg-semantic-win` surfaces (white) |
-| `--semantic-loss`          | `bg-semantic-loss` / `text-semantic-loss`   | Loss / Negative outcomes                      |
-| `--on-semantic-loss`       | `text-on-semantic-loss`                     | Text/icon on `bg-semantic-loss` surfaces (white) |
-| `--semantic-warning`       | `bg-semantic-warning` / `text-semantic-warning` | Warning / Caution / Non-destructive alerts |
-| `--on-semantic-warning`    | `text-on-semantic-warning`                  | Text/icon on `bg-semantic-warning` surfaces (white) |
-| `--semantic-info`          | `bg-semantic-info` / `text-semantic-info`   | Informational alerts                          |
-| `--semantic-boost`         | `bg-semantic-boost`                         | Boost / bonus badge background (`#F9840F` amber-orange) |
-| `--on-semantic-boost`      | `text-on-semantic-boost`                    | Boost / bonus badge foreground (`#713813` dark amber) |
-
-> All semantic tokens support opacity variants (e.g. `bg-semantic-warning/10` for tinted backgrounds). For structured alpha surfaces, use the primitive alpha scales — see Section 2.10.
-
-### 2.4 — Text & Icon Colors
-
-The system follows a Material-style `<surface>` / `on-<surface>` pair convention: no prefix = surface/background, `on-` prefix = the foreground (text/icon) color paired with that surface.
-
-| CSS Variable              | Tailwind Class                | Usage                     |
-| ------------------------- | ----------------------------- | ------------------------- |
-| `--prominent`             | `bg-prominent`                | Light surface (page chrome, cards) |
-| `--on-prominent`          | `text-on-prominent`           | Text/icon on `bg-prominent` (black) |
-| `--prominent-inverse`     | `bg-prominent-inverse`        | Dark surface for use on light pages (e.g. toasts) |
-| `--on-prominent-inverse`  | `text-on-prominent-inverse`   | Text/icon on `bg-prominent-inverse` (white) |
-| `--on-subtle`             | `text-on-subtle`              | Secondary text (descriptions, labels) — paired with `bg-subtle` |
-| `--on-disabled`           | `text-on-disabled`            | Disabled text (inactive controls, placeholders) |
-
-> **Deprecated aliases:** `--on-prominent-static-inverse` and `--surface-inverse-static` remain defined in CSS for backwards-compat with external consumers using raw `var()` references, but internal components no longer use them — prefer the explicit `on-<surface>` / `<surface>-inverse` pairs above.
-
-### 2.5 — Borders & Inputs
-
-| CSS Variable        | Tailwind Class            | Usage                     |
-| ------------------- | ------------------------- | ------------------------- |
-| `--border-subtle`   | `border-border-subtle`    | Default light border      |
-| `--border-prominent`| `border-border-prominent` | Strong / emphasized border|
-| `--input`           | `border-input`            | Input resting state border|
-| `--ring`            | `ring-ring` / `border-ring` | Focus ring and focus border color |
-
-### 2.6 — Supporting Colors
-
-| CSS Variable             | Tailwind Class       | Usage                     |
-| ------------------------ | -------------------- | ------------------------- |
-| `--secondary-hover`      | `bg-secondary-hover` | Hover bg on neutral elements (light gray) |
-| `--slider-range`         | `bg-slider-range`    | Slider range fill (primary at 40%) |
-| `--alert-info-text`      | `text-alert-info-text` | Alert info text color   |
-| `--alert-info-border`    | `border-alert-info-border` | Alert info border  |
-| `--alert-error-text`     | `text-alert-error-text` | Alert error text color |
-| `--alert-error-border`   | `border-alert-error-border` | Alert error border |
-
-> **Accent (orange) and Violet:** `--primitive-orange-500` and `--primitive-violet-500` are available as CSS variables only (no Tailwind utility class). Use `var(--primitive-orange-500)` directly for rank badges and special highlights.
-
-### 2.7 — Opacity Patterns
-
-| Usage                          | Tailwind Class         |
-| ------------------------------ | ---------------------- |
-| Subtle hover tint              | `bg-primary/[0.08]`   |
-| Medium highlight               | `bg-primary/[0.16]`   |
-| Selected/active tint           | `bg-primary/10`       |
-| Status badge tint backgrounds  | `bg-semantic-win/10`, `bg-semantic-loss/10`, etc. |
-
-### 2.8 — Interactive States
-
-> **`bg-hover` does not exist.** Use `bg-secondary-hover` or `bg-primary/[0.08]` for hover states.
-
-**Universal pattern for interactive list/row/chip elements** (except Button and Tabs which have their own):
-
-| State    | Background           | Text                               |
-| -------- | -------------------- | ---------------------------------- |
-| Default  | transparent          | `text-on-prominent` or `text-on-subtle` |
-| Hover    | `bg-secondary-hover` | `text-primary`                     |
-| Selected | `bg-secondary-hover` | `text-primary font-semibold`       |
-
-> **NEVER** use `bg-accent` or `text-accent-foreground`. Do NOT add borders to selected states.
-
-### 2.9 — Transitions
-
-**Duration tokens:**
-
-| Tailwind Class    | CSS Variable                   | Value  | Usage                                  |
-| ----------------- | ------------------------------ | ------ | -------------------------------------- |
-| `duration-instant`| `--primitive-duration-instant`  | `50ms` | Focus rings, hover color tints         |
-| `duration-fast`   | `--primitive-duration-fast`     | `100ms`| Buttons, inputs, badges, checkboxes    |
-| `duration-base`   | `--primitive-duration-base`     | `200ms`| Dropdowns, popovers, accordions        |
-| `duration-slow`   | `--primitive-duration-slow`     | `300ms`| Dialogs, sheets, drawers closing       |
-| `duration-open`   | `--primitive-duration-open`     | `500ms`| Sheets, drawers entering               |
-
-**Easing tokens:**
-
-| Tailwind Class   | CSS Variable                  | Value                          | Usage                                  |
-| ---------------- | ----------------------------- | ------------------------------ | -------------------------------------- |
-| `ease-standard`  | `--primitive-ease-standard`    | `cubic-bezier(0.2, 0, 0, 1)`  | General UI — bidirectional state changes |
-| `ease-enter`     | `--primitive-ease-enter`       | `cubic-bezier(0, 0, 0.2, 1)`  | Overlays / surfaces entering           |
-| `ease-exit`      | `--primitive-ease-exit`        | `cubic-bezier(0.4, 0, 1, 1)`  | Overlays / surfaces leaving            |
-| `ease-linear`    | `--primitive-ease-linear`      | `linear`                       | Sidebar width, progress bar            |
-
-**Usage pattern:**
-
-```tsx
-<div className="transition-colors duration-fast ease-standard">...</div>
-```
-
-### 2.10 — Primitive Alpha Scales
-
-> Raw alpha (opacity) variants of the mono and blue primitives. These are **internal CSS variables only** — not exposed as Tailwind utility classes. Reference them only from semantic tokens, never directly in components.
-
-**Naming convention:** `--primitive-[color]-alpha-[stop]`
-
-**Mono alpha scale** (black — `oklch(0 0 0 / X%)`)
-
-| CSS Variable                  | Opacity | Typical use                              |
-| ----------------------------- | ------- | ---------------------------------------- |
-| `--primitive-mono-alpha-4`    | 4%      | Tab container background (`--tabs`)      |
-| `--primitive-mono-alpha-8`    | 8%      | Subtle hover tint                        |
-| `--primitive-mono-alpha-16`   | 16%     | Pressed / active surface tint            |
-| `--primitive-mono-alpha-24`   | 24%     | Medium-weight tinted surface             |
-| `--primitive-mono-alpha-32`   | 32%     | Disabled state overlay                   |
-| `--primitive-mono-alpha-40`   | 40%     | Strong tint / scrim                      |
-| `--primitive-mono-alpha-50`   | 50%     | Backdrop overlay (replaces `--primitive-black-50`) |
-| `--primitive-mono-alpha-64`   | 64%     | Heavy overlay                            |
-| `--primitive-mono-alpha-80`   | 80%     | Near-opaque overlay                      |
-
-**Blue alpha scale** (brand blue — `oklch(0.476 0.297 267.4 / X%)`)
-
-| CSS Variable                  | Opacity | Typical use                              |
-| ----------------------------- | ------- | ---------------------------------------- |
-| `--primitive-blue-alpha-4`    | 4%      | Extremely subtle brand tint              |
-| `--primitive-blue-alpha-8`    | 8%      | Hover tint on brand surfaces             |
-| `--primitive-blue-alpha-16`   | 16%     | Selected / active brand tint             |
-| `--primitive-blue-alpha-24`   | 24%     | Medium brand surface highlight           |
-| `--primitive-blue-alpha-32`   | 32%     | Strong brand tint                        |
-| `--primitive-blue-alpha-40`   | 40%     | Slider range fill (via `--slider-range`) |
-| `--primitive-blue-alpha-50`   | 50%     | Brand overlay                            |
-| `--primitive-blue-alpha-64`   | 64%     | Heavy brand overlay                      |
-| `--primitive-blue-alpha-80`   | 80%     | Near-opaque brand overlay                |
-
-> **`--primitive-black-50` is deprecated.** It now aliases `--primitive-mono-alpha-50`. The `--overlay` semantic token is unaffected — it still resolves to the same 50% black value.
-
----
-
-## 3 — AI Agent Decision Rules
-
-> Quick-lookup table: "If I need X, use Y, never Z."
-
-| IF you need to...                      | THEN use                          | NEVER use                              |
-| -------------------------------------- | --------------------------------- | -------------------------------------- |
-| Pick a primary CTA button color        | `bg-primary`                      | Green, or any other color for primary CTA |
-| Show WIN / profit / positive           | `text-semantic-win`               | Primary blue for profit                |
-| Show LOSS / negative                   | `text-semantic-loss`              | Any non-token red                      |
-| Show WARNING / caution                 | `text-semantic-warning`           | Raw orange hex or primary tint         |
-| Show a credit / boost / bonus badge    | `<Badge variant="fill-credit">` (frosted glass — `bg-semantic-boost-surface` = `oklch(1 0 0 / 0.22)` + `backdrop-blur-md` + `text-on-primary`); place it on a coloured surface only — invisible on white | Hardcoded rgba/alpha |
-| Color a tab container background       | `bg-tabs`                         | `bg-subtle` for tabs                   |
-| Color an active/selected tab           | `bg-tabs-active`                  | `bg-prominent` for active tab          |
-| Color a page background                | `bg-prominent`                    | `bg-white` directly                    |
-| Color a modal/dialog backdrop          | `bg-overlay`                      | `bg-black/50` or raw black opacity     |
-| Color a card or panel                  | `bg-card`                         | Arbitrary gray                         |
-| Color an elevated surface (popover)    | `bg-popover`                      | `bg-card` for popovers                 |
-| Write primary heading text             | `text-on-prominent`               | Pure white, raw hex colors             |
-| Write body / description text          | `text-on-subtle`                  | `text-on-prominent` for descriptions   |
-| Write a subtle label                   | `text-on-subtle`                  | Raw gray values                        |
-| Write disabled / inactive text         | `text-on-disabled`                | `text-gray-300`, raw light hex values  |
-| Add a default border                   | `border-border-subtle`            | Solid black borders, `border-border`   |
-| Add a strong border                    | `border-border-prominent`         | —                                      |
-| Style an input (resting)               | `border-input`                    | Solid colored backgrounds              |
-| Style an input (focused)               | `border-ring` + `ring-[3px] ring-ring/50` | Generic shadows on inputs       |
-| Pick a heading font                    | `font-display`                    | System fonts, raw font-family names    |
-| Pick a body font                       | `font-body`                       | Raw font-family names                  |
-| Style button text                      | `font-display font-bold`, sentence case | `uppercase` on buttons           |
-| Write text on a primary blue surface   | `text-on-primary`                 | `text-white` or `text-on-prominent-static-inverse` |
-| Write text on a dark inverse surface   | `text-on-prominent-inverse`       | `text-white` or raw white hex          |
-| Write text on a semantic surface       | `text-on-semantic-win` / `-loss` / `-warning` / `-boost` | `text-white` (the surface may not always be dark) |
-
----
-
-## 4 — Typography
-
-### 4.1 — Font Setup
-
-All text uses **Plus Jakarta Sans** (loaded weights: 300–800). Three Tailwind aliases are available — they all resolve to the same font:
-
-| Tailwind Class  | Purpose                         |
-| --------------- | ------------------------------- |
-| `font-display`  | Headings, wordmark, buttons     |
-| `font-body`     | Body text, UI elements          |
-| `font-sans`     | Default sans-serif fallback     |
-
-### 4.2 — Pre-built Typography Classes
-
-The npm package ships these ready-to-use CSS classes. All include `text-transform: uppercase`:
-
-| Class         | Size  | Line Height | Weight | Letter Spacing |
-| ------------- | ----- | ----------- | ------ | -------------- |
-| `heading-h1`  | 72px  | 72px        | 600    | 1.5px          |
-| `heading-h2`  | 64px  | 64px        | 600    | 1.5px          |
-| `heading-h3`  | 48px  | 48px        | 600    | 1.5px          |
-| `heading-h4`  | 40px  | 40px        | 600    | 1.5px          |
-| `heading-xs`  | 24px  | 24px        | 600    | 1.5px          |
-| `body-lg`     | 18px  | 28px        | 600    | —              |
-| `body-md`     | 16px  | 24px        | 600    | —              |
-| `body-sm`     | 12px  | 16px        | 600    | —              |
-| `body-xs`     | 8px   | 12px        | 600    | —              |
-
-**Responsive heading sizes** (headings scale down on mobile):
-
-| Class        | Desktop | Mobile |
-| ------------ | ------- | ------ |
-| `heading-h1` | 72px    | 48px   |
-| `heading-h2` | 64px    | 48px   |
-| `heading-h3` | 48px    | 40px   |
-| `heading-h4` | 40px    | 32px   |
-| `heading-xs` | 24px    | 20px   |
-
-### 4.3 — Custom Text Size Overrides
-
-These sizes differ from standard Tailwind defaults — use the design system values:
-
-| Class       | Size   | Line Height | How it differs from Tailwind |
-| ----------- | ------ | ----------- | ---------------------------- |
-| `text-xxs`  | 8px    | 12px        | Custom (not in standard TW)  |
-| `text-2xl`  | 24px   | **24px**    | Line height differs (TW: 32px) |
-| `text-3xl`  | **32px** | **32px**  | Size differs (TW: 30px)     |
-| `text-4xl`  | **40px** | **40px**  | Size differs (TW: 36px)     |
-| `text-6xl`  | **64px** | **64px**  | Size differs (TW: 60px)     |
-
-> All other `text-*` sizes (`xs`, `sm`, `base`, `lg`, `xl`, `5xl`, `7xl`, `8xl`, `9xl`) match standard Tailwind.
-
-### 4.4 — Typography Usage Rules
-
-| Context                  | Class          | Weight              |
-| ------------------------ | -------------- | ------------------- |
-| Page headings            | `font-display` | `font-semibold` (600) |
-| Button labels            | `font-display` | `font-bold` (700), sentence case |
-| Body text                | `font-body`    | `font-semibold` (600) |
-| Tiny labels / decorative | `font-body`    | `font-semibold` (600) at 8px |
-
-### 4.5 — Letter Spacing Tokens
-
-| Token value | Usage                    |
-| ----------- | ------------------------ |
-| 1.5px       | Buttons, headings        |
-| -0.4px      | Paragraphs, tight text   |
-| -0.8px      | Tight display text       |
-
----
-
-## 5 — Border Radius
-
-The design system uses a custom radius scale (base = 10px). Use these named tokens instead of arbitrary values:
-
-| Tailwind Class | Value  |
-| -------------- | ------ |
-| `rounded-2xs`  | 2px    |
-| `rounded-xs`   | 4px    |
-| `rounded-sm`   | 6px    |
-| `rounded-md`   | 8px    |
-| `rounded-lg`   | 10px   |
-| `rounded-xl`   | 14px   |
-| `rounded-2xl`  | 18px   |
-| `rounded-3xl`  | 22px   |
-| `rounded-4xl`  | 26px   |
-| `rounded-full` | 9999px |
-
-> **Important:** Do NOT use `rounded-[4px]` or `rounded-[2px]` — use `rounded-xs` and `rounded-2xs` instead. Arbitrary radius values should only be used for sizes not in this scale (e.g. `rounded-[24px]`, `rounded-[32px]`).
-
----
-
-## 6 — Button System
-
-### 6.1 — Variants
-
-| Variant              | Background           | Text Color                  | Border                                   | Hover                       | Use on                 |
-| -------------------- | -------------------- | --------------------------- | ---------------------------------------- | --------------------------- | ---------------------- |
-| `primary`            | `bg-primary`         | `text-on-primary`           | none                                     | `bg-primary-hover`          | Light surfaces         |
-| `primary-inverse`    | `bg-primary-inverse` | `text-on-primary-inverse`   | none                                     | `bg-primary-inverse/80`     | Dark/coloured surfaces |
-| `secondary`          | transparent          | `text-on-prominent`         | `border-[1.5px] border-border-prominent` | `bg-secondary-hover`        | Light surfaces         |
-| `secondary-inverse`  | transparent          | `text-on-prominent-inverse` | `border-[1.5px] border-primary-inverse`  | `bg-primary-inverse/10`     | Dark/coloured surfaces |
-| `tertiary`           | transparent          | `text-on-prominent`         | none                                     | `bg-secondary-hover`        | Light surfaces         |
-| `tertiary-inverse`   | transparent          | `text-on-primary`           | none                                     | `bg-on-primary/[0.10]`      | Dark/coloured surfaces |
-
-### 6.2 — Sizes
-
-| Size      | Height | Padding X | Font Size | Icon Size | Radius |
-| --------- | ------ | --------- | --------- | --------- | ------ |
-| `lg`      | 48px   | 24px      | 16px      | 16px      | 4px    |
-| `md`      | 40px   | 16px      | 14px      | 16px      | 4px    |
-| `sm`      | 32px   | 12px      | 12px      | 14px      | 4px    |
-| `xs`      | 24px   | 8px       | 12px      | 12px      | 4px    |
-
-**Icon-only sizes:**
-
-| Size       | Dimensions | Icon Size |
-| ---------- | ---------- | --------- |
-| `icon-lg`  | 48×48px    | 16px      |
-| `icon-md`  | 40×40px    | 16px      |
-| `icon-sm`  | 28×28px    | 16px      |
-| `icon-xs`  | 24×24px    | 12px      |
-
-### 6.3 — Button Typography & States
-
-All buttons: `font-display font-bold`, sentence case (no `uppercase`, no `tracking-wide`).
-
-| State    | Behavior                                         |
-| -------- | ------------------------------------------------ |
-| Default  | Base styling per variant                         |
-| Hover    | Color shift per variant (see above)              |
-| Focus    | 3px ring with `ring-ring/50` opacity             |
-| Pressed  | `active:opacity-60`                              |
-| Loading  | `opacity-24`, `pointer-events-none`, `data-loading`, `aria-busy` — applies to all variants |
-| Disabled | `opacity-24`, `pointer-events-none` — applies to all variants |
-
----
-
-## 7 — Responsive Layout
-
-### 7.1 — Layout Grid
-
-| Breakpoint | Viewport   | Columns | Gutter | Margin |
-| ---------- | ---------- | ------- | ------ | ------ |
-| Default    | 0–319px    | 1       | 0      | 16px   |
-| Small      | 320–599px  | 4       | 16px   | 16px   |
-| Medium     | 600–1135px | 8       | 36px   | 36px   |
-| Large      | 1136px+    | 12      | 36px   | 64px   |
-
-**Tailwind utilities:** `gap-layout-gutter`, `px-layout-margin-inline`.
-
-**CSS variables for custom grids:** `var(--semantic-layout-grid-columns)`, `var(--spacing-layout-gutter)`, `var(--spacing-layout-margin-inline)`.
-
-### 7.2 — Responsive Spacing Tokens
-
-| Token                | Desktop | Mobile |
-| -------------------- | ------- | ------ |
-| container-padding-x  | 24px    | 16px   |
-| section-padding-y    | 96px    | 64px   |
-| section-title-gap-xl | 24px    | 20px   |
-| section-title-gap-lg | 20px    | 16px   |
-| section-title-gap-md | 20px    | 16px   |
-| section-title-gap-sm | 16px    | 16px   |
-
----
-
-## 8 — Available Components
-
-> **All components below are exported from `@trading-game/design-intelligence-layer`.**
-> - If a component is listed → import and use it. Do NOT re-implement.
-> - If NOT listed → STOP and ask the user (see Rule 1).
-> - For props, variants, sizes, and sub-components → inspect the package's TypeScript types after installation.
-
-### Import pattern
-
-All components use the same import path:
-
-```tsx
-import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
-```
-
-### Example — composed component with sub-components
-
-```tsx
-import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose } from "@trading-game/design-intelligence-layer"
-
-<Dialog>
-  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
-  <DialogContent showCloseButton>
-    <DialogHeader>
-      <DialogTitle>Title</DialogTitle>
-      <DialogDescription>Description text.</DialogDescription>
-    </DialogHeader>
-    <div>Content here</div>
-    <DialogFooter>
-      <Button variant="primary" size="md">Confirm</Button>
-    </DialogFooter>
-  </DialogContent>
-</Dialog>
-```
-
-### Component list
-
-> **Complexity tags:** `[simple]` = drop in, one import | `[composed]` = has required sub-components | `[complex]` = has significant state/setup, ask the user first
-
-| Component | Tag | Sub-components |
-|-----------|-----|----------------|
-| Accordion | [composed] | AccordionItem, AccordionTrigger, AccordionContent |
-| Alert | [simple] | — (flat-prop API: `variant`, `layout`, `title`, `description`, `icon`, `action`, `actions`, `onDismiss`, `dismissLabel`) — **status** notifications only; for promo use `Banner` |
-| AlertDialog | [complex] | AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel, AlertDialogMedia |
-| AspectRatio | [simple] | — |
-| Avatar | [composed] | AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, AvatarGroupCount |
-| Badge | [simple] | — |
-| Banner | [simple] | — (flat-prop API: `layout`, `title`, `description`, `icon`, `action`, `actions`, `onDismiss`, `dismissLabel`, `onClick`) |
-| Breadcrumb | [composed] | BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis |
-| Button | [simple] | — |
-| Calendar | [complex] | — |
-| Card | [composed] | CardHeader, CardTitle, CardDescription, CardContent, CardFooter, CardAction |
-| Carousel | [complex] | CarouselContent, CarouselItem, CarouselPrevious, CarouselNext |
-| Chart | [complex] | ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle |
-| Checkbox | [simple] | — |
-| Chip | [simple] | — (`selected`, `disabled`, `onClick`, standard button props) — pill-shaped toggle-able selection chip. Selected: `bg-primary/[0.08]` + `text-primary`. Unselected: outline + `text-on-prominent`. |
-| Collapsible | [composed] | CollapsibleTrigger, CollapsibleContent |
-| Combobox | [complex] | ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem, ComboboxEmpty, ComboboxGroup, ComboboxLabel |
-| Command | [complex] | CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut |
-| ContextMenu | [composed] | ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuLabel, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent |
-| Dialog | [complex] | DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose |
-| DirectionProvider | [simple] | — |
-| Drawer | [complex] | DrawerTrigger, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, DrawerClose |
-| DropdownMenu | [composed] | DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, DropdownMenuShortcut |
-| Empty | [composed] | EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent |
-| Field | [complex] | FieldLabel, FieldDescription, FieldError, FieldGroup, FieldLegend, FieldSet, FieldContent, FieldTitle, FieldSeparator |
-| Form | [complex] | FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage |
-| HoverCard | [composed] | HoverCardTrigger, HoverCardContent |
-| Input | [simple] | — variants: `default`, `inverse` (dark sunken fill + white text, for use on `bg-primary` and other brand-coloured surfaces). |
-| InputGroup | [composed] | InputGroupAddon, InputGroupInput, InputGroupButton, InputGroupText, InputGroupTextarea. Variants: `default`, `inverse` (propagates to nested controls via context — addon / text / input all swap to the inverse recipe automatically). |
-| InputOTP | [composed] | InputOTPGroup, InputOTPSlot, InputOTPSeparator. Variants: OTP 4 digits, OTP 6 digits, OTP 6 split, OTP 8 digits, OTP 6 separated |
-| Item | [composed] | ItemGroup, ItemContent, ItemTitle, ItemDescription, ItemMedia, ItemActions, ItemHeader, ItemFooter, ItemSeparator |
-| Kbd | [simple] | KbdGroup |
-| Label | [simple] | — |
-| Link | [simple] | — |
-| Menubar | [complex] | MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSub, MenubarSubTrigger, MenubarSubContent, MenubarShortcut |
-| NavigationButton | [simple] | — |
-| NavigationMenu | [complex] | NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport, navigationMenuTriggerStyle |
-| NativeSelect | [simple] | NativeSelectOption, NativeSelectOptGroup |
-| Pagination | [composed] | PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis |
-| Popover | [composed] | PopoverTrigger, PopoverContent, PopoverHeader, PopoverTitle, PopoverDescription |
-| Progress | [simple] | — |
-| RadioGroup | [composed] | RadioGroupItem |
-| Resizable | [complex] | ResizablePanelGroup, ResizablePanel, ResizableHandle |
-| ScrollArea | [simple] | ScrollBar |
-| Select | [composed] | SelectTrigger (`size`: sm/md/lg, default md), SelectValue, SelectContent, SelectGroup, SelectLabel, SelectItem, SelectSeparator |
-| Separator | [simple] | — |
-| Sheet | [complex] | SheetTrigger, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, SheetClose |
-| Sidebar | [complex] | SidebarProvider, SidebarTrigger, SidebarInset, SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarRail, useSidebar |
-| Skeleton | [simple] | — |
-| Slider | [simple] | — |
-| Toast | [simple] | `Toaster`, `toast` — import both from `@trading-game/design-intelligence-layer` (the toaster wraps `sonner` internally; `toast` is re-exported so consumers don't need to import the underlying library) |
-| Spinner | [simple] | — |
-| Stepper | [simple] | — |
-| Switch | [simple] | — |
-| Table | [composed] | TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption |
-| Tabs | [composed] | TabsList (`variant`: default/line, `size`: sm/md/lg), TabsTrigger (`iconPosition`: inline/top), TabsContent. Root accepts `orientation`: horizontal/vertical. |
-| Textarea | [simple] | — |
-| TicketCard | [composed] | — (`icon`, `label`, `value`, `currency`, `stubLabel`, `onStubClick`, `stubDisabled`, `compact`) |
-| CreditTicketCard | [composed] | — (`icon`, `label`, `value`, `currency`, `stubLabel`, `onStubClick`, `stubDisabled`, `badgeIcon`, `badgeLabel`, `badgeValue`, `badgeCurrency`, `badgeInfo`, `badgeInfoSide`, `badgeInfoAlign`, `badgeInfoTitle`, `badgeInfoCloseLabel`, `compact`) — use when a Welcome credit / bonus badge must sit next to (or, on narrow widths in compact mode, below) the value |
-| Toggle | [simple] | — |
-| ToggleGroup | [composed] | ToggleGroupItem |
-| Tooltip | [composed] | TooltipTrigger, TooltipContent, TooltipProvider |
-
-### Component styling notes
-
-These are styling behaviors you can't discover from TypeScript types alone:
-
-| Component | Note |
-|-----------|------|
-| Button | `font-display font-bold`, sentence case (no `uppercase`). **Variants:** `primary` (blue fill, light surfaces), `primary-inverse` (white fill + blue text, dark/coloured surfaces), `secondary` (black outline, light surfaces), `secondary-inverse` (white outline + white text, dark/coloured surfaces), `tertiary` (text-only, black text, light surfaces — `text-on-prominent` hover `bg-secondary-hover`). **Loading state:** pass `loading` prop — button automatically renders a centred `Spinner`, hides children with `invisible` to preserve width. Do NOT manually place `<Spinner>` or "Loading" text inside the button. |
-| Card | Flat by default (no shadow). Add elevation manually: `className="shadow-sm"` |
-| Input | Resting: `border-input`. Focus: `border-ring` + `ring-[3px] ring-ring/50`. Radius: `rounded-sm` (6px). **Read-only:** pass the native `readOnly` prop — renders with `border-transparent bg-subtle/60`, `pointer-events-none` (non-interactive, non-focusable). Use to display a value that the user should not be able to edit. |
-| InputGroup | Wraps `Input` with inline addons (icons, buttons, text). **Sizes:** `sm` (h-8) / `md` (h-10, default) / `lg` (h-12) — pass `size` to `InputGroup`, it flows to `InputGroupInput` via context. **Padding:** when any `inline-start` or `inline-end` addon is present, input text gets equal `pl-2 pr-2` (8px) on both sides for visual symmetry. Without addons, Input's default `px-3`/`px-4` applies. |
-| InputOTP | **Variants:** OTP 4 digits (single group, 4 slots), OTP 6 digits (single group, 6 slots), OTP 6 split (two groups of 3 with `InputOTPSeparator`), OTP 8 digits (single group, 8 slots), OTP 6 separated (each slot in its own `InputOTPGroup` for individually spaced boxes). Slot: `h-9 w-9`, `border-border-subtle`, `rounded-sm` on first/last. Focus: `border-primary` + `ring-primary/[0.08]`. |
-| NavigationButton | Icon-only tertiary button for navigation. `text-on-prominent` (black icons), `hover:bg-secondary-hover`. **Sizes (8-point grid):** `lg` 48px / 24px icon, `md` 40px / 20px icon, `sm` 32px / 20px icon, `xs` 24px / 16px icon. States: focus `ring-ring/50`, active `opacity-60`, disabled `opacity-24`. Supports `asChild`. |
-| Tooltip | Bubble (default variant): `bg-prominent-inverse` + `text-on-prominent-inverse` (black surface, white text). `inverse` variant: `bg-prominent` + `text-on-prominent` (white surface for use over saturated coloured surfaces). Default primitive includes `max-w-xs` + `whitespace-normal` so consumers don't need to pass them. When a `Kbd` is detected inside via `:has([data-slot=kbd])`, padding bumps to `px-3.5 py-2` and siblings get `space-y-1.5` for breathing room. Always wrap in `<TooltipProvider>`. |
-| Sidebar | `SidebarHeader` / `SidebarFooter` / `SidebarGroup` use `px-layout-margin-inline py-2` (16 px horizontal via `--semantic-layout-margin-inline`), with `group-data-[collapsible=icon]:px-2` so the icon-collapsed rail tightens to 8 px. Menu buttons: `rounded-sm`. Selection: `bg-primary/10` + `text-primary` + `font-semibold`. `lg`-size buttons get `group-data-[collapsible=icon]:p-0! group-data-[collapsible=icon]:justify-center` so a 32-px brand block fills the collapsed rail and a 16-px lucide icon still centers in the same row. |
-| Breadcrumb | Active page: `text-primary font-medium`. Links: `text-on-subtle` |
-| Tabs | **Variants:** `default` (pill, `bg-tabs`) and `line` (underline, transparent bg). **Sizes:** `sm` (h-8, text-xs), `md` (h-10, text-sm, default), `lg` (h-12, text-base). **Icon position:** `inline` (default) or `top` (stacks icon above label). **Orientation:** `horizontal` (default) or `vertical` (line variant renders left-edge indicator). Hover: `bg-secondary-hover` (default) / `text-primary` (line). Selected: `bg-tabs-active` + `text-primary font-semibold`. Line variant underline: `bg-primary`. |
-| Select | **Sizes:** `SelectTrigger` accepts `size` prop: `"sm"` (h-8, text-xs) / `"md"` (h-10, text-sm, **default**) / `"lg"` (h-12, text-base) — matches `Input` and `InputGroup` height scale. Item hover: `bg-primary/[0.08]`. Selected: `text-primary font-medium` + checkmark. `SelectTrigger` also accepts `readOnly` prop: blocks interaction, retains full default appearance, chevron renders at `opacity-30`. |
-| Progress | Track: `bg-primary/20`. Indicator: `bg-primary`. Radius: `rounded-2xs` |
-| Spinner | Inherits parent text color. **Always pass `text-primary` for standalone use** |
-| Stepper | Numeric input flanked by `−` / `+` `secondary` `icon-xs` buttons. Composes `InputGroup` internally. Props: `value`, `defaultValue`, `onValueChange`, `min`, `max`, `step` (default 1), `size` (`"sm" \| "md" \| "lg"`, default `"md"`), `disabled`, `placeholder`. **Sizes:** `sm` — h-8 (32px), `icon-xs` buttons, `size-3` icons; `md` — h-10 (40px), `icon-xs` buttons, `size-3.5` icons; `lg` — h-12 (48px), `icon-sm` buttons, `size-4` icons. Matches `Input` and `InputGroup` height scale exactly. Supports controlled & uncontrolled modes, keyboard Arrow Up/Down, and floating-point steps. Default width: `w-32`. An `InputGroupText` unit label (e.g. `USDT`) can be placed in the `inline-end` addon alongside the `+` button — use `font-normal text-on-subtle` for regular weight and subtle colour. Exports `StepperSize` type. |
-| Switch | Pill track (`rounded-full`) with a circle knob (`rounded-full`). Checked track: `bg-primary`. Unchecked track: `bg-input`. Thumb is always `bg-prominent` (white) in both states. Sizes: `default` (h-6 w-11, 18 px knob) / `sm` (h-5 w-9, 14 px knob). |
-| Slider | Thumb: square `rounded-[4px]`, `bg-primary`. Track range: `bg-slider-range` |
-| Dialog/Sheet | Footer buttons should use `size="md"`. Overlay: `bg-overlay` |
-| Menubar | Hover: `bg-primary/[0.08]`. Open state: `bg-primary/10` |
-| Alert | Dismissible **status** notification. Flat-prop API — pass `title` / `description` / `icon` / `action` / `actions` / `onDismiss` directly; no sub-components. (Promotional / marketing surfaces belong on `Banner`.) **Variants:** `info` (`bg-semantic-info/10`), `warning` (`bg-semantic-warning/10`), `danger` (`bg-semantic-error/10`), `success` (`bg-semantic-win/10`). **Layouts:** `inline` (single row: icon · body · optional action · close X) and `card` (icon · body · close X top-right; up to 2 buttons at bottom-left). **Buttons:** `action` (inline, max 1) and `actions` (card, max 2). Strings get wrapped as `Button variant="secondary" size="sm"`; React elements pass through. **Title colour:** `text-on-prominent` across all variants. **Icon colour:** the variant accent (`text-semantic-info` etc.) carries the severity signal; pass `icon={null}` to omit, or any `ReactNode` to override the per-variant default (`Info`, `AlertTriangle`, `XCircle`, `CheckCircle2`). **Single-line height:** `min-h-12` (48px floor) when only `title` or only `description` is provided in inline layout; grows when content wraps on narrow viewports. **Dismiss:** controlled — `onDismiss` callback; parent owns visibility. **A11y:** `role="alert"` + `aria-live="assertive"` for `danger`/`warning`; `role="status"` + `aria-live="polite"` for `info`/`success`. |
-| Banner | Dismissible **promotional / marketing** surface — feature launches, offers, onboarding nudges, cross-promo. Single visual treatment (no severity variants); for status messages use `Alert`. Flat-prop API: `layout`, `title`, `description`, `icon`/`glyph`, `action`, `actions`, `onDismiss`, `dismissLabel`, `onClick`. **Surface:** tinted primary surface (`bg-primary/[0.08]`) with `border-primary/[0.16]` edge, `rounded-sm` (6 px — matches Card / Alert), `px-4 py-3.5`. **Layouts:** `inline` (icon · body · optional action · close X, single row) and `card` (body row + actions row beneath, bottom-left, max 2 buttons). When the body is multi-line (description set, or `layout="card"`), the grid switches to `items-start` so the leading icon top-aligns with the title; single-line banners stay `items-center`. Multi-line banners also pin the close X to `absolute top-3 right-3` and apply `pr-12` to the surface so the body never wraps under the corner. **Buttons:** strings get wrapped in `Button variant="secondary" size="sm"` across every slot (inline `action` and card `actions`). React elements pass through unchanged. **Title:** `text-sm font-bold text-on-prominent`; wrap emphasis in `<b>` for an in-line brand-blue accent (`[&>b]:text-primary`). **Description:** `text-xs font-medium text-on-subtle`, `mt-0.5` from title. **Default icon:** built-in 40 px brand-blue **square** (`rounded-xs bg-primary`, 4 px corners) with a white `Gift` glyph inside. Two ways to customise: `glyph` swaps just the inner icon while keeping the brand-badge shell intact (use this for "different symbol, same brand badge"); `icon` replaces the entire wrapper (use for fully custom artwork). `icon={null}` omits the column. `icon` wins if both are set — a dev warning fires. **`onClick`:** when set, the whole surface becomes the CTA (cursor-pointer, hover/focus states, keyboard activation). Mutually exclusive with `action`/`actions` — buttons are silently dropped and a dev warning fires. Close X stops propagation so dismissing never triggers the surface click. **A11y:** no `role`/`aria-live` (Banner is not a status surface). |
-| Badge | Variants: `default` (solid blue), `default-success`, `default-fail`, `default-warning` (all use `bg-semantic-*` + matching `text-on-semantic-*` foreground); `fill` (blue tint), `fill-success`, `fill-fail`, `fill-warning`; `fill-credit` (**frosted-glass chip** — `bg-semantic-boost-surface` = `oklch(1 0 0 / 0.22)` translucent white + `backdrop-blur-md` + `text-on-primary` white text; readable only on coloured surfaces — designed to overlay a brand-blue hero card / wallet card, matching the wallet mock's `.c-hero-wc`); `fill-demo` (red-orange tint — `bg-semantic-demo/10` + `text-semantic-demo` — dedicated to "demo account" / "test mode" flags, **not** a severity signal); `outline`; `ghost`, `ghost-success`, `ghost-fail`. Base class no longer applies `tracking-wide` — letter spacing is default. |
-| TicketCard | **Icon:** pass any `ReactNode` via `icon`. Icon container: `size-10` rounded-full, `border-2 border-primary`, `text-primary`. **Labels:** `label` (above value) and `stubLabel` (stub button) render in sentence case — do NOT apply `uppercase` or `tracking-widest`. Stub: `w-[100px]` `bg-primary` button, `text-on-primary`, shimmer sweep animation. Disabled stub: `opacity-50`, `cursor-not-allowed`. Perforation notches sit outside the card box — do NOT put `overflow-hidden` on the card wrapper. **`compact`** (default `false`): `true` = mobile layout — reduces left-content horizontal padding from `px-4 gap-4` to `px-2 gap-2`. **For Welcome credit / bonus use cases:** use `CreditTicketCard` instead — it renders a `<Badge variant="fill-credit">` next to (or below, on narrow compact widths) the value. |
-| CreditTicketCard | Same visual shell as `TicketCard` (perforation notches, tear-line, shimmer stub). The card height is **variable** (grows with content via `py-4`) rather than fixed at `h-20`. The credit is displayed as an inline `<Badge variant="fill-credit" size="sm">` formatted as *"{badgeValue} {badgeCurrency}"* (e.g. `10.00 USDT`). The badge composes optional `badgeIcon` (e.g. `<Gift />`) on the left and an info trigger on the right that opens `badgeInfo` (desktop: `Tooltip variant="inverse"`; mobile: `Drawer`). Tokens used: `bg-subtle`, `bg-primary`, `bg-primary-hover`, `text-on-primary`, `bg-semantic-boost-surface` (`#FDCA8A`), `text-on-semantic-boost` (`#521900`, bold). `compact` shrinks padding and lets the badge wrap to a second line under the value only when balance + badge would otherwise overflow into the deposit stub (responsive `flex-wrap`). |
-| Toggle | Pressed: `bg-primary/10` + `border-primary` + `text-primary` |
-| Calendar | Selected: `bg-secondary-hover` + `text-primary font-bold`. Today: primary dot below date |
-
----
-
-## 8.5 — Blocks Catalogue
-
-> Blocks are fully composed UI sections built from design system primitives. They are **exported from the package** the same as primitives — import them by name and pass data via props.
-> - **Variants** (`layout` / `mode` / `status`) live on a single block, not separate components.
-> - Each block ships with internal state where appropriate (e.g. `NavBarBlock` manages its own mobile-menu drawer).
-> - Blocks appear in the **Blocks** tab of the playground for visual reference, with the demo importing the same exports a consumer would.
-
-### `HeroBlock`
-
-Marketing hero section with two layouts.
-
-```tsx
-import { HeroBlock } from "@trading-game/design-intelligence-layer"
-
-<HeroBlock
-  layout="centered"                                       // "centered" | "split"
-  tagline={{ label: "What's new", suffix: "v2.0" }}
-  heading="Solve your customer's main problem"
-  body="One or two sentences expanding on the value prop."
-  primaryCta={{ label: "Get started" }}
-  secondaryCta={{ label: "Learn more" }}                  // split layout only
-/>
-```
-
-| Variant | Description |
-|---------|-------------|
-| `centered` (Desktop) | Centred single-column: tagline pill + heading + body + single primary CTA with `ArrowRight` icon; no image |
-| `split` (Desktop) | Two columns: tagline pill + heading + body + Get started / Learn more CTAs left; square image panel right |
-| `split` (Mobile) | Single column stacked: text content centred above, image panel full-width below |
-
-**Components used:** `Button` (default `sm`, `secondary sm`); `ArrowUpRight`, `ArrowRight` icons (lucide)
-
-**Tokens used:** `bg-prominent`, `bg-subtle`, `border-border-subtle`, `text-on-prominent`, `text-on-subtle`, `bg-semantic-win`, `rounded-xl`, `rounded-full`, `px-layout-margin-inline`, `gap-layout-gutter`, `py-24`, `text-5xl`, `font-semibold`, `font-display`, `tracking-tight`, `text-lg`, `font-body`, `text-sm`, `shadow-sm`, `max-w-2xl`
-
----
-
-### `AuthBlock`
-
-Sign-in / sign-up form. Form fields are identical between modes; `mode` drives heading, terms copy, CTA label, and the footer cross-link.
-
-```tsx
-import { AuthBlock } from "@trading-game/design-intelligence-layer"
-
-<AuthBlock
-  mode="sign-in"                                          // "sign-in" | "sign-up"
-  logoSrc="/path/to/brand-icon.svg"                       // consumer-provided
-  providers={["google", "telegram", "x"]}                 // default: all three
-  onSubmit={({ email }) => { ... }}
-  crossLinkHref="/auth/signup"
-/>
-```
-
-| Region | Content |
-|--------|---------|
-| Top | Brand logo + wordmark lockup |
-| Heading | "Sign in" / "Sign up" (mode-driven) |
-| Providers | Configurable OAuth buttons (Google, Telegram, X) |
-| Body | "or" divider + email input + terms paragraph |
-| Footer | Primary CTA + footer cross-link to the opposite mode |
-
-**Components used:** `Button`, `Input`, `Link`
-
-**Tokens used:** `text-on-prominent`, `text-on-subtle`, `bg-border-subtle`, `font-display`, `font-body`
-
----
-
-### `FAQBlock`
-
-Frequently-asked-questions section with optional help card.
-
-```tsx
-import { FAQBlock } from "@trading-game/design-intelligence-layer"
-
-<FAQBlock
-  layout="desktop"                                        // "desktop" | "mobile"
-  items={[{ value: "q1", question: "...", answer: "..." }, ...]}
-  intro={<>Optional intro paragraph with a <Link>link</Link>.</>}
-  helpCard={{ title: "Need more help?", body: "...", ctaLabel: "Contact us" }}
-/>
-```
-
-| Variant | Description |
-|---------|-------------|
-| `desktop` | `text-5xl` heading, `gap-12`, help card padding `p-8` |
-| `mobile` | `text-4xl` heading, `gap-10`, help card padding `p-6` |
-
-**Components used:** `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Button`
-
-**Tokens used:** `text-on-prominent`, `text-on-subtle`, `bg-subtle`, `font-display`, `font-body`, `rounded-xl`
-
----
-
-### `NavBarBlock`
-
-A landing page top navigation bar with internal mobile-menu state. Single component handles both desktop bar and mobile drawer.
-
-```tsx
-import { NavBarBlock } from "@trading-game/design-intelligence-layer"
-
-<NavBarBlock
-  brand={{ fullLogoSrc: "...", iconLogoSrc: "...", alt: "Brand" }}
-  links={[{ label: "Products" }, { label: "Docs" }, ...]}
-  signIn={{ onClick: ... }}
-  signUp={{ onClick: ... }}
-/>
-```
-
-| Breakpoint | Description |
-|------------|-------------|
-| Desktop (≥600 px) | Full-width bar: full logo + tertiary nav links left; Sign in (tertiary) + Sign up (primary) right |
-| Mobile — closed | Icon logo left, hamburger icon-button right |
-| Mobile — open | Stacked tertiary nav links + full-width Sign in (secondary) / Sign up (primary) below a divider |
-
-**Components used:** `Button` (variants: `tertiary`, `secondary`, default; sizes: `sm`, `icon-sm`); `Menu`, `X` icons (lucide)
-
-**Tokens used:** `bg-prominent`, `border-border-subtle`, `rounded-md`, `px-layout-margin-inline`
-
----
-
-### `HeaderNavigationBlock`
-
-A product app top header bar. Includes optional history button with overlaid numeric count badge.
-
-```tsx
-import { HeaderNavigationBlock } from "@trading-game/design-intelligence-layer"
-
-<HeaderNavigationBlock
-  onBack={() => router.back()}
-  badge={{ label: "Demo", variant: "fill-demo" }}
-  balance={{ amount: "1000.00", currency: "USDT" }}
-  history={{ count: 5, onClick: openHistorySheet }}       // count 0 hides badge; >99 shows "99+"
-  actions={<SoundToggleButton />}
-/>
-```
-
-| Region | Content |
-|--------|---------|
-| Left | `NavigationButton` (back arrow, rendered only if `onBack` provided) |
-| Centre | `Badge` (fill-warning "Demo" label) + balance amount + currency |
-| Right | History `NavigationButton` with optional numeric badge (`bg-primary`, `ring-2 ring-prominent`) + `actions` slot for additional icon buttons |
-
-**Components used:** `NavigationButton`, `Badge`; `ArrowLeft`, `History` icons (lucide)
-
-**Tokens used:** `bg-prominent`, `border-border-subtle`, `text-on-prominent`, `text-on-subtle`, `bg-primary`, `text-on-primary`, `max-w-layout-diagram-small`, `px-layout-margin-inline`
-
----
-
-### `OpenPositionsBlock`
-
-A slide-in panel listing open trading positions. Responsive — `Sheet` on desktop, `Drawer` on mobile (via `useIsMobile()`).
-
-```tsx
-import { OpenPositionsBlock, type Position } from "@trading-game/design-intelligence-layer"
-
-const positions: Position[] = [
-  { kind: "rise-fall", direction: "Rise", market: "Vol 100", duration: "30 minutes",
-    stake: "1.00 USDT", pnl: "+0.96 USDT", win: true },
-  ...
-]
-
-<OpenPositionsBlock
-  trigger={<Button variant="secondary">Active trades</Button>}
-  positions={positions}
-  sheetTitle="Positions"
-  onViewHistory={openHistoryPage}
-/>
-```
-
-Positions are a discriminated union by `kind`:
-
-| `kind` | Title rendered as | Extra fields |
-|--------|--------------------|--------------|
-| `"rise-fall"` | `direction` (e.g. "Rise" / "Fall") | — |
-| `"swipe"` | `Swipe-<direction>` (e.g. "Swipe-up") | — |
-| `"box-o"` | `"Box-O"` | `multiplier` |
-| `"digits"` | Type label (e.g. "Matches", "Under") | `type`, `digit?` |
-
-**Components used:** `Sheet`, `Drawer`, `Item`, `ItemGroup`, `ItemContent`, `ItemTitle`, `ItemActions`, `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `Button`, `NavigationButton`, `Separator`
-
-**Tokens used:** `bg-prominent`, `border-border-subtle`, `text-semantic-win`, `text-semantic-loss`, `text-on-prominent`, `text-on-subtle`
-
----
-
-### `ResultBlock`
-
-Universal end-of-round result card. Fixed-width (320 px) with animated halo + thumb illustration (bundled inline as base64) + contract/duration badges + CTA.
-
-```tsx
-import { ResultBlock } from "@trading-game/design-intelligence-layer"
-
-<ResultBlock
-  status="win"                                            // "win" | "loss"
-  amount="10,000.00"
-  currency="USDT"
-  contractLabel="Rise"
-  duration="2 hours"
-  pickedDigit={7}                                         // optional, for Digits contracts
-  ctaMode="next-round"                                    // "next-round" | "go-again" | "conversion"
-/>
-```
-
-| `ctaMode` | Renders |
-|-----------|---------|
-| `"next-round"` | Single "Next round" button |
-| `"go-again"` | Single "Go again" button |
-| `"conversion"` | "Ready to play for real?" heading + "Deposit now" + "Stay in demo" |
-
-The float / shake / halo animations are defined in `src/styles.css` and ship with the package — consumers who `@import "@trading-game/design-intelligence-layer/styles"` get them automatically.
-
-**Components used:** `Card`, `Badge` (variant `standard`), `Button`
-
-**Tokens used:** `bg-semantic-win`, `bg-semantic-loss`, `text-semantic-win`, `text-semantic-loss`, `text-on-prominent`, `bg-border-prominent/40`, `font-display`, `font-semibold`, `tabular-nums`, `tracking-tight`, `rounded-md`, `shadow-sm`
-
----
-
-### `ResultDialog`
-
-Fixed-width system dialog (title + body + two CTAs). Used for messages adjacent to `ResultBlock` like "out of balance" or "on a roll" — same width and styling, no thumb or amount.
-
-```tsx
-import { ResultDialog } from "@trading-game/design-intelligence-layer"
-
-<ResultDialog
-  title="You're out of balance."
-  body="Deposit to keep playing or stay in demo mode."
-  primaryLabel="Deposit now"
-  secondaryLabel="Stay in demo"
-/>
-```
-
-**Components used:** `Card`, `Button`
-
-**Tokens used:** `text-on-prominent`, `text-on-subtle`, `rounded-md`, `shadow-sm`
-
----
-
-## 9 — Common Mistakes
-
-| Mistake | Correct Approach |
-| ------- | ---------------- |
-| Using hardcoded hex (`#2323FF`) for primary | Use `bg-primary` or `text-primary` |
-| Using `bg-white` or `bg-black` | Use `bg-prominent` or `bg-overlay` |
-| Using `border-border` | Use `border-border-subtle` or `border-border-prominent` |
-| Using `bg-hover` | Use `bg-primary/[0.08]` or `bg-secondary-hover` |
-| Using `text-primary-foreground` | Use `text-on-primary` (the paired foreground for `bg-primary`) |
-| Using `text-on-prominent-static-inverse` for new code | Pick the paired `text-on-<surface>` for whatever surface sits behind: `text-on-primary` for `bg-primary`, `text-on-prominent-inverse` for dark inverse surfaces, `text-on-semantic-win` / `-loss` / `-warning` / `-boost` for semantic colored surfaces. The static-inverse token is kept as a deprecated alias only. |
-| Using `text-on-decorative` | Use `text-on-subtle` |
-| Using `font-mono` expecting Plus Jakarta Sans | Use `font-display` or `font-body` |
-| Using `font-bold` for headings | Use `font-semibold` (600) for headings |
-| Using `uppercase` on buttons | Buttons use sentence case (no `uppercase`) |
-| Using standard TW sizes for headings (e.g. `text-6xl` = 60px) | Use design system values (`text-6xl` = 64px in this system) |
-| Forgetting responsive heading sizes | Headings scale down on mobile (see Section 4.2) |
-| Using `rounded-[4px]` or `rounded-[2px]` | Use `rounded-xs` (4px) or `rounded-2xs` (2px) |
-| Installing `lucide-react` separately | Already bundled — import icons directly |
-| Adding `tailwind.config.js` | Tailwind v4 uses CSS config via the package |
-| Using `bg-gray-*`, `text-zinc-*`, etc. | Use semantic tokens only |
-| Using `text-gray-400` for disabled text | Use `text-on-disabled` |
-
----
-
-## 10 — Accessibility Notes
-
-1. **Primary blue text on white** (~3.0:1) — reserve for large/bold UI labels only.
-2. **Secondary text `text-on-subtle` on white** (~4.5:1) — meets WCAG AA for normal text.
-3. **Secondary text `text-on-subtle` on white** (~4.5:1) — meets WCAG AA for normal text.
-4. **Win green on white** (~5.0:1) — safe for normal text at AA.
-5. **Loss red on white** (~3.9:1) — use at 18px+ bold or pair with icons.
-6. Always pair semantic colors with **icons or labels** — never communicate meaning through color alone.
-
----
-
-## Quick Reference — Code Snippets
-
-**Primary CTA:**
-```tsx
-<Button variant="primary" size="lg">Trade Now</Button>
-```
-
-**Profit/Loss display:**
-```tsx
-<span className="text-semantic-win font-body font-semibold">+$84.00</span>
-<span className="text-semantic-loss font-body font-semibold">-$120.00</span>
-```
-
-**Heading:**
-```tsx
-<h1 className="heading-h1">Trading Game</h1>
-```
-
-**Body text:**
-```tsx
-<p className="body-md">Your portfolio summary for today.</p>
-```
-
-**Input with focus styling:**
-```tsx
-<Input type="email" placeholder="Enter your email" />
-```
-
-**Read-only input:**
-```tsx
-<Input value="Read-only value" readOnly />
-```
-
----
-
-## 11 — Release Notes
-
-### v0.17.4
-
-- **Button `tertiary` variant** — text color changed from `text-primary` (blue) to `text-on-prominent` (black). Hover changed from `bg-primary/[0.08]` to `bg-secondary-hover`. Use `tertiary-inverse` for white text on dark/coloured surfaces (unchanged).
-- **Input `readOnly` state** — native `readOnly` prop now has a distinct visual treatment: `border-transparent`, `bg-subtle/60`, `pointer-events-none`. Renders as a non-interactive display field. Clearly distinguishable from both the default (bordered) and `disabled` (faded/greyed) states.
-- **Demo page sidebar** — replaced custom `<aside>` + plain buttons with the design system `Sidebar` component (`SidebarProvider`, `SidebarMenu`, `SidebarMenuButton` with `isActive`).
-- **Demo page layout** — removed `max-w-5xl` content cap; content now uses the full available width.