designlang 12.4.0 → 12.7.1

package/.claude-plugin/marketplace.json

@@ -1,15 +1,15 @@
 {
-  "name": "design-extract",
+  "name": "designlang",
   "owner": {
     "name": "Manavarya Singh",
     "url": "https://github.com/Manavarya09"
   },
   "plugins": [
     {
-      "name": "design-extract",
+      "name": "designlang",
       "source": "./",
-      "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, components, and more. Outputs AI-optimized markdown, W3C design tokens, Tailwind config, and CSS variables.",
-      "version": "1.0.0",
+      "description": "Seven slash commands wrapping the designlang CLI: /extract (full design language \u2192 DTCG, Tailwind, Figma), /grade (shareable HTML report card + SVG badge), /battle (head-to-head graded comparison), /remix (restyle in 6 vocabularies \u2014 brutalist, swiss, art-deco, cyberpunk, soft-ui, editorial), /pack (one downloadable design-system bundle), /theme-swap (OKLCH-correct recolour around a new brand primary), /brand (full editorial brand-guidelines book \u2014 13 chapters, hand-off-ready).",
+      "version": "12.7.1",
       "author": {
         "name": "Manavarya Singh"
       },
@@ -17,12 +17,20 @@
       "tags": [
         "design-system",
         "design-tokens",
-        "css",
+        "dtcg",
         "tailwind",
+        "shadcn",
+        "figma",
         "typography",
         "colors",
-        "web-scraping"
+        "motion",
+        "grade",
+        "battle",
+        "remix",
+        "pack",
+        "mcp",
+        "playwright"
       ]
     }
   ]
-}
+}

package/.claude-plugin/plugin.json

@@ -1,24 +1,35 @@
 {
-  "name": "design-extract",
-  "description": "Extract the complete design language from any website. Produces W3C design tokens, AI-optimized markdown, Tailwind config, and CSS custom properties.",
-  "version": "1.0.0",
+  "name": "designlang",
+  "description": "Extract any website's design language and ship it. Seven slash commands \u2014 /extract, /grade, /battle, /remix, /pack, /theme-swap, /brand \u2014 wrap the designlang CLI to pull DTCG tokens, Tailwind/shadcn/Figma vars, motion + voice, generate shareable graded report cards, head-to-head battle pages, six-vocabulary remixes, downloadable design-system bundles, OKLCH-correct theme recolouring, and full editorial brand-guidelines books.",
+  "version": "12.7.1",
   "author": {
     "name": "Manavarya Singh",
     "url": "https://github.com/Manavarya09"
   },
-  "homepage": "https://github.com/Manavarya09/design-extract",
+  "homepage": "https://designlang.app",
   "repository": "https://github.com/Manavarya09/design-extract",
   "license": "MIT",
   "keywords": [
     "design-system",
     "design-tokens",
     "design-language",
-    "css",
+    "dtcg",
     "tailwind",
+    "shadcn",
+    "figma-variables",
+    "css",
     "playwright",
     "extraction",
     "colors",
-    "typography"
+    "typography",
+    "motion",
+    "grade",
+    "battle",
+    "remix",
+    "pack",
+    "claude-plugin",
+    "mcp"
   ],
-  "skills": "./skills/"
-}
+  "skills": "./skills/",
+  "commands": "./commands/"
+}

package/CHANGELOG.md

@@ -1,5 +1,199 @@
 # Changelog
 
