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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/.claude/skills/build/SKILL.md +509 -0
  2. package/.claude/skills/build/references/components-and-tokens.md +490 -0
  3. package/.cursor/commands/build.md +3 -0
  4. package/.kiro/steering/build.md +6 -0
  5. package/AGENTS.md +25 -3
  6. package/CHANGELOG.md +25 -1
  7. package/README.md +79 -59
  8. package/dist/index.cjs +1473 -1181
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.cts +42 -6
  11. package/dist/index.d.ts +42 -6
  12. package/dist/index.js +1491 -1209
  13. package/dist/index.js.map +1 -1
  14. package/guides/design-system-guide/deriv-design-intelligence-guide.md +214 -176
  15. package/guides/design-system-guide/icon-reference.md +1 -1
  16. package/guides/design-system-guide/quill-ds-guide.md +31 -30
  17. package/guides/rules/design-system-consuming-project.mdc +42 -30
  18. package/package.json +5 -1
  19. package/src/styles.css +73 -3
package/README.md CHANGED
@@ -87,7 +87,7 @@ Icons are provided by **`@deriv/quill-icons`** via the bundled `Icon` component
87
87
  import { Icon } from "@deriv-ds/design-intelligence-layer"
88
88
 
89
89
  <Icon name="bell" />
90
- <Icon name="circle-check" weight="fill" className="text-success" />
90
+ <Icon name="circle-check" weight="fill" className="text-[var(--text-success-default)]" />
91
91
  ```
92
92
 
93
93
  The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/guides/design-system-guide/icon-reference.md`.
@@ -96,7 +96,7 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
96
96
 
97
97
  ## What's inside
98
98
 
99
- - **63 UI components** — buttons, forms, dialogs, charts, sidebars, and more
99
+ - **60+ UI components** — buttons, forms, dialogs, charts, sidebars, and more
100
100
  - **Design tokens** — three-layer architecture (primitives → foundation semantics → component tokens) synced from Figma
101
101
  - **Light + Dark themes** — toggle `.dark` on `<html>` to switch; every semantic token has a paired override
102
102
  - **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
117
117
  | Avatar | `Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup` |
118
118
  | Badge | `Badge, BadgeDot` |
119
119
  | Breadcrumb | `Breadcrumb, BreadcrumbList, BreadcrumbItem, ...` |
120
- | Button | `Button, buttonVariants` |
120
+ | Button | `Button, buttonVariants, SocialButton` |
121
121
  | Calendar | `Calendar, CalendarDayButton` |
122
122
  | Card | `Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter` |
123
123
  | Carousel | `Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext` |
@@ -137,16 +137,16 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
137
137
  | Field | `Field, FieldLabel, FieldDescription, FieldError, FieldGroup` |
138
138
  | Form | `Form, FormItem, FormLabel, FormControl, FormField, FormMessage` |
139
139
  | Hover Card | `HoverCard, HoverCardTrigger, HoverCardContent` |
140
+ | Icon | `Icon` (wraps `@deriv/quill-icons`; `weight="regular\|bold\|fill"`) |
140
141
  | Input | `Input` |
141
142
  | Input Group | `InputGroup, InputGroupAddon, InputGroupButton, InputGroupText` |
142
- | Item | `Item, ItemMedia, ItemContent, ItemTitle, ItemDescription` |
143
+ | List Item | `ListItem, ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, ListItemIcon, ListItemActions` |
143
144
  | Kbd | `Kbd, KbdGroup` |
144
145
  | Label | `Label` |
145
146
  | Link | `Link` |
146
147
  | Loading Spinner | `LoadingSpinner` |
147
- | Modal | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
148
148
  | Native Select | `NativeSelect, NativeSelectOptGroup, NativeSelectOption` |
149
- | Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuTrigger, ...` |
149
+ | Navigation Menu | `NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, ...` |
150
150
  | Notification | `NotificationBanner, NotificationItem, NotificationDivider` |
151
151
  | OTP Field | `CodeInput, CodeInputGroup, CodeInputSlot, CodeInputSeparator` |
152
152
  | Pagination | `Pagination, PaginationContent, PaginationLink, ...` |
@@ -165,13 +165,12 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
165
165
  | Sidebar | `Sidebar, SidebarProvider, SidebarMenu, SidebarMenuItem, ...` |
166
166
  | Skeleton | `Skeleton` |
167
167
  | Slider | `Slider` |
168
- | Snackbar | `Snackbar` |
168
+ | Snackbar | `Snackbar` (+ imperative `toast` — re-exported from sonner) |
169
169
  | Spinner | `Spinner` |
170
170
  | Stepper | `Stepper` |
171
171
  | Switch | `Switch` |
172
172
  | Tab | `Tab, TabList, TabTrigger, TabContent` |
173
173
  | Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` |
174
- | Tabs | `Tabs, TabsList, TabsTrigger, TabsContent` |
175
174
  | Tag | `Tag, tagVariants` |
176
175
  | Textarea | `Textarea` |
177
176
  | Toggle | `Toggle, toggleVariants` |
