designlang 7.2.0 → 9.0.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # 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.
+
+### Reliability
+
+- **Brand / primary color detection rewritten** — the extractor now ranks chromatic clusters by `interactiveBg × 100 + saturation × 2 + log(usage)` and requires either HSL saturation > 25 or an interactive-bg hit to qualify as chromatic. Previously the extractor picked the most-counted color, which on neutral-heavy sites like Linear meant the "Primary" was a pale gray (`#d0d6e0`). v8 correctly picks Linear's lime CTA (`#e4f222`) and Stripe's purple (`#533afd`). `src/extractors/colors.js`.
+- **Accessibility scoring defused** — the crawler now emits a `hasText` boolean per element (a direct text-node child with visible characters), and the WCAG extractor filters out decorative glyph wrappers, transparent/overlay pairs, and non-text containers. Linear's WCAG score moved from 25% (171 failing pairs) to 83% (1 failing pair). `src/extractors/accessibility.js`, `src/crawler.js`.
+- **Design-system score recalibrated** — thresholds for color count, shadow count, border-radii count, typography weight, and type-scale size were re-fit against ground-truth sites (Stripe, Linear, Vercel, GitHub, Apple). `cssHealth` is now weighted in the overall (8/100). Linear 47→76, Stripe 81→88, Apple 83→86, Vercel 64→76. `src/extractors/scoring.js`.
+
+### Added
+
+- **`--selector <css>`** — scopes extraction to a DOM subtree (e.g. `designlang https://stripe.com --selector "footer"`). Stripe full-page extraction drops from 2,409 elements to 112 when scoped to the footer. Falls back to the full document if the selector is invalid or empty.
+- **`--system-chrome`** — forces Playwright to use the locally installed Chrome (`channel: 'chrome'`) instead of the ~150 MB bundled Chromium, for faster `npx` first-runs in environments that already have Chrome.
+- **`--json` output mode** — full extraction payload written to stdout (suppresses progress UI) for piping into other tools. This was a partial implementation in v7; v8 makes it first-class and adds it to the CLI reference.
+- **VS Code extension** (`vscode-extension/`) — `designlang: Extract design from URL` and `designlang: Extract and inject into workspace` commands.
+- **Raycast extension** (`raycast-extension/`) — Extract, Score, and "Copy CLI command for URL" commands.
+- **Figma plugin** (`figma-plugin/`) — URL or paste-JSON → Figma Variables collections (MV for Figma's `figma.variables` API, with multi-mode support).
+- **GitHub Action** (`github-action/`) — "Design regression guard": runs `designlang` on a URL, diffs tokens vs a committed baseline, and comments the delta on the pull request. Optional `fail-on-change`.
+- **Smithery + MCP registry** (`smithery.yaml`, `smithery.dockerfile`, `docs/MCP-REGISTRY.md`) — one-command install in Smithery; checklist for the official MCP registry, Cursor, and Claude Desktop.
+- **Chrome Web Store + Firefox + Edge listing prep** (`chrome-extension/PRIVACY.md`, `chrome-extension/STORE_LISTING.md`) — privacy policy and store copy.
+- **README hero demo tape** (`docs/demo.tape`) — VHS script that renders an animated terminal GIF into `website/public/demo.gif`.
+- **Launch kit** (`docs/LAUNCH.md`) — Product Hunt / Show HN / Twitter copy + day-of checklist.
+
+### Changed
+
+- README: hero image now references the animated demo (with static PNG fallback), adds an "Install everywhere" table covering all surfaces, documents `--selector`, `--system-chrome`, and `--json`.
+- `.npmignore`: excludes all companion-surface directories (`vscode-extension/`, `raycast-extension/`, `figma-plugin/`, `github-action/`, `chrome-extension/`, `website/`) and test fixtures so the npm tarball stays small — each surface publishes to its own registry.
+- `bin/design-extract.js`: reports `8.0.0` from `--version`.
+- `src/config.js`: whitelists `selector` and `systemChrome` from CLI/config.
+
+### Thanks
+
+- To everyone who flagged that Linear's primary was coming out as light gray — that single complaint drove the brand-color rewrite.
+
 ## [7.2.0] — 2026-04-19
 
 ### Added

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:
 
@@ -396,6 +515,9 @@ Options:
   --header <headers...>   Custom headers (name:value)
   --user-agent <ua>       Override the browser User-Agent string
   --insecure              Ignore HTTPS/SSL certificate errors (self-signed, dev, proxies)
+  --selector <css>        Only extract from elements matching this CSS selector (e.g. ".pricing-card")
+  --system-chrome         Use the system Chrome install instead of the bundled Chromium (skips 150MB download)
+  --json                  Print full extraction as JSON to stdout (for piping into other tools)
   --framework <type>      Only generate specific theme (react, shadcn)
   --platforms <csv>       Additional platforms: web,ios,android,flutter,wordpress,all (additive)
   --emit-agent-rules      Emit Cursor / Claude Code / CLAUDE.md / agents.md rule files
@@ -404,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
@@ -468,6 +593,20 @@ Running `designlang https://vercel.com --full`:
 5. **Score** — Accessibility extractor calculates WCAG contrast ratios for all color pairs
 6. **Capture** — Optional: screenshots, responsive viewport crawling, interaction state recording
 
+## Install Everywhere
+
+designlang ships surfaces beyond the CLI:
+
+| Surface | Path | Description |
+|---------|------|-------------|
+| **CLI** | `npx designlang <url>` | Main entry point. |
+| **VS Code extension** | [`vscode-extension/`](vscode-extension/) | "Extract design from URL" command + auto-inject into workspace. |
+| **Raycast extension** | [`raycast-extension/`](raycast-extension/) | Extract, score, and "copy CLI command" from Raycast. |
+| **Figma plugin** | [`figma-plugin/`](figma-plugin/) | Paste a URL inside Figma, get a full Variables collection. |
+| **GitHub Action** | [`github-action/`](github-action/) | "Design regression guard" — diffs tokens on every PR and comments. |
+| **Chrome extension** | [`chrome-extension/`](chrome-extension/) | One-click handoff from any tab (MV3, `activeTab` only). |
+| **MCP server** | `npx designlang mcp` | Exposes the extracted design as MCP resources + tools for Cursor, Claude Code, Windsurf, etc. See [`docs/MCP-REGISTRY.md`](docs/MCP-REGISTRY.md). |
+
 ## Agent Skill
 
 Works with **Claude Code, Cursor, Codex, and 40+ AI coding agents** via the skills ecosystem:
@@ -489,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('6.0.0');
+  .version('9.0.0');
 
 // ── Main command: extract ──────────────────────────────────────
 program
@@ -72,6 +72,8 @@ program
   .option('--user-agent <ua>', 'override the browser User-Agent string')
   .option('--insecure', 'ignore HTTPS/SSL certificate errors (self-signed, dev, proxies)')
   .option('--ignore <selectors...>', 'CSS selectors to remove before extraction')
+  .option('--selector <css>', 'only extract design from elements matching this CSS selector (e.g. ".pricing-card")')
+  .option('--system-chrome', 'use the system Chrome install instead of the bundled Chromium (skips the 150MB Playwright download)')
   .option('--tokens-legacy', 'Emit pre-v7 flat token JSON (backward compat)')
   .option('--platforms <csv>', 'Additional platforms: web,ios,android,flutter,wordpress,all (web is always emitted)', 'web')
   .option('--emit-agent-rules', 'Emit Cursor/Claude Code/generic agent rules')
@@ -155,6 +157,8 @@ program
         insecure: merged.insecure || false,
         userAgent: merged.userAgent,
         deepInteract: merged.deepInteract || merged.full,
+        selector: merged.selector,
+        channel: merged.systemChrome ? 'chrome' : undefined,
       });
 
       // Responsive capture
