designlang 7.1.0 → 8.0.0

package/src/crawler.js

@@ -23,6 +23,9 @@ export async function crawlPage(url, options = {}) {
     cookies, headers, ignore,
     insecure = false,
     userAgent,
+    deepInteract = false,
+    selector,
+    channel,
   } = options;
 
   const launchArgs = [
@@ -38,6 +41,9 @@ export async function crawlPage(url, options = {}) {
   const browser = await chromium.launch({
     headless: true,
     ...(executablePath && { executablePath }),
+    // channel: 'chrome' forces Playwright to use the system Chrome install
+    // instead of the 150MB bundled Chromium — see --system-chrome.
+    ...(channel && { channel }),
     args: launchArgs,
   });
   try {
@@ -89,8 +95,16 @@ export async function crawlPage(url, options = {}) {
     }
 
     const title = await page.title();
-    const lightData = await extractPageData(page, ignore);
+
+    // Auto-interact pass (Tier 2): scroll, open menus, hover, open accordions & a first modal.
+    let interactState = null;
+    if (deepInteract) {
+      interactState = await runInteractionPass(page).catch(() => null);
+    }
+
+    const lightData = await extractPageData(page, ignore, selector);
     lightData.cssCoverage = cssCoverage;
+    if (interactState) lightData.interactState = interactState;
 
     // Component screenshots
     let componentScreenshots = {};
@@ -100,7 +114,17 @@ export async function crawlPage(url, options = {}) {
 
     // Multi-page crawl: discover internal links and extract from them
     let additionalPages = [];
+    const routes = [];
     if (depth > 0) {
+      // Seed routes with the primary page
+      try {
+        const u0 = new URL(url);
+        routes.push({
+          url,
+          path: u0.pathname || '/',
+          computedStylesSample: (lightData.computedStyles || []).slice(0, 2000),
+        });
+      } catch { /* ignore */ }
       const internalLinks = await discoverInternalLinks(page, url, depth);
       for (const link of internalLinks) {
         try {
@@ -109,6 +133,14 @@ export async function crawlPage(url, options = {}) {
           await page.evaluate(() => document.fonts.ready).catch(() => {});
           const pageData = await extractPageData(page);
           additionalPages.push({ url: link, data: pageData });
+          try {
+            const u = new URL(link);
+            routes.push({
+              url: link,
+              path: u.pathname || '/',
+              computedStylesSample: (pageData.computedStyles || []).slice(0, 2000),
+            });
+          } catch { /* ignore */ }
         } catch { /* skip failed pages */ }
       }
     }
@@ -153,6 +185,8 @@ export async function crawlPage(url, options = {}) {
       url, title,
       light: lightData,
       dark: darkData,
+      interactState,
+      routes: routes.length > 0 ? routes : undefined,
       pagesAnalyzed: 1 + additionalPages.length,
       componentScreenshots,
     };
@@ -228,8 +262,139 @@ export async function captureComponentScreenshots(page, outDir) {
   return result;
 }
 
-async function extractPageData(page, ignoreSelectors) {
-  const data = await page.evaluate(({ maxElements, ignoreSelectors }) => {
+async function snapshotSelector(page, selector) {
+  try {
+    return await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return null;
+      const cs = getComputedStyle(el);
+      return {
+        color: cs.color, backgroundColor: cs.backgroundColor,
+        borderColor: cs.borderColor, boxShadow: cs.boxShadow,
+        transform: cs.transform, opacity: cs.opacity,
+        outline: cs.outline, textDecoration: cs.textDecoration,
+      };
+    }, selector);
+  } catch { return null; }
+}
+
+async function runInteractionPass(page) {
+  const state = {
+    scrollSettled: false,
+    menusOpened: 0,
+    hoverSamples: [],
+    accordionsOpened: 0,
+    modals: [],
+  };
+
+  // 1) Full-page scroll in 4 steps to trigger lazy-load + scroll-linked animations
+  try {
+    for (let i = 1; i <= 4; i++) {
+      await page.evaluate((step) => {
+        const h = document.body.scrollHeight;
+        window.scrollTo(0, (h * step) / 4);
+      }, i).catch(() => {});
+      await page.waitForTimeout(300);
+      await page.waitForLoadState('networkidle', { timeout: 2000 }).catch(() => {});
+    }
+    await page.evaluate(() => window.scrollTo(0, 0)).catch(() => {});
+    await page.waitForTimeout(200);
+    state.scrollSettled = true;
+  } catch { /* ignore */ }
+
+  // 2) Open menus / dropdowns
+  try {
+    const triggers = await page.$$('nav [aria-haspopup], [aria-expanded="false"], .menu-toggle, .hamburger, [data-menu]');
+    for (const t of triggers.slice(0, 5)) {
+      try {
+        await t.click({ timeout: 1000, trial: false });
+        state.menusOpened++;
+      } catch { /* ignore */ }
+    }
+    await page.waitForTimeout(400);
+  } catch { /* ignore */ }
+
+  // 3) Hover up to 6 buttons + 6 links with style diffs
+  try {
+    const btnSelectors = await page.evaluate(() => {
+      const arr = [];
+      const btns = Array.from(document.querySelectorAll('button')).slice(0, 6);
+      btns.forEach((el, i) => arr.push(`button:nth-of-type(${i + 1})`));
+      return arr;
+    });
+    const linkSelectors = await page.evaluate(() => {
+      const arr = [];
+      const links = Array.from(document.querySelectorAll('a[href]')).slice(0, 6);
+      links.forEach((el, i) => arr.push(`a[href]:nth-of-type(${i + 1})`));
+      return arr;
+    });
+    const samples = [...(btnSelectors || []), ...(linkSelectors || [])].slice(0, 12);
+    for (const sel of samples) {
+      const before = await snapshotSelector(page, sel);
+      if (!before) continue;
+      try {
+        await page.hover(sel, { timeout: 500 });
+        await page.waitForTimeout(100);
+        const after = await snapshotSelector(page, sel);
+        if (after) state.hoverSamples.push({ selector: sel, before, after });
+      } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+
+  // 4) Accordions / details
+  try {
+    const accs = await page.$$('details, [role="tab"], [data-accordion]');
+    for (const a of accs.slice(0, 6)) {
+      try {
+        await a.click({ timeout: 800 });
+        state.accordionsOpened++;
+      } catch { /* ignore */ }
+    }
+    await page.waitForTimeout(200);
+  } catch { /* ignore */ }
+
+  // 5) First triggerable modal / dialog
+  try {
+    const candidates = await page.$$('button, a[role="button"]');
+    let triggered = false;
+    for (const c of candidates.slice(0, 30)) {
+      if (triggered) break;
+      try {
+        const txt = (await c.innerText({ timeout: 500 }).catch(() => '')) || '';
+        if (!/sign\s*in|log\s*in|menu|open|subscribe/i.test(txt)) continue;
+        await c.click({ timeout: 2000 });
+        await page.waitForTimeout(600);
+        const snapshot = await page.evaluate(() => {
+          const dlg = document.querySelector('dialog[open], [role="dialog"], [aria-modal="true"]');
+          if (!dlg) return null;
+          const cs = getComputedStyle(dlg);
+          const r = dlg.getBoundingClientRect();
+          return {
+            tag: dlg.tagName.toLowerCase(),
+            role: dlg.getAttribute('role') || '',
+            bg: cs.backgroundColor,
+            color: cs.color,
+            boxShadow: cs.boxShadow,
+            borderRadius: cs.borderRadius,
+            width: r.width,
+            height: r.height,
+          };
+        });
+        if (snapshot) {
+          state.modals.push({ trigger: txt.slice(0, 60), snapshot });
+          triggered = true;
+        }
+        await page.keyboard.press('Escape').catch(() => {});
+        await page.waitForTimeout(200);
+      } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+
+  return state;
+}
+
+async function extractPageData(page, ignoreSelectors, scopeSelector) {
+  const data = await page.evaluate(({ maxElements, ignoreSelectors, scopeSelector }) => {
     // Remove ignored elements before extraction
     if (ignoreSelectors && ignoreSelectors.length > 0) {
       for (const sel of ignoreSelectors) {
@@ -260,8 +425,85 @@ async function extractPageData(page, ignoreSelectors) {
       }
       return collected;
     }
-    const elements = collectElements(document, []);
 
+    // If --selector was provided, scope element collection to the matching
+    // subtrees only. Falls back to the full document if the selector is
+    // invalid or returns no matches.
+    let scopeRoots = [document];
+    if (scopeSelector) {
+      try {
+        const matches = Array.from(document.querySelectorAll(scopeSelector));
+        if (matches.length > 0) scopeRoots = matches;
+      } catch { /* invalid selector → use document */ }
+    }
+    const elements = [];
+    for (const root of scopeRoots) {
+      if (root !== document && root.nodeType === 1) elements.push(root);
+      collectElements(root, elements);
+      if (elements.length >= maxElements) break;
+    }
+
+    // Build a lightweight index: stylesheet URL + their top selectors.
+    // Used to attribute each element's primary source stylesheet.
+    const sheetIndex = [];
+    try {
+      for (const sheet of document.styleSheets) {
+        const entry = { url: sheet.href || '', mediaText: sheet.media ? sheet.media.mediaText : '', selectors: [] };
+        try {
+          let cap = 0;
+          for (const rule of sheet.cssRules) {
+            if (cap >= 200) break;
+            if (rule && rule.selectorText) {
+              entry.selectors.push(rule.selectorText);
+              cap++;
+            }
+          }
+        } catch { /* cross-origin */ }
+        if (entry.url || entry.selectors.length > 0) sheetIndex.push(entry);
+      }
+    } catch { /* no access */ }
+
+    function findSourceFor(el) {
+      // Try to find the first stylesheet that has a selector matching this element.
+      for (const sheet of sheetIndex) {
+        for (const sel of sheet.selectors) {
+          try {
+            // selectorText can contain multiple comma-separated selectors
+            if (el.matches(sel)) {
+              return { url: sheet.url, mediaText: sheet.mediaText };
+            }
+          } catch { /* invalid or unsupported selector */ }
+        }
+      }
+      return null;
+    }
+
+    function readPseudo(el, which) {
+      try {
+        const ps = getComputedStyle(el, which);
+        const content = ps.getPropertyValue('content');
+        if (!content || content === 'none' || content === 'normal') return null;
+        return {
+          content,
+          display: ps.display,
+          position: ps.position,
+          top: ps.top,
+          left: ps.left,
+          right: ps.right,
+          bottom: ps.bottom,
+          width: ps.width,
+          height: ps.height,
+          background: ps.background,
+          color: ps.color,
+          border: ps.border,
+          transform: ps.transform,
+          mask: ps.mask || ps.getPropertyValue('-webkit-mask') || '',
+          clipPath: ps.clipPath || ps.getPropertyValue('-webkit-clip-path') || '',
+        };
+      } catch { return null; }
+    }
+
+    let sourceAttrBudget = 500;
     for (const el of elements) {
       const cs = getComputedStyle(el);
       const tag = el.tagName.toLowerCase();
@@ -270,8 +512,27 @@ async function extractPageData(page, ignoreSelectors) {
       const rect = el.getBoundingClientRect();
       const area = rect.width * rect.height;
 
+      const before = readPseudo(el, '::before');
+      const after = readPseudo(el, '::after');
+      const pseudo = (before || after) ? { before, after } : null;
+
+      let sources = null;
+      if (sourceAttrBudget > 0) {
+        const s = findSourceFor(el);
+        if (s) sources = [s];
+        sourceAttrBudget--;
+      }
+
+      // hasText: at least one direct text-node child with visible characters —
+      // lets downstream extractors filter decorative spans/divs out of WCAG
+      // contrast accounting.
+      let hasText = false;
+      for (const node of el.childNodes) {
+        if (node.nodeType === 3 && node.textContent && node.textContent.trim()) { hasText = true; break; }
+      }
+
       results.computedStyles.push({
-        tag, classList, role, area,
+        tag, classList, role, area, hasText,
         color: cs.color,
         backgroundColor: cs.backgroundColor,
         backgroundImage: cs.backgroundImage,
@@ -307,6 +568,14 @@ async function extractPageData(page, ignoreSelectors) {
         gridTemplateColumns: cs.gridTemplateColumns,
         gridTemplateRows: cs.gridTemplateRows,
         maxWidth: cs.maxWidth,
+        fontVariationSettings: cs.fontVariationSettings || cs.getPropertyValue('font-variation-settings') || 'normal',
+        fontFeatureSettings: cs.fontFeatureSettings || cs.getPropertyValue('font-feature-settings') || 'normal',
+        textWrap: cs.textWrap || cs.getPropertyValue('text-wrap') || '',
+        textDecorationStyle: cs.textDecorationStyle || '',
+        textDecorationThickness: cs.textDecorationThickness || '',
+        textUnderlineOffset: cs.textUnderlineOffset || '',
+        pseudo,
+        sources,
       });
     }
 
@@ -366,6 +635,82 @@ async function extractPageData(page, ignoreSelectors) {
       }
     } catch { /* no access */ }
 
+    // Container queries (@container rules), env() usage, and modern colors
+    results.containerQueries = [];
+    results.envUsage = [];
+    results.modernColors = [];
+    const MODERN_COLOR_RE = /(oklch\([^)]+\)|oklab\([^)]+\)|color-mix\([^)]+\)|light-dark\([^)]+\)|color\(\s*display-p3[^)]+\)|color\(\s*rec2020[^)]+\))/gi;
+    function walkRulesForContainersAndEnv(rules) {
+      for (const rule of rules) {
+        try {
+          // Scan declarations for modern color functions
+          if (rule.style && rule.cssText) {
+            const css = rule.cssText;
+            for (const m of css.matchAll(MODERN_COLOR_RE)) {
+              const raw = m[1];
+              let type = 'other';
+              if (/^oklch/i.test(raw)) type = 'oklch';
+              else if (/^oklab/i.test(raw)) type = 'oklab';
+              else if (/^color-mix/i.test(raw)) type = 'color-mix';
+              else if (/^light-dark/i.test(raw)) type = 'light-dark';
+              else if (/display-p3/i.test(raw)) type = 'display-p3';
+              else if (/rec2020/i.test(raw)) type = 'rec2020';
+              // Try to infer property
+              let property = '';
+              for (let i = 0; i < rule.style.length; i++) {
+                const p = rule.style[i];
+                if ((rule.style.getPropertyValue(p) || '').includes(raw)) { property = p; break; }
+              }
+              results.modernColors.push({ raw, type, property, selector: rule.selectorText || '' });
+            }
+          }
+          // Container query
+          if (typeof CSSContainerRule !== 'undefined' && rule instanceof CSSContainerRule) {
+            const inner = [];
+            try {
+              for (const inr of rule.cssRules) {
+                if (inr.selectorText) inner.push(inr.selectorText);
+              }
+            } catch {}
+            results.containerQueries.push({
+              condition: rule.conditionText || rule.containerQuery || '',
+              selectorText: inner.join(', '),
+              declarationCount: inner.length,
+            });
+          } else if (rule.cssText && rule.cssText.startsWith('@container')) {
+            results.containerQueries.push({
+              condition: rule.conditionText || '',
+              selectorText: '',
+              declarationCount: 0,
+            });
+          }
+          // env() scan on declaration text
+          if (rule.style) {
+            const css = rule.cssText || '';
+            const envMatches = css.match(/env\(\s*(safe-area-inset-[a-z]+|viewport-[a-z-]+|[a-z-]+)/gi);
+            if (envMatches) {
+              for (const m of envMatches) {
+                results.envUsage.push(m.replace(/^env\(\s*/, '').trim());
+              }
+            }
+          }
+          // Recurse into grouping rules (media, supports, container)
+          if (rule.cssRules) {
+            walkRulesForContainersAndEnv(rule.cssRules);
+          }
+        } catch { /* ignore per-rule errors */ }
+      }
+    }
+    try {
+      for (const sheet of document.styleSheets) {
+        try {
+          walkRulesForContainersAndEnv(sheet.cssRules);
+        } catch { /* cross-origin — already tracked */ }
+      }
+    } catch { /* no access */ }
+    // dedupe envUsage
+    results.envUsage = [...new Set(results.envUsage)];
+
     // Component clusters (v7): per-element features for similarity-based grouping.
     function colorToChannels(str) {
       if (!str) return [0, 0, 0, 0];
@@ -524,7 +869,7 @@ async function extractPageData(page, ignoreSelectors) {
     }
 
     return results;
-  }, { maxElements: MAX_ELEMENTS, ignoreSelectors: ignoreSelectors || [] });
+  }, { maxElements: MAX_ELEMENTS, ignoreSelectors: ignoreSelectors || [], scopeSelector: scopeSelector || null });
 
   // Fetch and parse cross-origin stylesheets
   if (data.crossOriginSheets && data.crossOriginSheets.length > 0) {
@@ -551,6 +896,31 @@ function parseCrossOriginCSS(cssText, data) {
   for (const m of cssText.matchAll(/@media\s*([^{]+)\{/g)) {
     data.mediaQueries.push(m[1].trim());
   }
+  // Container queries
+  if (!data.containerQueries) data.containerQueries = [];
+  for (const m of cssText.matchAll(/@container\s*([^{]*)\{/g)) {
+    data.containerQueries.push({ condition: m[1].trim(), selectorText: '', declarationCount: 0 });
+  }
+  // env() usage
+  if (!data.envUsage) data.envUsage = [];
+  for (const m of cssText.matchAll(/env\(\s*(safe-area-inset-[a-z]+|viewport-[a-z-]+)/gi)) {
+    data.envUsage.push(m[1]);
+  }
+  data.envUsage = [...new Set(data.envUsage)];
+  // Modern colors
+  if (!data.modernColors) data.modernColors = [];
+  const modernRe = /(oklch\([^)]+\)|oklab\([^)]+\)|color-mix\([^)]+\)|light-dark\([^)]+\)|color\(\s*display-p3[^)]+\)|color\(\s*rec2020[^)]+\))/gi;
+  for (const m of cssText.matchAll(modernRe)) {
+    const raw = m[1];
+    let type = 'other';
+    if (/^oklch/i.test(raw)) type = 'oklch';
+    else if (/^oklab/i.test(raw)) type = 'oklab';
+    else if (/^color-mix/i.test(raw)) type = 'color-mix';
+    else if (/^light-dark/i.test(raw)) type = 'light-dark';
+    else if (/display-p3/i.test(raw)) type = 'display-p3';
+    else if (/rec2020/i.test(raw)) type = 'rec2020';
+    data.modernColors.push({ raw, type, property: '', selector: '' });
+  }
   // Keyframes
   for (const m of cssText.matchAll(/@keyframes\s+([\w-]+)\s*\{([\s\S]*?)\n\}/g)) {
     const steps = [];

package/src/extractors/accessibility.js

@@ -28,16 +28,59 @@ function wcagLevel(ratio, isLargeText) {
   return 'FAIL';
 }
 
+// Tags where "foreground vs background" contrast is *not* a WCAG text concern —
+// SVG/icon glyphs, media, form primitives, and structural containers without
+// direct text. Filtering these removes the overlay/decorative false-positives
+// that used to crater scores on dark-themed sites.
+const NON_TEXT_TAGS = new Set([
+  'svg', 'path', 'circle', 'rect', 'polygon', 'polyline', 'line', 'ellipse',
+  'use', 'defs', 'g', 'clippath', 'mask', 'filter', 'symbol', 'stop', 'lineargradient', 'radialgradient',
+  'img', 'picture', 'video', 'audio', 'canvas', 'iframe', 'source', 'track',
+  'br', 'hr', 'wbr',
+  'input', 'select', 'textarea', 'progress', 'meter', 'option', 'optgroup',
+  'script', 'style', 'link', 'meta', 'head', 'html', 'body',
+  'main', 'section', 'article', 'aside', 'header', 'footer', 'nav',
+  'div', 'figure', 'form', 'fieldset', 'ul', 'ol', 'dl',
+]);
+
+const TEXT_BEARING_TAGS = new Set([
+  'p', 'a', 'button', 'label', 'li', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'td', 'th', 'code', 'pre', 'em', 'strong', 'small', 'b', 'i', 'u',
+  'time', 'summary', 'figcaption', 'blockquote', 'q', 'mark', 'cite', 'abbr',
+  'dt', 'dd', 'kbd', 'samp', 'var', 'sub', 'sup', 'del', 'ins', 'caption', 'legend',
+  // span is a high-noise/high-signal tag — it wraps both real text and
+  // decorative glyphs. Include it but require an explicit background (the
+  // opacity filter downstream still removes the decorative transparent ones).
+  'span',
+]);
+
+function isContrastRelevant(el) {
+  const tag = (el.tag || '').toLowerCase();
+  if (NON_TEXT_TAGS.has(tag)) return false;
+  if (!TEXT_BEARING_TAGS.has(tag)) return false;
+  // If the crawler captured hasText, trust it — filters decorative
+  // span/link/button wrappers that hold no real glyphs. If hasText wasn't
+  // captured (older fixtures, unit tests) fall back to inclusion.
+  if (el.hasText === false) return false;
+  return true;
+}
+
 export function extractAccessibility(computedStyles) {
   const pairs = new Map(); // "fg|bg" -> { fg, bg, count, elements }
 
   for (const el of computedStyles) {
+    if (!isContrastRelevant(el)) continue;
+
     const fg = parseColor(el.color);
     const bg = parseColor(el.backgroundColor);
-    if (!fg || !bg || bg.a === 0) continue;
+    if (!fg || !bg) continue;
+    // Skip transparent/semi-transparent — real contrast depends on the parent
+    // stack which we don't composite. Counting these as "fails" is noise.
+    if (bg.a < 0.9 || fg.a < 0.9) continue;
 
     const fgHex = rgbToHex(fg);
     const bgHex = rgbToHex(bg);
+    if (fgHex === bgHex) continue;
     const key = `${fgHex}|${bgHex}`;
 
     if (!pairs.has(key)) {

package/src/extractors/colors.js

@@ -1,25 +1,39 @@
-import { parseColor, rgbToHex, rgbToHsl, clusterColors, isSaturated } from '../utils.js';
+import { parseColor, rgbToHex, rgbToHsl, clusterColors, isSaturated, colorDistance } from '../utils.js';
+
+const INTERACTIVE_TAGS = new Set(['a', 'button']);
+const INTERACTIVE_ROLES = new Set(['button', 'link', 'menuitem', 'tab']);
+const INTERACTIVE_CLASS_RE = /\b(btn|button|cta|primary|action)\b/i;
+
+function isInteractive(el) {
+  if (!el) return false;
+  if (INTERACTIVE_TAGS.has(el.tag)) return true;
+  if (el.role && INTERACTIVE_ROLES.has(el.role)) return true;
+  if (el.classList && INTERACTIVE_CLASS_RE.test(el.classList)) return true;
+  return false;
+}
 
 export function extractColors(computedStyles) {
-  const colorMap = new Map(); // hex -> { hex, parsed, count, contexts: Set }
+  const colorMap = new Map(); // hex -> { hex, parsed, count, contexts: Set, interactiveBg: number }
 
-  function addColor(value, context) {
+  function addColor(value, context, { interactive = false } = {}) {
     const parsed = parseColor(value);
     if (!parsed || parsed.a === 0) return;
     const hex = rgbToHex(parsed);
     if (!colorMap.has(hex)) {
-      colorMap.set(hex, { hex, parsed, count: 0, contexts: new Set() });
+      colorMap.set(hex, { hex, parsed, count: 0, contexts: new Set(), interactiveBg: 0 });
     }
     const entry = colorMap.get(hex);
     entry.count++;
     entry.contexts.add(context);
+    if (interactive && context === 'background') entry.interactiveBg++;
   }
 
   const gradients = new Set();
 
   for (const el of computedStyles) {
+    const interactive = isInteractive(el);
     addColor(el.color, 'text');
-    addColor(el.backgroundColor, 'background');
+    addColor(el.backgroundColor, 'background', { interactive });
     addColor(el.borderColor, 'border');
 
     if (el.backgroundImage && el.backgroundImage !== 'none' && el.backgroundImage.includes('gradient')) {
@@ -30,12 +44,21 @@ export function extractColors(computedStyles) {
   const allColors = Array.from(colorMap.values());
   const clusters = clusterColors(allColors, 15);
 
-  // Classify roles
+  // Aggregate interactive-bg score per cluster (sum across members)
+  for (const cluster of clusters) {
+    cluster.interactiveBg = cluster.members.reduce((s, m) => s + (m.interactiveBg || 0), 0);
+    const { s: sat, l: lit } = rgbToHsl(cluster.representative);
+    cluster.saturation = sat;
+    cluster.lightness = lit;
+  }
+
+  // Classify roles — tighten chromatic threshold so pale grays (hsl sat < 25) don't qualify
   const neutrals = [];
   const chromatic = [];
 
   for (const cluster of clusters) {
-    if (isSaturated(cluster.representative)) {
+    const chromaticEnough = cluster.saturation > 25 && cluster.lightness > 5 && cluster.lightness < 95;
+    if (chromaticEnough || (isSaturated(cluster.representative) && cluster.interactiveBg > 0)) {
       chromatic.push(cluster);
     } else {
       neutrals.push(cluster);
@@ -61,12 +84,27 @@ export function extractColors(computedStyles) {
     }
   }
 
-  const primary = chromatic[0] || null;
-  const secondary = chromatic[1] || null;
-  const accent = chromatic.find(c => {
-    const pct = c.count / allColors.reduce((s, a) => s + a.count, 0);
+  // Rank chromatic clusters by brand-likelihood:
+  //   interactiveBg carries the most signal (it's a CTA color)
+  //   saturation comes next (brand colors are usually punchy)
+  //   raw usage count is a weak tiebreaker (avoids neutral-heavy sites dominating)
+  function brandScore(c) {
+    return c.interactiveBg * 100 + c.saturation * 2 + Math.log10(Math.max(1, c.count));
+  }
+  const ranked = [...chromatic].sort((a, b) => brandScore(b) - brandScore(a));
+
+  const primary = ranked[0] || null;
+  // secondary: distinct hue from primary
+  const secondary = ranked.find(c => {
+    if (!primary || c === primary) return false;
+    return colorDistance(c.representative, primary.representative) > 60;
+  }) || ranked[1] || null;
+  // accent: sparse chromatic, prefers background context
+  const accent = ranked.find(c => {
+    if (c === primary || c === secondary) return false;
+    const pct = c.count / Math.max(1, allColors.reduce((s, a) => s + a.count, 0));
     return pct < 0.05 && c.members.some(m => m.contexts.has('background'));
-  }) || chromatic[2] || null;
+  }) || ranked.find(c => c !== primary && c !== secondary) || null;
 
   return {
     primary: primary ? { hex: primary.hex, rgb: primary.representative, hsl: rgbToHsl(primary.representative), count: primary.count } : null,