@@ -182,34 +181,35 @@ The full icon catalog is at `node_modules/@deriv-ds/design-intelligence-layer/gu
182
181
 
183
182
  ## Blocks
184
183
 
185
- 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.
184
+ 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:
186
185
 
187
- 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:
188
-
189
- 1. Drop the block file into your project
190
- 2. Ask you for values to replace each `// TODO`
191
- 3. Bundle in any shared dependencies (e.g. `HeroActionButton`)
186
+ ```tsx
187
+ import { Navbar, HeroDesktopMain, Section, TradingAccountCard } from "@deriv-ds/design-intelligence-layer";
188
+ ```
192
189
 
193
- 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.
190
+ 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).
194
191
 
195
192
  ### Available blocks
196
193
 
197
- | Block | Playground tab |
198
- |---|---|
199
- | `[mobile] section - hero (home)` | Blocks → Hero |
200
- | `[desktop] section - hero (home)` | Blocks → Hero |
201
- | `[mobile] section - hero (main)` | Blocks → Hero |
202
- | `[desktop] section - hero (main)` | Blocks → Hero |
203
- | `[mobile] section - hero (secondary)` | Blocks → Hero |
204
- | `[desktop] section - hero (secondary)` | Blocks → Hero |
205
- | `[mobile] section - hero (transaction details)` | Blocks → Hero |
206
- | `NavBar` | Blocks → NavBar |
207
-
208
- 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`.
209
-
210
- ### Manual fallback
211
-
212
- 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`.
194
+ | Block | Variants / exports | Description |
195
+ |---|---|---|
196
+ | NavBar | `Navbar` (responsive) · `NavMobileBottomBar` · `NavDesktopSidebar` — props `activeId`, `badges`, `onNavChange` | App navigation. `Navbar` auto-switches: sidebar ≥768px, bottom tab bar <768px. |
197
+ | Header | `HeaderApp` · `HeaderAppHome` · `HeaderBranding` | App top header. Home (avatar + notifications + Ask Amy), in-app sub-page (back, tabs, actions), or branding bar (language + actions). |
198
+ | Hero — home | `HeroMobileHomeTitle` · `HeroMobileHomeTotalAssets` · `HeroDesktopHomeOnboarding` · `HeroDesktopHomeWithBalance` (+ `*Skeleton`) | Home top area: greeting/title, total-assets balance, or onboarding hero. Mobile/desktop pair. |
199
+ | Hero — main / secondary / transaction | `HeroMobileMain` · `HeroDesktopMain` · `HeroMobileSecondary` · `HeroDesktopSecondary` · `HeroMobileTransaction` (+ `*Skeleton`) | Primary/secondary page hero with account tabs + action buttons; transaction details card. |
200
+ | Hero action button | `HeroActionButton` | The prominent circular action button used inside heroes. |
201
+ | Home — banner | `HomeBanner` · `BannerCard` — props `banner`, `layout`, `onClose` | Promo / announcement banner (carousel of cards, or a single dismissible card). |
202
+ | Home — highlights | `HomeHighlights` · `HomeHighlightCard` — prop `cards` | Row/grid of highlight cards. |
203
+ | Home — explore | `HomeExploreDeriv` | "Explore Deriv" discovery section. |
204
+ | Trading — account card | `TradingAccountCard` — prop `layout` | Account card with balance + actions. |
205
+ | Trading — action buttons | `TradingActionButtonsPrimary` · `TradingActionButtonsSecondary` (+ `*Skeleton`) | Deposit / withdraw / transfer action button cluster. |
206
+ | Trading — empty | `TradingEmpty` (+ `TradingEmptySkeleton`) | Empty trading list / no-accounts state. |
207
+ | Account activated | `AccountActivatedCard` | "Account activated" confirmation card. |
208
+ | Feedback / success | `FeedbackSuccessScreen` · `FeedbackTradeWithAccounts` · `FeedbackTransferSuggestion` | Post-action success / confirmation screens. |
209
+ | Referral | `Referral` — props `metrics`, … | Refer-a-friend / invite panel with metrics. |
210
+ | Section | `Section` | Section header pattern: eyebrow tag, title (+ chevron), control cluster, segmented control, content slot (`children`). |
211
+
212
+ 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.
213
213
 
214
214
  ---
215
215
 
@@ -317,13 +317,8 @@ by existing primitives — reach for these instead:
317
317
 
318
318
  ## Component behaviour notes
319
319
 
320
- ### AlertDialog — button fill
321
- `AlertDialogAction` and `AlertDialogCancel` fill the full container width **only** when `size="sm"`. On `size="default"` (the default), buttons are natural width and right-aligned.
322
-
323
- ```tsx
324
- <AlertDialogContent size="sm"> // buttons fill width (50/50 grid)
325
- <AlertDialogContent size="default"> // buttons natural width, right-aligned
326
- ```
320
+ ### Dialog — footer buttons
321
+ `DialogFooter` makes its direct child buttons fill the full width automatically. Stack your buttons inside `DialogFooter` and they will always be full-width.
327
322
 
328
323
  ### Drawer — footer buttons
