designlang 12.1.0 → 12.3.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [12.3.0] — 2026-05-05
+
+**Remix — restyle any site in a different design vocabulary.**
+
+A genuinely new product surface: take an extracted page-shape (sections,
+voice, page-intent, anatomy) and re-render it under one of six
+opinionated design vocabularies. "What would stripe.com look like if it
+had been designed brutalist? Or art-deco? Or cyberpunk?"
+
+### Added
+
+- **`designlang remix <url> --as <vocab>`** — re-renders the audited page
+  using the host's *own copy* (headings, ledes, CTA verbs from voice) but
+  styled in another vocabulary. Six built-ins:
+  - `brutalist` — hard edges, mono type, single screaming accent
+  - `swiss` — Helvetica, grids, restraint (post-Bauhaus default)
+  - `art-deco` — gold on ink, geometric ornament, vertical type
+  - `cyberpunk` — neon on midnight, scanlines, mono with glitch energy
+  - `soft-ui` — cushioned shapes, low contrast, Vision-OS-adjacent
+  - `editorial` — broadsheet serifs, generous whitespace, ink on paper
+- `--all` flag emits one HTML per vocabulary in a single extraction.
+- `--list` prints the vocabulary registry with blurbs.
+- New formatter: `src/formatters/remix.js` — maps every section role
+  (hero, feature-grid, pricing-table, stats, testimonial, faq,
+  logo-wall, steps, cta) to vocabulary-styled markup.
+- New module: `src/vocabularies/` — six self-contained vocab definitions
+  (tokens + font stack + signature CSS) plus `index.js` registry.
+- Hero-deduplication: real-world section walkers (especially on SPA
+  marketing pages) often emit a hero wrapper + an inner hero with the
+  same h1. Remix now dedupes by heading and excludes claimed headings
+  from the voice pool, so heading-less sections (cta bands, logo walls)
+  don't re-render an already-claimed heading.
+- 14 new tests (350 total, all passing). Cover registry shape,
+  per-vocab token validity, dedup, XSS escaping, missing-input errors.
+
+Why: Grade (v12.1) is the audit, Battle (v12.2) is the comparison,
+Remix is the *transformation*. Pure visual moat — no competitor
+(Dembrandt, Superposition, html.to.design, Builder Visual Copilot)
+ships site-shape-preserving vocabulary swap.
+
+## [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,19 @@ 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 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
+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 +65,9 @@ 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` |
+| `*-remix.<vocab>.html` | **v12.3** Site restyled in another vocabulary — brutalist / swiss / art-deco / cyberpunk / soft-ui / editorial |
 
 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 +126,10 @@ 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 (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 (NEW 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 |
 | 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 +182,9 @@ 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)
+  remix <url>                       Restyle in another vocabulary (--as brutalist|swiss|art-deco|cyberpunk|soft-ui|editorial, --all, --list, --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

@@ -43,9 +43,12 @@ import { syncDesign } from '../src/sync.js';
 import { compareBrands, formatBrandMatrix, formatBrandMatrixHtml } from '../src/multibrand.js';
 import { generateClone } from '../src/clone.js';
 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 { formatRemix } from '../src/formatters/remix.js';
+import { VOCABULARIES, getVocabulary, listVocabularies } from '../src/vocabularies/index.js';
 import { nameFromUrl } from '../src/utils.js';
 
 function validateUrl(url) {
@@ -941,7 +944,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 +961,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 +989,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 +1021,157 @@ 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);
+    }
+  });
+
+// ── Remix command — restyle an extracted page in another vocabulary ─
+program
+  .command('remix <url>')
+  .description('Restyle a site in a different design vocabulary (brutalist, swiss, art-deco, cyberpunk, soft-ui, editorial)')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-n, --name <name>', 'output file prefix (default: derived from URL)')
+  .option('--as <vocab>', 'vocabulary id (run `designlang remix --list` to see all)', 'brutalist')
+  .option('--list', 'list all vocabularies and exit')
+  .option('--all', 'emit one HTML per vocabulary (six files at once)')
+  .option('--open', 'open the result in the default browser')
+  .action(async (url, opts) => {
+    if (opts.list) {
+      console.log('');
+      console.log(chalk.bold('  Vocabularies'));
+      console.log('');
+      for (const v of listVocabularies()) {
+        console.log(`  ${chalk.cyan(v.id.padEnd(14))} ${chalk.gray(v.blurb)}`);
+      }
+      console.log('');
+      console.log(chalk.gray(`  Use: designlang remix <url> --as <id>`));
+      console.log('');
+      return;
+    }
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+
+    const vocabIds = opts.all ? Object.keys(VOCABULARIES) : [opts.as];
+    // Validate vocab early so we fail before extraction.
+    for (const id of vocabIds) getVocabulary(id);
+
+    const spinner = ora(`Extracting ${url}...`).start();
+    try {
+      const design = await extractDesignLanguage(url);
+
+      const outDir = resolve(opts.out);
+      mkdirSync(outDir, { recursive: true });
+      const prefix = opts.name || nameFromUrl(url);
+      const written = [];
+
+      for (const id of vocabIds) {
+        spinner.text = `Rendering ${id}...`;
+        const vocab = getVocabulary(id);
+        const html = formatRemix(design, vocab, { vocabId: id, version: PKG_VERSION });
+        const p = join(outDir, `${prefix}.remix.${id}.html`);
+        writeFileSync(p, html);
+        written.push(p);
+      }
+
+      spinner.stop();
+      console.log('');
+      console.log(`  ${chalk.bold('Remixed')} ${chalk.gray('·')} ${chalk.cyan(vocabIds.join(', '))} ${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 in a browser. One file per vocabulary, fully self-contained.`));
+      console.log('');
+
+      if (opts.open && written.length > 0) {
+        const { spawn } = await import('child_process');
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        spawn(cmd, [written[0]], { detached: true, stdio: 'ignore' }).unref();
+      }
+    } catch (err) {
+      spinner.fail('Remix 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.3.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/chat.js

@@ -22,20 +22,6 @@ function isHex(s) {
   return typeof s === 'string' && /^#[0-9a-f]{3,8}$/i.test(s.trim());
 }
 
-function hexToRgb(hex) {
-  const m = String(hex).trim().toLowerCase().replace(/^#/, '');
-  const full = m.length === 3 ? m.split('').map((c) => c + c).join('') : m.slice(0, 6);
-  return {
-    r: parseInt(full.slice(0, 2), 16) || 0,
-    g: parseInt(full.slice(2, 4), 16) || 0,
-    b: parseInt(full.slice(4, 6), 16) || 0,
-  };
-}
-
-function rgbToHex({ r, g, b }) {
-  return '#' + [r, g, b].map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('');
-}
-
 function opSharpenRadii(design, factor = 0.5) {
   const radii = design.borders?.radii || [];
   const next = radii.map((r) => ({ ...r, value: Math.max(0, Math.round((r.value || 0) * factor)) }));

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,
+  });
+}