designlang 12.3.0 → 12.7.1

package/bin/design-extract.js

@@ -49,6 +49,10 @@ import { formatBattle, formatBattleMarkdown } from '../src/formatters/battle.js'
 import { formatScoreBadge } from '../src/formatters/badge.js';
 import { formatRemix } from '../src/formatters/remix.js';
 import { VOCABULARIES, getVocabulary, listVocabularies } from '../src/vocabularies/index.js';
+import { buildPack } from '../src/pack.js';
+import { recolorDesign } from '../src/recolor.js';
+import { formatThemeSwap, formatThemeSwapMarkdown } from '../src/formatters/theme-swap.js';
+import { formatBrandBook, formatBrandBookMarkdown } from '../src/formatters/brand-book.js';
 import { nameFromUrl } from '../src/utils.js';
 
 function validateUrl(url) {
@@ -1172,6 +1176,236 @@ program
     }
   });
 
+// ── Pack command — bundle every emitter into one design-system directory
+program
+  .command('pack <url>')
+  .description('Bundle every output (tokens, components, storybook, prompts, starter) into a single design-system directory')
+  .option('-o, --out <dir>', 'output directory (default: ./<host>-design-system)')
+  .option('--with-clone', 'include the full Next.js clone as the starter (slower; otherwise emits a minimal HTML starter)')
+  .option('--open', 'open the starter index.html in the default browser')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const spinner = ora(`Extracting ${url}...`).start();
+    try {
+      const design = await extractDesignLanguage(url);
+
+      const defaultDirName = `${nameFromUrl(url)}-design-system`;
+      const outDir = resolve(opts.out || defaultDirName);
+
+      spinner.text = 'Packing artifacts...';
+      const { files } = buildPack(design, {
+        outDir,
+        version: PKG_VERSION,
+        withClone: !!opts.withClone,
+      });
+
+      spinner.stop();
+      console.log('');
+      console.log(`  ${chalk.bold('Packed')} ${chalk.gray('·')} ${chalk.cyan(files.length)} files ${chalk.gray('·')} ${chalk.gray(url)}`);
+      console.log('');
+      console.log(`  ${chalk.green('✓')} ${chalk.bold(outDir)}`);
+      console.log('');
+      console.log(chalk.gray('  Top-level layout:'));
+      const top = ['README.md', 'LICENSE.txt', 'tokens/', 'components/', 'storybook/', 'starter/', 'prompts/', 'extras/'];
+      for (const t of top) console.log(`    ${chalk.gray('·')} ${t}`);
+      console.log('');
+      console.log(chalk.gray(`  Zip it:    cd ${outDir} && zip -r ../${defaultDirName}.zip .`));
+      console.log(chalk.gray(`  Storybook: cd ${outDir}/storybook && npm install && npm run storybook`));
+      console.log('');
+
+      if (opts.open) {
+        const starter = join(outDir, 'starter', 'index.html');
+        const { spawn } = await import('child_process');
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        spawn(cmd, [starter], { detached: true, stdio: 'ignore' }).unref();
+      }
+    } catch (err) {
+      spinner.fail('Pack failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Theme-swap command — recolour an extracted design around a new primary
+program
+  .command('theme-swap <url>')
+  .description('Recolour the extracted design around a new brand primary (preserves type, spacing, neutrals)')
+  .requiredOption('--primary <hex>', 'target primary colour as hex (e.g. "#ff4800")')
+  .option('--from <hex>', 'override the auto-detected source primary (e.g. when the extractor misclassifies)')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: derived from URL + target hex)')
+  .option('--format <fmt>', 'output format: html, md, json, tokens, all', 'all')
+  .option('--open', 'open the HTML preview in the default browser')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const spinner = ora(`Extracting ${url}...`).start();
+    try {
+      const original = await extractDesignLanguage(url);
+      spinner.text = `Recolouring around ${opts.primary}...`;
+      const { design: recoloured, summary } = recolorDesign(original, {
+        primary: opts.primary,
+        fromPrimary: opts.from,
+      });
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const targetSlug = String(opts.primary).replace(/^#/, '').toLowerCase();
+      const prefix = opts.name || `${nameFromUrl(url)}-themeswap-${targetSlug}`;
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatThemeSwap(original, recoloured, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.themeswap.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatThemeSwapMarkdown(original, recoloured);
+        const p = join(outDir, `${prefix}.themeswap.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        const p = join(outDir, `${prefix}.themeswap.json`);
+        writeFileSync(p, JSON.stringify({
+          url: original.meta?.url,
+          from: summary.from,
+          to: summary.to,
+          hueShift: summary.hueShift,
+          changedColors: summary.changes.length,
+          changes: summary.changes,
+          timestamp: new Date().toISOString(),
+        }, null, 2));
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'tokens') {
+        const tokens = formatDtcgTokens(recoloured);
+        const p = join(outDir, `${prefix}.themeswap.tokens.json`);
+        writeFileSync(p, typeof tokens === 'string' ? tokens : JSON.stringify(tokens, null, 2));
+        written.push(p);
+      }
+
+      spinner.stop();
+      console.log('');
+      console.log(`  ${chalk.bold(`${summary.from} → ${summary.to}`)} ${chalk.gray('·')} ${chalk.cyan(summary.changes.length)} colours ${chalk.gray('·')} ${chalk.gray(url)}`);
+      console.log(`  ${chalk.gray(`Hue shift: ${(summary.hueShift).toFixed(1)}° · neutrals preserved · type/spacing/motion untouched`)}`);
+      console.log('');
+      for (const f of written) console.log(`  ${chalk.green('✓')} ${chalk.gray(f)}`);
+      console.log('');
+
+      if (opts.open) {
+        const htmlPath = written.find(p => p.endsWith('.html'));
+        if (htmlPath) {
+          const { spawn } = await import('child_process');
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+        }
+      }
+    } catch (err) {
+      spinner.fail('Theme-swap failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Brand command — full editorial brand-guidelines book ────
+program
+  .command('brand <url>')
+  .description('Generate a full brand-guidelines book — colour, type, spacing, motion, voice, components, accessibility, tokens, and how-to-use guidance')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: derived from URL)')
+  .option('--format <fmt>', 'output format: html, md, json, all', 'all')
+  .option('--open', 'open the HTML book in the default browser')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const spinner = ora(`Building brand guidelines for ${url}...`).start();
+    try {
+      // The brand book leans on the full extraction (logo, motion, voice,
+      // anatomy, accessibility), so default to --full unless the caller has
+      // explicitly opted out via env.
+      const design = await extractDesignLanguage(url, {
+        screenshots: true,
+        responsive: false,
+        interactions: false,
+        deepInteract: true,
+      });
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const prefix = opts.name || `${nameFromUrl(url)}.brand`;
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatBrandBook(design, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatBrandBookMarkdown(design);
+        const p = join(outDir, `${prefix}.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        // A trimmed JSON of the most-used surfaces in the book — useful for
+        // programmatic consumption without re-running extraction.
+        const p = join(outDir, `${prefix}.json`);
+        writeFileSync(p, JSON.stringify({
+          url: design.meta?.url,
+          title: design.meta?.title,
+          timestamp: design.meta?.timestamp,
+          intent: design.pageIntent,
+          material: design.materialLanguage,
+          imagery: design.imageryStyle,
+          library: design.componentLibrary,
+          stack: design.stack,
+          voice: design.voice,
+          colors: design.colors,
+          typography: design.typography,
+          spacing: design.spacing,
+          shadows: design.shadows,
+          borders: design.borders,
+          motion: design.motion,
+          accessibility: design.accessibility,
+          score: design.score,
+        }, null, 2));
+        written.push(p);
+      }
+
+      spinner.stop();
+      const colorCount = (design.colors?.all || []).length;
+      const fontCount = (design.typography?.families || []).length;
+      const grade = design.score?.grade || '—';
+      console.log('');
+      console.log(`  ${chalk.bold('Brand book')} ${chalk.gray('·')} ${chalk.cyan(colorCount + ' tokens')} ${chalk.gray('·')} ${chalk.cyan(fontCount + ' fonts')} ${chalk.gray('·')} ${chalk.cyan('grade ' + grade)} ${chalk.gray('·')} ${chalk.gray(url)}`);
+      console.log('');
+      for (const f of written) console.log(`  ${chalk.green('✓')} ${chalk.gray(f)}`);
+      console.log('');
+      console.log(chalk.gray(`  Open the .html — it's a self-contained, print-ready guidelines book.`));
+      console.log('');
+
+      if (opts.open) {
+        const htmlPath = written.find(p => p.endsWith('.html'));
+        if (htmlPath) {
+          const { spawn } = await import('child_process');
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+        }
+      }
+    } catch (err) {
+      spinner.fail('Brand book failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ── Apply command ──────────────────────────────────────────
 program
   .command('apply <url>')

package/commands/battle.md

@@ -0,0 +1,27 @@
+---
+description: Head-to-head graded battle card between two sites — eight dimensions, bar-by-bar, verdict line.
+argument-hint: <urlA> <urlB>
+---
+
+Pit two sites against each other and emit a single shareable HTML battle card.
+
+```bash
+npx designlang battle $ARGUMENTS
+```
+
+If `$ARGUMENTS` is empty or contains fewer than two URLs, ask the user for both sites.
+
+Both sites are extracted in parallel (~30s total). Outputs land in `./design-extract-output/`:
+
+- `<a>-vs-<b>.battle.html` — the shareable card
+- `<a>-vs-<b>.battle.md` — markdown summary
+- `<a>-vs-<b>.battle.json` — structured scores
+
+After the run:
+
+1. Read the `*.battle.md` file
+2. Show the user the verdict line ("X wins" / "tie") and the per-dimension table
+3. Highlight the dimensions where the gap is widest
+4. Offer to open the HTML card
+
+This is pure viral content — battles are designed to be tweeted. Pair with `/grade <url> --badge` so each side has a permanent badge to link back to.

package/commands/brand.md

@@ -0,0 +1,59 @@
+---
+description: Generate a full editorial brand-guidelines book for any URL. 13 chapters covering colour, typography, spacing, shape, iconography, motion, components, voice, accessibility, tokens, and how-to-use guidance. Print-ready, dark-mode toggle, hand-off-ready single HTML.
+argument-hint: <url> [--open]
+---
+
+Build a self-contained, hand-off-ready brand-guidelines book from any live URL.
+
+```bash
+npx designlang brand $ARGUMENTS
+```
+
+If no URL is provided, ask the user which site to document.
+
+Output goes to `./design-extract-output/`:
+
+- `*.brand.html` — the editorial book (open this — it's a self-contained, print-ready document with TOC, smooth-scroll, dark-mode toggle)
+- `*.brand.md` — terse markdown summary (good for diffing snapshots)
+- `*.brand.json` — structured slice of the design with the surfaces the book renders
+
+After the run completes:
+
+1. Read `*.brand.md` to summarise what was captured (host, page intent, material language, tone, palette size, type families, WCAG score)
+2. Tell the user the headline numbers (`X tokens · Y fonts · grade Z`)
+3. Offer to open the HTML book (`--open` does this automatically)
+4. Suggest pairing: `/pack <url>` if they want a developer-facing bundle to drop into a project, `/grade <url>` for the audit, `/theme-swap <url>` to derive a recoloured variant
+
+## What's in the book
+
+| § | Chapter | What it documents |
+|---|---|---|
+| 01 | About | Page intent, material language, imagery style, component library, stack, voice tone |
+| 02 | Logo | Extracted SVG logo + clearspace + dimensions |
+| 03 | Colour | Brand colours with HEX/RGB/HSL/usage, neutrals grid, full palette, A11y callout |
+| 04 | Typography | Display + body families, weights, scale table, large specimen |
+| 05 | Spacing | Base unit, scale length, visual rhythm bars |
+| 06 | Shape | Border radii visualised, shadow elevation system |
+| 07 | Iconography | Icon library detection + captured icons grid |
+| 08 | Motion | Feel, durations (animated dots), easings, spring presence, scroll-linked flag |
+| 09 | Components | Detected components with slots/variants/sizes |
+| 10 | Voice & tone | Tone, pronoun posture, heading case, top CTA verbs, sample headings |
+| 11 | Accessibility | WCAG score, failing pairs table, suggested replacements |
+| 12 | Tokens | Drop-in code blocks (CSS vars, Tailwind config) + cross-ref to `pack` |
+| 13 | How to use | Six rules of thumb for derivative work |
+
+## Useful flags
+
+| Flag | Effect |
+|---|---|
+| `--format html\|md\|json\|all` | Pick the output(s). Default `all`. |
+| `--out <dir>` | Output directory. Default `./design-extract-output`. |
+| `-n, --name <name>` | Output file prefix. Default derived from URL. |
+| `--open` | Open the HTML book in your default browser. |
+
+## Pairs nicely with
+
+- `/pack <url>` — when the recipient wants files to drop into a project, not a guidelines doc
+- `/grade <url>` — when the recipient wants the audit/score, not the full book
+- `/theme-swap <url> --primary <hex>` — when the recipient wants the same system in their brand colour
+- `/remix <url> --as <vocab>` — when the recipient wants a vocabulary swap (brutalist, swiss, etc.)

package/commands/extract.md

@@ -0,0 +1,41 @@
+---
+description: Extract the complete design language from a URL — DTCG tokens, Tailwind, Figma vars, motion, voice, components.
+argument-hint: <url> [extra flags…]
+---
+
+Run **designlang** against the user-provided URL and surface the result.
+
+```bash
+npx designlang $ARGUMENTS
+```
+
+If no `$ARGUMENTS` were supplied, ask the user which URL to extract.
+
+Default output goes to `./design-extract-output/`. Once it finishes, read the generated `*-design-language.md` (the AI-optimized markdown) and present a tight summary to the user:
+
+- Primary palette (hex codes)
+- Type families + scale
+- Spacing base + scale
+- WCAG accessibility score
+- Component patterns detected
+- Notable signals (motion feel, material language, brand voice tone)
+
+Then offer follow-ups:
+
+- `/grade <url>` — shareable HTML Design Report Card + SVG badge
+- `/battle <urlA> <urlB>` — head-to-head graded comparison
+- `/remix <url> --as <vocab>` — restyle in another vocabulary
+- `/pack <url>` — bundle every output into one design-system directory
+
+Useful flags the user may pass via `$ARGUMENTS`:
+
+| Flag | Effect |
+|---|---|
+| `--full` | screenshots + responsive + interactions + deep-interact |
+| `--depth <n>` | crawl N additional canonical pages |
+| `--dark` | also extract dark mode |
+| `--platforms ios,android,flutter,wordpress` | multi-platform emitters |
+| `--smart` | LLM fallback for low-confidence classifiers (needs `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) |
+| `--cookie-file ./session.json` | authenticated extraction |
+
+Full reference: https://github.com/Manavarya09/design-extract#full-cli-reference

package/commands/grade.md

@@ -0,0 +1,29 @@
+---
+description: Generate a shareable HTML "Design Report Card" — letter grade, 8 dimensions, evidence (palette, type, rhythm), strengths + fixes, plus an SVG badge.
+argument-hint: <url> [--badge] [--open]
+---
+
+Audit the design system at the user-provided URL. Emits a self-contained HTML report card plus JSON + Markdown variants. Pass `--badge` to also emit a shields.io-style SVG you can drop into any README.
+
+```bash
+npx designlang grade $ARGUMENTS
+```
+
+If no `$ARGUMENTS` were supplied, ask the user which URL to grade.
+
+After the run completes:
+
+1. Read the generated `*.grade.md` file from `./design-extract-output/`
+2. Surface the headline grade (A–F · score · 8 dimensions)
+3. Highlight the top 3 strengths and top 3 issues from the report
+4. Offer to open the HTML in the browser (the `--open` flag does this automatically)
+
+If the user wants the live shareable badge URL instead of generating files locally, they can use:
+
+```markdown
+![Design Score](https://designlang.app/badge/<host>.svg)
+```
+
+This endpoint is blob-cached 24h with edge caching for ~50ms repeat hits.
+
+Compare two sites with `/battle <A> <B>`, restyle with `/remix`, bundle everything with `/pack`.

package/commands/pack.md

@@ -0,0 +1,37 @@
+---
+description: Bundle every designlang output (DTCG tokens, Tailwind, shadcn, Figma vars, motion, anatomy, Storybook, prompts) into one polished design-system directory ready to zip and ship.
+argument-hint: <url> [--with-clone] [--open]
+---
+
+Run the full extraction once and write every emitter output into a single, signed, layered directory.
+
+```bash
+npx designlang pack $ARGUMENTS
+```
+
+If no URL is provided, ask the user. Default output is `./<host>-design-system/`.
+
+Layout produced:
+
+```
+<host>-design-system/
+├── README.md           bespoke "Built from <host>" + grade + at-a-glance
+├── LICENSE.txt         provenance + usage guidance
+├── tokens/             DTCG + Tailwind + CSS vars + Figma vars + motion + theme.js
+├── components/         typed React stubs (anatomy.tsx)
+├── storybook/          runnable Storybook project
+├── starter/            minimal HTML starter wired to tokens/variables.css
+├── prompts/            v0 / Lovable / Cursor / Claude Artifacts + named recipes/*.md
+└── extras/             voice.json + prompt-pack.md rollup
+```
+
+After the run:
+
+1. Surface the headline (`X files, Y KB · ./<dir>`)
+2. Read the auto-generated `README.md` and tell the user what's inside
+3. Suggest next steps:
+   - `cd <dir> && zip -r ../<dir>.zip .` to package for sharing
+   - `cd <dir>/storybook && npm install && npm run storybook` to run the design system locally
+   - Copy `tokens/tailwind.config.js` straight into a project
+
+Use `--with-clone` to swap the minimal HTML starter for the full Next.js clone (slower; only when the user wants a runnable app).

package/commands/remix.md

@@ -0,0 +1,29 @@
+---
+description: Restyle a site in another design vocabulary — brutalist, swiss, art-deco, cyberpunk, soft-ui, or editorial. Preserves page shape, swaps the visual vocabulary.
+argument-hint: <url> --as <brutalist|swiss|art-deco|cyberpunk|soft-ui|editorial> | --all
+---
+
+Restyle the page shape of an extracted site under a different visual vocabulary.
+
+```bash
+npx designlang remix $ARGUMENTS
+```
+
+If `$ARGUMENTS` is empty, ask the user for a URL and offer the six vocabularies. If only a URL is given, default to `--all` so they see every variant side by side.
+
+The six vocabularies:
+
+| `--as <id>` | Vibe |
+|---|---|
+| `brutalist` | Raw, blocky, monospace, no shadows |
+| `swiss` | Clean grid, sans, minimal palette |
+| `art-deco` | Geometric, gold accents, serif display |
+| `cyberpunk` | Neon, dark, glowing CTAs |
+| `soft-ui` | Pastel, soft shadows, generous radii |
+| `editorial` | Newspaper feel, serif, narrow columns |
+
+Use `--all` to emit all six in one pass — six standalone HTML files plus a comparison index.
+
+After the run, read the comparison index (`*-remix-index.html` or `*-remix.<vocab>.html`) and tell the user which file to open. Offer to launch `--open` automatically.
+
+Pair with `/battle` for cross-vocab fights ("Stripe-as-cyberpunk vs Vercel-as-art-deco"), or `/pack` to bundle a remixed system as a downloadable design directory.

package/commands/theme-swap.md

@@ -0,0 +1,42 @@
+---
+description: Recolour an extracted site's design around a new brand primary. OKLCH hue rotation preserves perceptual lightness — neutrals, type, spacing, and motion stay untouched. Side-by-side HTML preview + recoloured tokens (DTCG, Tailwind, shadcn, Figma).
+argument-hint: <url> --primary <hex>  [--from <hex>] [--open]
+---
+
+Take any extracted site and swap its brand primary to the user-provided hex. The whole palette rotates around that hue while neutrals and structural tokens stay put.
+
+```bash
+npx designlang theme-swap $ARGUMENTS
+```
+
+If `$ARGUMENTS` doesn't contain both a URL and `--primary <hex>`, ask the user for the missing piece.
+
+After the run completes, all output goes to `./design-extract-output/`:
+
+- `*.themeswap.html` — editorial side-by-side preview (open this)
+- `*.themeswap.md` — markdown diff table
+- `*.themeswap.json` — structured before→after deltas
+- `*.themeswap.tokens.json` — recoloured DTCG token set you can drop into a project
+
+After the command finishes:
+
+1. Read `*.themeswap.md` to summarise the swap (`from → to`, hue shift, count of changed colours).
+2. Show the user the verdict line ("X colours changed, neutrals preserved, type/spacing/motion untouched").
+3. Offer to open the HTML preview (`--open` does this automatically).
+4. Suggest the recoloured token files as drop-ins for an existing Tailwind / shadcn project.
+
+## Useful flags
+
+| Flag | Effect |
+|---|---|
+| `--primary <hex>` | **required.** Target brand colour (e.g. `"#ff4800"`). |
+| `--from <hex>` | Override the auto-detected source primary when the extractor misclassifies (e.g. a neutral got promoted by usage count). |
+| `--format html\|md\|json\|tokens\|all` | Pick the output(s). Default `all`. |
+| `--out <dir>` | Output directory. Default `./design-extract-output`. |
+| `--open` | Open the HTML preview in your default browser. |
+
+## Pairs nicely with
+
+- `/grade <url>` — grade the recoloured site by feeding the same target through `/extract` then `/grade`.
+- `/pack <url>` — bundle the recoloured tokens as a downloadable design-system folder.
+- `/remix <url> --as <vocab>` — full vocabulary swap (brutalist, art-deco, cyberpunk…) instead of just brand colour.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "designlang",
-  "version": "12.3.0",
-  "description": "Extract the complete design language from any website and ship it — clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
+  "version": "12.7.1",
+  "description": "Extract the complete design language from any website and ship it \u2014 clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {
     "designlang": "./bin/design-extract.js"
@@ -48,4 +48,4 @@
   ],
   "author": "masyv",
   "license": "MIT"
-}
+}

package/src/ci.js

@@ -32,9 +32,43 @@ export async function runCi(url, opts) {
   out.push(`## designlang · design regression guard`);
   out.push(`\n**URL:** \`${url}\`  \n**Run:** ${new Date().toISOString()}\n`);
 
-  // 1. Extract
+  // 1. Extract — guard the throw site so CI artifacts never come back empty.
+  // Playwright can crash on flaky networks, ad-walled URLs, or self-signed
+  // proxies; when that happens we still want a report file + a summary.json
+  // so downstream jobs (artifact uploads, status comments, dashboards) have
+  // something to point at. We preserve the original error via `cause` so the
+  // stack survives — losing the trace was a real problem with #76's draft.
   const { extractDesignLanguage } = await import('./index.js');
-  const design = await extractDesignLanguage(url);
+  let design;
+  try {
+    design = await extractDesignLanguage(url);
+  } catch (err) {
+    const stack = err?.stack || String(err);
+    out.push(section('Extraction', [
+      `_failed — ${err.message}_`,
+      '',
+      '```',
+      stack,
+      '```',
+    ].join('\n')));
+    const md = out.join('\n');
+    const mdPath = join(outDir, 'ci-report.md');
+    writeFileSync(mdPath, md, 'utf-8');
+    const summary = {
+      url,
+      score: null,
+      grade: null,
+      driftVerdict: 'unknown',
+      extractionFailed: true,
+      error: err.message,
+      timestamp: new Date().toISOString(),
+    };
+    writeFileSync(join(outDir, 'ci-summary.json'), JSON.stringify(summary, null, 2), 'utf-8');
+    if (process.env.GITHUB_STEP_SUMMARY) {
+      try { writeFileSync(process.env.GITHUB_STEP_SUMMARY, md, { flag: 'a' }); } catch {}
+    }
+    return { mdPath, md, summary, shouldFail: true, cause: err };
+  }
 
   // 2. Score block
   if (design.score) {