@deriv-ds/design-intelligence-layer 0.4.2 → 0.4.4

package/AGENTS.md

@@ -55,9 +55,21 @@ cp node_modules/@deriv-ds/design-intelligence-layer/guides/rules/design-system-c
 1. **Check before building** — if a component exists in `@deriv-ds/design-intelligence-layer`, import it. Never re-implement it.
 2. **Tokens only** — use semantic token classes (`bg-prominent`, `text-on-prominent`, `border-border`, etc.). Never hardcode hex values, raw Tailwind palette colors, or CSS variables.
 3. **Design principles and accessibility first** — every screen must reflect the 8 design principles and meet the accessibility standards (WCAG 2.1 AA). Run both checklists before shipping.
-4. **No separate installs** — do not install `lucide-react`, `tailwindcss`, or other bundled dependencies separately.
-5. **After a version bump** — re-copy the rules file into `.cursor/rules/`, check for stale local component copies, and align them with the package.
-6. **Blocks are playground-only** — Blocks (e.g. NavBar) appear in the playground's Blocks tab but are **not** exported from the package. Do not try to import them. To build a block pattern in a consuming project, compose it manually using package components and design tokens. See `guides/design-system-guide/deriv-design-intelligence-guide.md` Section 8.5.
+4. **No separate installs** — do not install `tailwindcss` or other bundled dependencies separately. Never install or import `lucide-react` or any other icon library.
+5. **Icons** — use the exported `<Icon />` component (FontAwesome Pro): `<Icon name="bell" weight="bold" />`. Three weights: `regular` (unselected nav, subtle), `bold` (default), `fill` (selected nav, strong actions). Full catalog of names, weights, and intent → icon mappings: `guides/design-system-guide/icon-reference.md`. At runtime, `ICON_NAMES` and `iconAvailableWeights(name)` are exported from the package.
+6. **After a version bump** — re-copy the rules file into `.cursor/rules/`, check for stale local component copies, and align them with the package.
+7. **Blocks are exported from the package** — Blocks (Hero sections, NavBar patterns) are importable directly from `@deriv-ds/design-intelligence-layer`. When a user asks to use a block by name, import it:
+   ```tsx
+   import { HeroMobileHomeTitle, HeroMobileHomeTotalAssets } from "@deriv-ds/design-intelligence-layer"
+   import { HeroDesktopHomeOnboarding, HeroDesktopHomeWithBalance } from "@deriv-ds/design-intelligence-layer"
+   import { HeroMobileMain, HeroDesktopMain } from "@deriv-ds/design-intelligence-layer"
+   import { HeroMobileSecondary, HeroDesktopSecondary } from "@deriv-ds/design-intelligence-layer"
+   import { HeroMobileTransaction } from "@deriv-ds/design-intelligence-layer"
+   import { Navbar } from "@deriv-ds/design-intelligence-layer"
+   // Responsive: renders sidebar on desktop (≥768px), bottom bar on mobile (<768px)
+   // For explicit control: NavMobileBottomBar, NavDesktopSidebar are also exported
+   ```
+   See `guides/design-system-guide/deriv-design-intelligence-guide.md` Section 8.5 for full block catalogue and prop signatures.
 
 ---
 

package/README.md

@@ -6,6 +6,23 @@ Published as **`@deriv-ds/design-intelligence-layer`** on npm.
 
 ---
 
+## License & FontAwesome Pro — read before installing
+
+This package is **proprietary to Deriv** (`"license": "UNLICENSED"`). It is not open source and must never be published with public access or mirrored to a public registry.
+
+The icon system depends on **FontAwesome Pro**, which is commercially licensed to Deriv on a **per-seat basis**. Compliance rules:
+
+1. **Only licensed seat-holders may install or build this package.** FontAwesome counts every developer who uses Pro icons during development as a seat. Currently this is restricted to one designated engineer — do not share registry access beyond licensed seats.
+2. **Token setup (required to install).** The FA registry token is read from an environment variable — it is never stored in the repo. The designated engineer adds this to their shell profile (and CI adds it as a masked secret):
+
+   ```bash
+   export FONTAWESOME_NPM_AUTH_TOKEN=<token from the Deriv FontAwesome account>
+   ```
+
+   The committed-ignored `.npmrc` references it as `${FONTAWESOME_NPM_AUTH_TOKEN}`. Without the variable set, `npm install` fails loudly — that is intentional.
+3. **Never bundle FA glyph data.** FA packages must stay in `dependencies` (tsup externalizes them) so the published tarball contains no FontAwesome code. Do not add `@fortawesome/*` to tsup's bundled output.
+4. **Never commit the token.** `.npmrc` is gitignored; the token lives only in shell profiles and CI secrets. If it ever leaks, regenerate it at fontawesome.com → Account.
+
 ## Quick Start
 
 ### Installation
