designlang 12.1.0 → 12.2.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [12.2.0] — 2026-05-02
+
+**Battle cards + design score badges — distribution + virality on top of Grade.**
+
+### Added
+
+- **`designlang battle <urlA> <urlB>`** — head-to-head graded battle card.
+  Single shareable HTML pitting two sites against each other, dimension by
+  dimension, with a verdict line and a per-dimension bar table. Both sites
+  are extracted in parallel. Emits `*.battle.html`, `*.battle.md`, and
+  `*.battle.json`.
+- **`designlang grade --badge`** — also emit `*.grade.svg`, a shields.io-style
+  SVG badge (`design · B · 87`) coloured by letter grade. Drop into any
+  README.
+- **Live badge endpoint** at `https://designlang.app/badge/<host>.svg` (with
+  rewrites from `/badge/<host>` and `/api/badge/<host>`). Reuses the same
+  blob cache the `/api/extract` route writes to, so the first hit warms the
+  cache and every subsequent hit is served from edge cache in ~50ms. 6h
+  fresh / 24h stale-while-revalidate / 7d max — friendly to the GitHub image
+  proxy.
+- New formatters: `src/formatters/battle.js`, `src/formatters/badge.js`,
+  with exports `formatBattle`, `formatBattleMarkdown`, `compareScores`,
+  `formatBadge`, `formatScoreBadge`.
+- 13 new tests (battle markup, score comparison thresholds, SVG escaping,
+  grade-color mapping, missing-score handling).
+
+Why this exists: the v12.1 Grade card was the differentiator. Battle is the
+viral content layer ("Stripe vs Vercel — guess who lost"). The badge is the
+distribution layer — every README that adopts it is a permanent backlink to
+a public grade page.
+
 ## [12.1.0] — 2026-04-29
 
 **Design Report Card — a shareable audit page, generated from any URL.**

package/README.md

@@ -25,10 +25,17 @@ It also goes where extractors don't: **layout patterns**, **responsive behavior
 ## Quick start
 
 ```bash
-npx designlang https://stripe.com           # extract everything
-npx designlang grade https://stripe.com     # shareable HTML report card  ← v12.1
-npx designlang clone https://stripe.com     # working Next.js starter
-npx designlang --full https://stripe.com    # screenshots + responsive + interactions
+npx designlang https://stripe.com                      # extract everything
+npx designlang grade https://stripe.com --badge        # report card + SVG badge  ← v12.2
+npx designlang battle stripe.com vercel.com            # head-to-head graded fight ← v12.2
+npx designlang clone https://stripe.com                # working Next.js starter
+npx designlang --full https://stripe.com               # screenshots + responsive + interactions
+```
+
+Drop a live design-score badge in any README:
+
+```markdown
+![Design Score](https://designlang.app/badge/stripe.com.svg)
 ```
 
 ## Install
@@ -56,6 +63,8 @@ Each run writes 17+ files to `./design-extract-output/`. The headline outputs:
 | `*-prompts/` | Paste-ready prompts for v0, Lovable, Cursor, Claude Artifacts |
 | `*-mcp.json` | Disk-backed MCP server payload |
 | `*-grade.html` | **v12.1** Shareable Design Report Card (letter grade + evidence) |
+| `*-grade.svg` | **v12.2** Shields.io-style design-score badge (drop into any README) |
+| `*-battle.html` | **v12.2** Head-to-head graded battle card from `designlang battle` |
 
 Multi-platform (`--platforms web,ios,android,flutter,wordpress,all`) adds `ios/`, `android/`, `flutter/`, and a WordPress block theme. `--emit-agent-rules` adds Cursor / Claude Code / generic agent rule files.
 
@@ -114,7 +123,9 @@ designlang mcp                              # stdio MCP server for Cursor / Clau
 | Apply | `designlang apply <url>` | Auto-detect framework and write tokens to your project |
 | Clone | `designlang clone <url>` | Generate a working Next.js starter with extracted design |
 | Score | `designlang score <url>` | Rate design quality with visual bar chart breakdown |
