designlang 8.0.0 → 9.0.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [9.0.0] — 2026-04-21
+
+**The Motion & Voice release.** Six new capabilities that push designlang past "extract the paint" and into "extract the *feel*, the *anatomy*, and the *voice*." No competing tool does any of these. All work ships with tests (282/282 passing).
+
+### Added — extraction
+
+- **Motion language extractor** (`src/extractors/motion.js`) — easings are classified into families (`ease-in`, `ease-in-out`, `ease-out`, `linear`, `steps`, `spring`, `custom`) via cubic-bezier geometry, durations are bucketed into a named scale (`instant`/`xs`/`sm`/`md`/`lg`/`xl`/`xxl`), spring/overshoot cubic-beziers are surfaced, scroll-linked animation usage is detected via `animation-timeline` / `view-timeline-name` / `scroll-timeline-name`, and each `@keyframes` rule is classified by kind (`slide-x`, `slide-y`, `fade`, `reveal`, `rotate`, `scale`, `pulse`, `custom`). A one-word `feel` fingerprint (`springy`/`responsive`/`smooth`/`mechanical`/`mixed`) summarizes the whole system.
+- **Motion tokens formatter** (`src/formatters/motion-tokens.js`) — emits `*-motion-tokens.json` in a DTCG-flavored shape with `$type: duration` / `$type: cubicBezier`.
+- **Component Anatomy v2** (`src/extractors/component-anatomy.js`) — groups components by variant-class hints, infers slot roles (icon / label / badge / heading / media / footer), builds a variant × size × state matrix, captures sample button labels, and emits typed React stubs via `formatAnatomyStubs`. Output: `*-anatomy.tsx`.
+- **Brand voice extractor** (`src/extractors/voice.js`) — classifies tone (friendly / formal / technical / playful / neutral) from lexical markers, picks pronoun posture (`we→you`, `you-only`, `we-only`, `third-person`), detects heading style, top CTA verbs, and microcopy patterns. Output: `*-voice.json`.
+- **Crawler extensions** (`src/crawler.js`) — per-element `animation-timeline`, view/scroll timeline names; per-candidate `text`, `slots[]`, `disabled`, `variantHint`, `sizeHint` to feed anatomy + voice.
+
+### Added — new commands
+
+- **`designlang lint <file>`** — audits DTCG / flat-JSON / CSS-vars token files for color sprawl, spacing-scale drift, radius/shadow bloat, and WCAG AA fg/bg contrast. Exits non-zero on `error`-level findings. CI-ready.
+- **`designlang drift <url> --tokens <file>`** — compares local tokens against a live site, reports `in-sync` / `minor-drift` / `notable-drift` / `major-drift` with a drift ratio. `--fail-on <level>` controls CI exit code.
+- **`designlang visual-diff <before> <after>`** — single-file HTML side-by-side report with embedded base64 screenshots, file-size deltas, and a changed-color-tokens table.
+
+### Added — markdown output
+
+Three new sections in `*-design-language.md`: **Motion Language**, **Component Anatomy**, **Brand Voice**.
+
+### Changed
+
+- Default extraction now writes **11+ files** (up from 8): `*-motion-tokens.json`, `*-anatomy.tsx` (when candidates exist), `*-voice.json`.
+- `bin/design-extract.js` version → `9.0.0`.
+- `package.json` — description refreshed; new keywords: `motion`, `animation`, `component-anatomy`, `brand-voice`, `token-lint`, `visual-diff`.
+- README: "What's New in v9" hero block, new feature sections 24-29, new CLI entries (`lint`, `drift`, `visual-diff`).
+
+### Tests
+
+- New `tests/v9-features.test.js` — 7 suites, 21 assertions across motion, anatomy, voice, and lint.
+- Full suite: **282/282 passing**.
+
 ## [8.0.0] — 2026-04-20
 
 A credibility-and-distribution release. Three reliability bugs that hurt trust on real sites are fixed; three DX flags close the most-requested CLI gaps; five new surfaces (VS Code, Raycast, Figma, GitHub Actions, MCP registry) ship alongside.

package/README.md

@@ -15,9 +15,20 @@
   <img src="designlang.png" alt="designlang in action" width="100%">
 </p>
 
