designlang 6.0.0 → 7.0.0

package/docs/superpowers/specs/2026-04-18-designlang-v7-design.md

@@ -0,0 +1,150 @@
+# designlang v7.0 — Design Spec
+
+**Date:** 2026-04-18
+**Status:** Approved for implementation
+**Author:** Manav Arya Singh
+
+## Theme
+
+*The design context layer for AI agents, across every platform.*
+
+v7.0 turns designlang from a web-only token extractor into (a) the default MCP/agent context source for AI IDEs, (b) a real multi-platform design system output (web + iOS + Android + Flutter + WordPress), (c) a CSS auditor, not just an extractor.
+
+## Scope — 10 features
+
+### 1. MCP server
+New command: `designlang mcp [--output-dir <path>]`. Launches a stdio MCP server built on `@modelcontextprotocol/sdk`. Exposes:
+- **Resources:** `tokens://primitive`, `tokens://semantic`, `tokens://components`, `regions://map`, `health://score`.
+- **Tools:** `search_tokens(query)`, `find_nearest_color(hex, level: AA|AAA)`, `get_region(name)`, `get_component(name)`, `list_failing_contrast_pairs()`.
+- No live extraction tool (deferred to v7.1 with hosted backend).
+
+### 2. Agent rules emitter
+New flag: `--emit-agent-rules` (and on by default when `--full`). Writes:
+- `.cursor/rules/designlang.mdc` — Cursor project rules referencing tokens.
+- `.claude/skills/designlang/SKILL.md` — Claude Code skill folder with frontmatter.
+- `CLAUDE.md.fragment` — append-ready fragment for root CLAUDE.md.
+- `agents.md` — generic agent prompt.
+
+All four files read from the same source-of-truth JSON.
+
+### 3. DTCG strict mode + semantic layer + composite tokens
+Rewrites `*-design-tokens.json` to W3C DTCG v1 format:
+- Every leaf is `{ "$value": ..., "$type": "color|dimension|fontFamily|shadow|...", "$extensions": {...} }`.
+- Two-layer structure: `primitive.*` (raw values) and `semantic.*` (alias references like `"{primitive.color.blue.500}"`).
+- Composite types for `typography`, `shadow`, `border`, `gradient` (single object with family/size/weight/lineHeight, etc.).
+- Auto-infers semantic roles from usage: `semantic.color.action.primary`, `semantic.color.surface.default`, `semantic.text.body`, `semantic.radius.control`, etc.
+- **Default ON.** `--tokens-legacy` preserves pre-v7 shape. Breaking change — documented in CHANGELOG and migration guide.
+
+### 4. Multi-platform emitters
+New flag: `--platforms <csv>` (values: `web,ios,android,flutter,wordpress,all`; default `web`).
+- **iOS (SwiftUI):** `*-ios.swift` with `Color.primaryAction`, `CGFloat` spacing/radius, `Font` registrations.
+- **Android (Compose):** `*-colors.xml`, `*-dimens.xml`, `*-Theme.kt` with Compose `val`s.
+- **Flutter (Dart):** `*-theme.dart` exporting a `ThemeData` + color/typography extensions.
+- **WordPress:** `theme.json` (Gutenberg block theme tokens), `style.css` with CSS custom props, minimal `functions.php` + `index.php`/`templates/index.html` skeleton so output is a drop-in block theme.
+
+All emitters consume the DTCG semantic layer, not primitives — they stay consistent.
+
+### 5. Tech-stack + Tailwind fingerprint
+New extractor `stack-fingerprint`:
+- Detects framework from window globals, script URLs, meta tags, DOM signatures (React/Vue/Svelte/Next/Nuxt/Remix/Astro/Shopify/WooCommerce/Webflow/Framer).
+- Detects CSS layer (Tailwind v3/v4, styled-components, CSS Modules, vanilla).
+- Detects analytics, CDN, fonts host, A/B tools.
+- When Tailwind is detected: scrapes class-name frequency, extracts utility classes in use, and emits `*-tailwind-diff.md` (what classes are used, config delta vs. default preset) instead of only a fresh `tailwind.config.js`.
+
+### 6. CSS health audit
+New extractor `css-health`:
+- Runs Playwright `coverage.startCSSCoverage()` → reports unused bytes per stylesheet.
+- Parses all stylesheets for specificity distribution, `!important` count, duplicate declarations, selector-per-rule averages, vendor-prefix and obsolete-property audit.
+- Enumerates `@keyframes` with name/duration/easing/steps.
+- Emits `*-css-health.json` and `*-css-health.md`.
+- Adds three new dimensions to the design score: `cssHealth`, `animationCatalog`, `specificity`. Old score fields remain for backward compat.
+
+### 7. A11y remediation suggestions
+Extends a11y extractor:
+- For each failing WCAG fg/bg pair, searches the extracted palette for the nearest color that passes AA (4.5:1) and AAA (7:1).
+- Emits suggestions in `*-a11y.md` and as fixable entries in `*-design-language.md`.
+- MCP tool `find_nearest_color(hex, level)` reuses this engine.
+
+### 8. Semantic component segmentation
+New extractor `semantic-regions`:
+- Heuristic classifier using ARIA landmarks (`<nav>`, `<main>`, `<header>`, `<footer>`, `role=banner|contentinfo|complementary`), layout properties (sticky header, footer at page end), and class-name hints (`.hero`, `.pricing`, `.cta`).
+- Labels detected regions: `nav`, `hero`, `features`, `pricing`, `testimonials`, `cta`, `footer`, `content`.
+- Emits `*-regions.json` with bounds, computed styles, and region role.
+- MCP tool `get_region(name)` returns the full region block.
+
+### 9. Reusable component detection
+New extractor `component-clusters`:
+- For each DOM element matching button/card/input/badge/tag candidates, computes a structural hash (tag sequence + class pattern) + style vector (flattened computed-style array).
+- Clusters by similarity (structural hash exact, style vector cosine > threshold).
+- Replaces current "one example per component type" with `{ component, instanceCount, variants: [...] }`.
+- Markdown output shows "Button — 24 instances, 2 variants (primary, ghost)" with CSS for each.
+
+### 10. WordPress theme export
+Covered under Feature 4; called out separately because it is a full emitter with file-tree skeleton, not only tokens.
+
+## Architecture changes
+
+### New modules
+- `src/extractors/stack-fingerprint.js`
+- `src/extractors/css-health.js`
+- `src/extractors/semantic-regions.js`
+- `src/extractors/component-clusters.js`
+- `src/extractors/a11y-remediation.js` (or extend existing a11y)
+- `src/formatters/dtcg-tokens.js` (replaces `design-tokens.js` with legacy fallback)
+- `src/formatters/ios-swiftui.js`
+- `src/formatters/android-compose.js`
+- `src/formatters/flutter-dart.js`
+- `src/formatters/wordpress-theme.js`
+- `src/formatters/agent-rules.js`
+- `src/mcp/server.js` + `src/mcp/resources.js` + `src/mcp/tools.js`
+
+### New dependencies
+- `@modelcontextprotocol/sdk` — for MCP server.
+- No other additions.
+
+### CLI surface
+```
+designlang <url> [...existing flags]
+  --platforms <csv>       web,ios,android,flutter,wordpress,all (default: web)
+  --emit-agent-rules      Emit Cursor/Claude Code/generic agent rules
+  --tokens-legacy         Keep pre-v7 token JSON shape
+
+designlang mcp [--output-dir <path>]   # NEW: launch MCP server
+```
+
+All existing commands (`apply`, `clone`, `score`, `watch`, `diff`, `brands`, `sync`, `history`) unchanged.
+
+### Backward compatibility
+- Base extraction stays — same file names, same top-level keys.
+- **Breaking:** token JSON shape changes to DTCG. Mitigated by `--tokens-legacy`, loud CHANGELOG, migration section in README.
+- **Additive:** score JSON gains new fields; existing fields preserved.
+- **Additive:** new files only appear with opt-in flags (`--platforms`, `--emit-agent-rules`).
+
+## Testing
+
+- Unit tests per extractor module using fixture HTML (existing pattern in `tests/`).
+- Integration test: run full extraction on a local fixture site, snapshot each output file.
+- DTCG output validated against the W3C DTCG JSON schema (vendored).
+- Multi-platform emitters: golden-file tests (check generated Swift/Kotlin/Dart/theme.json against known-good outputs).
+- MCP server: spin up server, run a handful of resource/tool requests over the MCP test harness, assert responses.
+
+## Release plan
+
+1. Implement features in dependency order (see writing-plans phase).
+2. All tests pass.
+3. Update README with new sections: MCP, agent rules, multi-platform, CSS health, WordPress.
+4. Write CHANGELOG.md with breaking-change callout on DTCG + migration snippet.
+5. Bump `package.json` version `6.0.0` → `7.0.0`.
+6. `npm publish` + `git tag v7.0.0 && git push --tags`.
+7. Website update — deferred to Wave 2.
+
+## Out of scope (deferred to v7.1+)
+
+- Bidirectional Figma Variables sync.
+- Full JSX/Vue/Svelte component codegen (needs Mitosis-style IR or LLM).
+- Versioned auto-published npm token package with changesets.
+- Hosted shareable reports (needs backend).
+- Hosted "Try it free" web extraction (Wave 2).
+- CMS content-model extraction.
+- Storybook + Chromatic integration.
+- Live clone-to-editable canvas.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, and more. Outputs AI-optimized markdown, W3C design tokens, Tailwind config, and CSS variables.",
   "type": "module",
   "bin": {
@@ -13,10 +13,11 @@
     "test": "node --test tests/*.test.js"
   },
   "dependencies": {
-    "playwright": "^1.42.0",
-    "commander": "^12.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
-    "ora": "^8.0.0"
+    "commander": "^12.0.0",
+    "ora": "^8.0.0",
+    "playwright": "^1.42.0"
   },
   "engines": {
     "node": ">=20"

package/src/config.js

@@ -32,5 +32,28 @@ export function mergeConfig(cliOpts, config) {
     cookie: cliOpts.cookie || config.cookies,
     header: cliOpts.header || config.headers,
     out: cliOpts.out || config.out || './design-extract-output',
+    tokensLegacy: cliOpts.tokensLegacy || config.tokensLegacy || false,
+    platforms: parsePlatforms(cliOpts.platforms ?? config.platforms ?? 'web'),
+    emitAgentRules: cliOpts.emitAgentRules || config.emitAgentRules || false,
   };
 }
