@deriv-ds/design-intelligence-layer 0.4.3 → 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
@@ -693,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
 
@@ -719,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` |
 
 ---
 
@@ -727,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