designlang 7.0.0 → 7.2.0

package/src/crawler.js

@@ -17,17 +17,36 @@ async function gotoWithRetry(page, url, opts, retries = 3) {
 }
 
 export async function crawlPage(url, options = {}) {
-  const { width = 1280, height = 800, wait = 0, dark = false, depth = 0, screenshots = false, outDir = '', executablePath, browserArgs, cookies, headers, ignore } = options;
+  const {
+    width = 1280, height = 800, wait = 0, dark = false, depth = 0,
+    screenshots = false, outDir = '', executablePath, browserArgs,
+    cookies, headers, ignore,
+    insecure = false,
+    userAgent,
+    deepInteract = false,
+  } = options;
+
+  const launchArgs = [
+    ...(browserArgs || []),
+    // Common flags that help with dev environments and CI. Insecure-only flags
+    // are added below when the user opts in.
+    '--disable-dev-shm-usage',
+  ];
+  if (insecure) {
+    launchArgs.push('--ignore-certificate-errors', '--ignore-ssl-errors');
+  }
 
   const browser = await chromium.launch({
     headless: true,
     ...(executablePath && { executablePath }),
-    ...(browserArgs && { args: browserArgs }),
+    args: launchArgs,
   });
   try {
     const context = await browser.newContext({
       viewport: { width, height },
       colorScheme: 'light',
+      ignoreHTTPSErrors: insecure,
+      ...(userAgent && { userAgent }),
       ...(headers && { extraHTTPHeaders: headers }),
     });
 
@@ -71,8 +90,16 @@ export async function crawlPage(url, options = {}) {
     }
 
     const title = await page.title();
+
+    // 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);
     lightData.cssCoverage = cssCoverage;
+    if (interactState) lightData.interactState = interactState;
 
     // Component screenshots
     let componentScreenshots = {};
@@ -82,7 +109,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 {
@@ -91,6 +128,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 */ }
       }
     }
@@ -135,6 +180,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,
     };
@@ -210,6 +257,137 @@ export async function captureComponentScreenshots(page, outDir) {
   return result;
 }
 
+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) {
   const data = await page.evaluate(({ maxElements, ignoreSelectors }) => {
     // Remove ignored elements before extraction
@@ -244,6 +422,67 @@ async function extractPageData(page, ignoreSelectors) {
     }
     const elements = collectElements(document, []);
 
+    // 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();
@@ -252,6 +491,17 @@ 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--;
+      }
+
       results.computedStyles.push({
         tag, classList, role, area,
         color: cs.color,
@@ -289,6 +539,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,
       });
     }
 
@@ -348,6 +606,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];
@@ -533,6 +867,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/interaction-states.js

@@ -0,0 +1,57 @@
+// Structured catalog of transition styles captured by the Tier-2 interaction
+// pass — hover deltas, modal appearance, menu styling.
+
+function diffStyles(before, after) {
+  const diff = {};
+  if (!before || !after) return diff;
+  for (const k of Object.keys(after)) {
+    if (before[k] !== after[k]) {
+      diff[k] = { from: before[k], to: after[k] };
+    }
+  }
+  return diff;
+}
+
+export function extractInteractionStates(interactState) {
+  if (!interactState || typeof interactState !== 'object') {
+    return {
+      scrollSettled: false,
+      menusOpened: 0,
+      hover: { sampled: 0, changed: 0, deltas: [] },
+      accordionsOpened: 0,
+      modals: [],
+    };
+  }
+
+  const deltas = [];
+  const samples = Array.isArray(interactState.hoverSamples) ? interactState.hoverSamples : [];
+  for (const s of samples) {
+    const d = diffStyles(s.before, s.after);
+    if (Object.keys(d).length > 0) {
+      deltas.push({ selector: s.selector, changes: d });
+    }
+  }
+
+  const modals = Array.isArray(interactState.modals) ? interactState.modals.map(m => ({
+    trigger: m.trigger || '',
+    bg: m.snapshot?.bg || '',
+    color: m.snapshot?.color || '',
+    boxShadow: m.snapshot?.boxShadow || '',
+    borderRadius: m.snapshot?.borderRadius || '',
+    width: m.snapshot?.width || 0,
+    height: m.snapshot?.height || 0,
+    role: m.snapshot?.role || '',
+  })) : [];
+
+  return {
+    scrollSettled: !!interactState.scrollSettled,
+    menusOpened: interactState.menusOpened || 0,
+    hover: {
+      sampled: samples.length,
+      changed: deltas.length,
+      deltas,
+    },
+    accordionsOpened: interactState.accordionsOpened || 0,
+    modals,
+  };
+}