-**designlang** crawls any website with a headless browser, extracts every computed style from the live DOM, and generates **8 output files** — including an AI-optimized markdown file, visual HTML preview, Tailwind config, React theme, shadcn/ui theme, Figma variables, W3C design tokens, and CSS custom properties.
+[![designlang on npm](https://pkgfolio.vercel.app/embed/pkg/designlang?v=2)](https://www.npmjs.com/package/designlang)
 
-But unlike every other tool out there, it also extracts **layout patterns** (grids, flexbox, containers), captures **responsive behavior** across 4 breakpoints, records **interaction states** (hover, focus, active), scores **WCAG accessibility**, and lets you **compare multiple brands** or **sync live sites to local tokens**.
+**designlang** crawls any website with a headless browser, extracts every computed style from the live DOM, and generates **11+ output files** — including an AI-optimized markdown file, visual HTML preview, Tailwind config, React theme, shadcn/ui theme, Figma variables, W3C design tokens, CSS custom properties, **motion tokens**, **typed component anatomy stubs**, and a **brand voice** summary.
+
+But unlike every other tool out there, it also extracts **layout patterns** (grids, flexbox, containers), **motion language** (durations, easings, springs, scroll-linked animations), **component anatomy** (slots, variant × size × state matrices), **brand voice** (tone, CTA verbs, heading style), captures **responsive behavior** across 4 breakpoints, records **interaction states** (hover, focus, active), scores **WCAG accessibility**, lints your own token files, and lets you **drift-check a codebase against a live site**, **visual-diff two URLs**, **compare multiple brands**, or **sync live sites to local tokens**.
+
+## What's New in v9 — The Motion & Voice Release
+
+- **Motion Language** — durations bucketed into semantic tokens (`instant`/`xs`/`sm`/`md`/`lg`/`xl`), easings classified into families (ease-out, spring-overshoot, steps), scroll-linked animation detection (`animation-timeline`, `view-timeline-name`), keyframe kind classification (slide / fade / reveal / rotate / scale / pulse), and a `feel` fingerprint — *springy*, *responsive*, *smooth*, *mechanical*, or *mixed*.
+- **Component Anatomy v2** — every component cluster is now an *anatomy tree* with slots (label, icon, badge, heading, media), variant × size × state matrices, and an emitted `*-anatomy.tsx` file of typed React stubs you can wire into your design system.
+- **Brand Voice** — extracts tone (friendly / formal / technical / playful / neutral), pronoun posture (`we→you` / `you-only` / `we-only` / `third-person`), heading style (Title Case / Sentence case / all-lowercase), top CTA verbs, and a microcopy inventory. Feeds LLMs the *voice*, not just the paint.
+- **`designlang lint`** — audit your own `design-tokens.json` (DTCG or flat) or `variables.css` for color sprawl, spacing-scale drift, radius/shadow bloat, and WCAG fg/bg contrast fails. Exits non-zero on errors — CI-ready.
+- **`designlang drift`** — point at a live site, pass your local token file, and get a verdict: `in-sync` / `minor-drift` / `notable-drift` / `major-drift`. Integrates cleanly with the existing GitHub Action.
+- **`designlang visual-diff`** — capture two URLs side-by-side and emit a single-file HTML report with component screenshots, file-size deltas, and changed color tokens. No heavy pixel-diff dependencies — runs in pure Node + Playwright.
 
 ## Quick Start
 
@@ -31,7 +42,7 @@ Get everything at once:
 npx designlang https://stripe.com --full
 ```
 
-## What You Get (8 Files)
+## What You Get (11+ Files)
 
 | File | What it is |
 |------|------------|
@@ -43,6 +54,9 @@ npx designlang https://stripe.com --full
 | `*-figma-variables.json` | Figma Variables import (with dark mode support) |
 | `*-theme.js` | React/CSS-in-JS theme (Chakra, Stitches, Vanilla Extract) |
 | `*-shadcn-theme.css` | shadcn/ui globals.css variables |
+| `*-motion-tokens.json` | **(v9)** Motion tokens — durations, easings, springs, scroll-linked flag |
+| `*-anatomy.tsx` | **(v9)** Typed React stubs for every detected component + variants |
+| `*-voice.json` | **(v9)** Brand voice fingerprint — tone, CTA verbs, heading style |
 
 The markdown output has **19 sections**: Color Palette, Typography, Spacing, Border Radii, Box Shadows, CSS Custom Properties, Breakpoints, Transitions & Animations, Component Patterns (with full CSS snippets), Layout System, Responsive Design, Interaction States, Accessibility (WCAG 2.1), Gradients, Z-Index Map, SVG Icons, Font Files, Image Style Patterns, and Quick Start.
 
@@ -319,7 +333,112 @@ A Manifest-v3 popup lives in [`chrome-extension/`](chrome-extension/). One click
 - **Install:** toggle developer mode at `chrome://extensions`, click *Load unpacked*, pick the `chrome-extension/` folder.
 - **Firefox + Edge** work with the same MV3 manifest.
 
-### 23. Better Auth + Network Control (NEW in v7.1)
+### 24. Motion Language (NEW in v9)
+
+Extracts the full motion fingerprint, not just transition strings:
+
+```bash
+designlang https://linear.app
+# emits linear-app-motion-tokens.json
+```
+
+```
+Motion: feel = springy, 2 spring easings, scroll-linked = yes
+Durations: instant (80ms), xs (150ms), sm (220ms), md (380ms)
+Easings: ease-out (61%), spring-overshoot (18%), ease-in-out (21%)
+Keyframes: fade-up (slide-y, used 18x), scale-in (reveal, used 4x)
+```
+
+### 25. Component Anatomy v2 (NEW in v9)
+
+Every detected component becomes an anatomy tree with typed React stubs:
+
+```bash
+designlang https://stripe.com
+# emits stripe-com-anatomy.tsx
+```
+
+```tsx
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  leadingIcon?: React.ReactNode;
+  badge?: React.ReactNode;
+  children?: React.ReactNode;
+}
+```
+
+### 26. Brand Voice (NEW in v9)
+
+Pulls the voice alongside the visual:
+
+```bash
+designlang https://vercel.com
+# emits vercel-com-voice.json + a Brand Voice section in the markdown
+```
+
+```
+Tone: technical · Pronoun: we→you · Headings: Sentence case (tight)
+Top CTA verbs: start (14), get (8), deploy (5), try (3)
+Sample headings:
+  > Develop. Preview. Ship.
+  > The React framework for the web.
+```
+
+### 27. `designlang lint` — Token Quality Linter (NEW in v9)
+
+Audit your own token file with the same rules the scorer runs against live sites:
+
+```bash
+designlang lint ./src/tokens/design-tokens.json
+```
+
+```
+Score: 74/100  Grade: C   Tokens: 126
+
+  colorDiscipline      ██████████████░░░░░░ 72
+  spacingSystem        ████████████████░░░░ 84
+  borderRadii          ████████████░░░░░░░░ 60
+  shadows              ██████████░░░░░░░░░░ 50
+  accessibility        █████████████████░░░ 88
+
+  WARN  [color-sprawl] 3 near-duplicate color pair(s) within 8 RGB units
+  ERROR [contrast-wcag-aa] 2 fg/bg pair(s) fail WCAG AA (4.5:1)
+```
+
+Exits non-zero on any `error`-level finding — drop into CI.
+
+### 28. `designlang drift` — Codebase ↔ Live Site Sync Check (NEW in v9)
+
+Point at a deployed site, pass your local tokens, and get a verdict:
+
+```bash
+designlang drift https://yourapp.com --tokens ./src/tokens.json --tolerance 8
+```
+
+```
+Verdict: notable-drift (drift ratio: 0.24)
+
+| token          | local    | nearest live       | Δ  |
+|----------------|----------|--------------------|----|
+| color.primary  | #4338CA  | #5B4CF5 (primary)  | 22 |
+| color.border   | #D4D4D8  | #E5E5EA (surface)  | 18 |
+```
+
+Configurable `--fail-on <level>` for CI: `minor-drift` / `notable-drift` / `major-drift`.
+
+### 29. `designlang visual-diff` — Two-URL Side-by-Side (NEW in v9)
+
+Capture screenshots + token deltas for two URLs in a single self-contained HTML report:
+
+```bash
+designlang visual-diff https://staging.app.com https://app.com
+```
+
+Emits `visual-diff-<timestamp>.html` with embedded images (base64), file-size deltas, and a changed-color-tokens table. Nothing else to serve — just open the file.
+
+### 30. Better Auth + Network Control (v7.1)
 
 Extracting from authenticated, self-signed, or non-default environments now takes one flag:
 
@@ -407,15 +526,18 @@ Options:
   --verbose               Detailed progress output
 
 Commands:
-  apply <url>             Extract and apply design directly to your project
-  clone <url>             Generate a working Next.js starter from extracted design
-  score <url>             Rate design quality (7 categories, A-F, bar chart)
-  watch <url>             Monitor for design changes on interval
-  diff <urlA> <urlB>      Compare two sites' design languages
-  brands <urls...>        Multi-brand comparison matrix
-  sync <url>              Sync local tokens with live site
-  history <url>           View design change history
-  mcp                     Launch stdio MCP server (--output-dir <dir>)
+  apply <url>                       Extract and apply design directly to your project
+  clone <url>                       Generate a working Next.js starter from extracted design
+  score <url>                       Rate design quality (7 categories, A-F, bar chart)
+  watch <url>                       Monitor for design changes on interval
+  diff <urlA> <urlB>                Compare two sites' design languages
+  brands <urls...>                  Multi-brand comparison matrix
+  sync <url>                        Sync local tokens with live site
+  history <url>                     View design change history
+  mcp                               Launch stdio MCP server (--output-dir <dir>)
+  lint <file>                       (v9) Audit a local token file (.json/.css) — CI-ready
+  drift <url> --tokens <file>       (v9) Check local tokens for drift against a live site
+  visual-diff <before> <after>      (v9) Side-by-side HTML diff of two URLs
 ```
 
 ## Example Output
@@ -506,3 +628,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome!
 ## License
 
 [MIT](LICENSE) - Manav Arya Singh
+
+

package/bin/design-extract.js

@@ -48,7 +48,7 @@ const program = new Command();
 program
   .name('designlang')
   .description('Extract the complete design language from any website')
-  .version('8.0.0');
+  .version('9.0.0');
 
 // ── Main command: extract ──────────────────────────────────────
 program
@@ -221,6 +221,15 @@ program
       };
       files.push({ name: `${prefix}-mcp.json`, content: JSON.stringify(mcpPayload, null, 2), label: 'MCP companion' });
 
+      // v9: motion tokens + component anatomy stubs + voice
+      const { formatMotionTokens } = await import('../src/formatters/motion-tokens.js');
+      const { formatAnatomyStubs } = await import('../src/extractors/component-anatomy.js');
+      files.push({ name: `${prefix}-motion-tokens.json`, content: formatMotionTokens(design.motion), label: 'Motion Tokens' });
+      if ((design.componentAnatomy || []).length) {
+        files.push({ name: `${prefix}-anatomy.tsx`, content: formatAnatomyStubs(design.componentAnatomy), label: 'Component Anatomy (stubs)' });
+      }
+      files.push({ name: `${prefix}-voice.json`, content: JSON.stringify(design.voice || {}, null, 2), label: 'Brand Voice' });
+
       for (const file of files) {
         writeFileSync(join(outDir, file.name), file.content, 'utf-8');
       }
@@ -804,6 +813,86 @@ program
     }
   });
 
+// ── Token lint (v9) ────────────────────────────────────────
+program
+  .command('lint <file>')
+  .description('Audit a local token file (.json / .css) for color sprawl, scale drift, contrast fails')
+  .option('--json', 'emit machine-readable JSON')
+  .action(async (file, opts) => {
+    try {
+      const { lintTokens } = await import('../src/lint.js');
+      const r = lintTokens(resolve(file));
+      if (opts.json) { process.stdout.write(JSON.stringify(r, null, 2) + '\n'); return; }
+      console.log('');
+      console.log(chalk.bold(`  designlang lint — ${file}`));
+      console.log(`  Score: ${chalk.bold(r.score + '/100')}  Grade: ${chalk.bold(r.grade)}   Tokens: ${r.tokenCount}`);
+      console.log('');
+      for (const [k, v] of Object.entries(r.scorecard)) {
+        const bar = '█'.repeat(Math.round(v / 5)) + '░'.repeat(20 - Math.round(v / 5));
+        console.log(`  ${k.padEnd(20)} ${bar} ${v}`);
+      }
+      console.log('');
+      for (const f of r.findings) {
+        const color = f.severity === 'error' ? chalk.red : f.severity === 'warn' ? chalk.yellow : chalk.cyan;
+        console.log(`  ${color(f.severity.toUpperCase())} [${f.rule}] ${f.message}`);
+      }
+      if (!r.findings.length) console.log(chalk.green('  ✓ no issues found'));
+      console.log('');
+      process.exit(r.findings.some(f => f.severity === 'error') ? 1 : 0);
+    } catch (err) {
+      process.stderr.write(chalk.red(`\n  Error: ${err.message}\n\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Drift (v9) ─────────────────────────────────────────────
+program
+  .command('drift <url>')
+  .description('Compare local tokens against a live site and report drift (CI-friendly)')
+  .requiredOption('--tokens <file>', 'local tokens file (.json or .css)')
+  .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('--json', 'emit machine-readable JSON')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+    try {
+      const { checkDrift, formatDriftMarkdown } = await import('../src/drift.js');
+      const r = await checkDrift(url, { tokens: resolve(opts.tokens), tolerance: opts.tolerance });
+      if (opts.json) { process.stdout.write(JSON.stringify(r, null, 2) + '\n'); }
+      else { console.log('\n' + formatDriftMarkdown(r) + '\n'); }
+      const order = ['in-sync', 'minor-drift', 'notable-drift', 'major-drift'];
+      if (order.indexOf(r.verdict) >= order.indexOf(opts.failOn)) process.exit(1);
+    } catch (err) {
+      process.stderr.write(chalk.red(`\n  Error: ${err.message}\n\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Visual diff (v9) ───────────────────────────────────────
+program
+  .command('visual-diff <before> <after>')
+  .description('Side-by-side HTML diff of two URLs with screenshots + token changes')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .action(async (before, after, opts) => {
+    if (!before.startsWith('http')) before = `https://${before}`;
+    if (!after.startsWith('http')) after = `https://${after}`;
+    validateUrl(before); validateUrl(after);
+    const spinner = ora('Capturing before + after').start();
+    try {
+      const { visualDiff, formatVisualDiffHtml } = await import('../src/visual-diff.js');
+      const r = await visualDiff({ beforeUrl: before, afterUrl: after });
+      const html = formatVisualDiffHtml(r);
+      mkdirSync(resolve(opts.out), { recursive: true });
+      const path = join(resolve(opts.out), `visual-diff-${Date.now()}.html`);
+      writeFileSync(path, html, 'utf8');
+      spinner.succeed(`Visual diff written → ${path}`);
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
 // ── MCP server command ─────────────────────────────────────
 program
   .command('mcp')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "designlang",
-  "version": "8.0.0",
-  "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, and more. Outputs AI-optimized markdown, W3C design tokens, Tailwind config, and CSS variables.",
+  "version": "9.0.0",
+  "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, motion, component anatomy, and brand voice. Outputs AI-optimized markdown, W3C design tokens, motion tokens, typed component stubs, Tailwind config, and more.",
   "type": "module",
   "bin": {
     "designlang": "./bin/design-extract.js"
@@ -38,7 +38,13 @@
     "vue",
     "svelte",
     "json",
-    "ci-cd"
+    "ci-cd",
+    "motion",
+    "animation",
+    "component-anatomy",
+    "brand-voice",
+    "token-lint",
+    "visual-diff"
   ],
   "author": "masyv",
   "license": "MIT"

package/src/crawler.js

@@ -559,6 +559,11 @@ async function extractPageData(page, ignoreSelectors, scopeSelector) {
         zIndex: cs.zIndex,
         transition: cs.transition,
         animation: cs.animation,
+        animationTimeline: cs.animationTimeline || cs.getPropertyValue('animation-timeline') || '',
+        animationRangeStart: cs.getPropertyValue('animation-range-start') || '',
+        animationRangeEnd: cs.getPropertyValue('animation-range-end') || '',
+        viewTimelineName: cs.getPropertyValue('view-timeline-name') || '',
+        scrollTimelineName: cs.getPropertyValue('scroll-timeline-name') || '',
         display: cs.display,
         position: cs.position,
         flexDirection: cs.flexDirection,
@@ -757,10 +762,25 @@ async function extractPageData(page, ignoreSelectors, scopeSelector) {
         parseFloat(cs.fontSize) || 0,
         parseFloat(cs.fontWeight) || 0,
       ];
+      const text = ((el.innerText || el.textContent || '') + '').trim().slice(0, 160);
+      const slots = Array.from(el.children).slice(0, 8).map(c => {
+        const tagName = c.tagName.toLowerCase();
+        let role = 'content';
+        if (tagName === 'svg' || tagName === 'img' || c.querySelector?.('svg,img')) role = 'icon';
+        else if (/badge|pill|tag|chip/i.test(c.className || '')) role = 'badge';
+        else if (/h[1-6]/.test(tagName) || /title|heading/i.test(c.className || '')) role = 'heading';
+        else if (/description|subtitle|text|body/i.test(c.className || '')) role = 'text';
+        return { tag: tagName, role, text: ((c.innerText || c.textContent || '') + '').trim().slice(0, 80) };
+      });
       results.componentCandidates.push({
         kind,
         structuralHash: structuralHashOf(el),
         styleVector,
+        text,
+        slots,
+        disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true',
+        variantHint: (cls.match(/\b(primary|secondary|tertiary|ghost|outline|solid|destructive|danger|success|warning|link|subtle)\b/) || [])[1] || '',
+        sizeHint: (cls.match(/\b(xs|sm|md|lg|xl|small|medium|large)\b/) || [])[1] || '',
         css: {
           background: cs.backgroundColor,
           color: cs.color,

package/src/drift.js

@@ -0,0 +1,137 @@
+// designlang drift <url> --tokens <file>
+// Compares local project tokens against the live site and reports what's drifted.
+// Designed for CI/CD: exits non-zero when drift exceeds the tolerance budget.
+
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+import { extractDesignLanguage } from './index.js';
+
+function flattenDtcg(obj, prefix = '', out = {}) {
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (k.startsWith('$')) continue;
+    if (v && typeof v === 'object') {
+      if ('$value' in v) {
+        out[prefix ? `${prefix}.${k}` : k] = v.$value;
+      } else {
+        flattenDtcg(v, prefix ? `${prefix}.${k}` : k, out);
+      }
+    }
+  }
+  return out;
+}
+
+function loadLocalTokens(file) {
+  const raw = readFileSync(file, 'utf8');
+  const ext = extname(file);
+  if (ext === '.json') {
+    const j = JSON.parse(raw);
+    const flat = flattenDtcg(j);
+    if (Object.keys(flat).length) return flat;
+    const out = {};
+    for (const [group, entries] of Object.entries(j)) {
+      if (!entries || typeof entries !== 'object') continue;
+      for (const [k, v] of Object.entries(entries)) out[`${group}.${k}`] = String(v);
+    }
+    return out;
+  }
+  if (ext === '.css') {
+    const out = {};
+    for (const m of raw.matchAll(/--([\w-]+):\s*([^;]+);/g)) out[m[1]] = m[2].trim();
+    return out;
+  }
+  throw new Error(`Unsupported token file: ${ext}`);
+}
+
+function hexToRgb(h) {
+  const m = h.replace('#', '').match(/^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i);
+  return m ? [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)] : null;
+}
+
+function colorDistance(a, b) {
+  const ra = hexToRgb(a), rb = hexToRgb(b);
+  if (!ra || !rb) return Infinity;
+  return Math.sqrt(ra.reduce((s, v, i) => s + (v - rb[i]) ** 2, 0));
+}
+
+function findNearest(value, palette) {
+  if (!/^#[\da-f]{6}$/i.test(value)) return null;
+  let best = { distance: Infinity, token: null };
+  for (const p of palette) {
+    if (!/^#[\da-f]{6}$/i.test(p.hex || '')) continue;
+    const d = colorDistance(value, p.hex);
+    if (d < best.distance) best = { distance: d, token: p };
+  }
+  return best;
+}
+
+export async function checkDrift(url, { tokens: tokensFile, tolerance = 8, options = {} } = {}) {
+  const local = loadLocalTokens(tokensFile);
+  const design = await extractDesignLanguage(url, options);
+  const livePalette = design.colors?.all || [];
+
+  const drifted = [];
+  const matched = [];
+  const unknown = [];
+
+  for (const [name, value] of Object.entries(local)) {
+    if (!/^#[\da-f]{3,8}$/i.test(String(value))) continue; // only color tokens for now
+    const hex = value.length === 4 ? '#' + value.slice(1).split('').map(c => c + c).join('') : value;
+    const nearest = findNearest(hex, livePalette);
+    if (!nearest || nearest.distance === Infinity) { unknown.push({ name, value: hex }); continue; }
+    if (nearest.distance > tolerance) {
+      drifted.push({
+        token: name,
+        local: hex,
+        nearestLive: nearest.token.hex,
+        distance: Math.round(nearest.distance),
+        role: nearest.token.role || 'unknown',
+      });
+    } else {
+      matched.push({ token: name, local: hex, liveMatch: nearest.token.hex, distance: Math.round(nearest.distance) });
+    }
+  }
+
+  const driftRatio = drifted.length / Math.max(1, drifted.length + matched.length);
+  const verdict = driftRatio === 0 ? 'in-sync' : driftRatio < 0.15 ? 'minor-drift' : driftRatio < 0.4 ? 'notable-drift' : 'major-drift';
+
+  return {
+    url,
+    tokensFile,
+    tolerance,
+    verdict,
+    driftRatio: +driftRatio.toFixed(3),
+    drifted,
+    matched,
+    unknown,
+    summary: {
+      total: drifted.length + matched.length,
+      drifted: drifted.length,
+      matched: matched.length,
+      unknown: unknown.length,
+    },
+  };
+}
+
+export function formatDriftMarkdown(r) {
+  const lines = [
+    `# designlang drift report`,
+    ``,
+    `**Live site:** ${r.url}`,
+    `**Local tokens:** ${r.tokensFile}`,
+    `**Verdict:** ${r.verdict} (drift ratio: ${r.driftRatio})`,
+    ``,
+    `| metric | count |`,
+    `|---|---|`,
+    `| total color tokens | ${r.summary.total} |`,
+    `| matched | ${r.summary.matched} |`,
+    `| drifted | ${r.summary.drifted} |`,
+    `| unknown | ${r.summary.unknown} |`,
+    ``,
+  ];
+  if (r.drifted.length) {
+    lines.push(`## Drifted tokens`, ``, `| token | local | nearest live | Δ |`, `|---|---|---|---|`);
+    for (const d of r.drifted) lines.push(`| \`${d.token}\` | \`${d.local}\` | \`${d.nearestLive}\` (${d.role}) | ${d.distance} |`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/extractors/component-anatomy.js

@@ -0,0 +1,123 @@
+// Component Anatomy v2 — builds per-kind anatomy trees, variant × state matrices,
+// and typed prop surfaces that downstream generators can turn into stubs.
+
+const KNOWN_VARIANTS = ['primary', 'secondary', 'tertiary', 'ghost', 'outline', 'solid', 'destructive', 'danger', 'success', 'warning', 'link', 'subtle'];
+const KNOWN_SIZES = ['xs', 'sm', 'md', 'lg', 'xl', 'small', 'medium', 'large'];
+
+function slotFingerprint(slots = []) {
+  return slots.map(s => s.role).join('>');
+}
+
+function inferSlots(slots = [], kind) {
+  const roles = new Set(slots.map(s => s.role));
+  if (kind === 'button') {
+    return {
+      label: true,
+      icon: roles.has('icon'),
+      badge: roles.has('badge'),
+    };
+  }
+  if (kind === 'card') {
+    return {
+      heading: roles.has('heading'),
+      description: roles.has('text'),
+      media: roles.has('icon'),
+      footer: slots.length > 3,
+    };
+  }
+  if (kind === 'input') {
+    return { leading: roles.has('icon'), trailing: false };
+  }
+  return {};
+}
+
+function dominant(arr) {
+  const counts = {};
+  for (const v of arr) counts[v] = (counts[v] || 0) + 1;
+  return Object.entries(counts).sort((a, b) => b[1] - a[1])[0]?.[0] || '';
+}
+
+export function extractComponentAnatomy(candidates = []) {
+  const byKind = {};
+  for (const c of candidates) {
+    const k = c.kind || 'other';
+    (byKind[k] ||= []).push(c);
+  }
+
+  const anatomies = [];
+  for (const [kind, items] of Object.entries(byKind)) {
+    if (items.length < 2) continue;
+
+    // Group variants by explicit class hint, fall back to style vector.
+    const variantGroups = {};
+    for (const it of items) {
+      const v = it.variantHint || 'default';
+      (variantGroups[v] ||= []).push(it);
+    }
+
+    const variants = Object.entries(variantGroups).map(([name, vs]) => {
+      const sizes = {};
+      for (const it of vs) {
+        const sz = it.sizeHint || 'default';
+        (sizes[sz] ||= []).push(it);
+      }
+      return {
+        name,
+        count: vs.length,
+        states: {
+          default: { count: vs.filter(v => !v.disabled).length, css: vs.find(v => !v.disabled)?.css || null },
+          disabled: { count: vs.filter(v => v.disabled).length, css: vs.find(v => v.disabled)?.css || null },
+        },
+        sizes: Object.entries(sizes).map(([sName, sItems]) => ({ name: sName, count: sItems.length, css: sItems[0].css })),
+        sampleText: vs.slice(0, 5).map(v => v.text).filter(Boolean),
+      };
+    }).sort((a, b) => b.count - a.count);
+
+    const slotSignatures = items.map(i => slotFingerprint(i.slots));
+    const anatomy = {
+      kind,
+      totalInstances: items.length,
+      slots: inferSlots(items[0].slots, kind),
+      dominantSlotShape: dominant(slotSignatures),
+      variants,
+      props: {
+        variant: Object.keys(variantGroups).filter(v => v !== 'default'),
+        size: [...new Set(items.map(i => i.sizeHint).filter(Boolean))],
+        disabled: items.some(i => i.disabled),
+      },
+    };
+    anatomies.push(anatomy);
+  }
+
+  return anatomies.sort((a, b) => b.totalInstances - a.totalInstances);
+}
+
+// Emit TypeScript-flavored React stub for the anatomy — includes variant/size props + slot children.
+export function formatAnatomyStubs(anatomies = []) {
+  const lines = [
+    "// Auto-generated by designlang — component anatomy v2.",
+    "// Scaffolds. Wire into your token system; not a runtime library.",
+    "",
+    "import * as React from 'react';",
+    "",
+  ];
+  for (const a of anatomies) {
+    const Name = a.kind.charAt(0).toUpperCase() + a.kind.slice(1);
+    const variantUnion = (a.props.variant.length ? a.props.variant : ['default']).map(v => `'${v}'`).join(' | ');
+    const sizeUnion = (a.props.size.length ? a.props.size : ['md']).map(v => `'${v}'`).join(' | ');
+    lines.push(`export interface ${Name}Props {`);
+    lines.push(`  variant?: ${variantUnion};`);
+    lines.push(`  size?: ${sizeUnion};`);
+    if (a.props.disabled) lines.push(`  disabled?: boolean;`);
+    if (a.slots.icon) lines.push(`  leadingIcon?: React.ReactNode;`);
+    if (a.slots.badge) lines.push(`  badge?: React.ReactNode;`);
+    lines.push(`  children?: React.ReactNode;`);
+    lines.push(`}`);
+    lines.push(``);
+    lines.push(`export function ${Name}({ variant = '${a.props.variant[0] || 'default'}', size = 'md', ...rest }: ${Name}Props) {`);
+    lines.push(`  return React.createElement('${a.kind === 'input' ? 'input' : a.kind === 'link' ? 'a' : a.kind === 'card' ? 'div' : 'button'}', { 'data-variant': variant, 'data-size': size, ...rest });`);
+    lines.push(`}`);
+    lines.push(``);
+  }
+  return lines.join('\n');
+}