designlang 1.0.0 → 3.0.0

package/skills/extract-design/SKILL.md

@@ -1,27 +1,38 @@
 ---
 name: extract-design
-description: "Extract the full design language from any website URL. Produces AI-optimized markdown, W3C design tokens, Tailwind config, and CSS variables. Use when user says 'extract design', 'get design system', 'design language', 'design tokens', 'what colors does this site use', 'what font does this site use', or '/extract-design'."
-argument-hint: "<url> [--dark] [--out <dir>]"
+description: "Extract the full design language from any website URL. Produces 8 output files including AI-optimized markdown, visual HTML preview, Tailwind config, React theme, shadcn/ui theme, Figma variables, W3C design tokens, and CSS variables. Also runs WCAG accessibility scoring. Use when user says 'extract design', 'get design system', 'design language', 'design tokens', 'what colors/fonts does this site use', or '/extract-design'."
 allowed-tools: Bash, Read, Write, Glob
 ---
 
 # Extract Design Language
 
-Extract the complete design language from any website URL.
+Extract the complete design language from any website URL. Generates 8 output files covering colors, typography, spacing, shadows, components, breakpoints, animations, and accessibility.
 
-## Process
+## Prerequisites
+
+Ensure `designlang` is available. Install if needed:
+
+```bash
+npm install -g designlang
+```
 
-1. **Run the extraction CLI** on the provided URL:
+Or use npx (no install required):
 
 ```bash
-cd "${CLAUDE_SKILL_DIR}/../.." && node bin/design-extract.js $ARGUMENTS
+npx designlang <url>
 ```
 
-If dependencies are not installed, run first:
+## Process
+
+1. **Run the extraction** on the provided URL:
+
 ```bash
-cd "${CLAUDE_SKILL_DIR}/../.." && npm install
+npx designlang <url> --screenshots
 ```
 
+For multi-page crawling: `npx designlang <url> --depth 3 --screenshots`
+For dark mode: `npx designlang <url> --dark --screenshots`
+
 2. **Read the generated markdown file** to understand the design:
 
 ```bash
@@ -29,31 +40,47 @@ cat design-extract-output/*-design-language.md
 ```
 
 3. **Present key findings** to the user:
-   - Primary color palette (with hex codes)
+   - Primary color palette with hex codes
    - Font families in use
    - Spacing system (base unit if detected)
-   - Number of component patterns found
-   - Any notable design decisions (shadows, border-radius scale, etc.)
+   - WCAG accessibility score
+   - Component patterns found
+   - Notable design decisions (shadows, radii, etc.)
 
 4. **Offer next steps:**
-   - Copy `tailwind.config.js` into the user's project
-   - Import `variables.css` into their stylesheet
-   - Use `design-tokens.json` for tooling integration
-   - Use the markdown file as a reference for AI-assisted development
+   - Copy `*-tailwind.config.js` into their project
+   - Import `*-variables.css` into their stylesheet
+   - Paste `*-shadcn-theme.css` into globals.css for shadcn/ui users
+   - Import `*-theme.js` for React/CSS-in-JS projects
+   - Import `*-figma-variables.json` into Figma for designer handoff
+   - Open `*-preview.html` in a browser for a visual overview
+   - Use the markdown file as context for AI-assisted development
 
-## Output Files
-
-The tool generates 4 files in the output directory:
+## Output Files (8)
 
 | File | Purpose |
 |------|---------|
-| `*-design-language.md` | AI-optimized markdown describing the full design system |
-| `*-design-tokens.json` | W3C Design Tokens format for tooling |
-| `*-tailwind.config.js` | Ready-to-use Tailwind CSS theme extension |
-| `*-variables.css` | CSS custom properties for direct use |
+| `*-design-language.md` | AI-optimized markdown — the full design system for LLMs |
+| `*-preview.html` | Visual HTML report with swatches, type scale, shadows, a11y |
+| `*-design-tokens.json` | W3C Design Tokens format |
+| `*-tailwind.config.js` | Ready-to-use Tailwind CSS theme |
+| `*-variables.css` | CSS custom properties |
+| `*-figma-variables.json` | Figma Variables import format |
+| `*-theme.js` | React/CSS-in-JS theme object |
+| `*-shadcn-theme.css` | shadcn/ui theme CSS variables |
+
+## Additional Commands
+
+- **Compare two sites:** `npx designlang diff <urlA> <urlB>`
+- **View history:** `npx designlang history <url>`
 
 ## Options
 
-- `--out <dir>` — Output directory (default: `./design-extract-output`)
-- `--dark` — Also extract dark mode color scheme
-- `--wait <ms>` — Wait time after page load for SPAs
+| Flag | Description |
+|------|-------------|
+| `--out <dir>` | Output directory (default: `./design-extract-output`) |
+| `--dark` | Also extract dark mode color scheme |
+| `--depth <n>` | Crawl N internal pages for site-wide extraction |
+| `--screenshots` | Capture component screenshots (buttons, cards, nav) |
+| `--wait <ms>` | Wait time after page load for SPAs |
+| `--framework <type>` | Generate only specific theme (`react` or `shadcn`) |

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,
@@ -95,12 +203,18 @@ async function extractPageData(page) {
         animation: cs.animation,
         display: cs.display,
         position: cs.position,
+        flexDirection: cs.flexDirection,
+        flexWrap: cs.flexWrap,
+        justifyContent: cs.justifyContent,
+        alignItems: cs.alignItems,
+        gridTemplateColumns: cs.gridTemplateColumns,
+        gridTemplateRows: cs.gridTemplateRows,
+        maxWidth: cs.maxWidth,
       });
     }
 
-    // 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 +228,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 +239,7 @@ async function extractPageData(page) {
       }
     }
 
-    // 3. Extract media queries from stylesheets
+    // Media queries
     try {
       for (const sheet of document.styleSheets) {
         try {
@@ -140,7 +252,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
+  };
+}