package/src/extractors/modern-css.js

@@ -0,0 +1,100 @@
+// Extractor for modern CSS features captured by the crawler:
+//   - Pseudo-elements (::before / ::after)
+//   - Variable-font axes (font-variation-settings)
+//   - OpenType features (font-feature-settings)
+//   - Modern text layout (text-wrap, text-decoration-*)
+//   - Container queries (@container)
+//   - env() usage (safe-area-inset-*, viewport-*)
+
+export function extractModernCss(payload) {
+  const light = (payload && payload.light) || payload || {};
+  const styles = Array.isArray(light.computedStyles) ? light.computedStyles : [];
+
+  // Pseudo-elements
+  const pseudoSamples = [];
+  let pseudoCount = 0;
+  for (const s of styles) {
+    const p = s && s.pseudo;
+    if (!p) continue;
+    if (p.before) { pseudoCount++; if (pseudoSamples.length < 20) pseudoSamples.push({ tag: s.tag, classList: s.classList, which: '::before', style: p.before }); }
+    if (p.after) { pseudoCount++; if (pseudoSamples.length < 20) pseudoSamples.push({ tag: s.tag, classList: s.classList, which: '::after', style: p.after }); }
+  }
+
+  // Variable fonts
+  const axesMap = new Map();
+  let variableFontCount = 0;
+  for (const s of styles) {
+    const v = s && s.fontVariationSettings;
+    if (!v || v === 'normal' || v === '') continue;
+    variableFontCount++;
+    // e.g. "\"wght\" 600, \"slnt\" -4"
+    for (const m of String(v).matchAll(/"([^"]+)"\s+(-?\d+(?:\.\d+)?)/g)) {
+      const axis = m[1];
+      const val = parseFloat(m[2]);
+      if (!axesMap.has(axis)) axesMap.set(axis, { axis, min: val, max: val, count: 0 });
+      const a = axesMap.get(axis);
+      a.min = Math.min(a.min, val);
+      a.max = Math.max(a.max, val);
+      a.count++;
+    }
+  }
+
+  // OpenType features
+  const featMap = new Map();
+  for (const s of styles) {
+    const f = s && s.fontFeatureSettings;
+    if (!f || f === 'normal' || f === '') continue;
+    for (const m of String(f).matchAll(/"([^"]+)"(?:\s+(on|off|\d+))?/g)) {
+      const key = m[1];
+      featMap.set(key, (featMap.get(key) || 0) + 1);
+    }
+  }
+
+  // Text-wrap / decoration
+  const textWrapMap = new Map();
+  const decStyleMap = new Map();
+  const thicknessMap = new Map();
+  const offsetMap = new Map();
+  for (const s of styles) {
+    if (s.textWrap && s.textWrap !== 'wrap' && s.textWrap !== '') {
+      textWrapMap.set(s.textWrap, (textWrapMap.get(s.textWrap) || 0) + 1);
+    }
+    if (s.textDecorationStyle && s.textDecorationStyle !== 'solid' && s.textDecorationStyle !== '') {
+      decStyleMap.set(s.textDecorationStyle, (decStyleMap.get(s.textDecorationStyle) || 0) + 1);
+    }
+    if (s.textDecorationThickness && s.textDecorationThickness !== 'auto' && s.textDecorationThickness !== '') {
+      thicknessMap.set(s.textDecorationThickness, (thicknessMap.get(s.textDecorationThickness) || 0) + 1);
+    }
+    if (s.textUnderlineOffset && s.textUnderlineOffset !== 'auto' && s.textUnderlineOffset !== '') {
+      offsetMap.set(s.textUnderlineOffset, (offsetMap.get(s.textUnderlineOffset) || 0) + 1);
+    }
+  }
+
+  const containerQueries = Array.isArray(light.containerQueries) ? light.containerQueries : [];
+  const envUsage = Array.isArray(light.envUsage) ? light.envUsage : [];
+
+  return {
+    pseudoElements: {
+      count: pseudoCount,
+      samples: pseudoSamples,
+    },
+    variableFonts: {
+      count: variableFontCount,
+      axes: [...axesMap.values()].sort((a, b) => b.count - a.count),
+    },
+    openTypeFeatures: [...featMap.entries()]
+      .map(([feature, count]) => ({ feature, count }))
+      .sort((a, b) => b.count - a.count),
+    textWrap: {
+      wrap: [...textWrapMap.entries()].map(([value, count]) => ({ value, count })),
+      decorationStyle: [...decStyleMap.entries()].map(([value, count]) => ({ value, count })),
+      decorationThickness: [...thicknessMap.entries()].map(([value, count]) => ({ value, count })),
+      underlineOffset: [...offsetMap.entries()].map(([value, count]) => ({ value, count })),
+    },
+    containerQueries: {
+      count: containerQueries.length,
+      rules: containerQueries,
+    },
+    envUsage: [...new Set(envUsage)],
+  };
+}

