designlang 12.7.1 → 12.9.0

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
     {
       "name": "designlang",
       "source": "./",
-      "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",
+      "description": "Eight 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), /pair (fuse two designs across configurable axes \u2014 colours from one site, typography from another).",
+      "version": "12.9.0",
       "author": {
         "name": "Manavarya Singh"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "description": "Extract any website's design language and ship it. Eight slash commands \u2014 /extract, /grade, /battle, /remix, /pack, /theme-swap, /brand, /pair \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, full editorial brand-guidelines books, and design crossovers between two sites.",
+  "version": "12.9.0",
   "author": {
     "name": "Manavarya Singh",
     "url": "https://github.com/Manavarya09"

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## [12.9.0] — 2026-05-11
+
+**Extraction quality pass — the core MVP, fixed.**
+
+Eight features rode on top of the same extractor. This release fixes
+four real defects in that extractor — visible across grade, battle,
+remix, pack, theme-swap, brand, and pair without anyone having to
+re-run the downstream code.
+
+### Fixed
+
+- **Cluster representative bug** in \`clusterColors()\`. Before: the first-
+  encountered colour seeded each cluster, so a sparsely-used pale shade
+  could become the canonical hex for a cluster that mostly held a vivid
+  brand colour. The brand-book primary slot was reading lavender for
+  Stripe instead of \`#533afd\`. Fixed: representative is now the
+  most-counted member of the cluster.
+- **Spacing base detection** missed common production scales. Before:
+  only \`[2, 4, 6, 8]\` were tried as base candidates, so Bootstrap-style
+  base-5 sites and base-7/10/12 sites returned \`base: null\`. Fixed:
+  expanded to \`[2, 4, 5, 6, 7, 8, 10, 12, 16]\` with a small bonus for
+  4 and 8 to keep results stable for the production-default sites.
+- **Typography noise**. Before: generic CSS stacks (\`sans-serif\`,
+  \`monospace\`, \`system-ui\`, \`inherit\`), OS UI fonts (\`-apple-system\`),
+  and icon fonts (Material Icons, Font Awesome, Lucide, Tabler, etc.)
+  polluted the \`families\` list, making the brand book mistakenly
+  document an icon font as the brand's body family. Fixed: explicit
+  generic + icon-family filter at the source.
+
+### Added
+
+- **\`primary.confidence\`** (0–1) on \`design.colors.primary\`. Computed
+  from the score gap between rank 1 and rank 2 brand candidates — a
+  runaway leader scores 1.0; a near-tie scores 0.3. Downstream
+  consumers (brand book, grade, theme-swap) can surface uncertainty
+  warnings on low-confidence extractions.
+- **\`asList(v)\`** helper exported from \`src/utils.js\`. Coerces
+  anything-shaped input (array / object / comma-string / scalar) into
+  a clean string array. Consolidates the per-formatter ad-hoc
+  defenses (brand-book, pair, pack all had their own copies).
+
+### Why
+
+Verified live on \`stripe.com\`:
+
+- Pre-v12.9: primary slot showed a lavender shade, multiple icon-font
+  entries in families, spacing base often \`null\`.
+- v12.9: primary \`#533afd\` (count 899, confidence 0.59), \`families:
+  ['sohne-var']\`, spacing base detected correctly.
+
+No new dependencies, no schema breaks, no public-API changes. 396/396
+tests pass (6 new — base-5 + base-6 detectScale, cluster representative
+correctness, generic-family filter, icon-family filter, asList shape
+coercion).
+
+## [12.8.0] — 2026-05-10
+
+**Pair — fuse two extracted designs into a single hybrid identity.**
+
+\`designlang pair <urlA> <urlB>\` extracts both sites in parallel, then
+mixes their design systems along seven configurable axes (colours,
+typography, spacing, shape, motion, voice, components). Default split is
+"visuals from A, voice + type + components from B" — i.e. the most
+distinctive crossover. Override any axis with \`--<axis>-from a|b\`.
+
+\`\`\`bash
+npx designlang pair stripe.com linear.app
+\`\`\`
+
+\`\`\`
+stripe.com × linear.app
+  A  Colours      · stripe.com
+  B  Typography   · linear.app
+  A  Spacing      · stripe.com
+  A  Shape        · stripe.com
+  A  Motion       · stripe.com
+  B  Voice        · linear.app
+  B  Components   · linear.app
+
+✓ stripe-com-x-linear-app.pair.html
+✓ stripe-com-x-linear-app.pair.md
+✓ stripe-com-x-linear-app.pair.json
+\`\`\`
+
+### Added
+
+- New CLI command: \`designlang pair <urlA> <urlB>\` with \`--colors-from\`,
+  \`--typography-from\`, \`--spacing-from\`, \`--shape-from\`, \`--motion-from\`,
+  \`--voice-from\`, \`--components-from\`, plus \`--brand\` to also emit a
+  full brand-guidelines book of the fused identity.
+- New module \`src/fuse.js\` — \`fuseDesigns(a, b, opts)\` deep-clones both
+  inputs, picks each axis from the requested source, synthesises a
+  pair-specific meta URL (\`pair://<a>-x-<b>\`), and strips score /
+  cssHealth (those belong to the source extractions, not the fusion).
+- New formatter \`src/formatters/pair.js\` — editorial pair card with a
+  three-card crossover (A · B · Fused), per-axis source matrix table,
+  and a fused specimen using the *real headline* from whichever site
+  contributed the voice axis.
+- Plus \`formatPairMarkdown\` for diff-friendly summaries.
+- 12 new tests covering default split, per-axis overrides, score-stripping,
+  meta synthesis, immutability of source designs, HTML rendering, voice
+  carry-through to the specimen, XSS escaping, and missing-input errors.
+
+### Plugin
+
+\`/pair\` is the 8th slash command in the Claude Code plugin
+(\`/extract\`, \`/grade\`, \`/battle\`, \`/remix\`, \`/pack\`, \`/theme-swap\`,
+\`/brand\`, \`/pair\`). Plugin manifests bumped to 12.8.0.
+
+### Why
+
+\`battle\` answers "which is better"; \`pair\` answers "what would the
+intersection look like". Same parallel extraction, opposite operation.
+Pure logic, no LLM, no new dependencies.
+
 ## [12.7.1] — 2026-05-09
 
 **Brand book — visual polish pass.**

package/README.md

@@ -26,6 +26,7 @@ It also goes where extractors don't: **layout patterns**, **responsive behavior
 
 ```bash
 npx designlang https://stripe.com                      # extract everything
+npx designlang pair stripe.com linear.app              # fuse two designs (visuals A × voice B)    ← v12.8
 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
@@ -135,7 +136,8 @@ designlang mcp                              # stdio MCP server for Cursor / Clau
 | 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 (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 |
+| Brand book (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 |
+| Pair (NEW v12.8) | `designlang pair <urlA> <urlB>` | Fuse two designs across 7 axes (colours/type/spacing/shape/motion/voice/components). Defaults to "visuals from A, voice + type from B". `--brand` also emits a brand book of the fused identity |
 | 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 |
@@ -194,6 +196,7 @@ Commands:
   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)
+  pair <urlA> <urlB>                Fuse two designs across 7 axes (--colors-from, --typography-from, --spacing-from, --shape-from, --motion-from, --voice-from, --components-from, --brand)
   watch <url>                       Monitor for design changes on interval
   diff <urlA> <urlB>                Compare two sites' design languages
   brands <urls...>                  Multi-brand comparison matrix

package/bin/design-extract.js

@@ -53,6 +53,8 @@ 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) {
@@ -1406,6 +1408,118 @@ program
     }
   });
 
+// ── 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "12.7.1",
+  "version": "12.9.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": {

package/src/extractors/colors.js

@@ -106,8 +106,29 @@ export function extractColors(computedStyles) {
     return pct < 0.05 && c.members.some(m => m.contexts.has('background'));
   }) || ranked.find(c => c !== primary && c !== secondary) || null;
 
+  // Primary detection confidence — useful signal for downstream consumers
+  // that may want to warn the user when extraction is uncertain (e.g. a
+  // monochrome site where there's no clear brand colour). We compute it
+  // from the score gap between rank 1 and rank 2: a runaway leader is
+  // confident, a near-tie is not.
+  let primaryConfidence = null;
+  if (primary) {
+    const top = brandScore(primary);
+    const next = ranked[1] ? brandScore(ranked[1]) : 0;
+    if (top <= 0) {
+      primaryConfidence = 0;
+    } else if (next <= 0) {
+      primaryConfidence = primary.interactiveBg > 0 ? 1 : 0.6;
+    } else {
+      const gap = (top - next) / top;
+      // Anchor: gap >= 0.5 → 1.0 (runaway). gap 0 → 0.3 (near-tie).
+      primaryConfidence = Math.max(0.3, Math.min(1, 0.3 + gap * 1.4));
+    }
+    primaryConfidence = Math.round(primaryConfidence * 100) / 100;
+  }
+
   return {
-    primary: primary ? { hex: primary.hex, rgb: primary.representative, hsl: rgbToHsl(primary.representative), count: primary.count } : null,
+    primary: primary ? { hex: primary.hex, rgb: primary.representative, hsl: rgbToHsl(primary.representative), count: primary.count, confidence: primaryConfidence } : null,
     secondary: secondary ? { hex: secondary.hex, rgb: secondary.representative, hsl: rgbToHsl(secondary.representative), count: secondary.count } : null,
     accent: accent ? { hex: accent.hex, rgb: accent.representative, hsl: rgbToHsl(accent.representative), count: accent.count } : null,
     neutrals: neutrals.map(c => ({ hex: c.hex, rgb: c.representative, hsl: rgbToHsl(c.representative), count: c.count })),

package/src/extractors/typography.js

@@ -1,14 +1,49 @@
 import { parseCSSValue } from '../utils.js';
 
+// Filter set for fonts that aren't part of the site's brand typography:
+// generic CSS fallbacks, OS UI stacks, icon fonts, and inherited "no
+// declaration" values. These slipped into families[] before and polluted
+// the brand book + grade summary.
+const GENERIC_FAMILIES = new Set([
+  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
+  'system-ui', 'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded',
+  'inherit', 'initial', 'unset', 'revert', 'auto', '-apple-system',
+  'blinkmacsystemfont', 'apple-system',
+]);
+const ICON_FAMILY_RE = /^(material[-\s]?icons|font\s?awesome|fa-?solid|fa-?regular|fa-?brands|ionicons|glyphicons|bootstrap-icons|remixicon|feather|tabler-icons|lucide)/i;
+
+function normaliseFamily(raw) {
+  if (!raw) return null;
+  // Strip quotes + take the first stack member (sites declare e.g.
+  // `"Inter", "Helvetica Neue", sans-serif` — only the first is the
+  // *intended* family).
+  const first = String(raw).replace(/["']/g, '').split(',')[0].trim();
+  if (!first) return null;
+  return first;
+}
+
+function isMeaningfulFamily(name) {
+  if (!name) return false;
+  const lower = name.toLowerCase();
+  if (GENERIC_FAMILIES.has(lower)) return false;
+  if (ICON_FAMILY_RE.test(name)) return false;
+  // Single-character or all-symbol names are extraction noise.
+  if (name.length < 2) return false;
+  if (!/[a-z]/i.test(name)) return false;
+  return true;
+}
+
 export function extractTypography(computedStyles) {
   const familyCount = new Map();
   const sizeEntries = [];
   const weightCount = new Map();
 
   for (const el of computedStyles) {
-    // Font families
-    const family = el.fontFamily?.replace(/["']/g, '').split(',')[0]?.trim();
-    if (family) familyCount.set(family, (familyCount.get(family) || 0) + 1);
+    // Font families — normalised first-of-stack, with noise filtered out.
+    const family = normaliseFamily(el.fontFamily);
+    if (family && isMeaningfulFamily(family)) {
+      familyCount.set(family, (familyCount.get(family) || 0) + 1);
+    }
 
     // Font sizes
     const sizeVal = parseCSSValue(el.fontSize);

package/src/formatters/pair.js

@@ -0,0 +1,331 @@
+// designlang pair — editorial preview HTML for a fused design.
+//
+// Shows both source sites + the fused result side-by-side, with a clear
+// matrix of which axis came from which source. Companion to the brand
+// book, which the same fused design also feeds into.
+
+const FONT_DISPLAY = 'Instrument Serif';
+const FONT_BODY = 'Inter';
+const FONT_MONO = 'JetBrains Mono';
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function host(url) {
+  try { return new URL(url).hostname; } catch { return String(url || ''); }
+}
+
+function familyName(f) {
+  if (!f) return '';
+  if (typeof f === 'string') return f;
+  return f.name || f.family || '';
+}
+
+function paletteStrip(design, n = 10) {
+  const all = (design?.colors?.all || []).slice(0, n);
+  if (!all.length) return '<span class="muted">—</span>';
+  return all.map(c => `<span class="chip" style="background:${esc(c?.hex || c)}" title="${esc(c?.hex || c)}"></span>`).join('');
+}
+
+function primaryHex(design) {
+  return design?.colors?.primary?.hex
+    || (design?.colors?.all || []).find(c => c?.hex)?.hex
+    || '#141414';
+}
+
+function topFamily(design) {
+  const f = (design?.typography?.families || [])[0];
+  return familyName(f) || 'system-ui';
+}
+
+function topHeading(design) {
+  const headings = (design?.voice?.sampleHeadings || []).filter(h => typeof h === 'string' && h.length > 4 && h.length < 120);
+  return headings[0] || 'Quick brown fox jumps over the lazy dog.';
+}
+
+export function formatPair(designA, designB, fused, summary, opts = {}) {
+  if (!designA || !designB || !fused) throw new Error('formatPair: all three designs are required');
+
+  const hostA = host(designA.meta?.url);
+  const hostB = host(designB.meta?.url);
+  const axes = summary?.axes || fused.fusedAxes || {};
+  const accent = primaryHex(fused);
+
+  const date = new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+  const ogTitle = `${hostA} × ${hostB} · designlang pair`;
+  const ogDesc = `Fused design system — ${hostA} crossed with ${hostB} along ${Object.keys(axes).length} axes.`;
+
+  // Six axes drive the matrix. We render a 6-row table so the viewer
+  // can see at a glance which dimension came from which source.
+  const axisLabels = [
+    ['colors',     'Colour'],
+    ['typography', 'Typography'],
+    ['spacing',    'Spacing'],
+    ['shape',      'Shape'],
+    ['motion',     'Motion'],
+    ['voice',      'Voice'],
+    ['components', 'Components'],
+  ];
+
+  const sampleHead = topHeading(fused);
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(ogTitle)}</title>
+<meta name="description" content="${esc(ogDesc)}">
+<meta property="og:title" content="${esc(ogTitle)}">
+<meta property="og:description" content="${esc(ogDesc)}">
+<meta property="og:type" content="article">
+<meta name="twitter:card" content="summary_large_image">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=${encodeURIComponent(FONT_DISPLAY)}&family=${encodeURIComponent(FONT_BODY)}:wght@400;500;600&family=${encodeURIComponent(FONT_MONO)}:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --paper: #f6f3ec;
+    --paper-2: #efebe1;
+    --ink: #131313;
+    --ink-soft: #555048;
+    --ink-faint: #8a8579;
+    --rule: #e0dccf;
+    --accent: ${esc(accent)};
+    --display: '${FONT_DISPLAY}', 'Times New Roman', serif;
+    --body: '${FONT_BODY}', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    --mono: '${FONT_MONO}', ui-monospace, 'SF Mono', monospace;
+  }
+  [data-theme="dark"] {
+    --paper: #0d0c0a;
+    --paper-2: #15140f;
+    --ink: #ece8de;
+    --ink-soft: #9d978a;
+    --ink-faint: #5b574e;
+    --rule: #292621;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body { background: var(--paper); color: var(--ink); font-family: var(--body); font-size: 16px; line-height: 1.55; -webkit-font-smoothing: antialiased; transition: background .25s, color .25s; }
+  a { color: var(--ink); border-bottom: 1px solid var(--rule); padding-bottom: 1px; text-decoration: none; }
+  a:hover { border-color: var(--ink); }
+  code { font-family: var(--mono); font-size: .92em; }
+  .muted { color: var(--ink-soft); }
+
+  .wrap { max-width: 980px; margin: 0 auto; padding: 56px 40px 96px; }
+  @media (max-width: 640px) { .wrap { padding: 32px 22px 64px; } }
+
+  .topbar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 56px; font-size: 13px; }
+  .brand { font-family: var(--display); font-size: 22px; }
+  .brand a { border-bottom: 1px solid var(--rule); }
+  .topbar nav { display: flex; gap: 18px; align-items: center; color: var(--ink-soft); }
+  .theme-btn { background: transparent; border: 1px solid var(--rule); color: var(--ink-soft); font-size: 11px; padding: 6px 12px; border-radius: 999px; cursor: pointer; letter-spacing: .12em; text-transform: uppercase; font-family: var(--body); }
+  .theme-btn:hover { color: var(--ink); border-color: var(--ink); }
+
+  .kicker { text-transform: uppercase; letter-spacing: .18em; font-size: 11px; color: var(--ink-soft); font-family: var(--mono); margin: 0 0 14px; }
+  h1.title { font-family: var(--display); font-weight: 400; font-size: clamp(40px, 6vw, 76px); line-height: 1.02; margin: 0 0 36px; letter-spacing: -.01em; }
+  h1.title em { font-style: italic; color: var(--ink-soft); padding: 0 .12em; }
+
+  /* — Hero crossover — */
+  .crossover { display: grid; grid-template-columns: 1fr auto 1fr 1fr; gap: 18px; align-items: stretch; padding: 12px 0 56px; border-bottom: 1px solid var(--rule); }
+  @media (max-width: 760px) { .crossover { grid-template-columns: 1fr; } .crossover .arrow { display: none; } }
+  .source-card, .fused-card { padding: 22px 22px 18px; border-radius: 8px; background: var(--paper-2); box-shadow: inset 0 0 0 1px var(--rule); display: flex; flex-direction: column; gap: 14px; min-height: 220px; }
+  .fused-card { background: var(--accent); color: ${/* readable on accent */''}; box-shadow: inset 0 0 0 1px rgba(0,0,0,.08); position: relative; overflow: hidden; }
+  .source-card .lbl, .fused-card .lbl { font-family: var(--mono); font-size: 10px; letter-spacing: .14em; text-transform: uppercase; opacity: .82; }
+  .source-card .host, .fused-card .host { font-family: var(--display); font-size: 24px; line-height: 1.1; word-break: break-all; }
+  .source-card .chips, .fused-card .chips { display: flex; gap: 4px; flex-wrap: wrap; }
+  .chip { width: 18px; height: 18px; border-radius: 3px; box-shadow: inset 0 0 0 1px rgba(0,0,0,.08); flex: 0 0 auto; }
+  .source-card .fam, .fused-card .fam { font-family: var(--mono); font-size: 11px; opacity: .82; }
+  .arrow { font-family: var(--display); font-style: italic; font-size: clamp(22px, 3vw, 36px); color: var(--ink-soft); align-self: center; padding: 0 8px; }
+  .fused-card .lbl, .fused-card .fam, .fused-card .chip { color: white; }
+  .fused-card .host { color: white; }
+
+  /* — Axis matrix — */
+  section { padding: 56px 0; border-bottom: 1px solid var(--rule); }
+  section:last-of-type { border-bottom: 0; }
+  section > h2 { font-family: var(--display); font-weight: 400; font-size: clamp(28px, 3.5vw, 40px); line-height: 1.04; margin: 0 0 8px; letter-spacing: -.005em; }
+  section > h2 + .lead { color: var(--ink-soft); margin: 0 0 28px; max-width: 60ch; }
+
+  .matrix { width: 100%; border-collapse: collapse; font-size: 14px; }
+  .matrix th, .matrix td { padding: 14px 12px; text-align: left; border-bottom: 1px solid var(--rule); vertical-align: middle; }
+  .matrix th { font-family: var(--mono); font-size: 10px; letter-spacing: .12em; text-transform: uppercase; color: var(--ink-faint); border-bottom: 1px solid var(--ink); }
+  .matrix .axis-name { font-family: var(--display); font-size: 18px; }
+  .matrix .src { font-family: var(--mono); font-size: 11px; letter-spacing: .04em; color: var(--ink-soft); }
+  .matrix .src.from-a { color: var(--ink); }
+  .matrix .src.from-b { color: var(--ink); }
+  .matrix .pill { display: inline-block; padding: 3px 8px; border-radius: 999px; font-family: var(--mono); font-size: 10px; letter-spacing: .12em; text-transform: uppercase; border: 1px solid var(--rule); background: var(--paper-2); }
+  .matrix .pill.from-a { border-color: var(--ink-soft); }
+  .matrix .pill.from-b { border-color: var(--accent); color: var(--ink); background: color-mix(in srgb, var(--accent) 14%, var(--paper-2)); }
+
+  /* — Specimen of the fused design — */
+  .specimen { padding: 32px; background: var(--paper-2); border-radius: 8px; box-shadow: inset 0 0 0 1px var(--rule); }
+  .spec-quote { font-family: var(--display); font-weight: 400; font-size: clamp(28px, 4vw, 48px); line-height: 1.05; margin: 0 0 16px; }
+  .spec-meta { font-family: var(--mono); font-size: 11px; text-transform: uppercase; letter-spacing: .14em; color: var(--ink-soft); display: flex; gap: 24px; flex-wrap: wrap; }
+
+  /* — Try the fused button — */
+  .mock-row { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 18px; padding: 18px 0; }
+  .mock-card { padding: 24px; border-radius: 10px; background: var(--paper-2); box-shadow: inset 0 0 0 1px var(--rule); display: flex; flex-direction: column; gap: 14px; align-items: flex-start; }
+  .mock-eyebrow { font-family: var(--mono); font-size: 10px; letter-spacing: .14em; text-transform: uppercase; color: var(--ink-faint); }
+  .mock-title { font-family: var(--display); font-size: 24px; line-height: 1.1; margin: 0; }
+  .mock-cta { font-family: var(--body); font-weight: 500; font-size: 14px; padding: 10px 18px; border-radius: 6px; background: var(--accent); color: white; border: 0; cursor: pointer; }
+
+  /* — Footer — */
+  footer { padding: 48px 0 0; font-size: 13px; color: var(--ink-soft); display: flex; justify-content: space-between; align-items: end; flex-wrap: wrap; gap: 16px; }
+  footer .sig { font-family: var(--display); font-size: 22px; color: var(--ink); }
+  footer .stamp { font-family: var(--mono); font-size: 11px; text-transform: uppercase; letter-spacing: .14em; }
+
+  @media print {
+    body { background: white; color: black; }
+    .topbar nav, .theme-btn { display: none; }
+    section, .crossover { page-break-inside: avoid; border-color: #ddd; }
+  }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <header class="topbar">
+      <div class="brand"><a href="https://designlang.app">designlang</a></div>
+      <nav>
+        <span>Pair</span>
+        <button class="theme-btn" id="themeBtn" type="button">Theme</button>
+      </nav>
+    </header>
+
+    <p class="kicker">Design Pair · ${esc(date)}</p>
+    <h1 class="title">${esc(hostA)} <em>×</em> ${esc(hostB)}</h1>
+
+    <div class="crossover">
+      <div class="source-card">
+        <span class="lbl">A</span>
+        <div class="host">${esc(hostA)}</div>
+        <div class="chips">${paletteStrip(designA)}</div>
+        <div class="fam">${esc(topFamily(designA))}</div>
+      </div>
+      <div class="arrow">×</div>
+      <div class="source-card">
+        <span class="lbl">B</span>
+        <div class="host">${esc(hostB)}</div>
+        <div class="chips">${paletteStrip(designB)}</div>
+        <div class="fam">${esc(topFamily(designB))}</div>
+      </div>
+      <div class="fused-card">
+        <span class="lbl">Fused</span>
+        <div class="host">${esc(hostA)} × ${esc(hostB)}</div>
+        <div class="chips">${paletteStrip(fused)}</div>
+        <div class="fam">${esc(topFamily(fused))}</div>
+      </div>
+    </div>
+
+    <section>
+      <h2>Which axis came from where</h2>
+      <p class="lead">Each row is one dimension of the design system. The pill shows whether the fused design inherited it from <strong>A</strong> (${esc(hostA)}) or <strong>B</strong> (${esc(hostB)}).</p>
+      <table class="matrix">
+        <thead>
+          <tr>
+            <th>Axis</th>
+            <th>Source</th>
+            <th>Inherited</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${axisLabels.map(([key, label]) => {
+            const src = axes[key] || 'a';
+            const sourceHost = src === 'a' ? hostA : hostB;
+            return `
+              <tr>
+                <td class="axis-name">${esc(label)}</td>
+                <td class="src">${esc(sourceHost)}</td>
+                <td><span class="pill from-${src}">From ${src.toUpperCase()}</span></td>
+              </tr>
+            `;
+          }).join('')}
+        </tbody>
+      </table>
+    </section>
+
+    <section>
+      <h2>The fused identity</h2>
+      <p class="lead">Specimen of the merged design — palette + radii from one source, type + voice from the other.</p>
+      <div class="specimen" style="font-family: ${esc(topFamily(fused))}, '${FONT_DISPLAY}', serif;">
+        <p class="spec-quote">${esc(sampleHead)}</p>
+        <div class="spec-meta">
+          <span>Primary · <code>${esc(primaryHex(fused).toUpperCase())}</code></span>
+          <span>Display · <code>${esc(topFamily(fused))}</code></span>
+          <span>Tone · <code>${esc(fused.voice?.tone || 'neutral')}</code></span>
+        </div>
+      </div>
+
+      <div class="mock-row">
+        <div class="mock-card">
+          <span class="mock-eyebrow">Primary action</span>
+          <h4 class="mock-title">Built from the fused tokens</h4>
+          <button type="button" class="mock-cta">Try this style</button>
+        </div>
+        <div class="mock-card">
+          <span class="mock-eyebrow">Run again</span>
+          <h4 class="mock-title">Different axes, different fusion</h4>
+          <code>npx designlang pair ${esc(hostA)} ${esc(hostB)} --type-from a</code>
+        </div>
+      </div>
+    </section>
+
+    <footer>
+      <div>
+        <div class="sig">designlang</div>
+        <div>Re-run: <code>npx designlang pair ${esc(hostA)} ${esc(hostB)}</code></div>
+      </div>
+      <div class="stamp">${esc(date)} · v${esc(opts.version || '')}</div>
+    </footer>
+  </div>
+
+  <script>
+    (function () {
+      var btn = document.getElementById('themeBtn');
+      var saved = null;
+      try { saved = localStorage.getItem('dl-theme'); } catch (e) {}
+      if (saved) document.documentElement.setAttribute('data-theme', saved);
+      btn && btn.addEventListener('click', function () {
+        var cur = document.documentElement.getAttribute('data-theme') === 'dark' ? '' : 'dark';
+        if (cur) document.documentElement.setAttribute('data-theme', cur);
+        else document.documentElement.removeAttribute('data-theme');
+        try { localStorage.setItem('dl-theme', cur); } catch (e) {}
+      });
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+export function formatPairMarkdown(designA, designB, fused, summary) {
+  const hostA = host(designA.meta?.url);
+  const hostB = host(designB.meta?.url);
+  const axes = summary?.axes || fused.fusedAxes || {};
+  const lines = [
+    `# ${hostA} × ${hostB}`,
+    ``,
+    `_Design pair fused by designlang on ${new Date().toISOString().slice(0, 10)}._`,
+    ``,
+    `## Axes`,
+    ``,
+    `| Axis | Source |`,
+    `|---|---|`,
+    `| Colour | ${axes.colors === 'b' ? hostB : hostA} |`,
+    `| Typography | ${axes.typography === 'a' ? hostA : hostB} |`,
+    `| Spacing | ${axes.spacing === 'b' ? hostB : hostA} |`,
+    `| Shape | ${axes.shape === 'b' ? hostB : hostA} |`,
+    `| Motion | ${axes.motion === 'b' ? hostB : hostA} |`,
+    `| Voice | ${axes.voice === 'a' ? hostA : hostB} |`,
+    `| Components | ${axes.components === 'a' ? hostA : hostB} |`,
+    ``,
+    `## Fused identity`,
+    ``,
+    `- Primary: \`${primaryHex(fused)}\``,
+    `- Display: ${topFamily(fused)}`,
+    `- Tone: ${fused.voice?.tone || 'neutral'}`,
+    ``,
+    `---`,
+    `_Re-run: \`npx designlang pair ${hostA} ${hostB}\`_`,
+  ];
+  return lines.join('\n');
+}

package/src/fuse.js

@@ -0,0 +1,154 @@
+// designlang pair — fuse two extracted designs across configurable axes.
+//
+// Picks each dimension from one source or the other so designers can run
+// experiments like "Stripe colours × Linear typography × Vercel motion".
+// Input: two full design objects from extractDesignLanguage(), an axis
+// map, and an output URL/title for branding the fused result.
+//
+// We deep-clone source objects before merging so callers' originals stay
+// intact. The fused design is structurally identical to a normal
+// extraction so every downstream emitter (DTCG, Tailwind, shadcn,
+// Figma, brand-book, pack) works on it untouched.
+
+const AXES = ['colors', 'typography', 'spacing', 'shape', 'motion', 'voice', 'components'];
+
+const DEFAULT_AXES = {
+  colors:     'a',
+  spacing:    'a',
+  shape:      'a',
+  motion:     'a',
+  typography: 'b',
+  voice:      'b',
+  components: 'b',
+};
+
+function host(url) {
+  try { return new URL(url).hostname; } catch { return String(url || ''); }
+}
+
+function clone(x) {
+  return x == null ? x : JSON.parse(JSON.stringify(x));
+}
+
+// Normalise the user's --<axis>-from flags into a single { axis: 'a'|'b' }
+// map. Anything they don't specify falls through to DEFAULT_AXES, which
+// is calibrated for a clean "visual A × voice B" crossover.
+function resolveAxes(opts = {}) {
+  const out = { ...DEFAULT_AXES };
+  for (const axis of AXES) {
+    const flag = opts[`${axis}From`];
+    if (flag === 'a' || flag === 'A') out[axis] = 'a';
+    else if (flag === 'b' || flag === 'B') out[axis] = 'b';
+  }
+  return out;
+}
+
+/**
+ * Fuse two extracted designs along configurable axes.
+ *
+ * @param {object} a — design from extractDesignLanguage(urlA)
+ * @param {object} b — design from extractDesignLanguage(urlB)
+ * @param {object} opts
+ * @param {'a'|'b'} [opts.colorsFrom='a']
+ * @param {'a'|'b'} [opts.typographyFrom='b']
+ * @param {'a'|'b'} [opts.spacingFrom='a']
+ * @param {'a'|'b'} [opts.shapeFrom='a']
+ * @param {'a'|'b'} [opts.motionFrom='a']
+ * @param {'a'|'b'} [opts.voiceFrom='b']
+ * @param {'a'|'b'} [opts.componentsFrom='b']
+ * @returns {object} { design, summary }
+ */
+export function fuseDesigns(a, b, opts = {}) {
+  if (!a || !b) throw new Error('fuseDesigns: both designs are required');
+  const axes = resolveAxes(opts);
+  const pick = (axis, sliceA, sliceB) => clone(axes[axis] === 'a' ? sliceA : sliceB);
+  const src = (axis) => axes[axis] === 'a' ? a : b;
+
+  // Start from a deep clone of A so meta-fields (e.g. raw crawler output)
+  // have a sensible default. Downstream emitters lean heavily on .meta.url
+  // for filenames + titles, so we synthesise a pair-specific URL.
+  const fused = clone(a);
+
+  // Colours — every sub-field in one block (primary, secondary, accent,
+  // neutrals, backgrounds, text, gradients, all). Mixing primary from
+  // one site and neutrals from another tends to produce off-brand greys,
+  // so we keep the whole palette together.
+  fused.colors = pick('colors', a.colors, b.colors);
+
+  // Typography — same logic. Families, scale, weights, headings, body
+  // travel as one unit because the type system is tightly coupled.
+  fused.typography = pick('typography', a.typography, b.typography);
+  // Pull related signals along with the type pick so the brand book
+  // renders coherently (specimen lines lean on voice.sampleHeadings).
+  if (axes.voice === axes.typography) {
+    // already aligned; keep voice-from picked below
+  }
+
+  // Spacing.
+  fused.spacing = pick('spacing', a.spacing, b.spacing);
+  // Layout often co-varies with spacing — move it together.
+  fused.layout = pick('spacing', a.layout, b.layout);
+
+  // Shape — radii + shadows + borders.
+  fused.borders = pick('shape', a.borders, b.borders);
+  fused.shadows = pick('shape', a.shadows, b.shadows);
+
+  // Motion.
+  fused.motion = pick('motion', a.motion, b.motion);
+  fused.animations = pick('motion', a.animations, b.animations);
+
+  // Voice.
+  fused.voice = pick('voice', a.voice, b.voice);
+
+  // Components — anatomy, clusters, library detection.
+  fused.componentAnatomy = pick('components', a.componentAnatomy, b.componentAnatomy);
+  fused.componentClusters = pick('components', a.componentClusters, b.componentClusters);
+  fused.componentLibrary = pick('components', a.componentLibrary, b.componentLibrary);
+  fused.components = pick('components', a.components, b.components);
+
+  // Material language and imagery style track colour by default — they
+  // describe the *visual* feel.
+  fused.materialLanguage = pick('colors', a.materialLanguage, b.materialLanguage);
+  fused.imageryStyle = pick('colors', a.imageryStyle, b.imageryStyle);
+
+  // CSS variables tend to mirror colour + typography. We keep the
+  // variables from whichever source contributed colour, since colour
+  // tokens are the dominant variable family.
+  fused.variables = pick('colors', a.variables, b.variables);
+
+  // Score, accessibility, css-health are *measurements* of the source
+  // sites — they don't apply to the fused design. Strip them so
+  // downstream consumers don't surface stale numbers.
+  fused.score = null;
+  fused.accessibility = src('colors').accessibility ? clone(src('colors').accessibility) : null;
+  fused.cssHealth = null;
+
+  // Synthesise meta. The pair URL is a virtual identifier so emitters
+  // produce non-colliding filenames (e.g. "stripe-x-linear").
+  const hostA = host(a.meta?.url);
+  const hostB = host(b.meta?.url);
+  fused.meta = {
+    ...(a.meta || {}),
+    url: `pair://${hostA}-x-${hostB}`,
+    title: `${hostA} × ${hostB}`,
+    pairedFrom: { a: a.meta?.url || hostA, b: b.meta?.url || hostB },
+    timestamp: new Date().toISOString(),
+    elementCount: (a.meta?.elementCount || 0) + (b.meta?.elementCount || 0),
+    pagesAnalyzed: 1,
+    fusedAxes: axes,
+  };
+  fused.fusedAxes = axes;
+
+  // Drop the raw crawler output — it belongs to a single page and
+  // confuses any consumer that tries to re-derive things from it.
+  delete fused._raw;
+
+  const summary = {
+    a: { url: a.meta?.url, host: hostA },
+    b: { url: b.meta?.url, host: hostB },
+    axes,
+  };
+  return { design: fused, summary };
+}
+
+export { AXES, DEFAULT_AXES };

package/src/utils.js

@@ -188,6 +188,20 @@ export function clusterColors(colors, threshold = 15) {
       clusters.push({ representative: color.parsed, hex: color.hex, members: [color], count: color.count });
     }
   }
+  // The first encountered colour seeded each cluster, but that's order-of-
+  // iteration accident, not signal. Re-pick the representative as the
+  // most-used member of the cluster so downstream consumers (primary
+  // detection, palette display, brand book) get the dominant shade.
+  for (const cluster of clusters) {
+    if (cluster.members.length > 1) {
+      const dominant = cluster.members.reduce(
+        (best, m) => (m.count > best.count ? m : best),
+        cluster.members[0],
+      );
+      cluster.representative = dominant.parsed;
+      cluster.hex = dominant.hex;
+    }
+  }
   return clusters.sort((a, b) => b.count - a.count);
 }
 
@@ -235,13 +249,33 @@ export function nameFromUrl(url) {
 
 export function detectScale(values) {
   if (values.length < 3) return { base: null, scale: values };
-  const candidates = [2, 4, 6, 8];
+  // Expanded candidate set. Real production palettes use 4/8 (Tailwind +
+  // Material), 5 (Bootstrap), 6 (some Apple specs), 7 (rare), 10/12/16
+  // (looser systems). 2 stays as a fallback for icon/component-level
+  // numbers. We give 4 and 8 a small head-start because they win >70%
+  // of the time and were the previous-only choices — keeps results
+  // stable for sites that worked before.
+  const candidates = [2, 4, 5, 6, 7, 8, 10, 12, 16];
+  const bonus = { 4: 0.04, 8: 0.04 };
   let bestBase = null;
   let bestScore = 0;
   for (const base of candidates) {
-    const score = values.filter(v => v > 0 && v % base === 0).length / values.length;
+    const fit = values.filter(v => v > 0 && v % base === 0).length / values.length;
+    const score = fit + (bonus[base] || 0);
     if (score > bestScore) { bestScore = score; bestBase = base; }
   }
   if (bestScore >= 0.6) return { base: bestBase, scale: values };
   return { base: null, scale: values };
 }
+
+// Shared "always-list" coercer for downstream consumers (formatters,
+// pack, brand-book). Different extractors return slot/prop/variant
+// fields as arrays, objects, or comma-separated strings depending on
+// what was detected; this normalises without losing data.
+export function asList(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v.filter(x => x != null);
+  if (typeof v === 'string') return v.split(',').map(s => s.trim()).filter(Boolean);
+  if (typeof v === 'object') return Object.keys(v).filter(k => v[k] !== false && v[k] !== null);
+  return [String(v)];
+}