+
+// Normalize the --platforms value into an array. Accepts comma-separated strings
+// or an existing array. Expands "all" to the full list. Always ensures "web"
+// remains included (v7.0: --platforms is additive, web is not disabled).
+export function parsePlatforms(value) {
+  const KNOWN = ['web', 'ios', 'android', 'flutter', 'wordpress'];
+  let list;
+  if (Array.isArray(value)) list = value.slice();
+  else if (typeof value === 'string') list = value.split(',').map((s) => s.trim()).filter(Boolean);
+  else list = ['web'];
+
+  const expanded = new Set();
+  for (const item of list) {
+    const v = item.toLowerCase();
+    if (v === 'all') KNOWN.forEach((k) => expanded.add(k));
+    else if (KNOWN.includes(v)) expanded.add(v);
+  }
+  expanded.add('web'); // web is always emitted in v7.0
+  return KNOWN.filter((k) => expanded.has(k));
+}

package/src/crawler.js

@@ -43,14 +43,36 @@ export async function crawlPage(url, options = {}) {
     }
     const page = await context.newPage();
 
+    // Start CSS coverage for css-health audit. Not supported on all targets —
+    // fail gracefully and set empty coverage if the API is unavailable.
+    let cssCoverageAvailable = true;
+    try {
+      await page.coverage.startCSSCoverage();
+    } catch { cssCoverageAvailable = false; }
+
     await gotoWithRetry(page, url, { waitUntil: 'domcontentloaded', timeout: 30000 });
     // Wait for network to settle — but don't hang on sites with persistent connections
     await page.waitForLoadState('networkidle').catch(() => {});
     if (wait > 0) await page.waitForTimeout(wait);
     await page.evaluate(() => document.fonts.ready).catch(() => {});
 
