@trading-game/design-system-playground 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +433 -0
  2. package/dist/index.cjs +6666 -0
  3. package/dist/index.cjs.map +1 -0
  4. package/dist/index.d.cts +592 -0
  5. package/dist/index.d.ts +592 -0
  6. package/dist/index.js +6344 -0
  7. package/dist/index.js.map +1 -0
  8. package/package.json +84 -0
  9. package/rules/design-system-consuming-project.mdc +126 -0
  10. package/src/styles.css +276 -0
package/README.md ADDED
@@ -0,0 +1,433 @@
1
+ # Trading Game Design System
2
+
3
+ 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.
4
+
5
+ Published as **`@trading-game/design-system-playground`** on npm.
6
+
7
+ ---
8
+
9
+ ## Quick Start
10
+
11
+ ## Installation
12
+
13
+ ```bash
14
+ npm install @trading-game/design-system-playground@latest --safe-chain-skip-minimum-package-age
15
+ ```
16
+
17
+ > **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).
18
+
19
+
20
+ ### 1. Add the CSS imports
21
+
22
+ In your main CSS file (e.g. `globals.css`), add these three lines **in this order**:
23
+
24
+ ```css
25
+ @import "@trading-game/design-system-playground/styles";
26
+ @import "tailwindcss";
27
+ @source "../node_modules/@trading-game/design-system-playground/dist";
28
+ ```
29
+
30
+ > **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/...`).
31
+
32
+ ### 1b. Vite projects — add the Tailwind plugin
33
+
34
+ If your project uses **Vite** (e.g. Vite + React), you must add the Tailwind CSS plugin to your Vite config:
35
+
36
+ ```bash
37
+ npm install @tailwindcss/vite
38
+ ```
39
+
40
+ ```js
41
+ // vite.config.js
42
+ import react from '@vitejs/plugin-react'
43
+ import tailwindcss from '@tailwindcss/vite'
44
+
45
+ export default {
46
+ plugins: [react(), tailwindcss()],
47
+ }
48
+ ```
49
+
50
+ > **Next.js projects** do not need this — Next.js uses PostCSS for Tailwind automatically.
51
+
52
+ ### 2. Add `class="dark"` to your `<html>` tag
53
+
54
+ The design system defaults to dark mode. Your root layout must include this:
55
+
56
+ ```html
57
+ <html class="dark">
58
+ ```
59
+
60
+ Without this class, components will render without the dark theme applied.
61
+
62
+ ### 3. Fonts (handled automatically)
63
+
64
+ The styles import loads **Barlow** (body) and **Orbitron** (display/headings) from Google Fonts automatically. No additional font setup is needed.
65
+
66
+ Use `font-body` for Barlow and `font-display` for Orbitron in your Tailwind classes.
67
+
68
+ ### 4. Use components
69
+
70
+ ```tsx
71
+ import { Button, Card, Badge } from "@trading-game/design-system-playground"
72
+
73
+ export default function App() {
74
+ return (
75
+ <Card>
76
+ <Button variant="primary">Trade Now</Button>
77
+ <Badge>Live</Badge>
78
+ </Card>
79
+ )
80
+ }
81
+ ```
82
+
83
+ ### Peer dependencies
84
+
85
+ Make sure these are installed in your project:
86
+
87
+ ```bash
88
+ npm install react react-dom tailwindcss
89
+ ```
90
+
91
+ > Requires React 18+ and Tailwind CSS v4+.
92
+
93
+ ---
94
+
95
+ ## What's inside
96
+
97
+ - **53 UI components** — buttons, forms, dialogs, charts, sidebars, and more
98
+ - **Design tokens** — CSS custom properties for color, radius, and typography synced from Figma
99
+ - **Typography classes** — heading scale (h1–xs) and body scale (lg–xs) ready to use
100
+ - **Dark mode** — dark theme by default, light mode via `class="light"`
101
+ - **TypeScript** — full type definitions included
102
+ - **ESM + CJS** — works with any bundler
103
+
104
+ ---
105
+
106
+ ## Available components
107
+
108
+ | Component | Import |
109
+ |---|---|
110
+ | Accordion | `Accordion, AccordionItem, AccordionTrigger, AccordionContent` |
111
+ | Alert | `Alert, AlertTitle, AlertDescription` |
112
+ | Alert Dialog | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
113
+ | Avatar | `Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup` |
114
+ | Badge | `Badge, badgeVariants` |
115
+ | Breadcrumb | `Breadcrumb, BreadcrumbList, BreadcrumbItem, ...` |
116
+ | Button | `Button, buttonVariants` |
117
+ | Calendar | `Calendar, CalendarDayButton` |
118
+ | Card | `Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter` |
119
+ | Carousel | `Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext` |
120
+ | Chart | `ChartContainer, ChartTooltip, ChartLegend, ChartStyle` |
121
+ | Checkbox | `Checkbox` |
122
+ | Collapsible | `Collapsible, CollapsibleTrigger, CollapsibleContent` |
123
+ | Combobox | `Combobox, ComboboxInput, ComboboxContent, ComboboxItem, ...` |
124
+ | Command | `Command, CommandDialog, CommandInput, CommandList, ...` |
125
+ | Context Menu | `ContextMenu, ContextMenuTrigger, ContextMenuContent, ...` |
126
+ | Dialog | `Dialog, DialogTrigger, DialogContent, DialogHeader, ...` |
127
+ | Drawer | `Drawer, DrawerTrigger, DrawerContent, DrawerHeader, ...` |
128
+ | Dropdown Menu | `DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, ...` |
129
+ | Empty State | `Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent` |
130
+ | Field | `Field, FieldLabel, FieldDescription, FieldError, FieldGroup` |
131
+ | Form | `Form, FormItem, FormLabel, FormControl, FormField, FormMessage` |
132
+ | Hover Card | `HoverCard, HoverCardTrigger, HoverCardContent` |
133
+ | Input | `Input` |
134
+ | Input Group | `InputGroup, InputGroupAddon, InputGroupButton, InputGroupText` |
135
+ | Input OTP | `InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator` |
136
+ | Item | `Item, ItemMedia, ItemContent, ItemTitle, ItemDescription` |
137
+ | Kbd | `Kbd, KbdGroup` |
138
+ | Label | `Label` |
139
+ | Menubar | `Menubar, MenubarMenu, MenubarTrigger, MenubarContent, ...` |
140
+ | Native Select | `NativeSelect, NativeSelectOptGroup, NativeSelectOption` |
141
+ | Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuTrigger, ...` |
142
+ | Pagination | `Pagination, PaginationContent, PaginationLink, ...` |
143
+ | Popover | `Popover, PopoverTrigger, PopoverContent, PopoverAnchor` |
144
+ | Progress | `Progress` |
145
+ | Radio Group | `RadioGroup, RadioGroupItem` |
146
+ | Resizable | `ResizableHandle, ResizablePanel, ResizablePanelGroup` |
147
+ | Scroll Area | `ScrollArea, ScrollBar` |
148
+ | Select | `Select, SelectTrigger, SelectContent, SelectItem, ...` |
149
+ | Separator | `Separator` |
150
+ | Sheet | `Sheet, SheetTrigger, SheetContent, SheetHeader, ...` |
151
+ | Sidebar | `Sidebar, SidebarProvider, SidebarMenu, SidebarMenuItem, ...` |
152
+ | Skeleton | `Skeleton` |
153
+ | Slider | `Slider` |
154
+ | Spinner | `Spinner` |
155
+ | Switch | `Switch` |
156
+ | Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` |
157
+ | Tabs | `Tabs, TabsList, TabsTrigger, TabsContent` |
158
+ | Textarea | `Textarea` |
159
+ | Toast | `Toaster` |
160
+ | Toggle | `Toggle, toggleVariants` |
161
+ | Toggle Group | `ToggleGroup, ToggleGroupItem` |
162
+ | Tooltip | `Tooltip, TooltipTrigger, TooltipContent, TooltipProvider` |
163
+
164
+ ---
165
+
166
+ ## Button variants and sizes
167
+
168
+ ```tsx
169
+ // Cyan family
170
+ <Button variant="primary" /> // cyan filled — main CTA
171
+ <Button variant="secondary" /> // cyan outline — secondary action
172
+ <Button variant="tertiary" /> // cyan text — minimal
173
+
174
+ // Sizes
175
+ <Button size="lg" /> // 48px height (default)
176
+ <Button size="md" /> // 40px height
177
+ <Button size="sm" /> // 32px height
178
+ <Button size="xs" /> // 24px height
179
+ <Button size="icon-lg" /> // 48px square
180
+ <Button size="icon-md" /> // 40px square
181
+ <Button size="icon-sm" /> // 28px square
182
+ <Button size="icon-xs" /> // 24px square
183
+ ```
184
+
185
+ ## Badge variants
186
+
187
+ ```tsx
188
+ // Default (solid) — 5 colors
189
+ <Badge /> // cyan (default)
190
+ <Badge variant="default-amber" /> // amber
191
+ <Badge variant="default-purple" /> // purple
192
+ <Badge variant="default-success" /> // green
193
+ <Badge variant="default-fail" /> // red
194
+
195
+ // Fill (tint) — 5 colors
196
+ <Badge variant="fill" /> // cyan tint
197
+ <Badge variant="fill-amber" /> // amber tint
198
+ <Badge variant="fill-purple" /> // purple tint
199
+ <Badge variant="fill-success" /> // green tint
200
+ <Badge variant="fill-fail" /> // red tint
201
+
202
+ // Ghost (transparent) — 5 colors
203
+ <Badge variant="ghost" /> // cyan text
204
+ <Badge variant="ghost-amber" /> // amber text
205
+ <Badge variant="ghost-purple" /> // purple text
206
+ <Badge variant="ghost-success" /> // green text
207
+ <Badge variant="ghost-fail" /> // red text
208
+
209
+ // Sizes (8pt grid)
210
+ <Badge size="sm" /> // 24px height
211
+ <Badge size="md" /> // 32px height (default)
212
+ <Badge size="lg" /> // 40px height
213
+ ```
214
+
215
+ ## Alert variants
216
+
217
+ ```tsx
218
+ <Alert variant="info" /> // blue — informational (default)
219
+ <Alert variant="error" /> // red — error state
220
+ ```
221
+
222
+ ---
223
+
224
+ ## Design tokens
225
+
226
+ All tokens are CSS custom properties, loaded automatically via `@trading-game/design-system-playground/styles`.
227
+
228
+ ### Color tokens
229
+
230
+ | Token class | CSS variable | Value | Usage |
231
+ |---|---|---|---|
232
+ | `bg-background` | `--background` | `#020B0A` | Page background |
233
+ | `bg-card` | `--card` | `#06000F` | Card/panel background |
234
+ | `bg-popover` | `--popover` | `#0A1A1E` | Elevated surfaces |
235
+ | `bg-muted` | `--muted` | `#0A1A1E` | Muted surfaces |
236
+ | `bg-primary` | `--primary` | `#2323FF` | Brand primary blue — CTAs |
237
+ | `bg-primary-hover` | `--primary-hover` | `#1A1ACC` | Primary hover state |
238
+ | `bg-secondary` | `--secondary` | `#FFB800` @ 4% | Amber tint background |
239
+ | `bg-secondary-hover` | `--secondary-hover` | `#FFB800` | Amber full |
240
+ | `bg-hover` | `--hover` | cyan @ 12% | Interactive hover background |
241
+ | `bg-overlay` | `--overlay` | black @ 50% | Modal/dialog backdrop |
242
+ | `bg-destructive` | `--destructive` | `#FF3355` | Destructive actions |
243
+ | `bg-brand-accent` | `--brand-accent` | `#FF6600` | Accent orange |
244
+ | `bg-brand-accent-hover` | `--brand-accent-hover` | `#D45200` | Accent orange hover |
245
+
246
+ ### Text tokens
247
+
248
+ | Token class | Value | Usage |
249
+ |---|---|---|
250
+ | `text-on-prominent` | `#D5EEE8` | Primary text |
251
+ | `text-on-subtle` | `#7AA8AE` | Paragraphs, descriptions, labels |
252
+ | `text-on-muted` | `#295B60` | Low-emphasis text |
253
+ | `text-on-decorative` | `#101E25` | Decorative/dark-on-dark text |
254
+ | `text-primary-foreground` | `#020B0A` | Text on primary backgrounds |
255
+ | `text-semantic-win` | `#00FF9F` | Positive/profit |
256
+ | `text-semantic-loss` | `#FF3355` | Negative/loss |
257
+ | `text-semantic-warning` | `#FF8C00` | Warning state |
258
+
259
+ ### Border & focus tokens
260
+
261
+ | Token class | Value | Usage |
262
+ |---|---|---|
263
+ | `border-border` | `#0F2830` | Default borders/dividers |
264
+ | `ring-ring` | `#2323FF` | Focus ring |
265
+ | `border-input` | `#0F2830` | Input borders |
266
+
267
+ ### Other tokens
268
+
269
+ | Token class | Value | Usage |
270
+ |---|---|---|
271
+ | `bg-accent` | `#0A1A1E` | UI interaction surface |
272
+ | `bg-accent-hover` | darker | Accent hover |
273
+ | `bg-badge-rank` | `#A040FF` | Violet — badge/rank accent |
274
+ | `bg-slider-range` | cyan @ 40% | Slider/switch filled range |
275
+ | `bg-overlay` | black @ 50% | Modal/dialog backdrop |
276
+ | `rounded-lg` | `0.625rem` | Base border radius |
277
+
278
+ ### Using opacity with tokens
279
+
280
+ Opacity on tokens is allowed and encouraged:
281
+
282
+ ```
283
+ ✅ bg-primary/20 → cyan at 20% opacity
284
+ ✅ border-border/50 → border at 50% opacity
285
+ ✅ ring-primary/10 → ring at 10% opacity
286
+
287
+ ❌ bg-black/50 → NOT a token, use bg-overlay instead
288
+ ```
289
+
290
+ ---
291
+
292
+ ## Typography
293
+
294
+ The styles export includes pre-built typography classes:
295
+
296
+ ### Heading scale (Orbitron · Semibold · tracking 1.5px · uppercase)
297
+
298
+ | Class | Size |
299
+ |---|---|
300
+ | `heading-h1` | 72px |
301
+ | `heading-h2` | 64px |
302
+ | `heading-h3` | 48px |
303
+ | `heading-h4` | 40px |
304
+ | `heading-xs` | 24px |
305
+
306
+ ### Body scale (Barlow · Semibold)
307
+
308
+ | Class | Size / Line height |
309
+ |---|---|
310
+ | `body-lg` | 18px / 28px |
311
+ | `body-md` | 16px / 24px |
312
+ | `body-sm` | 12px / 16px |
313
+ | `body-xs` | 8px / 12px |
314
+
315
+ ### Font utilities
316
+
317
+ | Tailwind class | Font |
318
+ |---|---|
319
+ | `font-display` | Orbitron — headings, display text |
320
+ | `font-body` or `font-sans` | Barlow — body text (default) |
321
+
322
+ ---
323
+
324
+ ## AI Agent Setup
325
+
326
+ ### Cursor
327
+
328
+ Copy the included rule file into your project:
329
+
330
+ ```bash
331
+ mkdir -p .cursor/rules
332
+ cp node_modules/@trading-game/design-system-playground/rules/design-system-consuming-project.mdc .cursor/rules/
333
+ ```
334
+
335
+ ### Claude Code
336
+
337
+ Add the following to your project's `CLAUDE.md`:
338
+
339
+ ```markdown
340
+ ## Design System
341
+
342
+ This project uses @trading-game/design-system-playground. Before writing any UI:
343
+ 1. Check if the component exists in the package — import it, don't re-implement
344
+ 2. Use only design token classes (bg-background, text-on-prominent, etc.) — no hardcoded hex or raw Tailwind palette colors
345
+ 3. Do not install lucide-react, tailwindcss, or other bundled dependencies separately
346
+ 4. If no token exists for a value, ask before using a hardcoded value
347
+
348
+ See node_modules/@trading-game/design-system-playground/rules/design-system-consuming-project.mdc for full rules.
349
+ See node_modules/@trading-game/design-system-playground/README.md for complete token and component reference.
350
+ ```
351
+
352
+ ### What the rules enforce
353
+
354
+ - **Check the package first** before writing any custom UI element
355
+ - **Use only design token classes** — no hardcoded hex, no raw Tailwind palette colors, no raw `var()` wrappers like `bg-[var(--token)]`
356
+ - **Don't re-install** bundled dependencies (lucide-react, tailwindcss, etc.)
357
+ - **Ask before proceeding** if no token exists for a value needed
358
+
359
+ ---
360
+
361
+ ## Common mistakes
362
+
363
+ | Wrong | Right | Why |
364
+ |---|---|---|
365
+ | `bg-gray-900` | `bg-background` | Raw Tailwind palette — use tokens |
366
+ | `text-white` | `text-on-prominent` | Not a semantic token |
367
+ | `bg-black/50` | `bg-overlay` | Overlay has its own token |
368
+ | `bg-[#2323FF]` | `bg-primary` | Hardcoded hex — use token |
369
+ | `bg-[var(--primary)]` | `bg-primary` | Raw CSS var — Tailwind v4 maps tokens directly |
370
+ | `hsl(var(--primary))` | `bg-primary` | Tailwind v3 syntax — not needed in v4 |
371
+ | Installing `lucide-react` | Already bundled | Icons are included in the package |
372
+
373
+ ---
374
+
375
+ ## Do NOT install separately
376
+
377
+ These are bundled with the package. Installing them separately can cause version conflicts:
378
+
379
+ - `lucide-react` — icon library
380
+ - `radix-ui` — headless primitives
381
+ - `class-variance-authority` — variant API
382
+ - `cmdk` — command palette
383
+ - `vaul` — drawer
384
+ - `sonner` — toast
385
+ - `recharts` — charts
386
+ - `react-day-picker` — calendar
387
+ - `embla-carousel-react` — carousel
388
+ - `react-resizable-panels` — resizable panels
389
+
390
+ ---
391
+
392
+ ## Further reading
393
+
394
+ - [trading-game-ds-guide.md](trading-game-ds-guide.md) — comprehensive AI-readable guide with all 876 Figma tokens, full component catalogue, and detailed usage rules
395
+
396
+ ---
397
+
398
+ ## Development (contributors only)
399
+
400
+ ```bash
401
+ # Clone
402
+ git clone https://github.com/trading-game/design-team-playground.git
403
+ cd design-team-playground
404
+
405
+ # Install dependencies
406
+ npm install
407
+
408
+ # Start dev server (Next.js component playground)
409
+ npm run dev
410
+
411
+ # Build the library (ESM + CJS + types)
412
+ npm run build
413
+
414
+ # Build the Next.js showcase app
415
+ npm run build:next
416
+ ```
417
+
418
+ ### Updating design tokens
419
+
420
+ Design tokens are managed in Figma and exported as JSON variables. To update:
421
+
422
+ 1. Export updated variables from Figma (TailwindCSS.json, Theme.json, Mode.json)
423
+ 2. Update the CSS custom properties in `app/globals.css` and `src/styles.css`
424
+
425
+ ---
426
+
427
+ ## Tech stack
428
+
429
+ - **React 19** + **TypeScript**
430
+ - **Tailwind CSS v4** — CSS-first configuration
431
+ - **shadcn/ui** (New York style) — base component primitives
432
+ - **Radix UI** — accessible headless primitives
433
+ - **Figma** — source of truth for design tokens