package/src/extractors/token-sources.js

@@ -0,0 +1,65 @@
+// Attribute top design tokens back to the stylesheet URL that most likely
+// contributed them. Uses the per-element `sources` captured by the crawler.
+
+import { parseColor, rgbToHex } from '../utils.js';
+
+function firstSourceUrlWhere(styles, predicate) {
+  for (const s of styles) {
+    if (!s || !predicate(s)) continue;
+    const src = Array.isArray(s.sources) ? s.sources[0] : null;
+    if (src && src.url) return src.url;
+  }
+  return '';
+}
+
+export function extractTokenSources(design, computedStyles) {
+  const styles = Array.isArray(computedStyles) ? computedStyles : [];
+  const out = [];
+
+  // Primary color
+  const primaryHex = design.colors?.primary?.hex;
+  if (primaryHex) {
+    const url = firstSourceUrlWhere(styles, s => {
+      const p = parseColor(s.color);
+      return p && rgbToHex(p) === primaryHex;
+    });
+    out.push({ token: 'color.primary', path: 'colors.primary', sourceUrl: url });
+  }
+
+  // Text color (first in design.colors.text[])
+  const textHex = (design.colors?.text || [])[0];
+  if (textHex) {
+    const url = firstSourceUrlWhere(styles, s => {
+      const p = parseColor(s.color);
+      return p && rgbToHex(p) === textHex;
+    });
+    out.push({ token: 'color.text', path: 'colors.text[0]', sourceUrl: url });
+  }
+
+  // Body font — first typography family
+  const bodyFont = design.typography?.families?.[0]?.name;
+  if (bodyFont) {
+    const url = firstSourceUrlWhere(styles, s => typeof s.fontFamily === 'string' && s.fontFamily.includes(bodyFont));
+    out.push({ token: 'font.body', path: 'typography.families[0]', sourceUrl: url });
+  }
+
+  // Spacing base
+  const spacingBase = design.spacing?.base;
+  if (spacingBase != null) {
+    const target = `${spacingBase}px`;
+    const url = firstSourceUrlWhere(styles,
+      s => s.paddingTop === target || s.paddingLeft === target || s.marginTop === target || s.gap === target);
+    out.push({ token: 'spacing.base', path: 'spacing.base', sourceUrl: url });
+  }
+
+  // Radius base — first non-zero from design.borders.radii
+  const radii = design.borders?.radii || [];
+  const firstRadius = radii.find(r => (r.value || r) && (r.value || r) !== '0px');
+  if (firstRadius) {
+    const target = typeof firstRadius === 'string' ? firstRadius : (firstRadius.value || '');
+    const url = firstSourceUrlWhere(styles, s => s.borderRadius === target);
+    out.push({ token: 'radius.base', path: 'borders.radii[0]', sourceUrl: url });
+  }
+
+  return out;
+}