@deriv-ds/design-intelligence-layer 0.6.1 → 0.6.2

package/guides/design-system-guide/icon-reference.md

@@ -14,7 +14,7 @@ import { Icon } from "@deriv-ds/design-intelligence-layer";
 <Icon name="bell" />
 
 // Explicit weight + styling via className
-<Icon name="circle-check" weight="fill" className="size-4 text-success" />
+<Icon name="circle-check" weight="fill" className="size-4 text-[var(--text-success-default)]" />
 <Icon name="user"         weight="regular" className="text-subtle" />
 ```
 

package/guides/design-system-guide/quill-ds-guide.md

@@ -39,7 +39,8 @@ ALWAYS use semantic tokens:
   ✅ text-prominent, text-subtle, text-on-prominent-static-inverse
   ✅ border-default, border-selected, ring-ring
   ✅ bg-primary, bg-primary-hover, bg-secondary-hover
-  ✅ text-warning, text-info, text-alert-info-text, text-alert-error-text
+  ✅ text-warning, text-info, text-success, text-error (the four status text utilities), text-alert-info-text, text-alert-error-text
+  ✅ text-on-primary / text-on-success / text-on-error / text-on-warning / text-on-info (foreground on a solid coloured surface)
   ✅ Opacity on a token IS allowed: bg-primary/20, border-default/50, ring-primary/10
 ```
 
@@ -59,7 +60,7 @@ Token rules apply ONLY to:
 ### Rule 4 — Do NOT install or import these separately
 
 ```
-❌ lucide-react or any icon library — icons come from FontAwesome Pro via the package's <Icon /> component (see icon-reference.md in this folder)
+❌ lucide-react or any icon library — icons come from `@deriv/quill-icons` via the package's <Icon /> component (see icon-reference.md in this folder)
 ❌ tailwindcss — the package ships its own Tailwind v4 config
 ❌ @apply with hsl(var(--token)) — Tailwind v4 uses CSS variables directly
 ❌ tailwind.config.js — configuration is handled by the package via CSS
@@ -135,14 +136,14 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 
 ### 2.3 — Semantic (Status)
 
-| CSS Variable                | Tailwind Class          | Usage                     |
-| --------------------------- | ----------------------- | ------------------------- |
-| `--text-success-default`    | `text-success` (via foundation) | Success / Positive outcomes (green-900 light, green-500 dark) |
-| `--text-error-default`      | `text-error` (via foundation)   | Error / Negative outcomes (red-900 light, red-500 dark)  |
-| `--text-warning-default`    | `text-warning`          | Warning / Caution / Non-destructive alerts (yellow-900 light, yellow-500 dark) |
-| `--text-information-default`| `text-info`             | Informational alerts (blue-900 light, blue-500 dark)     |
+| CSS Variable                | Tailwind Class                       | Usage                     |
+| --------------------------- | ------------------------------------ | ------------------------- |
+| `--text-warning-default`    | `text-warning`                       | Warning / Caution / Non-destructive alerts (yellow-900 light, yellow-500 dark) |
+| `--text-information-default`| `text-info`                          | Informational alerts (blue-900 light, blue-500 dark)     |
+| `--text-success-default`    | `text-success`                       | Success / Positive outcomes (green-900 light, green-500 dark) |
+| `--text-error-default`      | `text-error`                         | Error / Negative outcomes (red-900 light, red-500 dark) |
 
-> All semantic tokens support opacity variants (e.g. `bg-warning/10` for tinted backgrounds). Foundation background tokens are also available: `--background-success-default`, `--background-error-default`, `--background-warning-default`, `--background-information-default`. For structured alpha surfaces, use the primitive alpha scales — see Section 2.10.
+> **All four status colours are bare utility classes:** `text-warning`, `text-info`, `text-success`, `text-error` (each mapped to its `--text-*-default` value in the theme bridge — theme-aware and opacity-friendly, e.g. `bg-success/10`). The older `text-[var(--text-success-default)]` / `text-[var(--text-error-default)]` form still resolves (the package's own blocks such as `hero-mobile-transaction.tsx` use it) but new code should prefer the utilities. Foundation background tokens are also available: `--background-success-default`, `--background-error-default`, `--background-warning-default`, `--background-information-default`. For text/icons on a **solid** coloured surface use `text-on-primary` / `text-on-success` / `text-on-error` / `text-on-warning` / `text-on-info`. For a **solid opaque status tint** that won't bleed on a coloured background use `bg-success-surface` / `bg-error-surface` / `bg-warning-surface` / `bg-info-surface` (built with `color-mix`, theme-aware). For structured alpha surfaces, use the primitive alpha scales — see Section 2.10.
 
 ### 2.4 — Text & Icon Colors
 
@@ -160,7 +161,7 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 | `--border-subtle-default`   | (via `--input`)           | Subtle / light border (slate @ 8% alpha) |
 | `--border-selected-default` | `border-selected`         | Selected / emphasized border (solid slate-1200) |
 | `--input`                   | `border-input`            | Input resting state border (aliases `--border-subtle-default`) |
-| `--ring`                    | `ring-ring` / `border-ring` | Focus ring and focus border color (coral-700) |
+| `--ring`                    | `ring-ring`                 | Focus ring color (blue-800 `#1789E1` — chosen to clear WCAG 1.4.11's 3:1 minimum on both light and dark surfaces; see issue #38). Pair with `ring-2 ring-offset-2 ring-offset-primary-surface`, not `border-ring` |
 
 ### 2.6 — Supporting Colors
 
