designlang 12.4.0 → 12.8.0

package/bin/design-extract.js

@@ -50,6 +50,11 @@ import { formatScoreBadge } from '../src/formatters/badge.js';
 import { formatRemix } from '../src/formatters/remix.js';
 import { VOCABULARIES, getVocabulary, listVocabularies } from '../src/vocabularies/index.js';
 import { buildPack } from '../src/pack.js';
+import { recolorDesign } from '../src/recolor.js';
+import { formatThemeSwap, formatThemeSwapMarkdown } from '../src/formatters/theme-swap.js';
+import { formatBrandBook, formatBrandBookMarkdown } from '../src/formatters/brand-book.js';
+import { fuseDesigns, AXES } from '../src/fuse.js';
+import { formatPair, formatPairMarkdown } from '../src/formatters/pair.js';
 import { nameFromUrl } from '../src/utils.js';
 
 function validateUrl(url) {
@@ -1225,6 +1230,296 @@ program
     }
   });
 
+// ── Theme-swap command — recolour an extracted design around a new primary
+program
+  .command('theme-swap <url>')
+  .description('Recolour the extracted design around a new brand primary (preserves type, spacing, neutrals)')
+  .requiredOption('--primary <hex>', 'target primary colour as hex (e.g. "#ff4800")')
+  .option('--from <hex>', 'override the auto-detected source primary (e.g. when the extractor misclassifies)')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: derived from URL + target hex)')
+  .option('--format <fmt>', 'output format: html, md, json, tokens, all', 'all')
+  .option('--open', 'open the HTML preview in the default browser')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const spinner = ora(`Extracting ${url}...`).start();
+    try {
+      const original = await extractDesignLanguage(url);
+      spinner.text = `Recolouring around ${opts.primary}...`;
+      const { design: recoloured, summary } = recolorDesign(original, {
+        primary: opts.primary,
+        fromPrimary: opts.from,
+      });
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const targetSlug = String(opts.primary).replace(/^#/, '').toLowerCase();
+      const prefix = opts.name || `${nameFromUrl(url)}-themeswap-${targetSlug}`;
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatThemeSwap(original, recoloured, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.themeswap.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatThemeSwapMarkdown(original, recoloured);
+        const p = join(outDir, `${prefix}.themeswap.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        const p = join(outDir, `${prefix}.themeswap.json`);
+        writeFileSync(p, JSON.stringify({
+          url: original.meta?.url,
+          from: summary.from,
+          to: summary.to,
+          hueShift: summary.hueShift,
+          changedColors: summary.changes.length,
+          changes: summary.changes,
+          timestamp: new Date().toISOString(),
+        }, null, 2));
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'tokens') {
+        const tokens = formatDtcgTokens(recoloured);
+        const p = join(outDir, `${prefix}.themeswap.tokens.json`);
+        writeFileSync(p, typeof tokens === 'string' ? tokens : JSON.stringify(tokens, null, 2));
+        written.push(p);
+      }
+
+      spinner.stop();
+      console.log('');
+      console.log(`  ${chalk.bold(`${summary.from} → ${summary.to}`)} ${chalk.gray('·')} ${chalk.cyan(summary.changes.length)} colours ${chalk.gray('·')} ${chalk.gray(url)}`);
+      console.log(`  ${chalk.gray(`Hue shift: ${(summary.hueShift).toFixed(1)}° · neutrals preserved · type/spacing/motion untouched`)}`);
+      console.log('');
+      for (const f of written) console.log(`  ${chalk.green('✓')} ${chalk.gray(f)}`);
+      console.log('');
+
+      if (opts.open) {
+        const htmlPath = written.find(p => p.endsWith('.html'));
+        if (htmlPath) {
+          const { spawn } = await import('child_process');
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+        }
+      }
+    } catch (err) {
+      spinner.fail('Theme-swap failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Brand command — full editorial brand-guidelines book ────
+program
+  .command('brand <url>')
+  .description('Generate a full brand-guidelines book — colour, type, spacing, motion, voice, components, accessibility, tokens, and how-to-use guidance')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: derived from URL)')
+  .option('--format <fmt>', 'output format: html, md, json, all', 'all')
+  .option('--open', 'open the HTML book in the default browser')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const spinner = ora(`Building brand guidelines for ${url}...`).start();
+    try {
+      // The brand book leans on the full extraction (logo, motion, voice,
+      // anatomy, accessibility), so default to --full unless the caller has
+      // explicitly opted out via env.
+      const design = await extractDesignLanguage(url, {
+        screenshots: true,
+        responsive: false,
+        interactions: false,
+        deepInteract: true,
+      });
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const prefix = opts.name || `${nameFromUrl(url)}.brand`;
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatBrandBook(design, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatBrandBookMarkdown(design);
+        const p = join(outDir, `${prefix}.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        // A trimmed JSON of the most-used surfaces in the book — useful for
+        // programmatic consumption without re-running extraction.
+        const p = join(outDir, `${prefix}.json`);
+        writeFileSync(p, JSON.stringify({
+          url: design.meta?.url,
+          title: design.meta?.title,
+          timestamp: design.meta?.timestamp,
+          intent: design.pageIntent,
+          material: design.materialLanguage,
+          imagery: design.imageryStyle,
+          library: design.componentLibrary,
+          stack: design.stack,
+          voice: design.voice,
+          colors: design.colors,
+          typography: design.typography,
+          spacing: design.spacing,
+          shadows: design.shadows,
+          borders: design.borders,
+          motion: design.motion,
+          accessibility: design.accessibility,
+          score: design.score,
+        }, null, 2));
+        written.push(p);
+      }
+
+      spinner.stop();
+      const colorCount = (design.colors?.all || []).length;
+      const fontCount = (design.typography?.families || []).length;
+      const grade = design.score?.grade || '—';
+      console.log('');
+      console.log(`  ${chalk.bold('Brand book')} ${chalk.gray('·')} ${chalk.cyan(colorCount + ' tokens')} ${chalk.gray('·')} ${chalk.cyan(fontCount + ' fonts')} ${chalk.gray('·')} ${chalk.cyan('grade ' + grade)} ${chalk.gray('·')} ${chalk.gray(url)}`);
+      console.log('');
+      for (const f of written) console.log(`  ${chalk.green('✓')} ${chalk.gray(f)}`);
+      console.log('');
+      console.log(chalk.gray(`  Open the .html — it's a self-contained, print-ready guidelines book.`));
+      console.log('');
+
+      if (opts.open) {
+        const htmlPath = written.find(p => p.endsWith('.html'));
+        if (htmlPath) {
+          const { spawn } = await import('child_process');
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+        }
+      }
+    } catch (err) {
+      spinner.fail('Brand book failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ── Pair command — fuse two designs across configurable axes
+program
+  .command('pair <urlA> <urlB>')
+  .description('Fuse two extracted designs across axes (colours/typography/spacing/shape/motion/voice/components)')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: <hostA>-x-<hostB>)')
+  .option('--colors-from <a|b>',     'pull colours from A or B (default: a)')
+  .option('--typography-from <a|b>', 'pull typography from A or B (default: b)')
+  .option('--spacing-from <a|b>',    'pull spacing from A or B (default: a)')
+  .option('--shape-from <a|b>',      'pull shape (radii + shadows) from A or B (default: a)')
+  .option('--motion-from <a|b>',     'pull motion from A or B (default: a)')
+  .option('--voice-from <a|b>',      'pull voice from A or B (default: b)')
+  .option('--components-from <a|b>', 'pull component anatomy from A or B (default: b)')
+  .option('--brand', 'also emit a full brand-guidelines book of the fused identity')
+  .option('--format <fmt>', 'output format: html, md, json, all', 'all')
+  .option('--open', 'open the HTML pair card in the default browser')
+  .action(async (urlA, urlB, opts) => {
+    if (!urlA.startsWith('http')) urlA = `https://${urlA}`;
+    if (!urlB.startsWith('http')) urlB = `https://${urlB}`;
+    validateUrl(urlA);
+    validateUrl(urlB);
+
+    const spinner = ora(`Extracting ${urlA} and ${urlB} in parallel...`).start();
+    try {
+      const [designA, designB] = await Promise.all([
+        extractDesignLanguage(urlA),
+        extractDesignLanguage(urlB),
+      ]);
+
+      spinner.text = 'Fusing...';
+      const { design: fused, summary } = fuseDesigns(designA, designB, {
+        colorsFrom:     opts.colorsFrom,
+        typographyFrom: opts.typographyFrom,
+        spacingFrom:    opts.spacingFrom,
+        shapeFrom:      opts.shapeFrom,
+        motionFrom:     opts.motionFrom,
+        voiceFrom:      opts.voiceFrom,
+        componentsFrom: opts.componentsFrom,
+      });
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const prefix = opts.name || `${nameFromUrl(urlA)}-x-${nameFromUrl(urlB)}.pair`;
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatPair(designA, designB, fused, summary, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatPairMarkdown(designA, designB, fused, summary);
+        const p = join(outDir, `${prefix}.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        const p = join(outDir, `${prefix}.json`);
+        writeFileSync(p, JSON.stringify({
+          a: { url: designA.meta?.url, host: summary.a.host },
+          b: { url: designB.meta?.url, host: summary.b.host },
+          axes: summary.axes,
+          fused: {
+            primary: fused.colors?.primary?.hex || null,
+            family: (fused.typography?.families || [])[0],
+            tone: fused.voice?.tone,
+          },
+          timestamp: new Date().toISOString(),
+        }, null, 2));
+        written.push(p);
+      }
+      if (opts.brand) {
+        const html = formatBrandBook(fused, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.brand.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+
+      spinner.stop();
+      console.log('');
+      console.log(`  ${chalk.bold(`${summary.a.host} × ${summary.b.host}`)}`);
+      console.log('');
+      const axisLabels = {
+        colors: 'Colours', typography: 'Typography', spacing: 'Spacing',
+        shape: 'Shape', motion: 'Motion', voice: 'Voice', components: 'Components',
+      };
+      for (const axis of Object.keys(axisLabels)) {
+        const src = summary.axes[axis];
+        const fromHost = src === 'a' ? summary.a.host : summary.b.host;
+        const tag = src === 'a' ? chalk.cyan('A') : chalk.magenta('B');
+        console.log(`    ${tag}  ${axisLabels[axis].padEnd(12)} ${chalk.gray('·')} ${chalk.gray(fromHost)}`);
+      }
+      console.log('');
+      for (const f of written) console.log(`  ${chalk.green('✓')} ${chalk.gray(f)}`);
+      console.log('');
+
+      if (opts.open) {
+        const htmlPath = written.find(p => p.endsWith('.html'));
+        if (htmlPath) {
+          const { spawn } = await import('child_process');
+          const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(cmd, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+        }
+      }
+    } catch (err) {
+      spinner.fail('Pair failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ── Apply command ──────────────────────────────────────────
 program
   .command('apply <url>')

package/commands/battle.md

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

package/commands/brand.md

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

package/commands/extract.md

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

package/commands/grade.md

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

package/commands/pack.md

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

package/commands/pair.md

@@ -0,0 +1,68 @@
+---
+description: Fuse two extracted designs into a single hybrid identity. Pick which axis (colour, typography, spacing, shape, motion, voice, components) comes from which site. Defaults to "visual A × voice B" — same colours/spacing as the first URL, type/voice/components from the second.
+argument-hint: <urlA> <urlB>  [--colors-from a|b] [--typography-from a|b] [--brand]
+---
+
+Fuse the design DNA of two sites and emit an editorial pair card showing the crossover.
+
+```bash
+npx designlang pair $ARGUMENTS
+```
+
+If `$ARGUMENTS` doesn't contain at least two URLs, ask the user for the second one.
+
+Both sites are extracted in parallel (~30s total). Outputs land in `./design-extract-output/`:
+
+- `*-x-*.pair.html` — editorial pair card with cover, axis matrix, fused specimen
+- `*-x-*.pair.md` — markdown summary (axis source table)
+- `*-x-*.pair.json` — structured deltas (which axis came from where)
+- `*-x-*.pair.brand.html` — full brand-guidelines book of the fused identity (only with `--brand`)
+
+After the run completes:
+
+1. Read the markdown to summarise: which axis came from A, which from B
+2. Highlight the most distinctive crossover (the fused specimen quotes a real headline from whichever site contributed the voice)
+3. Offer to open the HTML pair card
+
+## Default axis split
+
+| Axis | Default source | Why |
+|---|---|---|
+| Colour | A | Brand identity tends to lead with colour |
+| Spacing | A | Spacing co-varies with the visual layout |
+| Shape | A | Radii + shadows belong with the visual surface |
+| Motion | A | Motion is part of the visual feel |
+| **Typography** | **B** | The crossover moment — different voice |
+| **Voice** | **B** | Tone, headings, CTA verbs from B |
+| **Components** | **B** | Anatomy from B's library |
+
+So the default is "Site A's visuals + Site B's words". Override any axis with `--<axis>-from a|b`.
+
+## Useful flags
+
+| Flag | Effect |
+|---|---|
+| `--colors-from <a\|b>` | Force colour source |
+| `--typography-from <a\|b>` | Force typography source |
+| `--spacing-from <a\|b>` | Force spacing source |
+| `--shape-from <a\|b>` | Force radii + shadows source |
+| `--motion-from <a\|b>` | Force motion source |
+| `--voice-from <a\|b>` | Force voice / tone / heading source |
+| `--components-from <a\|b>` | Force component anatomy source |
+| `--brand` | Also emit a full brand-guidelines book of the fused identity |
+| `--format html\|md\|json\|all` | Pick output formats |
+| `--open` | Open the HTML pair card |
+
+## Example experiments
+
+```
+npx designlang pair stripe.com linear.app                 # default split
+npx designlang pair stripe.com linear.app --type-from a   # Stripe everything except components/voice from Linear
+npx designlang pair vercel.com apple.com --brand          # fused identity as a hand-off brand book
+```
+
+## Pairs nicely with
+
+- `/grade <url>` — grade either source side individually before pairing
+- `/brand <url>` — generate a brand book of one source for comparison
+- `/battle <urlA> <urlB>` — head-to-head graded comparison (the inverse of `pair`)

package/commands/remix.md

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

package/commands/theme-swap.md

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

package/package.json

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