@@ -217,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');
       }
@@ -800,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": "7.2.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/config.js

@@ -39,6 +39,8 @@ export function mergeConfig(cliOpts, config) {
     cookieFile: cliOpts.cookieFile || config.cookieFile,
     insecure: cliOpts.insecure || config.insecure || false,
     userAgent: cliOpts.userAgent || config.userAgent,
+    selector: cliOpts.selector || config.selector,
+    systemChrome: cliOpts.systemChrome || config.systemChrome || false,
   };
 }
 

package/src/crawler.js

@@ -24,6 +24,8 @@ export async function crawlPage(url, options = {}) {
     insecure = false,
     userAgent,
     deepInteract = false,
+    selector,
+    channel,
   } = options;
 
   const launchArgs = [
@@ -39,6 +41,9 @@ export async function crawlPage(url, options = {}) {
   const browser = await chromium.launch({
     headless: true,
     ...(executablePath && { executablePath }),
+    // channel: 'chrome' forces Playwright to use the system Chrome install
+    // instead of the 150MB bundled Chromium — see --system-chrome.
+    ...(channel && { channel }),
     args: launchArgs,
   });
   try {
@@ -97,7 +102,7 @@ export async function crawlPage(url, options = {}) {
       interactState = await runInteractionPass(page).catch(() => null);
     }
 
-    const lightData = await extractPageData(page, ignore);
+    const lightData = await extractPageData(page, ignore, selector);
     lightData.cssCoverage = cssCoverage;
     if (interactState) lightData.interactState = interactState;
 
@@ -388,8 +393,8 @@ async function runInteractionPass(page) {
   return state;
 }
 
-async function extractPageData(page, ignoreSelectors) {
-  const data = await page.evaluate(({ maxElements, ignoreSelectors }) => {
+async function extractPageData(page, ignoreSelectors, scopeSelector) {
+  const data = await page.evaluate(({ maxElements, ignoreSelectors, scopeSelector }) => {
     // Remove ignored elements before extraction
     if (ignoreSelectors && ignoreSelectors.length > 0) {
       for (const sel of ignoreSelectors) {
@@ -420,7 +425,23 @@ async function extractPageData(page, ignoreSelectors) {
       }
       return collected;
     }
-    const elements = collectElements(document, []);
+
+    // If --selector was provided, scope element collection to the matching
+    // subtrees only. Falls back to the full document if the selector is
+    // invalid or returns no matches.
+    let scopeRoots = [document];
+    if (scopeSelector) {
+      try {
+        const matches = Array.from(document.querySelectorAll(scopeSelector));
+        if (matches.length > 0) scopeRoots = matches;
+      } catch { /* invalid selector → use document */ }
+    }
+    const elements = [];
+    for (const root of scopeRoots) {
+      if (root !== document && root.nodeType === 1) elements.push(root);
+      collectElements(root, elements);
+      if (elements.length >= maxElements) break;
+    }
 
     // Build a lightweight index: stylesheet URL + their top selectors.
     // Used to attribute each element's primary source stylesheet.
@@ -502,8 +523,16 @@ async function extractPageData(page, ignoreSelectors) {
         sourceAttrBudget--;
       }
 
+      // hasText: at least one direct text-node child with visible characters —
+      // lets downstream extractors filter decorative spans/divs out of WCAG
+      // contrast accounting.
+      let hasText = false;
+      for (const node of el.childNodes) {
+        if (node.nodeType === 3 && node.textContent && node.textContent.trim()) { hasText = true; break; }
+      }
+
       results.computedStyles.push({
-        tag, classList, role, area,
+        tag, classList, role, area, hasText,
         color: cs.color,
         backgroundColor: cs.backgroundColor,
         backgroundImage: cs.backgroundImage,
@@ -530,6 +559,11 @@ async function extractPageData(page, ignoreSelectors) {
         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,
@@ -728,10 +762,25 @@ async function extractPageData(page, ignoreSelectors) {
         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,
@@ -840,7 +889,7 @@ async function extractPageData(page, ignoreSelectors) {
     }
 
     return results;
-  }, { maxElements: MAX_ELEMENTS, ignoreSelectors: ignoreSelectors || [] });
+  }, { maxElements: MAX_ELEMENTS, ignoreSelectors: ignoreSelectors || [], scopeSelector: scopeSelector || null });
 
   // Fetch and parse cross-origin stylesheets
   if (data.crossOriginSheets && data.crossOriginSheets.length > 0) {