@trading-game/design-intelligence-layer 0.8.5 → 0.8.8

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

@@ -0,0 +1,642 @@
+# 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-background, bg-card, bg-popover, bg-subtle, bg-overlay
+  ✅ text-on-prominent, text-on-subtle, text-on-muted
+  ✅ 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                     |
+| ---------------- | ---------------- | ------------------------- |
+| `--background`   | `bg-background`  | 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 |
+| `--primary-hover`     | `bg-primary-hover`  | Hover & pressed states on primary elements |
+
+### 2.3 — Semantic (Trading Status)
+
+| CSS Variable         | Tailwind Class          | Usage                     |
+| -------------------- | ----------------------- | ------------------------- |
+| `--semantic-win`     | `text-semantic-win` / `bg-semantic-win`     | Win / Profit / Positive outcomes |
+| `--semantic-loss`    | `text-semantic-loss` / `bg-semantic-loss`   | Loss / Negative outcomes  |
+| `--semantic-warning` | `text-semantic-warning` / `bg-semantic-warning` | Warning / Caution / Non-destructive alerts |
+| `--semantic-info`    | `text-semantic-info` / `bg-semantic-info`   | Informational alerts      |
+
+> 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
+
+| CSS Variable                    | Tailwind Class                          | Usage                     |
+| ------------------------------- | --------------------------------------- | ------------------------- |
+| `--on-prominent`                | `text-on-prominent`                     | Primary text (headings, body) |
+| `--on-prominent-static-inverse` | `text-on-prominent-static-inverse`      | Always-white text (e.g. on primary blue buttons) |
+| `--on-subtle`                   | `text-on-subtle`                        | Secondary text (descriptions, labels) |
+| `--on-muted`                    | `text-on-muted`                         | Tertiary text (subtle labels, placeholders) |
+
+### 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         |
+| Color a tab container background       | `bg-tabs`                         | `bg-subtle` for tabs                   |
+| Color an active/selected tab           | `bg-tabs-active`                  | `bg-background` for active tab         |
+| Color a page background                | `bg-background`                   | `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-muted`                   | `text-on-subtle` for the subtlest text |
+| 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 white text on a dark surface     | `text-on-prominent-static-inverse`| `text-white` or raw white hex          |
+
+---
+
+## 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                   |
+| ----------- | ---------------------- | ---------------------------------- | ----------------------------------- | ----------------------- |
+| `primary`   | `bg-primary`           | `text-on-prominent-static-inverse` | none                                | `bg-primary-hover`      |
+| `secondary` | transparent            | `text-on-prominent`                | `border-[1.5px] border-border-prominent` | `bg-secondary-hover`    |
+| `tertiary`  | transparent            | `text-primary`                     | none                                | `bg-primary/[0.08]`     |
+
+### 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-50`, `pointer-events-none`, `data-loading`, `aria-busy` |
+| Disabled | `opacity-50`, `pointer-events-none`              |
+
+---
+
+## 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 | [composed] | AlertTitle, AlertDescription |
+| AlertDialog | [complex] | AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel, AlertDialogMedia |
+| AspectRatio | [simple] | — |
+| Avatar | [composed] | AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, AvatarGroupCount |
+| Badge | [simple] | — |
+| 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] | — |
+| 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] | — |
+| InputGroup | [composed] | InputGroupAddon, InputGroupInput, InputGroupButton, InputGroupText, InputGroupTextarea |
+| InputOTP | [composed] | InputOTPGroup, InputOTPSlot, InputOTPSeparator |
+| 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 |
+| 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, 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] | — |
+| Sonner (Toaster) | [simple] | — (also import `toast` from `sonner`) |
+| Spinner | [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] | — |
+| 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`). Primary: `text-on-prominent-static-inverse`. Tertiary hover: `bg-primary/[0.08]` |
+| 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) |
+| Tooltip | Bubble: `bg-primary` + `text-on-prominent-static-inverse` (not `bg-popover`). Always wrap in `<TooltipProvider>` |
+| Sidebar | Menu buttons use `rounded-sm`. Selection: `bg-secondary-hover` + `text-primary` + `font-semibold` |
+| 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 | Item hover: `bg-primary/[0.08]`. Selected: `text-primary font-medium` + checkmark. `SelectTrigger` 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** |
+| Switch | Checked track: `bg-slider-range`. Checked thumb: `bg-primary` |
+| 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` |
+| Toggle | Pressed: `bg-primary/10` + `border-primary` + `text-primary` |
+| Calendar | Selected: `bg-secondary-hover` + `text-primary font-bold`. Today: primary dot below date |
+
+---
+
+## 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-background` 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-prominent-static-inverse` |
+| Using `text-on-decorative` | Use `text-on-muted` |
+| 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 |
+
+---
+
+## 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. **Tertiary text `text-on-muted` on white** (~7.0:1) — safe for all sizes.
+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" />
+```

package/{docs → guides}/rules/design-system-consuming-project.mdc

@@ -199,7 +199,7 @@ When the user asks to **update**, **upgrade**, or **install the latest** `@tradi
 3. **Notify on replace** — If you **delete, replace, or substantially overwrite** local component code to match the package, **stop and tell the user clearly**, e.g.  
    `Aligned [ComponentName] with @trading-game/design-intelligence-layer@[version]. Previous local behavior or classes: [short summary]. Re-apply needs via package variants/props, tokens, or a thin wrapper only if product requires it.`
 4. **Review `className` overrides** — Parent apps often pass `className` on DS components. Old overrides (radius, colors, shadows) can **hide** new defaults (e.g. pill buttons). After upgrade, scan for overrides on DS components and trim or adjust them when they conflict with the new design.
-5. **Refresh Cursor rules** — The package ships `docs/rules/design-system-consuming-project.mdc`. Cursor does **not** read it from `node_modules` automatically. Tell the user to re-copy it (see README **AI Agent Setup → Cursor**) so agent instructions match the release.
+5. **Refresh Cursor rules** — The package ships `guides/rules/design-system-consuming-project.mdc`. Cursor does **not** read it from `node_modules` automatically. Tell the user to re-copy it (see README **AI Agent Setup → Cursor**) so agent instructions match the release.
 6. **Tailwind** — Confirm `@source` still points at `node_modules/@trading-game/design-intelligence-layer/dist` so Tailwind v4 emits classes from the updated bundle.
 
 ### Do not assume

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trading-game/design-intelligence-layer",
-  "version": "0.8.5",
+  "version": "0.8.8",
   "description": "Trading Game Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,7 +34,7 @@
   "files": [
     "dist/",
     "src/styles.css",
-    "docs/",
+    "guides/",
     "AGENTS.md"
   ],
   "publishConfig": {