designlang 7.2.0 → 9.0.0

package/src/extractors/scoring.js

@@ -4,14 +4,16 @@ export function scoreDesignSystem(design) {
   const scores = {};
   const issues = [];
 
-  // 1. Color discipline (0-100)
-  // Fewer unique colors = more disciplined
+  // 1. Color discipline (0-100) — calibrated against real production sites
+  // (Linear, Stripe, Vercel, GitHub, Apple) which commonly ship 20–50 colors
+  // once you include hover/disabled/alpha variants.
   const colorCount = design.colors.all.length;
-  if (colorCount <= 8) scores.colorDiscipline = 100;
-  else if (colorCount <= 15) scores.colorDiscipline = 85;
-  else if (colorCount <= 25) scores.colorDiscipline = 70;
-  else if (colorCount <= 40) scores.colorDiscipline = 50;
-  else { scores.colorDiscipline = 30; issues.push(`${colorCount} unique colors detected — consider consolidating to a tighter palette`); }
+  if (colorCount <= 12) scores.colorDiscipline = 100;
+  else if (colorCount <= 25) scores.colorDiscipline = 92;
+  else if (colorCount <= 40) scores.colorDiscipline = 80;
+  else if (colorCount <= 60) scores.colorDiscipline = 65;
+  else if (colorCount <= 100) scores.colorDiscipline = 50;
+  else { scores.colorDiscipline = 35; issues.push(`${colorCount} unique colors detected — consider consolidating to a tighter palette`); }
 
   if (!design.colors.primary) {
     scores.colorDiscipline -= 15;
@@ -26,46 +28,62 @@ export function scoreDesignSystem(design) {
 
   const weightCount = design.typography.weights.length;
   if (weightCount <= 3) scores.typographyConsistency = Math.min(scores.typographyConsistency, 100);
-  else if (weightCount <= 5) scores.typographyConsistency = Math.min(scores.typographyConsistency, 80);
+  else if (weightCount <= 5) scores.typographyConsistency = Math.min(scores.typographyConsistency, 90);
+  else if (weightCount <= 7) scores.typographyConsistency = Math.min(scores.typographyConsistency, 80);
   else { scores.typographyConsistency -= 15; issues.push(`${weightCount} font weights in use — consider standardizing to 3 (regular, medium, bold)`); }
 
+  // Type-scale count — variable-font sites and component-rich pages commonly
+  // ship 12–18 sizes (nav, body, caption, h1–h6, stat, pill, etc).
   const scaleSize = design.typography.scale.length;
-  if (scaleSize <= 6) scores.typographyConsistency = Math.min(scores.typographyConsistency, 100);
-  else if (scaleSize <= 10) scores.typographyConsistency = Math.min(scores.typographyConsistency, 85);
+  if (scaleSize <= 8) scores.typographyConsistency = Math.min(scores.typographyConsistency, 100);
+  else if (scaleSize <= 14) scores.typographyConsistency = Math.min(scores.typographyConsistency, 92);
+  else if (scaleSize <= 20) scores.typographyConsistency = Math.min(scores.typographyConsistency, 82);
   else { scores.typographyConsistency -= 10; issues.push(`${scaleSize} distinct font sizes — consider a tighter type scale`); }
 
-  // 3. Spacing system (0-100)
+  // 3. Spacing system (0-100) — detectScale() only tries 2/4/6/8 as bases and
+  // fails on sites whose computed-style spacing has line-height/SVG noise mixed
+  // in. Don't penalise too hard when a base isn't pinned but tokenization is
+  // healthy — the design still has a system, we just can't name it.
   if (design.spacing.base) {
     scores.spacingSystem = 90;
-    // Check how many values fit the base
     const fittingValues = design.spacing.scale.filter(v => v % design.spacing.base === 0).length;
     const fitRatio = fittingValues / design.spacing.scale.length;
     if (fitRatio >= 0.8) scores.spacingSystem = 100;
-    else if (fitRatio >= 0.6) scores.spacingSystem = 80;
-    else scores.spacingSystem = 65;
+    else if (fitRatio >= 0.6) scores.spacingSystem = 85;
+    else scores.spacingSystem = 75;
   } else {
-    scores.spacingSystem = 40;
-    issues.push('No consistent spacing base unit detected — values appear arbitrary');
+    // Fallback: soft penalty if the site still ships design tokens (CSS vars).
+    const varCount = Object.values(design.variables || {}).reduce((s, v) => s + Object.keys(v || {}).length, 0);
+    scores.spacingSystem = varCount >= 20 ? 70 : 55;
+    if (varCount < 20) issues.push('No consistent spacing base unit detected — values appear arbitrary');
   }
 
-  if (design.spacing.scale.length > 20) {
+  // Spacing value count — real sites commonly ship 25–40 distinct spacings
+  // (component padding, gap, stacked layout rhythm). Only penalise above 35.
+  if (design.spacing.scale.length > 50) {
     scores.spacingSystem -= 15;
     issues.push(`${design.spacing.scale.length} unique spacing values — too many one-off values`);
+  } else if (design.spacing.scale.length > 35) {
+    scores.spacingSystem -= 5;
   }
 
-  // 4. Shadow consistency (0-100)
+  // 4. Shadow consistency (0-100) — calibrated; real sites routinely ship
+  // 10–20 shadows once hover/focus/elevation variants are counted.
   const shadowCount = design.shadows.values.length;
-  if (shadowCount === 0) scores.shadowConsistency = 80; // no shadows is fine
-  else if (shadowCount <= 4) scores.shadowConsistency = 100;
-  else if (shadowCount <= 8) scores.shadowConsistency = 75;
+  if (shadowCount === 0) scores.shadowConsistency = 85;
+  else if (shadowCount <= 5) scores.shadowConsistency = 100;
+  else if (shadowCount <= 10) scores.shadowConsistency = 90;
+  else if (shadowCount <= 18) scores.shadowConsistency = 78;
+  else if (shadowCount <= 28) scores.shadowConsistency = 62;
   else { scores.shadowConsistency = 50; issues.push(`${shadowCount} unique shadows — consider a 3-level elevation scale (sm/md/lg)`); }
 
   // 5. Border radius consistency (0-100)
   const radiiCount = design.borders.radii.length;
-  if (radiiCount <= 3) scores.radiusConsistency = 100;
-  else if (radiiCount <= 5) scores.radiusConsistency = 85;
-  else if (radiiCount <= 8) scores.radiusConsistency = 65;
-  else { scores.radiusConsistency = 40; issues.push(`${radiiCount} unique border radii — standardize to 3-4 values`); }
+  if (radiiCount <= 4) scores.radiusConsistency = 100;
+  else if (radiiCount <= 7) scores.radiusConsistency = 90;
+  else if (radiiCount <= 10) scores.radiusConsistency = 80;
+  else if (radiiCount <= 15) scores.radiusConsistency = 65;
+  else { scores.radiusConsistency = 45; issues.push(`${radiiCount} unique border radii — standardize to 3-4 values`); }
 
   // 6. Accessibility (from existing extractor)
   scores.accessibility = design.accessibility?.score || 0;
@@ -101,13 +119,14 @@ export function scoreDesignSystem(design) {
 
   // Overall score (weighted average)
   const weights = {
-    colorDiscipline: 20,
-    typographyConsistency: 20,
-    spacingSystem: 20,
-    shadowConsistency: 10,
-    radiusConsistency: 10,
+    colorDiscipline: 18,
+    typographyConsistency: 18,
+    spacingSystem: 18,
+    shadowConsistency: 9,
+    radiusConsistency: 9,
     accessibility: 15,
     tokenization: 5,
+    cssHealth: 8,
   };
 
   let totalWeight = 0;

package/src/extractors/voice.js

@@ -0,0 +1,96 @@
+// Brand voice extraction — microcopy patterns from CTA verbs, headings, and section copy.
+// Feeds LLMs the *tone*, not just the paint.
+
+const IMPERATIVE_VERBS = new Set([
+  'get', 'start', 'try', 'build', 'create', 'ship', 'deploy', 'launch', 'learn', 'read',
+  'buy', 'shop', 'explore', 'discover', 'join', 'sign', 'subscribe', 'book', 'download',
+  'install', 'contact', 'talk', 'request', 'view', 'see', 'watch', 'read', 'meet',
+]);
+
+const FRIENDLY_MARKERS = /\b(we|our|us|you|your|let's|hey|welcome|thanks|love|yay|awesome)\b/i;
+const FORMAL_MARKERS = /\b(enterprise|platform|solution|infrastructure|comprehensive|leverage|empower|facilitate|utilize)\b/i;
+const TECHNICAL_MARKERS = /\b(api|sdk|webhook|latency|throughput|cli|runtime|schema|endpoint|token|typescript|kubernetes)\b/i;
+const PLAYFUL_MARKERS = /[!?]{1,2}$|\b(magic|wow|boom|zap|rocket|sparkle|fire)\b|[✨🚀🔥⚡💫]/i;
+
+function words(str) {
+  return (str || '').toLowerCase().match(/[a-z']+/g) || [];
+}
+
+function firstVerb(text) {
+  const w = words(text);
+  for (const word of w) {
+    if (IMPERATIVE_VERBS.has(word)) return word;
+  }
+  return w[0] || '';
+}
+
+function scoreTone(texts) {
+  const joined = texts.join(' ');
+  return {
+    friendly: (joined.match(FRIENDLY_MARKERS) || []).length,
+    formal: (joined.match(FORMAL_MARKERS) || []).length,
+    technical: (joined.match(TECHNICAL_MARKERS) || []).length,
+    playful: (joined.match(PLAYFUL_MARKERS) || []).length,
+  };
+}
+
+function pickTone(scores) {
+  const entries = Object.entries(scores);
+  const total = entries.reduce((s, [, n]) => s + n, 0);
+  if (total === 0) return 'neutral';
+  const [top] = entries.sort((a, b) => b[1] - a[1]);
+  return top[1] / total > 0.4 ? top[0] : 'neutral';
+}
+
+function topN(arr, n = 10) {
+  const counts = {};
+  for (const v of arr) if (v) counts[v] = (counts[v] || 0) + 1;
+  return Object.entries(counts).sort((a, b) => b[1] - a[1]).slice(0, n).map(([value, count]) => ({ value, count }));
+}
+
+function avgLen(arr) {
+  if (!arr.length) return 0;
+  return Math.round(arr.reduce((s, v) => s + v.length, 0) / arr.length);
+}
+
+export function extractVoice({ componentCandidates = [], sections = [] } = {}) {
+  const buttons = componentCandidates.filter(c => c.kind === 'button' || c.kind === 'link').map(c => c.text).filter(Boolean);
+  const headings = sections.flatMap(s => s.headings || []).filter(Boolean);
+  const sectionTexts = sections.map(s => s.text || '').filter(Boolean);
+
+  const ctaVerbs = buttons.map(firstVerb).filter(Boolean);
+  const buttonPatterns = topN(buttons.map(b => b.toLowerCase().trim()), 15);
+  const ctaTopVerbs = topN(ctaVerbs, 10);
+
+  const tone = pickTone(scoreTone([...buttons, ...headings, ...sectionTexts]));
+  const personPronoun = /\byou\b/i.test(headings.join(' ') + sectionTexts.join(' '))
+    ? (/\bwe\b/i.test(headings.join(' ')) ? 'we→you' : 'you-only')
+    : (/\bwe\b/i.test(headings.join(' ')) ? 'we-only' : 'third-person');
+
+  const headingStyle = (() => {
+    if (!headings.length) return 'unknown';
+    const titleCase = headings.filter(h => /^[A-Z]/.test(h) && /\s[A-Z]/.test(h)).length;
+    const sentenceCase = headings.filter(h => /^[A-Z]/.test(h) && !/\s[A-Z]/.test(h)).length;
+    const allLower = headings.filter(h => h === h.toLowerCase()).length;
+    if (allLower > headings.length / 2) return 'all-lowercase';
+    if (titleCase > sentenceCase) return 'Title Case';
+    return 'Sentence case';
+  })();
+
+  const avgHeadingWords = avgLen(headings.map(h => words(h))) / Math.max(avgLen(headings) || 1, 1) * (avgLen(headings) || 1);
+  const headingLengthClass = avgHeadingWords <= 4 ? 'tight' : avgHeadingWords <= 8 ? 'balanced' : 'verbose';
+
+  return {
+    tone,
+    pronoun: personPronoun,
+    headingStyle,
+    headingLengthClass,
+    ctaVerbs: ctaTopVerbs,
+    buttonPatterns,
+    sampleHeadings: headings.slice(0, 10),
+    stats: {
+      buttons: buttons.length,
+      headings: headings.length,
+    },
+  };
+}

package/src/formatters/markdown.js

@@ -623,6 +623,94 @@ export function formatMarkdown(design) {
     }
   }
 
+  // ── Motion Language (v9) ──
+  if (design.motion && (design.motion.durations?.length || design.motion.keyframes?.length)) {
+    lines.push('## Motion Language');
+    lines.push('');
+    lines.push(`**Feel:** ${design.motion.feel} · **Scroll-linked:** ${design.motion.scrollLinked?.present ? 'yes' : 'no'}`);
+    lines.push('');
+    if (design.motion.durations?.length) {
+      lines.push('### Duration Tokens');
+      lines.push('');
+      lines.push('| name | value | ms |');
+      lines.push('|---|---|---|');
+      for (const d of design.motion.durations) lines.push(`| \`${d.name}\` | \`${d.css}\` | ${d.ms} |`);
+      lines.push('');
+    }
+    if (design.motion.easings?.length) {
+      lines.push('### Easing Families');
+      lines.push('');
+      const byFamily = {};
+      for (const e of design.motion.easings) (byFamily[e.family] ||= []).push(e);
+      for (const [family, list] of Object.entries(byFamily)) {
+        lines.push(`- **${family}** (${list.reduce((s, e) => s + (e.count || 0), 0)} uses) — \`${list.map(e => e.raw).slice(0, 3).join('`, `')}\``);
+      }
+      lines.push('');
+    }
+    if (design.motion.springs?.length) {
+      lines.push('### Spring / Overshoot Easings');
+      lines.push('');
+      for (const s of design.motion.springs) lines.push(`- \`${s.raw}\``);
+      lines.push('');
+    }
+    const usedKf = (design.motion.keyframes || []).filter(k => k.used);
+    if (usedKf.length) {
+      lines.push('### Keyframes In Use');
+      lines.push('');
+      lines.push('| name | kind | properties | uses |');
+      lines.push('|---|---|---|---|');
+      for (const k of usedKf.slice(0, 20)) lines.push(`| \`${k.name}\` | ${k.kind} | ${k.propertiesAnimated.slice(0, 4).join(', ')} | ${k.usageCount} |`);
+      lines.push('');
+    }
+  }
+
+  // ── Component Anatomy (v9) ──
+  if ((design.componentAnatomy || []).length) {
+    lines.push('## Component Anatomy');
+    lines.push('');
+    for (const a of design.componentAnatomy.slice(0, 6)) {
+      lines.push(`### ${a.kind} — ${a.totalInstances} instance${a.totalInstances === 1 ? '' : 's'}`);
+      lines.push('');
+      const slots = Object.entries(a.slots).filter(([, v]) => v).map(([k]) => k);
+      if (slots.length) lines.push(`**Slots:** ${slots.join(', ')}`);
+      if (a.props.variant.length) lines.push(`**Variants:** ${a.props.variant.join(' · ')}`);
+      if (a.props.size.length) lines.push(`**Sizes:** ${a.props.size.join(' · ')}`);
+      lines.push('');
+      if (a.variants.length > 1) {
+        lines.push('| variant | count | sample label |');
+        lines.push('|---|---|---|');
+        for (const v of a.variants.slice(0, 8)) lines.push(`| ${v.name} | ${v.count} | ${(v.sampleText[0] || '').slice(0, 40)} |`);
+        lines.push('');
+      }
+    }
+  }
+
+  // ── Brand Voice (v9) ──
+  if (design.voice && (design.voice.ctaVerbs?.length || design.voice.sampleHeadings?.length)) {
+    lines.push('## Brand Voice');
+    lines.push('');
+    lines.push(`**Tone:** ${design.voice.tone} · **Pronoun:** ${design.voice.pronoun} · **Headings:** ${design.voice.headingStyle} (${design.voice.headingLengthClass})`);
+    lines.push('');
+    if (design.voice.ctaVerbs?.length) {
+      lines.push('### Top CTA Verbs');
+      lines.push('');
+      for (const v of design.voice.ctaVerbs.slice(0, 8)) lines.push(`- **${v.value}** (${v.count})`);
+      lines.push('');
+    }
+    if (design.voice.buttonPatterns?.length) {
+      lines.push('### Button Copy Patterns');
+      lines.push('');
+      for (const p of design.voice.buttonPatterns.slice(0, 10)) lines.push(`- "${p.value}" (${p.count}×)`);
+      lines.push('');
+    }
+    if (design.voice.sampleHeadings?.length) {
+      lines.push('### Sample Headings');
+      lines.push('');
+      for (const h of design.voice.sampleHeadings) lines.push(`> ${h}`);
+      lines.push('');
+    }
+  }
+
   // ── Quick Start ──
   lines.push('## Quick Start');
   lines.push('');

package/src/formatters/motion-tokens.js

@@ -0,0 +1,22 @@
+// Emits a DTCG-flavored motion tokens JSON.
+export function formatMotionTokens(motion) {
+  if (!motion) return '{}';
+  const out = {
+    $description: 'Motion tokens extracted by designlang',
+    duration: {},
+    easing: {},
+    spring: {},
+  };
+  for (const d of motion.durations || []) {
+    out.duration[d.name] = { $value: d.css, $type: 'duration', ms: d.ms };
+  }
+  for (const e of motion.easings || []) {
+    const slug = e.family + (e.raw.includes('cubic-bezier') ? `-${Math.abs(e.raw.split('').reduce((a, c) => a + c.charCodeAt(0), 0)) % 1000}` : '');
+    out.easing[slug] = { $value: e.raw, $type: 'cubicBezier', family: e.family };
+  }
+  (motion.springs || []).forEach((s, i) => {
+    out.spring[`spring-${i + 1}`] = { $value: s.raw, $type: 'cubicBezier', overshoot: true };
+  });
+  out.$meta = { feel: motion.feel, scrollLinked: !!motion.scrollLinked?.present };
+  return JSON.stringify(out, null, 2);
+}

package/src/index.js

@@ -25,7 +25,11 @@ import { extractModernCss } from './extractors/modern-css.js';
 import { extractWideGamut } from './extractors/wide-gamut.js';
 import { extractTokenSources } from './extractors/token-sources.js';
 import { extractInteractionStates } from './extractors/interaction-states.js';
+import { extractMotion } from './extractors/motion.js';
+import { extractComponentAnatomy, formatAnatomyStubs } from './extractors/component-anatomy.js';
+import { extractVoice } from './extractors/voice.js';
 import { formatDtcgTokens } from './formatters/dtcg-tokens.js';
+import { formatMotionTokens } from './formatters/motion-tokens.js';
 
 function safeExtract(fn, ...args) {
   try { return fn(...args); } catch { return null; }
@@ -73,6 +77,9 @@ export async function extractDesignLanguage(url, options = {}) {
     wideGamut: safeExtract(extractWideGamut, rawData.light.modernColors || []) || { oklch: { count: 0, samples: [] }, oklab: { count: 0, samples: [] }, colorMix: { count: 0, samples: [] }, lightDark: { count: 0, samples: [] }, displayP3: { count: 0, samples: [] }, rec2020: { count: 0, samples: [] }, totalCount: 0 },
     tokenSources: [],
     interactionStates: safeExtract(extractInteractionStates, rawData.interactState || rawData.light.interactState) || { scrollSettled: false, menusOpened: 0, hover: { sampled: 0, changed: 0, deltas: [] }, accordionsOpened: 0, modals: [] },
+    motion: safeExtract(extractMotion, styles, rawData.light.keyframes) || { durations: [], easings: [], springs: [], keyframes: [], scrollLinked: { present: false, signals: [] }, stats: {}, feel: 'unknown' },
+    componentAnatomy: safeExtract(extractComponentAnatomy, rawData.light.componentCandidates) || [],
+    voice: safeExtract(extractVoice, { componentCandidates: rawData.light.componentCandidates, sections: rawData.light.sections }) || { tone: 'neutral', ctaVerbs: [], buttonPatterns: [], sampleHeadings: [] },
     score: null,
   };
 
@@ -165,3 +172,10 @@ export { watchSite } from './watch.js';
 export { diffDarkMode } from './darkdiff.js';
 export { applyDesign } from './apply.js';
 export { loadConfig, mergeConfig } from './config.js';
+export { extractMotion } from './extractors/motion.js';
+export { formatMotionTokens } from './formatters/motion-tokens.js';
+export { extractComponentAnatomy, formatAnatomyStubs } from './extractors/component-anatomy.js';
+export { extractVoice } from './extractors/voice.js';
+export { lintTokens } from './lint.js';
+export { checkDrift, formatDriftMarkdown } from './drift.js';
+export { visualDiff, formatVisualDiffHtml } from './visual-diff.js';

package/src/lint.js

@@ -0,0 +1,198 @@
+// designlang lint — audit a local token file for the same issues scoring flags on live sites.
+// Supports DTCG, flat design-tokens.json, Tailwind config (partial), and CSS variable files.
+
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+
+function hexToRgb(hex) {
+  const m = hex.replace('#', '').match(/^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i);
+  if (!m) return null;
+  return { r: parseInt(m[1], 16), g: parseInt(m[2], 16), b: parseInt(m[3], 16) };
+}
+
+function relLum({ r, g, b }) {
+  const f = v => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 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(a), lb = relLum(b);
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+function flattenDtcg(obj, prefix = '', out = []) {
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (k.startsWith('$')) continue;
+    if (v && typeof v === 'object') {
+      if ('$value' in v) {
+        out.push({ name: prefix ? `${prefix}.${k}` : k, value: v.$value, type: v.$type });
+      } else {
+        flattenDtcg(v, prefix ? `${prefix}.${k}` : k, out);
+      }
+    }
+  }
+  return out;
+}
+
+function loadTokens(file) {
+  const raw = readFileSync(file, 'utf8');
+  const ext = extname(file);
+  if (ext === '.json') {
+    const json = JSON.parse(raw);
+    const flat = flattenDtcg(json);
+    if (flat.length) return flat;
+    // flat fallback: { colors: { primary: '#000' }, ... }
+    const out = [];
+    for (const [group, entries] of Object.entries(json)) {
+      if (!entries || typeof entries !== 'object') continue;
+      for (const [k, v] of Object.entries(entries)) {
+        out.push({ name: `${group}.${k}`, value: String(v), type: group.replace(/s$/, '') });
+      }
+    }
+    return out;
+  }
+  if (ext === '.css') {
+    const out = [];
+    for (const m of raw.matchAll(/--([\w-]+):\s*([^;]+);/g)) {
+      out.push({ name: m[1], value: m[2].trim(), type: 'unknown' });
+    }
+    return out;
+  }
+  throw new Error(`Unsupported file type: ${ext}. Use .json or .css.`);
+}
+
+function isColor(t) { return t.type === 'color' || /^#[\da-f]{3,8}$/i.test(t.value) || /^rgb/i.test(t.value); }
+function toHex(v) {
+  const m = v.match(/^#([a-f\d]{3,8})$/i);
+  if (m) {
+    const h = m[1];
+    if (h.length === 3) return '#' + h.split('').map(c => c + c).join('');
+    return '#' + h.slice(0, 6);
+  }
+  const rgb = v.match(/rgba?\(\s*(\d+)\s*,?\s*(\d+)\s*,?\s*(\d+)/i);
+  if (rgb) return '#' + [rgb[1], rgb[2], rgb[3]].map(n => (+n).toString(16).padStart(2, '0')).join('');
+  return null;
+}
+
+function dedupeClose(hexes, threshold = 8) {
+  const near = [];
+  for (let i = 0; i < hexes.length; i++) {
+    for (let j = i + 1; j < hexes.length; j++) {
+      const a = hexToRgb(hexes[i].value), b = hexToRgb(hexes[j].value);
+      if (!a || !b) continue;
+      const dist = Math.sqrt((a.r - b.r) ** 2 + (a.g - b.g) ** 2 + (a.b - b.b) ** 2);
+      if (dist > 0 && dist < threshold) near.push({ a: hexes[i].name, b: hexes[j].name, distance: Math.round(dist) });
+    }
+  }
+  return near;
+}
+
+function parsePx(v) {
+  const m = String(v).match(/^(-?\d*\.?\d+)px$/);
+  return m ? parseFloat(m[1]) : null;
+}
+
+function checkScale(values, label) {
+  const nums = values.map(parsePx).filter(n => n !== null && n >= 0).sort((a, b) => a - b);
+  if (nums.length < 3) return null;
+  const gaps = [];
+  for (let i = 1; i < nums.length; i++) gaps.push(nums[i] - nums[i - 1]);
+  // Heuristic: ratio wildly inconsistent?
+  const ratios = [];
+  for (let i = 1; i < nums.length; i++) if (nums[i - 1] > 0) ratios.push(nums[i] / nums[i - 1]);
+  const avg = ratios.reduce((s, r) => s + r, 0) / (ratios.length || 1);
+  const variance = ratios.reduce((s, r) => s + (r - avg) ** 2, 0) / (ratios.length || 1);
+  return { label, count: nums.length, values: nums, avgRatio: +avg.toFixed(2), variance: +variance.toFixed(3) };
+}
+
+export function lintTokens(file) {
+  const tokens = loadTokens(file);
+  const findings = [];
+  const scorecard = {};
+
+  const colors = tokens.filter(isColor).map(t => ({ name: t.name, value: toHex(t.value) || t.value })).filter(t => /^#[\da-f]{6}$/i.test(t.value));
+  const neighbors = dedupeClose(colors);
+  if (neighbors.length) {
+    findings.push({
+      severity: 'warn',
+      rule: 'color-sprawl',
+      message: `${neighbors.length} near-duplicate color pair(s) within 8 RGB units`,
+      detail: neighbors.slice(0, 5),
+    });
+  }
+  scorecard.colorDiscipline = Math.max(0, 100 - neighbors.length * 8);
+
+  const spacing = tokens.filter(t => /spacing|space|gap|size/i.test(t.name));
+  const spaceCheck = checkScale(spacing.map(t => t.value), 'spacing');
+  if (spaceCheck && spaceCheck.variance > 0.25) {
+    findings.push({
+      severity: 'warn',
+      rule: 'spacing-scale-inconsistent',
+      message: `Spacing scale ratios vary (variance ${spaceCheck.variance}). Consider a consistent ratio (1.5x, 2x).`,
+      detail: spaceCheck,
+    });
+  }
+  scorecard.spacingSystem = spaceCheck ? Math.max(30, 100 - Math.round(spaceCheck.variance * 200)) : 50;
+
+  const radii = tokens.filter(t => /radius|radii/i.test(t.name));
+  if (radii.length > 8) {
+    findings.push({
+      severity: 'warn',
+      rule: 'radius-sprawl',
+      message: `${radii.length} radius tokens — consider collapsing to 4-6.`,
+    });
+  }
+  scorecard.borderRadii = Math.max(30, 100 - Math.max(0, radii.length - 6) * 10);
+
+  const shadows = tokens.filter(t => /shadow|elevation/i.test(t.name));
+  if (shadows.length > 10) {
+    findings.push({
+      severity: 'info',
+      rule: 'shadow-sprawl',
+      message: `${shadows.length} shadow tokens — rarely need more than 6 elevation levels.`,
+    });
+  }
+  scorecard.shadows = Math.max(30, 100 - Math.max(0, shadows.length - 6) * 8);
+
+  // Contrast: try to find text/bg pairs by name.
+  const palette = colors;
+  const bgs = palette.filter(c => /bg|background|surface/i.test(c.name));
+  const fgs = palette.filter(c => /fg|text|foreground|ink|label/i.test(c.name));
+  const contrastFails = [];
+  for (const fg of fgs) {
+    for (const bg of bgs) {
+      const fgRgb = hexToRgb(fg.value), bgRgb = hexToRgb(bg.value);
+      if (!fgRgb || !bgRgb) continue;
+      const c = contrast(fgRgb, bgRgb);
+      if (c < 4.5) contrastFails.push({ fg: fg.name, bg: bg.name, ratio: +c.toFixed(2) });
+    }
+  }
+  if (contrastFails.length) {
+    findings.push({
+      severity: 'error',
+      rule: 'contrast-wcag-aa',
+      message: `${contrastFails.length} fg/bg pair(s) fail WCAG AA (4.5:1)`,
+      detail: contrastFails.slice(0, 10),
+    });
+  }
+  scorecard.accessibility = contrastFails.length ? Math.max(20, 100 - contrastFails.length * 12) : 100;
+
+  const avg = Math.round(Object.values(scorecard).reduce((s, v) => s + v, 0) / Object.keys(scorecard).length);
+  const grade = avg >= 90 ? 'A' : avg >= 80 ? 'B' : avg >= 70 ? 'C' : avg >= 60 ? 'D' : 'F';
+
+  return {
+    file,
+    tokenCount: tokens.length,
+    score: avg,
+    grade,
+    scorecard,
+    findings,
+    stats: {
+      colors: colors.length,
+      spacing: spacing.length,
+      radii: radii.length,
+      shadows: shadows.length,
+    },
+  };
+}