npm - @deriv-ds/design-intelligence-layer - Versions diffs - 0.1.0 → 0.3.0 - Mend

@deriv-ds/design-intelligence-layer 0.1.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 (16) hide show

package/AGENTS.md +15 -15
package/README.md +362 -156
package/dist/index.cjs +2905 -1538
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +169 -73
package/dist/index.d.ts +169 -73
package/dist/index.js +2703 -1332
package/dist/index.js.map +1 -1
package/guides/brand-voice/deriv-brand-voice.md +250 -0
package/guides/design-system-guide/{trading-game-ds-guide.md → deriv-design-intelligence-guide.md} +14 -14
package/guides/design-system-guide/quill-ds-guide.md +817 -0
package/guides/personas/trading-game-player-field-guide.md +4 -112
package/guides/rules/design-system-consuming-project.mdc +17 -17
package/package.json +1 -1
package/src/styles.css +2315 -202
package/guides/brand-voice/trading-game-brand-voice.md +0 -325

package/README.md CHANGED Viewed

@@ -1,8 +1,8 @@
-# Trading Game Design System
+# Quill 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.
+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.
-Published as **`@trading-game/design-intelligence-layer`** on npm.
+Published as **`@deriv-ds/design-intelligence-layer`** on npm.
 ---
@@ -11,7 +11,7 @@ Published as **`@trading-game/design-intelligence-layer`** on npm.
 ### Installation
 ```bash
-npm install @trading-game/design-intelligence-layer@latest --safe-chain-skip-minimum-package-age
+npm install @deriv-ds/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).
@@ -21,9 +21,9 @@ npm install @trading-game/design-intelligence-layer@latest --safe-chain-skip-min
 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 "@deriv-ds/design-intelligence-layer/styles";
 @import "tailwindcss";
-@source "../node_modules/@trading-game/design-intelligence-layer/dist";
+@source "../node_modules/@deriv-ds/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/...`).
@@ -50,19 +50,19 @@ export default {
 ### 2. Fonts (handled automatically)
-The styles import loads **Plus Jakarta Sans** from Google Fonts automatically. No additional font setup is needed.
+The styles import loads **Inter** from Google Fonts automatically (weights 300–800). No additional font setup is needed.
-Use `font-body`, `font-display`, or `font-sans` in your Tailwind classes — all resolve to Plus Jakarta Sans.
+Use `font-body`, `font-display`, or `font-sans` in your Tailwind classes — all resolve to Inter. Use `font-mono` for code (Red Hat Mono).
 ### 3. Use components
 ```tsx
-import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
+import { Button, Card, Badge } from "@deriv-ds/design-intelligence-layer"
 export default function App() {
   return (
     <Card>
-      <Button variant="primary">Trade Now</Button>
+      <Button variant="primary">Get Started</Button>
       <Badge>Live</Badge>
     </Card>
   )
@@ -84,10 +84,12 @@ npm install react react-dom tailwindcss
 ## 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
+- **Design tokens** — three-layer architecture (primitives → foundation semantics → component tokens) synced from Figma
+- **Light + Dark themes** — toggle `.dark` on `<html>` to switch; every semantic token has a paired override
+- **Inter typography** — heading (mega → h6) and body (xl → xs) scales ready to use
+- **17 colour ramps** — slate, blue, sapphire, blueberry, grape, magenta, cherry, coral, red, orange, yellow, mustard, green, emerald, tiffany, teal, seawater
+- **Transition tokens** — semantic duration (`duration-fast`, `duration-base`, etc.) and easing (`ease-standard`, `ease-enter`, etc.) — no hardcoded `duration-200`
+- **Elevation scale** — five composed `box-shadow` shorthands (`--elevation-100` through `--elevation-500`) that auto-adapt to the active theme
 - **TypeScript** — full type definitions included
 - **ESM + CJS** — works with any bundler
@@ -98,10 +100,7 @@ npm install react react-dom tailwindcss
 | 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` |
@@ -109,12 +108,14 @@ npm install react react-dom tailwindcss
 | Carousel | `Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext` |
 | Chart | `ChartContainer, ChartTooltip, ChartLegend, ChartStyle` |
 | Checkbox | `Checkbox` |
+| Chip | `Chip, chipVariants` |
 | 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, ...` |
+| Direction | `DirectionProvider, useDirection` |
+| Drawer | `Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, DrawerClose` |
 | Dropdown Menu | `DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, ...` |
 | Empty State | `Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent` |
 | Field | `Field, FieldLabel, FieldDescription, FieldError, FieldGroup` |
@@ -122,33 +123,35 @@ npm install react react-dom tailwindcss
 | 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, ...` |
+| Loading Spinner | `LoadingSpinner` |
+| Modal | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
 | Native Select | `NativeSelect, NativeSelectOptGroup, NativeSelectOption` |
 | Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuTrigger, ...` |
+| OTP Field | `CodeInput, CodeInputGroup, CodeInputSlot, CodeInputSeparator` |
 | Pagination | `Pagination, PaginationContent, PaginationLink, ...` |
 | Popover | `Popover, PopoverTrigger, PopoverContent, PopoverAnchor` |
 | Progress | `Progress` |
 | Radio Group | `RadioGroup, RadioGroupItem` |
 | Resizable | `ResizableHandle, ResizablePanel, ResizablePanelGroup` |
 | Scroll Area | `ScrollArea, ScrollBar` |
+| Section Message | `SectionMessage, SectionMessageTitle, SectionMessageDescription` |
 | 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` |
+| Tab | `Tab, TabList, TabTrigger, TabContent` |
 | Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` |
 | Tabs | `Tabs, TabsList, TabsTrigger, TabsContent` |
+| Tag | `Tag, tagVariants` |
 | Textarea | `Textarea` |
 | Ticket Card | `TicketCard` |
-| Toast | `Toaster` |
 | Toggle | `Toggle, toggleVariants` |
 | Toggle Group | `ToggleGroup, ToggleGroupItem` |
 | Tooltip | `Tooltip, TooltipTrigger, TooltipContent, TooltipProvider` |
@@ -157,7 +160,7 @@ npm install react react-dom tailwindcss
 ## 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.
+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.
 | Block | Variants | Description |
 |---|---|---|
@@ -168,54 +171,85 @@ Blocks are pre-composed UI patterns built from design system primitives. They ar
 ## Button variants and sizes
+The brand colour is **coral `#FF444F`** (`--primitive-coral-700`). Hover darkens to `#E12E3A` (coral-800), pressed to `#C41C28` (coral-900).
 ```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
+<Button variant="primary" />    // Coral filled (#FF444F) — main CTA, white text
+<Button variant="secondary" />  // 1.5px outline (slate-1200 / white in dark) — secondary actions
+<Button variant="tertiary" />   // Filled neutral surface (slate-100 / slate-1000 in dark)
+<Button variant="ghost" />      // Transparent, hover tint only
+// Theme tone modifiers (per variant): normal · inverse · static-light · static-dark
+// e.g. <Button variant="primary" tone="static-light" />
+// Sizes (height · font-size · min-width)
+<Button size="lg" />      // 48px · 18px · 96px min, 20px padding-x
+<Button size="md" />      // 40px · 16px · 80px min, 16px padding-x (default)
+<Button size="sm" />      // 32px · 14px · 64px min, 12px padding-x
+// Icon-only sizes (square)
+<Button size="icon-lg" /> // 48 × 48 — icon 24px
+<Button size="icon-md" /> // 40 × 40 — icon 20px
+<Button size="icon-sm" /> // 32 × 32 — icon 16px
+```
+All sizes use a fully pill-shaped border (`border-radius: 999px`).
+## Badge variants
+```tsx
+// Status fills (solid backgrounds, white text)
+<Badge variant="number" />  // Red (#C40000 light · #FF4D4D dark)
+<Badge variant="red" />     // Status red
+<Badge variant="yellow" />  // Status yellow (#C47D00 / #FFBE4D)
+<Badge variant="green" />   // Status green (#007A22 / #4DBC6B)
+<Badge variant="blue" />    // Status info blue (#0777C4 / #53B9FF)
 // 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 size="sm" />   // 20px height · 12px font · 8px dot
+<Badge size="md" />   // 24px height · 14px font · 16px dot
 ```
-## Badge variants
+Badges are pill-shaped (`border-radius: 999px`).
+## Tag variants
+Tags are 4px-radius chips for filtering, metadata, and categorisation. Two visual styles — outline and fill — across five tones.
 ```tsx
-// Default (solid)
-<Badge variant="default" />         // Blue (#2323FF)
-<Badge variant="default-success" /> // Green
-<Badge variant="default-fail" />    // Red
+<Tag tone="neutral" />   // slate (default)
+<Tag tone="red" />
+<Tag tone="yellow" />
+<Tag tone="green" />
+<Tag tone="blue" />
+<Tag variant="outline" />  // border + text, transparent fill
+<Tag variant="fill" />     // tinted background (red @ 8%, etc.)
-// Fill (tint background)
-<Badge variant="fill" />            // Blue tint
-<Badge variant="fill-success" />    // Green tint
-<Badge variant="fill-fail" />       // Red tint
+// Sizes
+<Tag size="sm" />   // 24px · 12px font · 16px icon · 4px gap
+<Tag size="md" />   // 32px · 14px font · 18px icon · 8px gap
+```
-// Outline (black border, secondary-hover on hover)
-<Badge variant="outline" />
+## Section message variants
-// Ghost (transparent)
-<Badge variant="ghost" />
-<Badge variant="ghost-success" />
-<Badge variant="ghost-fail" />
+```tsx
+<SectionMessage variant="default" />     // Neutral grey tint
+<SectionMessage variant="information" /> // Blue tint + info icon
+<SectionMessage variant="success" />     // Green tint + check icon
+<SectionMessage variant="warning" />     // Yellow tint + alert icon
+<SectionMessage variant="danger" />      // Red tint + danger icon
 // Sizes
-<Badge size="sm" />   // 24px height
-<Badge size="md" />   // 32px height (default)
-<Badge size="lg" />   // 40px height
+<SectionMessage size="sm" />  // 14px message · 16px title · 20px icon
+<SectionMessage size="md" />  // 16px message · 18px title · 22px icon
 ```
 ## Alert variants
 ```tsx
-<Alert variant="info" />    // blue — informational (default)
-<Alert variant="error" />   // red — error state
+<Alert variant="info" />    // blue (#0777C4 / #53B9FF) — informational (default)
+<Alert variant="error" />   // red (#C40000 / #FF4D4D) — error state
 ```
 ## Component behaviour notes
@@ -231,6 +265,18 @@ Blocks are pre-composed UI patterns built from design system primitives. They ar
 ### 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.
+### Drawer — handle bar (bottom direction)
+When `direction="bottom"`, `DrawerContent` renders a handle bar at the top that follows the `component-bottom-sheet` design tokens:
+| Property | Token | Value |
+|---|---|---|
+| Container height | `--bottom-sheet-size-height-handle-container` | 32px |
+| Container bg (default) | `--bottom-sheet-bg-handle-default` | `slate-50` / `slate-1100` |
+| Bar height | `--bottom-sheet-size-height-handle-bar` | 4px |
+| Bar width | `--bottom-sheet-size-width-handle-bar` | 40px |
+| Bar color | `--bottom-sheet-bg-handle-bar` | `black-alpha-300` / `white-alpha-300` |
+| Bar radius | `--bottom-sheet-size-radius-handle-bar` | 999 (pill) |
 ### 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.
@@ -241,54 +287,197 @@ The `lg` variant of `Link` uses `text-base` (16px). The `md` and `sm` variants u
 ```
 ### 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`.
+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`.
+Tab sizes:
+| Size | Min height | Min width | Padding-x | Font size |
+|---|---|---|---|---|
+| `sm` | 32px | 72px | 12px | 14px |
+| `md` | 40px | 80px | 16px | 16px |
+| `lg` | 48px | 96px | 20px | 18px |
 ---
 ## Design tokens
-All tokens are CSS custom properties, loaded automatically via `@trading-game/design-intelligence-layer/styles`.
+All tokens are CSS custom properties, loaded automatically via `@deriv-ds/design-intelligence-layer/styles`. Tokens follow a three-layer architecture:
+1. **Primitives** (`--primitive-*`) — raw colour ramps, alpha scales, durations, easings. Never reference directly.
+2. **Foundation semantics** (`--background-*`, `--text-*`, `--border-*`, `--icon-*`, `--elevation-*`) — paired between `:root` (light) and `.dark` (dark).
+3. **Component tokens** (`--button-*`, `--field-*`, `--tag-*`, `--badge-*`, etc.) — derived from foundation semantics.
+### Theme switching
+Toggle dark mode by adding `.dark` to the `<html>` element:
+```html
+<html class="dark"> <!-- or remove .dark for light mode -->
+```
+Every semantic token has a paired light/dark value, so component code never needs theme-aware conditionals.
 ### Background tokens
-| Tailwind class | CSS variable | Value | Usage |
+| Tailwind class | CSS variable | Light | Dark | Usage |
+|---|---|---|---|---|
+| `bg-primary-canvas` | `--background-primary-canvas` | `#F6F7F8` | `#181C25` | Page / app canvas |
+| `bg-secondary-canvas` | `--background-secondary-canvas` | `#FFFFFF` | `#181C25` | Alternate canvas |
+| `bg-primary-surface` | `--background-primary-surface` | `#FFFFFF` | `#20242F` | Cards, panels, default surface |
+| `bg-secondary-surface` | `--background-secondary-surface` | `#F6F7F8` | `#20242F` | Subtle / nested surface |
+| `bg-overlay` | `--overlay` | black 50% | black 50% | Modal / dialog / drawer backdrop |
+| `bg-tabs` | `--tabs` | slate @ 4% | white @ 4% | Tab container background (`variant="default"`) |
+| `bg-tabs-active` | `--tabs-active` | `#FFFFFF` | `#11141B` | Active / selected tab pill |
+| `bg-primary` | `--primary` | `#FF444F` | `#FF444F` | Brand coral — CTAs (same in both themes) |
+| `bg-primary-hover` | `--primary-hover` | `#E12E3A` | `#E12E3A` | Primary button hover (coral-800) |
+| `bg-secondary-hover` | `--secondary-hover` | secondary-surface | secondary-surface | Outline / secondary hover tint |
+| `bg-slider-range` | `--slider-range` | coral @ 40% | coral @ 40% | Slider filled range |
+#### Status backgrounds (24% tints)
+| Tailwind class | Light | Dark | 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 |
+| `bg-success-default` | green @ 24% | green @ 24% | Positive / win state surface |
+| `bg-error-default` | red @ 24% | red @ 24% | Negative / loss state surface |
+| `bg-warning-default` | yellow @ 24% | yellow @ 24% | Caution surface |
+| `bg-information-default` | blue @ 24% | blue @ 24% | Informational surface |
+#### Interaction tints (state layers)
+| Tailwind class | Light | Dark | Usage |
+|---|---|---|---|
+| `bg-hover-default` | slate @ 8% | white @ 8% | Hover state layer |
+| `bg-pressed-default` | slate @ 16% | white @ 16% | Pressed state layer |
+| `bg-selected-default` | slate @ 8% | white @ 8% | Selected state layer |
+> Each interaction tint also ships in `inverse`, `static-light`, and `static-dark` flavours (e.g. `bg-hover-static-light`) for placement on themed surfaces.
 ### Text tokens
-| Tailwind class | Value | Usage |
+| Tailwind class | Light | Dark | Usage |
+|---|---|---|---|
+| `text-prominent` | `#181C25` | `#FFFFFF` | Primary on-canvas text |
+| `text-subtle` | slate @ 48% | white @ 48% | Secondary / supporting text |
+| `text-disabled-default` | slate @ 16% | white @ 16% | Disabled labels |
+| `text-prominent-inverse` | `#FFFFFF` | `#181C25` | Text on inverse surfaces |
+| `text-prominent-static-dark` | `#FFFFFF` | `#FFFFFF` | Always white (text on coloured fills) |
+| `text-prominent-static-light` | `#181C25` | `#181C25` | Always slate (text on light fills) |
+#### Status text
+| Tailwind class | Light | Dark | Usage |
+|---|---|---|---|
+| `text-success-default` | `#007A22` | `#4DBC6B` | Profit / positive |
+| `text-error-default` | `#C40000` | `#FF4D4D` | Loss / negative |
+| `text-warning-default` | `#C47D00` | `#FFBE4D` | Caution |
+| `text-information-default` | `#0777C4` | `#53B9FF` | Informational |
+#### Utility text (brand & account modes)
+| Tailwind class | Value (both themes) | 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-utility-brand` | `#FF444F` (coral-700) | Brand-tinted inline text |
+| `text-utility-real` | `#00C390` (emerald-700) | Real-account indicator |
+| `text-utility-demo` | `#F55F0A` (orange-700) | Demo-account indicator |
+> The `*-inverse`, `*-static-light`, and `*-static-dark` variants exist for every status token and follow the same theme-pairing rules as `text-prominent`.
+### Border tokens
-| `text-primary` | `#2323FF` | Brand blue inline text |
-| `text-semantic-win` | green | Profit / positive text |
-| `text-semantic-loss` | red | Loss / negative text |
+| Tailwind class | CSS variable | Light | Dark | Usage |
+|---|---|---|---|---|
+| `border-default` | `--border-default-default` | slate @ 16% | white @ 16% | Default global border (used by `*` selector) |
+| `border-subtle-default` | `--border-subtle-default` | slate @ 8% | white @ 8% | Cards, dividers, panels |
+| `border-prominent-default` | `--border-prominent-default` | slate @ 16% | white @ 16% | Heavier dividers |
+| `border-selected` | `--border-selected-default` | `#181C25` | `#FFFFFF` | Selected state borders (chip, list-item) |
+| `border-disabled-default` | `--border-disabled-default` | slate @ 8% | white @ 8% | Disabled component borders |
+| `border-input` | `--input` | slate @ 8% | white @ 8% | Input field borders (alias of border-subtle) |
+| `border-border` | `--border` | slate @ 8% | white @ 8% | @deprecated alias — prefer `border-subtle-default` |
+| `ring-ring` | `--ring` | `#FF444F` | `#FF444F` | Focus rings (brand coral) |
-### Border & focus tokens
+#### Status borders
+| Tailwind class | Light | Dark |
+|---|---|---|
+| `border-success-default` | `#007A22` | `#4DBC6B` |
+| `border-error-default` | `#C40000` | `#FF4D4D` |
+| `border-warning-default` | `#C47D00` | `#FFBE4D` |
+| `border-information-default` | `#0777C4` | `#53B9FF` |
-| Tailwind class | CSS variable | Value | Usage |
+> ⚠️ **`border-border` is deprecated.** It now aliases `--border-subtle-default` for backward compatibility. Prefer `border-subtle-default` in all new code.
+### Icon tokens
+Icons follow the same `prominent / subtle / disabled / status / utility` taxonomy as text:
+| Tailwind class | Light | Dark | 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 |
+| `text-icon-prominent` (via `--icon-prominent-default`) | `#181C25` | `#FFFFFF` | Default icon colour |
+| `text-icon-subtle` | slate @ 48% | white @ 48% | Secondary icons |
+| `text-icon-disabled` | slate @ 16% | white @ 16% | Disabled icons |
+| `text-icon-success` | `#007A22` | `#4DBC6B` | Success icons |
+| `text-icon-error` | `#C40000` | `#FF4D4D` | Error icons |
+| `text-icon-warning` | `#C47D00` | `#FFBE4D` | Warning icons |
+| `text-icon-information` | `#0777C4` | `#53B9FF` | Info icons |
+| `text-icon-utility-brand` | `#FF444F` | `#FF444F` | Brand-tinted icon |
+| `text-icon-utility-real` | `#00C390` | `#00C390` | Real-account icon |
+| `text-icon-utility-demo` | `#F55F0A` | `#F55F0A` | Demo-account icon |
+Icon component sizes:
+| Size | Width × height | Flag width × height |
+|---|---|---|
+| `sm` | 16 × 16 | 24 × 16 |
+| `md` | 20 × 20 | 30 × 20 |
+| `lg` | 24 × 24 | 36 × 24 |
+### Elevation tokens
+Five composed `box-shadow` shorthands. Defined once in `:root` — `.dark` swaps only the layer colours, so a single `--elevation-*` reference works in both themes.
+| Token | Layer 1 (y / blur) | Layer 2 | Layer 3 | Used for |
+|---|---|---|---|---|
+| `--elevation-100` | 1 / 2 | — | — | Base raise (chips, segmented control segments) |
+| `--elevation-200` | 1 / 2 | 2 / 6 | — | Inputs, low cards |
+| `--elevation-300` | 1 / 2 | 4 / 12 | 8 / 24 | Menus, tooltips, popovers |
+| `--elevation-400` | 2 / 4 | 8 / 24 | 16 / 48 | Notifications, snackbars, banner |
+| `--elevation-500` | 4 / 8 | 16 / 48 | 32 / 96 | Bottom sheets, dialogs |
+Layer colours: black @ 4% / 8% (light) → black @ 8% / 16% (dark).
+### Spacing scale
+| Token | Value (px) | Token | Value (px) |
+|---|---|---|---|
+| `spacing-0` | 0 | `spacing-16` | 16 |
+| `spacing-1` | 1 | `spacing-20` | 20 |
+| `spacing-1-5` | 1.5 | `spacing-24` | 24 |
+| `spacing-2` | 2 | `spacing-32` | 32 |
+| `spacing-4` | 4 | `spacing-40` | 40 |
+| `spacing-6` | 6 | `spacing-48` | 48 |
+| `spacing-7` | 7 | `spacing-56` | 56 |
+| `spacing-8` | 8 | `spacing-64` | 64 |
+| `spacing-12` | 12 | `spacing-72` | 72 |
+| `spacing-14` | 14 | `spacing-80` | 80 |
+### Radius scale
+| Token | Value | Used for |
+|---|---|---|
+| `radius-0` | 0px | Sharp edges |
+| `radius-4` | 4px | Tags, tabs |
+| `radius-8` | 8px | Inputs, fields, cards (default) |
+| `radius-12` | 12px | Mid-tier surfaces |
+| `radius-16` | 16px | Section messages, notifications, bottom sheets |
+| `radius-24` | 24px | Bottom sheet handles |
+| `radius-48` | 48px | Large feature blocks |
+| `radius-999` | 999px | Pills — buttons, badges, chips, segmented control |
-> ⚠️ **`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.**
+### Border-width scale
+`border-0` (0) · `border-1` (1) · `border-1-5` (1.5) · `border-2` (2) · `border-4` (4) · `border-8` (8)
+> 1.5px is the standard for selected / focused outlines (chips, list-item, segmented control segments, tabs).
 ### Transition tokens
@@ -301,6 +490,7 @@ Duration — primitive scale:
 | `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 |
+| `duration-blink` | `--primitive-duration-blink` | `1000ms` | OTP caret blink |
 Easing — primitive scale:
@@ -313,89 +503,102 @@ Easing — primitive scale:
 > 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-primary/20            → coral at 20% opacity
+✅ border-subtle-default/50 → subtle border at 50% opacity
+✅ ring-ring/10             → focus 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
+❌ bg-black/50              → NOT a token, use bg-overlay instead
+❌ bg-white                 → NOT a token, use bg-primary-surface or bg-secondary-canvas
 ```
-### Primitive alpha scales
+### Primitive colour ramps
-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.
+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.
-```
---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.
+| Ramp | 700 (mid / brand stop) | Notes |
+|---|---|---|
+| `slate` | `#414652` | Neutral / surface scale (50 → 1400) |
+| `red` | `#E6190E` | Error / danger |
+| `orange` | `#F55F0A` | Demo-account utility |
+| `yellow` | `#FF9C13` | Warning |
+| `mustard` | `#F7C60B` | Decorative warm |
+| `green` | `#008832` | Success |
+| `emerald` | `#00C390` | Real-account utility |
+| `tiffany` | `#17EABD` | Decorative |
+| `teal` | `#00CCCC` | Decorative |
+| `seawater` | `#0AA0B0` | Decorative |
+| `blue` | `#2C9AFF` | Information |
+| `sapphire` | `#0C28F7` | Decorative |
+| `blueberry` | `#4902E0` | Decorative |
+| `grape` | `#7F0DCF` | Decorative |
+| `magenta` | `#CB0DF7` | Decorative |
+| `cherry` | `#DE0040` | Decorative |
+| `coral` | `#FF444F` | **Brand primary** |
+Opacity scale stops (per ramp): `50 · 75 · 100 · 200 · 300 · 400 · 500 · 600 · 700 · 800 · 900 · 1000 · 1100`
+→ alpha values: `0% · 4% · 8% · 16% · 24% · 32% · 40% · 48% · 56% · 64% · 72% · 80% · 88%`
+White and black opacity scales follow the same stops.
 ---
 ## Typography
-The styles export includes pre-built typography classes using **Plus Jakarta Sans**.
-### Heading scale (Semibold 600 · tracking 1.5px · uppercase)
+The styles export includes pre-built typography classes using **Inter** (loaded from Google Fonts, weights 300–800).
-| Class | Size / Line height |
-|---|---|
-| `heading-h1` | 72px / 72px |
-| `heading-h2` | 64px / 64px |
-| `heading-h3` | 48px / 48px |
-| `heading-h4` | 40px / 40px |
-| `heading-xs` | 24px / 24px |
+### Heading scale (Inter · ExtraBold 800 · letter-spacing −0.02em)
-### Body scale (Semibold 600)
+| Class | Font size | Line height |
+|---|---|---|
+| `heading-mega` | 72px | 72px |
+| `heading-hero` | 64px | 64px |
+| `heading-h1` | 56px | 56px |
+| `heading-h2` | 40px | 40px |
+| `heading-h3` | 32px | 32px |
+| `heading-h4` | 24px | 24px |
+| `heading-h5` | 20px | 20px |
+| `heading-h6` | 16px | 16px |
+| `heading-xs` | 24px | 24px | (@deprecated — use `heading-h4`)
+### Body scale (Inter · Regular 400)
+| Class | Font size | Line height |
+|---|---|---|
+| `body-xl` | 20px | 30px |
+| `body-lg` | 18px | 27px |
+| `body-md` | 16px | 24px |
+| `body-sm` | 14px | 21px |
+| `body-xs` | 12px | 18px |
-| Class | Size / Line height |
-|---|---|
-| `body-lg` | 18px / 28px |
-| `body-md` | 16px / 24px |
-| `body-sm` | 12px / 16px |
-| `body-xs` | 8px / 12px |
+> 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).
 ### Font utilities
