@deriv-ds/design-intelligence-layer 0.1.0

package/AGENTS.md

@@ -0,0 +1,71 @@
+# AI Agent Instructions — @trading-game/design-intelligence-layer
+
+This file is read automatically by AI coding agents (Cursor, Windsurf, Claude Code, Copilot, and others) to understand how to build with this design system correctly.
+
+---
+
+## Step 1 — Read all design intelligence files first
+
+Before building any landing page, product screen, game view, or feature UI, you MUST read all four files:
+
+**Design principles** — the decision framework for every layout, hierarchy, motion, copy, and component choice:
+```
+node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md
+```
+
+**Accessibility standards** — the inclusion standard every screen must meet (WCAG 2.1 AA):
+```
+node_modules/@trading-game/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md
+```
+
+**Personas** — the three player modes (Edge Seeker, System Runner, Public Predictor) that shape all copy and UX decisions:
+```
+node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
+```
+
+**Brand voice** — channel-specific voice application, banned phrases, vocabulary reference, and formatting rules for all player-facing copy:
+```
+node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md
+```
+
+All four files apply to all projects built with this package — landing pages, product screens, and games.
+
+Run the checklists at the end of the design principles and accessibility standards files before considering any screen complete. Use the personas and brand voice to guide all player-facing copy.
+
+---
+
+## Step 2 — Read the component and token rules
+
+You MUST also follow the full agent rules file:
+
+```
+node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc
+```
+
+**Cursor users:** Copy this file into `.cursor/rules/` after every package upgrade:
+
+```bash
+cp node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc .cursor/rules/
+```
+
+---
+
+## Step 3 — Core rules summary
+
+1. **Check before building** — if a component exists in `@trading-game/design-intelligence-layer`, import it. Never re-implement it.
+2. **Tokens only** — use semantic token classes (`bg-prominent`, `text-on-prominent`, `border-border`, etc.). Never hardcode hex values, raw Tailwind palette colors, or CSS variables.
+3. **Design principles and accessibility first** — every screen must reflect the 8 design principles and meet the accessibility standards (WCAG 2.1 AA). Run both checklists before shipping.
+4. **No separate installs** — do not install `lucide-react`, `tailwindcss`, or other bundled dependencies separately.
+5. **After a version bump** — re-copy the rules file into `.cursor/rules/`, check for stale local component copies, and align them with the package.
+6. **Blocks are playground-only** — Blocks (e.g. NavBar) appear in the playground's Blocks tab but are **not** exported from the package. Do not try to import them. To build a block pattern in a consuming project, compose it manually using package components and design tokens. See `guides/design-system-guide/trading-game-ds-guide.md` Section 8.5.
+
+---
+
+## Reference
+
+- Full token + component reference: `node_modules/@trading-game/design-intelligence-layer/README.md`
+- Design principles: `node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md`
+- Accessibility standards: `node_modules/@trading-game/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md`
+- Personas: `node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md`
+- Brand voice: `node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md`
+- Full agent rules: `node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc`

package/README.md

