designlang 1.0.0 → 2.0.0

package/src/crawler.js

@@ -1,9 +1,11 @@
 import { chromium } from 'playwright';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
 
 const MAX_ELEMENTS = 5000;
 
 export async function crawlPage(url, options = {}) {
-  const { width = 1280, height = 800, wait = 0, dark = false } = options;
+  const { width = 1280, height = 800, wait = 0, dark = false, depth = 0, screenshots = false, outDir = '' } = options;
 
   const browser = await chromium.launch({ headless: true });
   const context = await browser.newContext({
@@ -14,12 +16,32 @@ export async function crawlPage(url, options = {}) {
 
   await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
   if (wait > 0) await page.waitForTimeout(wait);
-
-  // Wait for fonts to load
   await page.evaluate(() => document.fonts.ready);
 
+  const title = await page.title();
   const lightData = await extractPageData(page);
 
+  // Component screenshots
+  let componentScreenshots = {};
+  if (screenshots && outDir) {
+    componentScreenshots = await captureComponentScreenshots(page, outDir);
+  }
+
+  // Multi-page crawl: discover internal links and extract from them
+  let additionalPages = [];
+  if (depth > 0) {
+    const internalLinks = await discoverInternalLinks(page, url, depth);
+    for (const link of internalLinks) {
+      try {
+        await page.goto(link, { waitUntil: 'networkidle', timeout: 20000 });
+        await page.evaluate(() => document.fonts.ready);
+        const pageData = await extractPageData(page);
+        additionalPages.push({ url: link, data: pageData });
+      } catch { /* skip failed pages */ }
+    }
+  }
+
+  // Dark mode extraction
   let darkData = null;
   if (dark) {
     await context.close();
@@ -32,12 +54,104 @@ export async function crawlPage(url, options = {}) {
     await darkPage.evaluate(() => document.fonts.ready);
     darkData = await extractPageData(darkPage);
     await darkContext.close();
+  } else {
+    await context.close();
   }
 
-  const title = await page.title();
   await browser.close();
 
-  return { url, title, light: lightData, dark: darkData };
+  // Merge additional page data into light data
+  if (additionalPages.length > 0) {
+    lightData.computedStyles = mergeStyles(lightData.computedStyles, additionalPages);
+    for (const ap of additionalPages) {
+      Object.assign(lightData.cssVariables, ap.data.cssVariables);
+      lightData.mediaQueries.push(...ap.data.mediaQueries);
+      lightData.keyframes.push(...ap.data.keyframes);
+    }
+    // Deduplicate media queries and keyframes
+    lightData.mediaQueries = [...new Set(lightData.mediaQueries)];
+    const seenKf = new Set();
+    lightData.keyframes = lightData.keyframes.filter(kf => {
+      if (seenKf.has(kf.name)) return false;
+      seenKf.add(kf.name);
+      return true;
+    });
+  }
+
+  return {
+    url, title,
+    light: lightData,
+    dark: darkData,
+    pagesAnalyzed: 1 + additionalPages.length,
+    componentScreenshots,
+  };
+}
+
+function mergeStyles(primary, additionalPages) {
+  // Add styles from additional pages, capping total
+  const all = [...primary];
+  for (const ap of additionalPages) {
+    if (all.length >= MAX_ELEMENTS * 2) break;
+    all.push(...ap.data.computedStyles);
+  }
+  return all;
+}
+
+async function discoverInternalLinks(page, baseUrl, maxLinks) {
+  const base = new URL(baseUrl);
+  const links = await page.evaluate((hostname) => {
+    return Array.from(document.querySelectorAll('a[href]'))
+      .map(a => a.href)
+      .filter(href => {
+        try {
+          const u = new URL(href);
+          return u.hostname === hostname && !href.includes('#') && !href.match(/\.(png|jpg|jpeg|gif|svg|pdf|zip|mp4|mp3)$/i);
+        } catch { return false; }
+      });
+  }, base.hostname);
+
+  // Deduplicate and limit
+  const unique = [...new Set(links)].filter(l => l !== baseUrl);
+  return unique.slice(0, Math.min(maxLinks * 3, 15)); // crawl up to 15 pages max
+}
+
+export async function captureComponentScreenshots(page, outDir) {
+  const screenshotDir = join(outDir, 'screenshots');
+  mkdirSync(screenshotDir, { recursive: true });
+
+  const result = {};
+
+  // Find representative elements for each component type
+  const selectors = [
+    { name: 'button', selector: 'button:not(:empty), a[role="button"], [class*="btn"]:not(:empty)', label: 'Buttons' },
+    { name: 'card', selector: '[class*="card"]:not(:empty)', label: 'Cards' },
+    { name: 'input', selector: 'input[type="text"], input[type="email"], input[type="search"], textarea', label: 'Inputs' },
+    { name: 'nav', selector: 'nav, [role="navigation"]', label: 'Navigation' },
+    { name: 'hero', selector: '[class*="hero"], section:first-of-type', label: 'Hero Section' },
+  ];
+
+  for (const { name, selector, label } of selectors) {
+    try {
+      const el = await page.$(selector);
+      if (el) {
+        const box = await el.boundingBox();
+        if (box && box.width > 20 && box.height > 10) {
+          const path = join(screenshotDir, `${name}.png`);
+          await el.screenshot({ path });
+          result[name] = { path: `screenshots/${name}.png`, label };
+        }
+      }
+    } catch { /* skip if screenshot fails */ }
+  }
+
+  // Full page screenshot
+  try {
+    const fullPath = join(screenshotDir, 'full-page.png');
+    await page.screenshot({ path: fullPath, fullPage: true });
+    result.fullPage = { path: 'screenshots/full-page.png', label: 'Full Page' };
+  } catch { /* skip */ }
+
+  return result;
 }
 
 async function extractPageData(page) {
@@ -49,7 +163,6 @@ async function extractPageData(page) {
       keyframes: [],
     };
 
-    // 1. Walk all elements and collect computed styles
     const allElements = document.querySelectorAll('*');
     const elements = allElements.length > maxElements
       ? Array.from(allElements).slice(0, maxElements)
@@ -60,16 +173,11 @@ async function extractPageData(page) {
       const tag = el.tagName.toLowerCase();
       const classList = Array.from(el.classList).join(' ');
       const role = el.getAttribute('role') || '';
-
-      // Get bounding rect for area estimation
       const rect = el.getBoundingClientRect();
       const area = rect.width * rect.height;
 
       results.computedStyles.push({
-        tag,
-        classList,
-        role,
-        area,
+        tag, classList, role, area,
         color: cs.color,
         backgroundColor: cs.backgroundColor,
         backgroundImage: cs.backgroundImage,
@@ -98,9 +206,8 @@ async function extractPageData(page) {
       });
     }
 
-    // 2. Extract CSS custom properties from :root
+    // CSS custom properties
     const rootStyles = getComputedStyle(document.documentElement);
-    // Get all custom properties by iterating stylesheets
     try {
       for (const sheet of document.styleSheets) {
         try {
@@ -114,12 +221,10 @@ async function extractPageData(page) {
               }
             }
           }
-        } catch { /* cross-origin stylesheet, skip */ }
+        } catch { /* cross-origin */ }
       }
-    } catch { /* no stylesheets accessible */ }
+    } catch { /* no access */ }
 
-    // Also get any custom properties from the computed style
-    // (fallback for CSS-in-JS that sets vars on :root)
     for (let i = 0; i < rootStyles.length; i++) {
       const prop = rootStyles[i];
       if (prop.startsWith('--') && !results.cssVariables[prop]) {
@@ -127,7 +232,7 @@ async function extractPageData(page) {
       }
     }
 
-    // 3. Extract media queries from stylesheets
+    // Media queries
     try {
       for (const sheet of document.styleSheets) {
         try {
@@ -140,7 +245,7 @@ async function extractPageData(page) {
       }
     } catch { /* no access */ }
 
-    // 4. Extract keyframes
+    // Keyframes
     try {
       for (const sheet of document.styleSheets) {
         try {

package/src/diff.js

@@ -0,0 +1,146 @@
+// Design diff engine — compare two design systems
+
+export function diffDesigns(designA, designB) {
+  const diff = { urlA: designA.meta.url, urlB: designB.meta.url, sections: [] };
+
+  // Color diff
+  const colorDiff = {
+    name: 'Colors',
+    onlyA: [], onlyB: [], shared: [], changed: [],
+  };
+  const hexesA = new Set(designA.colors.all.map(c => c.hex));
+  const hexesB = new Set(designB.colors.all.map(c => c.hex));
+  for (const h of hexesA) { if (!hexesB.has(h)) colorDiff.onlyA.push(h); }
+  for (const h of hexesB) { if (!hexesA.has(h)) colorDiff.onlyB.push(h); }
+  for (const h of hexesA) { if (hexesB.has(h)) colorDiff.shared.push(h); }
+
+  // Primary color comparison
+  if (designA.colors.primary && designB.colors.primary && designA.colors.primary.hex !== designB.colors.primary.hex) {
+    colorDiff.changed.push({ property: 'primary', a: designA.colors.primary.hex, b: designB.colors.primary.hex });
+  }
+  if (designA.colors.secondary && designB.colors.secondary && designA.colors.secondary.hex !== designB.colors.secondary.hex) {
+    colorDiff.changed.push({ property: 'secondary', a: designA.colors.secondary.hex, b: designB.colors.secondary.hex });
+  }
+  diff.sections.push(colorDiff);
+
+  // Typography diff
+  const typeDiff = { name: 'Typography', onlyA: [], onlyB: [], shared: [], changed: [] };
+  const fontsA = new Set(designA.typography.families.map(f => f.name));
+  const fontsB = new Set(designB.typography.families.map(f => f.name));
+  for (const f of fontsA) { if (!fontsB.has(f)) typeDiff.onlyA.push(f); }
+  for (const f of fontsB) { if (!fontsA.has(f)) typeDiff.onlyB.push(f); }
+  for (const f of fontsA) { if (fontsB.has(f)) typeDiff.shared.push(f); }
+  diff.sections.push(typeDiff);
+
+  // Spacing diff
+  const spaceDiff = { name: 'Spacing', changed: [] };
+  if (designA.spacing.base !== designB.spacing.base) {
+    spaceDiff.changed.push({ property: 'base unit', a: `${designA.spacing.base}px`, b: `${designB.spacing.base}px` });
+  }
+  spaceDiff.countA = designA.spacing.scale.length;
+  spaceDiff.countB = designB.spacing.scale.length;
+  diff.sections.push(spaceDiff);
+
+  // Accessibility diff
+  if (designA.accessibility && designB.accessibility) {
+    diff.sections.push({
+      name: 'Accessibility',
+      changed: [{ property: 'WCAG score', a: `${designA.accessibility.score}%`, b: `${designB.accessibility.score}%` }],
+    });
+  }
+
+  // Component diff
+  const compDiff = { name: 'Components', onlyA: [], onlyB: [], shared: [] };
+  const compsA = new Set(Object.keys(designA.components));
+  const compsB = new Set(Object.keys(designB.components));
+  for (const c of compsA) { if (!compsB.has(c)) compDiff.onlyA.push(c); }
+  for (const c of compsB) { if (!compsA.has(c)) compDiff.onlyB.push(c); }
+  for (const c of compsA) { if (compsB.has(c)) compDiff.shared.push(c); }
+  diff.sections.push(compDiff);
+
+  return diff;
+}
+
+export function formatDiffMarkdown(diff) {
+  const lines = [];
+  lines.push(`# Design Comparison`);
+  lines.push('');
+  lines.push(`| | Site A | Site B |`);
+  lines.push(`|---|--------|--------|`);
+  lines.push(`| URL | ${diff.urlA} | ${diff.urlB} |`);
+  lines.push('');
+
+  for (const section of diff.sections) {
+    lines.push(`## ${section.name}`);
+    lines.push('');
+
+    if (section.changed && section.changed.length > 0) {
+      lines.push('### Differences');
+      lines.push('');
+      lines.push('| Property | Site A | Site B |');
+      lines.push('|----------|--------|--------|');
+      for (const c of section.changed) {
+        lines.push(`| ${c.property} | \`${c.a}\` | \`${c.b}\` |`);
+      }
+      lines.push('');
+    }
+
+    if (section.onlyA && section.onlyA.length > 0) {
+      lines.push(`**Only in Site A:** ${section.onlyA.map(v => `\`${v}\``).join(', ')}`);
+      lines.push('');
+    }
+    if (section.onlyB && section.onlyB.length > 0) {
+      lines.push(`**Only in Site B:** ${section.onlyB.map(v => `\`${v}\``).join(', ')}`);
+      lines.push('');
+    }
+    if (section.shared && section.shared.length > 0) {
+      lines.push(`**Shared:** ${section.shared.map(v => `\`${v}\``).join(', ')}`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function formatDiffHtml(diff) {
+  return `<!DOCTYPE html>
+<html><head><meta charset="UTF-8"><title>Design Comparison</title>
+<style>
+  * { margin:0; padding:0; box-sizing:border-box; }
+  body { font-family:-apple-system,sans-serif; background:#0a0a0a; color:#e5e5e5; padding:40px; }
+  h1 { font-size:32px; color:#fff; margin-bottom:24px; }
+  h2 { font-size:20px; color:#fff; margin:32px 0 16px; border-bottom:1px solid #222; padding-bottom:8px; }
+  .urls { display:grid; grid-template-columns:1fr 1fr; gap:16px; margin-bottom:32px; }
+  .url-card { background:#141414; border:1px solid #222; border-radius:12px; padding:16px; }
+  .url-card h3 { font-size:12px; color:#666; margin-bottom:4px; }
+  .url-card a { color:#3b82f6; font-size:14px; }
+  .diff-row { display:grid; grid-template-columns:120px 1fr 1fr; gap:12px; padding:10px 16px; border-radius:8px; margin-bottom:4px; }
+  .diff-row:nth-child(odd) { background:#111; }
+  .diff-label { color:#888; font-size:13px; }
+  .diff-val { font-family:monospace; font-size:13px; }
+  .swatch-inline { display:inline-block; width:14px; height:14px; border-radius:3px; vertical-align:middle; margin-right:6px; border:1px solid #333; }
+  .only-a { color:#f97316; } .only-b { color:#8b5cf6; } .shared { color:#22c55e; }
+  .tag { display:inline-block; font-size:12px; padding:2px 8px; border-radius:4px; margin:2px; }
+  .tag-a { background:#f9731620; color:#f97316; }
+  .tag-b { background:#8b5cf620; color:#8b5cf6; }
+  .tag-shared { background:#22c55e20; color:#22c55e; }
+</style></head><body>
+<h1>Design Comparison</h1>
+<div class="urls">
+  <div class="url-card"><h3>Site A</h3><a href="${diff.urlA}">${diff.urlA}</a></div>
+  <div class="url-card"><h3>Site B</h3><a href="${diff.urlB}">${diff.urlB}</a></div>
+</div>
+${diff.sections.map(s => `
+<h2>${s.name}</h2>
+${s.changed && s.changed.length > 0 ? s.changed.map(c => `
+<div class="diff-row">
+  <span class="diff-label">${c.property}</span>
+  <span class="diff-val">${c.a.startsWith('#') ? `<span class="swatch-inline" style="background:${c.a}"></span>` : ''}${c.a}</span>
+  <span class="diff-val">${c.b.startsWith('#') ? `<span class="swatch-inline" style="background:${c.b}"></span>` : ''}${c.b}</span>
+</div>`).join('') : ''}
+${s.onlyA && s.onlyA.length > 0 ? `<p style="margin:8px 0"><span class="only-a">Only in A:</span> ${s.onlyA.slice(0, 15).map(v => `<span class="tag tag-a">${v.startsWith('#') ? `<span class="swatch-inline" style="background:${v}"></span>` : ''}${v}</span>`).join('')}</p>` : ''}
+${s.onlyB && s.onlyB.length > 0 ? `<p style="margin:8px 0"><span class="only-b">Only in B:</span> ${s.onlyB.slice(0, 15).map(v => `<span class="tag tag-b">${v.startsWith('#') ? `<span class="swatch-inline" style="background:${v}"></span>` : ''}${v}</span>`).join('')}</p>` : ''}
+${s.shared && s.shared.length > 0 ? `<p style="margin:8px 0"><span class="shared">Shared:</span> ${s.shared.slice(0, 15).map(v => `<span class="tag tag-shared">${v.startsWith('#') ? `<span class="swatch-inline" style="background:${v}"></span>` : ''}${v}</span>`).join('')}</p>` : ''}
+`).join('')}
+</body></html>`;
+}

package/src/extractors/accessibility.js

@@ -0,0 +1,95 @@
+import { parseColor, rgbToHex } from '../utils.js';
+
+// WCAG 2.1 relative luminance
+function luminance({ r, g, b }) {
+  const [rs, gs, bs] = [r, g, b].map(c => {
+    c = c / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+function contrastRatio(c1, c2) {
+  const l1 = luminance(c1);
+  const l2 = luminance(c2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function wcagLevel(ratio, isLargeText) {
+  if (isLargeText) {
+    if (ratio >= 4.5) return 'AAA';
+    if (ratio >= 3) return 'AA';
+    return 'FAIL';
+  }
+  if (ratio >= 7) return 'AAA';
+  if (ratio >= 4.5) return 'AA';
+  return 'FAIL';
+}
+
+export function extractAccessibility(computedStyles) {
+  const pairs = new Map(); // "fg|bg" -> { fg, bg, count, elements }
+
+  for (const el of computedStyles) {
+    const fg = parseColor(el.color);
+    const bg = parseColor(el.backgroundColor);
+    if (!fg || !bg || bg.a === 0) continue;
+
+    const fgHex = rgbToHex(fg);
+    const bgHex = rgbToHex(bg);
+    const key = `${fgHex}|${bgHex}`;
+
+    if (!pairs.has(key)) {
+      pairs.set(key, { fg, bg, fgHex, bgHex, count: 0, tags: new Set(), fontSize: null });
+    }
+    const pair = pairs.get(key);
+    pair.count++;
+    pair.tags.add(el.tag);
+    // Track font size for large text determination
+    const size = parseFloat(el.fontSize);
+    if (!pair.fontSize || size > pair.fontSize) pair.fontSize = size;
+  }
+
+  const results = [];
+  let passCount = 0;
+  let failCount = 0;
+
+  for (const [, pair] of pairs) {
+    if (pair.fgHex === pair.bgHex) continue; // skip same color pairs
+    const ratio = contrastRatio(pair.fg, pair.bg);
+    const isLargeText = pair.fontSize >= 18 || (pair.fontSize >= 14 && pair.tags.has('b'));
+    const level = wcagLevel(ratio, isLargeText);
+
+    if (level === 'FAIL') failCount += pair.count;
+    else passCount += pair.count;
+
+    results.push({
+      foreground: pair.fgHex,
+      background: pair.bgHex,
+      ratio: Math.round(ratio * 100) / 100,
+      level,
+      isLargeText,
+      count: pair.count,
+      elements: [...pair.tags].slice(0, 5),
+    });
+  }
+
+  // Sort: failures first, then by count
+  results.sort((a, b) => {
+    if (a.level === 'FAIL' && b.level !== 'FAIL') return -1;
+    if (b.level === 'FAIL' && a.level !== 'FAIL') return 1;
+    return b.count - a.count;
+  });
+
+  const total = passCount + failCount;
+  const score = total > 0 ? Math.round((passCount / total) * 100) : 100;
+
+  return {
+    score,
+    passCount,
+    failCount,
+    totalPairs: results.length,
+    pairs: results.slice(0, 50), // top 50 pairs
+  };
+}

package/src/formatters/figma.js

@@ -0,0 +1,83 @@
+// Figma Variables JSON format (compatible with Figma Variables import)
+export function formatFigma(design) {
+  const variables = [];
+
+  // Colors
+  if (design.colors.primary) {
+    variables.push(colorVar('color/primary', design.colors.primary.hex));
+  }
+  if (design.colors.secondary) {
+    variables.push(colorVar('color/secondary', design.colors.secondary.hex));
+  }
+  if (design.colors.accent) {
+    variables.push(colorVar('color/accent', design.colors.accent.hex));
+  }
+  for (let i = 0; i < design.colors.neutrals.length && i < 10; i++) {
+    variables.push(colorVar(`color/neutral/${i * 100 || 50}`, design.colors.neutrals[i].hex));
+  }
+  for (let i = 0; i < design.colors.backgrounds.length; i++) {
+    variables.push(colorVar(`color/background/${i === 0 ? 'default' : i}`, design.colors.backgrounds[i]));
+  }
+  for (let i = 0; i < design.colors.text.length && i < 5; i++) {
+    variables.push(colorVar(`color/text/${i === 0 ? 'default' : i}`, design.colors.text[i]));
+  }
+
+  // Spacing
+  for (const v of design.spacing.scale.slice(0, 20)) {
+    variables.push({ name: `spacing/${v}`, type: 'FLOAT', value: v, scopes: ['GAP', 'ALL_SCOPES'] });
+  }
+
+  // Border radius
+  for (const r of design.borders.radii) {
+    variables.push({ name: `radius/${r.label}`, type: 'FLOAT', value: r.value, scopes: ['CORNER_RADIUS'] });
+  }
+
+  // Font sizes
+  for (const s of design.typography.scale.slice(0, 12)) {
+    variables.push({ name: `fontSize/${s.size}`, type: 'FLOAT', value: s.size, scopes: ['FONT_SIZE'] });
+  }
+
+  const collection = {
+    name: `Design Language — ${design.meta.title || 'Extracted'}`,
+    modes: [{ name: 'Default', variables }],
+  };
+
+  // Add dark mode if available
+  if (design.darkMode) {
+    const darkVars = [];
+    const dc = design.darkMode.colors;
+    if (dc.primary) darkVars.push(colorVar('color/primary', dc.primary.hex));
+    if (dc.secondary) darkVars.push(colorVar('color/secondary', dc.secondary.hex));
+    for (let i = 0; i < dc.neutrals.length && i < 10; i++) {
+      darkVars.push(colorVar(`color/neutral/${i * 100 || 50}`, dc.neutrals[i].hex));
+    }
+    for (let i = 0; i < dc.backgrounds.length; i++) {
+      darkVars.push(colorVar(`color/background/${i === 0 ? 'default' : i}`, dc.backgrounds[i]));
+    }
+    for (let i = 0; i < dc.text.length && i < 5; i++) {
+      darkVars.push(colorVar(`color/text/${i === 0 ? 'default' : i}`, dc.text[i]));
+    }
+    collection.modes.push({ name: 'Dark', variables: darkVars });
+  }
+
+  return JSON.stringify(collection, null, 2);
+}
+
+function colorVar(name, hex) {
+  const rgb = hexToRgb(hex);
+  return {
+    name,
+    type: 'COLOR',
+    value: { r: rgb.r / 255, g: rgb.g / 255, b: rgb.b / 255, a: 1 },
+    scopes: ['ALL_SCOPES'],
+  };
+}
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}

package/src/formatters/markdown.js

@@ -7,7 +7,7 @@ export function formatMarkdown(design) {
   lines.push(`# Design Language: ${meta.title || 'Unknown Site'}`);
   lines.push('');
   lines.push(`> Extracted from \`${meta.url}\` on ${new Date(meta.timestamp).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })}`);
-  lines.push(`> ${meta.elementCount} elements analyzed`);
+  lines.push(`> ${meta.elementCount} elements analyzed${meta.pagesAnalyzed > 1 ? ` across ${meta.pagesAnalyzed} pages` : ''}`);
   lines.push('');
   lines.push('This document describes the complete design language of the website. It is structured for AI/LLM consumption — use it to faithfully recreate the visual design in any framework.');
   lines.push('');
@@ -259,6 +259,41 @@ export function formatMarkdown(design) {
     }
   }
 
+  // ── Accessibility ──
+  if (design.accessibility) {
+    const a = design.accessibility;
+    lines.push('## Accessibility (WCAG 2.1)');
+    lines.push('');
+    lines.push(`**Overall Score: ${a.score}%** — ${a.passCount} passing, ${a.failCount} failing color pairs`);
+    lines.push('');
+
+    if (a.pairs.length > 0) {
+      const failures = a.pairs.filter(p => p.level === 'FAIL');
+      if (failures.length > 0) {
+        lines.push('### Failing Color Pairs');
+        lines.push('');
+        lines.push('| Foreground | Background | Ratio | Level | Used On |');
+        lines.push('|------------|------------|-------|-------|---------|');
+        for (const p of failures.slice(0, 15)) {
+          lines.push(`| \`${p.foreground}\` | \`${p.background}\` | ${p.ratio}:1 | ${p.level} | ${p.elements.join(', ')} (${p.count}x) |`);
+        }
+        lines.push('');
+      }
+
+      const passes = a.pairs.filter(p => p.level !== 'FAIL');
+      if (passes.length > 0) {
+        lines.push('### Passing Color Pairs');
+        lines.push('');
+        lines.push('| Foreground | Background | Ratio | Level |');
+        lines.push('|------------|------------|-------|-------|');
+        for (const p of passes.slice(0, 10)) {
+          lines.push(`| \`${p.foreground}\` | \`${p.background}\` | ${p.ratio}:1 | ${p.level} |`);
+        }
+        lines.push('');
+      }
+    }
+  }
+
   // ── Dark Mode ──
   if (design.darkMode) {
     lines.push('## Dark Mode');