-| Tailwind class | Font |
+| Tailwind class | Font family |
 |---|---|
-| `font-display` | Plus Jakarta Sans — headings, display text |
-| `font-body` or `font-sans` | Plus Jakarta Sans — body text |
+| `font-display` | Inter — headings, display text |
+| `font-body` or `font-sans` | Inter — body text |
+| `font-mono` | Red Hat Mono — code, tabular figures |
 ---
 ## Upgrading the design system
-When you bump `@trading-game/design-intelligence-layer` and run `npm install` (or `npm ci`):
+When you bump `@deriv-ds/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 **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. |
 | 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.
+**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.
-**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.
+**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.
 ---
@@ -406,7 +609,7 @@ When you bump `@trading-game/design-intelligence-layer` and run `npm install` (o
 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
+cp node_modules/@deriv-ds/design-intelligence-layer/AGENTS.md ./AGENTS.md
 ```
 This tells any AI agent to:
@@ -416,22 +619,22 @@ This tells any AI agent to:
 **Design principles file** (bundled in the package):
 ```
-node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md
+node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/quill-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
+node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/quill-accessibility-standards.md
 ```
 **Personas file** (bundled in the package):
 ```
-node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
+node_modules/@deriv-ds/design-intelligence-layer/guides/personas/deriv-user-field-guide.md
 ```
 **Brand voice** (bundled in the package):
 ```
-node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md
+node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/quill-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.
@@ -442,7 +645,7 @@ 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/
+cp node_modules/@deriv-ds/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.
@@ -454,19 +657,19 @@ 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
+This project uses @deriv-ds/design-intelligence-layer (Quill Design System). Before writing any UI:
+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
+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
+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
+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
 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.
+See node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc for full rules.
+See node_modules/@deriv-ds/design-intelligence-layer/README.md for complete token and component reference.
 ```
 ---
