prism-design 2.13.0

package/scripts/generate-showcase.ts

@@ -0,0 +1,1588 @@
+/**
+ * generate-showcase.ts  —  Sprint 3
+ * Génère extractions/{domain}/showcase/index.html
+ *
+ * Nouveautés vs v1:
+ *   • Sticky sidebar nav (9 sections, IntersectionObserver)
+ *   • Copy-to-clipboard sur chaque swatch
+ *   • Semantic color roles (error/success/warning/info)
+ *   • Typography: line-height + letter-spacing columns + @font-face loading
+ *   • Header: desktop + mobile screenshots côte-à-côte
+ *   • Live Components: boutons/inputs/cards rendus en HTML réel avec vrais tokens
+ *   • Visual Match section: screenshot original vs section générée
+ */
+
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { join, resolve } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { luminance } from './shared/css-helpers.js';
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function rgbToHex(color: string): string {
+  if (!color || color === 'transparent') return '#transparent';
+  if (color.startsWith('#')) return color.toLowerCase();
+  const m = color.match(/rgba?\(\s*(\d+),\s*(\d+),\s*(\d+)/);
+  if (!m) return color;
+  const hex = [m[1], m[2], m[3]].map(v => parseInt(v).toString(16).padStart(2, '0')).join('');
+  return `#${hex}`;
+}
+
+// Note: re-uses shared luminance() (WCAG gamma-corrected) — Phase 1.2 cleanup, dedupe inline impl
+function luminanceFromColorString(color: string): number {
+  const hex = rgbToHex(color);
+  const m = hex.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+  if (!m) return 0.5;
+  const [r, g, b] = [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)];
+  return luminance(r, g, b);
+}
+
+function contrastColor(color: string): string {
+  return luminanceFromColorString(color) > 0.45 ? '#1a1a1a' : '#ffffff';
+}
+
+function escapeHtml(s: string): string {
+  if (!s) return '';
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try { await access(p); return true; } catch { return false; }
+}
+
+async function screenshotBase64(dir: string, preferMobile = false): Promise<string | null> {
+  const desktopCandidates = [
+    'above-fold-desktop.png', 'scroll-0-desktop.png', 'full-page-desktop.png',
+  ];
+  const mobileCandidates = [
+    'above-fold-mobile.png', 'scroll-0-mobile.png', 'full-page-mobile.png',
+  ];
+  const list = preferMobile ? mobileCandidates : desktopCandidates;
+  for (const name of list) {
+    const p = join(dir, 'screenshots', name);
+    if (await fileExists(p)) {
+      const buf = readFileSync(p);
+      return `data:image/png;base64,${buf.toString('base64')}`;
+    }
+  }
+  return null;
+}
+
+// Read fontFaces from raw-css.json for @font-face injection
+async function loadFontFaces(baseDir: string): Promise<string> {
+  const rawPath = join(baseDir, 'raw-css.json');
+  if (!existsSync(rawPath)) return '';
+  try {
+    const raw = JSON.parse(readFileSync(rawPath, 'utf-8'));
+    const data = raw.desktop || raw;
+    const faces: Array<{ family?: string; src?: string; weight?: string; style?: string }> = data.fontFaces || [];
+    if (!faces.length) return '';
+    return faces.slice(0, 8).map(f => {
+      if (!f.family || !f.src) return '';
+      // Only load woff2/woff — skip ttf/eot to stay lean
+      const safeSrc = (f.src || '').replace(/url\(['"]?([^'")\s]+\.(?:ttf|eot|svg)[^'")\s]*)['"]?\)/gi, '');
+      if (!safeSrc.includes('url(')) return '';
+      return `@font-face { font-family: '${f.family}'; src: ${safeSrc}; font-weight: ${f.weight || '400'}; font-style: ${f.style || 'normal'}; font-display: swap; }`;
+    }).filter(Boolean).join('\n');
+  } catch { return ''; }
+}
+
+// ── CSS ────────────────────────────────────────────────────────────────────────
+
+function buildCss(tokens: any): string {
+  const bg      = tokens.colors?.background?.primary || '#ffffff';
+  const bgAlt   = tokens.colors?.background?.secondary || '#f5f5f5';
+  let fg        = tokens.colors?.text?.primary || '#111111';
+  let fgMuted   = tokens.colors?.text?.muted || '#888888';
+  const accent  = tokens.colors?.accent?.primary || '#0070f3';
+  const border  = tokens.colors?.border || '#e5e5e5';
+  const radius  = tokens.borderRadius?.md || '8px';
+  const font    = tokens.typography?.fontFamily?.primary || 'system-ui';
+  const mono    = tokens.typography?.fontFamily?.mono || 'monospace';
+
+  const accentHex  = rgbToHex(accent);
+  const bgHex      = rgbToHex(bg);
+  const bgAltHex   = rgbToHex(bgAlt);
+  let fgHex        = rgbToHex(fg);
+  let fgMutedHex   = rgbToHex(fgMuted);
+  const borderHex  = rgbToHex(border);
+  const isLight    = luminanceFromColorString(bgHex) > 0.5;
+
+  // v5-FIX: Auto-correct invisible text — if bg and fg are both very dark OR both very light,
+  // override fg with safe contrast color (white on dark, black on light)
+  const bgLum = luminanceFromColorString(bgHex);
+  const fgLum = luminanceFromColorString(fgHex);
+  if (Math.abs(bgLum - fgLum) < 0.3) {
+    // Insufficient contrast → force readable color
+    fgHex = isLight ? '#1a1a1a' : '#fafafa';
+    fgMutedHex = isLight ? '#666666' : '#a8a8a8';
+  } else if (luminanceFromColorString(fgMutedHex) < 0.15 && !isLight) {
+    // Muted text invisible on dark
+    fgMutedHex = '#a8a8a8';
+  } else if (luminanceFromColorString(fgMutedHex) > 0.85 && isLight) {
+    fgMutedHex = '#666666';
+  }
+
+  // v7: FORCE LIGHT MODE — fond blanc partout, brand accent preserved
+  // The CA showcase itself is always white-background regardless of source site theme.
+  // The brand colors are shown in their cards/components but the chrome stays clean.
+  const v7Bg       = '#ffffff';
+  const v7BgAlt    = '#fafafa';
+  const v7Fg       = '#0a0a0a';
+  const v7FgMuted  = '#666666';
+  const v7Border   = '#e6e6e6';
+  const v7BorderSoft = '#f0f0f0';
+
+  return `
+  /* v7: Premium typography via @font-face Inter + JetBrains Mono (self-hosted Google Fonts) */
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap');
+
+  :root {
+    --bg:           ${v7Bg};
+    --bg-alt:       ${v7BgAlt};
+    --fg:           ${v7Fg};
+    --fg-muted:     ${v7FgMuted};
+    --accent:       ${accentHex};
+    --accent-soft:  ${accentHex}15;
+    --border:       ${v7Border};
+    --border-soft:  ${v7BorderSoft};
+    --radius:       12px;
+    --radius-sm:    8px;
+    --font:         'Inter', system-ui, -apple-system, sans-serif;
+    --font-display: 'Inter', system-ui, -apple-system, sans-serif;
+    --mono:         'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;
+    --page-max:     1240px;
+    --nav-w:        236px;
+    --shadow-soft:  0 1px 2px rgba(0,0,0,0.04), 0 1px 4px rgba(0,0,0,0.04);
+    --shadow-card:  0 1px 2px rgba(0,0,0,0.04), 0 4px 16px rgba(0,0,0,0.04);
+    --shadow-elev:  0 8px 32px rgba(0,0,0,0.08), 0 2px 8px rgba(0,0,0,0.04);
+  }
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  html { font-size: 16px; scroll-behavior: smooth; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
+  body { background: var(--bg); color: var(--fg); font-family: var(--font); font-size: 15px; line-height: 1.55; letter-spacing: -0.005em; }
+  /* Premium heading typography — Inter at heavy weights with tight letter-spacing */
+  h1, h2, h3, h4 { font-family: var(--font-display); font-weight: 700; letter-spacing: -0.025em; line-height: 1.15; color: var(--fg); }
+
+  /* ─ Layout ─────────────────────────────────────────────────────────── */
+  .app-layout {
+    display: flex;
+    max-width: calc(var(--page-max) + var(--nav-w) + 48px);
+    margin: 0 auto;
+    padding: 0 24px;
+    gap: 40px;
+    align-items: flex-start;
+  }
+
+  /* ─ Sidebar nav v7 — clean white modern ─────────────────────────────── */
+  .nav-sidebar {
+    position: sticky;
+    top: 32px;
+    width: var(--nav-w);
+    flex-shrink: 0;
+    align-self: flex-start;
+    padding: 24px 0;
+  }
+  .nav-sidebar-inner {
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 18px 0;
+    box-shadow: var(--shadow-soft);
+  }
+  .nav-brand {
+    display: block;
+    padding: 0 16px 12px;
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: .08em;
+    text-transform: uppercase;
+    opacity: .45;
+    border-bottom: 1px solid var(--border);
+    margin-bottom: 8px;
+  }
+  .nav-link {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 16px;
+    font-size: 13px;
+    color: var(--fg);
+    text-decoration: none;
+    opacity: .55;
+    transition: opacity .15s, background .15s;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .nav-link:hover { opacity: 1; background: rgba(128,128,128,.07); }
+  .nav-link.active { opacity: 1; font-weight: 600; color: var(--accent); }
+  .nav-dot {
+    width: 6px; height: 6px; border-radius: 50%;
+    background: var(--border);
+    flex-shrink: 0;
+    transition: background .15s;
+  }
+  .nav-link.active .nav-dot { background: var(--accent); }
+
+  /* ─ Main content ────────────────────────────────────────────────────── */
+  .main-content { flex: 1; min-width: 0; padding-bottom: 80px; }
+
+  /* ─ Header v5 — BRAND-CUSTOMIZED HERO ───────────────────────────────── */
+  .site-header {
+    position: relative;
+    padding: 64px 48px 56px;
+    margin: -24px -24px 56px -24px;
+    border-radius: 16px;
+    background:
+      radial-gradient(circle at 0% 0%, ${accentHex}25 0%, transparent 50%),
+      radial-gradient(circle at 100% 100%, ${accentHex}15 0%, transparent 60%),
+      linear-gradient(180deg, var(--bg) 0%, var(--bg-alt) 100%);
+    border: 1px solid var(--border);
+    overflow: hidden;
+    animation: heroFadeIn 0.6s cubic-bezier(0.4, 0, 0.2, 1);
+  }
+  .site-header::before {
+    content: '';
+    position: absolute;
+    top: 0; left: 0; right: 0; height: 3px;
+    background: linear-gradient(90deg, ${accentHex} 0%, ${accentHex}80 50%, transparent 100%);
+  }
+  @keyframes heroFadeIn {
+    from { opacity: 0; transform: translateY(8px); }
+    to   { opacity: 1; transform: translateY(0); }
+  }
+  .header-top { display: flex; gap: 32px; align-items: flex-start; flex-wrap: wrap; }
+  .header-meta { flex: 1; min-width: 280px; }
+  .header-badge {
+    display: inline-block; padding: 5px 12px;
+    background: var(--bg); color: var(--fg-muted); border: 1px solid var(--border);
+    border-radius: 99px; font-size: 10px; font-weight: 700;
+    letter-spacing: .08em; text-transform: uppercase; margin-bottom: 20px;
+    box-shadow: 0 2px 8px ${accentHex}40;
+  }
+  .header-domain {
+    font-size: 44px; font-weight: 800; letter-spacing: -.03em;
+    margin-bottom: 10px; line-height: 1.05;
+    background: none;
+    color: var(--fg);
+    /* removed background-clip text */
+  }
+  .header-tagline {
+    font-family: var(--font-display);
+    font-size: 22px; font-weight: 500;
+    color: var(--fg);
+    opacity: .75;
+    margin: 16px 0 24px;
+    max-width: 680px;
+    line-height: 1.35;
+    letter-spacing: -0.015em;
+  }
+  .header-meta-row { display: flex; gap: 16px; font-size: 12px; opacity: .6; flex-wrap: wrap; align-items: center; }
+  .header-meta-row a:hover { color: ${accentHex}; }
+  .confidence-badge {
+    display: inline-block; padding: 2px 7px; border-radius: 4px;
+    font-weight: 700; font-family: var(--mono); font-size: 11px;
+    margin-left: 4px;
+  }
+  .confidence-A { background: rgba(16,185,129,.15); color: #10b981; border: 1px solid rgba(16,185,129,.3); }
+  .confidence-B { background: rgba(14,165,233,.15); color: #0ea5e9; border: 1px solid rgba(14,165,233,.3); }
+  .confidence-C { background: rgba(245,158,11,.15); color: #f59e0b; border: 1px solid rgba(245,158,11,.3); }
+  .confidence-D { background: rgba(239,68,68,.15); color: #ef4444; border: 1px solid rgba(239,68,68,.3); }
+
+  /* v6: Stagger fade-in pour sections */
+  .section {
+    opacity: 0; transform: translateY(12px);
+    animation: sectionReveal 0.6s cubic-bezier(0.4, 0, 0.2, 1) forwards;
+  }
+  .section:nth-of-type(1) { animation-delay: 0.05s; }
+  .section:nth-of-type(2) { animation-delay: 0.1s; }
+  .section:nth-of-type(3) { animation-delay: 0.15s; }
+  .section:nth-of-type(4) { animation-delay: 0.2s; }
+  .section:nth-of-type(5) { animation-delay: 0.25s; }
+  .section:nth-of-type(n+6) { animation-delay: 0.3s; }
+  @keyframes sectionReveal {
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  /* v6: Footer */
+  .showcase-footer {
+    margin-top: 96px; padding: 32px 0; border-top: 1px solid var(--border);
+    display: flex; gap: 20px; align-items: center; justify-content: space-between;
+    flex-wrap: wrap; font-size: 12px; opacity: .7;
+  }
+  .showcase-footer .footer-meta { display: flex; gap: 12px; align-items: center; flex-wrap: wrap; }
+  .showcase-footer .footer-links { display: flex; gap: 16px; }
+  .showcase-footer a { color: var(--accent); text-decoration: none; font-weight: 600; }
+  .showcase-footer a:hover { text-decoration: underline; }
+
+  /* v6: WCAG contrast badge on swatch hover */
+  .swatch[data-wcag]::after {
+    content: attr(data-wcag);
+    position: absolute; top: 8px; right: 8px;
+    font-size: 9px; font-weight: 700; letter-spacing: .04em;
+    padding: 2px 6px; border-radius: 4px;
+    opacity: 0; transition: opacity .15s;
+    background: rgba(0,0,0,.7); color: white;
+  }
+  .swatch:hover[data-wcag]::after { opacity: 1; }
+  .header-screenshots {
+    display: flex; gap: 12px; margin-top: 24px;
+    align-items: flex-start; flex-wrap: wrap;
+  }
+  .header-screenshot-wrap { flex-shrink: 0; }
+  .screenshot-label {
+    font-size: 10px; font-weight: 600; letter-spacing: .06em; text-transform: uppercase;
+    opacity: .4; margin-bottom: 6px;
+  }
+  .header-screenshot {
+    border-radius: var(--radius); overflow: hidden;
+    border: 1px solid var(--border); box-shadow: 0 4px 16px rgba(0,0,0,.08);
+  }
+  .header-screenshot.desktop img { width: 360px; display: block; }
+  .header-screenshot.mobile img  { width: 120px; display: block; }
+
+  /* ─ Section chrome v5 — Indexed numbering ───────────────────────────── */
+  .main-content { counter-reset: section; }
+  .section { margin-bottom: 72px; scroll-margin-top: 32px; counter-increment: section; }
+  .section > h2 {
+    font-size: 28px; font-weight: 800;
+    margin-bottom: 28px; padding-bottom: 12px;
+    border-bottom: 2px solid var(--accent);
+    display: inline-block;
+    letter-spacing: -.02em;
+  }
+  .section > h2::before {
+    content: counter(section, decimal-leading-zero) " — ";
+    color: var(--accent);
+    font-weight: 600;
+    opacity: .7;
+  }
+  .section-desc { font-size: 13px; opacity: .55; margin-bottom: 24px; margin-top: -16px; max-width: 720px; line-height: 1.55; }
+  .section h3 {
+    font-size: 11px; font-weight: 700; letter-spacing: .1em;
+    text-transform: uppercase; opacity: .5;
+    margin-bottom: 14px; margin-top: 32px;
+  }
+
+  /* ─ Palette v5 — Enhanced cards 180x120 ─────────────────────────────── */
+  .color-group { margin-bottom: 32px; }
+  .color-group-label {
+    font-size: 11px; font-weight: 700; letter-spacing: .08em;
+    text-transform: uppercase; opacity: .5; margin-bottom: 12px;
+  }
+  .swatches {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+    gap: 14px;
+  }
+  .swatch {
+    min-height: 124px; border-radius: 10px;
+    padding: 14px 16px; display: flex; flex-direction: column;
+    justify-content: flex-end; border: 1px solid rgba(255,255,255,.08);
+    cursor: pointer; position: relative; transition: transform .2s cubic-bezier(.4,0,.2,1), box-shadow .2s;
+    user-select: none; overflow: hidden;
+  }
+  .swatch::before {
+    content: ''; position: absolute; inset: 0;
+    background: linear-gradient(180deg, rgba(255,255,255,.04) 0%, transparent 30%, rgba(0,0,0,.12) 100%);
+    pointer-events: none;
+  }
+  .swatch:hover { transform: translateY(-3px); box-shadow: 0 10px 24px rgba(0,0,0,.2); }
+  .swatch-name { font-size: 13px; font-weight: 700; line-height: 1.3; position: relative; }
+  .swatch-hex  { font-size: 11px; opacity: .85; font-family: var(--mono); margin-top: 3px; position: relative; }
+  .swatch-use  { font-size: 10px; opacity: .7; margin-top: 6px; position: relative; }
+  .swatch-role {
+    position: absolute; top: 8px; right: 8px;
+    font-size: 9px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase;
+    opacity: .6; padding: 2px 5px; border-radius: 4px; background: rgba(0,0,0,.12);
+  }
+  .swatch-copied {
+    position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+    background: rgba(0,0,0,.6); color: #fff; font-size: 13px; font-weight: 700;
+    border-radius: var(--radius); opacity: 0; transition: opacity .15s;
+    pointer-events: none;
+  }
+  .swatch.flash .swatch-copied { opacity: 1; }
+
+  /* ─ Typography ──────────────────────────────────────────────────────── */
+  .typo-table { width: 100%; border-collapse: collapse; }
+  .typo-table th {
+    text-align: left; font-size: 10px; font-weight: 700; letter-spacing: .07em;
+    text-transform: uppercase; opacity: .4; padding: 0 8px 10px 0;
+    border-bottom: 1px solid var(--border);
+  }
+  .typo-table td { padding: 12px 8px 12px 0; border-bottom: 1px solid var(--border); vertical-align: top; }
+  .typo-table tr:last-child td { border-bottom: none; }
+  .typo-role-cell { font-size: 12px; font-weight: 600; white-space: nowrap; }
+  .typo-spec-cell { font-family: var(--mono); font-size: 11px; opacity: .5; white-space: nowrap; }
+  .typo-preview-cell { font-size: inherit; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 320px; }
+
+  /* ─ Spacing ─────────────────────────────────────────────────────────── */
+  .token-list { display: flex; flex-direction: column; gap: 10px; margin-bottom: 40px; }
+  .token-row  { display: flex; align-items: center; gap: 12px; }
+  .token-name { font-family: var(--mono); font-size: 12px; width: 52px; opacity: .55; flex-shrink: 0; }
+  .token-bar-wrap { flex: 1; max-width: 320px; }
+  .token-bar  { height: 8px; background: var(--accent); border-radius: 4px; display: block; opacity: .6; }
+  .token-value{ font-family: var(--mono); font-size: 12px; opacity: .55; }
+  .radius-row { display: flex; flex-wrap: wrap; gap: 24px; align-items: flex-end; margin-top: 8px; }
+  .radius-item{ display: flex; flex-direction: column; align-items: center; gap: 8px; }
+  .radius-box { width: 48px; height: 48px; background: var(--accent); opacity: .65; }
+  .radius-label{ font-size: 11px; text-align: center; opacity: .55; font-family: var(--mono); }
+
+  /* ─ Live Components ─────────────────────────────────────────────────── */
+  .live-components-grid { display: flex; flex-direction: column; gap: 40px; }
+  .live-component-group { }
+  .live-component-group h3 { margin-top: 0; margin-bottom: 16px; }
+  .live-demo-row { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; padding: 24px; background: var(--bg-alt); border-radius: var(--radius); border: 1px solid var(--border); }
+  .live-demo-label { font-size: 11px; opacity: .4; font-family: var(--mono); margin-top: 12px; display: block; }
+
+  /* ─ Component specs ─────────────────────────────────────────────────── */
+  .component-group { margin-bottom: 32px; }
+  .variants-grid   { display: flex; flex-wrap: wrap; gap: 14px; }
+  .component-variant {
+    background: var(--bg-alt); border: 1px solid var(--border);
+    border-radius: var(--radius); padding: 14px; width: 210px; font-size: 12px;
+  }
+  .component-variant strong { display: block; margin-bottom: 8px; font-size: 13px; }
+  .component-variant ul { list-style: none; }
+  .component-variant li {
+    padding: 3px 0; opacity: .65; border-top: 1px solid var(--border);
+    margin-top: 4px; font-family: var(--mono); font-size: 11px;
+  }
+
+  /* ─ Breakpoints ─────────────────────────────────────────────────────── */
+  .bp-list { display: flex; flex-direction: column; gap: 10px; }
+  .bp-row  { display: flex; align-items: center; gap: 12px; }
+  .bp-name { font-size: 12px; width: 120px; opacity: .55; flex-shrink: 0; }
+  .bp-bar-wrap { flex: 1; max-width: 400px; background: var(--border); border-radius: 4px; height: 8px; }
+  .bp-bar  { height: 8px; background: var(--accent); border-radius: 4px; display: block; opacity: .75; min-width: 4px; }
+  .bp-value{ font-family: var(--mono); font-size: 12px; opacity: .55; width: 72px; }
+
+  /* ─ Elevation ───────────────────────────────────────────────────────── */
+  .elev-grid { display: flex; gap: 20px; flex-wrap: wrap; padding: 24px 0; }
+  .elev-card {
+    flex: 1 1 160px; min-height: 90px; border-radius: var(--radius);
+    background: var(--bg); border: 1px solid var(--border); padding: 16px;
+    display: flex; flex-direction: column; gap: 8px;
+  }
+  .elev-label { font-size: 12px; font-weight: 600; opacity: .7; }
+  .elev-code  { font-size: 10px; opacity: .4; word-break: break-all; line-height: 1.4; font-family: var(--mono); }
+
+  /* ─ Motion ──────────────────────────────────────────────────────────── */
+  .motion-table { width: 100%; border-collapse: collapse; }
+  .motion-table td { padding: 5px 8px; font-size: 12px; border-bottom: 1px solid var(--border); }
+  .motion-table tr:last-child td { border-bottom: none; }
+
+  /* ─ Do's & Don'ts ───────────────────────────────────────────────────── */
+  .dos-donts-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin-top: 8px; }
+  .do-col   { background: rgba(0,128,0,.05);  border: 1px solid rgba(0,128,0,.15);  border-radius: 8px; padding: 16px 20px; }
+  .dont-col { background: rgba(200,0,0,.05);  border: 1px solid rgba(200,0,0,.12);  border-radius: 8px; padding: 16px 20px; }
+  .do-header   { font-size: 12px; font-weight: 700; color: #1a7a1a; margin-bottom: 12px; letter-spacing: .04em; }
+  .dont-header { font-size: 12px; font-weight: 700; color: #9a1a1a; margin-bottom: 12px; letter-spacing: .04em; }
+  .do-list, .dont-list { list-style: none; display: flex; flex-direction: column; gap: 8px; }
+  .do-item, .dont-item { font-size: 13px; line-height: 1.5; display: flex; gap: 8px; align-items: flex-start; }
+  .do-icon   { color: #1a7a1a; font-weight: 700; flex-shrink: 0; }
+  .dont-icon { color: #9a1a1a; font-weight: 700; flex-shrink: 0; }
+
+  /* ─ Visual Match ────────────────────────────────────────────────────── */
+  .visual-match-grid { display: flex; gap: 24px; align-items: flex-start; flex-wrap: wrap; }
+  .visual-match-item { flex: 1 1 360px; }
+  .visual-match-label { font-size: 11px; font-weight: 700; letter-spacing: .07em; text-transform: uppercase; opacity: .45; margin-bottom: 10px; }
+  .visual-match-frame {
+    border: 1px solid var(--border); border-radius: var(--radius);
+    overflow: hidden; box-shadow: 0 2px 12px rgba(0,0,0,.07);
+  }
+  .visual-match-frame img { width: 100%; display: block; }
+
+  /* ─ Agent Guide ─────────────────────────────────────────────────────── */
+  .agent-code {
+    background: rgba(0,0,0,.04); border: 1px solid var(--border);
+    border-radius: 6px; padding: 14px 16px; font-family: var(--mono);
+    font-size: 11px; line-height: 1.65; overflow-x: auto;
+    margin: 8px 0 16px; white-space: pre-wrap;
+  }
+
+  /* ─ DESIGN.md ───────────────────────────────────────────────────────── */
+  .designmd-section pre {
+    background: #0f0f0f; color: #e5e7eb; padding: 28px;
+    border-radius: var(--radius); font-family: var(--mono);
+    font-size: 12px; line-height: 1.7; overflow: auto;
+    max-height: 520px; white-space: pre-wrap;
+  }
+  .copy-btn {
+    display: inline-flex; align-items: center; gap: 6px;
+    margin-bottom: 12px; padding: 8px 18px;
+    background: var(--accent); color: ${contrastColor(accentHex)};
+    border: none; border-radius: 99px; font-size: 13px; font-weight: 600;
+    cursor: pointer; font-family: var(--font); transition: opacity .15s;
+  }
+  .copy-btn:hover { opacity: .85; }
+
+  /* ─ Footer ──────────────────────────────────────────────────────────── */
+  .site-footer { padding-top: 32px; border-top: 1px solid var(--border); font-size: 12px; opacity: .4; text-align: center; }
+
+  /* ─ Responsive ──────────────────────────────────────────────────────── */
+  @media (max-width: 900px) {
+    .app-layout { flex-direction: column; padding: 0 16px; }
+    .nav-sidebar { position: static; width: 100%; }
+    .nav-sidebar-inner { display: flex; flex-wrap: wrap; padding: 8px; gap: 4px; }
+    .nav-brand { display: none; }
+    .nav-link { padding: 5px 10px; border-radius: 99px; opacity: .7; }
+    .nav-link.active { background: var(--accent); color: ${contrastColor(accentHex)}; opacity: 1; }
+  }
+  @media (max-width: 600px) {
+    .header-screenshot.desktop img { width: 100%; }
+    .swatch { width: calc(50% - 5px); }
+    .dos-donts-grid { grid-template-columns: 1fr; }
+    .typo-preview-cell { max-width: 160px; }
+  }
+`;
+}
+
+// ── Section: Color Palette ─────────────────────────────────────────────────────
+
+function buildColorSection(tokens: any, brandOverrides: Map<string, string>, rawData?: any): string {
+  const c = tokens.colors || {};
+
+  interface SwatchItem { name: string; hex: string; raw: string; use: string; role?: string }
+  const cats: Array<{ label: string; id: string; items: SwatchItem[] }> = [];
+
+  function collectCat(label: string, id: string, obj: Record<string, string | null>, useMap: Record<string, string>, roleMap?: Record<string, string>) {
+    const items: SwatchItem[] = [];
+    for (const [key, val] of Object.entries(obj)) {
+      if (!val || val === 'transparent' || val.includes('transparent')) continue;
+      const hex = rgbToHex(val);
+      if (hex === '#transparent') continue;
+      const override = brandOverrides.get(hex);
+      const name = override || key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase());
+      items.push({ name, hex, raw: val, use: useMap[key] || '', role: roleMap?.[key] });
+    }
+    if (items.length) cats.push({ label, id, items });
+  }
+
+  collectCat('Background & Surface', 'bg', c.background || {}, { primary: 'Page bg', secondary: 'Elevated', tertiary: 'Card bg' });
+  collectCat('Text & Content',        'text', c.text     || {}, { primary: 'Body text', secondary: 'Secondary', muted: 'Muted / Placeholder' });
+  collectCat('Accent & Interactive',  'accent', c.accent || {}, { primary: 'Primary CTA', secondary: 'Secondary CTA' });
+  if (c.border) {
+    collectCat('Border & Divider', 'border', { border: c.border }, { border: 'Dividers / Lines' });
+  }
+
+  // Semantic colors
+  if (c.semantic && Object.keys(c.semantic).length > 0) {
+    const sem = c.semantic as Record<string, string>;
+    const roleMap: Record<string, string> = {
+      error: '⚠ Error', success: '✓ Success', warning: '! Warning', info: 'ℹ Info'
+    };
+    collectCat('Semantic States', 'semantic', sem,
+      { error: 'Errors, destructive', success: 'Success, positive', warning: 'Caution', info: 'Informative' },
+      roleMap
+    );
+  }
+
+  // v9-color: Full Extracted Palette — surface ALL real colors from the live capture,
+  // not just the capped categorized roles above. Sources: rawData.allColors (rendered
+  // element colors) ∪ color values inside CSS custom properties (sites like theverge keep
+  // their palette in token vars, not on elements). rgbToHex handles hex + rgb(); junk and
+  // already-shown colors are skipped. Mirrors the DESIGN.md fix so the public site reflects it.
+  const shownHexes = new Set<string>();
+  for (const cat of cats) for (const it of cat.items) shownHexes.add(it.hex.toLowerCase());
+
+  const paletteCandidates: string[] = [];
+  if (rawData) {
+    if (Array.isArray(rawData.allColors)) paletteCandidates.push(...rawData.allColors);
+    for (const v of Object.values(rawData.cssCustomProperties || {})) {
+      const val = String(v).trim();
+      if (!val || val.startsWith('var(')) continue;
+      const m = val.match(/#[0-9a-fA-F]{6}\b|rgba?\([^)]+\)/g);
+      if (m) paletteCandidates.push(...m);
+    }
+  }
+  const extraSwatches: { hex: string; raw: string }[] = [];
+  const extraSeen = new Set<string>(shownHexes);
+  for (const cand of paletteCandidates) {
+    const s = String(cand).trim();
+    if (!/^#[0-9a-fA-F]{3,8}$/.test(s) && !/^rgba?\(/.test(s)) continue;
+    const hex = rgbToHex(s);
+    if (!/^#[0-9a-f]{6}$/.test(hex)) continue;
+    if (extraSeen.has(hex)) continue;
+    extraSeen.add(hex);
+    extraSwatches.push({ hex, raw: s });
+  }
+  if (extraSwatches.length > 0) {
+    cats.push({
+      label: `Full Extracted Palette (+${extraSwatches.length})`,
+      id: 'full-palette',
+      items: extraSwatches.slice(0, 40).map(e => ({ name: e.hex, hex: e.hex, raw: e.raw, use: '' })),
+    });
+  }
+
+  const swatchHtml = cats.map(cat => `
+    <div class="color-group">
+      <h3>${escapeHtml(cat.label)}</h3>
+      <div class="swatches">
+        ${cat.items.map(col => {
+          const fg = contrastColor(col.hex);
+          return `<div class="swatch" style="background:${escapeHtml(col.raw)};color:${fg}" onclick="copySwatch(this,'${escapeHtml(col.hex)}')" title="Click to copy ${escapeHtml(col.hex)}">
+            ${col.role ? `<span class="swatch-role" style="color:${fg}">${escapeHtml(col.role)}</span>` : ''}
+            <span class="swatch-name">${escapeHtml(col.name)}</span>
+            <span class="swatch-hex">${escapeHtml(col.hex)}</span>
+            ${col.use ? `<span class="swatch-use">${escapeHtml(col.use)}</span>` : ''}
+            <span class="swatch-copied">Copied!</span>
+          </div>`;
+        }).join('')}
+      </div>
+    </div>`).join('');
+
+  const totalShown = cats.reduce((n, cat) => n + cat.items.length, 0);
+  return `<section class="section" id="s-colors">
+    <h2>Color Palette</h2>
+    <p class="section-desc">${totalShown} colors extracted via getComputedStyle(). Click any swatch to copy its hex value.</p>
+    ${swatchHtml}
+  </section>`;
+}
+
+// ── Section: Typography ────────────────────────────────────────────────────────
+
+function buildTypoSection(tokens: any, designMd: string): string {
+  const primaryFont  = (tokens.typography?.fontFamily?.primary  || 'system-ui').replace(/['"]/g, '');
+  const secondaryFont= (tokens.typography?.fontFamily?.secondary || primaryFont).replace(/['"]/g, '');
+
+  // Parse typography table from DESIGN.md §3
+  const tableMatch = designMd.match(/## 3\. Typography Rules[\s\S]*?\| Role \|([\s\S]*?)(?=\n##|\n---)/);
+
+  if (tableMatch) {
+    const lines = tableMatch[0].split('\n')
+      .filter(l => l.startsWith('|') && !l.includes('---') && !l.includes('| Role |'));
+
+    const rows = lines.map(line => {
+      const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+      if (cells.length < 3) return '';
+      const [role, font, size, weight, lh, ls] = cells;
+      const safeFont = (font || primaryFont).replace(/['"]/g, '');
+      const safeSize = size || '14px';
+      const safeWeight = weight || '400';
+      const lhDisplay = lh && lh !== '-' ? lh : '—';
+      const lsDisplay = ls && ls !== '-' ? ls : '—';
+
+      return `<tr>
+        <td class="typo-role-cell">${escapeHtml(role || '')}</td>
+        <td class="typo-spec-cell">${escapeHtml(safeFont)}</td>
+        <td class="typo-spec-cell">${escapeHtml(safeSize)} / w${escapeHtml(safeWeight)}</td>
+        <td class="typo-spec-cell">${escapeHtml(lhDisplay)}</td>
+        <td class="typo-spec-cell">${escapeHtml(lsDisplay)}</td>
+        <td class="typo-preview-cell" style="font-size:${escapeHtml(safeSize)};font-weight:${escapeHtml(safeWeight)};font-family:'${escapeHtml(safeFont)}',sans-serif;line-height:${lhDisplay !== '—' ? escapeHtml(lhDisplay) : '1.3'};letter-spacing:${lsDisplay !== '—' ? escapeHtml(lsDisplay) : 'normal'}">
+          ${escapeHtml(role || 'Sample')}
+        </td>
+      </tr>`;
+    }).filter(Boolean).join('');
+
+    return `<section class="section" id="s-typography">
+      <h2>Typography</h2>
+      <p class="section-desc">All values extracted via getComputedStyle() — no estimation.</p>
+      <div style="overflow-x:auto">
+        <table class="typo-table">
+          <thead>
+            <tr>
+              <th>Role</th><th>Font Family</th><th>Size / Weight</th>
+              <th>Line Height</th><th>Letter Spacing</th><th>Preview</th>
+            </tr>
+          </thead>
+          <tbody>${rows}</tbody>
+        </table>
+      </div>
+    </section>`;
+  }
+
+  // Fallback: font size scale
+  const sizes = tokens.typography?.fontSize || {};
+  const fontEntries = Object.entries(sizes)
+    .filter(([, v]) => v && (v as string).includes('px'))
+    .sort(([, a], [, b]) => parseFloat(b as string) - parseFloat(a as string));
+
+  const rows = fontEntries.map(([k, v]) =>
+    `<tr>
+      <td class="typo-role-cell">${escapeHtml(k)}</td>
+      <td class="typo-spec-cell">${escapeHtml(primaryFont)}</td>
+      <td class="typo-spec-cell">${escapeHtml(v as string)}</td>
+      <td class="typo-spec-cell">—</td>
+      <td class="typo-spec-cell">—</td>
+      <td class="typo-preview-cell" style="font-size:${escapeHtml(v as string)};font-family:'${escapeHtml(primaryFont)}',sans-serif">
+        ${escapeHtml(k)} specimen
+      </td>
+    </tr>`
+  ).join('');
+
+  return `<section class="section" id="s-typography">
+    <h2>Typography</h2>
+    <div style="overflow-x:auto">
+      <table class="typo-table">
+        <thead><tr><th>Scale</th><th>Font</th><th>Size</th><th>LH</th><th>LS</th><th>Preview</th></tr></thead>
+        <tbody>${rows}</tbody>
+      </table>
+    </div>
+  </section>`;
+}
+
+// ── Section: Live Components ───────────────────────────────────────────────────
+
+function buildLiveComponentsSection(tokens: any): string {
+  const c  = tokens.colors    || {};
+  const ty = tokens.typography || {};
+  const br = tokens.borderRadius || {};
+
+  const accent    = c.accent?.primary     || '#0070f3';
+  const accentFg  = contrastColor(rgbToHex(accent));
+  const bg        = c.background?.primary || '#ffffff';
+  const bgAlt     = c.background?.secondary || '#f5f5f5';
+  const border    = c.border               || '#e5e5e5';
+  const textPrim  = c.text?.primary        || '#111111';
+  const textMuted = c.text?.muted          || '#888888';
+  const radius    = br.sm                  || br.md || '6px';
+  const radiusFull= br.full               || '9999px';
+  const font      = ty.fontFamily?.primary || 'system-ui';
+  const fw        = ty.fontWeight;
+  const fwBold    = fw?.bold    || '700';
+  const fwMedium  = fw?.medium  || '500';
+  const fwNormal  = fw?.normal  || '400';
+
+  const sharedBtnStyle = `font-family:'${font}',system-ui;cursor:pointer;font-size:14px;transition:opacity .15s;`;
+
+  const btnPrimary  = `style="${sharedBtnStyle}padding:10px 20px;background:${accent};color:${accentFg};border:none;border-radius:${radiusFull};font-weight:${fwBold};"`;
+  const btnSecondary= `style="${sharedBtnStyle}padding:10px 20px;background:transparent;color:${accent};border:2px solid ${accent};border-radius:${radiusFull};font-weight:${fwMedium};"`;
+  const btnGhost    = `style="${sharedBtnStyle}padding:10px 20px;background:transparent;color:${textPrim};border:1px solid ${border};border-radius:${radius};font-weight:${fwNormal};"`;
+  const btnDisabled = `style="${sharedBtnStyle}padding:10px 20px;background:${bgAlt};color:${textMuted};border:1px solid ${border};border-radius:${radiusFull};font-weight:${fwNormal};opacity:.5;cursor:not-allowed;"`;
+
+  const inputStyle = `style="padding:10px 14px;background:${bg};color:${textPrim};border:1.5px solid ${border};border-radius:${radius};font-size:14px;font-family:'${font}',system-ui;outline:none;width:260px;"`;
+  const inputFocusStyle = `style="padding:10px 14px;background:${bg};color:${textPrim};border:2px solid ${accent};border-radius:${radius};font-size:14px;font-family:'${font}',system-ui;outline:none;width:260px;"`;
+
+  const shadow = tokens.shadows ? Object.values(tokens.shadows)[0] as string || 'none' : 'none';
+  const cardStyle = `style="background:${bgAlt};border:1px solid ${border};border-radius:${br.md || '10px'};padding:20px 24px;max-width:300px;box-shadow:${shadow};"`;
+
+  const badgeStyle     = `style="display:inline-block;padding:3px 10px;background:${accent};color:${accentFg};border-radius:${radiusFull};font-size:11px;font-weight:${fwBold};font-family:'${font}',system-ui;"`;
+  const badgeNeutralSt = `style="display:inline-block;padding:3px 10px;background:${bgAlt};color:${textMuted};border:1px solid ${border};border-radius:${radiusFull};font-size:11px;font-weight:${fwMedium};font-family:'${font}',system-ui;"`;
+
+  return `<section class="section" id="s-components">
+    <h2>Live Components</h2>
+    <p class="section-desc">Rendered in real HTML using your extracted tokens — no screenshots.</p>
+    <div class="live-components-grid">
+
+      <div class="live-component-group">
+        <h3>Buttons</h3>
+        <div class="live-demo-row">
+          <button ${btnPrimary}>Primary CTA</button>
+          <button ${btnSecondary}>Secondary</button>
+          <button ${btnGhost}>Ghost / Text</button>
+          <button ${btnDisabled} disabled>Disabled</button>
+        </div>
+        <span class="live-demo-label">accent: ${escapeHtml(accent)} · border-radius: ${escapeHtml(radiusFull)} · weight: ${escapeHtml(fwBold)}</span>
+      </div>
+
+      <div class="live-component-group">
+        <h3>Form Inputs</h3>
+        <div class="live-demo-row">
+          <input ${inputStyle} type="text" placeholder="Default input..." />
+          <input ${inputFocusStyle} type="text" value="Focused input" />
+        </div>
+        <span class="live-demo-label">border: ${escapeHtml(border)} · focus: ${escapeHtml(accent)} · radius: ${escapeHtml(radius)}</span>
+      </div>
+
+      <div class="live-component-group">
+        <h3>Card</h3>
+        <div class="live-demo-row" style="background:${escapeHtml(bg)}">
+          <div ${cardStyle}>
+            <div style="font-size:12px;font-weight:${fwBold};letter-spacing:.06em;text-transform:uppercase;opacity:.4;margin-bottom:10px;font-family:'${escapeHtml(font)}',system-ui">Card Component</div>
+            <div style="font-size:16px;font-weight:${fwBold};margin-bottom:8px;color:${escapeHtml(textPrim)};font-family:'${escapeHtml(font)}',system-ui">Card Title</div>
+            <div style="font-size:13px;color:${escapeHtml(textMuted)};line-height:1.55;font-family:'${escapeHtml(font)}',system-ui">Supporting description text with muted color for secondary information.</div>
+            <div style="margin-top:16px"><button style="${sharedBtnStyle}padding:8px 16px;background:${accent};color:${accentFg};border:none;border-radius:${radiusFull};font-weight:${fwBold};font-size:13px;">Action</button></div>
+          </div>
+        </div>
+        <span class="live-demo-label">bg: ${escapeHtml(bgAlt)} · radius: ${escapeHtml(br.md || '10px')} · shadow from tokens</span>
+      </div>
+
+      <div class="live-component-group">
+        <h3>Badges & Labels</h3>
+        <div class="live-demo-row">
+          <span ${badgeStyle}>New</span>
+          <span ${badgeStyle}>Feature</span>
+          <span ${badgeNeutralSt}>Beta</span>
+          <span ${badgeNeutralSt}>Draft</span>
+        </div>
+      </div>
+
+    </div>
+  </section>`;
+}
+
+// ── Section: Spacing & Radius ──────────────────────────────────────────────────
+
+function buildSpacingSection(tokens: any): string {
+  const spacing = tokens.spacing || {};
+  const radius  = tokens.borderRadius || {};
+
+  const spacingBars = Object.entries(spacing)
+    .filter(([, v]) => v && (v as string).includes('px'))
+    .map(([k, v]) => {
+      const px = parseFloat(v as string);
+      return `<div class="token-row">
+        <span class="token-name">${escapeHtml(k)}</span>
+        <span class="token-bar-wrap"><span class="token-bar" style="width:${Math.min(px * 3, 280)}px"></span></span>
+        <span class="token-value">${escapeHtml(v as string)}</span>
+      </div>`;
+    }).join('');
+
+  const radiusItems = Object.entries(radius)
+    .filter(([, v]) => v)
+    .map(([k, v]) => {
+      const displayV = v as string;
+      const r = displayV === '9999px' ? '50%' : displayV;
+      return `<div class="radius-item">
+        <div class="radius-box" style="border-radius:${r}"></div>
+        <span class="radius-label">${escapeHtml(k)}<br><small>${escapeHtml(displayV)}</small></span>
+      </div>`;
+    }).join('');
+
+  return `<section class="section" id="s-spacing">
+    <h2>Spacing Scale</h2>
+    <div class="token-list">${spacingBars}</div>
+    <h2>Border Radius</h2>
+    <div class="radius-row">${radiusItems}</div>
+  </section>`;
+}
+
+// ── Section: Component Specs (from DESIGN.md) ─────────────────────────────────
+
+function buildComponentSpecsSection(designMd: string): string {
+  const match = designMd.match(/## 4\. Component Stylings([\s\S]*?)(?=\n## 5\.|\n---)/);
+  if (!match) return '';
+  const raw = match[1].trim();
+  const groups = raw.split(/\n### /).filter(Boolean);
+  const html = groups.map(group => {
+    const [header, ...rest] = group.split('\n');
+    const specs = rest.join('\n');
+    const variants = specs.split(/\n\*\*/).filter(Boolean).map(v => {
+      const [nameLine, ...props] = v.split('\n');
+      const name = nameLine.replace(/\*\*/g, '').trim();
+      const propHtml = props.filter(p => p.trim().startsWith('-'))
+        .map(p => `<li>${escapeHtml(p.replace(/^- /, '').trim())}</li>`).join('');
+      return `<div class="component-variant">
+          <strong>${escapeHtml(name)}</strong>
+          <ul>${propHtml}</ul>
+        </div>`;
+    }).join('');
+    return `<div class="component-group">
+      <h3>${escapeHtml((header || '').replace(/\*\*/g, '').trim())}</h3>
+      <div class="variants-grid">${variants}</div>
+    </div>`;
+  }).join('');
+
+  return `<section class="section" id="s-specs">
+    <h2>Component Specs</h2>
+    <p class="section-desc">Extracted CSS values per component and variant state.</p>
+    ${html}
+  </section>`;
+}
+
+// ── Section: Visual Match ──────────────────────────────────────────────────────
+
+function buildVisualMatchSection(desktopUrl: string | null, mobileUrl: string | null): string {
+  if (!desktopUrl && !mobileUrl) return '';
+
+  const items = [
+    desktopUrl ? { label: 'Desktop (1440px)', url: desktopUrl } : null,
+    mobileUrl  ? { label: 'Mobile (390px)',   url: mobileUrl  } : null,
+  ].filter(Boolean) as Array<{ label: string; url: string }>;
+
+  const cards = items.map(item => `
+    <div class="visual-match-item">
+      <div class="visual-match-label">${escapeHtml(item.label)}</div>
+      <div class="visual-match-frame">
+        <img src="${item.url}" alt="${escapeHtml(item.label)} screenshot" loading="lazy">
+      </div>
+    </div>`).join('');
+
+  return `<section class="section" id="s-visual">
+    <h2>Visual Reference</h2>
+    <p class="section-desc">Playwright screenshots captured during extraction — source of truth for all tokens.</p>
+    <div class="visual-match-grid">${cards}</div>
+  </section>`;
+}
+
+// ── Section: Breakpoints ───────────────────────────────────────────────────────
+
+function buildBreakpointsSection(designMd: string): string {
+  const match = designMd.match(/### Breakpoints\n\| Name \| Width \|([\s\S]*?)(?=\n###|\n##)/);
+  if (!match) return '';
+  const lines = match[0].split('\n').filter(l => l.startsWith('|') && !l.includes('---') && !l.includes('Name'));
+  const maxWidth = 1440;
+  const bars = lines.map(line => {
+    const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+    if (cells.length < 2) return '';
+    const [name, width] = cells;
+    const px = parseFloat(width || '0');
+    const pct = Math.round((px / maxWidth) * 100);
+    return `<div class="bp-row">
+        <span class="bp-name">${escapeHtml(name || '')}</span>
+        <span class="bp-bar-wrap"><span class="bp-bar" style="width:${pct}%"></span></span>
+        <span class="bp-value">${escapeHtml(width || '')}</span>
+      </div>`;
+  }).join('');
+
+  return `<section class="section" id="s-breakpoints">
+    <h2>Breakpoints</h2>
+    <div class="bp-list">${bars}</div>
+  </section>`;
+}
+
+// ── Section: Elevation ─────────────────────────────────────────────────────────
+
+function buildElevationSection(tokens: any): string {
+  const shadows = tokens.shadows || {};
+  const shadowEntries = Object.entries(shadows).filter(([, v]) => v && v !== 'none') as [string, string][];
+  if (shadowEntries.length === 0) return '';
+
+  const cards = shadowEntries.map(([name, shadow]) => {
+    const label = name.replace(/shadow-?/i, 'Level ').replace(/^(\w)/, c => c.toUpperCase());
+    const truncated = shadow.length > 80 ? shadow.slice(0, 80) + '…' : shadow;
+    return `<div class="elev-card" style="box-shadow:${shadow}">
+      <div class="elev-label">${escapeHtml(label)}</div>
+      <code class="elev-code">${escapeHtml(truncated)}</code>
+    </div>`;
+  }).join('');
+
+  return `<section class="section" id="s-elevation">
+    <h2>Elevation &amp; Depth</h2>
+    <p class="section-desc">Shadow levels rendered live — every value extracted directly from the design system.</p>
+    <div class="elev-grid">${cards}</div>
+  </section>`;
+}
+
+// ── Section: Motion ────────────────────────────────────────────────────────────
+
+// v4-V2-T1: Motion Timeline — live preview animations from extracted keyframes
+function buildMotionTimelineSection(rawData: any): string {
+  if (!rawData) return '';
+  const keyframes = rawData.keyframes || {};
+  const animNames = Object.keys(keyframes);
+  if (animNames.length === 0) return '';
+
+  // Build CSS @keyframes from extracted data
+  const cssRules: string[] = [];
+  const previewItems: string[] = [];
+
+  const shown = animNames.slice(0, 12); // cap at 12 for performance
+  for (const name of shown) {
+    const frames = keyframes[name];
+    if (!frames || typeof frames !== 'object') continue;
+    const keyframeBody = Object.entries(frames)
+      .map(([key, props]: any) => {
+        const propsStr = Object.entries(props || {})
+          .map(([p, v]: any) => `${p}: ${v};`)
+          .join(' ');
+        return `${key} { ${propsStr} }`;
+      })
+      .join('\n');
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    cssRules.push(`@keyframes ca-preview-${safeName} {\n${keyframeBody}\n}`);
+    previewItems.push(`
+      <div style="display:flex;flex-direction:column;align-items:center;gap:8px;padding:16px;background:rgba(0,0,0,.03);border-radius:8px;">
+        <div class="anim-box" data-anim="${safeName}" style="width:48px;height:48px;background:linear-gradient(135deg,#10b981,#0ea5e9);border-radius:6px;animation:ca-preview-${safeName} 2s ease-in-out infinite;"></div>
+        <code style="font-size:11px;font-family:var(--mono);">${escapeHtml(name)}</code>
+      </div>`);
+  }
+
+  return `<section class="section" id="s-motion-timeline">
+    <h2>Motion Timeline</h2>
+    <p class="section-desc">${animNames.length} keyframe animation${animNames.length > 1 ? 's' : ''} extracted from the live page. Preview ${shown.length} below — each block is animating right now with the actual extracted keyframes.</p>
+    <style>${cssRules.join('\n')}</style>
+    <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(140px,1fr));gap:12px;margin:16px 0;">${previewItems.join('')}</div>
+    ${animNames.length > 12 ? `<p style="font-size:12px;color:var(--fg-muted);">+${animNames.length - 12} additional animations not previewed (cap at 12 for performance).</p>` : ''}
+  </section>`;
+}
+
+// v4-V2-T2: Component State Machine — default/hover/focus/active per element
+function buildComponentStatesSection(rawData: any): string {
+  if (!rawData) return '';
+  const states = rawData.componentStates || {};
+  const components = Object.keys(states);
+  if (components.length === 0) return '';
+
+  const rows: string[] = [];
+  for (const comp of components.slice(0, 5)) {
+    const compStates = states[comp];
+    if (!compStates || typeof compStates !== 'object') continue;
+    const stateKeys = Object.keys(compStates).filter(s => compStates[s]);
+    if (stateKeys.length === 0) continue;
+
+    const stateCells = stateKeys.map(state => {
+      const s = compStates[state] || {};
+      const bg = s.backgroundColor || 'transparent';
+      const fg = s.color || 'inherit';
+      const border = s.border || 'none';
+      const shadow = (s.boxShadow || 'none').slice(0, 60);
+      return `<td style="vertical-align:top;padding:8px;border:1px solid var(--border);">
+        <div style="font-weight:600;font-size:11px;text-transform:uppercase;letter-spacing:.5px;margin-bottom:6px;color:var(--fg-muted);">${state}</div>
+        <div style="display:inline-block;padding:6px 12px;background:${bg};color:${fg};border:${border};border-radius:${s.borderRadius || '4px'};font-size:12px;box-shadow:${shadow};">${comp}</div>
+        <div style="font-size:10px;font-family:var(--mono);margin-top:6px;color:var(--fg-muted);">bg ${bg}<br>fg ${fg}</div>
+      </td>`;
+    }).join('');
+
+    rows.push(`<tr><td style="padding:8px;font-weight:600;text-transform:capitalize;border:1px solid var(--border);">${comp}</td>${stateCells}</tr>`);
+  }
+
+  if (rows.length === 0) return '';
+
+  return `<section class="section" id="s-states">
+    <h2>Component States</h2>
+    <p class="section-desc">Default → Hover → Focus → Active visual diff per component. Captured via Playwright state simulation.</p>
+    <div style="overflow-x:auto;">
+      <table style="border-collapse:collapse;width:100%;font-size:12px;">
+        <thead>
+          <tr>
+            <th style="padding:8px;text-align:left;border:1px solid var(--border);">Component</th>
+            <th style="padding:8px;text-align:left;border:1px solid var(--border);">States</th>
+          </tr>
+        </thead>
+        <tbody>${rows}</tbody>
+      </table>
+    </div>
+  </section>`;
+}
+
+// v4-V2-T3: Z-Index Stacking Context Heatmap
+function buildZIndexHeatmapSection(rawData: any): string {
+  if (!rawData) return '';
+  const zMap = rawData.zIndexMap || [];
+  if (!Array.isArray(zMap) || zMap.length === 0) return '';
+
+  // Sort by z desc
+  const sorted = [...zMap].sort((a: any, b: any) => (b.z || 0) - (a.z || 0));
+  const maxZ = Math.max(...sorted.map((e: any) => e.z || 0));
+
+  const rows = sorted.slice(0, 20).map((entry: any) => {
+    const z = entry.z || 0;
+    const pct = maxZ > 0 ? Math.round((z / maxZ) * 100) : 0;
+    // Color tier
+    const tier = z >= 100 ? '#ef4444' : z >= 10 ? '#f59e0b' : '#10b981';
+    return `
+      <div style="display:flex;align-items:center;gap:12px;padding:6px 0;border-bottom:1px solid var(--border);">
+        <div style="width:60px;text-align:right;font-family:var(--mono);font-size:12px;color:${tier};font-weight:600;">z:${z}</div>
+        <div style="flex:1;background:rgba(0,0,0,.05);border-radius:3px;height:18px;position:relative;overflow:hidden;">
+          <div style="position:absolute;left:0;top:0;height:100%;width:${pct}%;background:${tier};opacity:.75;"></div>
+        </div>
+        <div style="flex:2;font-family:var(--mono);font-size:11px;color:var(--fg-muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">${escapeHtml((entry.selector || '?').slice(0, 80))}</div>
+      </div>`;
+  }).join('');
+
+  return `<section class="section" id="s-zindex">
+    <h2>Z-Index Stacking Context</h2>
+    <p class="section-desc">${zMap.length} z-index value${zMap.length > 1 ? 's' : ''} detected. Top 20 ordered by stacking priority. <span style="color:#ef4444">●</span> 100+ (modals) · <span style="color:#f59e0b">●</span> 10-99 (overlays) · <span style="color:#10b981">●</span> 1-9 (UI chrome).</p>
+    <div style="margin:16px 0;">${rows}</div>
+  </section>`;
+}
+
+// v4-V2-T4: Export buttons section — Copy as Tailwind/Figma/CSS vars
+function buildExportSection(tokens: any, domain: string): string {
+  // Build Tailwind config snippet
+  const tw: any = { theme: { extend: { colors: {}, fontFamily: {}, spacing: {}, borderRadius: {} } } };
+  const flattenColors = (obj: any, prefix = ''): void => {
+    for (const [k, v] of Object.entries(obj || {})) {
+      if (typeof v === 'string') tw.theme.extend.colors[prefix + k] = v;
+      else if (typeof v === 'object') flattenColors(v, prefix + k + '-');
+    }
+  };
+  flattenColors(tokens.colors || {});
+  Object.assign(tw.theme.extend.fontFamily, {
+    sans: [tokens.typography?.fontFamily?.primary || 'system-ui', 'sans-serif'],
+    mono: [tokens.typography?.fontFamily?.mono || 'monospace'],
+  });
+  Object.assign(tw.theme.extend.spacing, tokens.spacing || {});
+  Object.assign(tw.theme.extend.borderRadius, tokens.borderRadius || {});
+
+  const twJson = JSON.stringify(tw, null, 2);
+  const twCode = `// tailwind.config.js — generated from ${domain} by Prism\nmodule.exports = ${twJson};`;
+
+  // Build Figma tokens JSON (Figma Tokens plugin format)
+  const figmaTokens: any = { colors: {}, typography: {}, spacing: {}, radius: {} };
+  flattenColors(tokens.colors || {});
+  for (const [k, v] of Object.entries(tokens.colors?.background || {})) {
+    figmaTokens.colors['bg-' + k] = { value: v, type: 'color' };
+  }
+  for (const [k, v] of Object.entries(tokens.colors?.text || {})) {
+    figmaTokens.colors['text-' + k] = { value: v, type: 'color' };
+  }
+  for (const [k, v] of Object.entries(tokens.spacing || {})) {
+    figmaTokens.spacing[k] = { value: v, type: 'spacing' };
+  }
+  for (const [k, v] of Object.entries(tokens.borderRadius || {})) {
+    figmaTokens.radius[k] = { value: v, type: 'borderRadius' };
+  }
+  const figmaJson = JSON.stringify(figmaTokens, null, 2);
+
+  // Build CSS :root vars
+  const cssLines: string[] = [':root {'];
+  cssLines.push(`  /* ${domain} — extracted by Prism */`);
+  const flatCss = (obj: any, prefix = '--ca'): void => {
+    for (const [k, v] of Object.entries(obj || {})) {
+      if (typeof v === 'string') cssLines.push(`  ${prefix}-${k}: ${v};`);
+      else if (typeof v === 'object') flatCss(v, prefix + '-' + k);
+    }
+  };
+  flatCss(tokens.colors || {}, '--ca-color');
+  flatCss(tokens.spacing || {}, '--ca-spacing');
+  flatCss(tokens.borderRadius || {}, '--ca-radius');
+  cssLines.push('}');
+  const cssCode = cssLines.join('\n');
+
+  // Encode each safely for inline JS (base64 to avoid escape headaches)
+  const b64 = (s: string) => Buffer.from(s, 'utf-8').toString('base64');
+
+  return `<section class="section" id="s-export">
+    <h2>Export tokens</h2>
+    <p class="section-desc">Copy these design tokens to any framework. Generated from <code>${escapeHtml(domain)}</code> live extraction.</p>
+    <div style="display:flex;gap:12px;flex-wrap:wrap;margin:16px 0;">
+      <button class="export-btn" data-payload="${b64(twCode)}" data-filename="tailwind.config.js" style="padding:10px 18px;border-radius:8px;background:#10b981;color:#fff;border:none;font-weight:600;font-size:13px;cursor:pointer;display:flex;align-items:center;gap:8px;">
+        <span>⬇️</span> Tailwind config
+      </button>
+      <button class="export-btn" data-payload="${b64(figmaJson)}" data-filename="figma-tokens.json" style="padding:10px 18px;border-radius:8px;background:#a259ff;color:#fff;border:none;font-weight:600;font-size:13px;cursor:pointer;display:flex;align-items:center;gap:8px;">
+        <span>⬇️</span> Figma tokens
+      </button>
+      <button class="export-btn" data-payload="${b64(cssCode)}" data-filename="tokens.css" style="padding:10px 18px;border-radius:8px;background:#0ea5e9;color:#fff;border:none;font-weight:600;font-size:13px;cursor:pointer;display:flex;align-items:center;gap:8px;">
+        <span>⬇️</span> CSS variables
+      </button>
+    </div>
+    <p style="font-size:12px;color:var(--fg-muted);margin-top:8px;">
+      Clicks copy to clipboard AND download the file. All values from <code>getComputedStyle()</code> on the live page — no estimates.
+    </p>
+    <script>
+    document.querySelectorAll('.export-btn').forEach(btn => {
+      btn.addEventListener('click', () => {
+        const payload = atob(btn.dataset.payload);
+        const filename = btn.dataset.filename;
+        // Copy to clipboard
+        navigator.clipboard.writeText(payload).then(() => {
+          const orig = btn.innerHTML;
+          btn.innerHTML = '<span>✓</span> Copied!';
+          setTimeout(() => { btn.innerHTML = orig; }, 1500);
+        });
+        // Also download as file
+        const blob = new Blob([payload], { type: 'text/plain' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url; a.download = filename;
+        document.body.appendChild(a); a.click(); document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+      });
+    });
+    </script>
+  </section>`;
+}
+
+function buildMotionSection(tokens: any): string {
+  const cssVars = tokens.cssCustomProperties || {};
+  const motionVars = Object.entries(cssVars)
+    .filter(([k]) => /--motion-|--transition-|--duration-|--ease-|--spring/i.test(k))
+    .filter(([, v]) => typeof v === 'string' && !(v as string).trim().startsWith('var('))
+    .slice(0, 20) as [string, string][];
+
+  const transitions = tokens.transitions || {};
+  const transEntries = Object.entries(transitions) as [string, string][];
+
+  if (motionVars.length === 0 && transEntries.length === 0) return '';
+
+  const dataVars = motionVars.length > 0 ? motionVars : transEntries;
+  const rows = dataVars.map(([k, v]) => {
+    const displayVal = (v as string).length > 70 ? (v as string).slice(0, 70) + '…' : v as string;
+    return `<tr><td style="opacity:.55;font-family:var(--mono);white-space:nowrap">${escapeHtml(k)}</td><td><code style="font-size:11px">${escapeHtml(displayVal)}</code></td></tr>`;
+  }).join('');
+
+  return `<section class="section" id="s-motion">
+    <h2>Motion &amp; Transitions</h2>
+    <p class="section-desc">${dataVars.length} motion tokens — easing curves and durations.</p>
+    <table class="motion-table">${rows}</table>
+  </section>`;
+}
+
+// ── Section: Do's & Don'ts ─────────────────────────────────────────────────────
+
+function buildDosDontSection(designMd: string): string {
+  const sectionMatch = designMd.match(/## 7\. Do's and Don'ts\n([\s\S]*?)(?=\n## \d+\.|$)/);
+  if (!sectionMatch) return '';
+  const section = sectionMatch[1];
+  const dosMatch   = section.match(/### Do\n([\s\S]*?)(?=### Don|$)/);
+  const dontsMatch = section.match(/### Don't\n([\s\S]*?)(?=### |$)/);
+  if (!dosMatch && !dontsMatch) return '';
+
+  function parseListItems(text: string): string[] {
+    return text.split('\n').filter(l => l.trim().startsWith('- ')).map(l => l.replace(/^- /, '').trim()).filter(l => l.length > 0);
+  }
+  const dos   = dosMatch   ? parseListItems(dosMatch[1])   : [];
+  const donts = dontsMatch ? parseListItems(dontsMatch[1]) : [];
+  if (dos.length === 0 && donts.length === 0) return '';
+
+  const doItems   = dos.map(d   => `<li class="do-item">  <span class="do-icon">✓</span>${escapeHtml(d)}</li>`).join('');
+  const dontItems = donts.map(d => `<li class="dont-item"><span class="dont-icon">✕</span>${escapeHtml(d)}</li>`).join('');
+
+  return `<section class="section" id="s-dosdonts">
+    <h2>Do's &amp; Don'ts</h2>
+    <div class="dos-donts-grid">
+      ${dos.length > 0 ? `<div class="do-col"><div class="do-header">✓ Do</div><ul class="do-list">${doItems}</ul></div>` : ''}
+      ${donts.length > 0 ? `<div class="dont-col"><div class="dont-header">✕ Don't</div><ul class="dont-list">${dontItems}</ul></div>` : ''}
+    </div>
+  </section>`;
+}
+
+// ── Section: Agent Guide ───────────────────────────────────────────────────────
+
+function buildAgentGuideSection(designMd: string): string {
+  const sectionMatch = designMd.match(/## 9\. Agent Prompt Guide\n([\s\S]*?)(?=\n## \d+\.|$)/);
+  if (!sectionMatch) return '';
+  const content = sectionMatch[1].trim();
+  if (!content) return '';
+
+  const lines = content.split('\n');
+  let html = '';
+  let inCode = false;
+  let codeBlock = '';
+
+  for (const line of lines) {
+    if (line.startsWith('```')) {
+      if (inCode) {
+        html += `<pre class="agent-code">${escapeHtml(codeBlock.trim())}</pre>`;
+        codeBlock = '';
+        inCode = false;
+      } else { inCode = true; }
+    } else if (inCode) {
+      codeBlock += line + '\n';
+    } else if (line.startsWith('### ')) {
+      html += `<h3 style="font-size:13px;font-weight:600;opacity:.65;margin:16px 0 8px">${escapeHtml(line.slice(4))}</h3>`;
+    } else if (line.startsWith('- ')) {
+      html += `<p style="font-size:13px;margin:4px 0;padding-left:16px">${escapeHtml(line.slice(2))}</p>`;
+    } else if (line.trim()) {
+      html += `<p style="font-size:13px;margin:6px 0;opacity:.8">${escapeHtml(line)}</p>`;
+    }
+  }
+
+  return `<section class="section" id="s-agent">
+    <h2>Agent Prompt Guide</h2>
+    <p class="section-desc">Ready-to-use prompts for Claude Code, Cursor, or Bolt — paste and build.</p>
+    ${html}
+  </section>`;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+
+async function generateShowcase(domain: string): Promise<void> {
+  const baseDir   = resolve(process.cwd(), 'extractions', domain);
+  const tokensPath   = join(baseDir, 'tokens.json');
+  const designMdPath = join(baseDir, 'DESIGN.md');
+  const outputDir    = join(baseDir, 'showcase');
+
+  console.log(`\n🎨 Generating showcase for ${domain}...`);
+
+  const tokens   = JSON.parse(await readFile(tokensPath, 'utf-8'));
+  const designMd = await readFile(designMdPath, 'utf-8');
+
+  // v4-V2: load raw-css for advanced sections (Motion Timeline, States, Z-Index)
+  const rawCssPath = join(baseDir, 'raw-css.json');
+  let rawDataDesktop: any = null;
+  try {
+    const rawAll = JSON.parse(await readFile(rawCssPath, 'utf-8'));
+    rawDataDesktop = rawAll.desktop || rawAll;
+  } catch { /* raw-css optional */ }
+
+  // v6: extract brand tagline from the hero text on the source page
+  // (h1 textContent if it's shorter than 120 chars, otherwise meta description)
+  let brandTagline = '';
+  if (rawDataDesktop) {
+    const heroEl = rawDataDesktop.elements?.heading;
+    const text = heroEl?.textContent || heroEl?.innerText || '';
+    if (text && text.length > 4 && text.length < 120) {
+      brandTagline = text.trim().replace(/\s+/g, ' ');
+    } else {
+      // fallback: meta description if available
+      const meta = rawDataDesktop.metaDescription || '';
+      if (meta && meta.length > 4 && meta.length < 160) {
+        brandTagline = meta.trim();
+      }
+    }
+  }
+
+  // v6: confidence score from DESIGN.md completeness
+  const completenessMatch = designMd.match(/Completeness: (\d+)\/100/);
+  const confidenceScore = completenessMatch ? parseInt(completenessMatch[1]) : 50;
+  const confidenceGrade =
+    confidenceScore >= 90 ? 'A' :
+    confidenceScore >= 75 ? 'B' :
+    confidenceScore >= 60 ? 'C' : 'D';
+
+  const dateMatch   = designMd.match(/Date: (.+)/);
+  const sourceMatch = designMd.match(/Source: (\S+)/);
+  const extractedDate = dateMatch?.[1]  || new Date().toLocaleDateString();
+  const sourceUrl     = sourceMatch?.[1] || `https://${domain}`;
+
+  // Brand palette overrides (--palette-WORD → brand name)
+  const brandOverrides = new Map<string, string>();
+  const cssVars = tokens.cssCustomProperties || {};
+  for (const [key, rawValue] of Object.entries(cssVars)) {
+    const match = key.match(/^--(palette|color)-([a-zA-Z]+)$/);
+    if (!match) continue;
+    const brandWord = match[2];
+    if (/^(primary|secondary|tertiary|bg|text|fg|background|border|divider|surface|accent|link|muted|error|warning|success|info|white|black|dark|light|base)$/i.test(brandWord)) continue;
+    const val = (rawValue as string).trim();
+    if (!/^#[0-9a-fA-F]{3,8}$/.test(val) && !/^rgba?\(/i.test(val)) continue;
+    const hex = rgbToHex(val);
+    if (!brandOverrides.has(hex)) {
+      brandOverrides.set(hex, brandWord.charAt(0).toUpperCase() + brandWord.slice(1).toLowerCase());
+    }
+  }
+
+  // Screenshots
+  const desktopUrl = await screenshotBase64(baseDir, false);
+  const mobileUrl  = await screenshotBase64(baseDir, true);
+
+  // Font faces from raw-css
+  const fontFaceCss = await loadFontFaces(baseDir);
+
+  // Build all sections
+  const cssStr           = buildCss(tokens);
+  const colorSection     = buildColorSection(tokens, brandOverrides, rawDataDesktop);
+  const typoSection      = buildTypoSection(tokens, designMd);
+  const spacingSection   = buildSpacingSection(tokens);
+  const liveComponents   = buildLiveComponentsSection(tokens);
+  const componentSpecs   = buildComponentSpecsSection(designMd);
+  const visualSection    = buildVisualMatchSection(desktopUrl, mobileUrl);
+  const breakpointsSection = buildBreakpointsSection(designMd);
+  const elevationSection = buildElevationSection(tokens);
+  const motionSection    = buildMotionSection(tokens);
+  // v4-V2: advanced sections from raw-css.json data
+  const motionTimelineSection = buildMotionTimelineSection(rawDataDesktop);
+  const componentStatesSection = buildComponentStatesSection(rawDataDesktop);
+  const zIndexSection    = buildZIndexHeatmapSection(rawDataDesktop);
+  const exportSection    = buildExportSection(tokens, domain);
+  const dosDontSection   = buildDosDontSection(designMd);
+  const agentSection     = buildAgentGuideSection(designMd);
+
+  // Nav items — only include sections that have content
+  const navItems = [
+    { id: 's-colors',      label: 'Colors',          icon: '●' },
+    { id: 's-typography',  label: 'Typography',       icon: 'T' },
+    { id: 's-components',  label: 'Live Components',  icon: '⬜' },
+    { id: 's-spacing',     label: 'Spacing & Radius', icon: '↔' },
+    ...(componentSpecs    ? [{ id: 's-specs',     label: 'Component Specs', icon: '⚙' }] : []),
+    ...(visualSection     ? [{ id: 's-visual',    label: 'Screenshots',     icon: '🖼' }] : []),
+    ...(breakpointsSection? [{ id: 's-breakpoints',label: 'Breakpoints',   icon: '⟺' }] : []),
+    ...(elevationSection  ? [{ id: 's-elevation',  label: 'Elevation',     icon: '◫' }] : []),
+    ...(motionSection     ? [{ id: 's-motion',     label: 'Motion',        icon: '→' }] : []),
+    ...(motionTimelineSection ? [{ id: 's-motion-timeline', label: 'Animation Timeline', icon: '◐' }] : []),
+    ...(componentStatesSection ? [{ id: 's-states', label: 'Component States', icon: '◑' }] : []),
+    ...(zIndexSection     ? [{ id: 's-zindex',    label: 'Z-Index Heatmap', icon: '⫝' }] : []),
+    ...(exportSection     ? [{ id: 's-export',     label: 'Export tokens', icon: '⬇' }] : []),
+    ...(dosDontSection    ? [{ id: 's-dosdonts',   label: "Do's & Don'ts", icon: '✓' }] : []),
+    ...(agentSection      ? [{ id: 's-agent',      label: 'Agent Guide',   icon: '🤖' }] : []),
+    { id: 's-designmd',    label: 'DESIGN.md',        icon: '</>' },
+  ];
+
+  const navHtml = navItems.map(item =>
+    `<a class="nav-link" href="#${item.id}" data-section="${item.id}">
+      <span class="nav-dot"></span>
+      ${escapeHtml(item.label)}
+    </a>`
+  ).join('');
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(domain)} — Design System · Prism</title>
+  <style>
+${fontFaceCss}
+${cssStr}
+  </style>
+</head>
+<body>
+
+<div class="app-layout">
+
+  <!-- Sticky Sidebar Nav -->
+  <nav class="nav-sidebar" aria-label="Design system sections">
+    <div class="nav-sidebar-inner">
+      <span class="nav-brand">Prism</span>
+      ${navHtml}
+    </div>
+  </nav>
+
+  <!-- Main Content -->
+  <main class="main-content">
+
+    <!-- Header -->
+    <header class="site-header">
+      <div class="header-top">
+        <div class="header-meta">
+          <span class="header-badge">Design System</span>
+          <h1 class="header-domain">${escapeHtml(domain)}</h1>
+          ${brandTagline ? `<p class="header-tagline">"${escapeHtml(brandTagline)}"</p>` : ''}
+          <div class="header-meta-row">
+            <span>Extracted ${escapeHtml(extractedDate)}</span>
+            <span>·</span>
+            <a href="${escapeHtml(sourceUrl)}" target="_blank" rel="noopener" style="color:inherit">${escapeHtml(sourceUrl)}</a>
+            <span>·</span>
+            <span>Confidence: <span class="confidence-badge confidence-${confidenceGrade}">${confidenceGrade} · ${confidenceScore}/100</span></span>
+          </div>
+        </div>
+        ${(desktopUrl || mobileUrl) ? `
+        <a href="#s-visual" class="proof-cta" style="display:inline-flex;align-items:center;gap:8px;padding:10px 14px;border-radius:8px;background:linear-gradient(135deg,#10b981 0%,#0ea5e9 100%);color:#fff;font-size:13px;font-weight:600;text-decoration:none;white-space:nowrap;box-shadow:0 4px 12px rgba(16,185,129,.25);transition:transform .15s ease;" onmouseover="this.style.transform='translateY(-1px)'" onmouseout="this.style.transform='translateY(0)'" title="See source screenshots side-by-side with extracted tokens">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
+          View Source Proof
+        </a>` : ''}
+      </div>
+      <div class="proof-tagline" style="margin-top:12px;padding:10px 14px;background:rgba(16,185,129,.08);border-left:3px solid #10b981;border-radius:4px;font-size:13px;color:var(--text-muted,#666);">
+        <strong style="color:var(--text-primary,#000);">Every claim is screenshot-verified.</strong>
+        getdesign.md tells. Prism <em>shows</em> — every color, font, and component below was extracted via <code style="background:rgba(0,0,0,.05);padding:2px 4px;border-radius:3px;font-size:11px;">getComputedStyle()</code> from the live screenshots ${desktopUrl ? '<a href="#s-visual" style="color:#10b981;font-weight:600;text-decoration:underline;">visible here</a>' : 'below'}.
+      </div>
+      ${(desktopUrl || mobileUrl) ? `
+      <div class="header-screenshots">
+        ${desktopUrl ? `<div class="header-screenshot-wrap">
+          <div class="screenshot-label">Desktop</div>
+          <div class="header-screenshot desktop">
+            <img src="${desktopUrl}" alt="${escapeHtml(domain)} desktop screenshot" loading="lazy">
+          </div>
+        </div>` : ''}
+        ${mobileUrl ? `<div class="header-screenshot-wrap">
+          <div class="screenshot-label">Mobile</div>
+          <div class="header-screenshot mobile">
+            <img src="${mobileUrl}" alt="${escapeHtml(domain)} mobile screenshot" loading="lazy">
+          </div>
+        </div>` : ''}
+      </div>` : ''}
+    </header>
+
+    ${colorSection}
+    ${typoSection}
+    ${liveComponents}
+    ${spacingSection}
+    ${componentSpecs}
+    ${visualSection}
+    ${breakpointsSection}
+    ${elevationSection}
+    ${motionSection}
+    ${motionTimelineSection}
+    ${componentStatesSection}
+    ${zIndexSection}
+    ${exportSection}
+    ${dosDontSection}
+    ${agentSection}
+
+    <!-- DESIGN.md -->
+    <section class="section designmd-section" id="s-designmd">
+      <h2>DESIGN.md</h2>
+      <p class="section-desc">Narrative design system document — paste directly into Claude Code, Cursor, or Bolt.</p>
+      <button class="copy-btn" onclick="copyMd()"><span>📋</span> Copy DESIGN.md</button>
+      <pre id="designmd-content">${escapeHtml(designMd)}</pre>
+    </section>
+
+    <footer class="showcase-footer">
+      <div class="footer-meta">
+        <span>🏗️ Generated by <strong>Prism</strong></span>
+        <span>·</span>
+        <span>Confidence <span class="confidence-badge confidence-${confidenceGrade}">${confidenceGrade} · ${confidenceScore}/100</span></span>
+        <span>·</span>
+        <span>${extractedDate}</span>
+      </div>
+      <div class="footer-links">
+        <a href="https://github.com/paulsainton/clone-architect" target="_blank" rel="noopener">GitHub ↗</a>
+        <a href="https://www.npmjs.com/package/clone-architect" target="_blank" rel="noopener">npm ↗</a>
+        <a href="${escapeHtml(sourceUrl)}" target="_blank" rel="noopener">Source ↗</a>
+        <a href="https://prism.ps-tools.dev/${escapeHtml(domain)}?raw=1">Raw DESIGN.md</a>
+      </div>
+    </footer>
+    <p style="text-align:center;font-size:11px;opacity:.4;margin-top:16px;font-family:var(--mono);">
+      Re-extract: <code style="background:rgba(0,0,0,.04);padding:2px 6px;border-radius:3px;">clone-architect update ${escapeHtml(domain)}</code>
+    </p>
+
+  </main>
+</div>
+
+<script>
+// ── Copy swatch hex ──────────────────────────────────────────────────────────
+function copySwatch(el, hex) {
+  navigator.clipboard.writeText(hex).then(() => {
+    el.classList.add('flash');
+    setTimeout(() => el.classList.remove('flash'), 1200);
+  }).catch(() => {
+    // Fallback for http contexts
+    const ta = document.createElement('textarea');
+    ta.value = hex; ta.style.position = 'fixed'; ta.style.opacity = '0';
+    document.body.appendChild(ta); ta.select();
+    document.execCommand('copy');
+    document.body.removeChild(ta);
+    el.classList.add('flash');
+    setTimeout(() => el.classList.remove('flash'), 1200);
+  });
+}
+
+// ── Copy DESIGN.md ───────────────────────────────────────────────────────────
+function copyMd() {
+  const text = document.getElementById('designmd-content').textContent;
+  navigator.clipboard.writeText(text).then(() => {
+    const btn = document.querySelector('.copy-btn');
+    btn.innerHTML = '<span>✓</span> Copied!';
+    setTimeout(() => { btn.innerHTML = '<span>📋</span> Copy DESIGN.md'; }, 2500);
+  });
+}
+
+// ── Sticky nav IntersectionObserver ─────────────────────────────────────────
+(function () {
+  const links = document.querySelectorAll('.nav-link[data-section]');
+  if (!links.length) return;
+
+  const map = {};
+  links.forEach(a => { map[a.dataset.section] = a; });
+
+  const sectionIds = Array.from(links).map(a => a.dataset.section);
+  let current = sectionIds[0];
+
+  const observer = new IntersectionObserver(entries => {
+    entries.forEach(e => {
+      if (e.isIntersecting && e.intersectionRatio >= 0.1) {
+        current = e.target.id;
+      }
+    });
+    links.forEach(a => a.classList.remove('active'));
+    if (map[current]) map[current].classList.add('active');
+  }, { threshold: [0.1, 0.5], rootMargin: '-10% 0px -60% 0px' });
+
+  sectionIds.forEach(id => {
+    const el = document.getElementById(id);
+    if (el) observer.observe(el);
+  });
+
+  // Activate first on load
+  if (map[sectionIds[0]]) map[sectionIds[0]].classList.add('active');
+})();
+</script>
+
+</body>
+</html>`;
+
+  await mkdir(outputDir, { recursive: true });
+  const outPath = join(outputDir, 'index.html');
+  await writeFile(outPath, html, 'utf-8');
+
+  const sizeKb = Math.round(Buffer.byteLength(html, 'utf-8') / 1024);
+  console.log(`✅ Showcase saved to ${outPath}`);
+  console.log(`   ${sizeKb} KB — inline CSS + screenshot base64`);
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────────
+
+const domain = process.argv[2];
+if (!domain) {
+  console.error('Usage: npx tsx scripts/generate-showcase.ts <domain>');
+  process.exit(1);
+}
+
+generateShowcase(domain).catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});