+## [12.7.1] — 2026-05-09
+
+**Brand book — visual polish pass.**
+
+The v12.7.0 brand book had a real-data deficit: the cover used a generic
+grade-coloured accent strip, every section opened with a philosophical
+lede ("the felt pace of an interface", "form follows feeling"), and
+components were a metadata table instead of a real mock. This pass
+replaces all of that with the extracted values themselves.
+
+Changes:
+
+- **Cover** now leads with the brand's actual primary as a full-bleed
+  band (auto-detected, falls back through secondary/accent/most-used).
+  Asymmetric layout — band + label + hex above, host name in massive
+  serif below.
+- **Lede paragraphs replaced with one-line data summaries.**
+  "1 primary · 1 secondary · 1 accent · 27 neutrals · 88 total" instead
+  of "Brand colours carry meaning. Neutrals carry structure."
+- **Type specimen** now uses real headlines extracted from the site's
+  voice (`design.voice.sampleHeadings`). Falls back to a single neutral
+  pangram only when those are absent. The recycled aphorisms ("quiet
+  authority of restraint", "form follows feeling") are gone.
+- **Colour chapter** — primary at full-width hero card, secondary +
+  accent at half-width below, neutrals as a flush horizontal strip,
+  full palette grid below. Hex labels render *inside* the swatch in
+  high-contrast text (auto black/white).
+- **Components chapter** — renders an actual primary + secondary
+  button using the extracted brand colour and radius, plus a card
+  mockup using extracted surface + text colours. Metadata table moved
+  below the visual mock.
+- **Accessibility chapter** — failing pairs render as actual stacked
+  colour blocks (foreground text on background with ratio inline),
+  not a pure table. Big score number on top.
+- **Tokens chapter** — code blocks now have a header bar with the
+  language label and target filename.
+- **"How to use"** trimmed from six rules of thumb to four punchy
+  ones, drops the "rule of thumb" framing.
+- **Layout** — section padding moved into the wrap (no more gutter
+  around the hero band), TOC now sits on a tinted sub-paper background,
+  chapter headers are thinner with a bottom rule.
+
+Same 13 chapters, same public API. No breaking changes.
+
+378/378 tests pass (one assertion updated for the new lowercase
+"Brand guidelines" cover label).
+
+## [12.7.0] — 2026-05-09
+
+**Brand book — full editorial design-guidelines document for any URL.**
+
+\`designlang brand <url>\` produces a self-contained, print-ready HTML
+"brand guidelines book" that documents every dimension of an extracted
+design system. Cover, table of contents, 13 chapters: about, logo,
+colour, typography, spacing, shape, iconography, motion, components,
+voice, accessibility, tokens, how-to-use. Editorial layout, dark-mode
+toggle, smooth-scroll TOC, drop-in code blocks per stack.
+
+\`\`\`bash
+npx designlang brand stripe.com
+\`\`\`
+
+\`\`\`
+Brand book · 54 tokens · 3 fonts · grade B · https://stripe.com
+✓ stripe-com.brand.html
+✓ stripe-com.brand.md
+✓ stripe-com.brand.json
+\`\`\`
+
+### Why this is different from \`pack\`, \`grade\`, and \`design-language.md\`
+
+| Output | Audience | Format |
+|---|---|---|
+| \`pack\` (v12.4) | Devs picking up a design system | Directory of files (tokens, components, Storybook, starter) |
+| \`grade\` (v12.1) | Audit / share | Single audit page with score + verdict |
+| \`design-language.md\` | LLMs | AI-optimized markdown (data-dense) |
+| **\`brand\` (v12.7)** | **Designers + handoff** | **Editorial brand-guidelines book — readable, print-ready, hand-off-ready** |
+
+### Added
+
+- New CLI command: \`designlang brand <url> [-o] [-n] [--format] [--open]\`.
+- New formatter \`src/formatters/brand-book.js\` exporting \`formatBrandBook\`
+  (HTML book) and \`formatBrandBookMarkdown\` (terse markdown summary).
+- 13 chapters with editorial typography (Instrument Serif display + Inter
+  body), generous whitespace, smooth-scroll anchors, dark-mode toggle,
+  print stylesheet with page breaks at chapter boundaries.
+- Per-colour section: large swatch + HEX/RGB/HSL/usage grid for brand
+  colours, mini-grid for neutrals + full palette.
+- Per-token section: drop-in code blocks for CSS variables, Tailwind
+  config, with cross-reference to \`pack\` for the full bundle.
+- Closing "How to use" chapter with six rules of thumb (hierarchy of
+  brand colour, two-family discipline, snap-to-scale spacing, tight
+  radius set, motion as feedback, accessibility as hard constraint).
+- 7 new tests covering chapter coverage, host/colour/font rendering,
+  XSS escaping, sparse-design fallback, and mixed-shape component
+  anatomy (the bug that broke the first integration — slots / variants
+  arrive as objects, strings, or arrays from the extractor).
+
+### Plugin
+
+\`/brand\` is the 7th slash command in the Claude Code plugin
+(\`/extract\`, \`/grade\`, \`/battle\`, \`/remix\`, \`/pack\`, \`/theme-swap\`,
+\`/brand\`). \`.claude-plugin/plugin.json\` and \`marketplace.json\`
+bumped to 12.7.0.
+
+## [12.6.0] — 2026-05-06
+
+**Theme-swap — recolour any extracted design around your brand primary.**
+
+\`designlang theme-swap <url> --primary <hex>\` takes the existing
+extraction and rotates the brand palette around a new primary while
+preserving everything else: type scale, spacing rhythm, neutrals, motion,
+component anatomy. Closes
+[#57](https://github.com/Manavarya09/design-extract/issues/57).
+
+\`\`\`bash
+npx designlang theme-swap stripe.com --primary "#ff4800"
+\`\`\`
+
+\`\`\`
+#533afd → #ff4800 · 91 colours · https://stripe.com
+Hue shift: 118.5° · neutrals preserved · type/spacing/motion untouched
+
+✓ stripe-com-themeswap-ff4800.themeswap.html
+✓ stripe-com-themeswap-ff4800.themeswap.md
+✓ stripe-com-themeswap-ff4800.themeswap.json
+✓ stripe-com-themeswap-ff4800.themeswap.tokens.json
+\`\`\`
+
+### Added
+
+- New CLI command: \`designlang theme-swap <url> --primary <hex>\`
+  with \`--from\`, \`-o\`, \`-n\`, \`--format\`, \`--open\` flags.
+- New module \`src/recolor.js\` exporting \`recolorDesign(design, opts)\`.
+  Operates in OKLCH so perceptual lightness stays constant — only hue
+  rotates. Auto-detects the source primary; pin it with \`--from\`.
+  Neutrals (chroma < 0.04 in OKLCH) are explicitly preserved so body
+  text, surfaces, and rule lines stay readable.
+- New formatter \`src/formatters/theme-swap.js\` exporting
+  \`formatThemeSwap\` (HTML side-by-side preview) and
+  \`formatThemeSwapMarkdown\`.
+- New OKLCH inverse helpers in \`src/utils/color-gamut.js\`:
+  \`srgbToOklab\`, \`srgbToOklch\`, \`hexToOklch\`, \`oklchToHex\` —
+  with chroma fallback for out-of-gamut colours.
+- The recoloured design is fed through every existing emitter (DTCG,
+  Tailwind, shadcn, Figma vars, CSS vars), so the swap propagates
+  for free.
+- 10 new tests covering primary-pinning, neutral preservation,
+  hue rotation, error paths, \`--from\` override, HTML/markdown shapes,
+  and XSS escaping.
+
+### Why
+
+People keep asking *"what would Stripe look like in our brand colors?"*.
+\`theme-swap\` answers it in 30 seconds. Bridges \`remix\` (full-vocab
+restyle) and \`apply\` (token write-through to a project).
+
+## [12.5.0] — 2026-05-06
+
+**Claude Code plugin — five slash commands wrapping the CLI.**
+
+designlang is now a first-class Claude Code plugin. Drop it into any
+session and every CLI verb becomes a slash command:
+
+\`\`\`bash
+/plugin install Manavarya09/design-extract
+\`\`\`
+
+| Command | What it does |
+|---|---|
+| \`/extract <url>\` | Full extraction → DTCG, Tailwind, Figma, motion, voice |
+| \`/grade <url>\` | Shareable HTML Design Report Card (+ \`--badge\`) |
+| \`/battle <urlA> <urlB>\` | Head-to-head graded battle card |
+| \`/remix <url> --as <vocab>\` | Restyle in 6 vocabularies |
+| \`/pack <url>\` | Bundle every output into one design-system directory |
+
+### Added
+
+- \`commands/extract.md\`, \`commands/grade.md\`, \`commands/battle.md\`,
+  \`commands/remix.md\`, \`commands/pack.md\` — five slash-command
+  manifests with \`description\` + \`argument-hint\` frontmatter and prompt
+  bodies that wrap the CLI and surface tight summaries.
+- Refreshed \`.claude-plugin/plugin.json\` (was stale at v1.0.0) — name
+  bumped to \`designlang\`, description rewritten around all v12 surfaces,
+  added \`commands\` directory pointer + expanded keywords.
+- Refreshed \`.claude-plugin/marketplace.json\` — same updates plus
+  marketplace tags.
+- New README section "Claude Code plugin" documenting install + the
+  five slash commands. Existing skills-ecosystem section retained for
+  Cursor / Codex / 40+ other agents.
+
+No CLI behavior change. The slash commands are pure wrappers — they
+shell out to \`npx designlang …\` and read the same output files.
+
 ## [12.4.0] — 2026-05-05
 
 **Pack — one command, one polished design-system bundle.**

package/README.md

@@ -26,6 +26,8 @@ It also goes where extractors don't: **layout patterns**, **responsive behavior
 
 ```bash
 npx designlang https://stripe.com                      # extract everything
+npx designlang brand stripe.com                        # full brand-guidelines book (13 chapters)  ← v12.7
+npx designlang theme-swap stripe.com --primary "#ff4800"  # recolour around your brand        ← v12.6
 npx designlang pack stripe.com                         # one polished design-system directory ← v12.4
 npx designlang remix stripe.com --as cyberpunk         # restyle in another vocabulary       ← v12.3
 npx designlang remix stripe.com --all                  # emit all 6 vocabs at once           ← v12.3
@@ -131,7 +133,9 @@ designlang mcp                              # stdio MCP server for Cursor / Clau
 | Battle (v12.2) | `designlang battle <A> <B>` | Head-to-head graded battle card with verdict, dimension table, palette comparison |
 | Badge (v12.2) | `designlang grade --badge` | Shields.io-style SVG badge — `design · B · 87` — drop into any README. Live endpoint: `designlang.app/badge/<host>.svg` |
 | Remix (v12.3) | `designlang remix <url> --as <vocab>` | Restyle the audited page in another vocabulary (brutalist / swiss / art-deco / cyberpunk / soft-ui / editorial). `--all` emits all 6 |
-| Pack (NEW v12.4) | `designlang pack <url>` | Bundle every output (tokens / components / Storybook / starter / prompts) into one polished design-system directory |
+| Pack (v12.4) | `designlang pack <url>` | Bundle every output (tokens / components / Storybook / starter / prompts) into one polished design-system directory |
+| Theme-swap (v12.6) | `designlang theme-swap <url> --primary <hex>` | Recolour the extracted design around a new brand primary. OKLCH hue rotation, neutrals preserved, type/spacing/motion untouched |
+| Brand book (NEW v12.7) | `designlang brand <url>` | Full editorial brand-guidelines document (13 chapters: cover, about, logo, colour, type, spacing, shape, iconography, motion, components, voice, a11y, tokens, how-to-use). Print-ready, dark-mode toggle, hand-off-ready |
 | Watch | `designlang watch <url>` | Monitor for design changes on interval |
 | Diff | `designlang diff <A> <B>` | Compare two sites (MD + HTML) |
 | Multi-brand | `designlang brands <urls...>` | N-site comparison matrix |
@@ -188,6 +192,8 @@ Commands:
   battle <urlA> <urlB>              Head-to-head graded battle card (--format html|md|json|all, --open)
   remix <url>                       Restyle in another vocabulary (--as brutalist|swiss|art-deco|cyberpunk|soft-ui|editorial, --all, --list, --open)
   pack <url>                        Bundle every output into one design-system directory (--with-clone, --open)
+  theme-swap <url> --primary <hex>  Recolour around a new brand primary (--from, --format html|md|json|tokens|all, --open)
+  brand <url>                       Generate a full editorial brand-guidelines book (--format html|md|json|all, --open)
   watch <url>                       Monitor for design changes on interval
   diff <urlA> <urlB>                Compare two sites' design languages
   brands <urls...>                  Multi-brand comparison matrix
@@ -235,16 +241,37 @@ designlang ships surfaces beyond the CLI:
 | **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). |