@@ -182,7 +183,7 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 | Subtle hover tint              | `bg-primary/[0.08]`   |
 | Medium highlight               | `bg-primary/[0.16]`   |
 | Selected/active tint           | `bg-primary/10`       |
-| Status tint backgrounds        | `bg-success/10`, `bg-error/10`, `bg-warning/10`, etc. |
+| Status tint backgrounds        | `bg-warning/10`, `bg-info/10`, `bg-success/10`, `bg-error/10` (all utilities); or the foundation tints `bg-[var(--background-success-default)]` / `bg-[var(--background-error-default)]` |
 
 ### 2.8 — Interactive States
 
@@ -225,6 +226,8 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 <div className="transition-colors duration-fast ease-standard">...</div>
 ```
 
+**Reduced motion:** the base layer includes a global `@media (prefers-reduced-motion: reduce)` rule that collapses all `animation-duration` / `transition-duration` to `0.01ms` and forces `scroll-behavior: auto` for every element. This is automatic — components using the duration/easing tokens above don't need to add anything extra. If you hand-roll a custom animation outside these tokens (e.g. a raw `@keyframes` or a JS-driven animation library), you must independently respect `prefers-reduced-motion` since the CSS rule only overrides CSS-driven animations/transitions.
+
 ### 2.10 — Primitive Alpha Scales
 
 > Raw alpha (opacity) variants. These are **internal CSS variables only** — not exposed as Tailwind utility classes. Reference them only from semantic or component tokens, never directly in components.
@@ -274,7 +277,7 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 | `--primitive-emerald-alpha-*`| `oklch(0.725 0.150 166.0)` | Real-account highlights                |
 | `--primitive-cherry-alpha-*`| `oklch(0.571 0.229 18.2)`  | Reserved                               |
 
-> The `--overlay` semantic token resolves to `--primitive-black-50` (black at 0% — effectively transparent). For modal backdrops, use `bg-overlay` which is handled by the semantic layer.
+> The `--overlay` semantic token resolves to black at 50% opacity (via the `--overlay` CSS variable). Use `bg-overlay` for modal/dialog/sheet/drawer backdrops — do not manually reconstruct it with `bg-black/50`. The alpha-stop number in the primitive scale naming convention (e.g. `alpha-50`) refers to the palette stop index, not the opacity percentage; the actual opacity is defined separately in the semantic token.
 
 ---
 
@@ -285,8 +288,8 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 | IF you need to...                      | THEN use                          | NEVER use                              |
 | -------------------------------------- | --------------------------------- | -------------------------------------- |
 | Pick a primary CTA button color        | `bg-primary`                      | Green, blue, or any other color for primary CTA |
-| Show SUCCESS / profit / positive       | `text-success` (foundation)       | Primary coral for profit               |
-| Show ERROR / negative                  | `text-error` (foundation)         | Any non-token red                      |
+| Show SUCCESS / profit / positive       | `text-success`                    | Primary coral for success, non-token green |
+| Show ERROR / negative                  | `text-error`                      | Primary coral for error, non-token red |
 | Show WARNING / caution                 | `text-warning`                    | Raw orange hex or primary tint         |
 | Color a tab container background       | `bg-tabs`                         | `bg-secondary-surface` for tabs        |
 | Color an active/selected tab           | `bg-tabs-active`                  | `bg-primary-surface` for active tab    |
@@ -301,10 +304,11 @@ import { Button, Card, Tag } from "@deriv-ds/design-intelligence-layer"
 | Add a default border                   | `border-default`                  | Solid black borders, raw hex           |
 | Add a selected/strong border           | `border-selected`                 | —                                      |
 | Style an input (resting)               | `border-input`                    | Solid colored backgrounds              |
-| Style an input (focused)               | `border-ring` + `ring-[3px] ring-ring/50` | Generic shadows on inputs       |
+| Style an interactive element (focused) | `ring-2 ring-ring ring-offset-2 ring-offset-primary-surface` | `ring-ring/50` (fails 3:1 contrast), generic shadows |
+| Style an input (focused)               | Border-based: `border-field-*-border-focus` (see Section 8.5 Input) | `ring-ring` on inputs — inputs use border, not ring, focus indication |
 | Pick a heading font                    | `font-display`                    | System fonts, raw font-family names    |
 | Pick a body font                       | `font-body`                       | Raw font-family names                  |
-| Style button text                      | `font-display font-semibold`, sentence case | `uppercase` on buttons, `font-bold` |
+| Style button text                      | `font-display font-extrabold`, sentence case | `uppercase` on buttons, `font-bold` |
 | Write white text on a dark surface     | `text-on-prominent-static-inverse`| `text-white` or raw white hex          |
 
 ---
@@ -368,7 +372,7 @@ These sizes differ from standard Tailwind defaults — use the design system val
 | Context                  | Class          | Weight              |
 | ------------------------ | -------------- | ------------------- |
 | Page headings            | `font-display` | `font-extrabold` (800) |
-| Button labels            | `font-display` | `font-semibold` (600), sentence case |
+| Button labels            | `font-display` | `font-extrabold` (800), sentence case |
 | Body text                | `font-body`    | `font-normal` (400) |
 | Tiny labels / decorative | `font-body`    | `font-medium` (500) |
 
@@ -434,13 +438,13 @@ The design system uses a custom radius scale (base = 10px). Use these named toke
 
 ### 6.3 — Button Typography & States
 
-All buttons: `font-display font-semibold` (600), sentence case (no `uppercase`, no `tracking-wide`).
+All buttons: `font-display font-extrabold` (800), sentence case (no `uppercase`, no `tracking-wide`).
 
 | State    | Behavior                                         |
 | -------- | ------------------------------------------------ |
 | Default  | Base styling per variant                         |
 | Hover    | Color shift per variant (see above)              |
-| Focus    | 3px ring with `ring-ring/50` opacity             |
+| Focus    | 2px `ring-ring` (full opacity, blue-800) + 2px `ring-offset-primary-surface` — clears WCAG 1.4.11 3:1 |
 | Pressed  | Pressed bg token per variant (e.g. `bg-button-primary-bg-pressed`) |
 | Loading  | `opacity-24`, `pointer-events-none`, `data-loading`, `aria-busy` — applies to all variants |
 | Disabled | Dedicated disabled tokens: `bg-button-disabled-normal-bg`, `text-button-disabled-normal-text` — not generic opacity |
@@ -544,8 +548,6 @@ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Dialog
 | Kbd | [simple] | KbdGroup |
 | Label | [simple] | — |
 | Link | [simple] | — |
-| Menubar | [complex] | MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSub, MenubarSubTrigger, MenubarSubContent, MenubarShortcut |
-| Modal | [complex] | ModalTrigger, ModalContent, ModalHeader, ModalFooter, ModalTitle, ModalDescription, ModalAction, ModalCancel, ModalMedia |
 | NativeSelect | [simple] | NativeSelectOption, NativeSelectOptGroup |
 | NavigationMenu | [complex] | NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport, navigationMenuTriggerStyle |
 | OTPField | [composed] | OTPFieldGroup, OTPFieldSlot, OTPFieldSeparator |
@@ -562,7 +564,7 @@ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Dialog
 | Sidebar | [complex] | SidebarProvider, SidebarTrigger, SidebarInset, SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarRail, useSidebar |
 | Skeleton | [simple] | — |
 | Slider | [simple] | — |
-| Sonner (Toaster) | [simple] | — (also import `toast` from `sonner`) |
+| Sonner (Toaster) | [simple] | — (the imperative `toast` is re-exported from the package: `import { Snackbar, toast } from "@deriv-ds/design-intelligence-layer"`) |
 | Spinner | [simple] | — |
 | Stepper | [simple] | — |
 | Switch | [simple] | — |
@@ -581,9 +583,9 @@ These are styling behaviors you can't discover from TypeScript types alone:
 
 | Component | Note |
 |-----------|------|
-| Button | `font-display font-semibold` (600), sentence case (no `uppercase`). Primary: `text-on-prominent-static-inverse`. Radius: `rounded-full` (pill). 4 variants: primary, secondary, tertiary, ghost |
+| Button | `font-display font-extrabold` (800), sentence case (no `uppercase`). Primary: `text-on-prominent-static-inverse`. Radius: `rounded-full` (pill). 4 variants: primary, secondary, tertiary, ghost |
 | Card | Flat by default (no shadow). Add elevation manually: `className="shadow-sm"` or use elevation tokens `var(--elevation-100)` through `var(--elevation-500)` |
-| Input | Resting: `border-input`. Focus: `border-ring` + `ring-[3px] ring-ring/50`. Radius: `rounded-sm` (6px) |
+| Input | Resting: `border-input`. Focus: border-based (`border-field-*-border-focus` + border-width step-up), no ring. Radius: `rounded-sm` (6px). **Variants:** `outline` (default), `fill`, `inverse` (sunken translucent fill + light foregrounds — for inputs ON a brand/coloured surface; also on `InputGroup`). **`readOnly`** renders a distinct borderless, softly-filled "display only" state (separate from the faded `disabled` state). |
 | Tooltip | Bubble: uses component tokens `--tooltip-bg-default` + `--tooltip-text-default`. Always wrap in `<TooltipProvider>` |
 | Sidebar | Menu buttons use `rounded-sm`. Selection: `bg-secondary-hover` + `text-primary` + `font-semibold` |
 | Breadcrumb | Active page: `text-primary font-medium`. Links: `text-subtle` |
@@ -595,7 +597,6 @@ These are styling behaviors you can't discover from TypeScript types alone:
 | Switch | Checked track: `bg-slider-range`. Checked thumb: `bg-primary` |
 | Slider | Thumb: square `rounded-[4px]`, `bg-primary`. Track range: `bg-slider-range` |
 | Dialog/Sheet | Footer buttons should use `size="md"`. Overlay: `bg-overlay` |
-| Menubar | Hover: `bg-primary/[0.08]`. Open state: `bg-primary/10` |
 | Toggle | Pressed: `bg-primary/10` + `border-primary` + `text-primary` |
 | Calendar | Selected: `bg-secondary-hover` + `text-primary font-bold`. Today: primary dot below date |
 
@@ -634,9 +635,9 @@ Landing page hero sections in multiple layout types.
 | Type 1 — Mobile | Single column stacked: text content centred above, image panel full-width below |
 | Type 2 — Desktop | Centred single-column: tagline pill + heading + body + single primary CTA with `<Icon name="arrow-right" />`; no image |
 
-**Components used:** `Button` (default `sm`, `secondary sm`); `<Icon name="arrow-up-right" />`, `<Icon name="arrow-right" />` (FontAwesome Pro via the `Icon` component)
+**Components used:** `Button` (default `sm`, `secondary sm`); `<Icon name="arrow-up-right" />`, `<Icon name="arrow-right" />` (`@deriv/quill-icons` via the `Icon` component)
 
-**Tokens used:** `bg-primary-surface`, `bg-secondary-surface`, `border-default`, `text-prominent`, `text-subtle`, `bg-success`, `rounded-xl`, `rounded-full`, `px-layout-margin-inline`, `gap-layout-gutter`, `py-24`, `text-5xl`, `font-semibold`, `font-display`, `tracking-tight`, `text-lg`, `font-body`, `text-sm`, `shadow-sm`, `max-w-2xl`
+**Tokens used:** `bg-primary-surface`, `bg-secondary-surface`, `border-default`, `text-prominent`, `text-subtle`, `bg-[var(--background-success-default)]`, `rounded-xl`, `rounded-full`, `px-layout-margin-inline`, `gap-layout-gutter`, `py-24`, `text-5xl`, `font-semibold`, `font-display`, `tracking-tight`, `text-lg`, `font-body`, `text-sm`, `shadow-sm`, `max-w-2xl`
 
 ---
 
@@ -652,18 +653,18 @@ Landing page hero sections in multiple layout types.
 | Using `text-on-decorative` | Use `text-subtle` |
 | Using `font-mono` expecting Inter | Use `font-display` or `font-body` |
 | Using `font-semibold` for headings | Use `font-extrabold` (800) for headings |
-| Using `font-bold` for buttons | Use `font-semibold` (600) for buttons |
+| Using `font-bold` or `font-semibold` for buttons | Use `font-extrabold` (800) for buttons |
 | Using `uppercase` on buttons | Buttons use sentence case (no `uppercase`) |
 | Using standard TW sizes for headings (e.g. `text-6xl` = 60px) | Use design system values (`text-6xl` = 64px in this system) |
 | Using `rounded-[4px]` or `rounded-[2px]` | Use `rounded-xs` (4px) or `rounded-2xs` (2px) |
 | Using small radius on buttons | Buttons use `rounded-full` (pill shape, 999px) |
-| Installing or importing `lucide-react` | Use `<Icon name="..." weight="..." />` (FontAwesome Pro) — catalog in `icon-reference.md` |
+| Installing or importing `lucide-react` | Use `<Icon name="..." weight="..." />` (`@deriv/quill-icons`) — catalog in `icon-reference.md` |
 | Adding `tailwind.config.js` | Tailwind v4 uses CSS config via the package |
 | Using `bg-gray-*`, `text-zinc-*`, etc. | Use semantic tokens only |
 | Using `bg-prominent`, `bg-card`, `bg-popover`, `bg-subtle` | Use `bg-primary-surface`, `bg-primary-canvas`, `bg-secondary-surface`, `bg-secondary-canvas` |
 | Using `text-on-prominent`, `text-on-subtle` | Use `text-prominent`, `text-subtle` |
 | Using `border-border-subtle`, `border-border-prominent` | Use `border-default`, `border-selected` |
-| Using `text-semantic-win`, `text-semantic-loss` | Use foundation tokens or component tokens for status colors |
+| Using `text-semantic-win`, `text-semantic-loss` | Use the status utilities `text-success` / `text-error` (or `text-warning` / `text-info`) |
 
 ---
 

package/guides/rules/design-system-consuming-project.mdc

@@ -12,7 +12,13 @@ alwaysApply: true
 
 ### Available components (check this list first)
 
-Accordion, Alert, AlertDialog, Avatar, AvatarGroup, Badge, Breadcrumb, Button, Calendar, Card, Carousel, Chart, Checkbox, Collapsible, Combobox, Command, ContextMenu, Dialog, Drawer, DropdownMenu, EmptyState, Field, Form, HoverCard, Input, InputGroup, InputOTP, Item, Kbd, Label, Menubar, NativeSelect, NavigationMenu, Pagination, Popover, Progress, RadioGroup, Resizable, ScrollArea, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Spinner, Switch, Table, Tabs, Textarea, Toast/Toaster, Toggle, ToggleGroup, Tooltip
+Accordion, AlertDialog, Avatar, AvatarGroup, Badge, Breadcrumb, Button, Calendar, Card, Carousel, Chart, Checkbox, Collapsible, Combobox, Command, ContextMenu, Dialog, Drawer, DropdownMenu, Empty, Field, Form, HoverCard, Input, InputGroup, InputOTP, Item, Kbd, Label, Link, NativeSelect, NavigationMenu, NotificationBanner, Pagination, Popover, Progress, RadioGroup, Resizable, ScrollArea, SectionMessage, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Sonner (Toaster), Spinner, Stepper, Switch, Table, Tabs, Tag, Textarea, Toggle, ToggleGroup, Tooltip
+
+> **No `Alert` / `Banner` component.** For an inline status/alert message use `SectionMessage`. For a dismissible banner bar use `NotificationBanner`. Never invent an `Alert` or `Banner` import.
+
+### Complexity — ask before building with `[complex]` components
+
+Each component in the design guide (Section 8) is tagged `[simple]` (drop-in, one import), `[composed]` (has required sub-components — use the full pattern), or `[complex]` (significant state/setup). Before building with a `[complex]` component, **ask the user clarifying questions first** rather than guessing at configuration. The `[complex]` set is: Calendar, Carousel, Chart, Combobox, Command, Dialog, Drawer, Field, Form, NavigationMenu, Resizable, Sheet, Sidebar.
 
 ### Decision flow
 
@@ -41,10 +47,10 @@ import { Button, Card, Badge } from "@deriv-ds/design-intelligence-layer"
 ### Never use
 
 ```