@@ -475,15 +678,18 @@ See node_modules/@trading-game/design-intelligence-layer/README.md for complete
 | 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-gray-100` | `bg-secondary-surface` | Raw Tailwind palette — use tokens |
+| `bg-white` | `bg-primary-surface` | Not a semantic token; breaks dark mode |
+| `bg-[#181C25]` | `bg-primary-canvas` (dark) | Hardcoded hex — use the canvas token |
+| `text-white` | `text-prominent-static-dark` | Use `static-dark` for "always white" cases |
+| `text-black` | `text-prominent` | Not a semantic token; breaks dark mode |
 | `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-[#2323FF]` or `bg-blue-600` | `bg-primary` | Brand is **coral `#FF444F`**, not blue |
+| `bg-[#FF444F]` | `bg-primary` | Hardcoded hex — use token |
+| `border-border` | `border-subtle-default` | 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 |
+| `font-[Plus_Jakarta_Sans]` | `font-sans` (Inter) | Project font is Inter, not Plus Jakarta Sans |
 | Installing `lucide-react` | Already bundled | Icons are included in the package |
 ---
@@ -509,8 +715,8 @@ These are bundled with the package. Installing them separately can cause version
 ```bash
 # Clone
-git clone https://github.com/trading-game/TG-design-system.git
-cd TG-design-system
+git clone https://github.com/deriv-com/deriv-intelligence-layer.git
+cd deriv-intelligence-layer
 # Install dependencies
 npm install
@@ -541,4 +747,4 @@ Design tokens are managed in Figma and exported as CSS variables. To update:
 - **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
+- **Figma** — source of truth for design tokens