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

package/.claude/skills/build/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: build
+description: Build Deriv UI strictly from the @deriv-ds/design-intelligence-layer npm package — pages, screens, and components. Triggers when the user mentions "@deriv-ds/design-intelligence-layer" or the Deriv design system, asks to bootstrap/build a project with it, asks to build a page/screen/component in a project where the package is installed, pastes a figma.com URL to build with the Deriv design system, or pastes a code block importing from @deriv-ds/design-intelligence-layer or @/components/ui. Do NOT trigger for generic build requests unrelated to Deriv or this package.
+---
+
+# build
+
+Build pages and screens with `@deriv-ds/design-intelligence-layer` — Deriv's npm-published design system. This skill handles four modes: **bootstrap** a fresh project, **build from a text prompt**, **build from a Figma link**, and **integrate a pasted block**.
+
+**The sole goal: every build comes strictly from the package — its components, its tokens, its primitives. Figma builds must be 1:1 replicas of the frame. Never invent components, classes, copy, or layout.**
+
+---
+
+## HARD RULES — never violate these
+
+1. **Components come from the package.** Every import must exist in `node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts` (the package ships compiled — there is NO `src/index.ts`). The canonical list is in [references/components-and-tokens.md](references/components-and-tokens.md), including the **commonly hallucinated imports** table (`Tabs` → `Tab`, `Notification` → `NotificationBanner`, etc.). If the design needs an element with no package component, **compose it from package components + tokens** (like the Blocks pattern) — never invent an import, never pull in another UI library, and flag the composition in the Build Report.
+
+2. **Every colour/radius/font-family value resolves through the Token Resolution Loop (below).** Raw values never appear in JSX or class names. Forbidden everywhere:
+   - hex / rgba literals (`#FFFFFF`, `rgba(0,0,0,.5)`) — even brand coral
+   - raw Tailwind palette, ANY hue (`bg-gray-*`, `bg-red-500`, `text-blue-600`, `bg-black`, `bg-white`, …)
+   - arbitrary colour values (`bg-[#EEE]`, `text-[rgba(...)]`, `bg-[var(--anything)]`)
+   - `hsl(var(--x))` (Tailwind v3 syntax)
+   - arbitrary radius (`rounded-[12px]`) and `font-family` overrides
+
+   When no existing token fits, **create one** (loop step 2–4) — do not stop, do not ask, do not silently substitute a wrong-but-existing token.
+
+3. **Imports come from `@deriv-ds/design-intelligence-layer`.** Icons use the package's `<Icon />` component (`import { Icon } from "@deriv-ds/design-intelligence-layer"`) — it wraps `@deriv/quill-icons`. **Never install or import `lucide-react` or any other icon library.** Never import from local `@/components/ui/*` paths (playground-internal) and never from the older `@deriv-com/quill-ui*`.
+
+4. **Don't install bundled deps** — no separate `tailwindcss`, no `tailwind.config.js`, no `lucide-react`. Tailwind v4 and the icon set (`@deriv/quill-icons`, surfaced via `<Icon />`) are already inside the package.
+
+5. **Blocks are importable — and matching a block is MANDATORY before you mock anything up.** The package ships whole sections as named exports — navbar, heroes, home banner/highlights/explore, trading cards/action-buttons/empty, referral, header, feedback screens, section wrapper (full catalog + "matches when" hints in [references/components-and-tokens.md](references/components-and-tokens.md)). Before composing from primitives or writing JSX for ANY page region, run the **Block Matching gate** (below): if a region in the design or the prompt corresponds to a block, you MUST import and use that exact block — never re-implement, re-mock, or eyeball a look-alike of something the package already ships. Only compose from primitives when the Block Matching gate finds no block for that region, and flag the composition in the Build Report. Never invent a block import name.
+
+6. **Figma builds are replicas, not interpretations** (Mode 4): no element in the build that isn't in the frame, no element in the frame missing from the build, no copy that isn't verbatim from the frame, no eyeballed spacing/sizes/weights — every value comes from the extracted design data.
+
+---
+
+## Token Resolution Loop — run for EVERY colour/radius/font value, in every mode
+
+For each value the design needs, resolve in order — **first match wins, never skip ahead to hardcoding, never stop to ask**:
+
+1. **Existing semantic token** — check the [token cheatsheet](references/components-and-tokens.md). Intent match, not just colour match: `component/app/background/normal` (#FFFFFF) → `bg-card`, NOT `bg-prominent`.
+
+2. **Package semantic variable** — `src/styles.css` ships theme-aware vars (`--text-success-default`, `--background-error-default`, …) that flip in dark mode. Register in the project's `globals.css`:
+   ```css
+   @theme inline { --color-success: var(--text-success-default); }  /* → text-success */
+   ```
+
+3. **Package primitive** — 1294 primitives (`--primitive-coral-700`, `--primitive-slate-1200`, …). Find by hex, then register:
+   ```bash
+   grep -i "#0777C4" node_modules/@deriv-ds/design-intelligence-layer/src/styles.css
+   ```
+   ```css
+   @theme inline { --color-brand-blue: var(--primitive-blue-900); }  /* → bg-brand-blue */
+   ```
+   ⚠ Primitives are static (no dark-mode flip) — prefer step 2 when a semantic var resolves to the same hex.
+
+4. **Exact value, centralized** — only when nothing in the package resolves to the design's value. Create the token with the exact Figma value; the raw value lives in ONE place (the theme), never in JSX:
+   ```css
+   @theme inline { --color-figma-hero-overlay: #1A2233; }  /* → bg-figma-hero-overlay */
+   ```
+
+Rules for created tokens: intent-based names following the package convention (`--color-<intent>`, `--radius-<name>`); registered after the DS imports in `globals.css`; **every created token is listed in the Build Report**. Referencing a primitive or var inline (`bg-[var(--primitive-…)]`) is still forbidden — register, then use the generated class. **Idempotent registration:** before adding a token, grep `globals.css` for an existing `--color-*` of the same intent/value and reuse it — never register a second token for a colour you already have.
+
+**Loop until zero unresolved values remain. The build may not start while any value is unresolved.** *Loop discipline (exit · bound · escalate):* this loop always terminates — step 4 (create an exact-value token) is available for any value, so there is no "unresolvable" case and no hardcoding fallback. The only escalation is ambiguous **intent** (you can't tell which semantic token the design means): stop and ask the user — do not guess a token.
+
+(Spacing, sizing, font-size/weight/line-height are NOT tokens — use the exact values from the design, including arbitrary px like `p-[18px]`, for fidelity.)
+
+---
+
+## Preflight — run before writing UI in EVERY build mode (3, 4, 5)
+
+Even when you're not bootstrapping, the app may have been scaffolded earlier with create-next-app defaults that silently break DS tokens and fonts. Before generating any page:
+
+```bash
+grep -rn "next/font\|geist\|--background:\|--foreground:\|prefers-color-scheme" app/ src/ 2>/dev/null
+grep -n "@source" app/globals.css src/app/globals.css src/index.css 2>/dev/null
+```
+
+If the first grep hits, fix it (same as Mode 2's "Clean the scaffold"):
+- Strip `next/font`/Geist imports from `layout.tsx`; ensure `<body className="bg-card text-prominent">`.
+- Remove default `:root --background/--foreground` and `@media (prefers-color-scheme: dark)` blocks from `globals.css` — leave only the DS `@import`/`@source` lines.
+
+For the second grep, **verify the `@source` path actually resolves** — it is relative to the CSS file: `../node_modules/...` from `app/globals.css`, but `../../node_modules/...` from `src/app/globals.css`. A wrong path means Tailwind generates NO classes for package internals — components render unstyled and the build looks broken even when the code is right.
+
+These leftovers cause near-black backgrounds and the wrong font even when the build code itself is correct.
+
+---
+
+## Page layout scaffold — match the design's actual placement
+
+**Replicate where the design puts each element — do NOT impose a layout pattern of your own.** In Figma mode especially, read the frame: are the action buttons *pinned to the bottom* of the viewport, or do they *flow inline* directly under the content? These need different scaffolds, and guessing wrong is a real defect.
+
+**A — Buttons flow inline below content** (most onboarding/form steps; the buttons sit right under the field with empty space beneath them):
+
+```tsx
+<main className="min-h-screen flex flex-col">
+  <header className="shrink-0">…</header>
+  <div className="flex flex-col …">…content…</div>      {/* NOT flex-1 */}
+  <div className="flex flex-col …">…actions…</div>       {/* flows directly under content */}
+</main>
+```
+
+**B — Action bar pinned to the bottom of the viewport** (only when the design clearly anchors it there):
+
+```tsx
+<main className="min-h-screen flex flex-col">
+  <header className="shrink-0">…</header>
+  <div className="flex-1 …">…scrolling body…</div>      {/* flex-1 pushes footer down */}
+  <footer className="shrink-0">…primary CTA…</footer>
+</main>
+```
+
+**How to distinguish A from B in a Figma frame (Mode 4):**
+- Pattern B requires the footer element to be explicitly **constrained/pinned to the bottom** in Figma — a "Fixed position" or a bottom-anchored auto-layout constraint. Confirm this in `get_design_context`.
+- **Trailing blank space below the action buttons is NOT a signal for Pattern B.** It means the frame has a fixed height with empty padding — the buttons still flow inline (Pattern A).
+- When the Figma frame shows no explicit bottom constraint on the action area, **default to Pattern A**. Using Pattern B when the design doesn't anchor the footer is always a layout defect.
+
+Rule: don't add `flex-1` to the body unless `get_design_context` confirms the footer is bottom-anchored. Either way, verify the primary CTA is visible in the default viewport and placed where the design shows it (see Final Checklist).
+
+---
+
+## Block Matching gate — run BEFORE composing or writing JSX, in Modes 3, 4, 5
+
+The package ships whole page sections as blocks. **Before you build any region from primitives, match it against the block catalog.** A region that corresponds to a shipped block must be *imported*, not mocked up — re-implementing a navbar, hero, or card the package already exports is a defect, even if your version "looks right".
+
+**Procedure — for every distinct region of the page (header strip, nav, hero/balance area, banner, highlight cards, trading cards, action buttons, empty state, referral panel, footer/section wrapper):**
+
+1. **Identify the region's intent** — not its pixels. "Top nav with menu items", "balance/total-assets header", "promo banner card", "row of highlight cards", "account card with balance + actions", "empty trading list", "referral invite panel". The intent is what you match on.
+2. **Look it up in the block catalog** ([references/components-and-tokens.md](references/components-and-tokens.md) → *Blocks* table, which lists each export with a "matches when" hint).
+3. **If a block matches → import and use it.** Resolve the responsive variant (mobile vs desktop hero, `Navbar` vs `NavMobileBottomBar`/`NavDesktopSidebar`) from the target viewport. Wire its props/children to the design's real content. Do NOT re-create its internals.
+4. **Read the block's real prop types before wiring — never guess prop names.** The catalog gives the export name and intent, not the signature. Look the block's type up in `node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts` (e.g. `grep -A30 "interface NavbarProps\|type NavbarProps\|NavbarProps =" node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts`) and pass exactly the props it declares. Inventing a prop that doesn't exist is as much a defect as hand-rolling the block.
+5. **If no block matches → compose from primitives + tokens** and flag the composition in the Build Report.
+
+**The gate runs per region, and blocks compose.** A page is normally several blocks together (`Navbar` + a `Hero*` + one or more `Section`s, plus primitives for the gaps), not one block. Finding a block for the nav doesn't end the matching — run the procedure for every region, assemble the matched blocks into the page layout, and only fill the leftover regions with composed primitives.
+
+**Two triggers for a match — both are mandatory:**
+
+- **Prompt / text signal (Mode 3, 5):** the user names or describes a region that maps to a block — "navbar", "nav menu", "sidebar nav", "bottom bar", "hero", "balance header", "banner", "highlights", "explore Deriv", "trading account card", "action buttons", "empty state", "referral", "header". Identify it and pull the block. Example: a "build the home page with a nav menu" prompt → import `Navbar`, do not hand-roll a nav.
+- **Figma signal (Mode 4):** a frame (or a node subtree) is visually/structurally the same as a shipped block — e.g. the frame's nav matches the `Navbar` block, the balance area matches a `HeroDesktopHome*`, a card matches `TradingAccountCard`. When `get_code_connect_map` already maps the Figma component to a block export, that mapping is binding. Otherwise match by structure + intent against the catalog. A matched region is imported as the block and tuned to the frame's content — **not** rebuilt node-by-node from the fidelity contract. (The contract still records the region; its "→ Resolution" column reads `block: <ExportName>`.)
+
+Record every region's outcome (`block: <Name>` or `composed`) — this feeds the Build Report's block audit.
+
+---
+
+## Mode 1 — Router
+
+When invoked, classify the user's message:
+
+- **`bootstrap`** — package not installed, or phrases like "set up", "new project", "install Deriv DS", "start with Deriv"
+- **`figma`** — message contains a `figma.com/design/...` URL
+- **`pasted-block`** — message contains a fenced code block importing from `@deriv-ds/design-intelligence-layer` or from `@/components/ui/*`, OR the user says "paste this block / build this navbar / integrate this hero" with code
+- **`text-prompt`** — natural-language page request ("login page", "settings page", "dashboard", "build me an X")
+
+Modes can compose on one turn (e.g. bootstrap → then text-prompt).
+
+If invoked as `/build` with no args, ask one question: **"What are you building?"** — landing, dashboard, onboarding, marketing, form-heavy (login/signup/KYC/settings), or trading interface.
+
+---
+
+## Mode 2 — Bootstrap
+
+Set up a fresh consuming project. Default to Next.js App Router.
+
+```bash
+npx create-next-app@latest <name> --typescript --tailwind --app --src-dir
+cd <name>
+npm install @deriv-ds/design-intelligence-layer
+```
+
+Wire the global stylesheet — REPLACE the existing Tailwind import block. **The `@source` path is relative to the CSS file**; with `--src-dir` (as scaffolded above) the file is `src/app/globals.css`, so it needs TWO levels up:
+
+```css
+/* src/app/globals.css (Next.js with --src-dir, as above) */
+@import "@deriv-ds/design-intelligence-layer/styles";
+@import "tailwindcss";
+@source "../../node_modules/@deriv-ds/design-intelligence-layer/dist";
+```
+
+```css
+/* app/globals.css (no src dir) — one level up */
+@source "../node_modules/@deriv-ds/design-intelligence-layer/dist";
+```
+
+A wrong `@source` path fails silently: Tailwind generates no CSS for package internals and every DS component renders unstyled. Verify after first render (Final Checklist).
+
+For **Vite** projects only, add `@tailwindcss/vite` to `vite.config.ts`. Next.js needs no extra config.
+
+Copy the package's `AGENTS.md` into the project root so other AI agents pick it up:
+
+```bash
+cp node_modules/@deriv-ds/design-intelligence-layer/AGENTS.md ./AGENTS.md
+```
+
+Generate a `CLAUDE.md` at project root pointing to the mandatory guides:
+
+```md
+# Project guidance
+
+This project uses `@deriv-ds/design-intelligence-layer`. Before building any UI, read:
+- `node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/deriv-brand-voice.md`
+- `node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc`
+
+Use the `build` skill for any "build me a page / build with this Figma / build this block" request.
+```
+
+**Clean the Next.js scaffold** (create-next-app ships defaults that fight DS token resolution):
+- In `src/app/layout.tsx` (or `app/layout.tsx`): remove `next/font` imports (Geist etc.) and the `className={…font…}` on `<html>`/`<body>`. Set `<body className="bg-card text-prominent">`. The DS styles import loads **Inter** automatically — per `guides/rules/design-system-consuming-project.mdc`, do NOT use `next/font` and do NOT override `font-family`.
+- In `globals.css`: after the DS import block, **delete** the default `:root { --background / --foreground }` declarations and the `@media (prefers-color-scheme: dark)` override that create-next-app emits — they shadow DS tokens. The file should be essentially just the three `@import`/`@source` lines.
+
+Run `npm run dev` and confirm with the running preview that the page background renders **white** (`bg-card`) and body text renders **near-black** (`text-prominent`) — verify the computed colours, don't assume the class names. (Reminder: `bg-prominent` is a near-black *text* token, not a white background — see [references/components-and-tokens.md](references/components-and-tokens.md).)
+
+If the user immediately follows with a build request, chain into the matching mode below.
+
+---
+
+## Mode 3 — Text prompt ("build me an X page")
+
+1. **Read the mandatory guides first** (per `AGENTS.md` Step 1):
+   - `node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/deriv-brand-voice.md`
+2. Read `node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc`.
+3. Read [references/components-and-tokens.md](references/components-and-tokens.md) for the canonical component list and token cheatsheet.
+4. **Run Preflight** (above) to clean any leftover Geist/font/`:root` scaffold defects.
+5. **Run the Block Matching gate** (above) over the page's regions FIRST — any region the prompt names or implies that maps to a block (nav/navbar, hero/balance header, banner, highlights, explore, trading cards, action buttons, empty state, referral, header) is imported as that block, not mocked up. Only the regions with no block match proceed to primitive composition.
+6. Map the remaining (non-block) regions to components. For each required UI element, confirm it's on the list (HARD RULE 1). Anything missing → compose from package components + tokens, flag in the Build Report.
+7. Sketch the layout structurally (flex/grid utilities are fine); if the page has a bottom action bar, use the **Page layout scaffold** above. Then drop in matched blocks and package components. Every colour/radius/font value goes through the **Token Resolution Loop**. Page background → `bg-card`, primary text → `text-prominent` (never `bg-prominent` as a surface). Typography → `heading-*`/`body-*` classes (NOT `text-heading-*`).
+8. Write copy in a voice aligned with `deriv-brand-voice.md`.
+9. Run the Final Checklist below.
+
+---
+
+## Mode 4 — Figma link → 1:1 replica
+
+Triggered by a `figma.com/design/...` URL. **The output is a replica of the frame, not an interpretation.** The three failure modes this mode exists to kill: invented/omitted elements, paraphrased copy, eyeballed spacing/weights.
+
+### 4.1 Extract — everything, before any code
+
+1. Confirm `mcp__figma__*` tools are available. **Run Preflight** (above).
+2. Parse the URL: extract `fileKey` and `nodeId` (convert `-` → `:` in nodeId).
+3. Call, in this order:
+   - `mcp__figma__get_metadata` — the **complete node tree** of the frame. This is the inventory; every visible node in it must appear in the contract below.
+   - `mcp__figma__get_design_context` — layout, auto-layout values, constraints, text content, styles.
+   - `mcp__figma__get_variable_defs` — design variables → resolved values.
+   - `mcp__figma__get_screenshot` — the visual ground truth for the diff loop in 4.4.
+   - `mcp__figma__get_code_connect_map` — any Figma component already mapped to a package component MUST use that mapping.
+
+### 4.1.5 Block Matching — before the contract
+
+**Run the Block Matching gate** (above) over the frame's regions before building the node-by-node contract. For each major region of the frame (nav, hero/balance header, banner, highlight cards, trading cards, action buttons, empty state, referral, header):
+
+- If `get_code_connect_map` maps that region's Figma component to a block export → **binding**, use that block.
+- Else, match the region's structure + intent against the block catalog ([references/components-and-tokens.md](references/components-and-tokens.md)). A frame nav that matches the `Navbar` block, a balance area that matches `HeroDesktopHome*`, a card that matches `TradingAccountCard` → **import the block and tune it to the frame's content; do NOT rebuild it node-by-node.**
+
+A region resolved to a block collapses to ONE contract row (`→ Resolution: block: <ExportName>`) — you do not enumerate its internal nodes. Only the regions with no block match expand into the full per-node contract in 4.2.
+
+### 4.2 Fidelity contract — every node, every value
+
+Build a table with one row per **visible node** from `get_metadata` (not just "key elements"). Columns:
+
+| Node | Type | Text (verbatim) | Fill/stroke (var → hex) | Font (size/weight/line-height) | Auto-layout (padding/gap/align) | Size (w×h) | Radius | → Resolution |
+
+- **Text is copied character-for-character** from the frame — headings, labels, placeholder text, microcopy, button labels. Never paraphrase, never "improve", never translate.
+- **Every fill/stroke** resolves through the **Token Resolution Loop** — record which step resolved it (semantic / registered-var / registered-primitive / registered-exact). Zero unresolved rows before writing JSX.
+- **Every text node** records the exact weight (`800/ExtraBold` → `font-extrabold`) and the closest `heading-*`/`body-*` scale class, with explicit overrides for any delta.
+- **Spacing comes from auto-layout values**, not from your eye: `padding: 18px` → `p-[18px]` (or `p-4` only when the value is exactly 16). Arbitrary px values are correct here — spacing is token-exempt.
+- **Components**: map each node to a package component (Code Connect mapping first, then name/shape match against the [canonical list](references/components-and-tokens.md) — beware the hallucinated-imports table). No match → compose from package components + tokens, flag it. (Regions already resolved to a block in 4.1.5 are not re-decomposed here.)
+- **Assets**: icons in the frame are matched to the exact package icon via `<Icon name="…" weight="…" />` (catalog: `node_modules/@deriv-ds/design-intelligence-layer/guides/design-system-guide/icon-reference.md`, or the `ICON_NAMES` export). Images are exported from Figma. Never substitute a "close enough" icon, and never reach for `lucide-react`.
+- **Placement**: decide layout scaffold A or B now, per the rules above.
+
+**Do not write a single line of JSX until every row is resolved.** Anti-invention check on the contract itself: every node in `get_metadata` has a row; no row exists for a node that isn't in the frame.
+
+### 4.3 Build
+
+Generate the page from the contract — the contract is the spec, the screenshot is the ground truth. Register all created tokens in `globals.css` first, then write JSX using only generated classes and package components.
+
+### 4.4 Visual-diff loop — iterate until it matches
+
+"Renders without errors" proves nothing about parity. With the dev server running:
+
+1. `preview_resize` the preview viewport to the **Figma frame's exact dimensions** (from `get_metadata`).
+2. `preview_screenshot` the render. Put it side-by-side with the Figma `get_screenshot`.
+3. Compare top-to-bottom, systematically: element presence and order · spacing rhythm · colours · font sizes/weights · copy · alignment · radii. List every deviation.
+4. Fix every deviation → re-screenshot → re-compare. **Repeat until no visible deviation remains**, up to 5 iterations. Anything still deviating after 5 passes is listed explicitly in the Build Report with the reason.
+5. Then run the per-row computed-style checks (Final Checklist) — screenshots catch layout drift; `preview_eval` catches hallucinated classes rendering transparent.
+
+If the preview MCP tools are unavailable, say so explicitly in the Build Report, verify what you can (`npm run build`, grep audits), and ask the user to compare against the frame — never silently skip the visual verification.
+
+### 4.5 Finish
+
+Run the Final Checklist (including the per-row fidelity verification) and present the Build Report.
+
+---
+
+## Mode 5 — Pasted block
+
+Triggered when the user pastes a code block and says something like "integrate this", "build this navbar into the page".
+
+0. **Run Preflight** (above) before integrating the block.
+1. Scan the imports in the pasted code:
+   - `@/components/ui/...` → REWRITE to `@deriv-ds/design-intelligence-layer` (the playground uses local paths; consuming projects MUST use the package — HARD RULE 3). Verify each rewritten import actually exists in `dist/index.d.ts` — playground code can reference internals the package doesn't export; recompose those from real exports.
+   - `@deriv-com/quill-ui*` → flag and ask; this is the older library.
+   - `lucide-react` (or any other icon lib) → HARD RULE 3: replace with the package's `<Icon />` (map each glyph to a name in the icon catalog).
+   - Anything else outside the package (except `react`) → HARD RULE 3: replace with package equivalents.
+2. Scan styles for forbidden patterns (hex, raw palette, arbitrary colour values, `hsl(var())`). Each hit → run the **Token Resolution Loop** (replace with semantic token, or register one).
+3. Ask the user **where the block goes**:
+   > "Where should this block live? (a) new route at `app/<name>/page.tsx`, (b) replace a section in an existing page, (c) extract into `components/<name>.tsx` and import where needed?"
+4. Wire any state the block expects (form state for hero CTAs, open/closed state for navbar drawers, etc.) using React hooks. Don't invent new stores.
+5. Run the Final Checklist.
+
+---
+
+## Final Checklist — run at the end of EVERY mode
+
+Before declaring done, verify:
+
+**Guardrail self-audit** — grep the generated/modified files for forbidden patterns. Any hit = stop and fix.
+
+```bash
+# From the project root, on the files you just touched:
+grep -nE '#[0-9a-fA-F]{3,8}\b' <changed-tsx-files>                          # hex anywhere in JSX (hex in globals.css @theme is OK)
+grep -nE '\b(bg|text|border|ring|from|to|via)-(gray|zinc|slate|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}\b' <changed-files>   # raw palette, every hue
+grep -nE '\b(bg|text|border|ring)-(black|white)\b' <changed-files>           # raw black/white
+grep -nE '(bg|text|border|ring)-\[(#|rgb|hsl|oklch|var)' <changed-files>     # arbitrary colour values / inline vars
+grep -nE 'hsl\(var\(|rounded-\[|font-family' <changed-files>                 # v3 syntax, arbitrary radius, font overrides
+```
+
+(`p-[18px]`, `gap-[12px]`, `text-[18px]`, `leading-[24px]` are fine — spacing/size are token-exempt.)
+
+**Token classes resolve** — the forbidden-pattern grep does NOT catch *hallucinated* token classes: ones that look semantic (`text-on-subtle`, `text-success` without registration, `text-heading-h1`) but have no definition, so they produce no CSS and the element silently inherits the wrong style. For every colour/`bg`/`text`/`border`/`ring` class in your diff, confirm it's in the [token cheatsheet](references/components-and-tokens.md) tables OR registered in this project's `globals.css`. To prove a class exists, check the **definition**, not usage:
+
+```bash
+# colour class bg-X / text-X / border-X → token --color-X must be defined:
+grep -- "--color-X:" node_modules/@deriv-ds/design-intelligence-layer/src/styles.css <project globals.css>
+# zero hits in both = hallucinated → fix via the Token Resolution Loop
+```
+
+The runtime check below is the backstop: a token-intended element whose computed `background-color` is `rgba(0,0,0,0)`, or whose text colour clearly inherited rather than applied, means a hallucinated class.
+
+**Blocks matched, not mocked** — every page region went through the Block Matching gate. No region hand-rolls a navbar, hero, card, banner, action-button cluster, empty state, or referral panel that the package already ships as a block. A region built from primitives must have NO matching block in the catalog — confirm before declaring done; this is recorded in the Build Report's block audit.
+
+**Import audit** — every import in the diff comes from `@deriv-ds/design-intelligence-layer`, including icons via `<Icon />`. No `lucide-react` or other icon lib. No `@/components/ui/*`. No `@deriv-com/quill-ui*`. Every imported name exists in `dist/index.d.ts` (beware `Tabs`/`Notification`/`Chart`/`Resizable`/`Direction` — see the hallucinated-imports table).
+
+**Created tokens registered** — every class generated by the Token Resolution Loop has its `@theme inline` registration in `globals.css`, named by intent, listed for the Build Report.
+
+**Build & render** — `npm run dev` builds without errors and the page renders. Use `preview_snapshot` to confirm structure and `preview_screenshot` to capture proof. If preview tools are unavailable, run `npm run build` and state in the Build Report that visual checks could not run.
+
+**Runtime visual verification** — "renders without errors" is NOT enough. With the preview running, use `preview_eval` to read computed styles and confirm:
+- The page/`<body>` background is the intended **light** surface (NOT near-black) — catches `bg-prominent`-as-background.
+- Body text computed `color` is dark-on-light (and white on any coral/inverse surface).
+- Computed `font-family` resolves to **Inter** — catches leftover Geist / `next/font`.
+- The **primary CTA element is within the viewport** (visible, not pushed below the fold) — catches an unanchored footer. (`getBoundingClientRect().bottom <= innerHeight`.)
+- Every element you styled with a colour token actually **got that colour** — its computed `background-color`/`color` is not transparent or inherited. A coral CTA reading `rgba(0,0,0,0)`, or a "subtle" caption reading solid near-black, means the class doesn't exist (hallucinated) — fix per "Token classes resolve" above.
+- DS component internals are styled (a default `Button` has a coral fill) — catches a wrong `@source` path.
+
+**Figma fidelity (Mode 4 only)** — the visual-diff loop (4.4) has converged, AND verify the render against the fidelity contract row by row with `preview_eval`:
+
+- **Colour** — `getComputedStyle(el).backgroundColor`/`color` matches the hex recorded in the contract. Transparent or near-black-when-it-shouldn't-be = wrong/hallucinated token → fix.
+- **Typography** — `fontWeight`/`fontSize` match the contract (e.g. `"800"` for ExtraBold). DS component defaults often ship `font-semibold` (600) — override when the spec differs.
+- **Copy** — `textContent` is verbatim from the frame.
+- **Placement** — `getBoundingClientRect()` puts each key element in the correct region; bottom-pinned CTAs at the bottom, inline CTAs directly under their preceding content.
+- **Completeness** — every contract row is rendered; nothing rendered lacks a contract row.
+
+Any mismatch is a defect — fix it before the Build Report. Every contract row must be explicitly marked ✅ matched or listed as a deviation.
+
+**Accessibility (WCAG 2.1 AA)** — focus states visible on every interactive element, contrast ratios meet AA, semantic HTML (`<main>`, `<nav>`, `<button>`), labels associated with inputs. Note: the package's built-in coral focus ring on fields is **expected** — keep it.
+
+**Bundled deps untouched** — no separate `tailwindcss`, `tailwind.config.js`, or `lucide-react` (or any icon lib) installs in `package.json` diff.
+
+**Copy** — Modes 2/3/5: reflects `deriv-brand-voice.md`, no banned phrases. Mode 4: verbatim from the frame (brand voice does NOT override the design's copy).
+
+**→ Next: run the Independent audit below, THEN present the Build Report.**
+
+---
+
+## Independent audit (critic pass) — REQUIRED before the Build Report
+
+You verified your own work in the same context that wrote it — confirmation bias lets hallucinated imports, unregistered tokens, and out-of-scope edits survive the self-checklist. Before the Build Report, get a **fresh pair of eyes**:
+
+- **Claude Code:** spawn a reviewer with the Task tool (general-purpose agent). It may read files and run `grep` / `npm run build` / `tsc`, but it MUST NOT edit — it only reports.
+- **Cursor / Kiro (no subagents):** do the audit yourself in a deliberately fresh pass — re-read each changed file and re-derive every fact from ground truth, ignoring your own build notes.
+
+Hand the reviewer ONLY the list of changed files (`git status`) plus the ground-truth sources. Use this prompt verbatim:
+
+> Independent reviewer; you did not write this code and must trust no claim about it. For the changed files `<list>`, verify ONLY the following and report each violation with `file:line` + the evidence you checked:
+> 1. Every name imported from `@deriv-ds/design-intelligence-layer` exists in `node_modules/@deriv-ds/design-intelligence-layer/dist/index.d.ts` (grep each name).
+> 2. No forbidden imports: `lucide-react`, `@fortawesome/*`, `@/components/ui/*`, `@deriv-com/quill-ui*`.
+> 3. Every colour class (`bg|text|border|ring-X`) has a real `--color-X` token in the package `styles.css` or the project `globals.css`.
+> 4. No forbidden style patterns: hex in JSX, raw Tailwind palette, raw black/white, arbitrary colour values, `hsl(var())`, arbitrary radius, `font-family`.
+> 5. Scope: `git status` shows only files this build was meant to touch — no unrelated edits.
+> Output **PASS** (zero violations) or a numbered violation list, each with `file:line`, the offending name/token, and your evidence. Do not propose fixes — just report.
+
+The critic re-derives the **Final Checklist** gates above independently; it does not invent new rules.
+
+**Loop:** any violation → fix the root cause → re-run the critic. Bound = **3 rounds**; if it still fails, list the remainder under the Build Report's "Needs your review" and stop. Never loop forever, never silently ship.
+
+---
+
+## Build Report — REQUIRED output of every build
+
+The build is not "done" until the runtime checks pass **and** you present this report to the user. Never end a build with just "done." Show:
+
+1. **Result** — a `preview_screenshot` (and the preview URL). In Mode 4, side-by-side with the Figma `get_screenshot`.
+
+2. **Token & Component Audit** — a table of every token class and component used, with confirmed evidence. No row may be left as "assumed". Use this format:
+
+   | Element | Class / Component | Status | Evidence |
+   |---|---|---|---|
+   | Page background | `bg-card` | ✅ confirmed | `--color-card` in styles.css |
+   | Primary CTA | `Button` | ✅ confirmed | export in dist/index.d.ts |
+   | Heading colour | `text-on-subtle` | ❌ hallucinated → replaced | no `--color-on-subtle` → swapped to `text-subtle` |
+   | Profit figure | `text-success` | 🆕 created | registered `--color-success: var(--text-success-default)` |
+   | Brand border | `border-brand-coral` | 🆕 created | registered `--color-brand-coral: var(--primitive-coral-700)` |
+
+   **Hallucinated classes must be fixed before this report is shown** — the table is proof they were caught and corrected, not a to-do list.
+
+3. **Block audit (Block Matching gate)** — one row per page region, proving each was matched against the block catalog and either imported as a block or consciously composed. A region that *should* have used a block but was hand-rolled is a defect — fix before showing this report.
+
+   | Region | Outcome | Evidence / reason |
+   |---|---|---|
+   | Top nav | `block: Navbar` | export in dist/index.d.ts; Code Connect map |
+   | Balance header | `block: HeroDesktopHomeWithBalance` | matched home balance hero |
+   | Promo strip | `composed` | no block matches a 2-up promo grid — flagged |
+
+4. **Created tokens** — every `@theme inline` registration added to `globals.css`, with which loop step produced it (semantic var / primitive / exact value) and whether it's dark-mode-aware.
+
+5. **Fidelity results (Mode 4)** — visual-diff loop: how many iterations, what was fixed each pass. Then the contract: every row ✅ matched or listed as a deviation with the reason. State explicitly: zero invented elements, zero omitted elements, copy verbatim.
+
+6. **⚠ Flagged** — composed (non-package) elements, token substitutions, assumptions made. If nothing was flagged, say so explicitly.
+
+7. **Intentional DS behaviours** — surface things that look like bugs but aren't (e.g. the coral focus ring on inputs), so the user doesn't try to "fix" them.
+
+8. **Needs your review** — anything uncertain or that you couldn't verify (e.g. preview tools unavailable), plus any critic violations still unresolved after 3 rounds.
+
+9. **Independent audit** — the critic verdict: how many rounds ran, and what it caught and you fixed (hallucinated imports, unregistered tokens, out-of-scope edits). If the critic could not run (no subagent + you did the fresh pass yourself), say so.
+
+---
+
+## Ship — open a PR (ask first)
+
+After the Build Report, offer to ship. Creating a PR is outward-facing — never do it without an explicit yes. (This runs in the consumer's own product repo, so keep branch/commit conventions generic and follow whatever the host repo already uses.)
+
+1. **Ask the user** (Claude Code: `AskUserQuestion`; Cursor / Kiro: a plain question): *"Create a PR for this build?"* — **Yes** / **No (leave it uncommitted)**.
+2. On **No** → stop; leave the working tree untouched and list the changed files so the user can commit later.
+3. On **Yes**:
+   a. **Branch** — if on the default/protected branch (`main`/`master`), create a feature branch (e.g. `feat/<page-or-feature-slug>`); if already on a feature branch, reuse it. Never commit on the default branch.
+   b. **Stage only the files this build touched** — explicit `git add` of the pages/components you created or edited plus the project `globals.css` (registered tokens). **Never `git add -A`.**
+   c. **Commit** — a clear, conventional message. Follow the **host project's and the running agent's own** commit conventions for message style, trailers, and footers — this skill imposes none.
+   d. **Auth preflight** — run `gh auth status`. If not authenticated, do NOT fail silently: print the exact `git push -u origin <branch>` and `gh pr create` commands, ask the user to run `gh auth login` first, then stop.
+   e. **Push + PR** — `git push -u origin <branch>`, then `gh pr create --title "<title>" --body "<body>"`. Body = the Build Report (token/component audit, block audit, created tokens, critic verdict). Never force-push.
+   f. **Return the PR URL** to the user.

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

@@ -0,0 +1,463 @@
+# 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.1). 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:
+
+- `navigation-menu` (`NavigationMenu*`) — use `Navbar` / the nav blocks, or compose with `DropdownMenu` / `Sidebar`.
+- `theme-toggle` (`ThemeToggle`) — compose from `Button` + `Switch` + `<Icon />`.
+
+### 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 |
+
+### ⚠ Status / profit-loss colours — NOT built in, register them
+
+**`text-success`, `text-error`, `bg-success`, `bg-error`, `text-win`, `text-loss` do NOT exist as
+utilities** — there is no `--color-success` / `--color-error` in the theme. The package DOES ship
+the underlying **theme-aware variables** (they flip automatically in dark mode). Register them once
+in the consuming project's `globals.css` and then use the generated classes:
+
+```css
+/* globals.css — after the DS imports */
+@theme inline {
+  --color-success: var(--text-success-default);        /* #007A22 light / #4DBC6B dark → text-success */
+  --color-error: var(--text-error-default);            /* #C40000 light / #FF4D4D dark → text-error */
+  --color-success-fill: var(--background-success-default);  /* green tint → bg-success-fill */
+  --color-error-fill: var(--background-error-default);      /* red tint  → bg-error-fill */
+}
+```
+
+This is the canonical Token Creation pattern (below) — 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` do NOT exist — register them like the status colours above if needed.
+
+### 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-subtle` | `text-subtle` |
+| `text-success` / `bg-success` / `text-error` / `bg-error` | register first (see Status colours above), then use |
+| `bg-loss` / `text-loss` / `bg-win` / `text-win` | registered `text-error` / `text-success` |
+| `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. Pick the **mobile vs desktop** variant from the target viewport.
+
+---
+
+## 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

@@ -48,6 +48,28 @@ 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

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +73,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

package/README.md

@@ -96,7 +96,7 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
 
 ## What's inside
 
-- **63 UI components** — buttons, forms, dialogs, charts, sidebars, and more
+- **60+ UI components** — buttons, forms, dialogs, charts, sidebars, and more
 - **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
@@ -117,7 +117,7 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
 | Avatar | `Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup` |
 | Badge | `Badge, BadgeDot` |
 | Breadcrumb | `Breadcrumb, BreadcrumbList, BreadcrumbItem, ...` |
-| Button | `Button, buttonVariants` |
+| Button | `Button, buttonVariants, SocialButton` |
 | Calendar | `Calendar, CalendarDayButton` |
 | Card | `Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter` |
 | Carousel | `Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext` |
@@ -137,16 +137,15 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
 | Field | `Field, FieldLabel, FieldDescription, FieldError, FieldGroup` |
 | Form | `Form, FormItem, FormLabel, FormControl, FormField, FormMessage` |
 | Hover Card | `HoverCard, HoverCardTrigger, HoverCardContent` |
+| Icon | `Icon` (wraps `@deriv/quill-icons`; `weight="regular\|bold\|fill"`) |
 | Input | `Input` |
 | Input Group | `InputGroup, InputGroupAddon, InputGroupButton, InputGroupText` |
-| Item | `Item, ItemMedia, ItemContent, ItemTitle, ItemDescription` |
+| List Item | `ListItem, ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, ListItemIcon, ListItemActions` |
 | Kbd | `Kbd, KbdGroup` |
 | Label | `Label` |
 | Link | `Link` |
 | Loading Spinner | `LoadingSpinner` |
-| Modal | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
 | Native Select | `NativeSelect, NativeSelectOptGroup, NativeSelectOption` |
-| Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuTrigger, ...` |
 | Notification | `NotificationBanner, NotificationItem, NotificationDivider` |
 | OTP Field | `CodeInput, CodeInputGroup, CodeInputSlot, CodeInputSeparator` |
 | Pagination | `Pagination, PaginationContent, PaginationLink, ...` |
@@ -171,7 +170,6 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
 | Switch | `Switch` |
 | Tab | `Tab, TabList, TabTrigger, TabContent` |
 | Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` |
-| Tabs | `Tabs, TabsList, TabsTrigger, TabsContent` |
 | Tag | `Tag, tagVariants` |
 | Textarea | `Textarea` |
 | Toggle | `Toggle, toggleVariants` |
@@ -182,34 +180,30 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
 
 ## Blocks
 
-Blocks are pre-composed UI patterns built from package primitives. They live in the **Blocks** tab of the development playground and are **not** exported from the npm package.
+Blocks are pre-composed UI patterns (navbars, heroes, cards, …) built from package primitives. **They ship as named exports** — import them directly, just like any component:
 
-To use a block in your project, click the **"Copy block"** button in the playground next to the block label. It copies an AI-ready prompt with the full block source to your clipboard. Paste it into your AI agent (Claude Code, Cursor, Kiro, Copilot) and the agent will:
-
-1. Drop the block file into your project
-2. Ask you for values to replace each `// TODO`
-3. Bundle in any shared dependencies (e.g. `HeroActionButton`)
+```tsx
+import { Navbar, HeroDesktopMain, Section, TradingAccountCard } from "@deriv-ds/design-intelligence-layer";
+```
 
-The agent doesn't generate or invent — it pastes the exact code from the playground and only swaps the dummy data for your real data.
+Wire each block's props/children to your real content — don't re-implement them. The `build` skill's Block Matching gate does this automatically (it imports the matching block instead of mocking up a look-alike).
 
 ### Available blocks
 
-| Block | Playground tab |
+| Block | Import(s) |
 |---|---|
-| `[mobile] section - hero (home)` | Blocks → Hero |
-| `[desktop] section - hero (home)` | Blocks → Hero |
-| `[mobile] section - hero (main)` | Blocks → Hero |
-| `[desktop] section - hero (main)` | Blocks → Hero |
-| `[mobile] section - hero (secondary)` | Blocks → Hero |
-| `[desktop] section - hero (secondary)` | Blocks → Hero |
-| `[mobile] section - hero (transaction details)` | Blocks → Hero |
-| `NavBar` | Blocks → NavBar |
-
-The block source files live in `app/components/hero-*.tsx`. The playground reads them and builds the AI prompt at dev/build time via `scripts/generate-block-sources.mjs`.
-
-### Manual fallback
-
-If you don't want to use an AI agent, open the block file directly on GitHub and copy everything between the `🟢 BLOCK TO COPY` and `🔵 PLAYGROUND ONLY` markers. Replace each `// TODO` with your own data. If the block imports `HeroActionButton`, also copy `app/components/hero-action-button.tsx`.
+| NavBar | `Navbar` (responsive) · `NavMobileBottomBar` · `NavDesktopSidebar` |
+| Header | `HeaderApp` · `HeaderAppHome` · `HeaderBranding` |
+| Hero — home | `HeroMobileHomeTitle` · `HeroMobileHomeTotalAssets` · `HeroDesktopHomeOnboarding` · `HeroDesktopHomeWithBalance` |
+| Hero — main / secondary / transaction | `HeroMobileMain` · `HeroDesktopMain` · `HeroMobileSecondary` · `HeroDesktopSecondary` · `HeroMobileTransaction` |
+| Hero action button | `HeroActionButton` |
+| Home — banner / highlights / explore | `HomeBanner` · `BannerCard` · `HomeHighlights` · `HomeHighlightCard` · `HomeExploreDeriv` |
+| Trading | `TradingAccountCard` · `TradingActionButtonsPrimary` · `TradingActionButtonsSecondary` · `TradingEmpty` |
+| Account / feedback | `AccountActivatedCard` · `FeedbackSuccessScreen` · `FeedbackTradeWithAccounts` · `FeedbackTransferSuggestion` |
+| Referral | `Referral` |
+| Section | `Section` |
+
+Block source files live in `components/blocks/`. Most heroes and trading blocks also export a `*Skeleton` loading variant. See `.claude/skills/build/references/components-and-tokens.md` for the full catalog with "matches when" hints.
 
 ---
 
@@ -317,13 +311,8 @@ by existing primitives — reach for these instead:
 
 ## Component behaviour notes
 
-### AlertDialog — button fill
-`AlertDialogAction` and `AlertDialogCancel` fill the full container width **only** when `size="sm"`. On `size="default"` (the default), buttons are natural width and right-aligned.
-
-```tsx
-<AlertDialogContent size="sm">   // buttons fill width (50/50 grid)
-<AlertDialogContent size="default"> // buttons natural width, right-aligned
-```
+### Dialog — footer buttons
+`DialogFooter` makes its direct child buttons fill the full width automatically. Stack your buttons inside `DialogFooter` and they will always be full-width.
 
 ### 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.
@@ -349,8 +338,8 @@ The `lg` variant of `Link` uses `text-base` (16px). The `md` and `sm` variants u
 <Link size="sm" />  // 12px — font-xs
 ```
 
-### Tabs — line variant hover
-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 — hover & sizes
+`Tab` is a line/underline tab set (`Tab, TabList, TabTrigger, TabContent` — note the singular names; `Tabs`/`TabsList` do not exist). Hover shows coral text (`text-primary`, `#FF444F`) on a transparent background.
 
 Tab sizes:
 
@@ -687,17 +676,17 @@ node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/quill-
 
 **Accessibility standards file** (bundled in the package):
 ```
-node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/quill-accessibility-standards.md
+node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md
 ```
 
 **Personas file** (bundled in the package):
 ```
-node_modules/@deriv-ds/design-intelligence-layer/guides/personas/deriv-user-field-guide.md
+node_modules/@deriv-ds/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
 ```
 
 **Brand voice** (bundled in the package):
 ```
-node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/quill-brand-voice.md
+node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/deriv-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.
@@ -722,9 +711,9 @@ Add the following to your project's `CLAUDE.md`:
 
 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
+2. Read node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md — apply WCAG 2.1 AA standards and run the 9-point accessibility checklist on every screen
+3. Read node_modules/@deriv-ds/design-intelligence-layer/guides/personas/trading-game-player-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/deriv-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 — icons come from @deriv/quill-icons via the bundled Icon component; do not install tailwindcss or other bundled dependencies separately
@@ -735,6 +724,29 @@ See node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-
 See node_modules/@deriv-ds/design-intelligence-layer/README.md for complete token and component reference.
 ```
 
+### Claude Code skill (`build`)
+
+The package ships a Claude Code **skill** that drives every UI build strictly from the design system — bootstrap, build-from-prompt, build-from-Figma, and integrate-a-pasted-block, all with the token/component/icon rules enforced. It also runs a **Block Matching gate**: before mocking up any region (nav, hero, cards, …) it matches the region against the package's shipped blocks and imports the real one instead of re-creating a look-alike. Copy it into your project's skills directory:
+
+```bash
+mkdir -p .claude/skills
+cp -R node_modules/@deriv-ds/design-intelligence-layer/.claude/skills/build .claude/skills/
+```
+
+Re-copy after each version bump so the skill matches the installed release. Once copied, Claude Code triggers it automatically when you ask to build Deriv UI (or invoke `/build`).
+
+**Cursor / Kiro:** copy the same skill folder as above, plus the shipped shim so `/build` (Cursor) or `#build` (Kiro) invokes it:
+
+```bash
+# Cursor
+mkdir -p .cursor/commands
+cp node_modules/@deriv-ds/design-intelligence-layer/.cursor/commands/build.md .cursor/commands/build.md
+
+# Kiro
+mkdir -p .kiro/steering
+cp node_modules/@deriv-ds/design-intelligence-layer/.kiro/steering/build.md .kiro/steering/build.md
+```
+
 ---
 
 ## Common mistakes
@@ -793,24 +805,26 @@ npm run build
 # Build the Next.js showcase app
 npm run build:next
 
-# Regenerate block sources for the "Copy block" button
-# (auto-runs on `npm run dev` — only needed manually after editing a hero block file)
-npm run generate:blocks
+# Check the build-skill catalog matches the package's real exports
+npm run check:skill-catalog
 ```
 
-### Adding or editing hero blocks
+### Authoring skills (`block`, `component`)
+
+This repo ships two Claude Code **authoring skills** that scaffold a new export end-to-end so it lands consistently across the component file, the playground demo, the package export, the nav wiring, and the docs/catalog. They live only in this source repo (`.claude/skills/block/`, `.claude/skills/component/`) and are **not published to npm** — they edit `components/`, `src/index.ts`, and the playground, which only exist here. Anyone with this repo checked out gets them automatically. Package consumers building product UI use the `build` skill instead (npm-published, described above).
+
+| Skill | Invoke | What it does |
+|---|---|---|
+| `block` | `/block` or "add a block" | Scaffolds a new block: `components/blocks/<name>.tsx`, playground page, `src/index.ts` export, nav wiring, **and the build-skill block catalog** (`.claude/skills/build/references/components-and-tokens.md`) so the consumer `build` skill's Block Matching gate can discover and import it. |
+| `component` | `/component` or "add a component" | Scaffolds a new UI primitive: `components/ui/<name>.tsx`, export, playground, nav wiring, and consumer docs (this README's component table, the design guide, and the build-skill cheatsheet). |
 
-Block files live in `app/components/hero-*.tsx`. Each file has two clearly marked sections:
+**Other agents:** the `/`-invocation above is Claude Code's. Cursor users invoke the same skills as `/block` and `/component` via this repo's `.cursor/commands/` shims; Kiro users pull them in with `#block` / `#component` via `.kiro/steering/`. Each shim just points the agent at the canonical `.claude/skills/<name>/SKILL.md`, so all agents run the same rules. (These shims live in this repo only — not published to npm, same as the skills themselves.)
 
-- `🟢 BLOCK TO COPY` — the block source consumers receive when they click "Copy block"
-- `🔵 PLAYGROUND ONLY` — the wrapper with switchers, skeletons, and intersection observers (excluded from the prompt)
+`npm run check:skill-catalog` guards the build-skill catalog these skills update — it fails if a component or block is exported but undocumented (or documented but not exported), so the `build` skill's catalog never drifts from the package's real surface.
 
-The `scripts/generate-block-sources.mjs` script reads each block file, extracts the section between the two markers, builds an AI-ready prompt, and writes `app/blocks-source.generated.ts`. The `CopyBlockPromptButton` component reads from that generated file. The script auto-runs on every `npm run dev`.
+### Adding or editing blocks
 
-When adding a new hero block:
-1. Create `app/components/hero-<name>-page.tsx` with both 🟢 and 🔵 markers
-2. Add an entry to the `BLOCKS` array in `scripts/generate-block-sources.mjs`
-3. Add `<CopyBlockPromptButton blockId="..." />` to the block's playground header row
+Block source files live in `components/blocks/<name>.tsx`, with a matching playground page in `app/components/<name>-page.tsx`. To add a new block, use the **`block`** authoring skill (above) — it scaffolds the block file, playground page, `src/index.ts` export, nav wiring, and the build-skill block catalog in one pass. Run `npm run check:skill-catalog` afterwards to confirm the catalog stays in sync.
 
 ### Updating design tokens
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deriv-ds/design-intelligence-layer",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Deriv Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,6 +26,7 @@
     "dev": "next dev -H 127.0.0.1 -p 3000",
     "generate:registry": "node scripts/generate-component-registry.mjs",
     "generate:icon-reference": "node scripts/generate-icon-reference.mjs",
+    "check:skill-catalog": "node scripts/check-skill-catalog.mjs",
     "build": "tsup",
     "build:next": "next build",
     "start": "next start",
@@ -45,6 +46,9 @@
     "public/assets/logo-deriv-x.png",
     "AGENTS.md",
     "README.md",
+    ".claude/skills/build/",
+    ".cursor/commands/build.md",
+    ".kiro/steering/build.md",
     "CHANGELOG.md"
   ],
   "peerDependencies": {