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

package/{docs → guides}/design-principles/trading-game-design-principles.md

@@ -2,11 +2,11 @@
 
 *High-level product design guidance for designers and AI agents*
 
-Version 1.0 · March 2026
+Version 1.1 · April 2026 · *Updated to align with Product Vision & Strategy*
 
 ---
 
-trading.game makes trading feel faster, simpler, and more exciting — without losing the confidence and seriousness that financial products require. These principles define the design personality of the product and guide how AI agents apply components, layouts, motion, copy, and brand assets. This is not a style guide. It is a decision framework — giving AI enough direction to design with the right taste, energy, and priorities without over-constraining creativity.
+trading.game makes trading feel intuitive, fun, and exciting — without losing the confidence and seriousness that financial products require. These principles define the design personality of the product and guide how AI agents apply components, layouts, motion, copy, and brand assets. These principles are rooted in the [trading.game Product Vision & Strategy](trading-game-product-vision.md) and should be read alongside it. This is not a style guide. It is a decision framework — giving AI enough direction to design with the right taste, energy, and priorities without over-constraining creativity.
 
 ---
 
@@ -28,11 +28,11 @@ Every screen should make trading feel central. Game mechanics, rewards, and visu
 
 ---
 
-### 2. Simple by default
+### 2. Intuitive by default
 
-Complexity must be absorbed by the interface, not pushed onto the user. The product should feel easy to enter, easy to scan, and easy to act on.
+Complexity must be absorbed by the interface, not pushed onto the user. The product should feel natural to navigate, quick to scan, and obvious to act on. Trading is never simple when real money is at stake — but the experience of trading can be intuitive.
 
-*Agent guidance:* Reduce visible choices, sequence decisions clearly, and reveal more only when needed. Make the next step obvious.
+*Agent guidance:* Reduce visible choices, sequence decisions clearly, and reveal more only when needed. Make the next step obvious. Never hide complexity — make it make sense.
 
 ---
 
@@ -94,4 +94,5 @@ Run this before completing any screen or feature.
 - [ ] Energy comes from the experience, not decoration
 - [ ] Serious information is treated seriously
 - [ ] A first-time user would understand this without instructions
+- [ ] The platform layer feels trustworthy enough to deposit real money
 - [ ] One pattern was reused before a new one was invented

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

@@ -0,0 +1,602 @@
+# 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) |
+
+### 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).
+
+### 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>
+```
+
+---
+
+## 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 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-subtle`) 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-background` + `text-primary font-semibold`. Line variant underline: `bg-primary`. |
+| Select | Item hover: `bg-primary/[0.08]`. Selected: `text-primary font-medium` + checkmark |
+| 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.7",
   "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": {