designlang 8.0.0 → 9.0.0

package/src/extractors/motion.js

@@ -0,0 +1,184 @@
+// Motion v2 — rich motion language extraction.
+// Classifies easings into semantic families, detects springs/bounces,
+// catches scroll/view-timeline usage, and emits motion tokens (duration, easing, spring).
+
+const MS = v => {
+  if (!v) return 0;
+  const m = String(v).match(/(-?\d+\.?\d*)(m?s)?/);
+  if (!m) return 0;
+  const n = parseFloat(m[1]);
+  return m[2] === 's' ? n * 1000 : n;
+};
+
+const DURATION_NAMES = [
+  { max: 80, name: 'instant' },
+  { max: 150, name: 'xs' },
+  { max: 250, name: 'sm' },
+  { max: 400, name: 'md' },
+  { max: 700, name: 'lg' },
+  { max: 1200, name: 'xl' },
+  { max: Infinity, name: 'xxl' },
+];
+
+function nameDuration(ms) {
+  return DURATION_NAMES.find(d => ms <= d.max).name;
+}
+
+function classifyCubicBezier(raw) {
+  const m = raw.match(/cubic-bezier\(\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\)/);
+  if (!m) return { family: 'custom', raw };
+  const [x1, y1, x2, y2] = m.slice(1).map(Number);
+  if (y1 < 0 || y2 > 1 || y2 < 0 || y1 > 1) return { family: 'spring', raw, overshoot: true };
+  if (x1 < 0.2 && x2 > 0.8) return { family: 'ease-in-out', raw };
+  if (x1 < 0.2 && y1 < 0.2) return { family: 'ease-out', raw };
+  if (x2 > 0.8 && y2 > 0.8) return { family: 'ease-in', raw };
+  if (y1 < x1 && y2 < x2) return { family: 'ease-in', raw };
+  if (y1 > x1 && y2 > x2) return { family: 'ease-out', raw };
+  return { family: 'custom', raw };
+}
+
+function classifyEasing(raw) {
+  if (!raw) return { family: 'linear', raw };
+  if (raw === 'linear') return { family: 'linear', raw };
+  if (raw === 'ease' || raw === 'ease-in-out') return { family: 'ease-in-out', raw };
+  if (raw === 'ease-in') return { family: 'ease-in', raw };
+  if (raw === 'ease-out') return { family: 'ease-out', raw };
+  if (/cubic-bezier/.test(raw)) return classifyCubicBezier(raw);
+  if (/steps/.test(raw)) return { family: 'steps', raw };
+  return { family: 'custom', raw };
+}
+
+function isBounceKeyframe(kf) {
+  if (!kf.steps || kf.steps.length < 3) return false;
+  const first = kf.steps.find(s => s.offset === '0%' || s.offset === 'from');
+  const last = kf.steps.find(s => s.offset === '100%' || s.offset === 'to');
+  if (!first || !last) return false;
+  return first.style.replace(/\s+/g, '') === last.style.replace(/\s+/g, '');
+}
+
+function keyframeKind(kf) {
+  const props = new Set();
+  const values = [];
+  for (const step of kf.steps || []) {
+    for (const part of (step.style || '').split(';')) {
+      const [p, v] = part.split(':').map(s => (s || '').trim());
+      if (p) props.add(p);
+      if (v) values.push(v);
+    }
+  }
+  const has = p => props.has(p);
+  const anyValue = re => values.some(v => re.test(v));
+  if (has('transform') && anyValue(/translate/i)) {
+    if (anyValue(/translateY\(-?\d/)) return 'slide-y';
+    if (anyValue(/translateX\(-?\d/)) return 'slide-x';
+    return 'slide';
+  }
+  if (has('opacity') && !has('transform')) return 'fade';
+  if (has('opacity') && has('transform')) return 'reveal';
+  if (anyValue(/rotate/)) return 'rotate';
+  if (anyValue(/scale/)) return 'scale';
+  if (isBounceKeyframe(kf)) return 'pulse';
+  return 'custom';
+}
+
+export function extractMotion(computedStyles, keyframes = []) {
+  const transitions = new Set();
+  const easingRaw = new Set();
+  const durations = [];
+  const animationRefs = new Map();
+  const transitionedProps = {};
+  const scrollSignals = new Set();
+  let animatingElements = 0;
+
+  for (const el of computedStyles) {
+    let isAnimating = false;
+    if (el.transition && el.transition !== 'all 0s ease 0s' && el.transition !== 'none') {
+      transitions.add(el.transition);
+      isAnimating = true;
+      for (const m of el.transition.matchAll(/(?<![(\d])(\d+\.?\d*m?s)(?![)\w])/g)) durations.push(MS(m[1]));
+      for (const m of el.transition.matchAll(/(ease|ease-in|ease-out|ease-in-out|linear|cubic-bezier\([^)]+\)|steps\([^)]+\))/g)) easingRaw.add(m[1]);
+      for (const part of el.transition.split(',')) {
+        const prop = part.trim().split(/\s+/)[0];
+        if (prop && prop !== 'all') transitionedProps[prop] = (transitionedProps[prop] || 0) + 1;
+      }
+    }
+    if (el.animation && el.animation !== 'none 0s ease 0s 1 normal none running' && el.animation !== 'none') {
+      const nameMatch = el.animation.match(/([a-zA-Z_][\w-]*)\s*$/) || el.animation.match(/^([a-zA-Z_][\w-]*)/);
+      if (nameMatch) {
+        const name = nameMatch[1];
+        if (name !== 'none' && name !== 'running' && name !== 'paused') {
+          animationRefs.set(name, (animationRefs.get(name) || 0) + 1);
+        }
+      }
+      isAnimating = true;
+    }
+    if (el.animationTimeline && el.animationTimeline !== 'auto' && el.animationTimeline !== 'none' && el.animationTimeline !== '') {
+      scrollSignals.add(el.animationTimeline);
+    }
+    if (el.viewTimelineName) scrollSignals.add(`view:${el.viewTimelineName}`);
+    if (el.scrollTimelineName) scrollSignals.add(`scroll:${el.scrollTimelineName}`);
+    if (isAnimating) animatingElements++;
+  }
+
+  const uniqueDurations = [...new Set(durations.filter(d => d > 0))].sort((a, b) => a - b);
+  const durationTokens = uniqueDurations.map(ms => ({
+    name: nameDuration(ms),
+    ms,
+    css: ms >= 1000 ? `${ms / 1000}s` : `${ms}ms`,
+  }));
+  // dedupe by name — keep first (smallest) per bucket
+  const seenName = new Set();
+  const namedDurations = [];
+  for (const t of durationTokens) {
+    if (seenName.has(t.name)) continue;
+    seenName.add(t.name);
+    namedDurations.push(t);
+  }
+
+  const easings = [...easingRaw].map(e => ({ ...classifyEasing(e), count: computedStyles.filter(c => (c.transition || '').includes(e)).length }));
+  const springs = easings.filter(e => e.family === 'spring');
+
+  const enrichedKeyframes = (keyframes || []).map(kf => ({
+    name: kf.name,
+    steps: kf.steps,
+    kind: keyframeKind(kf),
+    isBounce: isBounceKeyframe(kf),
+    used: animationRefs.has(kf.name),
+    usageCount: animationRefs.get(kf.name) || 0,
+    propertiesAnimated: [...new Set((kf.steps || []).flatMap(s => (s.style || '').split(';').map(d => d.split(':')[0].trim()).filter(Boolean)))],
+  }));
+
+  const transitionTop = Object.entries(transitionedProps).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([property, count]) => ({ property, count }));
+
+  // Motion language fingerprint — what does this site's motion *feel* like?
+  const totalUses = easings.reduce((s, e) => s + e.count, 0);
+  const share = family => easings.filter(e => e.family === family).reduce((s, e) => s + e.count, 0) / (totalUses || 1);
+  const feel = springs.length > 0
+    ? 'springy'
+    : share('ease-out') > 0.5
+      ? 'responsive'
+      : share('ease-in-out') > 0.5
+        ? 'smooth'
+        : share('linear') > 0.5
+          ? 'mechanical'
+          : 'mixed';
+
+  return {
+    durations: namedDurations,
+    easings,
+    springs,
+    keyframes: enrichedKeyframes,
+    transitionedProperties: transitionTop,
+    scrollLinked: {
+      present: scrollSignals.size > 0,
+      signals: [...scrollSignals],
+    },
+    stats: {
+      animatingElements,
+      transitionCount: transitions.size,
+      keyframeCount: enrichedKeyframes.length,
+      keyframeUnused: enrichedKeyframes.filter(k => !k.used).length,
+    },
+    feel,
+  };
+}

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,
+    },
+  };
+}