329
324
  `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 +344,8 @@ The `lg` variant of `Link` uses `text-base` (16px). The `md` and `sm` variants u
349
344
  <Link size="sm" /> // 12px — font-xs
350
345
  ```
351
346
 
352
- ### Tabs — line variant hover
353
- 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`.
347
+ ### Tab — hover & sizes
348
+ `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.
354
349
 
355
350
  Tab sizes:
356
351
 
@@ -687,17 +682,17 @@ node_modules/@deriv-ds/design-intelligence-layer/guides/design-principles/quill-
687
682
 
688
683
  **Accessibility standards file** (bundled in the package):
689
684
  ```
690
- node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/quill-accessibility-standards.md
685
+ node_modules/@deriv-ds/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md
691
686
  ```
692
687
 
693
688
  **Personas file** (bundled in the package):
694
689
  ```
695
- node_modules/@deriv-ds/design-intelligence-layer/guides/personas/deriv-user-field-guide.md
690
+ node_modules/@deriv-ds/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
696
691
  ```
697
692
 
698
693
  **Brand voice** (bundled in the package):
699
694
  ```
700
- node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/quill-brand-voice.md
695
+ node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/deriv-brand-voice.md
701
696
  ```
702
697
 
703
698
  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,11 +717,11 @@ Add the following to your project's `CLAUDE.md`:
722
717
 
723
718
  This project uses @deriv-ds/design-intelligence-layer (Quill Design System). Before writing any UI:
724
719
  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
725
- 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
726
- 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
727
- 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
720
+ 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
721
+ 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
722
+ 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
728
723
  5. Check if the component exists in the package — import it, don't re-implement
729
- 6. Use only design token classes (bg-prominent, text-on-prominent, border-border-subtle, etc.) — no hardcoded hex or raw Tailwind palette colors
724
+ 6. Use only design token classes (bg-primary-canvas, text-prominent, border-default, etc.) — no hardcoded hex or raw Tailwind palette colors
730
725
  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
731
726
  8. If no token exists for a value, ask before using a hardcoded value
732
727
  9. After upgrading the package: prefer package imports over local copies of components; if replacing local UI code with the package version, tell the user what was overwritten; re-copy guides/rules/design-system-consuming-project.mdc into .cursor/rules if using Cursor
@@ -735,6 +730,29 @@ See node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-
735
730
  See node_modules/@deriv-ds/design-intelligence-layer/README.md for complete token and component reference.
736
731
  ```
737
732
 
733
+ ### Claude Code skill (`build`)
734
+
735
+ 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:
736
+
737
+ ```bash
738
+ mkdir -p .claude/skills
739
+ cp -R node_modules/@deriv-ds/design-intelligence-layer/.claude/skills/build .claude/skills/
740
+ ```
741
+
742
+ 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`).
743
+
744
+ **Cursor / Kiro:** copy the same skill folder as above, plus the shipped shim so `/build` (Cursor) or `#build` (Kiro) invokes it:
745
+
746
+ ```bash
747
+ # Cursor
748
+ mkdir -p .cursor/commands
749
+ cp node_modules/@deriv-ds/design-intelligence-layer/.cursor/commands/build.md .cursor/commands/build.md
750
+
751
+ # Kiro
752
+ mkdir -p .kiro/steering
753
+ cp node_modules/@deriv-ds/design-intelligence-layer/.kiro/steering/build.md .kiro/steering/build.md
754
+ ```
755
+
738
756
  ---
739
757
 
740
758
  ## Common mistakes
@@ -793,24 +811,26 @@ npm run build
793
811
  # Build the Next.js showcase app
794
812
  npm run build:next
795
813
 
796
- # Regenerate block sources for the "Copy block" button
797
- # (auto-runs on `npm run dev` — only needed manually after editing a hero block file)
798
- npm run generate:blocks
814
+ # Check the build-skill catalog matches the package's real exports
815
+ npm run check:skill-catalog
799
816
  ```
800
817
 
801
- ### Adding or editing hero blocks
818
+ ### Authoring skills (`block`, `component`)
819
+
820
+ 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).
821
+
822
+ | Skill | Invoke | What it does |
823
+ |---|---|---|
824
+ | `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. |
825
+ | `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). |
802
826
 
803
- Block files live in `app/components/hero-*.tsx`. Each file has two clearly marked sections:
827
+ **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.)
804
828
 
805
- - `🟢 BLOCK TO COPY` — the block source consumers receive when they click "Copy block"
806
- - `🔵 PLAYGROUND ONLY` — the wrapper with switchers, skeletons, and intersection observers (excluded from the prompt)
829
+ `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.
807
830
 
808
- 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`.
831
+ ### Adding or editing blocks
809
832
 
810
- When adding a new hero block:
811
- 1. Create `app/components/hero-<name>-page.tsx` with both 🟢 and 🔵 markers
812
- 2. Add an entry to the `BLOCKS` array in `scripts/generate-block-sources.mjs`
813
- 3. Add `<CopyBlockPromptButton blockId="..." />` to the block's playground header row
833
+ 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.
814
834
 
815
835
  ### Updating design tokens
816
836