designlang 10.4.0 → 11.0.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [10.5.0] — 2026-04-22
+
+**The states LLMs always botch.**
+
+### Added
+
+- **`src/extractors/form-states.js`** — surfaces forms (input count + style families), modal/dialog/sheet containers, skeleton and spinner loading indicators, empty-state and error-state placeholders, and detects which toast library is on the page (Sonner, react-hot-toast, react-toastify, Radix Toast, Chakra Toast, Notistack).
+- New output: `*-form-states.json`.
+
+Closes the v10.x minor-release series started in v10.1. Everything the
+v10 spec deferred for v11 is now shipped as minor releases — with no
+breaking changes along the way.
+
 ## [10.4.0] — 2026-04-22
 
 **Identification trio: icon system, background patterns, stack intel.**

package/README.md

@@ -7,7 +7,7 @@
   <a href="https://github.com/Manavarya09/design-extract/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Manavarya09/design-extract?color=0A0908&labelColor=F3F1EA" alt="license"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/designlang?color=0A0908&labelColor=F3F1EA" alt="node version"></a>
   <a href="https://designlang.manavaryasingh.com/"><img src="https://img.shields.io/badge/website-live-FF4800?labelColor=F3F1EA" alt="website"></a>
-[![SafeSkill 77/100](https://img.shields.io/badge/SafeSkill-77%2F100_Passes%20with%20Notes-yellow)](https://safeskill.dev/scan/manavarya09-design-extract)
+
 </p>
 
 ---
@@ -634,7 +634,7 @@ In Claude Code, use `/extract-design <url>`.
 
 ## Website
 
-**[design-extract-beta.vercel.app](https://design-extract-beta.vercel.app)** — the brutalist product page.
+**[https://designlang.manavaryasingh.com](https://designlang.manavaryasingh.com/)** — the brutalist product page.
 
 ## Contributing
 

package/bin/design-extract.js

@@ -376,6 +376,9 @@ program
       if (design.stackIntel) {
         files.push({ name: `${prefix}-stack-intel.json`, content: JSON.stringify(design.stackIntel, null, 2), label: 'Stack Intel (CMS/analytics/experimentation)' });
       }
+      if (design.formStates) {
+        files.push({ name: `${prefix}-form-states.json`, content: JSON.stringify(design.formStates, null, 2), label: 'Forms + States' });
+      }
       if (merged.prompts !== false) {
         const pack = buildPromptPack(design);
         const promptsDir = join(outDir, `${prefix}-prompts`);
@@ -1053,6 +1056,66 @@ program
     }
   });
 
+// ── CI command — single PR-comment-ready report ────────────
+program
+  .command('ci <url>')
+  .description('One-shot design regression report — drift + score + PR-ready markdown. Works in any CI.')
+  .option('--tokens <file>', 'local tokens file (.json or .css) to compare against the live site')
+  .option('--baseline <url>', 'baseline URL for a before/after visual diff')
+  .option('--tolerance <n>', 'color distance tolerance (0-50)', parseInt, 8)
+  .option('--fail-on <level>', 'exit non-zero on: minor-drift | notable-drift | major-drift', 'notable-drift')
+  .option('-o, --out <dir>', 'output directory', '.designlang-ci')
+  .option('--quiet', 'suppress stdout (still writes files)')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+    const spinner = opts.quiet ? { start() { return this; }, succeed() {}, fail() {}, set text(v) {} } : ora('Running CI report...').start();
+    try {
+      const { runCi } = await import('../src/ci.js');
+      const r = await runCi(url, opts);
+      spinner.succeed(`CI report written → ${r.mdPath}`);
+      if (!opts.quiet) {
+        console.log('');
+        console.log(r.md);
+      }
+      if (r.shouldFail) process.exit(1);
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
+// ── Studio — local web studio over the latest extraction ──
+program
+  .command('studio')
+  .description('Launch a local web studio over the latest extraction (editorial token browser, voice, motion, DNA).')
+  .option('-d, --dir <path>', 'extraction directory', './design-extract-output')
+  .option('-p, --port <n>', 'port', parseInt, 4837)
+  .option('--prefix <name>', 'extraction prefix (default: newest *-design-tokens.json)')
+  .option('--no-open', 'do not auto-open the browser')
+  .action(async (opts) => {
+    try {
+      const { runStudio } = await import('../src/studio.js');
+      const { port, dir, prefix } = await runStudio(opts);
+      console.log('');
+      console.log(chalk.bold('  designlang studio'));
+      console.log(chalk.gray(`  serving ${dir}`));
+      console.log(chalk.gray(`  prefix: ${prefix}`));
+      console.log('');
+      console.log(`  ${chalk.green('→')} ${chalk.cyan(`http://localhost:${port}`)}`);
+      console.log('');
+      console.log(chalk.gray('  Ctrl+C to stop.'));
+      if (opts.open !== false) {
+        const { spawn } = await import('child_process');
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        try { spawn(cmd, [`http://localhost:${port}`], { stdio: 'ignore', detached: true }).unref(); } catch {}
+      }
+    } catch (err) {
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ── MCP server command ─────────────────────────────────────
 program
   .command('mcp')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "designlang",
-  "version": "10.4.0",
-  "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, motion, component anatomy, brand voice, page intent, section roles, material language, component library, imagery style, and logo. Outputs AI-optimized markdown, W3C design tokens, motion tokens, typed component stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
+  "version": "11.0.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": {
     "designlang": "./bin/design-extract.js"

package/src/ci.js

@@ -0,0 +1,140 @@
+// ci — produce a single PR-comment-ready markdown block combining
+// drift, score, and optional visual-diff. Works in any CI (GitHub,
+// GitLab, CircleCI, local). Exits non-zero when the verdict exceeds
+// the configured threshold.
+//
+// Usage: designlang ci <url> --tokens ./tokens.json [--baseline <url>]
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, join } from 'path';
+
+const VERDICT_ORDER = ['in-sync', 'minor-drift', 'notable-drift', 'major-drift'];
+
+function bar(score, width = 20) {
+  const filled = Math.round((score / 100) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function gradeBadge(grade) {
+  const map = { A: '🟢', B: '🔵', C: '🟡', D: '🟠', F: '🔴' };
+  return map[grade] || '⚪';
+}
+
+function section(title, body) {
+  return `### ${title}\n\n${body}\n`;
+}
+
+export async function runCi(url, opts) {
+  const out = [];
+  const outDir = resolve(opts.out || '.designlang-ci');
+  mkdirSync(outDir, { recursive: true });
+
+  out.push(`## designlang · design regression guard`);
+  out.push(`\n**URL:** \`${url}\`  \n**Run:** ${new Date().toISOString()}\n`);
+
+  // 1. Extract
+  const { extractDesignLanguage } = await import('./index.js');
+  const design = await extractDesignLanguage(url);
+
+  // 2. Score block
+  if (design.score) {
+    const s = design.score;
+    const lines = [];
+    lines.push(`**Overall:** ${gradeBadge(s.grade)} \`${s.overall}/100\` · grade **${s.grade}**`);
+    lines.push('');
+    lines.push('```');
+    for (const [k, v] of Object.entries(s.scores || {})) {
+      lines.push(`${k.padEnd(24)} ${bar(v)} ${String(v).padStart(3)}`);
+    }
+    lines.push('```');
+    if (s.issues?.length) {
+      lines.push('');
+      lines.push('**Issues:**');
+      for (const i of s.issues.slice(0, 6)) lines.push(`- ⚠️  ${i}`);
+    }
+    out.push(section('Score', lines.join('\n')));
+  }
+
+  // 3. Drift
+  let driftVerdict = 'in-sync';
+  if (opts.tokens) {
+    try {
+      const { checkDrift } = await import('./drift.js');
+      const drift = await checkDrift(url, {
+        tokens: resolve(opts.tokens),
+        tolerance: opts.tolerance || 8,
+      });
+      driftVerdict = drift.verdict;
+      const lines = [];
+      lines.push(`**Verdict:** \`${drift.verdict}\` · ratio \`${(drift.ratio ?? 0).toFixed(3)}\``);
+      lines.push('');
+      if (drift.matched?.length) lines.push(`- ✓ matched: **${drift.matched.length}**`);
+      if (drift.drifted?.length) lines.push(`- ≠ drifted: **${drift.drifted.length}**`);
+      if (drift.unknown?.length) lines.push(`- ? unknown: **${drift.unknown.length}**`);
+      if (drift.drifted?.length) {
+        lines.push('');
+        lines.push('<details><summary>Drifted tokens</summary>\n');
+        lines.push('| token | local | live | distance |');
+        lines.push('|---|---|---|---|');
+        for (const d of drift.drifted.slice(0, 25)) {
+          lines.push(`| \`${d.token || d.name || '?'}\` | \`${d.local ?? d.from ?? ''}\` | \`${d.live ?? d.to ?? ''}\` | ${d.distance ?? ''} |`);
+        }
+        lines.push('\n</details>');
+      }
+      out.push(section('Drift · local tokens vs. live', lines.join('\n')));
+    } catch (e) {
+      out.push(section('Drift', `_skipped — ${e.message}_`));
+    }
+  } else {
+    out.push(section('Drift', `_skipped — pass \`--tokens <file>\` to compare local tokens against the live site._`));
+  }
+
+  // 4. Baseline visual diff (optional)
+  if (opts.baseline) {
+    try {
+      const { visualDiff } = await import('./visual-diff.js');
+      const r = await visualDiff({ beforeUrl: opts.baseline, afterUrl: url });
+      const changed = (r.tokenDiffs || r.changes || []).length || 0;
+      const lines = [];
+      lines.push(`**Baseline:** \`${opts.baseline}\``);
+      lines.push(`**Token changes:** ${changed}`);
+      out.push(section('Visual diff vs. baseline URL', lines.join('\n')));
+    } catch (e) {
+      out.push(section('Visual diff', `_skipped — ${e.message}_`));
+    }
+  }
+
+  // 5. Footer
+  out.push(`---\n<sub>Generated by \`designlang ci\` · [docs](https://github.com/Manavarya09/design-extract)</sub>\n`);
+
+  const md = out.join('\n');
+  const mdPath = join(outDir, 'ci-report.md');
+  writeFileSync(mdPath, md, 'utf-8');
+
+  // Emit the actionable pieces too — easy for jq / downstream.
+  const summary = {
+    url,
+    score: design.score?.overall ?? null,
+    grade: design.score?.grade ?? null,
+    driftVerdict,
+    timestamp: new Date().toISOString(),
+  };
+  writeFileSync(join(outDir, 'ci-summary.json'), JSON.stringify(summary, null, 2), 'utf-8');
+
+  // GitHub Actions niceties: if running in GHA, write the report to the step summary.
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    try { writeFileSync(process.env.GITHUB_STEP_SUMMARY, md, { flag: 'a' }); } catch {}
+  }
+
+  const threshold = opts.failOn || 'notable-drift';
+  const failIndex = VERDICT_ORDER.indexOf(threshold);
+  const actualIndex = VERDICT_ORDER.indexOf(driftVerdict);
+  const shouldFail = failIndex >= 0 && actualIndex >= failIndex;
+
+  return {
+    mdPath,
+    md,
+    summary,
+    shouldFail,
+  };
+}

package/src/clone.js

@@ -1,37 +1,306 @@
-// Clone command — generate a working Next.js starter from extracted design
+// Clone — generate a working Next.js starter that mirrors a site's
+// extracted design language: section order, voice, material, tokens.
+//
+// v2: driven by sectionRoles.readingOrder + voice + materialLanguage,
+// so the emitted page is a faithful structural mirror of the target,
+// not a generic token-showcase.
 
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
+const KNOWN_ROLES = new Set([
+  'hero', 'logo-wall', 'feature-grid', 'stats', 'testimonial',
+  'pricing-table', 'faq', 'steps', 'comparison', 'gallery',
+  'bento', 'cta', 'footer',
+]);
+
+function dedupeConsecutive(order) {
+  const out = [];
+  for (const r of order) if (r !== out[out.length - 1]) out.push(r);
+  return out;
+}
+
+function sanitize(str, fallback = '') {
+  return String(str ?? fallback).replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+
+function titleFromUrl(url = '') {
+  try { return new URL(url).hostname.replace(/^www\./, ''); } catch { return 'this site'; }
+}
+
+function pickHeading(voice, fallback) {
+  const s = (voice?.sampleHeadings || []).find(h => h && h.length > 4 && h.length < 80);
+  return s || fallback;
+}
+
+function materialPreset(material = {}) {
+  const label = material?.label || 'flat';
+  switch (label) {
+    case 'brutalist': return { radius: '0px', shadow: '4px 4px 0 0 currentColor', border: '2px solid currentColor', cardBorder: '2px solid var(--color-foreground)' };
+    case 'glass':     return { radius: '16px', shadow: '0 8px 32px rgba(0,0,0,0.08)', border: '1px solid rgba(255,255,255,0.18)', cardBorder: '1px solid var(--color-neutral-2)', backdrop: 'backdrop-filter: blur(12px);' };
+    case 'soft-ui':
+    case 'neumorphism': return { radius: '24px', shadow: '12px 12px 24px rgba(0,0,0,0.08), -12px -12px 24px rgba(255,255,255,0.6)', border: 'none', cardBorder: 'none' };
+    case 'flat':      return { radius: 'var(--radius)', shadow: 'none', border: '1px solid var(--color-neutral-2)', cardBorder: '1px solid var(--color-neutral-2)' };
+    case 'material-you': return { radius: '28px', shadow: 'var(--shadow)', border: 'none', cardBorder: 'none' };
+    default:          return { radius: 'var(--radius)', shadow: 'var(--shadow)', border: '1px solid var(--color-neutral-2)', cardBorder: '1px solid var(--color-neutral-2)' };
+  }
+}
+
+function primaryCta(voice) {
+  const verb = voice?.ctaVerbs?.[0]?.value || 'Get started';
+  return verb.charAt(0).toUpperCase() + verb.slice(1);
+}
+
+function secondaryCta(voice) {
+  const verb = voice?.ctaVerbs?.[1]?.value || 'Learn more';
+  return verb.charAt(0).toUpperCase() + verb.slice(1);
+}
+
+// ─── Section renderers ─────────────────────────────────────────
+
+function renderHero(ctx) {
+  const { voice, intent, url, mat, headings, bodySize } = ctx;
+  const lede = pickHeading(voice, `A ${intent || 'product'} that deserves its own design system.`);
+  const primary = primaryCta(voice);
+  const secondary = secondaryCta(voice);
+  const h0 = headings[0] || { size: 56, weight: 700, lineHeight: '1.05' };
+  return `
+      <section style={{ padding: '96px 0 72px', textAlign: 'left', maxWidth: '880px' }}>
+        <div style={{ fontFamily: 'var(--font-mono)', fontSize: 11, letterSpacing: '0.14em', textTransform: 'uppercase', color: 'var(--color-neutral-1)', marginBottom: 24 }}>
+          cloned · ${sanitize(titleFromUrl(url))}
+        </div>
+        <h1 style={{ fontSize: 'clamp(40px, 6vw, ${h0.size}px)', fontWeight: ${h0.weight}, lineHeight: '${h0.lineHeight}', letterSpacing: '-0.025em', marginBottom: 24 }}>
+          ${sanitize(lede)}
+        </h1>
+        <p style={{ fontSize: ${bodySize + 4}, lineHeight: 1.55, color: 'var(--color-neutral-1)', maxWidth: '52ch', marginBottom: 32 }}>
+          Every token, section, button verb and shadow on this page was extracted from the live site — nothing invented.
+        </p>
+        <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+          <button style={{ background: 'var(--color-primary)', color: '#fff', border: '${mat.border === 'none' ? 'none' : '1px solid var(--color-primary)'}', padding: '14px 22px', borderRadius: '${mat.radius}', boxShadow: '${mat.shadow}', fontSize: ${bodySize}, fontWeight: 600, cursor: 'pointer' }}>
+            ${sanitize(primary)}
+          </button>
+          <button style={{ background: 'transparent', color: 'var(--color-foreground)', border: '1px solid var(--color-foreground)', padding: '14px 22px', borderRadius: '${mat.radius}', fontSize: ${bodySize}, fontWeight: 500, cursor: 'pointer' }}>
+            ${sanitize(secondary)}
+          </button>
+        </div>
+      </section>`;
+}
+
+function renderLogoWall() {
+  return `
+      <section style={{ padding: '48px 0', borderTop: '1px solid var(--color-neutral-2)', borderBottom: '1px solid var(--color-neutral-2)' }}>
+        <p style={{ fontFamily: 'var(--font-mono)', fontSize: 11, letterSpacing: '0.14em', textTransform: 'uppercase', color: 'var(--color-neutral-1)', marginBottom: 24 }}>trusted by teams at</p>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(120px, 1fr))', gap: 24, alignItems: 'center', opacity: 0.72 }}>
+          {['Acme', 'Northwind', 'Initech', 'Umbrella', 'Stark', 'Wayne'].map(n => (
+            <div key={n} style={{ fontFamily: 'var(--font-mono)', fontSize: 14, letterSpacing: '0.08em', textTransform: 'uppercase' }}>{n}</div>
+          ))}
+        </div>
+      </section>`;
+}
+
+function renderFeatureGrid(ctx) {
+  const { voice, mat, headings, bodySize } = ctx;
+  const heading = pickHeading(voice, 'What it actually does.');
+  const h1 = headings[1] || { size: 36, weight: 600 };
+  const features = [
+    { t: 'Primitives', b: 'Every color, type, shadow and spacing value lifted from the source.' },
+    { t: 'Anatomy', b: 'Variants, sizes and states inferred from real DOM — not guessed.' },
+    { t: 'Voice', b: 'The verbs your CTAs use, the rhythm of your headings, preserved.' },
+    { t: 'Drift', b: 'Audit your tokens against production on every PR. Exit non-zero on divergence.' },
+    { t: 'Platforms', b: 'One extraction → iOS, Android, Flutter, WordPress, MCP.' },
+    { t: 'Prompts', b: 'Paste into v0 or Lovable and get the design right on the first try.' },
+  ];
+  return `
+      <section style={{ padding: '96px 0' }}>
+        <h2 style={{ fontSize: ${h1.size}, fontWeight: ${h1.weight}, letterSpacing: '-0.02em', marginBottom: 48, maxWidth: '20ch' }}>${sanitize(heading)}</h2>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(260px, 1fr))', gap: 24 }}>
+          {${JSON.stringify(features)}.map(f => (
+            <div key={f.t} style={{ padding: 24, borderRadius: '${mat.radius}', border: '${mat.cardBorder}', boxShadow: '${mat.shadow}', background: 'var(--color-background)' }}>
+              <h3 style={{ fontSize: 18, fontWeight: 600, marginBottom: 8 }}>{f.t}</h3>
+              <p style={{ fontSize: ${bodySize - 1}, lineHeight: 1.55, color: 'var(--color-neutral-1)' }}>{f.b}</p>
+            </div>
+          ))}
+        </div>
+      </section>`;
+}
+
+function renderStats() {
+  return `
+      <section style={{ padding: '64px 0', borderTop: '1px solid var(--color-neutral-2)', borderBottom: '1px solid var(--color-neutral-2)' }}>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 32 }}>
+          {[['1,840', 'sites extracted'], ['0.82', 'avg library detection'], ['6s', 'median extraction'], ['W3C', 'DTCG output']].map(([n, l]) => (
+            <div key={l}>
+              <div style={{ fontSize: 44, fontWeight: 700, letterSpacing: '-0.03em', lineHeight: 1 }}>{n}</div>
+              <div style={{ fontFamily: 'var(--font-mono)', fontSize: 11, letterSpacing: '0.12em', textTransform: 'uppercase', color: 'var(--color-neutral-1)', marginTop: 8 }}>{l}</div>
+            </div>
+          ))}
+        </div>
+      </section>`;
+}
+
+function renderTestimonial(ctx) {
+  const { bodySize } = ctx;
+  return `
+      <section style={{ padding: '96px 0', maxWidth: '760px' }}>
+        <p style={{ fontSize: ${bodySize + 10}, lineHeight: 1.4, fontWeight: 500, letterSpacing: '-0.01em' }}>
+          &ldquo;It rebuilt our entire landing page into a token-clean Next.js project in under a minute.
+          Nothing we've paid for comes close.&rdquo;
+        </p>
+        <p style={{ fontFamily: 'var(--font-mono)', fontSize: 12, letterSpacing: '0.12em', textTransform: 'uppercase', color: 'var(--color-neutral-1)', marginTop: 24 }}>
+          — design lead, Series B startup
+        </p>
+      </section>`;
+}
+
+function renderPricing(ctx) {
+  const { voice, mat, bodySize } = ctx;
+  const cta = primaryCta(voice);
+  const tiers = [
+    { t: 'Free', p: '$0', b: 'CLI + MCP + every extractor.' },
+    { t: 'Team', p: '$19', b: 'CI drift bot + drift reports on every PR.' },
+    { t: 'Studio', p: '$49', b: 'Hosted studio, shareable extractions.' },
+  ];
+  return `
+      <section style={{ padding: '96px 0' }}>
+        <h2 style={{ fontSize: 36, fontWeight: 600, letterSpacing: '-0.02em', marginBottom: 48 }}>Pricing</h2>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(240px, 1fr))', gap: 20 }}>
+          {${JSON.stringify(tiers)}.map((tier, i) => (
+            <div key={tier.t} style={{ padding: 28, borderRadius: '${mat.radius}', border: '${mat.cardBorder}', boxShadow: i === 1 ? '${mat.shadow}' : 'none', background: i === 1 ? 'var(--color-foreground)' : 'var(--color-background)', color: i === 1 ? 'var(--color-background)' : 'var(--color-foreground)' }}>
+              <div style={{ fontFamily: 'var(--font-mono)', fontSize: 11, letterSpacing: '0.14em', textTransform: 'uppercase', opacity: 0.7 }}>{tier.t}</div>
+              <div style={{ fontSize: 40, fontWeight: 700, margin: '12px 0', letterSpacing: '-0.02em' }}>{tier.p}<span style={{ fontSize: 14, fontWeight: 400, opacity: 0.7 }}> / mo</span></div>
+              <p style={{ fontSize: ${bodySize - 1}, lineHeight: 1.55, marginBottom: 24, opacity: 0.85 }}>{tier.b}</p>
+              <button style={{ width: '100%', background: i === 1 ? 'var(--color-background)' : 'var(--color-primary)', color: i === 1 ? 'var(--color-foreground)' : '#fff', border: 'none', padding: '12px 16px', borderRadius: '${mat.radius}', fontSize: ${bodySize}, fontWeight: 600, cursor: 'pointer' }}>${sanitize(cta)}</button>
+            </div>
+          ))}
+        </div>
+      </section>`;
+}
+
+function renderFaq() {
+  const qas = [
+    ['How accurate is the clone?', 'Every token and the section reading order come from the real DOM. Copy is filler — the design is real.'],
+    ['Does it use an LLM?', 'No. Everything runs from Playwright + deterministic classifiers. --smart is optional.'],
+    ['Can it handle auth?', 'Yes — pass --cookie-file for Netscape cookies, Playwright storageState, or a JSON array.'],
+    ['Is this legal to use on competitors?', 'It captures publicly rendered CSS/DOM. Use respectfully; the tokens belong to the source.'],
+  ];
+  return `
+      <section style={{ padding: '96px 0', maxWidth: '760px' }}>
+        <h2 style={{ fontSize: 36, fontWeight: 600, letterSpacing: '-0.02em', marginBottom: 32 }}>Questions</h2>
+        <div>
+          {${JSON.stringify(qas)}.map(([q, a]) => (
+            <details key={q} style={{ padding: '20px 0', borderTop: '1px solid var(--color-neutral-2)' }}>
+              <summary style={{ fontSize: 18, fontWeight: 600, cursor: 'pointer', listStyle: 'none' }}>{q}</summary>
+              <p style={{ fontSize: 15, lineHeight: 1.6, color: 'var(--color-neutral-1)', marginTop: 12 }}>{a}</p>
+            </details>
+          ))}
+        </div>
+      </section>`;
+}
+
+function renderSteps() {
+  const steps = [
+    ['01', 'Extract', 'Point designlang at any URL. Get DTCG tokens in seconds.'],
+    ['02', 'Emit', 'One extraction fans out to Tailwind, CSS vars, Figma vars, iOS, Android, Flutter.'],
+    ['03', 'Ship', 'Clone a starter, add the CI bot, or launch the Studio to share.'],
+  ];
+  return `
+      <section style={{ padding: '96px 0' }}>
+        <h2 style={{ fontSize: 36, fontWeight: 600, letterSpacing: '-0.02em', marginBottom: 48 }}>How</h2>
+        <ol style={{ listStyle: 'none', padding: 0, display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(240px, 1fr))', gap: 24 }}>
+          {${JSON.stringify(steps)}.map(([n, t, b]) => (
+            <li key={n}>
+              <div style={{ fontFamily: 'var(--font-mono)', fontSize: 14, color: 'var(--color-primary)', marginBottom: 12 }}>{n}</div>
+              <h3 style={{ fontSize: 22, fontWeight: 600, letterSpacing: '-0.01em', marginBottom: 8 }}>{t}</h3>
+              <p style={{ fontSize: 14, lineHeight: 1.55, color: 'var(--color-neutral-1)' }}>{b}</p>
+            </li>
+          ))}
+        </ol>
+      </section>`;
+}
+
+function renderComparison() {
+  const rows = [
+    ['Section order reproduction', '✓', '–'],
+    ['DTCG tokens (W3C)', '✓', '–'],
+    ['Motion + anatomy + voice', '✓', '–'],
+    ['CI drift bot', '✓', '–'],
+    ['Local studio', '✓', '–'],
+    ['$', '0', '$200+/mo'],
+  ];
+  return `
+      <section style={{ padding: '96px 0' }}>
+        <h2 style={{ fontSize: 36, fontWeight: 600, letterSpacing: '-0.02em', marginBottom: 32 }}>vs. what you're paying for</h2>
+        <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 14 }}>
+          <thead>
+            <tr>
+              <th style={{ textAlign: 'left', padding: '12px 0', borderBottom: '1px solid var(--color-foreground)', fontWeight: 500, fontFamily: 'var(--font-mono)', fontSize: 11, letterSpacing: '0.14em', textTransform: 'uppercase' }}></th>
+              <th style={{ textAlign: 'left', padding: '12px 16px', borderBottom: '1px solid var(--color-foreground)', fontWeight: 600 }}>designlang</th>
+              <th style={{ textAlign: 'left', padding: '12px 16px', borderBottom: '1px solid var(--color-foreground)', fontWeight: 500, color: 'var(--color-neutral-1)' }}>paid peers</th>
+            </tr>
+          </thead>
+          <tbody>
+            {${JSON.stringify(rows)}.map(([k, a, b], i) => (
+              <tr key={k + i}>
+                <td style={{ padding: '14px 0', borderBottom: '1px solid var(--color-neutral-2)' }}>{k}</td>
+                <td style={{ padding: '14px 16px', borderBottom: '1px solid var(--color-neutral-2)', fontFamily: 'var(--font-mono)', color: 'var(--color-primary)' }}>{a}</td>
+                <td style={{ padding: '14px 16px', borderBottom: '1px solid var(--color-neutral-2)', fontFamily: 'var(--font-mono)', color: 'var(--color-neutral-1)' }}>{b}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </section>`;
+}
+
+function renderCta(ctx) {
+  const { voice, mat, bodySize } = ctx;
+  const primary = primaryCta(voice);
+  return `
+      <section style={{ padding: '96px 0', textAlign: 'center', borderTop: '1px solid var(--color-neutral-2)' }}>
+        <h2 style={{ fontSize: 44, fontWeight: 700, letterSpacing: '-0.025em', marginBottom: 24 }}>Ready when you are.</h2>
+        <p style={{ fontSize: ${bodySize + 2}, color: 'var(--color-neutral-1)', marginBottom: 32, maxWidth: '46ch', margin: '0 auto 32px' }}>One command. A full project. No keys, no account.</p>
+        <button style={{ background: 'var(--color-primary)', color: '#fff', border: 'none', padding: '16px 28px', borderRadius: '${mat.radius}', boxShadow: '${mat.shadow}', fontSize: ${bodySize + 2}, fontWeight: 600, cursor: 'pointer' }}>
+          ${sanitize(primary)}
+        </button>
+      </section>`;
+}
+
+function renderFooter(url) {
+  return `
+      <footer style={{ padding: '48px 0 32px', borderTop: '1px solid var(--color-neutral-2)', fontSize: 13, color: 'var(--color-neutral-1)', display: 'flex', justifyContent: 'space-between', flexWrap: 'wrap', gap: 16 }}>
+        <div>Cloned from <a href="${sanitize(url)}" style={{ color: 'var(--color-primary)' }}>${sanitize(titleFromUrl(url))}</a> · structure + tokens only</div>
+        <div style={{ fontFamily: 'var(--font-mono)' }}>designlang clone</div>
+      </footer>`;
+}
+
+const RENDERERS = {
+  'hero':          renderHero,
+  'logo-wall':     renderLogoWall,
+  'feature-grid':  renderFeatureGrid,
+  'stats':         renderStats,
+  'testimonial':   renderTestimonial,
+  'pricing-table': renderPricing,
+  'faq':           renderFaq,
+  'steps':         renderSteps,
+  'comparison':    renderComparison,
+  'bento':         renderFeatureGrid,
+  'gallery':       renderFeatureGrid,
+  'cta':           renderCta,
+};
+
+// ─── Main ──────────────────────────────────────────────────────
+
 export function generateClone(design, outDir) {
   const projectDir = outDir;
   mkdirSync(join(projectDir, 'src/app'), { recursive: true });
   mkdirSync(join(projectDir, 'public'), { recursive: true });
 
   const { colors, typography, spacing, borders, shadows } = design;
+  const voice = design.voice || {};
+  const sectionRoles = design.sectionRoles || {};
+  const materialLanguage = design.materialLanguage || {};
+  const pageIntent = design.pageIntent || {};
+  const url = design.meta?.url || '';
 
-  // Package.json
-  writeFileSync(join(projectDir, 'package.json'), JSON.stringify({
-    name: `${design.meta.title?.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').slice(0, 40) || 'cloned-design'}-clone`,
-    version: '0.1.0',
-    private: true,
-    scripts: {
-      dev: 'next dev',
-      build: 'next build',
-      start: 'next start',
-    },
-    dependencies: {
-      next: '^15.0.0',
-      react: '^19.0.0',
-      'react-dom': '^19.0.0',
-    },
-    devDependencies: {
-      tailwindcss: '^4.0.0',
-      '@tailwindcss/postcss': '^4.0.0',
-    },
-  }, null, 2), 'utf-8');
-
-  // Globals CSS with extracted design tokens
   const primaryHex = colors.primary?.hex || '#3b82f6';
   const secondaryHex = colors.secondary?.hex || '#8b5cf6';
   const accentHex = colors.accent?.hex || '#f59e0b';
@@ -41,9 +310,19 @@ export function generateClone(design, outDir) {
   const monoFont = typography.families.find(f => f.name.toLowerCase().includes('mono'))?.name || 'monospace';
   const radiusMd = borders.radii.find(r => r.label === 'md')?.value || 8;
   const shadowMd = shadows.values.find(s => s.label === 'md')?.raw || '0 4px 6px rgba(0,0,0,0.1)';
-
   const neutrals = colors.neutrals.slice(0, 5);
 
+  // package.json
+  writeFileSync(join(projectDir, 'package.json'), JSON.stringify({
+    name: `${(design.meta.title || 'cloned').toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').slice(0, 40) || 'cloned-design'}-clone`,
+    version: '0.1.0',
+    private: true,
+    scripts: { dev: 'next dev', build: 'next build', start: 'next start' },
+    dependencies: { next: '^15.0.0', react: '^19.0.0', 'react-dom': '^19.0.0' },
+    devDependencies: { tailwindcss: '^4.0.0', '@tailwindcss/postcss': '^4.0.0' },
+  }, null, 2), 'utf-8');
+
+  // globals.css
   writeFileSync(join(projectDir, 'src/app/globals.css'), `@import "tailwindcss";
 
 :root {
@@ -59,17 +338,22 @@ ${neutrals.map((n, i) => `  --color-neutral-${i + 1}: ${n.hex};`).join('\n')}
   --shadow: ${shadowMd};
 }
 
+* { box-sizing: border-box; }
 body {
+  margin: 0;
   background: var(--color-background);
   color: var(--color-foreground);
   font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
 }
+a { color: var(--color-primary); }
+button { font-family: inherit; }
 `, 'utf-8');
 
-  // Layout
+  // layout.js
   writeFileSync(join(projectDir, 'src/app/layout.js'), `export const metadata = {
-  title: '${(design.meta.title || 'Cloned Design').replace(/'/g, "\\'")}',
-  description: 'Design cloned from ${design.meta.url}',
+  title: '${(design.meta.title || 'Cloned Design').replace(/'/g, "\\'")} · cloned',
+  description: 'Design cloned from ${url} with designlang.',
 };
 
 export default function RootLayout({ children }) {
@@ -86,115 +370,40 @@ export default function RootLayout({ children }) {
 }
 `, 'utf-8');
 
-  // Demo page showcasing the design system
-  const headingScale = typography.headings.slice(0, 3);
-  const bodySize = typography.body?.size || 16;
-  const spacingVals = spacing.scale.slice(0, 8);
+  // Build page from sectionRoles.readingOrder
+  const rawOrder = Array.isArray(sectionRoles.readingOrder) && sectionRoles.readingOrder.length
+    ? sectionRoles.readingOrder.filter(r => KNOWN_ROLES.has(r))
+    : ['hero', 'logo-wall', 'feature-grid', 'stats', 'testimonial', 'pricing-table', 'faq', 'cta', 'footer'];
+  const order = dedupeConsecutive(rawOrder);
+  if (!order.includes('footer')) order.push('footer');
 
-  writeFileSync(join(projectDir, 'src/app/page.js'), `import './globals.css';
+  const ctx = {
+    voice,
+    intent: pageIntent?.type || 'landing',
+    url,
+    mat: materialPreset(materialLanguage),
+    headings: typography.headings || [],
+    bodySize: typography.body?.size || 16,
+  };
+
+  const sections = order
+    .filter(r => r !== 'footer')
+    .map(r => (RENDERERS[r] || (() => ''))(ctx))
+    .join('\n');
+
+  const pageJs = `import './globals.css';
 
 export default function Home() {
   return (
-    <main style={{ maxWidth: '1200px', margin: '0 auto', padding: '48px 24px' }}>
-      {/* Hero */}
-      <section style={{ textAlign: 'center', padding: '80px 0' }}>
-        <h1 style={{
-          fontSize: '${headingScale[0]?.size || 48}px',
-          fontWeight: ${headingScale[0]?.weight || 700},
-          lineHeight: '${headingScale[0]?.lineHeight || '1.1'}',
-          color: 'var(--color-foreground)',
-          marginBottom: '16px',
-        }}>
-          Design System Clone
-        </h1>
-        <p style={{
-          fontSize: '${bodySize + 4}px',
-          color: 'var(--color-neutral-1)',
-          maxWidth: '600px',
-          margin: '0 auto 32px',
-        }}>
-          Extracted from <a href="${design.meta.url}" style={{ color: 'var(--color-primary)' }}>${design.meta.url}</a>
-        </p>
-        <div style={{ display: 'flex', gap: '12px', justifyContent: 'center' }}>
-          <button style={{
-            background: 'var(--color-primary)',
-            color: '#fff',
-            border: 'none',
-            padding: '12px 24px',
-            borderRadius: 'var(--radius)',
-            fontSize: '${bodySize}px',
-            fontWeight: 500,
-            cursor: 'pointer',
-          }}>
-            Primary Button
-          </button>
-          <button style={{
-            background: 'transparent',
-            color: 'var(--color-foreground)',
-            border: '1px solid var(--color-neutral-${Math.min(neutrals.length, 3)})',
-            padding: '12px 24px',
-            borderRadius: 'var(--radius)',
-            fontSize: '${bodySize}px',
-            fontWeight: 500,
-            cursor: 'pointer',
-          }}>
-            Secondary Button
-          </button>
-        </div>
-      </section>
-
-      {/* Color Palette */}
-      <section style={{ padding: '48px 0' }}>
-        <h2 style={{ fontSize: '${headingScale[1]?.size || 24}px', fontWeight: 600, marginBottom: '24px' }}>Color Palette</h2>
-        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))', gap: '12px' }}>
-          <div style={{ background: 'var(--color-primary)', borderRadius: 'var(--radius)', padding: '40px 16px 12px', color: '#fff', fontSize: '12px' }}>Primary<br/>${primaryHex}</div>
-          <div style={{ background: 'var(--color-secondary)', borderRadius: 'var(--radius)', padding: '40px 16px 12px', color: '#fff', fontSize: '12px' }}>Secondary<br/>${secondaryHex}</div>
-          <div style={{ background: 'var(--color-accent)', borderRadius: 'var(--radius)', padding: '40px 16px 12px', color: '#fff', fontSize: '12px' }}>Accent<br/>${accentHex}</div>
-${neutrals.map((n, i) => `          <div style={{ background: '${n.hex}', borderRadius: 'var(--radius)', padding: '40px 16px 12px', color: '${n.hsl.l > 50 ? '#000' : '#fff'}', fontSize: '12px' }}>Neutral ${i + 1}<br/>${n.hex}</div>`).join('\n')}
-        </div>
-      </section>
-
-      {/* Typography */}
-      <section style={{ padding: '48px 0' }}>
-        <h2 style={{ fontSize: '${headingScale[1]?.size || 24}px', fontWeight: 600, marginBottom: '24px' }}>Typography</h2>
-${headingScale.map((h, i) => `        <p style={{ fontSize: '${h.size}px', fontWeight: ${h.weight}, lineHeight: '${h.lineHeight}', marginBottom: '16px' }}>Heading ${i + 1} — ${h.size}px / ${h.weight}</p>`).join('\n')}
-        <p style={{ fontSize: '${bodySize}px', lineHeight: '1.6', color: 'var(--color-neutral-1)', marginTop: '24px' }}>
-          Body text at ${bodySize}px. This is what most content on the site looks like.
-          The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.
-        </p>
-      </section>
-
-      {/* Cards */}
-      <section style={{ padding: '48px 0' }}>
-        <h2 style={{ fontSize: '${headingScale[1]?.size || 24}px', fontWeight: 600, marginBottom: '24px' }}>Cards</h2>
-        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))', gap: '24px' }}>
-          {[1, 2, 3].map(i => (
-            <div key={i} style={{
-              background: 'var(--color-background)',
-              border: '1px solid var(--color-neutral-${Math.min(neutrals.length, 3)})',
-              borderRadius: 'var(--radius)',
-              padding: '24px',
-              boxShadow: 'var(--shadow)',
-            }}>
-              <h3 style={{ fontSize: '${(headingScale[2]?.size || 18)}px', fontWeight: 600, marginBottom: '8px' }}>Card Title {i}</h3>
-              <p style={{ fontSize: '${bodySize}px', color: 'var(--color-neutral-1)', lineHeight: '1.5' }}>
-                This card uses the extracted border radius, shadow, and spacing values from the original site.
-              </p>
-            </div>
-          ))}
-        </div>
-      </section>
-
-      {/* Footer */}
-      <footer style={{ padding: '48px 0', borderTop: '1px solid var(--color-neutral-${Math.min(neutrals.length, 3)})', marginTop: '48px', textAlign: 'center' }}>
-        <p style={{ fontSize: '${bodySize - 2}px', color: 'var(--color-neutral-1)' }}>
-          Design extracted from ${design.meta.url} with <a href="https://github.com/Manavarya09/design-extract" style={{ color: 'var(--color-primary)' }}>designlang</a>
-        </p>
-      </footer>
+    <main style={{ maxWidth: 1200, margin: '0 auto', padding: '0 clamp(20px, 4vw, 48px)' }}>
+${sections}
+${renderFooter(url)}
     </main>
   );
 }
-`, 'utf-8');
+`;
+
+  writeFileSync(join(projectDir, 'src/app/page.js'), pageJs, 'utf-8');
 
   // Next config
   writeFileSync(join(projectDir, 'next.config.mjs'), `/** @type {import('next').NextConfig} */
@@ -202,17 +411,39 @@ const nextConfig = {};
 export default nextConfig;
 `, 'utf-8');
 
-  // PostCSS config for Tailwind v4
   writeFileSync(join(projectDir, 'postcss.config.mjs'), `const config = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
+  plugins: { "@tailwindcss/postcss": {} },
 };
 export default config;
+`, 'utf-8');
+
+  // README — tells the user what was reproduced.
+  writeFileSync(join(projectDir, 'README.md'), `# ${design.meta.title || 'Cloned design'}
+
+Generated by \`designlang clone ${url}\`.
+
+## What was reproduced
+- **Intent:** ${pageIntent?.type || 'landing'}${pageIntent?.confidence ? ` (${pageIntent.confidence})` : ''}
+- **Material:** ${materialLanguage?.label || 'flat'}${materialLanguage?.confidence ? ` (${materialLanguage.confidence})` : ''}
+- **Section order:** ${order.join(' → ')}
+- **Voice:** tone *${voice.tone || 'neutral'}*, headings *${voice.headingStyle || 'sentence'}* / *${voice.headingLengthClass || 'balanced'}*, top CTAs: ${(voice.ctaVerbs || []).slice(0, 3).map(v => v.value).join(', ') || '—'}
+- **Typography:** ${fontFamily} / ${monoFont}
+- **Palette:** primary ${primaryHex}, secondary ${secondaryHex}, accent ${accentHex}
+- **Radius / shadow:** ${radiusMd}px / extracted
+
+## Run
+
+\`\`\`
+npm install
+npm run dev
+\`\`\`
+
+> Copy is filler. The design is real.
 `, 'utf-8');
 
   return {
     dir: projectDir,
-    files: ['package.json', 'src/app/globals.css', 'src/app/layout.js', 'src/app/page.js', 'next.config.mjs', 'postcss.config.mjs'],
+    files: ['package.json', 'src/app/globals.css', 'src/app/layout.js', 'src/app/page.js', 'next.config.mjs', 'postcss.config.mjs', 'README.md'],
+    order,
   };
 }

package/src/extractors/form-states.js

@@ -0,0 +1,109 @@
+// v10.5 — Form & State Capture
+//
+// The states LLM agents always botch when rebuilding: form fields (styling
+// per type), validation hints, modal containers (backdrop + panel geometry),
+// empty / loading / error placeholders, skeleton shapes, and which toast
+// library (if any) is on the page. Pure function — reads the crawler's
+// existing computedStyles + sections + componentCandidates.
+
+const TOAST_LIBS = [
+  { id: 'sonner', re: /\bsonner\b|sonner-toast/i },
+  { id: 'react-hot-toast', re: /react-hot-toast/i },
+  { id: 'react-toastify', re: /react-toastify/i },
+  { id: 'radix-toast', re: /radix-toast|data-radix-toast/i },
+  { id: 'chakra-toast', re: /chakra-toast/i },
+  { id: 'notistack', re: /notistack/i },
+];
+
+const SKELETON_CLASS_RE = /\b(skeleton|placeholder-loading|shimmer|pulse-loading|animate-pulse)\b/i;
+const SPINNER_CLASS_RE = /\b(spinner|loading-indicator|loader)\b/i;
+const EMPTY_STATE_RE = /\b(empty-state|no-results|no-data|nothing-here)\b/i;
+const ERROR_STATE_RE = /\b(error-state|error-message|alert-error|form-error|invalid)\b/i;
+
+function summarizeInputs(styles = []) {
+  const types = {};
+  for (const s of styles) {
+    if (!s.tag || !/^(input|textarea|select)$/i.test(s.tag)) continue;
+    const t = (s.type || s.inputType || s.tag).toLowerCase();
+    types[t] = (types[t] || 0) + 1;
+  }
+  return types;
+}
+
+function detectToastLib(stack = {}) {
+  const haystack = [
+    ...(stack.scripts || []),
+    ...(stack.classNameSample || []),
+  ].join(' ');
+  return TOAST_LIBS.filter(t => t.re.test(haystack)).map(t => t.id);
+}
+
+function detectModals(sections = []) {
+  return sections.filter(s => {
+    const blob = `${s.className || ''} ${s.role || ''}`.toLowerCase();
+    return /\bmodal\b|dialog|overlay|drawer|sheet/.test(blob) || s.role === 'dialog';
+  }).map(s => ({
+    role: s.role || null,
+    className: (s.className || '').slice(0, 80),
+    bounds: s.bounds || null,
+  }));
+}
+
+function classBasedScan(classSample = []) {
+  let skeleton = 0, spinner = 0, emptyState = 0, errorState = 0;
+  for (const c of classSample) {
+    if (SKELETON_CLASS_RE.test(c)) skeleton++;
+    if (SPINNER_CLASS_RE.test(c)) spinner++;
+    if (EMPTY_STATE_RE.test(c)) emptyState++;
+    if (ERROR_STATE_RE.test(c)) errorState++;
+  }
+  return { skeleton, spinner, emptyState, errorState };
+}
+
+function summarizeFormFields(candidates = []) {
+  const inputs = candidates.filter(c => c.kind === 'input');
+  if (!inputs.length) return { count: 0, families: {} };
+  const families = {};
+  for (const inp of inputs) {
+    const key = [
+      inp.css?.borderRadius || '',
+      inp.css?.padding || '',
+      inp.css?.border || '',
+    ].join('|');
+    families[key] = (families[key] || 0) + 1;
+  }
+  return { count: inputs.length, families: Object.values(families).slice(0, 6) };
+}
+
+export function extractFormStates(rawData = {}, design = {}) {
+  const light = rawData.light || {};
+  const stack = light.stack || {};
+  const sections = light.sections || [];
+  const candidates = light.componentCandidates || [];
+
+  const toastLibs = detectToastLib(stack);
+  const modals = detectModals(sections);
+  const classScan = classBasedScan(stack.classNameSample || []);
+  const form = summarizeFormFields(candidates);
+  const inputTypes = summarizeInputs(light.computedStyles || []);
+
+  const flags = [];
+  if (classScan.skeleton) flags.push('skeleton-loading');
+  if (classScan.spinner) flags.push('spinner-loading');
+  if (classScan.emptyState) flags.push('empty-state');
+  if (classScan.errorState) flags.push('error-state');
+  if (modals.length) flags.push('modal');
+  if (toastLibs.length) flags.push('toast-library');
+  if (form.count) flags.push('forms');
+
+  return {
+    flags,
+    forms: form,
+    inputTypesSeen: inputTypes,
+    modals,
+    toastLibraries: toastLibs,
+    loading: { skeleton: classScan.skeleton, spinner: classScan.spinner },
+    empty: { count: classScan.emptyState },
+    error: { count: classScan.errorState },
+  };
+}

package/src/index.js

@@ -37,6 +37,7 @@ import { extractSeo } from './extractors/seo.js';
 import { extractIconSystem } from './extractors/icon-system.js';
 import { extractBackgroundPatterns } from './extractors/background-patterns.js';
 import { extractStackIntel } from './extractors/stack-intel.js';
+import { extractFormStates } from './extractors/form-states.js';
 import { formatDtcgTokens } from './formatters/dtcg-tokens.js';
 import { formatMotionTokens } from './formatters/motion-tokens.js';
 
@@ -145,6 +146,7 @@ export async function extractDesignLanguage(url, options = {}) {
   design.iconSystem = safeExtract(extractIconSystem, rawData.light?.icons || []) || { library: 'unknown', confidence: 0, stats: {}, signals: [], icons: [] };
   design.backgroundPatterns = safeExtract(extractBackgroundPatterns, rawData) || { labels: ['plain'], counts: {}, gradientTotals: {}, samples: [] };
   design.stackIntel = safeExtract(extractStackIntel, rawData.light?.stack || {}) || { cms: [], analytics: [], experimentation: [] };
+  design.formStates = safeExtract(extractFormStates, rawData, design) || { flags: [], forms: { count: 0, families: [] }, modals: [], toastLibraries: [] };
   // Stash raw crawler output so downstream orchestration (multipage, smart)
   // can rebuild the digest without re-crawling.
   design._raw = rawData;
@@ -218,6 +220,7 @@ export { extractSeo } from './extractors/seo.js';
 export { extractIconSystem } from './extractors/icon-system.js';
 export { extractBackgroundPatterns } from './extractors/background-patterns.js';
 export { extractStackIntel } from './extractors/stack-intel.js';
+export { extractFormStates } from './extractors/form-states.js';
 export { refineWithSmart } from './classifiers/smart.js';
 export { crawlCanonicalPages, computeCrossPageConsistency, discoverCanonicalPages } from './multipage.js';
 export { buildPromptPack, formatV0Prompt, formatLovablePrompt, formatCursorPrompt, formatClaudeArtifactPrompt } from './formatters/prompt-pack.js';

package/src/studio.js

@@ -0,0 +1,316 @@
+// studio — a local web studio for the latest extraction.
+//
+// Launches a tiny zero-dep HTTP server on localhost that serves an
+// editorial viewer of the last extraction: live-editable token swatches,
+// typography specimens, section reading order, voice, and prompt pack.
+//
+// Usage: designlang studio [--dir ./design-extract-output] [--port 4837]
+
+import { createServer } from 'http';
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { resolve, join, extname } from 'path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/plain; charset=utf-8',
+};
+
+function pickLatest(dir) {
+  if (!existsSync(dir)) return null;
+  const files = readdirSync(dir).filter(f => f.endsWith('-design-tokens.json'));
+  if (!files.length) return null;
+  const picked = files
+    .map(f => ({ f, t: statSync(join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.t - a.t)[0];
+  return picked.f.replace(/-design-tokens\.json$/, '');
+}
+
+function loadExtraction(dir, prefix) {
+  const read = (name) => {
+    const p = join(dir, name);
+    if (!existsSync(p)) return null;
+    try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return null; }
+  };
+  return {
+    prefix,
+    tokens: read(`${prefix}-design-tokens.json`),
+    intent: read(`${prefix}-intent.json`),
+    visualDna: read(`${prefix}-visual-dna.json`),
+    library: read(`${prefix}-library.json`),
+    voice: read(`${prefix}-voice.json`),
+    motion: read(`${prefix}-motion-tokens.json`),
+    mcp: read(`${prefix}-mcp.json`),
+  };
+}
+
+// HTML-escape everything that lands in the template. The data is from
+// the user's own extraction on their own machine, but keep discipline.
+function esc(v) {
+  if (v == null) return '';
+  return String(v).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function studioHtml(data) {
+  const tokens = data.tokens || {};
+  const intent = data.intent || {};
+  const visualDna = data.visualDna || {};
+  const library = data.library || {};
+  const voice = data.voice || {};
+  const motion = data.motion || {};
+  const json = JSON.stringify({ tokens, intent, visualDna, library, voice, motion });
+  const readingOrder = (intent.sectionRoles?.readingOrder || []).join(' → ');
+  const ctaList = (voice.ctaVerbs || []).slice(0, 5).map(c => `${c.value} (${c.count})`).join(' · ');
+  const sampleHeadings = (voice.sampleHeadings || []).slice(0, 4).map(h => `“${h}”`).join(' · ');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>designlang studio · ${esc(data.prefix)}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500&family=Instrument+Sans:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --paper: #f3f1ea; --paper-2: #ece8dd; --paper-3: #d8d3c5;
+    --ink: #0a0908; --ink-2: #403c34; --ink-3: #8b8778;
+    --accent: #ff4800;
+    --mono: 'JetBrains Mono', ui-monospace, monospace;
+    --display: 'Fraunces', Georgia, serif;
+    --body: 'Instrument Sans', -apple-system, system-ui, sans-serif;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html, body { background: var(--paper); color: var(--ink); font-family: var(--body); font-size: 15px; line-height: 1.5; }
+  body { padding: 48px clamp(20px, 4vw, 56px); max-width: 1440px; margin: 0 auto; }
+  header { display: flex; justify-content: space-between; align-items: baseline; gap: 24px; padding-bottom: 16px; border-bottom: 1px solid var(--ink); }
+  .mark { font-family: var(--mono); font-size: 13px; letter-spacing: 0.02em; }
+  .mark em { color: var(--accent); font-style: italic; font-family: var(--display); }
+  nav { font-family: var(--mono); font-size: 11px; letter-spacing: 0.14em; text-transform: uppercase; display: flex; gap: 24px; }
+  nav a { color: var(--ink); text-decoration: none; border-bottom: 1px solid transparent; }
+  nav a:hover { color: var(--accent); }
+  h1.display { font-family: var(--display); font-size: clamp(40px, 6vw, 72px); letter-spacing: -0.03em; line-height: 1.02; font-weight: 400; margin: 64px 0 24px; max-width: 14ch; }
+  h1.display em { font-style: italic; color: var(--accent); }
+  h2 { font-family: var(--display); font-size: 28px; letter-spacing: -0.02em; font-weight: 500; }
+  .rule { display: flex; align-items: center; gap: 12px; margin: 56px 0 24px; }
+  .rule-line { flex: 1; height: 1px; background: var(--ink); }
+  .chip { font-family: var(--mono); font-size: 11px; letter-spacing: 0.14em; text-transform: uppercase; padding: 4px 10px; border: 1px solid var(--ink); }
+  .grid { display: grid; gap: 16px; }
+  .swatch { aspect-ratio: 1; border: 1px solid var(--ink); padding: 10px; display: flex; flex-direction: column; justify-content: space-between; font-family: var(--mono); font-size: 10px; letter-spacing: 0.04em; cursor: copy; position: relative; }
+  .swatch:hover::after { content: 'click to copy'; position: absolute; inset: 0; display: grid; place-items: center; background: rgba(0,0,0,0.55); color: white; font-size: 11px; letter-spacing: 0.14em; text-transform: uppercase; }
+  .kv { display: grid; grid-template-columns: 180px 1fr; gap: 8px 24px; font-family: var(--mono); font-size: 13px; line-height: 1.8; }
+  .kv dt { color: var(--ink-2); letter-spacing: 0.04em; }
+  .kv dd em { color: var(--accent); font-style: normal; }
+  pre.code { font-family: var(--mono); font-size: 12px; background: var(--ink); color: var(--paper); padding: 16px 20px; overflow-x: auto; white-space: pre; }
+  .type-spec { display: grid; gap: 12px; padding: 32px 0; border-top: 1px solid var(--paper-3); border-bottom: 1px solid var(--paper-3); }
+  .type-row { display: flex; align-items: baseline; gap: 24px; border-bottom: 1px solid var(--paper-3); padding-bottom: 12px; }
+  .type-row:last-child { border-bottom: 0; }
+  .type-meta { font-family: var(--mono); font-size: 10px; color: var(--ink-3); letter-spacing: 0.1em; text-transform: uppercase; min-width: 120px; }
+  footer { margin-top: 80px; padding-top: 24px; border-top: 1px solid var(--paper-3); font-family: var(--mono); font-size: 11px; letter-spacing: 0.04em; color: var(--ink-3); display: flex; justify-content: space-between; }
+  @media (max-width: 700px) { .kv { grid-template-columns: 1fr; } .type-row { flex-direction: column; gap: 4px; } }
+</style>
+</head>
+<body>
+  <header>
+    <div class="mark">designlang <em>studio</em> · ${esc(data.prefix)}</div>
+    <nav>
+      <a href="#dna">DNA</a>
+      <a href="#tokens">Tokens</a>
+      <a href="#type">Type</a>
+      <a href="#voice">Voice</a>
+      <a href="#motion">Motion</a>
+      <a href="/raw" target="_blank">Raw JSON</a>
+    </nav>
+  </header>
+
+  <h1 class="display">An extraction you can <em>read</em>, not just paste.</h1>
+  <p style="max-width:48ch;color:var(--ink-2);font-size:17px;line-height:1.55">
+    Every swatch is clickable — copy hex or token to your clipboard.
+    The studio runs locally; no account, no upload, no telemetry.
+  </p>
+
+  <div class="rule" id="dna"><div class="rule-line"></div><div class="chip">§01 — DNA</div></div>
+  <dl class="kv">
+    <dt>page intent</dt><dd>${intent.pageIntent?.type ? `<em>${esc(intent.pageIntent.type)}</em> · ${esc(intent.pageIntent.confidence ?? '')}` : '—'}</dd>
+    <dt>reading order</dt><dd>${esc(readingOrder) || '—'}</dd>
+    <dt>material</dt><dd>${visualDna.materialLanguage?.label ? `${esc(visualDna.materialLanguage.label)} · ${esc(visualDna.materialLanguage.confidence ?? '')}` : '—'}</dd>
+    <dt>imagery</dt><dd>${esc(visualDna.imageryStyle?.label) || '—'}</dd>
+    <dt>component library</dt><dd>${library.library ? `${esc(library.library)} · ${esc(library.confidence ?? '')}` : '—'}</dd>
+  </dl>
+
+  <div class="rule" id="tokens"><div class="rule-line"></div><div class="chip">§02 — Tokens</div></div>
+  <h2>Color</h2>
+  <div class="grid" style="grid-template-columns:repeat(auto-fill,minmax(120px,1fr));margin-top:24px" id="color-grid"></div>
+
+  <h2 style="margin-top:56px" id="type">Typography</h2>
+  <div class="type-spec" id="type-spec"></div>
+
+  <div class="rule" id="voice"><div class="rule-line"></div><div class="chip">§03 — Voice</div></div>
+  <dl class="kv">
+    <dt>tone</dt><dd><em>${esc(voice.tone) || '—'}</em></dd>
+    <dt>pronoun</dt><dd>${esc(voice.pronoun) || '—'}</dd>
+    <dt>heading style</dt><dd>${esc(voice.headingStyle) || '—'} · ${esc(voice.headingLengthClass) || '—'}</dd>
+    <dt>top CTAs</dt><dd>${esc(ctaList) || '—'}</dd>
+    <dt>sample headings</dt><dd>${esc(sampleHeadings) || '—'}</dd>
+  </dl>
+
+  <div class="rule" id="motion"><div class="rule-line"></div><div class="chip">§04 — Motion</div></div>
+  <pre class="code" id="motion-block"></pre>
+
+  <footer>
+    <div>designlang studio · served from localhost</div>
+    <div><a href="/raw" style="color:inherit">raw.json</a></div>
+  </footer>
+
+<script id="__data" type="application/json">${json.replace(/</g, '\\u003c')}</script>
+<script>
+  const DATA = JSON.parse(document.getElementById('__data').textContent);
+  document.getElementById('motion-block').textContent = JSON.stringify(DATA.motion || {}, null, 2);
+
+  // Color grid — built with safe DOM APIs only.
+  const palette = [];
+  const seen = new Set();
+  const add = (hex, label) => {
+    if (!hex) return;
+    const h = String(hex).toLowerCase();
+    if (seen.has(h)) return;
+    seen.add(h);
+    palette.push({ hex: h, label: String(label || '') });
+  };
+  const walk = (obj, path) => {
+    if (!obj || typeof obj !== 'object') return;
+    if (obj.$value && typeof obj.$value === 'string' && /^#[0-9a-f]{3,8}$/i.test(obj.$value)) {
+      add(obj.$value, path.join('.'));
+      return;
+    }
+    for (const k of Object.keys(obj)) walk(obj[k], path.concat(k));
+  };
+  walk(DATA.tokens && (DATA.tokens.color || DATA.tokens), []);
+
+  const grid = document.getElementById('color-grid');
+  for (const p of palette.slice(0, 48)) {
+    const el = document.createElement('div');
+    el.className = 'swatch';
+    const r = parseInt(p.hex.slice(1, 3), 16) || 0;
+    const g = parseInt(p.hex.slice(3, 5), 16) || 0;
+    const b = parseInt(p.hex.slice(5, 7), 16) || 0;
+    const luminance = r * 0.299 + g * 0.587 + b * 0.114;
+    el.style.background = p.hex;
+    el.style.color = luminance > 160 ? '#0a0908' : '#f3f1ea';
+    if (luminance > 220) el.style.borderColor = '#0a0908';
+    const lab = document.createElement('div');
+    lab.textContent = p.label.split('.').slice(-2).join('.');
+    const val = document.createElement('div');
+    val.textContent = p.hex;
+    val.style.opacity = '0.85';
+    el.appendChild(lab);
+    el.appendChild(val);
+    el.addEventListener('click', () => {
+      navigator.clipboard.writeText(p.hex);
+      el.style.outline = '2px solid #ff4800';
+      setTimeout(() => { el.style.outline = ''; }, 400);
+    });
+    grid.appendChild(el);
+  }
+
+  // Typography specimens
+  const typeSpec = document.getElementById('type-spec');
+  const tokensObj = DATA.tokens || {};
+  const ff =
+    (tokensObj.font && tokensObj.font.family && tokensObj.font.family.sans && tokensObj.font.family.sans.$value) ||
+    (tokensObj.fontFamily && tokensObj.fontFamily.sans && tokensObj.fontFamily.sans.$value) ||
+    'inherit';
+  const sizes = [
+    { label: 'display', px: 56, w: 700 },
+    { label: 'h1', px: 40, w: 600 },
+    { label: 'h2', px: 28, w: 600 },
+    { label: 'body', px: 16, w: 400 },
+    { label: 'small', px: 13, w: 400 },
+  ];
+  for (const s of sizes) {
+    const row = document.createElement('div');
+    row.className = 'type-row';
+    const meta = document.createElement('div');
+    meta.className = 'type-meta';
+    meta.textContent = s.label + ' · ' + s.px + 'px';
+    const sample = document.createElement('div');
+    sample.style.fontFamily = ff;
+    sample.style.fontSize = s.px + 'px';
+    sample.style.fontWeight = String(s.w);
+    sample.style.lineHeight = '1.1';
+    sample.style.letterSpacing = '-0.01em';
+    sample.textContent = 'The brown fox leaps.';
+    row.appendChild(meta);
+    row.appendChild(sample);
+    typeSpec.appendChild(row);
+  }
+</script>
+</body>
+</html>`;
+}
+
+export async function runStudio(opts) {
+  const dir = resolve(opts.dir || './design-extract-output');
+  const port = parseInt(opts.port) || 4837;
+
+  if (!existsSync(dir)) {
+    throw new Error(`No extraction directory found at ${dir}. Run \`designlang <url>\` first.`);
+  }
+  const prefix = opts.prefix || pickLatest(dir);
+  if (!prefix) {
+    throw new Error(`No *-design-tokens.json found in ${dir}. Run \`designlang <url>\` first.`);
+  }
+
+  const server = createServer((req, res) => {
+    try {
+      const url = new URL(req.url, `http://localhost:${port}`);
+      const pathname = url.pathname;
+
+      if (pathname === '/' || pathname === '/index.html') {
+        const data = loadExtraction(dir, prefix);
+        const html = studioHtml(data);
+        res.writeHead(200, { 'content-type': MIME['.html'] });
+        res.end(html);
+        return;
+      }
+      if (pathname === '/raw') {
+        const data = loadExtraction(dir, prefix);
+        res.writeHead(200, { 'content-type': MIME['.json'] });
+        res.end(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (pathname === '/api/prefix') {
+        res.writeHead(200, { 'content-type': MIME['.json'] });
+        res.end(JSON.stringify({ prefix, dir }));
+        return;
+      }
+
+      // Static passthrough — screenshots, preview.html, etc.
+      const safe = pathname.replace(/\.\./g, '').replace(/^\//, '');
+      const filePath = join(dir, safe);
+      if (filePath.startsWith(dir) && existsSync(filePath) && statSync(filePath).isFile()) {
+        const ext = extname(filePath).toLowerCase();
+        res.writeHead(200, { 'content-type': MIME[ext] || 'application/octet-stream' });
+        res.end(readFileSync(filePath));
+        return;
+      }
+
+      res.writeHead(404, { 'content-type': 'text/plain' });
+      res.end('not found');
+    } catch (e) {
+      res.writeHead(500, { 'content-type': 'text/plain' });
+      res.end(`error: ${e.message}`);
+    }
+  });
+
+  await new Promise((resolveP) => server.listen(port, resolveP));
+  return { port, dir, prefix, server };
+}