+    // Capture CSS coverage after the page has settled.
+    let cssCoverage = [];
+    if (cssCoverageAvailable) {
+      try {
+        const raw = await page.coverage.stopCSSCoverage();
+        cssCoverage = raw.map(c => ({
+          url: c.url,
+          text: c.text,
+          totalBytes: (c.text || '').length,
+          ranges: c.ranges || [],
+        }));
+      } catch { cssCoverage = []; }
+    }
+
     const title = await page.title();
     const lightData = await extractPageData(page, ignore);
+    lightData.cssCoverage = cssCoverage;
 
     // Component screenshots
     let componentScreenshots = {};
@@ -326,6 +348,100 @@ async function extractPageData(page, ignoreSelectors) {
       }
     } catch { /* no access */ }
 
+    // Component clusters (v7): per-element features for similarity-based grouping.
+    function colorToChannels(str) {
+      if (!str) return [0, 0, 0, 0];
+      const m = String(str).match(/rgba?\(([^)]+)\)/i);
+      if (!m) return [0, 0, 0, 0];
+      const parts = m[1].split(',').map(s => parseFloat(s));
+      return [parts[0] || 0, parts[1] || 0, parts[2] || 0, parts[3] === undefined ? 1 : parts[3]];
+    }
+    function structuralHashOf(el) {
+      const parts = [el.tagName.toLowerCase()];
+      for (const c of el.children) {
+        parts.push(c.tagName.toLowerCase());
+      }
+      return parts.slice(0, 6).join('>');
+    }
+    const candidateSelector = 'button, a[role="button"], .btn, [class*="button"], input[type="text"], input[type="email"], input[type="search"], textarea, [class*="card"]';
+    results.componentCandidates = [];
+    const seenCandidates = new Set();
+    for (const el of document.querySelectorAll(candidateSelector)) {
+      if (results.componentCandidates.length >= 300) break;
+      const rect = el.getBoundingClientRect();
+      if (rect.width < 4 || rect.height < 4) continue;
+      if (seenCandidates.has(el)) continue;
+      seenCandidates.add(el);
+      const cs = getComputedStyle(el);
+      const tag = el.tagName.toLowerCase();
+      let kind = 'other';
+      const cls = typeof el.className === 'string' ? el.className.toLowerCase() : '';
+      if (tag === 'button' || el.getAttribute('role') === 'button' || /\bbtn\b|button/.test(cls)) kind = 'button';
+      else if (tag === 'input' || tag === 'textarea') kind = 'input';
+      else if (tag === 'a') kind = 'link';
+      else if (/card/.test(cls)) kind = 'card';
+      const bg = colorToChannels(cs.backgroundColor);
+      const fg = colorToChannels(cs.color);
+      const styleVector = [
+        parseFloat(cs.paddingTop) || 0,
+        parseFloat(cs.paddingRight) || 0,
+        parseFloat(cs.paddingBottom) || 0,
+        parseFloat(cs.paddingLeft) || 0,
+        bg[0], bg[1], bg[2], bg[3] * 255,
+        fg[0], fg[1], fg[2], fg[3] * 255,
+        parseFloat(cs.borderTopLeftRadius) || 0,
+        parseFloat(cs.borderWidth) || 0,
+        parseFloat(cs.fontSize) || 0,
+        parseFloat(cs.fontWeight) || 0,
+      ];
+      results.componentCandidates.push({
+        kind,
+        structuralHash: structuralHashOf(el),
+        styleVector,
+        css: {
+          background: cs.backgroundColor,
+          color: cs.color,
+          padding: `${cs.paddingTop} ${cs.paddingRight} ${cs.paddingBottom} ${cs.paddingLeft}`,
+          borderRadius: cs.borderTopLeftRadius,
+          border: `${cs.borderWidth} ${cs.borderStyle} ${cs.borderColor}`,
+          fontSize: cs.fontSize,
+          fontWeight: cs.fontWeight,
+        },
+      });
+    }
+
+    // Semantic regions (v7): landmark + heading + bounds data for classifier.
+    results.sections = Array.from(document.querySelectorAll(
+      'header, nav, main, section, footer, aside, [role="banner"], [role="contentinfo"], [role="complementary"], [role="navigation"]'
+    )).slice(0, 100).map(el => {
+      const r = el.getBoundingClientRect();
+      return {
+        tag: el.tagName.toLowerCase(),
+        role: el.getAttribute('role') || '',
+        className: typeof el.className === 'string' ? el.className : '',
+        id: el.id || '',
+        text: (el.innerText || '').slice(0, 2000),
+        headings: Array.from(el.querySelectorAll('h1,h2,h3')).slice(0, 5).map(h => h.innerText || ''),
+        buttonCount: el.querySelectorAll('button, a[role="button"], .btn, [class*="button"]').length,
+        cardCount: el.querySelectorAll('article, li, [class*="card"], [class*="item"]').length,
+        bounds: { x: r.x, y: r.y, w: r.width, h: r.height },
+      };
+    });
+
+    // Stack fingerprint signals (v7)
+    results.stack = {
+      scripts: Array.from(document.scripts).map(s => s.src).filter(Boolean).slice(0, 50),
+      metas: Array.from(document.querySelectorAll('meta[name],meta[property]'))
+        .map(m => ({ name: m.name || m.getAttribute('property'), content: m.content }))
+        .slice(0, 50),
+      classNameSample: Array.from(document.querySelectorAll('[class]'))
+        .slice(0, 500)
+        .map(e => typeof e.className === 'string' ? e.className : '')
+        .filter(Boolean),
+      windowGlobals: ['React', 'Vue', '__NEXT_DATA__', '__NUXT__', '___gatsby', '_remixContext', 'Shopify', 'wp']
+        .filter(k => typeof window[k] !== 'undefined'),
+    };
+
     // SVG icons
     results.icons = [];
     for (const svg of document.querySelectorAll('svg')) {

package/src/extractors/a11y-remediation.js

@@ -0,0 +1,47 @@
+// A11y remediation: for each failing fg/bg pair, propose the nearest palette
+// color that passes the requested WCAG rule.
+
+function toRgb(hex) {
+  const h = String(hex || '').replace('#', '');
+  const n = h.length === 3 ? h.split('').map(x => x + x).join('') : h;
+  const i = parseInt(n, 16);
+  if (Number.isNaN(i)) return [0, 0, 0];
+  return [(i >> 16) & 255, (i >> 8) & 255, i & 255];
+}
+
+function relLum([r, g, b]) {
+  const f = c => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+}
+
+function contrast(a, b) {
+  const la = relLum(toRgb(a));
+  const lb = relLum(toRgb(b));
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+const THRESHOLDS = { 'AA-normal': 4.5, 'AA-large': 3, 'AAA-normal': 7, 'AAA-large': 4.5 };
+
+export function remediateFailingPairs(failing = [], palette = []) {
+  return failing.map(p => {
+    const target = THRESHOLDS[p.rule] || 4.5;
+    let best = null;
+    for (const candidate of palette) {
+      if (!candidate) continue;
+      const newRatio = contrast(candidate, p.bg);
+      if (newRatio >= target && (!best || newRatio > best.newRatio)) {
+        best = {
+          replace: 'fg',
+          color: candidate,
+          newRatio: Math.round(newRatio * 100) / 100,
+        };
+      }
+    }
+    return { ...p, suggestion: best };
+  });
+}
+
+export { contrast as _contrast };

package/src/extractors/component-clusters.js

@@ -0,0 +1,39 @@
+// Cluster similar component instances by structuralHash + style vector cosine similarity.
+
+function cosine(a = [], b = []) {
+  const n = Math.min(a.length, b.length);
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < n; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : (na === nb ? 1 : 0);
+}
+
+export function clusterComponents(elements = [], { threshold = 0.95 } = {}) {
+  const byKind = {};
+  for (const el of elements) {
+    const key = `${el.kind}|${el.structuralHash}`;
+    (byKind[key] ||= []).push(el);
+  }
+  const out = [];
+  for (const group of Object.values(byKind)) {
+    const variants = [];
+    for (const el of group) {
+      const match = variants.find(v => cosine(v.example.styleVector || [], el.styleVector || []) >= threshold);
+      if (match) {
+        match.instanceCount++;
+      } else {
+        variants.push({ example: el, instanceCount: 1 });
+      }
+    }
+    out.push({
+      kind: group[0].kind,
+      structuralHash: group[0].structuralHash,
+      instanceCount: group.length,
+      variants: variants.map(v => ({ css: v.example.css, instanceCount: v.instanceCount })),
+    });
+  }
+  return out;
+}

package/src/extractors/css-health.js

@@ -0,0 +1,151 @@
+// CSS health audit — operates on page.coverage.stopCSSCoverage() output
+// serialized as [{ url, text, totalBytes, ranges:[{start,end}] }].
+
+function countUsed(ranges = []) {
+  let used = 0;
+  for (const r of ranges) used += Math.max(0, (r.end || 0) - (r.start || 0));
+  return used;
+}
+
+function countImportant(text) {
+  const m = text.match(/!important/g);
+  return m ? m.length : 0;
+}
+
+function countDuplicates(text) {
+  // Count prop:value pairs that appear >=2x across the sheet.
+  const seen = new Map();
+  const re = /([\w-]+)\s*:\s*([^;{}!]+)(\s*!important)?\s*;?/g;
+  for (const m of text.matchAll(re)) {
+    const key = `${m[1].trim()}:${m[2].trim()}`;
+    seen.set(key, (seen.get(key) || 0) + 1);
+  }
+  let dup = 0;
+  for (const n of seen.values()) if (n >= 2) dup += (n - 1);
+  return dup;
+}
+
+function countVendorPrefixes(text) {
+  return {
+    webkit: (text.match(/-webkit-/g) || []).length,
+    moz: (text.match(/-moz-/g) || []).length,
+    ms: (text.match(/-ms-/g) || []).length,
+    o: (text.match(/(^|[^-\w])-o-/g) || []).length,
+  };
+}
+
+function extractKeyframes(text) {
+  const out = [];
+  const re = /@keyframes\s+([\w-]+)\s*\{([\s\S]*?)\n\}/g;
+  for (const m of text.matchAll(re)) {
+    const body = m[2];
+    const steps = (body.match(/(\d+%|from|to)\s*\{/g) || []).length;
+    out.push({ name: m[1], steps });
+  }
+  return out;
+}
+
+function specificityFor(selector) {
+  // Simple WCAG-ish triple: ids, classes+attrs+pseudo-classes, types
+  const ids = (selector.match(/#[\w-]+/g) || []).length;
+  const classes = (selector.match(/\.[\w-]+|\[[^\]]+\]|:(?!:)[\w-]+(?:\([^)]+\))?/g) || []).length;
+  const types = (selector.match(/(?:^|[\s>+~,])([a-z][\w-]*)/gi) || []).length;
+  return [ids, classes, types];
+}
+
+function specificityDistribution(text) {
+  const triples = [];
+  const re = /([^{}]+)\{([^}]*)\}/g;
+  for (const m of text.matchAll(re)) {
+    const selectorList = m[1];
+    for (const sel of selectorList.split(',').map(s => s.trim()).filter(Boolean)) {
+      if (sel.startsWith('@')) continue;
+      triples.push(specificityFor(sel));
+    }
+  }
+  if (triples.length === 0) {
+    return { max: [0, 0, 0], average: [0, 0, 0], count: 0 };
+  }
+  let max = [0, 0, 0];
+  let sum = [0, 0, 0];
+  for (const t of triples) {
+    for (let i = 0; i < 3; i++) {
+      sum[i] += t[i];
+      if (t[i] > max[i]) max[i] = t[i];
+    }
+  }
+  const avg = sum.map(v => Math.round((v / triples.length) * 100) / 100);
+  return { max, average: avg, count: triples.length };
+}
+
+export function extractCssHealth(coverage = []) {
+  const sheets = [];
+  let totalBytes = 0;
+  let usedBytes = 0;
+  let importantCount = 0;
+  let duplicates = 0;
+  const vendorPrefixes = { webkit: 0, moz: 0, ms: 0, o: 0 };
+  const keyframes = [];
+  let specMax = [0, 0, 0];
+  let specSumWeighted = [0, 0, 0];
+  let specCount = 0;
+
+  for (const c of coverage) {
+    const text = c.text || '';
+    const sheetTotal = typeof c.totalBytes === 'number' ? c.totalBytes : text.length;
+    const sheetUsed = countUsed(c.ranges);
+    const sheetUnused = Math.max(0, sheetTotal - sheetUsed);
+    sheets.push({
+      url: c.url || '',
+      totalBytes: sheetTotal,
+      usedBytes: sheetUsed,
+      unusedBytes: sheetUnused,
+      unusedPercent: sheetTotal ? Math.round((sheetUnused / sheetTotal) * 100) : 0,
+    });
+    totalBytes += sheetTotal;
+    usedBytes += sheetUsed;
+
+    importantCount += countImportant(text);
+    duplicates += countDuplicates(text);
+
+    const vp = countVendorPrefixes(text);
+    vendorPrefixes.webkit += vp.webkit;
+    vendorPrefixes.moz += vp.moz;
+    vendorPrefixes.ms += vp.ms;
+    vendorPrefixes.o += vp.o;
+
+    keyframes.push(...extractKeyframes(text));
+
+    const spec = specificityDistribution(text);
+    for (let i = 0; i < 3; i++) {
+      if (spec.max[i] > specMax[i]) specMax[i] = spec.max[i];
+      specSumWeighted[i] += spec.average[i] * spec.count;
+    }
+    specCount += spec.count;
+  }
+
+  const unusedBytes = Math.max(0, totalBytes - usedBytes);
+  const unusedPercent = totalBytes ? Math.round((unusedBytes / totalBytes) * 100) : 0;
+  const specAvg = specCount > 0
+    ? specSumWeighted.map(v => Math.round((v / specCount) * 100) / 100)
+    : [0, 0, 0];
+
+  const issues = [];
+  if (importantCount > 0) issues.push(`${importantCount} !important rule${importantCount > 1 ? 's' : ''}`);
+  if (duplicates > 0) issues.push(`${duplicates} duplicate declaration${duplicates > 1 ? 's' : ''}`);
+  if (unusedPercent >= 50) issues.push(`${unusedPercent}% unused CSS`);
+
+  return {
+    sheets,
+    totalBytes,
+    usedBytes,
+    unusedBytes,
+    unusedPercent,
+    importantCount,
+    duplicates,
+    vendorPrefixes,
+    keyframes,
+    specificity: { max: specMax, average: specAvg, count: specCount },
+    issues,
+  };
+}

package/src/extractors/scoring.js

@@ -73,7 +73,26 @@ export function scoreDesignSystem(design) {
     issues.push(`${design.accessibility.failCount} WCAG contrast failures`);
   }
 
-  // 7. CSS variable usage (0-100)
+  // 7. CSS health (0-100) — additive; does not affect existing weights.
+  if (design.cssHealth) {
+    const ch = design.cssHealth;
+    let h = 100;
+    if (ch.unusedPercent >= 70) h -= 30;
+    else if (ch.unusedPercent >= 50) h -= 20;
+    else if (ch.unusedPercent >= 30) h -= 10;
+    if (ch.importantCount >= 20) h -= 20;
+    else if (ch.importantCount >= 5) h -= 10;
+    else if (ch.importantCount >= 1) h -= 5;
+    if (ch.duplicates >= 20) h -= 15;
+    else if (ch.duplicates >= 5) h -= 8;
+    else if (ch.duplicates >= 1) h -= 3;
+    scores.cssHealth = Math.max(0, h);
+    if (ch.importantCount >= 5) issues.push(`${ch.importantCount} !important rules — prefer specificity over overrides`);
+    if (ch.unusedPercent >= 50) issues.push(`${ch.unusedPercent}% of CSS is unused — consider purging`);
+    if (ch.duplicates >= 5) issues.push(`${ch.duplicates} duplicate CSS declarations`);
+  }
+
+  // 8. CSS variable usage (0-100)
   const varCount = Object.values(design.variables).reduce((s, v) => s + Object.keys(v).length, 0);
   if (varCount >= 20) scores.tokenization = 100;
   else if (varCount >= 10) scores.tokenization = 75;

package/src/extractors/semantic-regions.js

@@ -0,0 +1,44 @@
+// Classify page sections: nav/hero/features/pricing/testimonials/cta/footer/sidebar/content.
+
+const KW = {
+  pricing: /\b(\$\s*\d|per\s?month|\/mo\b|pricing|free|billed)/i,
+  testimonials: /(customer|review|testimonial|said|"|")/i,
+  features: /(feature|benefit|why|what you get)/i,
+  cta: /(get started|sign up|try free|start now|request demo|contact sales)/i,
+};
+
+function classify(s) {
+  const role = (s.role || '').toLowerCase();
+  const tag = (s.tag || '').toLowerCase();
+  if (tag === 'nav' || role === 'navigation') return 'nav';
+  if (tag === 'header' || role === 'banner') return 'nav';
+  if (tag === 'footer' || role === 'contentinfo') return 'footer';
+  if (tag === 'aside' || role === 'complementary') return 'sidebar';
+
+  const cls = (s.className || '').toLowerCase();
+  const id = (s.id || '').toLowerCase();
+  const blob = `${cls} ${id}`;
+  const text = s.text || '';
+  const headings = s.headings || [];
+
+  if (/hero/.test(blob)) return 'hero';
+  if (/pricing/.test(blob) || KW.pricing.test(text)) return 'pricing';
+  if (/testimonial|review/.test(blob) || KW.testimonials.test(text)) return 'testimonials';
+  if (/features?|grid/.test(blob) && s.cardCount >= 3) return 'features';
+  if (KW.features.test(text) && s.cardCount >= 3) return 'features';
+  if (s.buttonCount <= 2 && headings.length && text.length < 400 && KW.cta.test(text)) return 'cta';
+  if (headings.length === 1 && s.buttonCount >= 1 && s.bounds && s.bounds.h > 300) return 'hero';
+  return 'content';
+}
+
+export function extractSemanticRegions(sections = []) {
+  return sections.map(s => ({
+    role: classify(s),
+    tag: s.tag,
+    bounds: s.bounds,
+    heading: (s.headings && s.headings[0]) || null,
+    buttonCount: s.buttonCount || 0,
+    cardCount: s.cardCount || 0,
+    className: s.className || null,
+  }));
+}