-❌ Hardcoded hex:         #2323FF, #000000, rgba(0,0,0,0.5)
+❌ Hardcoded hex:         #FF444F, #000000, rgba(0,0,0,0.5)
 ❌ Raw Tailwind palette:  bg-gray-100, text-zinc-500, text-slate-400, bg-black, bg-white
-❌ Arbitrary color:       bg-[#EEEEEE], text-[rgba(35,35,255,0.1)]
-❌ Raw CSS var:           bg-[var(--border-subtle)]  ← NEVER do this
+❌ Arbitrary color:       bg-[#EEEEEE], text-[rgba(255,68,79,0.1)]
+❌ Raw CSS var:           bg-[var(--border-subtle)]  ← NEVER do this (exception: the success/error status vars below)
 ❌ hsl(var()) syntax:     hsl(var(--primary))  ← this is Tailwind v3, not v4
 ❌ Raw opacity on non-tokens: bg-black/50
 ```
@@ -53,41 +59,45 @@ import { Button, Card, Badge } from "@deriv-ds/design-intelligence-layer"
 
 #### Background tokens
 ```
-✅ bg-prominent           — page background (white #FFFFFF)
-✅ bg-card                — card/panel surface (white #FFFFFF)
-✅ bg-popover             — popover/dropdown surface (white #FFFFFF)
-✅ bg-subtle              — subtle tinted surface (#F5F5F5)
+✅ bg-primary-canvas      — main page / canvas background
+✅ bg-primary-surface     — card/panel/modal surface
+✅ bg-card / bg-popover   — alias bg-primary-surface (cards, dropdowns)
+✅ bg-secondary-surface   — subtle / muted surface
+✅ bg-secondary-canvas    — secondary canvas area
 ✅ bg-overlay             — modal/dialog backdrop (black 50%) — ONLY for overlays
-✅ bg-primary             — brand blue #2323FF — CTAs and primary actions
-✅ bg-primary-hover       — darker blue #0B0BD2 — primary button hover
-✅ bg-secondary-hover     — light grey #EEEEEE — outline/secondary button hover
-✅ bg-win                 — green — profit/positive
-✅ bg-loss                — red — loss/negative
+✅ bg-primary             — brand coral #FF444F — CTAs and primary actions
+✅ bg-primary-hover       — darker coral #E12E3A — primary button hover
+✅ bg-secondary-hover     — light grey — outline/secondary button hover
+✅ bg-tabs / bg-tabs-active — tab container / active tab background
 ```
+> Do NOT use `bg-prominent` or `bg-subtle` as backgrounds — those classes map to TEXT foreground values.
 
 #### Text tokens
 ```
-✅ text-on-prominent                — primary text (black #000000)
+✅ text-prominent                   — primary text (headings, body)
 ✅ text-on-prominent-static-inverse — always white — for text on dark/primary bg
-✅ text-on-subtle                   — secondary text (mid grey)
+✅ text-subtle                      — secondary text (descriptions, labels)
 
-✅ text-primary                     — brand blue #2323FF
-✅ text-win                         — green — profit/positive
-✅ text-loss                        — red — loss/negative
+✅ text-primary                     — brand coral #FF444F
+✅ text-warning / text-info / text-success / text-error — the four status text utilities (theme-aware, opacity-friendly: bg-success/10)
+✅ text-on-primary / text-on-success / text-on-error / text-on-warning / text-on-info — foreground on a SOLID coloured surface
 ```
+> All four status text utilities exist (`text-warning`, `text-info`, `text-success`, `text-error`). The older `text-[var(--text-success-default)]` / `text-[var(--text-error-default)]` form still resolves (the package's own blocks use it) but prefer the bare utilities in new code.
+> Use `text-on-*` foregrounds ONLY on the solid brand/status colour (`bg-primary`, `bg-success`, …). On a status *tint* (`bg-success/10`) use `text-success` / `text-error` instead.
+> `text-on-prominent` still resolves but is ALWAYS-WHITE (for dark surfaces), not page body text — use `text-prominent`.
 
 #### Border tokens
 ```
-✅ border-border-subtle    — light grey #EEEEEE — default UI borders, dividers, cards
-✅ border-border-prominent — pure black #000000 — outline variant components
-✅ border-border           — @deprecated alias for border-subtle (still works, prefer border-border-subtle)
-✅ border-input            — input field borders (same value as border-subtle)
-✅ ring-ring               — focus ring (blue #2323FF)
+✅ border-default          — default UI borders, dividers, cards (slate @ 16% alpha)
+✅ border-selected         — selected / emphasized / outline components (solid slate-1200)
+✅ border-input            — input field borders
+✅ ring-ring               — focus ring (blue #1789E1 — WCAG 3:1 on light + dark; pair with ring-2 + ring-offset-2 ring-offset-primary-surface)
 ```
+> `border-border-subtle` / `border-border-prominent` / `border-border` still resolve (deprecated aliases) — prefer `border-default` / `border-selected` in new code.
 
 #### Opacity on a token is fine
 ```
-✅ bg-primary/20, border-border-subtle/50, ring-ring/10
+✅ bg-primary/20, border-default/50, ring-ring/10
 ```
 
 ---
@@ -109,7 +119,7 @@ Token rules apply **only** to: color (bg, text, border, ring, shadow color), bor
 ## Rule 4 — Do NOT install or configure these separately
 
 ```
-❌ Do NOT install or import lucide-react or any icon library — use the package's <Icon /> component (FontAwesome Pro): <Icon name="bell" weight="bold" />. Catalog + weight conventions: guides/design-system-guide/icon-reference.md
+❌ Do NOT install or import lucide-react or any icon library — use the package's <Icon /> component (@deriv/quill-icons): <Icon name="bell" weight="bold" />. Catalog + weight conventions: guides/design-system-guide/icon-reference.md
 ❌ Do NOT install tailwindcss separately — the package ships its own Tailwind v4 setup
 ❌ Do NOT add a tailwind.config.js — configuration is handled by the package
 ❌ Do NOT use @apply with hsl(var(--token)) — Tailwind v4 uses CSS variables directly
@@ -141,20 +151,22 @@ Without this, Tailwind CSS will not process any styles. Next.js projects do NOT
 
 ### Button variants
 ```tsx
-<Button variant="primary" />    // Blue filled — main CTA
-<Button variant="secondary" />  // Black outline, white bg — secondary actions
-<Button variant="tertiary" />   // Text only, underline on hover — minimal
+<Button variant="primary" />    // Coral filled — main CTA
+<Button variant="secondary" />  // Outline, transparent bg — secondary actions
+<Button variant="tertiary" />   // Text only — minimal
+<Button variant="ghost" />      // Transparent, hover tint — lowest emphasis
 ```
+> All buttons are pill-shaped (`rounded-full`) and use `font-display font-extrabold` (800), sentence case.
 
 ### Badge variants
 ```tsx
 // Solid
-<Badge variant="default" />         // Blue solid
+<Badge variant="default" />         // Brand solid
 <Badge variant="default-success" /> // Green solid
 <Badge variant="default-fail" />    // Red solid
 
 // Tint
-<Badge variant="fill" />            // Blue tint bg
+<Badge variant="fill" />            // Brand tint bg
 <Badge variant="fill-success" />    // Green tint bg
 <Badge variant="fill-fail" />       // Red tint bg
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deriv-ds/design-intelligence-layer",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Deriv Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/styles.css

@@ -74,6 +74,26 @@
 
   --color-warning: var(--text-warning-default);
   --color-info: var(--text-information-default);
+  /* Status colour utilities — mirror warning/info: theme-aware, opacity-friendly.
+   * `text-success` / `text-error` (status text), `bg-success/10` etc. (status tint). */
+  --color-success: var(--text-success-default);
+  --color-error: var(--text-error-default);
+  /* ── Paired foregrounds for text/icons ON a solid coloured surface ──
+   * Use ONLY with the SOLID brand/status colour (bg-primary, bg-success, bg-error,
+   * bg-warning, bg-info). On a status *tint* (bg-success/10, bg-[var(--background-success-default)])
+   * use the status text colour (text-success / text-error) instead. All resolve to the
+   * always-legible static-inverse foreground — additive only, no component is rewired. */
+  --color-on-primary: var(--on-prominent-static-inverse);
+  --color-on-success: var(--on-prominent-static-inverse);
+  --color-on-error: var(--on-prominent-static-inverse);
+  --color-on-warning: var(--on-prominent-static-inverse);
+  --color-on-info: var(--on-prominent-static-inverse);
+  /* Opaque status surfaces (bg-success-surface, bg-error-surface, …) — solid
+   * status tints that don't bleed on coloured backgrounds. See LAYER 2A. */
+  --color-success-surface: var(--background-success-opaque);
+  --color-error-surface: var(--background-error-opaque);
+  --color-warning-surface: var(--background-warning-opaque);
+  --color-info-surface: var(--background-information-opaque);
   --color-alert-info-text: var(--alert-info-text);
   --color-alert-info-border: var(--alert-info-border);
   --color-alert-error-text: var(--alert-error-text);
@@ -329,6 +349,13 @@
   --color-field-fill-border-focus:       var(--field-fill-border-focus);
   --color-field-fill-border-success:     var(--field-fill-border-success-focus);
   --color-field-fill-border-error:       var(--field-fill-border-error-focus);
+  /* Field — inverse variant (input on brand/coloured surfaces) */
+  --color-field-inverse-bg-default:      var(--field-inverse-bg-default);
+  --color-field-inverse-bg-hover:        var(--field-inverse-bg-hover);
+  --color-field-inverse-bg-focus:        var(--field-inverse-bg-focus);
+  --color-field-inverse-text:            var(--field-inverse-text);
+  --color-field-inverse-subtle:          var(--field-inverse-subtle);
+  --color-field-inverse-border-focus:    var(--field-inverse-border-focus);
   /* ── Snackbar colour bridges ── */
   --color-snackbar-bg-default:  var(--snackbar-bg-default);
   --color-snackbar-bg-fail:     var(--snackbar-bg-fail);
@@ -757,6 +784,17 @@
   --background-pressed-static-light: var(--primitive-slate-alpha-200); /* #181C25 @ 16% */
   --background-primary-canvas: var(--primitive-slate-75); /* #F6F7F8 */
   --background-primary-surface: var(--primitive-slate-50); /* #FFFFFF */
+  /* ── Derived opaque status surfaces ──
+   * Solid (non-alpha) status tints that read identically on ANY background — no
+   * bleed-through when placed over a coloured card/hero (unlike the alpha
+   * background-*-default tints). Built with color-mix; inputs are theme-aware so
+   * the value recomputes automatically under .dark (lazy custom-property
+   * resolution), hence a single :root definition covers both themes. Exposed as
+   * bg-success-surface / bg-error-surface / bg-warning-surface / bg-info-surface. */
+  --background-success-opaque: color-mix(in oklch, var(--text-success-default) 12%, var(--background-primary-canvas));
+  --background-error-opaque: color-mix(in oklch, var(--text-error-default) 12%, var(--background-primary-canvas));
+  --background-warning-opaque: color-mix(in oklch, var(--text-warning-default) 12%, var(--background-primary-canvas));
+  --background-information-opaque: color-mix(in oklch, var(--text-information-default) 12%, var(--background-primary-canvas));
   --background-secondary-canvas: var(--primitive-slate-50); /* #FFFFFF */
   --background-secondary-surface: var(--primitive-slate-75); /* #F6F7F8 */
   --background-selected-default: var(--primitive-slate-alpha-100); /* #181C25 @ 8% */
@@ -1111,8 +1149,10 @@
   /* coral-800 (#E12E3A) — brand hover, same in both themes */
   --secondary-hover: var(--background-secondary-surface);
   /* TODO PR 3 — replace with button.secondary-normal-bg-hover when component tokens ship */
-  --ring: var(--primitive-coral-700);
-  /* coral-700 — brand colour, same in both themes */
+  /* Focus indicator. Figma spec is blue #2c9aff (blue-700), but that is only ~2.93:1 on
+     white; blue-800 #1789e1 keeps the hue and clears WCAG 1.4.11 3:1 in both light
+     (~3.68:1) and dark (~4.08:1). Paired with a 2px ring + 2px surface offset. See issue #38. */
+  --ring: var(--primitive-blue-800);
   --overlay: var(--primitive-black-50);
   /* TODO — no dedicated overlay foundation token; keeping primitive alias. Revisit when overlay token ships. */
   --semantic-error: var(--text-error-default);
@@ -1218,12 +1258,24 @@
 @layer base {
   * {
     border-color: var(--color-default);
-    outline-color: color-mix(in oklch, var(--color-ring) 50%, transparent);
+    /* Full opacity: a 50% alpha ring fails the 3:1 WCAG 1.4.11 focus-indicator minimum. See issue #38. */
+    outline-color: var(--color-ring);
   }
 
   body {
     @apply bg-primary-surface text-prominent font-sans antialiased;
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
 }
 
 /* ── Snackbar: dark mode override via :root.dark (specificity 0,1,1 beats :root 0,0,1) ── */
@@ -1597,6 +1649,15 @@
   --field-fill-border-focus: var(--primitive-slate-1200);
   --field-fill-border-success-focus: var(--primitive-green-900);
   --field-fill-border-error-focus: var(--primitive-red-900);
+  /* Field — inverse: sunken translucent fill for inputs placed ON a brand/coloured
+   * surface (hero cards, banners) where a light fill would blend in. Theme-agnostic
+   * (the surface behind is coloured, not the page), so the light and dark values match. */
+  --field-inverse-bg-default: var(--primitive-black-alpha-400); /* 32% black */
+  --field-inverse-bg-hover: var(--primitive-black-alpha-500); /* 40% black */
+  --field-inverse-bg-focus: var(--primitive-black-alpha-500); /* 40% black */
+  --field-inverse-text: var(--primitive-slate-50); /* white */
+  --field-inverse-subtle: var(--primitive-white-alpha-600); /* 48% white — label/placeholder/icons */
+  --field-inverse-border-focus: var(--primitive-white-alpha-500); /* 40% white */
 
   /* Marker */
   --marker-text-asterisk: var(--primitive-red-900);
@@ -2474,6 +2535,15 @@
   --field-fill-border-focus: var(--primitive-slate-50);
   --field-fill-border-success-focus: var(--primitive-green-500);
   --field-fill-border-error-focus: var(--primitive-red-500);
+  /* Field — inverse: sunken translucent fill for inputs placed ON a brand/coloured
+   * surface (hero cards, banners) where a light fill would blend in. Theme-agnostic
+   * (the surface behind is coloured, not the page), so the light and dark values match. */
+  --field-inverse-bg-default: var(--primitive-black-alpha-400); /* 32% black */
+  --field-inverse-bg-hover: var(--primitive-black-alpha-500); /* 40% black */
+  --field-inverse-bg-focus: var(--primitive-black-alpha-500); /* 40% black */
+  --field-inverse-text: var(--primitive-slate-50); /* white */
+  --field-inverse-subtle: var(--primitive-white-alpha-600); /* 48% white — label/placeholder/icons */
+  --field-inverse-border-focus: var(--primitive-white-alpha-500); /* 40% white */
 
   /* Marker */
   --marker-text-asterisk: var(--primitive-red-500);