+| **Claude Code plugin** | [`.claude-plugin/`](.claude-plugin/) | Five slash commands inside Claude Code — `/extract`, `/grade`, `/battle`, `/remix`, `/pack`. |
 
-## Agent Skill
+## Claude Code plugin
 
-Works with **Claude Code, Cursor, Codex, and 40+ AI coding agents** via the skills ecosystem:
+Drop designlang straight into Claude Code as a plugin. Every CLI command becomes a slash command:
+
+```bash
+/plugin install Manavarya09/design-extract
+```
+
+Then inside any Claude Code session:
+
+| Slash command | What it does |
+|---|---|
+| `/extract <url>` | Full extraction → DTCG tokens, Tailwind, Figma vars, motion, voice |
+| `/grade <url>` | Shareable HTML "Design Report Card" (+ `--badge` for an SVG) |
+| `/battle <urlA> <urlB>` | Head-to-head graded battle card |
+| `/remix <url> --as <vocab>` | Restyle in brutalist / swiss / art-deco / cyberpunk / soft-ui / editorial |
+| `/pack <url>` | Bundle every output into one design-system directory |
+
+Manifest: [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) · marketplace: [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) · commands: [`commands/`](commands/) · skills: [`skills/`](skills/).
+
+## Agent skill (other ecosystems)
+
+Works with **Cursor, Codex, and 40+ AI coding agents** via the skills ecosystem:
 
 ```bash
 npx skills add Manavarya09/design-extract
 ```
 