-| Grade (NEW v12.1) | `designlang grade <url>` | Generate a shareable HTML "Design Report Card" — letter grade, 8 dimensions, evidence (palette, type, rhythm), strengths + fixes |
+| Grade (v12.1) | `designlang grade <url>` | Shareable HTML "Design Report Card" — letter grade, 8 dimensions, evidence, strengths + fixes |
+| Battle (NEW v12.2) | `designlang battle <A> <B>` | Head-to-head graded battle card with verdict, dimension table, palette comparison |
+| Badge (NEW v12.2) | `designlang grade --badge` | Shields.io-style SVG badge — `design · B · 87` — drop into any README. Live endpoint: `designlang.app/badge/<host>.svg` |
 | 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 |
@@ -167,7 +178,8 @@ Commands:
   apply <url>                       Extract and apply design directly to your project
   clone <url>                       Generate a working Next.js starter from extracted design
   score <url>                       Rate design quality (7 categories, A-F, bar chart)
-  grade <url>                       Generate a shareable HTML Design Report Card (--format html|md|json|all, --open)
+  grade <url>                       Generate a shareable HTML Design Report Card (--format html|md|json|svg|all, --badge, --open)
+  battle <urlA> <urlB>              Head-to-head graded battle card (--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

package/bin/design-extract.js

@@ -46,6 +46,8 @@ import { watchSite } from '../src/watch.js';
 import { diffDarkMode } from '../src/darkdiff.js';
 import { applyDesign } from '../src/apply.js';
 import { formatGrade, formatGradeMarkdown } from '../src/formatters/grade.js';
+import { formatBattle, formatBattleMarkdown } from '../src/formatters/battle.js';
+import { formatScoreBadge } from '../src/formatters/badge.js';
 import { nameFromUrl } from '../src/utils.js';
 
 function validateUrl(url) {
@@ -941,7 +943,8 @@ program
   .description('Generate a shareable Design Report Card (HTML + JSON + Markdown)')
   .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('--format <fmt>', 'output format: html, md, json, svg, all', 'all')
+  .option('--badge', 'also emit *-badge.svg (shields.io-style) — implies adding svg to format')
   .option('--open', 'open the HTML report in the default browser')
   .action(async (url, opts) => {
     if (!url.startsWith('http')) url = `https://${url}`;
@@ -957,6 +960,7 @@ program
       mkdirSync(outDir, { recursive: true });
       const prefix = opts.name || nameFromUrl(url);
       const written = [];
+      const wantSvg = opts.badge || opts.format === 'svg' || opts.format === 'all';
 
       if (opts.format === 'all' || opts.format === 'html') {
         const html = formatGrade(design, { version: PKG_VERSION });
@@ -984,6 +988,12 @@ program
         }, null, 2));
         written.push(p);
       }
+      if (wantSvg) {
+        const svg = formatScoreBadge(s);
+        const p = join(outDir, `${prefix}.grade.svg`);
+        writeFileSync(p, svg);
+        written.push(p);
+      }
 
       spinner.stop();
       const gradeColor = s.grade === 'A' ? chalk.green : s.grade === 'B' ? chalk.cyan : s.grade === 'C' ? chalk.yellow : chalk.red;
@@ -1010,6 +1020,88 @@ program
     }
   });
 