@@ -167,12 +184,34 @@ npm install react react-dom tailwindcss
 
 ## Blocks
 
-Blocks are pre-composed UI patterns built from Quill primitives. They are demonstrated in the **Blocks** tab of the development playground and are **not** exported from the npm package — import the underlying components directly if you need to use them.
+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.
 
-| Block | Variants | Description |
-|---|---|---|
-| NavBar | Desktop, Mobile (closed), Mobile (open) | Landing page top navigation bar. Logo + ghost nav links (Products, Use Cases, Docs, Blog, FAQ) + Sign in / Sign up CTAs. |
-| Hero | Type 1 (Desktop + Mobile), Type 2 | Landing page hero sections. Type 1: tagline pill + heading + body + CTAs left, image right (responsive). Type 2: centred single-column, tagline pill + heading + body + primary CTA with arrow icon, no image. |
+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`)
+
+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.
+
+### Available blocks
+
+| Block | Playground tab |
+|---|---|
+| `[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`.
 
 ---
 
@@ -671,7 +710,7 @@ This project uses @deriv-ds/design-intelligence-layer (Quill Design System). Bef
 4. Read node_modules/@deriv-ds/design-intelligence-layer/guides/brand-voice/quill-brand-voice.md — apply the brand voice: channel-specific voice, banned phrases, vocabulary, and formatting rules for all player-facing copy
 5. Check if the component exists in the package — import it, don't re-implement
 6. Use only design token classes (bg-prominent, text-on-prominent, border-border-subtle, etc.) — no hardcoded hex or raw Tailwind palette colors
-7. Do not install lucide-react, tailwindcss, or other bundled dependencies separately
+7. Do not install icon libraries (lucide-react etc.), tailwindcss, or other bundled dependencies separately — icons come from FontAwesome Pro via the <Icon /> component (see guides/design-system-guide/icon-reference.md for the full catalog and weight conventions)
 8. If no token exists for a value, ask before using a hardcoded value
 9. After upgrading the package: prefer package imports over local copies of components; if replacing local UI code with the package version, tell the user what was overwritten; re-copy guides/rules/design-system-consuming-project.mdc into .cursor/rules if using Cursor
 
@@ -697,7 +736,7 @@ See node_modules/@deriv-ds/design-intelligence-layer/README.md for complete toke
 | `bg-[var(--primary)]` | `bg-primary` | Raw CSS var — Tailwind v4 maps tokens directly |
 | `hsl(var(--primary))` | `bg-primary` | Tailwind v3 syntax — not needed in v4 |
 | `font-[Plus_Jakarta_Sans]` | `font-sans` (Inter) | Project font is Inter, not Plus Jakarta Sans |
-| Installing `lucide-react` | Already bundled | Icons are included in the package |
+| Importing `lucide-react` | `<Icon name="..." />` | Icons are FontAwesome Pro via the bundled `<Icon />` component — see `guides/design-system-guide/icon-reference.md` |
 
 ---
 
@@ -705,7 +744,7 @@ See node_modules/@deriv-ds/design-intelligence-layer/README.md for complete toke
 
 These are bundled with the package. Installing them separately can cause version conflicts:
 
-- `lucide-react` — icon library
+- `@fortawesome/*` and `@awesome.me/*` — FontAwesome Pro icon packages, used through the exported `<Icon />` component (never imported directly in consuming code)
 - `radix-ui` — headless primitives
 - `class-variance-authority` — variant API
 - `cmdk` — command palette
@@ -736,8 +775,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
 ```
 
+### Adding or editing hero blocks
+
+Block files live in `app/components/hero-*.tsx`. Each file has two clearly marked sections:
+
+- `🟢 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)
+
+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`.
+
+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
+
 ### Updating design tokens
 
 Design tokens are managed in Figma and exported as CSS variables. To update:
@@ -754,4 +811,4 @@ Design tokens are managed in Figma and exported as CSS variables. To update:
 - **Tailwind CSS v4** — CSS-first configuration
 - **shadcn/ui** (New York style) — base component primitives
 - **Radix UI** — accessible headless primitives
-- **Figma** — source of truth for design tokens
+- **Figma** — source of truth for design tokens