@@ -0,0 +1,544 @@
+# Trading Game Design System
+
+A component library and design token system for the Trading Game product. Built on [shadcn/ui](https://ui.shadcn.com/) with a custom Figma-driven token architecture, Tailwind CSS v4, and React 19.
+
+Published as **`@trading-game/design-intelligence-layer`** on npm.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @trading-game/design-intelligence-layer@latest --safe-chain-skip-minimum-package-age
+```
+
+> **Note:** The `--safe-chain-skip-minimum-package-age` flag bypasses npm's 72-hour safe-chain hold on newly published packages. Required when the latest version was published less than 72 hours ago (common for AI agents and CI pipelines).
+
+### 1. Add the CSS imports
+
+In your main CSS file (e.g. `globals.css`), add these three lines **in this order**:
+
+```css
+@import "@trading-game/design-intelligence-layer/styles";
+@import "tailwindcss";
+@source "../node_modules/@trading-game/design-intelligence-layer/dist";
+```
+
+> **Why `@source`?** Tailwind v4 skips `node_modules` by default. Without this line, Tailwind won't generate CSS for the component classes. Adjust the path if your CSS file is not one level below `node_modules` (e.g. in a monorepo use `../../node_modules/...`).
+
+### 1b. Vite projects — add the Tailwind plugin
+
+If your project uses **Vite** (e.g. Vite + React), you must add the Tailwind CSS plugin to your Vite config:
+
+```bash
+npm install @tailwindcss/vite
+```
+
+```js
+// vite.config.js
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default {
+  plugins: [react(), tailwindcss()],
+}
+```
+
+> **Next.js projects** do not need this — Next.js uses PostCSS for Tailwind automatically.
+
+### 2. Fonts (handled automatically)
+
+The styles import loads **Plus Jakarta Sans** from Google Fonts automatically. No additional font setup is needed.
+
+Use `font-body`, `font-display`, or `font-sans` in your Tailwind classes — all resolve to Plus Jakarta Sans.
+
+### 3. Use components
+
+```tsx
+import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
+
+export default function App() {
+  return (
+    <Card>
+      <Button variant="primary">Trade Now</Button>
+      <Badge>Live</Badge>
+    </Card>
+  )
+}
+```
+
+### Peer dependencies
+
+Make sure these are installed in your project:
+
+```bash
+npm install react react-dom tailwindcss
+```
+
+> Requires React 18+ and Tailwind CSS v4+.
+
+---
+
+## What's inside
+
+- **54 UI components** — buttons, forms, dialogs, charts, sidebars, and more
+- **Design tokens** — CSS custom properties for color, radius, typography, and transitions synced from Figma
+- **Transition tokens** — semantic duration and easing tokens (`duration-base`, `ease-standard`, etc.) — no hardcoded `duration-200` anywhere
+- **Light-only theme** — white backgrounds, black text, primary blue accents — no dark mode
+- **Typography classes** — heading scale (h1–xs) and body scale (lg–xs) ready to use
+- **TypeScript** — full type definitions included
+- **ESM + CJS** — works with any bundler
+
+---
+
+## Available components
+
+| Component | Import |
+|---|---|
+| Accordion | `Accordion, AccordionItem, AccordionTrigger, AccordionContent` |
+| Alert | `Alert, AlertTitle, AlertDescription` |
+| Alert Dialog | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
+| Avatar | `Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup` |
+| Badge | `Badge, badgeVariants` |
+| Breadcrumb | `Breadcrumb, BreadcrumbList, BreadcrumbItem, ...` |
+| Button | `Button, buttonVariants` |
+| Calendar | `Calendar, CalendarDayButton` |
+| Card | `Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter` |
+| Carousel | `Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext` |
+| Chart | `ChartContainer, ChartTooltip, ChartLegend, ChartStyle` |
+| Checkbox | `Checkbox` |
+| Collapsible | `Collapsible, CollapsibleTrigger, CollapsibleContent` |
+| Combobox | `Combobox, ComboboxInput, ComboboxContent, ComboboxItem, ...` |
+| Command | `Command, CommandDialog, CommandInput, CommandList, ...` |
+| Context Menu | `ContextMenu, ContextMenuTrigger, ContextMenuContent, ...` |
+| Dialog | `Dialog, DialogTrigger, DialogContent, DialogHeader, ...` |
+| Drawer | `Drawer, DrawerTrigger, DrawerContent, DrawerHeader, ...` |
+| Dropdown Menu | `DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, ...` |
+| Empty State | `Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent` |
+| Field | `Field, FieldLabel, FieldDescription, FieldError, FieldGroup` |
+| Form | `Form, FormItem, FormLabel, FormControl, FormField, FormMessage` |
+| Hover Card | `HoverCard, HoverCardTrigger, HoverCardContent` |
+| Input | `Input` |
+| Input Group | `InputGroup, InputGroupAddon, InputGroupButton, InputGroupText` |
+| Input OTP | `InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator` |
+| Item | `Item, ItemMedia, ItemContent, ItemTitle, ItemDescription` |
+| Kbd | `Kbd, KbdGroup` |
+| Label | `Label` |
+| Link | `Link` |
+| Menubar | `Menubar, MenubarMenu, MenubarTrigger, MenubarContent, ...` |
+| Native Select | `NativeSelect, NativeSelectOptGroup, NativeSelectOption` |
+| Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuTrigger, ...` |
+| Pagination | `Pagination, PaginationContent, PaginationLink, ...` |
+| Popover | `Popover, PopoverTrigger, PopoverContent, PopoverAnchor` |
+| Progress | `Progress` |
+| Radio Group | `RadioGroup, RadioGroupItem` |
+| Resizable | `ResizableHandle, ResizablePanel, ResizablePanelGroup` |
+| Scroll Area | `ScrollArea, ScrollBar` |
+| Select | `Select, SelectTrigger, SelectContent, SelectItem, ...` |
+| Separator | `Separator` |
+| Sheet | `Sheet, SheetTrigger, SheetContent, SheetHeader, ...` |
+| Sidebar | `Sidebar, SidebarProvider, SidebarMenu, SidebarMenuItem, ...` |
+| Skeleton | `Skeleton` |
+| Slider | `Slider` |
+| Spinner | `Spinner` |
+| Switch | `Switch` |
+| Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` |
+| Tabs | `Tabs, TabsList, TabsTrigger, TabsContent` |
+| Textarea | `Textarea` |
+| Ticket Card | `TicketCard` |
+| Toast | `Toaster` |
+| Toggle | `Toggle, toggleVariants` |
+| Toggle Group | `ToggleGroup, ToggleGroupItem` |
+| Tooltip | `Tooltip, TooltipTrigger, TooltipContent, TooltipProvider` |
+
+---
+
+## Blocks
+
+Blocks are pre-composed UI patterns built from design system primitives. They are demonstrated in the **Blocks** tab of the development playground and are **not** exported from the npm package — import the underlying components directly if you need to use them.
+
+| Block | Variants | Description |
+|---|---|---|
+| NavBar | Desktop, Mobile (closed), Mobile (open) | Landing page top navigation bar. Logo + ghost nav links (Products, Use Cases, Docs, Blog, FAQ) + Sign in / Sign up CTAs. |
+| Hero | Type 1 (Desktop + Mobile), Type 2 | Landing page hero sections. Type 1: tagline pill + heading + body + CTAs left, image right (responsive). Type 2: centred single-column, tagline pill + heading + body + primary CTA with arrow icon, no image. |
+
+---
+
+## Button variants and sizes
+
+```tsx
+<Button variant="primary" />    // Blue filled (#2323FF) — main CTA
+<Button variant="secondary" />  // Black outline — secondary actions
+<Button variant="tertiary" />   // Text only, underline on hover — minimal
+
+// Sizes
+<Button size="lg" />      // 48px height (default)
+<Button size="md" />      // 40px height
+<Button size="sm" />      // 32px height
+<Button size="xs" />      // 24px height
+<Button size="icon-lg" /> // 48px square
+<Button size="icon-md" /> // 40px square
+<Button size="icon-sm" /> // 28px square
+<Button size="icon-xs" /> // 24px square
+```
+
+## Badge variants
+
+```tsx
+// Default (solid)
+<Badge variant="default" />         // Blue (#2323FF)
+<Badge variant="default-success" /> // Green
+<Badge variant="default-fail" />    // Red
+
+// Fill (tint background)
+<Badge variant="fill" />            // Blue tint
+<Badge variant="fill-success" />    // Green tint
+<Badge variant="fill-fail" />       // Red tint
+
+// Outline (black border, secondary-hover on hover)
+<Badge variant="outline" />
+
+// Ghost (transparent)
+<Badge variant="ghost" />
+<Badge variant="ghost-success" />
+<Badge variant="ghost-fail" />
+
+// Sizes
+<Badge size="sm" />   // 24px height
+<Badge size="md" />   // 32px height (default)
+<Badge size="lg" />   // 40px height
+```
+
+## Alert variants
+
+```tsx
+<Alert variant="info" />    // blue — informational (default)
+<Alert variant="error" />   // red — error state
+```
+
+## Component behaviour notes
+
+### AlertDialog — button fill
+`AlertDialogAction` and `AlertDialogCancel` fill the full container width **only** when `size="sm"`. On `size="default"` (the default), buttons are natural width and right-aligned.
+
+```tsx
+<AlertDialogContent size="sm">   // buttons fill width (50/50 grid)
+<AlertDialogContent size="default"> // buttons natural width, right-aligned
+```
+
+### Drawer — footer buttons
+`DrawerFooter` makes all direct child buttons fill the full width automatically via `[&>*]:w-full`. Stack your buttons inside `DrawerFooter` and they will always be full-width.
+
+### Link — size lg
+The `lg` variant of `Link` uses `text-base` (16px). The `md` and `sm` variants use `text-sm` (14px) and `text-xs` (12px) respectively.
+
+```tsx
+<Link size="lg" />  // 16px — font-base
+<Link size="md" />  // 14px — font-sm
+<Link size="sm" />  // 12px — font-xs
+```
+
+### Tabs — line variant hover
+On the `line` variant, hover state shows `text-primary` (blue) with no background fill. On the `default` (pill) variant, hover shows a grey background with `text-on-prominent`.
+
+---
+
+## Design tokens
+
+All tokens are CSS custom properties, loaded automatically via `@trading-game/design-intelligence-layer/styles`.
+
+### Background tokens
+
+| Tailwind class | CSS variable | Value | Usage |
+|---|---|---|---|
+| `bg-prominent` | `--prominent` | `#FFFFFF` | Page background |
+| `bg-card` | `--card` | `#FFFFFF` | Card/panel surface |
+| `bg-popover` | `--popover` | `#FFFFFF` | Popover/dropdown surface |
+| `bg-subtle` | `--subtle` | `#F5F5F5` | Subtle tinted surface |
+| `bg-overlay` | `--overlay` | black 50% | Modal/dialog backdrop only |
+| `bg-tabs` | `--tabs` | black 4% alpha | Tab container background (`variant="default"`) |
+| `bg-tabs-active` | `--tabs-active` | `#FFFFFF` | Active / selected tab pill |
+| `bg-primary` | `--primary` | `#2323FF` | Brand blue — CTAs |
+| `bg-primary-hover` | `--primary-hover` | `#0B0BD2` | Primary button hover (darker blue) |
+| `bg-secondary-hover` | `--secondary-hover` | `#EEEEEE` | Outline/secondary hover (light grey) |
+| `bg-semantic-win` | `--semantic-win` | green | Profit / positive state |
+| `bg-semantic-loss` | `--semantic-loss` | red | Loss / negative state |
+
+### Text tokens
+
+| Tailwind class | Value | Usage |
+|---|---|---|
+| `text-on-prominent` | `#000000` | Primary text on light backgrounds |
+| `text-on-prominent-static-inverse` | `#FFFFFF` | Always white — for text on dark/primary backgrounds |
+| `text-on-subtle` | mid grey | Secondary / supporting text |
+
+| `text-primary` | `#2323FF` | Brand blue inline text |
+| `text-semantic-win` | green | Profit / positive text |
+| `text-semantic-loss` | red | Loss / negative text |
+
+### Border & focus tokens
+
+| Tailwind class | CSS variable | Value | Usage |
+|---|---|---|---|
+| `border-border-subtle` | `--border-subtle` | `#EEEEEE` | **Default** — cards, dividers, form borders |
+| `border-border-prominent` | `--border-prominent` | `#000000` | Outline variant components (button, badge, toggle) |
+| `border-border` | `--border` | `#EEEEEE` | @deprecated alias — prefer `border-border-subtle` |
+| `border-input` | `--input` | `#EEEEEE` | Input field borders |
+| `ring-ring` | `--ring` | `#2323FF` | Focus rings |
+
+> ⚠️ **`border-border` vs `border-border-subtle`:** Both resolve to the same light grey `#EEEEEE`. `border-border` is kept for backward compatibility. **Prefer `border-border-subtle` in all new code.**
+
+### Transition tokens
+
+Duration — primitive scale:
+
+| Tailwind class | CSS variable | Value | Used for |
+|---|---|---|---|
+| `duration-instant` | `--primitive-duration-instant` | `50ms` | Focus rings, hover tints |
+| `duration-fast` | `--primitive-duration-fast` | `100ms` | Buttons, inputs, badges |
+| `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 — primitive scale:
+
+| Tailwind class | CSS variable | Value | Used for |
+|---|---|---|---|
+| `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 |
+
+> Always use token utilities — never raw `duration-200` or `ease-in-out` directly.
+
+### Other tokens
+
+| Tailwind class | Value | Usage |
+|---|---|---|
+| `bg-slider-range` | blue 40% | Slider filled range |
+| `rounded-lg` | `0.625rem` | Base border radius |
+
+### Using opacity with tokens
+
+Opacity on tokens is allowed and encouraged:
+
+```
+✅ bg-primary/20           → blue at 20% opacity
+✅ border-border-subtle/50 → light grey border at 50% opacity
+✅ ring-ring/10            → ring at 10% opacity
+
+❌ bg-black/50             → NOT a token, use bg-overlay instead
+❌ bg-white                → NOT a token, use bg-prominent or bg-card
+```
+
+### Primitive alpha scales
+
+For structured alpha surfaces, the design system ships two internal alpha primitive scales. These are **CSS variables only** — not exposed as Tailwind utility classes. Always reference them via a semantic token, never directly in components.
+
+```
+--primitive-mono-alpha-4  through --primitive-mono-alpha-80   (black at N%)
+--primitive-blue-alpha-4  through --primitive-blue-alpha-80   (brand blue at N%)
+Stops: 4 · 8 · 16 · 24 · 32 · 40 · 50 · 64 · 80
+```
+
+Example — how `--tabs` uses the alpha scale:
+```css
+--tabs: var(--primitive-mono-alpha-4); /* black at 4% — tab container background */
+```
+
+> `--primitive-black-50` is deprecated. It now aliases `--primitive-mono-alpha-50`. The `--overlay` semantic token is unaffected.
+
+---
+
+## Typography
+
+The styles export includes pre-built typography classes using **Plus Jakarta Sans**.
+
+### Heading scale (Semibold 600 · tracking 1.5px · uppercase)
+
+| Class | Size / Line height |
+|---|---|
+| `heading-h1` | 72px / 72px |
+| `heading-h2` | 64px / 64px |
+| `heading-h3` | 48px / 48px |
+| `heading-h4` | 40px / 40px |
+| `heading-xs` | 24px / 24px |
+
+### Body scale (Semibold 600)
+
+| Class | Size / Line height |
+|---|---|
+| `body-lg` | 18px / 28px |
+| `body-md` | 16px / 24px |
+| `body-sm` | 12px / 16px |
+| `body-xs` | 8px / 12px |
+
+### Font utilities
+
+| Tailwind class | Font |
+|---|---|
+| `font-display` | Plus Jakarta Sans — headings, display text |
+| `font-body` or `font-sans` | Plus Jakarta Sans — body text |
+
+---
+
+## Upgrading the design system
+
+When you bump `@trading-game/design-intelligence-layer` and run `npm install` (or `npm ci`):
+
+| How you use the package | What happens |
+|-------------------------|----------------|
+| You **import** components only from `@trading-game/design-intelligence-layer` | After install and a rebuild, your app uses the **new** implementations in `node_modules/.../dist` — buttons, cards, etc. reflect the version you installed. |
+| You **copied** `components/ui/*` (or similar) into your repo | Those files **do not** auto-update. You must delete them and switch to package imports, or manually merge changes from the new package. |
+
+**Overrides:** Passing large `className` strings onto DS components can mask new defaults (e.g. old radius after a “pill button” update). After upgrading, review those callsites.
+
+**Cursor / AI agents:** The package ships agent rules at `node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc`. Cursor does **not** load rules from `node_modules` by default — **re-copy** that file into `.cursor/rules/` after each upgrade so instructions match the release (same command as in **AI Agent Setup** below). The rules include **Rule 7 — Package version upgrades**: agents should search for duplicated components, align with the package, and **tell you explicitly** if local component code was replaced.
+
+---
+
+## AI Agent Setup
+
+### All AI tools (Cursor, Windsurf, Claude Code, Copilot, and others)
+
+The package ships an `AGENTS.md` file that most AI tools read automatically. After installing the package, copy it to your project root:
+
+```bash
+cp node_modules/@trading-game/design-intelligence-layer/AGENTS.md ./AGENTS.md
+```
+
+This tells any AI agent to:
+1. Read the design principles before building any screen
+2. Follow the component and token rules
+3. Run the 7-point checklist before completing any view
+
+**Design principles file** (bundled in the package):
+```
+node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md
+```
+
+**Accessibility standards file** (bundled in the package):
+```
+node_modules/@trading-game/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md
+```
+
+**Personas file** (bundled in the package):
+```
+node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
+```
+
+**Brand voice** (bundled in the package):
+```
+node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md
+```
+
+All four files apply to all projects built with this package — landing pages, product screens, and games. Every AI agent must read all of them before starting any build. Run the design principles and accessibility checklists before completing any screen. Use the personas and brand voice to guide all player-facing copy.
+
+### Cursor
+
+Copy the included rule file into your project:
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc .cursor/rules/
+```
+
+Re-run this **`cp` after every design-system version bump** so your workspace rules stay in sync with the installed package.
+
+### Claude Code
+
+Add the following to your project's `CLAUDE.md`:
+
+```markdown
+## Design System
+
+This project uses @trading-game/design-intelligence-layer. Before writing any UI:
+1. Read node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md — apply the 8 principles and run the 7-point checklist on every screen
+2. Read node_modules/@trading-game/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md — apply WCAG 2.1 AA standards and run the 9-point accessibility checklist on every screen
+3. Read node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md — understand the 3 player modes (Edge Seeker, System Runner, Public Predictor) that shape all copy and UX
+4. Read node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md — apply the brand voice: channel-specific voice, banned phrases, vocabulary, and formatting rules for all player-facing copy
+5. Check if the component exists in the package — import it, don't re-implement
+6. Use only design token classes (bg-prominent, text-on-prominent, border-border-subtle, etc.) — no hardcoded hex or raw Tailwind palette colors
+7. Do not install lucide-react, tailwindcss, or other bundled dependencies separately
+8. If no token exists for a value, ask before using a hardcoded value
+9. After upgrading the package: prefer package imports over local copies of components; if replacing local UI code with the package version, tell the user what was overwritten; re-copy guides/rules/design-system-consuming-project.mdc into .cursor/rules if using Cursor
+
+See node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc for full rules.
+See node_modules/@trading-game/design-intelligence-layer/README.md for complete token and component reference.
+```
+
+---
+
+## Common mistakes
+
+| Wrong | Right | Why |
+|---|---|---|
+| `bg-gray-100` | `bg-subtle` | Raw Tailwind palette — use tokens |
+| `bg-white` | `bg-prominent` or `bg-card` | Not a semantic token |
+| `text-white` | `text-on-prominent-static-inverse` | Use the semantic inverse token |
+| `text-black` | `text-on-prominent` | Not a semantic token |
+| `bg-black/50` | `bg-overlay` | Overlay has its own token |
+| `bg-[#2323FF]` | `bg-primary` | Hardcoded hex — use token |
+| `border-border` | `border-border-subtle` | Old name — prefer the new explicit name |
+| `bg-[var(--primary)]` | `bg-primary` | Raw CSS var — Tailwind v4 maps tokens directly |
+| `hsl(var(--primary))` | `bg-primary` | Tailwind v3 syntax — not needed in v4 |
+| Installing `lucide-react` | Already bundled | Icons are included in the package |
+
+---
+
+## Do NOT install separately
+
+These are bundled with the package. Installing them separately can cause version conflicts:
+
+- `lucide-react` — icon library
+- `radix-ui` — headless primitives
+- `class-variance-authority` — variant API
+- `cmdk` — command palette
+- `vaul` — drawer
+- `sonner` — toast
+- `recharts` — charts
+- `react-day-picker` — calendar
+- `embla-carousel-react` — carousel
+- `react-resizable-panels` — resizable panels
+
+---
+
+## Development (contributors only)
+
+```bash
+# Clone
+git clone https://github.com/trading-game/TG-design-system.git
+cd TG-design-system
+
+# Install dependencies
+npm install
+
+# Start dev server (Next.js component playground)
+npm run dev
+
+# Build the library (ESM + CJS + types)
+npm run build
+
+# Build the Next.js showcase app
+npm run build:next
+```
+
+### Updating design tokens
+
+Design tokens are managed in Figma and exported as CSS variables. To update:
+
+1. Update the CSS custom properties in `app/globals.css` (playground) and `src/styles.css` (published package)
+2. Update `guides/rules/design-system-consuming-project.mdc` to reflect any token renames
+3. Update this README's token tables
+
+---
+
+## Tech stack
+
+- **React 19** + **TypeScript**
+- **Tailwind CSS v4** — CSS-first configuration
+- **shadcn/ui** (New York style) — base component primitives
+- **Radix UI** — accessible headless primitives
+- **Figma** — source of truth for design tokens