+// ── Battle command — head-to-head graded comparison ────────
+program
+  .command('battle <urlA> <urlB>')
+  .description('Generate a head-to-head graded battle card (HTML + JSON + Markdown)')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: a-vs-b)')
+  .option('--format <fmt>', 'output format: html, md, json, all', 'all')
+  .option('--open', 'open the battle 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(`Auditing ${urlA} and ${urlB} in parallel...`).start();
+    try {
+      const [designA, designB] = await Promise.all([
+        extractDesignLanguage(urlA),
+        extractDesignLanguage(urlB),
+      ]);
+      if (!designA.score || !designB.score) throw new Error('scoring failed for one or both sites');
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const prefix = opts.name || `${nameFromUrl(urlA)}-vs-${nameFromUrl(urlB)}`;
+      const written = [];
+
+      if (opts.format === 'all' || opts.format === 'html') {
+        const html = formatBattle(designA, designB, { version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.battle.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'md') {
+        const md = formatBattleMarkdown(designA, designB);
+        const p = join(outDir, `${prefix}.battle.md`);
+        writeFileSync(p, md);
+        written.push(p);
+      }
+      if (opts.format === 'all' || opts.format === 'json') {
+        const p = join(outDir, `${prefix}.battle.json`);
+        writeFileSync(p, JSON.stringify({
+          a: { url: designA.meta?.url, grade: designA.score.grade, overall: designA.score.overall, scores: designA.score.scores },
+          b: { url: designB.meta?.url, grade: designB.score.grade, overall: designB.score.overall, scores: designB.score.scores },
+          timestamp: new Date().toISOString(),
+        }, null, 2));
+        written.push(p);
+      }
+
+      spinner.stop();
+      const aGrade = designA.score.grade, bGrade = designB.score.grade;
+      const aColor = aGrade === 'A' ? chalk.green : aGrade === 'B' ? chalk.cyan : aGrade === 'C' ? chalk.yellow : chalk.red;
+      const bColor = bGrade === 'A' ? chalk.green : bGrade === 'B' ? chalk.cyan : bGrade === 'C' ? chalk.yellow : chalk.red;
+      console.log('');
+      console.log(`  ${aColor.bold(`${aGrade} · ${designA.score.overall}`)} ${chalk.gray(designA.meta?.url || urlA)}`);
+      console.log(`  ${chalk.gray('vs')}`);
+      console.log(`  ${bColor.bold(`${bGrade} · ${designB.score.overall}`)} ${chalk.gray(designB.meta?.url || urlB)}`);
+      console.log('');
+      const winner =
+        designA.score.overall - designB.score.overall >= 3 ? `${chalk.bold(designA.meta?.url || urlA)} wins`
+        : designB.score.overall - designA.score.overall >= 3 ? `${chalk.bold(designB.meta?.url || urlB)} wins`
+        : 'Too close to call';
+      console.log(`  Verdict: ${winner}`);
+      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('Battle failed');
+      console.error(chalk.red(`\n  ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ── Apply command ──────────────────────────────────────────
 program
   .command('apply <url>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "12.1.0",
+  "version": "12.2.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.",
   "type": "module",
   "bin": {

package/src/formatters/badge.js

@@ -0,0 +1,90 @@
+// designlang badge — shields.io-style SVG badge for design score.
+// Uses Verdana web-safe font + computed text width so it renders identically
+// on GitHub, npm, and arbitrary markdown. No external font dependency.
+
+const COLORS = {
+  A: '#0a8a52',
+  B: '#1f6feb',
+  C: '#b08400',
+  D: '#d2691e',
+  F: '#c43d3d',
+  unknown: '#555',
+};
+
+// Verdana 11px character width approximation (em units × 11). Verdana is
+// chosen because it ships natively on every OS and matches shields.io's
+// rendering, so widths are predictable across platforms.
+const VERDANA_WIDTHS = {
+  ' ': 5, '!': 5, '#': 9, '$': 7, '%': 12, '&': 9, "'": 3, '(': 5, ')': 5,
+  '*': 7, '+': 7, ',': 5, '-': 5, '.': 5, '/': 5, '0': 7, '1': 7, '2': 7,
+  '3': 7, '4': 7, '5': 7, '6': 7, '7': 7, '8': 7, '9': 7, ':': 5, ';': 5,
+  '<': 7, '=': 7, '>': 7, '?': 7, '@': 12, 'A': 8, 'B': 8, 'C': 8, 'D': 9,
+  'E': 7, 'F': 7, 'G': 9, 'H': 9, 'I': 5, 'J': 5, 'K': 8, 'L': 7, 'M': 10,
+  'N': 9, 'O': 9, 'P': 7, 'Q': 9, 'R': 8, 'S': 7, 'T': 7, 'U': 9, 'V': 8,
+  'W': 12, 'X': 8, 'Y': 8, 'Z': 7, '[': 5, ']': 5, '_': 7, '`': 7,
+  'a': 7, 'b': 7, 'c': 6, 'd': 7, 'e': 7, 'f': 4, 'g': 7, 'h': 7, 'i': 3,
+  'j': 4, 'k': 7, 'l': 3, 'm': 11, 'n': 7, 'o': 7, 'p': 7, 'q': 7, 'r': 5,
+  's': 6, 't': 4, 'u': 7, 'v': 7, 'w': 10, 'x': 7, 'y': 7, 'z': 6, '|': 5,
+};
+
+function textWidth(s) {
+  let w = 0;
+  for (const ch of String(s)) w += VERDANA_WIDTHS[ch] ?? 7;
+  return w;
+}
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+/**
+ * Render a shields.io-style two-section SVG badge.
+ *   formatBadge({ label: 'design', value: 'B · 87', grade: 'B' })
+ *
+ * @param {object} opts
+ * @param {string} opts.label  — left-side label (default 'design')
+ * @param {string} opts.value  — right-side value (e.g. 'B · 87' or 'F · 12')
+ * @param {string} [opts.grade] — A–F, controls right-side fill color
+ * @param {string} [opts.color] — explicit hex override
+ * @returns {string} SVG markup
+ */
+export function formatBadge({ label = 'design', value = '—', grade, color } = {}) {
+  const fill = color || COLORS[grade] || COLORS.unknown;
+  const labelW = textWidth(label) + 12;   // 6px padding each side
+  const valueW = textWidth(value) + 12;
+  const totalW = labelW + valueW;
+  const labelX = labelW / 2;
+  const valueX = labelW + valueW / 2;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="20" role="img" aria-label="${esc(label)}: ${esc(value)}">
+  <title>${esc(label)}: ${esc(value)}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="${totalW}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelW}" height="20" fill="#555"/>
+    <rect x="${labelW}" width="${valueW}" height="20" fill="${fill}"/>
+    <rect width="${totalW}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+    <text aria-hidden="true" x="${labelX * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${textWidth(label) * 10}">${esc(label)}</text>
+    <text x="${labelX * 10}" y="140" transform="scale(.1)" fill="#fff" textLength="${textWidth(label) * 10}">${esc(label)}</text>
+    <text aria-hidden="true" x="${valueX * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${textWidth(value) * 10}">${esc(value)}</text>
+    <text x="${valueX * 10}" y="140" transform="scale(.1)" fill="#fff" textLength="${textWidth(value) * 10}">${esc(value)}</text>
+  </g>
+</svg>`;
+}
+
+/** Convenience: render a badge directly from a design.score object. */
+export function formatScoreBadge(score, opts = {}) {
+  if (!score || !score.grade) {
+    return formatBadge({ label: opts.label || 'design', value: '—', grade: 'unknown' });
+  }
+  return formatBadge({
+    label: opts.label || 'design',
+    value: `${score.grade} · ${score.overall}`,
+    grade: score.grade,
+  });
+}

package/src/formatters/battle.js

@@ -0,0 +1,338 @@
+// designlang battle — head-to-head graded comparison of two sites.
+// Renders both audited designs against each other, dimension by dimension,
+// and emits a single shareable HTML page with a verdict. Builds on the
+// scoring already done in src/extractors/scoring.js — no new analysis here.
+
+const FONT_DISPLAY = 'Instrument Serif';
+const FONT_BODY = 'Inter';
+const FONT_MONO = 'JetBrains Mono';
+
+const DIMENSIONS = [
+  ['colorDiscipline',       'Color'],
+  ['typographyConsistency', 'Typography'],
+  ['spacingSystem',         'Spacing'],
+  ['shadowConsistency',     'Elevation'],
+  ['radiusConsistency',     'Radii'],
+  ['accessibility',         'A11y'],
+  ['tokenization',          'Tokenization'],
+  ['cssHealth',             'CSS Health'],
+];
+
+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 gradeAccent(grade) {
+  return ({ A: '#0a8a52', B: '#1f6feb', C: '#b08400', D: '#d2691e', F: '#c43d3d' })[grade] || '#1f1f1f';
+}
+
+function familyName(f) {
+  if (!f) return '';
+  if (typeof f === 'string') return f;
+  return f.name || f.family || '';
+}
+
+export function compareScores(a, b) {
+  // Build dimension-by-dimension comparison from two design.score objects.
+  const rows = [];
+  let aWins = 0, bWins = 0, ties = 0;
+  for (const [key, label] of DIMENSIONS) {
+    const va = a?.scores?.[key];
+    const vb = b?.scores?.[key];
+    if (va === undefined || vb === undefined) continue;
+    const gap = Math.round(va - vb);
+    let winner = 'tie';
+    if (gap >= 3) { winner = 'a'; aWins++; }
+    else if (gap <= -3) { winner = 'b'; bWins++; }
+    else ties++;
+    rows.push({ key, label, a: Math.round(va), b: Math.round(vb), gap, winner });
+  }
+  let verdict = 'tie';
+  if (a?.overall - b?.overall >= 3) verdict = 'a';
+  else if (b?.overall - a?.overall >= 3) verdict = 'b';
+  return { rows, aWins, bWins, ties, verdict };
+}
+
+function paletteStrip(design) {
+  const all = (design?.colors?.all || []).slice(0, 10);
+  if (!all.length) return '';
+  return all.map(c => `<span class="chip" style="--c:${esc(c.hex || c)}" title="${esc(c.hex || c)}"></span>`).join('');
+}
+
+export function formatBattle(designA, designB, opts = {}) {
+  if (!designA?.score || !designB?.score) {
+    throw new Error('battle: both designs must include a score (run extractDesignLanguage first)');
+  }
+
+  const a = {
+    url: designA.meta?.url || '',
+    host: host(designA.meta?.url),
+    title: designA.meta?.title || '',
+    score: designA.score,
+    family: familyName((designA.typography?.families || [])[0]),
+  };
+  const b = {
+    url: designB.meta?.url || '',
+    host: host(designB.meta?.url),
+    title: designB.meta?.title || '',
+    score: designB.score,
+    family: familyName((designB.typography?.families || [])[0]),
+  };
+
+  const cmp = compareScores(a.score, b.score);
+  const aAccent = gradeAccent(a.score.grade);
+  const bAccent = gradeAccent(b.score.grade);
+  const verdictText =
+    cmp.verdict === 'a' ? `${a.host} wins`
+    : cmp.verdict === 'b' ? `${b.host} wins`
+    : `Too close to call`;
+  const date = new Date().toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' });
+  const ogTitle = `${a.host} vs ${b.host} · designlang`;
+  const ogDesc = `${verdictText}. ${a.score.overall} (${a.score.grade}) vs ${b.score.overall} (${b.score.grade}) across 8 design dimensions.`;
+
+  const dimRows = cmp.rows.map(r => {
+    const aPct = r.a;
+    const bPct = r.b;
+    const winnerClass = r.winner === 'a' ? 'win-a' : r.winner === 'b' ? 'win-b' : 'tie';
+    return `
+      <tr class="${winnerClass}">
+        <td class="d-label">${esc(r.label)}</td>
+        <td class="d-num d-num-a">${r.a}</td>
+        <td class="d-bar">
+          <div class="bar bar-a" style="width:${aPct}%; background:${aAccent}"></div>
+          <div class="bar bar-b" style="width:${bPct}%; background:${bAccent}"></div>
+        </td>
+        <td class="d-num d-num-b">${r.b}</td>
+        <td class="d-gap">${r.gap > 0 ? '+' : ''}${r.gap}</td>
+      </tr>`;
+  }).join('');
+
+  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: #f7f5ef;
+    --ink: #141414;
+    --ink-soft: #555049;
+    --rule: #e5e1d6;
+    --a-accent: ${aAccent};
+    --b-accent: ${bAccent};
+    --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: #0e0d0b;
+    --ink: #f0ece2;
+    --ink-soft: #9b9589;
+    --rule: #2a2823;
+  }
+  * { 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; }
+  .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 { color: var(--ink); text-decoration: none; border-bottom: 1px solid var(--rule); padding-bottom: 1px; }
+  .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: 12px; padding: 6px 12px; border-radius: 999px; cursor: pointer; letter-spacing: .04em; 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); margin-bottom: 14px; }
+  h1.title { font-family: var(--display); font-weight: 400; font-size: clamp(40px, 6vw, 72px); line-height: 1.02; margin: 0 0 36px; letter-spacing: -.01em; }
+  h1.title em { font-style: italic; color: var(--ink-soft); padding: 0 .12em; }
+
+  /* — Versus hero — */
+  .versus { display: grid; grid-template-columns: 1fr auto 1fr; gap: 24px; align-items: center; padding: 8px 0 56px; border-bottom: 1px solid var(--rule); }
+  .side { text-align: center; }
+  .side .host-name { font-family: var(--display); font-size: clamp(24px, 3vw, 32px); margin: 0 0 6px; line-height: 1.1; }
+  .side .host-name a { color: var(--ink); text-decoration: none; border-bottom: 2px solid currentColor; padding-bottom: 2px; }
+  .side .grade { font-family: var(--display); font-size: clamp(120px, 18vw, 200px); line-height: .85; font-weight: 400; letter-spacing: -.04em; margin: 8px 0; }
+  .side.a .grade { color: var(--a-accent); }
+  .side.b .grade { color: var(--b-accent); }
+  .side .score-num { font-family: var(--mono); font-size: 13px; color: var(--ink-soft); letter-spacing: .04em; }
+  .versus .vs { font-family: var(--display); font-size: clamp(28px, 4vw, 44px); color: var(--ink-soft); font-style: italic; }
+  @media (max-width: 640px) { .versus { grid-template-columns: 1fr; gap: 8px; } .versus .vs { padding: 8px 0; } }
+
+  /* — Verdict — */
+  .verdict { padding: 40px 0; border-bottom: 1px solid var(--rule); text-align: center; }
+  .verdict .v-label { font-family: var(--mono); font-size: 11px; letter-spacing: .18em; text-transform: uppercase; color: var(--ink-soft); margin-bottom: 16px; }
+  .verdict .v-text { font-family: var(--display); font-size: clamp(32px, 5vw, 56px); margin: 0; line-height: 1.05; letter-spacing: -.005em; }
+  .verdict .v-text em { font-style: italic; color: var(--a-accent); }
+  .verdict .v-text.b em { color: var(--b-accent); }
+  .verdict .v-tally { display: flex; justify-content: center; gap: 28px; margin-top: 18px; font-family: var(--mono); font-size: 12px; color: var(--ink-soft); text-transform: uppercase; letter-spacing: .08em; }
+  .verdict .v-tally .a-wins { color: var(--a-accent); }
+  .verdict .v-tally .b-wins { color: var(--b-accent); }
+
+  /* — Dimension table — */
+  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: 32px; margin: 0 0 8px; letter-spacing: -.005em; }
+  section > h2 + .lead { color: var(--ink-soft); margin: 0 0 32px; max-width: 60ch; }
+
+  table.dims { width: 100%; border-collapse: collapse; font-size: 14px; }
+  table.dims tr { border-bottom: 1px solid var(--rule); }
+  table.dims tr:last-child { border-bottom: 0; }
+  table.dims td { padding: 18px 8px; vertical-align: middle; }
+  table.dims .d-label { font-family: var(--display); font-size: 18px; width: 22%; }
+  table.dims .d-num { font-family: var(--mono); font-size: 16px; width: 12%; text-align: center; color: var(--ink-soft); }
+  table.dims .d-num-a { text-align: right; }
+  table.dims .d-num-b { text-align: left; }
+  table.dims .win-a .d-num-a { color: var(--a-accent); font-weight: 500; }
+  table.dims .win-b .d-num-b { color: var(--b-accent); font-weight: 500; }
+  table.dims .d-bar { padding: 18px 12px; }
+  table.dims .bar { height: 6px; border-radius: 3px; transition: opacity .15s; }
+  table.dims .bar-a { margin-bottom: 4px; }
+  table.dims .d-gap { font-family: var(--mono); font-size: 12px; text-align: right; width: 8%; color: var(--ink-soft); letter-spacing: .04em; }
+  table.dims .win-a .d-gap { color: var(--a-accent); }
+  table.dims .win-b .d-gap { color: var(--b-accent); }
+
+  /* — Palette strip — */
+  .palettes { display: grid; grid-template-columns: 1fr 1fr; gap: 32px; margin-top: 24px; }
+  @media (max-width: 640px) { .palettes { grid-template-columns: 1fr; } }
+  .pal h3 { font-family: var(--display); font-weight: 400; font-size: 18px; margin: 0 0 12px; color: var(--ink-soft); }
+  .pal .chips { display: flex; flex-wrap: wrap; gap: 6px; }
+  .chip { width: 26px; height: 26px; border-radius: 4px; background: var(--c); box-shadow: inset 0 0 0 1px rgba(0,0,0,.06); }
+
+  /* — 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 code { font-family: var(--mono); }
+  footer .stamp { font-family: var(--mono); font-size: 11px; text-transform: uppercase; letter-spacing: .08em; }
+
+  @media print {
+    body { background: white; color: black; }
+    .topbar nav, .theme-btn { display: none; }
+    section, .versus, .verdict { page-break-inside: avoid; border-color: #ddd; }
+    .side .grade { color: black; }
+  }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <header class="topbar">
+      <div class="brand"><a href="https://designlang.dev">designlang</a></div>
+      <nav>
+        <span>Battle Card</span>
+        <button class="theme-btn" id="themeBtn" type="button">Theme</button>
+      </nav>
+    </header>
+
+    <p class="kicker">Design Battle · ${esc(date)}</p>
+    <h1 class="title">${esc(a.host)} <em>versus</em> ${esc(b.host)}</h1>
+
+    <div class="versus">
+      <div class="side a">
+        <p class="host-name"><a href="${esc(a.url)}" target="_blank" rel="noopener">${esc(a.host)}</a></p>
+        <div class="grade">${esc(a.score.grade)}</div>
+        <p class="score-num">${a.score.overall} / 100</p>
+      </div>
+      <div class="vs">vs.</div>
+      <div class="side b">
+        <p class="host-name"><a href="${esc(b.url)}" target="_blank" rel="noopener">${esc(b.host)}</a></p>
+        <div class="grade">${esc(b.score.grade)}</div>
+        <p class="score-num">${b.score.overall} / 100</p>
+      </div>
+    </div>
+
+    <div class="verdict">
+      <p class="v-label">Verdict</p>
+      <p class="v-text ${cmp.verdict === 'b' ? 'b' : ''}">${
+        cmp.verdict === 'a' ? `<em>${esc(a.host)}</em> takes it.`
+        : cmp.verdict === 'b' ? `<em>${esc(b.host)}</em> takes it.`
+        : 'Too <em>close</em> to call.'
+      }</p>
+      <div class="v-tally">
+        <span class="a-wins">${cmp.aWins} ${cmp.aWins === 1 ? 'win' : 'wins'} · ${esc(a.host)}</span>
+        <span>${cmp.ties} ${cmp.ties === 1 ? 'tie' : 'ties'}</span>
+        <span class="b-wins">${cmp.bWins} ${cmp.bWins === 1 ? 'win' : 'wins'} · ${esc(b.host)}</span>
+      </div>
+    </div>
+
+    <section>
+      <h2>Round by round.</h2>
+      <p class="lead">Eight scored dimensions. Bigger bar wins. A gap under three points is called a tie.</p>
+      <table class="dims">
+        <tbody>${dimRows}</tbody>
+      </table>
+    </section>
+
+    <section>
+      <h2>The evidence.</h2>
+      <p class="lead">Palettes pulled straight from each site's live styles.</p>
+      <div class="palettes">
+        <div class="pal">
+          <h3>${esc(a.host)} · ${esc(a.family || '—')}</h3>
+          <div class="chips">${paletteStrip(designA)}</div>
+        </div>
+        <div class="pal">
+          <h3>${esc(b.host)} · ${esc(b.family || '—')}</h3>
+          <div class="chips">${paletteStrip(designB)}</div>
+        </div>
+      </div>
+    </section>
+
+    <footer>
+      <div>
+        <div class="sig">designlang</div>
+        <div>Run your own: <code>npx designlang battle ${esc(a.host)} ${esc(b.host)}</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 formatBattleMarkdown(designA, designB) {
+  if (!designA?.score || !designB?.score) throw new Error('battle: both designs need scores');
+  const a = { host: host(designA.meta?.url), score: designA.score };
+  const b = { host: host(designB.meta?.url), score: designB.score };
+  const cmp = compareScores(a.score, b.score);
+  const lines = [
+    `# ${a.host} vs ${b.host}`,
+    ``,
+    `**Verdict:** ${cmp.verdict === 'a' ? `${a.host} wins` : cmp.verdict === 'b' ? `${b.host} wins` : 'Tie'} — ${cmp.aWins}–${cmp.bWins} (${cmp.ties} ties)`,
+    ``,
+    `| | ${a.host} | ${b.host} | Δ |`,
+    `|---|---|---|---|`,
+    `| **Overall** | ${a.score.overall} (${a.score.grade}) | ${b.score.overall} (${b.score.grade}) | ${a.score.overall - b.score.overall > 0 ? '+' : ''}${a.score.overall - b.score.overall} |`,
+    ...cmp.rows.map(r => `| ${r.label} | ${r.a} | ${r.b} | ${r.gap > 0 ? '+' : ''}${r.gap} |`),
+    ``,
+    `_Audited by [designlang](https://designlang.dev) · \`npx designlang battle ${a.host} ${b.host}\`_`,
+  ];
+  return lines.join('\n');
+}