designlang 11.0.2 → 11.2.0

package/SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 11.x    | :white_check_mark: |
+| 10.x    | :white_check_mark: (critical only) |
+| < 10    | :x:                |
+
+Only the latest minor of each supported major receives fixes.
+
+## Reporting a vulnerability
+
+**Please don't open a public issue.** Use GitHub's private vulnerability reporting instead:
+
+👉 <https://github.com/Manavarya09/design-extract/security/advisories/new>
+
+What to include:
+
+- A description of the issue and its impact.
+- A minimal repro (URL being extracted, CLI flags, OS + Node version).
+- Suggested severity and, if you have one, a proposed fix.
+
+### What to expect
+
+- Acknowledgement within **72 hours**.
+- A triage verdict (accepted / needs info / out of scope) within **7 days**.
+- Public disclosure coordinated with you after a fix ships — usually as part of a patch release.
+
+## Scope
+
+In scope:
+
+- The `designlang` CLI and all subcommands (`extract`, `clone`, `ci`, `studio`, `replay`, `mcp`, etc.).
+- The MCP server (`src/mcp/server.js`).
+- The hosted extractor website (`website/`) when used at its canonical URL.
+- The Figma, Chrome, Raycast, and VS Code extensions shipped in this repo.
+
+Out of scope:
+
+- Vulnerabilities that require the user to run `designlang` against a page **they themselves control** (i.e. self-owned XSS in content they feed us).
+- Denial of service via crafted sites that simply take a long time to extract — we already time-bound Playwright operations.
+- Browser-level shadow-DOM opacity (closed shadow roots are unreachable by web platform design, not a designlang bug).
+
+Thanks for taking the time to report responsibly.

package/bin/design-extract.js

@@ -85,6 +85,7 @@ program
   .option('--insecure', 'ignore HTTPS/SSL certificate errors (self-signed, dev, proxies)')
   .option('--ignore <selectors...>', 'CSS selectors to remove before extraction')
   .option('--ignore-widgets', 'Also ignore a curated list of third-party widgets (Intercom, Drift, HubSpot chat, cookie banners, reCAPTCHA, etc.)  See `designlang widgets`.')
+  .option('--storybook', 'Emit a runnable Storybook project (stories/, .storybook/, package.json) alongside the extraction')
   .option('--selector <css>', 'only extract design from elements matching this CSS selector (e.g. ".pricing-card")')
   .option('--system-chrome', 'use the system Chrome install instead of the bundled Chromium (skips the 150MB Playwright download)')
   .option('--tokens-legacy', 'Emit pre-v7 flat token JSON (backward compat)')
@@ -93,6 +94,7 @@ program
   .option('--smart', 'use optional LLM fallback when heuristic classifiers have low confidence (needs OPENAI_API_KEY or ANTHROPIC_API_KEY)')
   .option('--pages <n>', 'crawl N canonical pages (pricing/docs/blog/about/product) in addition to the homepage', parseInt)
   .option('--no-prompts', 'skip writing the prompt-pack directory')
+  .option('--no-design-md', 'skip writing the agent-native DESIGN.md (single-file, 8-section, YAML front matter)')
   .option('--responsive-shots', 'capture full-page PNGs at 4 breakpoints × (light,dark)')
   .option('--perf', 'measure Core Web Vitals + bundle profile (LCP/CLS/INP, JS/CSS/font/img bytes, third-party count)')
   .option('--json', 'output raw JSON to stdout (for CI/CD)')
@@ -351,6 +353,13 @@ program
       }
       files.push({ name: `${prefix}-voice.json`, content: JSON.stringify(design.voice || {}, null, 2), label: 'Brand Voice' });
 
+      // v11.2: agent-native single-file DESIGN.md (compatible with the
+      // 8-canonical-section convention; default-on, opt-out via --no-design-md).
+      if (merged.designMd !== false) {
+        const { formatDesignMd } = await import('../src/formatters/design-md.js');
+        files.push({ name: `${prefix}-DESIGN.md`, content: formatDesignMd(design), label: 'DESIGN.md (agent-native)' });
+      }
+
       // v10: page intent + section roles + visual DNA + component library + multi-page + prompt pack.
       files.push({ name: `${prefix}-intent.json`, content: JSON.stringify({ pageIntent: design.pageIntent, sectionRoles: design.sectionRoles }, null, 2), label: 'Page Intent + Section Roles' });
       files.push({ name: `${prefix}-visual-dna.json`, content: JSON.stringify({ materialLanguage: design.materialLanguage, imageryStyle: design.imageryStyle, backgroundPatterns: design.backgroundPatterns }, null, 2), label: 'Visual DNA' });
