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

package/.claude/skills/build/references/components-and-tokens.md

@@ -0,0 +1,490 @@
+# Components & tokens — `@deriv-ds/design-intelligence-layer`
+
+This is the **authoritative cheatsheet** for building in a consuming project, verified against the published package (v0.6.2). If something isn't here and isn't in the package's `dist/index.d.ts`, it doesn't exist — resolve it with the Token Resolution Loop (for styles) or compose it from real components (for UI). Never invent an import or a class. (The `npm run check:skill-catalog` script in the source repo guards this list against the package's real exports.)
+
+> **Verification targets** (the package ships compiled — there is NO `src/index.ts`):
+> - Components → `node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts`
+> - Tokens / variables / primitives → `node_modules/@deriv-ds/design-intelligence-layer/src/styles.css`
+
+---
+
+## Canonical component list (importable from the package)
+
+```tsx
+import {
+  // Layout & structure
+  Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, CardAction,
+  AspectRatio,
+  ScrollArea, ScrollBar,
+  ResizablePanelGroup, ResizablePanel, ResizableHandle,   // NOTE: no bare `Resizable`
+  Separator,
+  Sidebar, SidebarContent, SidebarFooter, SidebarHeader, SidebarGroup, SidebarGroupLabel,
+  SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarProvider,
+  SidebarTrigger, SidebarInset, SidebarRail, SidebarSeparator,
+
+  // Forms & input
+  Input,
+  PhoneInput,
+  EmailOrPhoneInput,
+  InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea,
+  SearchField,
+  InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator,
+  CodeInput, CodeInputGroup, CodeInputSlot, CodeInputSeparator,
+  Textarea,
+  Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator,
+  NativeSelect, NativeSelectOption, NativeSelectOptGroup,
+  Combobox, ComboboxInput, ComboboxTrigger, ComboboxContent, ComboboxItem, ComboboxList,
+  ComboboxValue, ComboboxEmpty, ComboboxGroup, ComboboxLabel, ComboboxChip, ComboboxChips,
+  Checkbox, CheckboxField,
+  RadioGroup, RadioGroupItem, RadioGroupField,
+  Switch,
+  Toggle,
+  ToggleGroup, ToggleGroupItem,
+  SegmentedControl, SegmentedControlList, SegmentedControlTrigger, SegmentedControlContent,
+  Slider,
+  Label,
+  Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend,
+  FieldSeparator, FieldSet, FieldTitle,
+  Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage,
+
+  // Navigation
+  Button,
+  SocialButton,                                            // social-login button (provider variants), from button.tsx
+  Link,
+  Tab, TabList, TabTrigger, TabContent,                   // NOTE: singular — Tabs/TabsList/TabsTrigger/TabsContent do NOT exist
+  Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis,
+  Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious,
+  PaginationEllipsis, PaginationBullets,
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, DropdownMenuLabel,
+  DropdownMenuSeparator, DropdownMenuGroup, DropdownMenuCheckboxItem, DropdownMenuRadioGroup,
+  DropdownMenuRadioItem, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger,
+  ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger, ContextMenuSeparator,
+  Command, CommandDialog, CommandInput, CommandList, CommandItem, CommandGroup, CommandEmpty,
+  CommandSeparator, CommandShortcut,
+  Stepper,
+
+  // Overlays & surfaces
+  Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DialogClose,
+  Drawer, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, DrawerClose,
+  Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, SheetClose,
+  Popover, PopoverContent, PopoverTrigger, PopoverAnchor, PopoverHeader, PopoverTitle, PopoverDescription,
+  HoverCard, HoverCardContent, HoverCardTrigger,
+  Tooltip, TooltipContent, TooltipProvider, TooltipTrigger,
+
+  // Feedback & status
+  Badge, BadgeDot,
+  Chip,
+  Tag,
+  NotificationBanner, NotificationItem, NotificationDivider,   // NOTE: no bare `Notification`
+  SectionMessage, SectionMessageTitle, SectionMessageDescription,
+  Snackbar,
+  Spinner,
+  LoadingSpinner,
+  Skeleton,
+  Progress,
+  Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle,
+
+  // Data display
+  Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, TableFooter,
+  Calendar, CalendarDayButton,
+  Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,
+  ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent,   // NOTE: no bare `Chart`
+  ListItem, ListItemTitle, ListItemDescription, ListItemContent, ListItemIcon, ListItemMedia,
+  ListItemActions, ListItemFlag, ListItemFooter, ListItemGroup, ListItemHeader, ListItemSeparator,
+  Accordion, AccordionContent, AccordionItem, AccordionTrigger,
+  Collapsible, CollapsibleContent, CollapsibleItem, CollapsibleTrigger,
+
+  // Utility
+  Avatar, AvatarFallback, AvatarImage, AvatarBadge, AvatarGroup, AvatarGroupCount,
+  Kbd, KbdGroup,
+  DirectionProvider,                                       // NOTE: no bare `Direction`; hook is `useDirection`
+} from "@deriv-ds/design-intelligence-layer"
+
+// Helpers & hooks
+import { cn, useIsMobile, useDirection, useSidebar, useFormField } from "@deriv-ds/design-intelligence-layer"
+```
+
+**Anything NOT exported from `dist/index.d.ts` does not exist in the package.** To prove an export exists:
+
+```bash
+grep -w "<ComponentName>" node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts
+# zero hits = doesn't exist → use the closest real component or compose one
+```
+
+### ⚠ Commonly hallucinated imports — look valid, don't exist
+
+| ❌ Doesn't exist | ✅ Real export |
+|---|---|
+| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | `Tab`, `TabList`, `TabTrigger`, `TabContent` |
+| `Resizable` | `ResizablePanelGroup` + `ResizablePanel` + `ResizableHandle` |
+| `Notification` | `NotificationBanner` / `NotificationItem` |
+| `Chart` | `ChartContainer` (+ `ChartTooltip`, `ChartLegend`) |
+| `Direction` | `DirectionProvider` / `useDirection` |
+
+### ⚠ In the source tree but NOT exported — do not import
+
+These files exist under `components/ui/` in the source repo but are **not** re-exported from the package, so they are not importable by consumers. Treat them as nonexistent and compose the equivalent from real exports:
+
+- `theme-toggle` (`ThemeToggle`) — compose from `Button` + `Switch` + `<Icon />`.
+
+> `NavigationMenu*` (`NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuViewport`) **is now a real export** — prefer the `Navbar` / nav blocks for app navigation, but the primitive is available when you need a custom menu. Verify with `grep -w NavigationMenu node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts` against the installed version.
+
+### Secondary exports (real, but rarely imported directly)
+
+Exported and valid, but niche — only reach for them when you specifically need them: `ChartStyle` (internal to the Chart family), `IconSizeContext` (advanced `<Icon />` sizing). Most builds never touch these.
+
+---
+
+## Icons
+
+Icons come from the package's `<Icon />` component (a wrapper over `@deriv/quill-icons`). **Never install or import `lucide-react` or any other icon library.** Import `Icon` from the package and pass a `name` (plus optional `weight`):
+
+```tsx
+import { Icon } from "@deriv-ds/design-intelligence-layer"
+
+<Icon name="arrow-right" />                                  // default weight: bold
+<Icon name="chevron-down" weight="regular" className="size-4 text-subtle" />
+<Icon name="circle-check" weight="fill"    className="size-4 text-success" />
+```
+
+Three weights: `regular` (thin — subtle/unselected), `bold` (medium outline — the default, most UI), `fill` (solid — selected/strong actions). The full name catalog lives at `node_modules/@deriv-ds/design-intelligence-layer/guides/design-system-guide/icon-reference.md`; `ICON_NAMES` and `iconAvailableWeights(name)` are exported from the package at runtime.
+
+Use an icon ONLY when the Figma frame / design actually shows that glyph — match it to the closest catalog `name`, and never substitute a "close enough" icon for an exported Figma asset.
+
+---
+
+## Token cheatsheet — use these classes ONLY
+
+> Every class below maps to a `--color-*` entry in the package's `src/styles.css` `@theme inline`
+> block — that is the ONLY thing that makes a utility class real in Tailwind v4. A class with no
+> `--color-*` definition produces **no CSS** and silently inherits the wrong colour.
+>
+> **Existence proof for any colour class** (`bg-X` / `text-X` / `border-X` / `ring-X` → token name `X`):
+> ```bash
+> grep -- "--color-X:" node_modules/@deriv-ds/design-intelligence-layer/src/styles.css
+> # zero hits = the class does NOT exist → use a real token or register one (see Token Creation)
+> ```
+
+### ⚠ Background vs text tokens — the #1 trap
+
+`prominent` and `subtle` are **text / foreground** colours, not surfaces:
+
+- `--color-prominent → var(--text-prominent-default)` = #181C25 (near-black). So **`bg-prominent` paints near-black** — it's an *inverse* surface for dark elements, NOT a white page background.
+- **Page / surface backgrounds are a separate family:** `bg-card`, `bg-primary-canvas`, etc.
+
+**Never use `bg-prominent` / `bg-subtle` as a page or header background.** Map the Figma
+variable `component/app/background/normal` (`#ffffff`) → **`bg-card`**.
+
+### Backgrounds (surfaces)
+
+| Class | Use | Value (light) |
+|---|---|---|
+| `bg-card` | page / card / panel surface — **the default white background** | #FFFFFF |
+| `bg-primary-surface` | white surface (alias of `bg-card`) | #FFFFFF |
+| `bg-primary-canvas` | neutral page canvas (app shell behind cards) | #F6F7F8 |
+| `bg-secondary-surface` | subtle muted surface | #F6F7F8 |
+| `bg-secondary-canvas` | alternate canvas | #FFFFFF |
+| `bg-popover` | popover / dropdown surface | #FFFFFF |
+| `bg-prominent` | **inverse (near-black) surface only** — tooltips, inverted chips. NOT a page bg | #181C25 |
+| `bg-overlay` | modal backdrop only | black 50% |
+| `bg-primary` | brand primary (CTAs) — **coral** | #FF444F |
+| `bg-primary-hover` | primary hover | coral-800 |
+| `bg-secondary-hover` | outline / secondary hover | #F6F7F8 |
+
+### Text
+
+| Class | Use | Value (light) |
+|---|---|---|
+| `text-prominent` | primary text — **near-black** (NOT `text-on-prominent`, which doesn't exist) | #181C25 |
+| `text-subtle` | secondary / description text | #181C25 @ 48% |
+| `text-on-prominent-static-inverse` | always white — text on coral / dark / inverse surfaces | #FFFFFF |
+| `text-primary` | brand text — coral | #FF444F |
+| `text-warning` | warning text | #C47D00 |
+| `text-info` | informational text | #0777C4 |
+| `text-success` | success text — green | #007A22 light / #4DBC6B dark |
+| `text-error` | error / danger text — red | #C40000 light / #FF4D4D dark |
+| `text-on-primary` / `text-on-success` / `text-on-error` / `text-on-warning` / `text-on-info` | foreground for text/icons **on a solid coloured surface** (`bg-primary`, `bg-success`, …) — always-legible static-inverse | #FFFFFF |
+
+### Status colours — now built in
+
+`text-success`, `text-error`, `text-warning`, `text-info` are **shipped utilities** (theme-aware —
+they flip automatically in dark mode). Their solid `bg-*` / `border-*` / `ring-*` counterparts also
+generate (`bg-success`, `bg-error`, `border-success`, …) and pair with the `text-on-*` foregrounds
+above. For a **subtle opaque status tint** that reads identically on any background (cards, chips,
+banners) use the surface utilities:
+
+| Class | Use |
+|---|---|
+| `bg-success-surface` / `bg-error-surface` / `bg-warning-surface` / `bg-info-surface` | opaque status tint background (color-mix — no bleed-through on coloured surfaces) |
+| `bg-success/10`, `bg-error/16`, … | alpha status tint (fine on the page canvas; can bleed on coloured surfaces) |
+
+Only **game-specific profit/loss** utilities (`text-win`, `text-loss`, `bg-win`, `bg-loss`) are NOT
+shipped — register those with the Token Creation pattern below (map to `--text-success-default` /
+`--text-error-default`). Never use a raw green/red hex or `text-green-600`.
+
+### Borders & ring
+
+| Class | Use | Value (light) |
+|---|---|---|
+| `border-border-subtle` | default UI borders, dividers, cards | #181C25 @ 8% |
+| `border-border-prominent` | outline-variant components, heavier dividers | #181C25 @ 16% |
+| `border-default` | global default border | #181C25 @ 16% |
+| `border-input` | input field borders | #181C25 @ 8% |
+| `border-selected` | selected-state border (solid dark) | #181C25 |
+| `ring-ring` | focus ring — **coral** | #FF444F |
+
+> `border-border` is deprecated — use `border-border-subtle` or `border-border-prominent`.
+> `border-success` / `border-error` now generate (solid status colour) alongside `bg-success` / `bg-error`.
+
+### Radius
+
+`--radius-xs`, `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl` are defined → use
+`rounded-xs` … `rounded-xl`. Never `rounded-[Npx]` — if a Figma radius matches no step, register a
+radius token (Token Creation pattern) instead.
+
+### ⚠ Commonly hallucinated classes — look valid, don't exist, render the WRONG colour
+
+These pass the forbidden-pattern grep (they look like semantic tokens) but have no `--color-*`
+definition, so they produce **no CSS** — the element silently inherits a wrong colour:
+
+| ❌ Doesn't exist | ✅ Real fix |
+|---|---|
+| `text-on-prominent` | `text-prominent` (`text-on-prominent` is always-white — for dark/coloured surfaces only) |
+| `text-on-subtle` | `text-subtle` |
+| `bg-loss` / `text-loss` / `bg-win` / `text-win` | register first (game profit/loss — see Status colours above), then use |
+| `bg-prominent` (as page bg) | `bg-card` |
+| `bg-subtle` (as page bg) | `bg-card` / `bg-primary-canvas` |
+| `text-heading-h1`, `text-body-md`, `text-heading-mega` | `heading-h1`, `body-md`, `heading-hero` (see Typography) |
+
+**Runtime tell:** a token-intended element whose computed `background-color` is `rgba(0,0,0,0)` or
+whose text colour inherited instead of applying = hallucinated class.
+
+---
+
+## Token Creation — registering tokens the package doesn't ship
+
+When a design value has no existing utility class, NEVER inline it and NEVER stop the build.
+Register a token in the consuming project's `globals.css` (after the DS imports) and use the
+generated class. Resolution order — first match wins:
+
+1. **Existing semantic token** from the tables above → use it directly.
+2. **Package semantic variable** (theme-aware — flips in dark mode automatically). Find it in
+   `src/styles.css` (`--text-*-default`, `--background-*-default`, etc.):
+   ```css
+   @theme inline { --color-success: var(--text-success-default); }
+   ```
+3. **Package primitive** (1294 of them: `--primitive-coral-700`, `--primitive-slate-1200`,
+   `--primitive-blue-500`, …). Grep the resolved hex to find it:
+   ```bash
+   grep -i "#1A2233" node_modules/@deriv-ds/design-intelligence-layer/src/styles.css
+   ```
+   ```css
+   @theme inline { --color-brand-coral: var(--primitive-coral-700); }  /* → bg-brand-coral */
+   ```
+   ⚠ Primitives are static — they do NOT flip in dark mode. Prefer step 2 when a semantic var exists.
+4. **Exact hex, centralized** — only when no package variable resolves to the design's value.
+   The hex lives in ONE place (the theme), never in JSX:
+   ```css
+   @theme inline { --color-figma-hero-overlay: #1A2233; }  /* → bg-figma-hero-overlay */
+   ```
+
+Naming: follow the package's convention — `--color-<intent>` (e.g. `--color-success`,
+`--color-brand-coral`), not `--color-green` or `--color-1A2233`. Same pattern applies to radius
+(`--radius-<name>`) and font sizes. **Every registered token must be listed in the Build Report.**
+
+Referencing a primitive or raw var **inline** is still forbidden — `bg-[var(--primitive-coral-700)]` never; register, then use the class.
+
+---
+
+## Forbidden patterns — never write these
+
+```
+❌ #FF444F, #000000, rgba(0,0,0,0.5)        — hex / rgba in JSX or class names (even brand coral — use bg-primary)
+❌ bg-gray-100, text-zinc-500, bg-red-500,
+   text-blue-600, bg-amber-100, bg-black     — ANY raw Tailwind palette, every hue
+❌ bg-[#EEEEEE], text-[rgba(...)]            — arbitrary colour values
+❌ bg-[var(--border-subtle)]                 — raw CSS var inline (register a token instead)
+❌ hsl(var(--primary))                       — Tailwind v3 syntax
+❌ rounded-[12px]                            — arbitrary radius (use rounded-xs…xl or register)
+❌ font-[...] / style={{fontFamily}}         — font-family overrides (use font-display / font-body)
+❌ bg-prominent as a page/header background  — near-black inverse surface (see trap above)
+❌ bg-black/50                               — raw opacity on non-token (backdrop → bg-overlay)
+```
+
+### Opacity on a real token is fine
+
+```
+✅ bg-primary/20, border-border-subtle/50, ring-ring/10
+```
+
+### Layout utilities — exempt from token rules
+
+```
+✅ flex, grid, gap-4, p-6, m-2, w-full, h-screen, max-w-lg
+✅ p-[18px], gap-[12px], w-[327px]            — exact px from Figma auto-layout (fidelity!)
+✅ z-50, overflow-hidden, opacity-50, transition-all
+✅ col-span-2, items-center, justify-between
+```
+
+Token rules apply **only** to: colour (bg, text, border, ring, shadow colour), border radius, and
+font family. Spacing/sizing should use the **exact values from the design** — arbitrary px values
+are encouraged there when the Figma auto-layout values don't match a Tailwind step.
+
+---
+
+## Button variants
+
+```tsx
+<Button variant="primary" />    // Coral filled — main CTA
+<Button variant="secondary" />  // Black outline, white bg — secondary action
+<Button variant="tertiary" />   // Text only, underline on hover — minimal
+```
+
+Sizes: `lg` (48px), `md` (40px, default), `sm` (32px), plus `icon-lg | icon-md | icon-sm`.
+Tones: `normal`, `inverse`, `static-light`, `static-dark`.
+
+## Badge variants
+
+```tsx
+// Solid
+<Badge variant="default" />          // Coral (brand)
+<Badge variant="default-success" />  // Green
+<Badge variant="default-fail" />     // Red
+
+// Tint
+<Badge variant="fill" />             // Coral tint bg
+<Badge variant="fill-success" />     // Green tint bg
+<Badge variant="fill-fail" />        // Red tint bg
+
+// Outline (black border, hover grey)
+<Badge variant="outline" />
+
+// Ghost (transparent bg)
+<Badge variant="ghost" />
+<Badge variant="ghost-success" />
+<Badge variant="ghost-fail" />
+```
+
+---
+
+## Blocks — importable from the package
+
+Blocks ship as named exports — **import them directly, never re-implement.** Matching a page region to a block is the **Block Matching gate** in the build skill: if a region in a Figma frame or a text prompt corresponds to a block below, import that exact block and tune it to the content — do NOT mock up a look-alike. Only compose from primitives + tokens when **no** block matches, and flag the composition in the Build Report. Never invent a block import name.
+
+```tsx
+import { Navbar, HeroDesktopMain, Section, TradingAccountCard, Referral } from "@deriv-ds/design-intelligence-layer"
+// Navbar is responsive: sidebar on desktop (≥768px), bottom bar on mobile (<768px).
+// For explicit control, NavMobileBottomBar and NavDesktopSidebar are also exported.
+```
+
+The **"matches when"** column is what the Block Matching gate matches on — intent, not pixels.
+
+| Region | Import(s) | Matches when (prompt or frame shows…) |
+|---|---|---|
+| **Navbar** | `Navbar` (responsive) · `NavMobileBottomBar` · `NavDesktopSidebar` | top/side nav, nav menu, sidebar nav, bottom tab bar, "navbar" / "nav menu" |
+| **Header** | `HeaderApp` · `HeaderAppHome` · `HeaderBranding` | app top header strip, branded header bar, "header" |
+| **Hero — home** | `HeroMobileHomeTitle` · `HeroMobileHomeTotalAssets` · `HeroDesktopHomeOnboarding` · `HeroDesktopHomeWithBalance` | home top area: greeting/title, total-assets/balance header, onboarding hero |
+| **Hero — main/secondary/transaction** | `HeroMobileMain` · `HeroDesktopMain` · `HeroMobileSecondary` · `HeroDesktopSecondary` · `HeroMobileTransaction` | primary/secondary page hero, transaction hero |
+| **Hero action button** | `HeroActionButton` | the prominent action button(s) sitting inside a hero |
+| **Home — banner** | `HomeBanner` · `BannerCard` | promo / announcement banner card on home |
+| **Home — highlights** | `HomeHighlights` · `HomeHighlightCard` | row/grid of highlight cards, "highlights" |
+| **Home — explore** | `HomeExploreDeriv` | "explore Deriv" discovery section |
+| **Trading — account card** | `TradingAccountCard` | account card with balance + actions |
+| **Trading — action buttons** | `TradingActionButtonsPrimary` · `TradingActionButtonsSecondary` (+ `…Skeleton`) | deposit/withdraw/transfer action button cluster |
+| **Trading — empty** | `TradingEmpty` (+ `TradingEmptySkeleton`) | empty trading list / no-accounts state |
+| **Account activated card** | `AccountActivatedCard` | "account activated" confirmation card |
+| **Feedback / success** | `FeedbackSuccessScreen` · `FeedbackTradeWithAccounts` · `FeedbackTransferSuggestion` | success screen, post-action confirmation/feedback |
+| **Referral** | `Referral` | refer-a-friend / invite panel |
+| **Section** | `Section` | eyebrow tag + title + control cluster + segmented control wrapping a content slot (children) |
+
+Most heroes/trading blocks also export a `*Skeleton` variant for loading states.
+
+### Default app shell — home/dashboard pages
+
+**Home and dashboard pages ship a default app shell even when the prompt/frame never mentions it:** a header block on top + `Navbar`. The build skill's Block Matching gate injects these automatically (see SKILL.md → *App Shell defaults*). Skip only on explicit user opt-out, or for marketing/auth/standalone screens.
+
+| Shell region | Block | Wire |
+|---|---|---|
+| Top header | `HeaderAppHome` (home) / `HeaderApp` (in-app sub-page) | avatar, notification badge, actions |
+| Navigation | `Navbar` (responsive) | `activeId`, `badges`, `onNavChange` |
+
+### Mobile / desktop variant pairing — render BOTH viewports
+
+Blocks target **both** a mobile (~375px) and desktop (~1440px) viewport. Some blocks are responsive on their own; others ship as an explicit mobile/desktop pair with **no** single responsive export — render BOTH and switch on the **768px** breakpoint with `md:hidden` (mobile) / `hidden md:block` (desktop), mirroring how `Navbar` picks its variant internally. Resolve BOTH variants of every paired region before writing JSX. Render a single viewport only when the user restricts scope.
+
+| Region | Mobile | Desktop | Responsive? |
+|---|---|---|---|
+| Navigation | `NavMobileBottomBar` | `NavDesktopSidebar` | **Yes — use `Navbar`** (auto-switches) |
+| Hero — home (title) | `HeroMobileHomeTitle` | `HeroDesktopHomeOnboarding` | No — pair + `md:` switch |
+| Hero — home (balance) | `HeroMobileHomeTotalAssets` | `HeroDesktopHomeWithBalance` | No — pair + `md:` switch |
+| Hero — main | `HeroMobileMain` | `HeroDesktopMain` | No — pair + `md:` switch |
+| Hero — secondary | `HeroMobileSecondary` | `HeroDesktopSecondary` | No — pair + `md:` switch |
+| Hero — transaction | `HeroMobileTransaction` | *(reuse mobile / compose)* | No |
+| Section | `Section` | `Section` | Yes — same export |
+| Trading / home cards | responsive via `layout` prop where present | — | Prefer `layout` prop |
+
+New blocks favour a single `layout="mobile" \| "desktop"` prop over separate exports — check the block's props in `dist/index.d.ts` before assuming a pair.
+
+---
+
+## Typography
+
+The package defines **bare utility classes** in `styles.css` (no `text-` prefix):
+
+- Families: `font-display` / `font-body` (Inter loads automatically with the DS styles import)
+- Headings: `heading-hero`, `heading-h1`, `heading-h2`, `heading-h3`, `heading-h4`, `heading-h5`, `heading-h6`
+- Body: `body-xl`, `body-lg`, `body-md`, `body-sm`, `body-xs`
+
+```tsx
+<h1 className="heading-h1 text-prominent">Title</h1>
+<p className="body-md text-subtle">Description</p>
+```
+
+⚠ `text-heading-h1`, `text-body-md`, `text-heading-mega` do NOT exist — they render at the browser
+default size. Never override `font-family` manually in CSS. When a Figma text style doesn't match a
+scale step exactly, start from the closest `heading-*`/`body-*` class and override the deltas with
+standard utilities (`font-extrabold`, `text-[18px]`, `leading-[24px]`, `tracking-[-0.2px]`) — size,
+weight, line-height, and letter-spacing are NOT colour tokens, so exact values from Figma are
+allowed and preferred for fidelity. Only `font-family` itself is locked to `font-display`/`font-body`.
+
+---
+
+## Intentional DS behaviours — do NOT "fix" these
+
+- The **focus ring** on `Select`, `Input`, `SelectTrigger`, etc. (`ring-ring`, coral, shown on
+  `:focus-visible`) is built into the package as WCAG focus indication. It is **expected** — do
+  not remove it, override it to `ring-0`, or flag it as a bug.
+
+---
+
+## Quick install reference
+
+```bash
+npm install @deriv-ds/design-intelligence-layer
+```
+
+```css
+/* The @source path is RELATIVE TO THIS CSS FILE — count the directories up to the project root: */
+
+/* app/globals.css (Next.js, no src dir) */
+@import "@deriv-ds/design-intelligence-layer/styles";
+@import "tailwindcss";
+@source "../node_modules/@deriv-ds/design-intelligence-layer/dist";
+
+/* src/app/globals.css (Next.js with --src-dir) */
+@import "@deriv-ds/design-intelligence-layer/styles";
+@import "tailwindcss";
+@source "../../node_modules/@deriv-ds/design-intelligence-layer/dist";
+
+/* src/index.css (Vite) */
+@import "@deriv-ds/design-intelligence-layer/styles";
+@import "tailwindcss";
+@source "../node_modules/@deriv-ds/design-intelligence-layer/dist";
+```
+
+**Verify the path resolved:** if DS component internals render unstyled (e.g. a Button with no
+fill), the `@source` path is wrong — Tailwind found no classes to generate. Fix the `../` count.
+
+Vite-only: add `@tailwindcss/vite` to `vite.config.ts`. Next.js needs no extra config.
+
+**Do NOT** install `lucide-react`, `tailwindcss`, or create a `tailwind.config.js` — these are handled by the package.

package/.cursor/commands/build.md

@@ -0,0 +1,3 @@
+Build UI strictly from the `@deriv-ds/design-intelligence-layer` package — pages, screens, and components.
+
+First read and follow **`.claude/skills/build/SKILL.md`** in this repo and every file it links under `.claude/skills/build/references/`. Execute exactly as that skill specifies — package imports only, token-only styling, Figma visual fidelity, and the accessibility checklist.

package/.kiro/steering/build.md

@@ -0,0 +1,6 @@
+---
+inclusion: manual
+---
+Build UI strictly from the `@deriv-ds/design-intelligence-layer` package — pages, screens, and components.
+
+First read and follow **`.claude/skills/build/SKILL.md`** in this repo and every file it links under `.claude/skills/build/references/`. Execute exactly as that skill specifies — package imports only, token-only styling, Figma visual fidelity, and the accessibility checklist.

package/AGENTS.md

@@ -10,7 +10,7 @@ Before building any landing page, product screen, game view, or feature UI, you
 
 **Design principles** — the decision framework for every layout, hierarchy, motion, copy, and component choice:
 ```
-node_modules/@deriv-ds/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** — the inclusion standard every screen must meet (WCAG 2.1 AA):
@@ -48,12 +48,34 @@ node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-cons
 cp node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc .cursor/rules/
 ```
 
+**Claude Code users:** The package also ships a `build` skill that enforces these rules during every UI build. Copy it into your project (re-copy after each upgrade), then invoke it with `/build`:
+
+```bash
+mkdir -p .claude/skills && cp -R node_modules/@deriv-ds/design-intelligence-layer/.claude/skills/build .claude/skills/
+```
+
+**Cursor users:** Copy the shipped `/build` command shim (points at the `.claude/skills/build/` copy above, so copy that first):
+
+```bash
+mkdir -p .cursor/commands
+cp node_modules/@deriv-ds/design-intelligence-layer/.cursor/commands/build.md .cursor/commands/build.md
+```
+
+**Kiro users:** Copy the shipped `#build` steering doc the same way:
+
+```bash
+mkdir -p .kiro/steering
+cp node_modules/@deriv-ds/design-intelligence-layer/.kiro/steering/build.md .kiro/steering/build.md
+```
+
+Re-copy both after every version bump so the shims match the installed release.
+
 ---
 
 ## Step 3 — Core rules summary
 
 1. **Check before building** — if a component exists in `@deriv-ds/design-intelligence-layer`, import it. Never re-implement it.
-2. **Tokens only** — use semantic token classes (`bg-prominent`, `text-on-prominent`, `border-border`, etc.). Never hardcode hex values, raw Tailwind palette colors, or CSS variables.
+2. **Tokens only** — use semantic token classes (`bg-primary-canvas`, `text-prominent`, `border-default`, etc.). Never hardcode hex values, raw Tailwind palette colors, or CSS variables.
 3. **Design principles and accessibility first** — every screen must reflect the 8 design principles and meet the accessibility standards (WCAG 2.1 AA). Run both checklists before shipping.
 4. **No separate installs** — do not install `tailwindcss` or other bundled dependencies separately. Never install or import `lucide-react` or any other icon library.
 5. **Icons** — use the exported `<Icon />` component (`@deriv/quill-icons`): `<Icon name="bell" weight="bold" />`. Three weights: `regular` (unselected nav, subtle), `bold` (default), `fill` (selected nav, strong actions). Full catalog of names, weights, and intent → icon mappings: `guides/design-system-guide/icon-reference.md`. At runtime, `ICON_NAMES` and `iconAvailableWeights(name)` are exported from the package.
@@ -80,7 +102,7 @@ cp node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-c
 ## Reference
 
 - Full token + component reference: `node_modules/@deriv-ds/design-intelligence-layer/README.md`
-- Design principles: `node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md`
+- Design principles: `node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/quill-design-principles.md`
 - Accessibility standards: `node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md`
 - Personas: `node_modules/@deriv-ds/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md`
 - Brand voice: `node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/deriv-brand-voice.md`

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2]
+
+### Fixed
+- **Focus ring contrast (WCAG 1.4.11 / 2.4.7)** — the base focus outline was rendered at 50% alpha and the `--ring` token (coral-700) fell well under the 3:1 minimum once composited. `--ring` is now blue-800 (`#1789e1`), rendered at full opacity, and every component's `focus-visible` ring is standardized to `ring-2 ring-ring ring-offset-2 ring-offset-primary-surface` — verified at ≥3:1 against both light and dark surfaces, and against coral primary buttons via the offset gap. (#38)
+- **`prefers-reduced-motion` support** — added a global `@media (prefers-reduced-motion: reduce)` rule that collapses animation/transition durations and disables smooth scrolling package-wide. (#38)
+- **Stale agent-facing docs** — corrected `AGENTS.md`'s design-principles path (was pointing at a non-existent file) and refreshed ring-color references in the consuming-project rules and design-system guides to match the shipped coral/blue theme. (#38)
+
+## [0.6.1]
+
+### Note
+- **`0.6.0` was published in error** by a tag pushed against the wrong commit before the skills PR was merged — it contains the old pre-merge codebase mislabeled as `0.6.0` and has been deprecated on npm. `0.6.1` is the real release of everything listed below; no code changes from `0.6.0`'s intended content, only the correct commit and version number.
+
+## [0.6.0]
+
+### Added
+- **Three AI agent skills**, runnable from Claude Code, Cursor, and Kiro:
+  - `build` — **npm-published**, for package consumers. Builds pages/screens/components strictly from the published package (text prompt, Figma link, or pasted block), enforcing token-only styling, the Block Matching gate, and an accessibility checklist. Ends with an independent critic pass and an offer to open a PR.
+  - `component` — **source-repo only**, for extending the design system. Authors a new UI primitive end-to-end (component file, package export, playground page, nav wiring, and consumer docs), with a dedupe gate against the existing catalog.
+  - `block` — **source-repo only**, for extending the design system. Authors a new composite Block end-to-end (block file, package export, playground page, nav wiring, and the `build` skill's block catalog), with the same dedupe gate and critic pass.
+- **Cross-agent shims** — `.cursor/commands/{build,component,block}.md` (Cursor `/build`, `/component`, `/block`) and `.kiro/steering/{build,component,block}.md` (Kiro `#build`, `#component`, `#block`), all pointing at the same canonical `SKILL.md` files so every agent runs identical rules. Only the `build` shims are published to npm — `component`/`block` shims live in this repo only, alongside the skills they invoke.
+- **Skill catalog drift guard** — `npm run check:skill-catalog` (wired into CI) fails the build if a component/block is exported but missing from the `build` skill's catalog, or documented in the catalog but not actually exported — keeping the Block Matching gate from ever hand-rolling a look-alike of a shipped block.
+- **Skills foundation page** in the playground, documenting all three skills, their guardrails (dedupe-first, independent critic audit, bounded loops, idempotent edits, ask-then-PR), and how to invoke them per agent.
+
 ## [0.5.2]
 
 ### Added
@@ -57,7 +80,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - Patched CVE-2026-53550 and CVE-2026-49356 (dependency bumps).
 
-[Unreleased]: https://github.com/deriv-com/design-intelligence-layer/compare/v0.5.1...HEAD
+[Unreleased]: https://github.com/deriv-com/design-intelligence-layer/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/deriv-com/design-intelligence-layer/compare/v0.5.2...v0.6.1
 [0.5.1]: https://github.com/deriv-com/design-intelligence-layer/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/deriv-com/design-intelligence-layer/compare/v0.4.5...v0.5.0
 [0.4.5]: https://github.com/deriv-com/design-intelligence-layer/releases/tag/v0.4.5