@deriv-ds/design-intelligence-layer 0.2.0 → 0.3.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 (14) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +350 -144
  3. package/dist/index.cjs +2815 -1449
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +169 -73
  6. package/dist/index.d.ts +169 -73
  7. package/dist/index.js +2608 -1238
  8. package/dist/index.js.map +1 -1
  9. package/guides/brand-voice/deriv-brand-voice.md +250 -0
  10. package/guides/design-system-guide/{trading-game-ds-guide.md → deriv-design-intelligence-guide.md} +5 -5
  11. package/guides/design-system-guide/quill-ds-guide.md +817 -0
  12. package/package.json +1 -1
  13. package/src/styles.css +840 -14
  14. package/guides/brand-voice/trading-game-brand-voice.md +0 -325
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # Trading Game Design System
1
+ # Quill Design System
2
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.
3
+ A component library and design token system built on [shadcn/ui](https://ui.shadcn.com/) with a custom Figma-driven token architecture, Tailwind CSS v4, and React 19.
4
4
 
5
5
  Published as **`@deriv-ds/design-intelligence-layer`** on npm.
6
6
 
@@ -50,9 +50,9 @@ export default {
50
50
 
51
51
  ### 2. Fonts (handled automatically)
52
52
 
53
- The styles import loads **Plus Jakarta Sans** from Google Fonts automatically. No additional font setup is needed.
53
+ The styles import loads **Inter** from Google Fonts automatically (weights 300–800). No additional font setup is needed.
54
54
 
55
- Use `font-body`, `font-display`, or `font-sans` in your Tailwind classes — all resolve to Plus Jakarta Sans.
55
+ Use `font-body`, `font-display`, or `font-sans` in your Tailwind classes — all resolve to Inter. Use `font-mono` for code (Red Hat Mono).
56
56
 
57
57
  ### 3. Use components
58
58
 
@@ -62,7 +62,7 @@ import { Button, Card, Badge } from "@deriv-ds/design-intelligence-layer"
62
62
  export default function App() {
63
63
  return (
64
64
  <Card>
65
- <Button variant="primary">Trade Now</Button>
65
+ <Button variant="primary">Get Started</Button>
66
66
  <Badge>Live</Badge>
67
67
  </Card>
68
68
  )
@@ -84,10 +84,12 @@ npm install react react-dom tailwindcss
84
84
  ## What's inside
85
85
 
86
86
  - **54 UI components** — buttons, forms, dialogs, charts, sidebars, and more
87
- - **Design tokens** — CSS custom properties for color, radius, typography, and transitions synced from Figma
88
- - **Transition tokens** — semantic duration and easing tokens (`duration-base`, `ease-standard`, etc.) — no hardcoded `duration-200` anywhere
89
- - **Light-only theme** — white backgrounds, black text, primary blue accents — no dark mode
90
- - **Typography classes** — heading scale (h1–xs) and body scale (lg–xs) ready to use
87
+ - **Design tokens** — three-layer architecture (primitives → foundation semantics → component tokens) synced from Figma
88
+ - **Light + Dark themes** — toggle `.dark` on `<html>` to switch; every semantic token has a paired override
89
+ - **Inter typography** — heading (mega → h6) and body (xl → xs) scales ready to use
90
+ - **17 colour ramps** — slate, blue, sapphire, blueberry, grape, magenta, cherry, coral, red, orange, yellow, mustard, green, emerald, tiffany, teal, seawater
91
+ - **Transition tokens** — semantic duration (`duration-fast`, `duration-base`, etc.) and easing (`ease-standard`, `ease-enter`, etc.) — no hardcoded `duration-200`
92
+ - **Elevation scale** — five composed `box-shadow` shorthands (`--elevation-100` through `--elevation-500`) that auto-adapt to the active theme
91
93
  - **TypeScript** — full type definitions included
92
94
  - **ESM + CJS** — works with any bundler
93
95
 
@@ -98,10 +100,7 @@ npm install react react-dom tailwindcss
98
100
  | Component | Import |
99
101
  |---|---|
100
102
  | Accordion | `Accordion, AccordionItem, AccordionTrigger, AccordionContent` |
101
- | Alert | `Alert, AlertTitle, AlertDescription` |
102
- | Alert Dialog | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
103
103
  | Avatar | `Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup` |
104
- | Badge | `Badge, badgeVariants` |
105
104
  | Breadcrumb | `Breadcrumb, BreadcrumbList, BreadcrumbItem, ...` |
106
105
  | Button | `Button, buttonVariants` |
107
106
  | Calendar | `Calendar, CalendarDayButton` |
@@ -109,12 +108,14 @@ npm install react react-dom tailwindcss
109
108
  | Carousel | `Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext` |
110
109
  | Chart | `ChartContainer, ChartTooltip, ChartLegend, ChartStyle` |
111
110
  | Checkbox | `Checkbox` |
111
+ | Chip | `Chip, chipVariants` |
112
112
  | Collapsible | `Collapsible, CollapsibleTrigger, CollapsibleContent` |
113
113
  | Combobox | `Combobox, ComboboxInput, ComboboxContent, ComboboxItem, ...` |
114
114
  | Command | `Command, CommandDialog, CommandInput, CommandList, ...` |
115
115
  | Context Menu | `ContextMenu, ContextMenuTrigger, ContextMenuContent, ...` |
116
116
  | Dialog | `Dialog, DialogTrigger, DialogContent, DialogHeader, ...` |
117
- | Drawer | `Drawer, DrawerTrigger, DrawerContent, DrawerHeader, ...` |
117
+ | Direction | `DirectionProvider, useDirection` |
118
+ | Drawer | `Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, DrawerClose` |
118
119
  | Dropdown Menu | `DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, ...` |
119
120
  | Empty State | `Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent` |
120
121
  | Field | `Field, FieldLabel, FieldDescription, FieldError, FieldGroup` |
@@ -122,33 +123,35 @@ npm install react react-dom tailwindcss
122
123
  | Hover Card | `HoverCard, HoverCardTrigger, HoverCardContent` |
123
124
  | Input | `Input` |
124
125
  | Input Group | `InputGroup, InputGroupAddon, InputGroupButton, InputGroupText` |
125
- | Input OTP | `InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator` |
126
126
  | Item | `Item, ItemMedia, ItemContent, ItemTitle, ItemDescription` |
127
127
  | Kbd | `Kbd, KbdGroup` |
128
128
  | Label | `Label` |
129
129
  | Link | `Link` |
130
- | Menubar | `Menubar, MenubarMenu, MenubarTrigger, MenubarContent, ...` |
130
+ | Loading Spinner | `LoadingSpinner` |
131
+ | Modal | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
131
132
  | Native Select | `NativeSelect, NativeSelectOptGroup, NativeSelectOption` |
132
133
  | Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuTrigger, ...` |
134
+ | OTP Field | `CodeInput, CodeInputGroup, CodeInputSlot, CodeInputSeparator` |
133
135
  | Pagination | `Pagination, PaginationContent, PaginationLink, ...` |
134
136
  | Popover | `Popover, PopoverTrigger, PopoverContent, PopoverAnchor` |
135
137
  | Progress | `Progress` |
136
138
  | Radio Group | `RadioGroup, RadioGroupItem` |
137
139
  | Resizable | `ResizableHandle, ResizablePanel, ResizablePanelGroup` |
138
140
  | Scroll Area | `ScrollArea, ScrollBar` |
141
+ | Section Message | `SectionMessage, SectionMessageTitle, SectionMessageDescription` |
139
142
  | Select | `Select, SelectTrigger, SelectContent, SelectItem, ...` |
140
143
  | Separator | `Separator` |
141
144
  | Sheet | `Sheet, SheetTrigger, SheetContent, SheetHeader, ...` |
142
145
  | Sidebar | `Sidebar, SidebarProvider, SidebarMenu, SidebarMenuItem, ...` |
143
146
  | Skeleton | `Skeleton` |
144
147
  | Slider | `Slider` |
145
- | Spinner | `Spinner` |
146
148
  | Switch | `Switch` |
149
+ | Tab | `Tab, TabList, TabTrigger, TabContent` |
147
150
  | Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` |
148
151
  | Tabs | `Tabs, TabsList, TabsTrigger, TabsContent` |
152
+ | Tag | `Tag, tagVariants` |
149
153
  | Textarea | `Textarea` |
150
154
  | Ticket Card | `TicketCard` |
151
- | Toast | `Toaster` |
152
155
  | Toggle | `Toggle, toggleVariants` |
153
156
  | Toggle Group | `ToggleGroup, ToggleGroupItem` |
154
157
  | Tooltip | `Tooltip, TooltipTrigger, TooltipContent, TooltipProvider` |
@@ -157,7 +160,7 @@ npm install react react-dom tailwindcss
157
160
 
158
161
  ## Blocks
159
162
 
160
- 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.
163
+ Blocks are pre-composed UI patterns built from Quill 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.
161
164
 
162
165
  | Block | Variants | Description |
163
166
  |---|---|---|
@@ -168,54 +171,85 @@ Blocks are pre-composed UI patterns built from design system primitives. They ar
168
171
 
169
172
  ## Button variants and sizes
170
173
 
174
+ The brand colour is **coral `#FF444F`** (`--primitive-coral-700`). Hover darkens to `#E12E3A` (coral-800), pressed to `#C41C28` (coral-900).
175
+
171
176
  ```tsx
172
- <Button variant="primary" /> // Blue filled (#2323FF) — main CTA
173
- <Button variant="secondary" /> // Black outline — secondary actions
174
- <Button variant="tertiary" /> // Text only, underline on hover — minimal
177
+ <Button variant="primary" /> // Coral filled (#FF444F) — main CTA, white text
178
+ <Button variant="secondary" /> // 1.5px outline (slate-1200 / white in dark) — secondary actions
179
+ <Button variant="tertiary" /> // Filled neutral surface (slate-100 / slate-1000 in dark)
180
+ <Button variant="ghost" /> // Transparent, hover tint only
181
+
182
+ // Theme tone modifiers (per variant): normal · inverse · static-light · static-dark
183
+ // e.g. <Button variant="primary" tone="static-light" />
184
+
185
+ // Sizes (height · font-size · min-width)
186
+ <Button size="lg" /> // 48px · 18px · 96px min, 20px padding-x
187
+ <Button size="md" /> // 40px · 16px · 80px min, 16px padding-x (default)
188
+ <Button size="sm" /> // 32px · 14px · 64px min, 12px padding-x
189
+
190
+ // Icon-only sizes (square)
191
+ <Button size="icon-lg" /> // 48 × 48 — icon 24px
192
+ <Button size="icon-md" /> // 40 × 40 — icon 20px
193
+ <Button size="icon-sm" /> // 32 × 32 — icon 16px
194
+ ```
195
+
196
+ All sizes use a fully pill-shaped border (`border-radius: 999px`).
197
+
198
+ ## Badge variants
199
+
200
+ ```tsx
201
+ // Status fills (solid backgrounds, white text)
202
+ <Badge variant="number" /> // Red (#C40000 light · #FF4D4D dark)
203
+ <Badge variant="red" /> // Status red
204
+ <Badge variant="yellow" /> // Status yellow (#C47D00 / #FFBE4D)
205
+ <Badge variant="green" /> // Status green (#007A22 / #4DBC6B)
206
+ <Badge variant="blue" /> // Status info blue (#0777C4 / #53B9FF)
175
207
 
176
208
  // Sizes
177
- <Button size="lg" /> // 48px height (default)
178
- <Button size="md" /> // 40px height
179
- <Button size="sm" /> // 32px height
180
- <Button size="xs" /> // 24px height
181
- <Button size="icon-lg" /> // 48px square
182
- <Button size="icon-md" /> // 40px square
183
- <Button size="icon-sm" /> // 28px square
184
- <Button size="icon-xs" /> // 24px square
209
+ <Badge size="sm" /> // 20px height · 12px font · 8px dot
210
+ <Badge size="md" /> // 24px height · 14px font · 16px dot
185
211
  ```
186
212
 
187
- ## Badge variants
213
+ Badges are pill-shaped (`border-radius: 999px`).
214
+
215
+ ## Tag variants
216
+
217
+ Tags are 4px-radius chips for filtering, metadata, and categorisation. Two visual styles — outline and fill — across five tones.
188
218
 
189
219
  ```tsx
190
- // Default (solid)
191
- <Badge variant="default" /> // Blue (#2323FF)
192
- <Badge variant="default-success" /> // Green
193
- <Badge variant="default-fail" /> // Red
220
+ <Tag tone="neutral" /> // slate (default)
221
+ <Tag tone="red" />
222
+ <Tag tone="yellow" />
223
+ <Tag tone="green" />
224
+ <Tag tone="blue" />
225
+
226
+ <Tag variant="outline" /> // border + text, transparent fill
227
+ <Tag variant="fill" /> // tinted background (red @ 8%, etc.)
194
228
 
195
- // Fill (tint background)
196
- <Badge variant="fill" /> // Blue tint
197
- <Badge variant="fill-success" /> // Green tint
198
- <Badge variant="fill-fail" /> // Red tint
229
+ // Sizes
230
+ <Tag size="sm" /> // 24px · 12px font · 16px icon · 4px gap
231
+ <Tag size="md" /> // 32px · 14px font · 18px icon · 8px gap
232
+ ```
199
233
 
200
- // Outline (black border, secondary-hover on hover)
201
- <Badge variant="outline" />
234
+ ## Section message variants
202
235
 
203
- // Ghost (transparent)
204
- <Badge variant="ghost" />
205
- <Badge variant="ghost-success" />
206
- <Badge variant="ghost-fail" />
236
+ ```tsx
237
+ <SectionMessage variant="default" /> // Neutral grey tint
238
+ <SectionMessage variant="information" /> // Blue tint + info icon
239
+ <SectionMessage variant="success" /> // Green tint + check icon
240
+ <SectionMessage variant="warning" /> // Yellow tint + alert icon
241
+ <SectionMessage variant="danger" /> // Red tint + danger icon
207
242
 
208
243
  // Sizes
209
- <Badge size="sm" /> // 24px height
210
- <Badge size="md" /> // 32px height (default)
211
- <Badge size="lg" /> // 40px height
244
+ <SectionMessage size="sm" /> // 14px message · 16px title · 20px icon
245
+ <SectionMessage size="md" /> // 16px message · 18px title · 22px icon
212
246
  ```
213
247
 
214
248
  ## Alert variants
215
249
 
216
250
  ```tsx
217
- <Alert variant="info" /> // blue — informational (default)
218
- <Alert variant="error" /> // red — error state
251
+ <Alert variant="info" /> // blue (#0777C4 / #53B9FF) — informational (default)
252
+ <Alert variant="error" /> // red (#C40000 / #FF4D4D) — error state
219
253
  ```
220
254
 
221
255
  ## Component behaviour notes
@@ -231,6 +265,18 @@ Blocks are pre-composed UI patterns built from design system primitives. They ar
231
265
  ### Drawer — footer buttons
232
266
  `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.
233
267
 
268
+ ### Drawer — handle bar (bottom direction)
269
+ When `direction="bottom"`, `DrawerContent` renders a handle bar at the top that follows the `component-bottom-sheet` design tokens:
270
+
271
+ | Property | Token | Value |
272
+ |---|---|---|
273
+ | Container height | `--bottom-sheet-size-height-handle-container` | 32px |
274
+ | Container bg (default) | `--bottom-sheet-bg-handle-default` | `slate-50` / `slate-1100` |
275
+ | Bar height | `--bottom-sheet-size-height-handle-bar` | 4px |
276
+ | Bar width | `--bottom-sheet-size-width-handle-bar` | 40px |
277
+ | Bar color | `--bottom-sheet-bg-handle-bar` | `black-alpha-300` / `white-alpha-300` |
278
+ | Bar radius | `--bottom-sheet-size-radius-handle-bar` | 999 (pill) |
279
+
234
280
  ### Link — size lg
235
281
  The `lg` variant of `Link` uses `text-base` (16px). The `md` and `sm` variants use `text-sm` (14px) and `text-xs` (12px) respectively.
236
282
 
@@ -241,54 +287,197 @@ The `lg` variant of `Link` uses `text-base` (16px). The `md` and `sm` variants u
241
287
  ```
242
288
 
243
289
  ### Tabs — line variant hover
244
- 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`.
290
+ On the `line` variant, hover state shows `text-utility-brand` (coral `#FF444F`) with no background fill. On the `default` (pill) variant, hover shows a slate-tinted background with `text-prominent`.
291
+
292
+ Tab sizes:
293
+
294
+ | Size | Min height | Min width | Padding-x | Font size |
295
+ |---|---|---|---|---|
296
+ | `sm` | 32px | 72px | 12px | 14px |
297
+ | `md` | 40px | 80px | 16px | 16px |
298
+ | `lg` | 48px | 96px | 20px | 18px |
245
299
 
246
300
  ---
247
301
 
248
302
  ## Design tokens
249
303
 
250
- All tokens are CSS custom properties, loaded automatically via `@deriv-ds/design-intelligence-layer/styles`.
304
+ All tokens are CSS custom properties, loaded automatically via `@deriv-ds/design-intelligence-layer/styles`. Tokens follow a three-layer architecture:
305
+
306
+ 1. **Primitives** (`--primitive-*`) — raw colour ramps, alpha scales, durations, easings. Never reference directly.
307
+ 2. **Foundation semantics** (`--background-*`, `--text-*`, `--border-*`, `--icon-*`, `--elevation-*`) — paired between `:root` (light) and `.dark` (dark).
308
+ 3. **Component tokens** (`--button-*`, `--field-*`, `--tag-*`, `--badge-*`, etc.) — derived from foundation semantics.
309
+
310
+ ### Theme switching
311
+
312
+ Toggle dark mode by adding `.dark` to the `<html>` element:
313
+
314
+ ```html
315
+ <html class="dark"> <!-- or remove .dark for light mode -->
316
+ ```
317
+
318
+ Every semantic token has a paired light/dark value, so component code never needs theme-aware conditionals.
251
319
 
252
320
  ### Background tokens
253
321
 
254
- | Tailwind class | CSS variable | Value | Usage |
322
+ | Tailwind class | CSS variable | Light | Dark | Usage |
323
+ |---|---|---|---|---|
324
+ | `bg-primary-canvas` | `--background-primary-canvas` | `#F6F7F8` | `#181C25` | Page / app canvas |
325
+ | `bg-secondary-canvas` | `--background-secondary-canvas` | `#FFFFFF` | `#181C25` | Alternate canvas |
326
+ | `bg-primary-surface` | `--background-primary-surface` | `#FFFFFF` | `#20242F` | Cards, panels, default surface |
327
+ | `bg-secondary-surface` | `--background-secondary-surface` | `#F6F7F8` | `#20242F` | Subtle / nested surface |
328
+ | `bg-overlay` | `--overlay` | black 50% | black 50% | Modal / dialog / drawer backdrop |
329
+ | `bg-tabs` | `--tabs` | slate @ 4% | white @ 4% | Tab container background (`variant="default"`) |
330
+ | `bg-tabs-active` | `--tabs-active` | `#FFFFFF` | `#11141B` | Active / selected tab pill |
331
+ | `bg-primary` | `--primary` | `#FF444F` | `#FF444F` | Brand coral — CTAs (same in both themes) |
332
+ | `bg-primary-hover` | `--primary-hover` | `#E12E3A` | `#E12E3A` | Primary button hover (coral-800) |
333
+ | `bg-secondary-hover` | `--secondary-hover` | secondary-surface | secondary-surface | Outline / secondary hover tint |
334
+ | `bg-slider-range` | `--slider-range` | coral @ 40% | coral @ 40% | Slider filled range |
335
+
336
+ #### Status backgrounds (24% tints)
337
+
338
+ | Tailwind class | Light | Dark | Usage |
255
339
  |---|---|---|---|
256
- | `bg-prominent` | `--prominent` | `#FFFFFF` | Page background |
257
- | `bg-card` | `--card` | `#FFFFFF` | Card/panel surface |
258
- | `bg-popover` | `--popover` | `#FFFFFF` | Popover/dropdown surface |
259
- | `bg-subtle` | `--subtle` | `#F5F5F5` | Subtle tinted surface |
260
- | `bg-overlay` | `--overlay` | black 50% | Modal/dialog backdrop only |
261
- | `bg-tabs` | `--tabs` | black 4% alpha | Tab container background (`variant="default"`) |
262
- | `bg-tabs-active` | `--tabs-active` | `#FFFFFF` | Active / selected tab pill |
263
- | `bg-primary` | `--primary` | `#2323FF` | Brand blue — CTAs |
264
- | `bg-primary-hover` | `--primary-hover` | `#0B0BD2` | Primary button hover (darker blue) |
265
- | `bg-secondary-hover` | `--secondary-hover` | `#EEEEEE` | Outline/secondary hover (light grey) |
266
- | `bg-semantic-win` | `--semantic-win` | green | Profit / positive state |
267
- | `bg-semantic-loss` | `--semantic-loss` | red | Loss / negative state |
340
+ | `bg-success-default` | green @ 24% | green @ 24% | Positive / win state surface |
341
+ | `bg-error-default` | red @ 24% | red @ 24% | Negative / loss state surface |
342
+ | `bg-warning-default` | yellow @ 24% | yellow @ 24% | Caution surface |
343
+ | `bg-information-default` | blue @ 24% | blue @ 24% | Informational surface |
344
+
345
+ #### Interaction tints (state layers)
346
+
347
+ | Tailwind class | Light | Dark | Usage |
348
+ |---|---|---|---|
349
+ | `bg-hover-default` | slate @ 8% | white @ 8% | Hover state layer |
350
+ | `bg-pressed-default` | slate @ 16% | white @ 16% | Pressed state layer |
351
+ | `bg-selected-default` | slate @ 8% | white @ 8% | Selected state layer |
352
+
353
+ > Each interaction tint also ships in `inverse`, `static-light`, and `static-dark` flavours (e.g. `bg-hover-static-light`) for placement on themed surfaces.
268
354
 
269
355
  ### Text tokens
270
356
 
271
- | Tailwind class | Value | Usage |
357
+ | Tailwind class | Light | Dark | Usage |
358
+ |---|---|---|---|
359
+ | `text-prominent` | `#181C25` | `#FFFFFF` | Primary on-canvas text |
360
+ | `text-subtle` | slate @ 48% | white @ 48% | Secondary / supporting text |
361
+ | `text-disabled-default` | slate @ 16% | white @ 16% | Disabled labels |
362
+ | `text-prominent-inverse` | `#FFFFFF` | `#181C25` | Text on inverse surfaces |
363
+ | `text-prominent-static-dark` | `#FFFFFF` | `#FFFFFF` | Always white (text on coloured fills) |
364
+ | `text-prominent-static-light` | `#181C25` | `#181C25` | Always slate (text on light fills) |
365
+
366
+ #### Status text
367
+
368
+ | Tailwind class | Light | Dark | Usage |
369
+ |---|---|---|---|
370
+ | `text-success-default` | `#007A22` | `#4DBC6B` | Profit / positive |
371
+ | `text-error-default` | `#C40000` | `#FF4D4D` | Loss / negative |
372
+ | `text-warning-default` | `#C47D00` | `#FFBE4D` | Caution |
373
+ | `text-information-default` | `#0777C4` | `#53B9FF` | Informational |
374
+
375
+ #### Utility text (brand & account modes)
376
+
377
+ | Tailwind class | Value (both themes) | Usage |
272
378
  |---|---|---|
273
- | `text-on-prominent` | `#000000` | Primary text on light backgrounds |
274
- | `text-on-prominent-static-inverse` | `#FFFFFF` | Always white — for text on dark/primary backgrounds |
275
- | `text-on-subtle` | mid grey | Secondary / supporting text |
379
+ | `text-utility-brand` | `#FF444F` (coral-700) | Brand-tinted inline text |
380
+ | `text-utility-real` | `#00C390` (emerald-700) | Real-account indicator |
381
+ | `text-utility-demo` | `#F55F0A` (orange-700) | Demo-account indicator |
382
+
383
+ > The `*-inverse`, `*-static-light`, and `*-static-dark` variants exist for every status token and follow the same theme-pairing rules as `text-prominent`.
384
+
385
+ ### Border tokens
276
386
 
277
- | `text-primary` | `#2323FF` | Brand blue inline text |
278
- | `text-semantic-win` | green | Profit / positive text |
279
- | `text-semantic-loss` | red | Loss / negative text |
387
+ | Tailwind class | CSS variable | Light | Dark | Usage |
388
+ |---|---|---|---|---|
389
+ | `border-default` | `--border-default-default` | slate @ 16% | white @ 16% | Default global border (used by `*` selector) |
390
+ | `border-subtle-default` | `--border-subtle-default` | slate @ 8% | white @ 8% | Cards, dividers, panels |
391
+ | `border-prominent-default` | `--border-prominent-default` | slate @ 16% | white @ 16% | Heavier dividers |
392
+ | `border-selected` | `--border-selected-default` | `#181C25` | `#FFFFFF` | Selected state borders (chip, list-item) |
393
+ | `border-disabled-default` | `--border-disabled-default` | slate @ 8% | white @ 8% | Disabled component borders |
394
+ | `border-input` | `--input` | slate @ 8% | white @ 8% | Input field borders (alias of border-subtle) |
395
+ | `border-border` | `--border` | slate @ 8% | white @ 8% | @deprecated alias — prefer `border-subtle-default` |
396
+ | `ring-ring` | `--ring` | `#FF444F` | `#FF444F` | Focus rings (brand coral) |
280
397
 
281
- ### Border & focus tokens
398
+ #### Status borders
399
+
400
+ | Tailwind class | Light | Dark |
401
+ |---|---|---|
402
+ | `border-success-default` | `#007A22` | `#4DBC6B` |
403
+ | `border-error-default` | `#C40000` | `#FF4D4D` |
404
+ | `border-warning-default` | `#C47D00` | `#FFBE4D` |
405
+ | `border-information-default` | `#0777C4` | `#53B9FF` |
282
406
 
283
- | Tailwind class | CSS variable | Value | Usage |
407
+ > ⚠️ **`border-border` is deprecated.** It now aliases `--border-subtle-default` for backward compatibility. Prefer `border-subtle-default` in all new code.
408
+
409
+ ### Icon tokens
410
+
411
+ Icons follow the same `prominent / subtle / disabled / status / utility` taxonomy as text:
412
+
413
+ | Tailwind class | Light | Dark | Usage |
284
414
  |---|---|---|---|
285
- | `border-border-subtle` | `--border-subtle` | `#EEEEEE` | **Default** — cards, dividers, form borders |
286
- | `border-border-prominent` | `--border-prominent` | `#000000` | Outline variant components (button, badge, toggle) |
287
- | `border-border` | `--border` | `#EEEEEE` | @deprecated alias — prefer `border-border-subtle` |
288
- | `border-input` | `--input` | `#EEEEEE` | Input field borders |
289
- | `ring-ring` | `--ring` | `#2323FF` | Focus rings |
415
+ | `text-icon-prominent` (via `--icon-prominent-default`) | `#181C25` | `#FFFFFF` | Default icon colour |
416
+ | `text-icon-subtle` | slate @ 48% | white @ 48% | Secondary icons |
417
+ | `text-icon-disabled` | slate @ 16% | white @ 16% | Disabled icons |
418
+ | `text-icon-success` | `#007A22` | `#4DBC6B` | Success icons |
419
+ | `text-icon-error` | `#C40000` | `#FF4D4D` | Error icons |
420
+ | `text-icon-warning` | `#C47D00` | `#FFBE4D` | Warning icons |
421
+ | `text-icon-information` | `#0777C4` | `#53B9FF` | Info icons |
422
+ | `text-icon-utility-brand` | `#FF444F` | `#FF444F` | Brand-tinted icon |
423
+ | `text-icon-utility-real` | `#00C390` | `#00C390` | Real-account icon |
424
+ | `text-icon-utility-demo` | `#F55F0A` | `#F55F0A` | Demo-account icon |
425
+
426
+ Icon component sizes:
427
+
428
+ | Size | Width × height | Flag width × height |
429
+ |---|---|---|
430
+ | `sm` | 16 × 16 | 24 × 16 |
431
+ | `md` | 20 × 20 | 30 × 20 |
432
+ | `lg` | 24 × 24 | 36 × 24 |
433
+
434
+ ### Elevation tokens
435
+
436
+ Five composed `box-shadow` shorthands. Defined once in `:root` — `.dark` swaps only the layer colours, so a single `--elevation-*` reference works in both themes.
437
+
438
+ | Token | Layer 1 (y / blur) | Layer 2 | Layer 3 | Used for |
439
+ |---|---|---|---|---|
440
+ | `--elevation-100` | 1 / 2 | — | — | Base raise (chips, segmented control segments) |
441
+ | `--elevation-200` | 1 / 2 | 2 / 6 | — | Inputs, low cards |
442
+ | `--elevation-300` | 1 / 2 | 4 / 12 | 8 / 24 | Menus, tooltips, popovers |
443
+ | `--elevation-400` | 2 / 4 | 8 / 24 | 16 / 48 | Notifications, snackbars, banner |
444
+ | `--elevation-500` | 4 / 8 | 16 / 48 | 32 / 96 | Bottom sheets, dialogs |
445
+
446
+ Layer colours: black @ 4% / 8% (light) → black @ 8% / 16% (dark).
447
+
448
+ ### Spacing scale
449
+
450
+ | Token | Value (px) | Token | Value (px) |
451
+ |---|---|---|---|
452
+ | `spacing-0` | 0 | `spacing-16` | 16 |
453
+ | `spacing-1` | 1 | `spacing-20` | 20 |
454
+ | `spacing-1-5` | 1.5 | `spacing-24` | 24 |
455
+ | `spacing-2` | 2 | `spacing-32` | 32 |
456
+ | `spacing-4` | 4 | `spacing-40` | 40 |
457
+ | `spacing-6` | 6 | `spacing-48` | 48 |
458
+ | `spacing-7` | 7 | `spacing-56` | 56 |
459
+ | `spacing-8` | 8 | `spacing-64` | 64 |
460
+ | `spacing-12` | 12 | `spacing-72` | 72 |
461
+ | `spacing-14` | 14 | `spacing-80` | 80 |
462
+
463
+ ### Radius scale
464
+
465
+ | Token | Value | Used for |
466
+ |---|---|---|
467
+ | `radius-0` | 0px | Sharp edges |
468
+ | `radius-4` | 4px | Tags, tabs |
469
+ | `radius-8` | 8px | Inputs, fields, cards (default) |
470
+ | `radius-12` | 12px | Mid-tier surfaces |
471
+ | `radius-16` | 16px | Section messages, notifications, bottom sheets |
472
+ | `radius-24` | 24px | Bottom sheet handles |
473
+ | `radius-48` | 48px | Large feature blocks |
474
+ | `radius-999` | 999px | Pills — buttons, badges, chips, segmented control |
290
475
 
291
- > ⚠️ **`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.**
476
+ ### Border-width scale
477
+
478
+ `border-0` (0) · `border-1` (1) · `border-1-5` (1.5) · `border-2` (2) · `border-4` (4) · `border-8` (8)
479
+
480
+ > 1.5px is the standard for selected / focused outlines (chips, list-item, segmented control segments, tabs).
292
481
 
293
482
  ### Transition tokens
294
483
 
@@ -301,6 +490,7 @@ Duration — primitive scale:
301
490
  | `duration-base` | `--primitive-duration-base` | `200ms` | Dropdowns, popovers, accordions |
302
491
  | `duration-slow` | `--primitive-duration-slow` | `300ms` | Dialogs, sheets, drawers closing |
303
492
  | `duration-open` | `--primitive-duration-open` | `500ms` | Sheets, drawers entering |
493
+ | `duration-blink` | `--primitive-duration-blink` | `1000ms` | OTP caret blink |
304
494
 
305
495
  Easing — primitive scale:
306
496
 
@@ -313,74 +503,87 @@ Easing — primitive scale:
313
503
 
314
504
  > Always use token utilities — never raw `duration-200` or `ease-in-out` directly.
315
505
 
316
- ### Other tokens
317
-
318
- | Tailwind class | Value | Usage |
319
- |---|---|---|
320
- | `bg-slider-range` | blue 40% | Slider filled range |
321
- | `rounded-lg` | `0.625rem` | Base border radius |
322
-
323
506
  ### Using opacity with tokens
324
507
 
325
508
  Opacity on tokens is allowed and encouraged:
326
509
 
327
510
  ```
328
- ✅ bg-primary/20 → blue at 20% opacity
329
- ✅ border-border-subtle/50 → light grey border at 50% opacity
330
- ✅ ring-ring/10 → ring at 10% opacity
511
+ ✅ bg-primary/20 → coral at 20% opacity
512
+ ✅ border-subtle-default/50 → subtle border at 50% opacity
513
+ ✅ ring-ring/10 → focus ring at 10% opacity
331
514
 
332
- ❌ bg-black/50 → NOT a token, use bg-overlay instead
333
- ❌ bg-white → NOT a token, use bg-prominent or bg-card
515
+ ❌ bg-black/50 → NOT a token, use bg-overlay instead
516
+ ❌ bg-white → NOT a token, use bg-primary-surface or bg-secondary-canvas
334
517
  ```
335
518
 
336
- ### Primitive alpha scales
519
+ ### Primitive colour ramps
337
520
 
338
- 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.
521
+ The system ships **17 colour ramps**. Each ramp has solid stops 100 → 1300 (slate adds 50, 75, 1400) and an opacity scale 50 → 1100. Reference these only via semantic or component tokens — never in product code.
339
522
 
340
- ```
341
- --primitive-mono-alpha-4 through --primitive-mono-alpha-80 (black at N%)
342
- --primitive-blue-alpha-4 through --primitive-blue-alpha-80 (brand blue at N%)
343
- Stops: 4 · 8 · 16 · 24 · 32 · 40 · 50 · 64 · 80
344
- ```
345
-
346
- Example — how `--tabs` uses the alpha scale:
347
- ```css
348
- --tabs: var(--primitive-mono-alpha-4); /* black at 4% — tab container background */
349
- ```
350
-
351
- > `--primitive-black-50` is deprecated. It now aliases `--primitive-mono-alpha-50`. The `--overlay` semantic token is unaffected.
523
+ | Ramp | 700 (mid / brand stop) | Notes |
524
+ |---|---|---|
525
+ | `slate` | `#414652` | Neutral / surface scale (50 → 1400) |
526
+ | `red` | `#E6190E` | Error / danger |
527
+ | `orange` | `#F55F0A` | Demo-account utility |
528
+ | `yellow` | `#FF9C13` | Warning |
529
+ | `mustard` | `#F7C60B` | Decorative warm |
530
+ | `green` | `#008832` | Success |
531
+ | `emerald` | `#00C390` | Real-account utility |
532
+ | `tiffany` | `#17EABD` | Decorative |
533
+ | `teal` | `#00CCCC` | Decorative |
534
+ | `seawater` | `#0AA0B0` | Decorative |
535
+ | `blue` | `#2C9AFF` | Information |
536
+ | `sapphire` | `#0C28F7` | Decorative |
537
+ | `blueberry` | `#4902E0` | Decorative |
538
+ | `grape` | `#7F0DCF` | Decorative |
539
+ | `magenta` | `#CB0DF7` | Decorative |
540
+ | `cherry` | `#DE0040` | Decorative |
541
+ | `coral` | `#FF444F` | **Brand primary** |
542
+
543
+ Opacity scale stops (per ramp): `50 · 75 · 100 · 200 · 300 · 400 · 500 · 600 · 700 · 800 · 900 · 1000 · 1100`
544
+ → alpha values: `0% · 4% · 8% · 16% · 24% · 32% · 40% · 48% · 56% · 64% · 72% · 80% · 88%`
545
+
546
+ White and black opacity scales follow the same stops.
352
547
 
353
548
  ---
354
549
 
355
550
  ## Typography
356
551
 
357
- The styles export includes pre-built typography classes using **Plus Jakarta Sans**.
358
-
359
- ### Heading scale (Semibold 600 · tracking 1.5px · uppercase)
552
+ The styles export includes pre-built typography classes using **Inter** (loaded from Google Fonts, weights 300–800).
360
553
 
361
- | Class | Size / Line height |
362
- |---|---|
363
- | `heading-h1` | 72px / 72px |
364
- | `heading-h2` | 64px / 64px |
365
- | `heading-h3` | 48px / 48px |
366
- | `heading-h4` | 40px / 40px |
367
- | `heading-xs` | 24px / 24px |
554
+ ### Heading scale (Inter · ExtraBold 800 · letter-spacing −0.02em)
368
555
 
369
- ### Body scale (Semibold 600)
556
+ | Class | Font size | Line height |
557
+ |---|---|---|
558
+ | `heading-mega` | 72px | 72px |
559
+ | `heading-hero` | 64px | 64px |
560
+ | `heading-h1` | 56px | 56px |
561
+ | `heading-h2` | 40px | 40px |
562
+ | `heading-h3` | 32px | 32px |
563
+ | `heading-h4` | 24px | 24px |
564
+ | `heading-h5` | 20px | 20px |
565
+ | `heading-h6` | 16px | 16px |
566
+ | `heading-xs` | 24px | 24px | (@deprecated — use `heading-h4`)
567
+
568
+ ### Body scale (Inter · Regular 400)
569
+
570
+ | Class | Font size | Line height |
571
+ |---|---|---|
572
+ | `body-xl` | 20px | 30px |
573
+ | `body-lg` | 18px | 27px |
574
+ | `body-md` | 16px | 24px |
575
+ | `body-sm` | 14px | 21px |
576
+ | `body-xs` | 12px | 18px |
370
577
 
371
- | Class | Size / Line height |
372
- |---|---|
373
- | `body-lg` | 18px / 28px |
374
- | `body-md` | 16px / 24px |
375
- | `body-sm` | 12px / 16px |
376
- | `body-xs` | 8px / 12px |
578
+ > Body text bold weight is 700. Body regular is 400. Apply via standard `font-bold` / `font-medium` / `font-semibold` Tailwind utilities (medium = 500, semibold = 600).
377
579
 
378
580
  ### Font utilities
379
581
 
380
- | Tailwind class | Font |
582
+ | Tailwind class | Font family |
381
583
  |---|---|
382
- | `font-display` | Plus Jakarta Sans — headings, display text |
383
- | `font-body` or `font-sans` | Plus Jakarta Sans — body text |
584
+ | `font-display` | Inter — headings, display text |
585
+ | `font-body` or `font-sans` | Inter — body text |
586
+ | `font-mono` | Red Hat Mono — code, tabular figures |
384
587
 
385
588
  ---
386
589
 
@@ -393,7 +596,7 @@ When you bump `@deriv-ds/design-intelligence-layer` and run `npm install` (or `n
393
596
  | You **import** components only from `@deriv-ds/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. |
394
597
  | 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. |
395
598
 
396
- **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.
599
+ **Overrides:** Passing large `className` strings onto Quill components can mask new defaults (e.g. old radius after a "pill button" update). After upgrading, review those callsites.
397
600
 
398
601
  **Cursor / AI agents:** The package ships agent rules at `node_modules/@deriv-ds/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.
399
602
 
@@ -416,22 +619,22 @@ This tells any AI agent to:
416
619
 
417
620
  **Design principles file** (bundled in the package):
418
621
  ```
419
- node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md
622
+ node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/quill-design-principles.md
420
623
  ```
421
624
 
422
625
  **Accessibility standards file** (bundled in the package):
423
626
  ```
424
- node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md
627
+ node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/quill-accessibility-standards.md
425
628
  ```
426
629
 
427
630
  **Personas file** (bundled in the package):
428
631
  ```
429
- node_modules/@deriv-ds/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
632
+ node_modules/@deriv-ds/design-intelligence-layer/guides/personas/deriv-user-field-guide.md
430
633
  ```
431
634
 
432
635
  **Brand voice** (bundled in the package):
433
636
  ```
434
- node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md
637
+ node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/quill-brand-voice.md
435
638
  ```
436
639
 
437
640
  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.
@@ -454,11 +657,11 @@ Add the following to your project's `CLAUDE.md`:
454
657
  ```markdown
455
658
  ## Design System
456
659
 
457
- This project uses @deriv-ds/design-intelligence-layer. Before writing any UI:
458
- 1. Read node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md — apply the 8 principles and run the 7-point checklist on every screen
459
- 2. Read node_modules/@deriv-ds/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
460
- 3. Read node_modules/@deriv-ds/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
461
- 4. Read node_modules/@deriv-ds/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
660
+ This project uses @deriv-ds/design-intelligence-layer (Quill Design System). Before writing any UI:
661
+ 1. Read node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/quill-design-principles.md — apply the 8 principles and run the 7-point checklist on every screen
662
+ 2. Read node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/quill-accessibility-standards.md — apply WCAG 2.1 AA standards and run the 9-point accessibility checklist on every screen
663
+ 3. Read node_modules/@deriv-ds/design-intelligence-layer/guides/personas/deriv-user-field-guide.md — understand the player personas that shape all copy and UX
664
+ 4. Read node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/quill-brand-voice.md — apply the brand voice: channel-specific voice, banned phrases, vocabulary, and formatting rules for all player-facing copy
462
665
  5. Check if the component exists in the package — import it, don't re-implement
463
666
  6. Use only design token classes (bg-prominent, text-on-prominent, border-border-subtle, etc.) — no hardcoded hex or raw Tailwind palette colors
464
667
  7. Do not install lucide-react, tailwindcss, or other bundled dependencies separately
@@ -475,15 +678,18 @@ See node_modules/@deriv-ds/design-intelligence-layer/README.md for complete toke
475
678
 
476
679
  | Wrong | Right | Why |
477
680
  |---|---|---|
478
- | `bg-gray-100` | `bg-subtle` | Raw Tailwind palette — use tokens |
479
- | `bg-white` | `bg-prominent` or `bg-card` | Not a semantic token |
480
- | `text-white` | `text-on-prominent-static-inverse` | Use the semantic inverse token |
481
- | `text-black` | `text-on-prominent` | Not a semantic token |
681
+ | `bg-gray-100` | `bg-secondary-surface` | Raw Tailwind palette — use tokens |
682
+ | `bg-white` | `bg-primary-surface` | Not a semantic token; breaks dark mode |
683
+ | `bg-[#181C25]` | `bg-primary-canvas` (dark) | Hardcoded hex — use the canvas token |
684
+ | `text-white` | `text-prominent-static-dark` | Use `static-dark` for "always white" cases |
685
+ | `text-black` | `text-prominent` | Not a semantic token; breaks dark mode |
482
686
  | `bg-black/50` | `bg-overlay` | Overlay has its own token |
483
- | `bg-[#2323FF]` | `bg-primary` | Hardcoded hex — use token |
484
- | `border-border` | `border-border-subtle` | Old name — prefer the new explicit name |
687
+ | `bg-[#2323FF]` or `bg-blue-600` | `bg-primary` | Brand is **coral `#FF444F`**, not blue |
688
+ | `bg-[#FF444F]` | `bg-primary` | Hardcoded hex — use token |
689
+ | `border-border` | `border-subtle-default` | Old name — prefer the new explicit name |
485
690
  | `bg-[var(--primary)]` | `bg-primary` | Raw CSS var — Tailwind v4 maps tokens directly |
486
691
  | `hsl(var(--primary))` | `bg-primary` | Tailwind v3 syntax — not needed in v4 |
692
+ | `font-[Plus_Jakarta_Sans]` | `font-sans` (Inter) | Project font is Inter, not Plus Jakarta Sans |
487
693
  | Installing `lucide-react` | Already bundled | Icons are included in the package |
488
694
 
489
695
  ---
@@ -509,8 +715,8 @@ These are bundled with the package. Installing them separately can cause version
509
715
 
510
716
  ```bash
511
717
  # Clone
512
- git clone https://github.com/trading-game/TG-design-system.git
513
- cd TG-design-system
718
+ git clone https://github.com/deriv-com/deriv-intelligence-layer.git
719
+ cd deriv-intelligence-layer
514
720
 
515
721
  # Install dependencies
516
722
  npm install
@@ -541,4 +747,4 @@ Design tokens are managed in Figma and exported as CSS variables. To update:
541
747
  - **Tailwind CSS v4** — CSS-first configuration
542
748
  - **shadcn/ui** (New York style) — base component primitives
543
749
  - **Radix UI** — accessible headless primitives
544
- - **Figma** — source of truth for design tokens
750
+ - **Figma** — source of truth for design tokens