-In Claude Code, use `/extract-design <url>`.
+In Cursor / Codex / etc., use `/extract-design <url>`.
 
 ## Website
 

package/SUPPORT.md

@@ -0,0 +1,22 @@
+# Support
+
+Need help with **designlang**?
+
+- **Bugs** — open an [issue](https://github.com/Manavarya09/design-extract/issues/new/choose) with steps to reproduce and the URL you were extracting.
+- **Feature requests** — see the [open roadmap](https://github.com/Manavarya09/design-extract/issues?q=is%3Aopen+label%3Aroadmap) (issues #56–#70). Feel free to claim one with a comment, or open a new one.
+- **Security issues** — see [SECURITY.md](SECURITY.md). Please report privately.
+- **Questions** — start a [Discussion](https://github.com/Manavarya09/design-extract/discussions) or DM [@manavaryasingh](https://github.com/Manavarya09).
+
+## Surfaces
+
+| Surface | Where to ask |
+|---|---|
+| CLI (`npx designlang`) | issue with the failing command + Node version |
+| Claude Code plugin | issue tagged `claude-code` |
+| MCP server (`designlang mcp`) | issue tagged `mcp` |
+| Website (designlang.app) | issue tagged `website` |
+| VS Code / Raycast / Figma / Chrome extensions | issue tagged with the surface name |
+
+## Response time
+
+Best effort within 5 business days. PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

package/bin/design-extract.js

@@ -50,6 +50,9 @@ 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 { nameFromUrl } from '../src/utils.js';
 
 function validateUrl(url) {
@@ -1225,6 +1228,184 @@ 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);
+    }
+  });
+
 // ── 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.)