@@ -473,6 +482,20 @@ program
         }
       }
 
+      // Storybook project (opt-in via --storybook)
+      if (merged.storybook && Array.isArray(design.componentAnatomy) && design.componentAnatomy.length > 0) {
+        const { formatStorybook } = await import('../src/formatters/storybook.js');
+        const sbFiles = formatStorybook(design);
+        const sbDir = join(outDir, `${prefix}-storybook`);
+        mkdirSync(sbDir, { recursive: true });
+        for (const [rel, content] of Object.entries(sbFiles)) {
+          const p = join(sbDir, rel);
+          mkdirSync(join(p, '..'), { recursive: true });
+          writeFileSync(p, content, 'utf-8');
+          platformFiles.push({ path: p, label: `Storybook (${rel})` });
+        }
+      }
+
       // Save to history
       if (opts.history !== false) {
         const histInfo = saveSnapshot(design);
@@ -1062,6 +1085,46 @@ program
     }
   });
 
+// ── Replay — record a short WebM of motion from a URL ─────
+program
+  .command('replay <url>')
+  .description('Record a short WebM clip of a site\'s motion (scroll + hover). Optional MP4 if ffmpeg is on PATH.')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix', 'motion-replay')
+  .option('-d, --duration <s>', 'duration in seconds (2-15)', parseInt, 5)
+  .option('-w, --width <px>', 'viewport width', parseInt, 1280)
+  .option('--height <px>', 'viewport height', parseInt, 800)
+  .option('--mp4', 'also emit an MP4 (requires ffmpeg on PATH)')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+    const spinner = ora('Recording motion replay...').start();
+    try {
+      const { recordReplay } = await import('../src/replay.js');
+      const r = await recordReplay(url, {
+        out: opts.out,
+        prefix: opts.name,
+        duration: opts.duration,
+        width: opts.width,
+        height: opts.height,
+        mp4: opts.mp4,
+      });
+      if (!r.webm) {
+        spinner.fail('No video was produced. The browser may have blocked recording; try a different URL.');
+        process.exit(1);
+      }
+      spinner.succeed(`Replay captured (${r.duration}s)`);
+      console.log('');
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan(r.webm)} — WebM`);
+      if (r.mp4) console.log(`  ${chalk.green('✓')} ${chalk.cyan(r.mp4)} — MP4`);
+      else if (opts.mp4) console.log(`  ${chalk.gray('note: ffmpeg not found on PATH; MP4 skipped')}`);
+      console.log('');
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
 // ── Widgets — print the curated third-party widget ignore list ─
 program
   .command('widgets')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "11.0.2",
+  "version": "11.2.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.",
   "type": "module",
   "bin": {

package/src/formatters/design-md.js

@@ -0,0 +1,319 @@
+// DESIGN.md — agent-native single-file output. Compatible with the
+// 8-canonical-section convention (Overview · Colors · Typography · Layout
+// · Elevation and Depth · Shapes · Components · Do's and Don'ts), plus
+// YAML front matter holding the machine-readable token snapshot.
+//
+// Designed to be a drop-in replacement for design-extractor.com's
+// DESIGN.md output, but driven by the v10/v11 semantic layer (intent,
+// material, voice, anatomy, library detection) rather than just colors.
+
+import { readFileSync } from 'fs';
+
+function yamlString(v) {
+  if (v == null) return '~';
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  const s = String(v);
+  if (s === '' || /[:#&*!?[\]{},|>%@`'"\n]/.test(s) || /^\s|\s$/.test(s)) {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+
+function yamlList(arr, indent = '    ') {
+  if (!arr || arr.length === 0) return '[]';
+  return '\n' + arr.map(v => `${indent}- ${yamlString(v)}`).join('\n');
+}
+
+function yamlMap(obj, indent = '    ') {
+  const entries = Object.entries(obj || {}).filter(([, v]) => v != null);
+  if (entries.length === 0) return '{}';
+  return '\n' + entries.map(([k, v]) => `${indent}${k}: ${yamlString(v)}`).join('\n');
+}
+
+function topColor(colors, role) {
+  return colors?.[role]?.hex || null;
+}
+
+function fmtPx(v) {
+  if (v == null) return null;
+  const n = typeof v === 'number' ? v : parseFloat(String(v));
+  return Number.isFinite(n) ? `${Math.round(n)}px` : String(v);
+}
+
+function uniq(arr) { return [...new Set(arr.filter(Boolean))]; }
+
+function pickHeading(voice, fallback) {
+  const s = (voice?.sampleHeadings || []).find(h => h && h.length > 4 && h.length < 80);
+  return s || fallback;
+}
+
+function ratioLine(v, n) { return `${v} (${n})`; }
+
+// ─── Section renderers ─────────────────────────────────────────
+
+function sectionOverview(design) {
+  const intent = design.pageIntent?.type || 'landing';
+  const intentConf = design.pageIntent?.confidence;
+  const material = design.materialLanguage?.label || 'flat';
+  const matConf = design.materialLanguage?.confidence;
+  const library = design.componentLibrary?.library;
+  const libConf = design.componentLibrary?.confidence;
+  const order = (design.sectionRoles?.readingOrder || []).join(' → ') || '—';
+  const voice = design.voice || {};
+  const tone = voice.tone || 'neutral';
+  const lede = pickHeading(voice, design.meta?.title || '');
+  const url = design.meta?.url || '';
+
+  const lines = [];
+  lines.push(`A **${intent}** page${intentConf ? ` (heuristic confidence ${intentConf})` : ''}, dressed in **${material}** material${matConf ? ` (${matConf})` : ''}.`);
+  if (library && library !== 'unknown') {
+    lines.push('');
+    lines.push(`Component library appears to be **${library}**${libConf ? ` (${libConf})` : ''}.`);
+  }
+  if (lede) {
+    lines.push('');
+    lines.push(`> "${lede}"`);
+  }
+  lines.push('');
+  lines.push(`The author writes in a **${tone}** voice; headings tend to be **${voice.headingStyle || 'sentence'}** case and **${voice.headingLengthClass || 'balanced'}**.`);
+  lines.push('');
+  lines.push(`Reading order detected on the source: \`${order}\`.`);
+  if (url) {
+    lines.push('');
+    lines.push(`Source: <${url}>.`);
+  }
+  return lines.join('\n');
+}
+
+function sectionColors(design) {
+  const c = design.colors || {};
+  const lines = ['| role | hex | usage |', '|---|---|---|'];
+  const rows = [
+    ['primary',     c.primary?.hex,     c.primary?.count],
+    ['secondary',   c.secondary?.hex,   c.secondary?.count],
+    ['accent',      c.accent?.hex,      c.accent?.count],
+    ['background',  c.backgrounds?.[0], '—'],
+    ['foreground',  c.text?.[0],        '—'],
+  ];
+  for (const [role, hex, count] of rows) {
+    if (!hex) continue;
+    lines.push(`| ${role} | \`${hex}\` | ${count ?? '—'} |`);
+  }
+  const neutrals = (c.neutrals || []).slice(0, 5);
+  if (neutrals.length) {
+    lines.push('');
+    lines.push('**Neutrals:** ' + neutrals.map(n => `\`${n.hex}\``).join(' · '));
+  }
+  if (c.all?.length) {
+    lines.push('');
+    lines.push(`**Total unique colors detected:** ${c.all.length}.`);
+  }
+  return lines.join('\n');
+}
+
+function sectionTypography(design) {
+  const t = design.typography || {};
+  const lines = [];
+  if (t.families?.length) {
+    lines.push('**Families**');
+    for (const f of t.families.slice(0, 4)) {
+      lines.push(`- \`${f.name}\`${f.weights ? ` — weights ${[...new Set(f.weights)].join(', ')}` : ''}${f.count ? ` · ${f.count} uses` : ''}`);
+    }
+  }
+  if (t.body?.size) {
+    lines.push('');
+    lines.push(`**Body size:** \`${t.body.size}px\` / line-height \`${t.body.lineHeight ?? '1.5'}\`.`);
+  }
+  if (t.headings?.length) {
+    lines.push('');
+    lines.push('**Heading scale**');
+    lines.push('| level | size | weight | line-height |');
+    lines.push('|---|---|---|---|');
+    for (const [i, h] of t.headings.slice(0, 4).entries()) {
+      lines.push(`| h${i + 1} | \`${h.size}px\` | \`${h.weight}\` | \`${h.lineHeight}\` |`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function sectionLayout(design) {
+  const sp = design.spacing || {};
+  const bp = design.breakpoints || [];
+  const layout = design.layout || {};
+  const lines = [];
+  if (sp.base) lines.push(`**Spacing base:** \`${sp.base}px\` increments.`);
+  if (sp.scale?.length) lines.push(`**Scale:** ${sp.scale.slice(0, 10).map(s => `\`${(s.value ?? s)}px\``).join(' · ')}`);
+  if (layout.gridCount != null || layout.flexCount != null) {
+    lines.push('');
+    lines.push(`**Layout primitives:** ${layout.gridCount ?? 0} grid containers · ${layout.flexCount ?? 0} flex containers.`);
+  }
+  if (bp.length) {
+    lines.push('');
+    lines.push(`**Breakpoints:** ${bp.map(b => `\`${b}px\``).join(' · ')}`);
+  }
+  return lines.join('\n') || '_No layout signals captured._';
+}
+
+function sectionElevation(design) {
+  const sh = design.shadows?.values || [];
+  const z = design.zIndex || {};
+  const lines = [];
+  if (sh.length) {
+    lines.push('**Shadow scale**');
+    for (const s of sh.slice(0, 6)) {
+      lines.push(`- \`${s.label || '?'}\` — \`${s.raw || s.value}\``);
+    }
+  } else {
+    lines.push('_No discrete shadow tokens detected — flat material._');
+  }
+  if (z.allValues?.length) {
+    lines.push('');
+    lines.push(`**Z-index layers:** ${z.allValues.length}${z.issues?.length ? ` · ⚠ ${z.issues.length} issue(s)` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+function sectionShapes(design) {
+  const r = design.borders?.radii || [];
+  const lines = [];
+  if (r.length) {
+    lines.push('**Radius scale**');
+    for (const x of r.slice(0, 6)) lines.push(`- \`${x.label || '?'}\` — \`${x.value}px\``);
+  } else {
+    lines.push('_No discrete radius tokens detected — sharp/brutalist shapes._');
+  }
+  return lines.join('\n');
+}
+
+function sectionComponents(design) {
+  const lines = [];
+  const detected = Object.keys(design.components || {});
+  if (detected.length) {
+    lines.push(`**Detected patterns:** ${detected.map(c => `\`${c}\``).join(' · ')}`);
+    lines.push('');
+  }
+  const anatomies = design.componentAnatomy || [];
+  if (anatomies.length) {
+    lines.push('**Anatomy**');
+    lines.push('| kind | variants | sizes | instances |');
+    lines.push('|---|---|---|---|');
+    for (const a of anatomies.slice(0, 8)) {
+      const variants = (a.props?.variant || []).join(', ') || '—';
+      const sizes = (a.props?.size || []).join(', ') || '—';
+      lines.push(`| ${a.kind} | ${variants} | ${sizes} | ${a.totalInstances ?? '—'} |`);
+    }
+  }
+  if (!lines.length) lines.push('_No component anatomy extracted._');
+  return lines.join('\n');
+}
+
+function sectionDosDonts(design) {
+  const voice = design.voice || {};
+  const score = design.score || {};
+  const a11y = design.accessibility || {};
+  const lines = [];
+
+  lines.push("**Do's**");
+  const dos = [];
+  const ctas = (voice.ctaVerbs || []).slice(0, 3).map(v => v.value).filter(Boolean);
+  if (ctas.length) dos.push(`Use \`${ctas.join('\`, \`')}\` as the primary verbs in CTAs — these dominate the source.`);
+  if (voice.headingStyle) dos.push(`Write headings in **${voice.headingStyle}** case, **${voice.headingLengthClass || 'balanced'}** length.`);
+  if (voice.pronoun && voice.pronoun !== 'neutral') dos.push(`Address the reader with the pronoun posture **${voice.pronoun}**.`);
+  if (design.materialLanguage?.label) dos.push(`Stay inside the **${design.materialLanguage.label}** material — match shadow and radius habits.`);
+  if (!dos.length) dos.push('_No strong directional signals captured._');
+  for (const d of dos) lines.push(`- ${d}`);
+
+  lines.push('');
+  lines.push("**Don'ts**");
+  const donts = [];
+  if (a11y.failCount > 0) donts.push(`Don't ship copy on the colors flagged in accessibility — ${a11y.failCount} contrast pair(s) fail WCAG AA on the source itself.`);
+  if (score.issues?.length) for (const i of score.issues.slice(0, 4)) donts.push(`Don't ${i.toLowerCase().replace(/^./, c => c.toLowerCase())}.`);
+  if (!donts.length) donts.push("_No anti-patterns surfaced. Don't invent new tokens — reuse the scale above._");
+  for (const d of donts) lines.push(`- ${d}`);
+
+  return lines.join('\n');
+}
+
+// ─── YAML front matter ─────────────────────────────────────────
+
+function frontMatter(design, version) {
+  const url = design.meta?.url || '';
+  const title = design.meta?.title || '';
+  const c = design.colors || {};
+  const t = design.typography || {};
+  const sp = design.spacing || {};
+  const r = design.borders?.radii || [];
+  const sh = design.shadows?.values || [];
+
+  const lines = ['---'];
+  lines.push(`site: ${yamlString(title || url)}`);
+  if (url) lines.push(`url: ${yamlString(url)}`);
+  lines.push(`generated_at: ${yamlString(new Date().toISOString())}`);
+  lines.push(`generator: ${yamlString(`designlang@${version}`)}`);
+  if (design.pageIntent?.type) lines.push(`intent: ${yamlString(design.pageIntent.type)}`);
+  if (design.materialLanguage?.label) lines.push(`material: ${yamlString(design.materialLanguage.label)}`);
+  if (design.componentLibrary?.library && design.componentLibrary.library !== 'unknown') {
+    lines.push(`library: ${yamlString(design.componentLibrary.library)}`);
+  }
+
+  lines.push('tokens:');
+  lines.push('  colors:' + yamlMap({
+    primary: topColor(c, 'primary'),
+    secondary: topColor(c, 'secondary'),
+    accent: topColor(c, 'accent'),
+    background: c.backgrounds?.[0],
+    foreground: c.text?.[0],
+  }, '    '));
+  lines.push('  typography:' + yamlMap({
+    sans: t.families?.[0]?.name,
+    mono: t.families?.find(f => /mono/i.test(f.name))?.name,
+    base: t.body?.size,
+  }, '    '));
+  lines.push('  spacing:' + yamlMap({
+    base: sp.base,
+    scale: sp.scale?.length ? '[' + sp.scale.slice(0, 10).map(s => (s.value ?? s)).join(', ') + ']' : null,
+  }, '    '));
+  if (r.length) {
+    lines.push('  radii:' + yamlMap(Object.fromEntries(r.slice(0, 6).map(x => [x.label || `r${x.value}`, x.value])), '    '));
+  }
+  if (sh.length) {
+    lines.push('  shadows:' + yamlMap(Object.fromEntries(sh.slice(0, 4).map(x => [x.label || 'shadow', x.raw || x.value])), '    '));
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+// ─── Main ──────────────────────────────────────────────────────
+
+let CACHED_VERSION = null;
+function pkgVersion() {
+  if (CACHED_VERSION) return CACHED_VERSION;
+  try {
+    const url = new URL('../../package.json', import.meta.url);
+    CACHED_VERSION = JSON.parse(readFileSync(url, 'utf-8')).version;
+  } catch { CACHED_VERSION = '0.0.0'; }
+  return CACHED_VERSION;
+}
+
+export function formatDesignMd(design) {
+  const version = pkgVersion();
+  const fm = frontMatter(design, version);
+
+  const sections = [
+    ['Overview',            sectionOverview(design)],
+    ['Colors',              sectionColors(design)],
+    ['Typography',          sectionTypography(design)],
+    ['Layout',              sectionLayout(design)],
+    ['Elevation and Depth', sectionElevation(design)],
+    ['Shapes',              sectionShapes(design)],
+    ['Components',          sectionComponents(design)],
+    ["Do's and Don'ts",     sectionDosDonts(design)],
+  ];
+
+  const body = sections.map(([h, b]) => `# ${h}\n\n${b || '_—_'}\n`).join('\n');
+
+  const sourceUrl = design.meta?.url || '';
+  const footer = `\n---\n_Generated by [designlang](https://github.com/Manavarya09/design-extract) v${version} from <${sourceUrl}>._\n_Compatible with the DESIGN.md convention pioneered by [design-extractor.com](https://www.design-extractor.com) — extended with intent, material, voice, anatomy, and library detection._\n`;
+
+  return `${fm}\n\n${body}${footer}`;
+}

package/src/formatters/storybook.js

@@ -0,0 +1,225 @@
+// Storybook emitter — turns extracted componentAnatomy + design tokens into
+// a runnable CSF3 Storybook project. Writes stories/*, .storybook/*, and a
+// README showing the install + run steps. Zero Storybook dependency in
+// designlang itself; the emitted project installs its own.
+//
+// Consumer wiring (bin):
+//   if (merged.storybook && (design.componentAnatomy || []).length) {
+//     const { formatStorybook } = await import('../src/formatters/storybook.js');
+//     const files = formatStorybook(design);
+//     for (const [rel, content] of Object.entries(files)) {
+//       writeFileSync(join(outDir, 'storybook', rel), content);
+//     }
+//   }
+
+function cap(s) { return s.charAt(0).toUpperCase() + s.slice(1); }
+
+function htmlTagFor(kind) {
+  return kind === 'input' ? 'input'
+    : kind === 'link' ? 'a'
+    : kind === 'card' ? 'div'
+    : 'button';
+}
+
+function storyFor(anatomy, tokenVars) {
+  const Name = cap(anatomy.kind);
+  const variants = anatomy.props.variant.length ? anatomy.props.variant : ['default'];
+  const sizes = anatomy.props.size.length ? anatomy.props.size : ['md'];
+  const tag = htmlTagFor(anatomy.kind);
+  const hasIcon = !!anatomy.slots?.icon;
+  const hasBadge = !!anatomy.slots?.badge;
+
+  const sampleLabel = anatomy.kind === 'card' ? 'Card content'
+    : anatomy.kind === 'input' ? ''
+    : anatomy.kind === 'link' ? 'Read more'
+    : 'Button';
+
+  // Render via inline React to keep the emitted project dependency-light.
+  const render = `(args) => {
+    const style = {
+      fontFamily: 'var(--font-sans, inherit)',
+      padding: args.size === 'sm' ? '6px 12px' : args.size === 'lg' ? '14px 22px' : '10px 16px',
+      borderRadius: 'var(--radius, 8px)',
+      background: args.variant === 'secondary' ? 'transparent'
+        : args.variant === 'outline' ? 'transparent'
+        : 'var(--color-primary, #3b82f6)',
+      color: args.variant === 'secondary' || args.variant === 'outline' ? 'var(--color-foreground, #111)' : '#fff',
+      border: args.variant === 'outline' ? '1px solid var(--color-foreground, #111)' : 'none',
+      fontWeight: 500,
+      cursor: 'pointer',
+    };
+    return React.createElement('${tag}', { style, 'data-variant': args.variant, 'data-size': args.size },
+      '${sampleLabel}'${hasIcon ? ", React.createElement('span', { style: { marginLeft: 8 } }, '→')" : ''}${hasBadge ? ", React.createElement('span', { style: { marginLeft: 6, padding: '2px 6px', background: '#f59e0b', borderRadius: 99, color: '#fff', fontSize: 11 } }, '3')" : ''}
+    );
+  }`;
+
+  return `import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+// Extracted from a live site by \`designlang\`. No runtime library —
+// these stories render inline to stay dependency-free.
+const ${Name}: React.FC<{ variant?: string; size?: string }> = ${render};
+
+const meta: Meta<typeof ${Name}> = {
+  title: 'Extracted/${Name}',
+  component: ${Name},
+  tags: ['autodocs'],
+  argTypes: {
+    variant: { control: 'select', options: [${variants.map(v => `'${v}'`).join(', ')}] },
+    size:    { control: 'select', options: [${sizes.map(s => `'${s}'`).join(', ')}] },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: '${anatomy.kind} — ${anatomy.totalInstances || 0} instances detected across the page.',
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ${Name}>;
+
+${variants.map(v => `export const ${cap(v)}: Story = { args: { variant: '${v}', size: '${sizes[0]}' } };`).join('\n')}
+
+export const Sizes: Story = {
+  render: () => React.createElement('div', { style: { display: 'flex', gap: 12, alignItems: 'center' } },
+    ${sizes.map(s => `React.createElement(${Name}, { key: '${s}', variant: '${variants[0]}', size: '${s}' })`).join(',\n    ')}
+  ),
+};
+`;
+}
+
+function tokensCss(design) {
+  const colors = design.colors || {};
+  const primary = colors.primary?.hex || '#3b82f6';
+  const secondary = colors.secondary?.hex || '#8b5cf6';
+  const accent = colors.accent?.hex || '#f59e0b';
+  const bg = colors.backgrounds?.[0] || '#ffffff';
+  const fg = colors.text?.[0] || '#171717';
+  const radii = design.borders?.radii || [];
+  const radius = radii.find(r => r.label === 'md')?.value ?? 8;
+  const shadow = design.shadows?.values?.find(s => s.label === 'md')?.raw || '0 4px 6px rgba(0,0,0,0.1)';
+  const font = design.typography?.families?.[0]?.name || 'Inter';
+  return `:root {
+  --color-primary: ${primary};
+  --color-secondary: ${secondary};
+  --color-accent: ${accent};
+  --color-background: ${bg};
+  --color-foreground: ${fg};
+  --radius: ${radius}px;
+  --shadow: ${shadow};
+  --font-sans: '${font}', system-ui, sans-serif;
+}
+body { background: var(--color-background); color: var(--color-foreground); font-family: var(--font-sans); }
+`;
+}
+
+export function formatStorybook(design) {
+  const anatomies = design.componentAnatomy || [];
+  const files = {};
+
+  // Story files (one per kind).
+  for (const a of anatomies) {
+    const Name = cap(a.kind);
+    files[`stories/${Name}.stories.tsx`] = storyFor(a, design);
+  }
+
+  // A tokens page so people can see the palette/scale inline.
+  files['stories/Tokens.mdx'] = `import { Meta, ColorPalette, ColorItem, Typeset } from '@storybook/blocks';
+
+<Meta title="Extracted/Tokens" />
+
+# Design tokens
+
+Extracted from ${design.meta?.url || 'the target site'} by [designlang](https://github.com/Manavarya09/design-extract).
+
+<ColorPalette>
+  <ColorItem title="primary"    colors={{ primary: '${design.colors?.primary?.hex || '#3b82f6'}' }} />
+  <ColorItem title="secondary"  colors={{ secondary: '${design.colors?.secondary?.hex || '#8b5cf6'}' }} />
+  <ColorItem title="accent"     colors={{ accent: '${design.colors?.accent?.hex || '#f59e0b'}' }} />
+  <ColorItem title="background" colors={{ background: '${design.colors?.backgrounds?.[0] || '#ffffff'}' }} />
+  <ColorItem title="foreground" colors={{ foreground: '${design.colors?.text?.[0] || '#171717'}' }} />
+</ColorPalette>
+`;
+
+  files['stories/tokens.css'] = tokensCss(design);
+
+  files['.storybook/main.ts'] = `import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../stories/**/*.mdx', '../stories/**/*.stories.@(ts|tsx)'],
+  addons: ['@storybook/addon-essentials', '@storybook/addon-docs'],
+  framework: { name: '@storybook/react-vite', options: {} },
+};
+export default config;
+`;
+
+  files['.storybook/preview.ts'] = `import type { Preview } from '@storybook/react';
+import './../stories/tokens.css';
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: { default: 'paper' },
+    controls: { matchers: { color: /(background|color)$/i } },
+  },
+};
+export default preview;
+`;
+
+  files['package.json'] = JSON.stringify({
+    name: `${(design.meta?.title || 'extracted').toLowerCase().replace(/[^a-z0-9]/g, '-').slice(0, 40) || 'extracted'}-storybook`,
+    private: true,
+    version: '0.1.0',
+    type: 'module',
+    scripts: {
+      storybook: 'storybook dev -p 6006',
+      'build-storybook': 'storybook build',
+    },
+    dependencies: { react: '^19.0.0', 'react-dom': '^19.0.0' },
+    devDependencies: {
+      '@storybook/addon-essentials': '^8.0.0',
+      '@storybook/addon-docs': '^8.0.0',
+      '@storybook/blocks': '^8.0.0',
+      '@storybook/react': '^8.0.0',
+      '@storybook/react-vite': '^8.0.0',
+      '@types/react': '^19.0.0',
+      '@types/react-dom': '^19.0.0',
+      storybook: '^8.0.0',
+      typescript: '^5.0.0',
+      vite: '^5.0.0',
+    },
+  }, null, 2);
+
+  files['tsconfig.json'] = JSON.stringify({
+    compilerOptions: {
+      target: 'ES2020',
+      module: 'ESNext',
+      moduleResolution: 'Bundler',
+      jsx: 'react-jsx',
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+    },
+    include: ['stories/**/*', '.storybook/**/*'],
+  }, null, 2);
+
+  files['README.md'] = `# ${design.meta?.title || 'Extracted'} · Storybook
+
+Auto-generated by \`designlang <url> --storybook\`.
+
+## Stories
+${anatomies.map(a => `- **${cap(a.kind)}** — ${a.props.variant.length || 1} variant(s), ${a.props.size.length || 1} size(s), ${a.totalInstances || 0} detected`).join('\n') || '_No anatomy detected on the source page._'}
+
+## Run
+
+\`\`\`
+npm install
+npm run storybook
+\`\`\`
+
+Opens at http://localhost:6006.
+`;
+
+  return files;
+}

package/src/replay.js

@@ -0,0 +1,131 @@
+// Motion replay — records a short WebM of a site with scripted
+// interactions (hover/scroll) so the captured motion actually fires.
+// Zero new deps: Playwright ships video recording out of the box.
+//
+// Output: <prefix>-motion.webm  (+ optional MP4 if ffmpeg is on PATH)
+//
+// Usage: designlang replay <url> [--duration 5] [--out dir]
+
+import { chromium } from 'playwright';
+import { mkdirSync, existsSync, readdirSync, statSync, renameSync, unlinkSync, rmdirSync } from 'fs';
+import { resolve, join } from 'path';
+import { spawnSync } from 'child_process';
+
+async function ensureFfmpeg() {
+  try {
+    const r = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function toMp4(webmPath) {
+  const mp4Path = webmPath.replace(/\.webm$/, '.mp4');
+  const r = spawnSync('ffmpeg', ['-y', '-i', webmPath, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', mp4Path], { stdio: 'ignore' });
+  return r.status === 0 ? mp4Path : null;
+}
+
+export async function recordReplay(url, opts = {}) {
+  const outDir = resolve(opts.out || './design-extract-output');
+  mkdirSync(outDir, { recursive: true });
+  const prefix = opts.prefix || 'motion-replay';
+  const duration = Math.max(2, Math.min(15, parseInt(opts.duration) || 5));
+  const width = parseInt(opts.width) || 1280;
+  const height = parseInt(opts.height) || 800;
+
+  const videoDir = join(outDir, `.playwright-video-${Date.now()}`);
+  mkdirSync(videoDir, { recursive: true });
+
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width, height },
+    recordVideo: { dir: videoDir, size: { width, height } },
+    reducedMotion: 'no-preference',
+  });
+  const page = await context.newPage();
+
+  try {
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 25000 });
+  } catch {
+    try { await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 }); } catch {}
+  }
+
+  // Scripted motion pass: slow scroll → hover first CTA → scroll back.
+  const frameMs = 50;
+  const steps = Math.floor((duration * 1000) / frameMs);
+  for (let i = 0; i < steps; i++) {
+    const progress = i / steps;
+    // Slow smooth scroll across the page
+    await page.evaluate((p) => {
+      const max = Math.max(document.body.scrollHeight - window.innerHeight, 0);
+      window.scrollTo({ top: max * p, behavior: 'auto' });
+    }, progress).catch(() => {});
+    // Partway through, hover a button to trigger transition states.
+    if (i === Math.floor(steps / 2)) {
+      try {
+        const btn = await page.$('button, [role="button"], a.btn, .button, [class*="btn"]');
+        if (btn) await btn.hover({ timeout: 1000 }).catch(() => {});
+      } catch {}
+    }
+    await page.waitForTimeout(frameMs);
+  }
+
+  const videoPromise = page.video();
+  await context.close();
+  await browser.close();
+
+  // Move the captured WebM out of the Playwright temp dir.
+  const finalWebm = join(outDir, `${prefix}.webm`);
+  try {
+    const video = await videoPromise;
+    if (video && typeof video.path === 'function') {
+      const src = await video.path();
+      if (src && existsSync(src)) {
+        renameSync(src, finalWebm);
+      }
+    } else {
+      // Fallback: grab whatever .webm Playwright wrote to the dir.
+      const produced = readdirSync(videoDir).filter(f => f.endsWith('.webm'))
+        .map(f => ({ f, t: statSync(join(videoDir, f)).mtimeMs }))
+        .sort((a, b) => b.t - a.t)[0];
+      if (produced) renameSync(join(videoDir, produced.f), finalWebm);
+    }
+  } catch { /* no video — fall through with null result */ }
+
+  // Clean the scratch dir.
+  try {
+    for (const f of readdirSync(videoDir)) unlinkSync(join(videoDir, f));
+    rmdirSync(videoDir);
+  } catch {}
+
+  const result = {
+    url,
+    webm: existsSync(finalWebm) ? finalWebm : null,
+    mp4: null,
+    duration,
+    width,
+    height,
+  };
+
+  if (result.webm && opts.mp4 && await ensureFfmpeg()) {
+    const mp4 = toMp4(result.webm);
+    if (mp4) result.mp4 = mp4;
+  }
+
+  return result;
+}
+
+// Tiny snippet that can be spliced into the existing HTML preview to embed
+// the replay next to the static screenshot. Consumer decides where to place.
+export function replayEmbedHtml(result) {
+  if (!result?.webm) return '';
+  const src = result.webm.split(/[\\/]/).pop();
+  return `<figure class="motion-replay" style="margin:24px 0">
+  <video autoplay loop muted playsinline style="width:100%;border:1px solid #0a0908">
+    <source src="${src}" type="video/webm" />
+    ${result.mp4 ? `<source src="${result.mp4.split(/[\\/]/).pop()}" type="video/mp4" />` : ''}
+  </video>
+  <figcaption style="font-family:var(--font-mono, monospace);font-size:11px;letter-spacing:0.12em;text-transform:uppercase;color:#403c34;margin-top:8px">
+    motion replay · ${result.duration}s · ${result.width}×${result.height}
+  </figcaption>
+</figure>`;
+}