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

package/README.md

@@ -167,12 +167,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`.
 
 ---
 
@@ -736,8 +758,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 +794,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deriv-ds/design-intelligence-layer",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Deriv Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,9 +23,11 @@
     "**/*.css"
   ],
   "scripts": {
-    "dev": "next dev -H 127.0.0.1 -p 3000",
+    "dev": "npm run generate:blocks && next dev -H 127.0.0.1 -p 3000",
     "generate:registry": "node scripts/generate-component-registry.mjs",
+    "generate:blocks": "node scripts/generate-block-sources.mjs",
     "build": "tsup",
+    "prebuild:next": "npm run generate:blocks",
     "build:next": "next build",
     "start": "next start",
     "lint": "eslint",
@@ -87,6 +89,7 @@
   "overrides": {
     "lodash": "^4.18.0",
     "postcss": "^8.5.10",
-    "qs": "^6.15.2"
+    "qs": "^6.15.2",
+    "hono": "^4.12.21"
   }
 }