@starklab/stark-mcp 0.1.0

package/src/adopt/tailwindResolver.js

@@ -0,0 +1,512 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+import postcss from 'postcss';
+import traverseModule from '@babel/traverse';
+
+import { stkRoot } from '../data.js';
+import { parseSource } from './parseSource.js';
+import { buildModuleGraph } from './moduleGraph.js';
+import {
+  extractVarRefs,
+  resolveTerminal,
+  loadTokenInventory,
+  collectCssFiles,
+  buildPropertyGraph,
+  classifyTerminalState,
+} from './tokenAliasResolver.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+// "5 is governance, 20 is safety" — see ADOPTION_APP_PLAN.md §4/§5a. Kept as
+// its own local constant rather than importing tokenAliasResolver's (not
+// exported) — resolveTerminal already enforces MAX_DEPTH internally; this
+// file only needs the warn threshold for its own findings.
+const WARN_DEPTH = 3;
+
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.next/**',
+  '**/coverage/**',
+  '**/storybook-static/**',
+  '**/.storybook*/**',
+];
+
+// ---------------------------------------------------------------------------
+// Namespace → utility-class-prefix table
+//
+// Deliberately a bounded subset, not a full Tailwind theme-key clone: color,
+// spacing (named keys), radius, shadow, font-family. This covers the
+// dominant real-world case — a consumer re-namespacing Stark's color scale
+// under Tailwind (ADOPTION_APP_PLAN.md §5a's own worked example) — plus the
+// next most common indirections. Deliberately NOT covered: font-size
+// (--text-*), because its utility prefix ("text-") collides with the color
+// namespace's own "text-" prefix (Tailwind itself disambiguates by checking
+// which scale actually has the key; replicating that is disproportionate for
+// a dimension this repo's own token rules already steer away from — text
+// styles own typography, not tokens, per CLAUDE.md), tracking/leading,
+// breakpoints/containers, ease/animate, blur/perspective/aspect. A bare
+// utility keyword with no key suffix (`rounded`, `shadow`, `border` alone)
+// is also out of scope — it almost always resolves to Tailwind's own
+// hardcoded default, not a named theme key.
+//
+// Prefixes are matched longest-first so e.g. "ring-offset" wins over "ring",
+// "gap-x" over "gap", "min-w" over "w".
+// ---------------------------------------------------------------------------
+
+const NAMESPACES = {
+  color: {
+    cssPrefix: 'color',
+    classPrefixes: [
+      'ring-offset', 'ring', 'bg', 'text', 'border', 'outline', 'decoration',
+      'accent', 'caret', 'divide', 'fill', 'stroke', 'placeholder', 'from', 'via', 'to',
+    ],
+  },
+  spacing: {
+    cssPrefix: 'spacing',
+    classPrefixes: [
+      'min-w', 'max-w', 'min-h', 'max-h', 'gap-x', 'gap-y', 'space-x', 'space-y',
+      'px', 'py', 'pt', 'pr', 'pb', 'pl', 'ps', 'pe', 'p',
+      'mx', 'my', 'mt', 'mr', 'mb', 'ml', 'ms', 'me', 'm',
+      'gap', 'w', 'h', 'size', 'inset', 'top', 'right', 'bottom', 'left',
+    ],
+  },
+  radius: { cssPrefix: 'radius', classPrefixes: ['rounded'] },
+  shadow: { cssPrefix: 'shadow', classPrefixes: ['shadow'] },
+  font: { cssPrefix: 'font', classPrefixes: ['font'] },
+};
+
+const ALL_PREFIXES = Object.entries(NAMESPACES)
+  .flatMap(([, def]) => def.classPrefixes.map((prefix) => ({ prefix, cssPrefix: def.cssPrefix })))
+  .sort((a, b) => b.prefix.length - a.prefix.length);
+
+export function matchUtilityBase(base) {
+  for (const { prefix, cssPrefix } of ALL_PREFIXES) {
+    if (base.startsWith(`${prefix}-`)) {
+      const key = base.slice(prefix.length + 1);
+      if (!key) continue;
+      return `--${cssPrefix}-${key}`;
+    }
+  }
+  return null;
+}
+
+// Strips variant prefixes (`hover:`, `dark:`, `sm:`, `data-[state=open]:`,
+// `[&:hover]:`) by splitting on the LAST top-level colon — bracket-aware, so
+// a colon inside an arbitrary-variant selector (`[&:hover]:bg-primary`)
+// isn't mistaken for the variant/utility boundary.
+export function stripVariants(cls) {
+  let depth = 0;
+  let lastColon = -1;
+  for (let i = 0; i < cls.length; i++) {
+    if (cls[i] === '[') depth++;
+    else if (cls[i] === ']') depth--;
+    else if (cls[i] === ':' && depth === 0) lastColon = i;
+  }
+  return lastColon === -1 ? cls : cls.slice(lastColon + 1);
+}
+
+// `bg-[var(--stk-surface-brand-1-strong)]` — an arbitrary-value utility
+// whose bracket content is itself a var() call, bypassing the theme layer
+// entirely. This is the Tailwind-syntax equivalent of a direct var() call
+// site in plain CSS, so it's resolved the same way rather than through the
+// theme map.
+function matchArbitraryVar(base) {
+  const m = base.match(/^[a-z][\w-]*-\[(.+)\]$/i);
+  if (!m) return null;
+  const inner = m[1];
+  const refs = extractVarRefs(inner);
+  const isPureVar = refs.length === 1 && inner.trim() === inner.trim().slice(refs[0].start, refs[0].end);
+  return isPureVar ? refs[0] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Theme extraction — v4 CSS @theme blocks
+//
+// Tailwind v4's @theme block compiles to plain `:root { --key: value; }`
+// declarations, so its entries are folded into the SAME per-selector alias
+// graph the token-alias resolver builds from ordinary CSS (at :root scope) —
+// resolveTerminal then resolves through a --stk-* reference, a further
+// consumer alias, a raw value, or an undefined name identically either way.
+// ---------------------------------------------------------------------------
+
+function collectV4ThemeEntries(cssFiles) {
+  const entries = new Map(); // --key -> { value, file, line }
+  let found = false;
+  for (const file of cssFiles) {
+    let src;
+    try {
+      src = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    let root;
+    try {
+      root = postcss.parse(src, { from: file });
+    } catch {
+      continue;
+    }
+    root.walkAtRules('theme', (atRule) => {
+      found = true;
+      atRule.walkDecls((decl) => {
+        if (!decl.prop.startsWith('--')) return;
+        entries.set(decl.prop, { value: decl.value, file, line: decl.source?.start?.line ?? null });
+      });
+    });
+  }
+  return { found, entries };
+}
+
+// ---------------------------------------------------------------------------
+// Theme extraction — v3 tailwind.config.{js,cjs,mjs,ts} theme.extend.colors
+//
+// Statically parsed (never executed — this scans arbitrary consumer repos).
+// Only plain string/template-literal values are resolvable; a
+// function-based `theme: (helpers) => ({...})` config, or values built from
+// expressions, are silently skipped as unresolvable (documented, not
+// silently misreported — see the themeParseIncomplete escape hatch in
+// resolveTailwindTokens).
+// ---------------------------------------------------------------------------
+
+export function findExportedConfigObject(ast) {
+  let found = null;
+  traverse(ast, {
+    AssignmentExpression(path_) {
+      const { left, right } = path_.node;
+      if (
+        left.type === 'MemberExpression' &&
+        left.object.type === 'Identifier' && left.object.name === 'module' &&
+        !left.computed &&
+        left.property.type === 'Identifier' && left.property.name === 'exports' &&
+        right.type === 'ObjectExpression'
+      ) {
+        found = right;
+      }
+    },
+    ExportDefaultDeclaration(path_) {
+      let decl = path_.node.declaration;
+      // `export default {...} satisfies Config` / `as Config`
+      if (decl.type === 'TSSatisfiesExpression' || decl.type === 'TSAsExpression') {
+        decl = decl.expression;
+      }
+      if (decl.type === 'ObjectExpression') found = decl;
+    },
+  });
+  return found;
+}
+
+export function objectKey(propNode) {
+  if (propNode.key.type === 'Identifier') return propNode.key.name;
+  if (propNode.key.type === 'StringLiteral') return propNode.key.value;
+  if (propNode.key.type === 'NumericLiteral') return String(propNode.key.value);
+  return null;
+}
+
+export function getObjectProp(objExpr, key) {
+  if (!objExpr || objExpr.type !== 'ObjectExpression') return null;
+  for (const prop of objExpr.properties) {
+    if (prop.type !== 'ObjectProperty') continue;
+    if (objectKey(prop) === key) return prop.value;
+  }
+  return null;
+}
+
+function staticStringValue(node) {
+  if (!node) return null;
+  if (node.type === 'StringLiteral') return node.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis.map((q) => q.value.cooked).join('');
+  }
+  return null;
+}
+
+// One level of DEFAULT/shade nesting: `colors: { primary: { DEFAULT: '...',
+// 500: '...' } }` → `--color-primary`, `--color-primary-500`.
+function collectV3Colors(objExpr, into, file) {
+  if (!objExpr || objExpr.type !== 'ObjectExpression') return;
+  for (const prop of objExpr.properties) {
+    if (prop.type !== 'ObjectProperty') continue;
+    const key = objectKey(prop);
+    if (!key) continue;
+
+    const flat = staticStringValue(prop.value);
+    if (flat !== null) {
+      into.set(`--color-${key}`, { value: flat, file, line: prop.loc?.start.line ?? null });
+      continue;
+    }
+
+    if (prop.value.type === 'ObjectExpression') {
+      for (const sub of prop.value.properties) {
+        if (sub.type !== 'ObjectProperty') continue;
+        const subKey = objectKey(sub);
+        if (!subKey) continue;
+        const subVal = staticStringValue(sub.value);
+        if (subVal === null) continue; // nested-again or dynamic — out of scope
+        const cssKey = subKey === 'DEFAULT' ? key : `${key}-${subKey}`;
+        into.set(`--color-${cssKey}`, { value: subVal, file, line: sub.loc?.start.line ?? null });
+      }
+    }
+  }
+}
+
+function collectV3ThemeEntries(root, ignore) {
+  const entries = new Map();
+  const configFiles = fg
+    .sync(['**/tailwind.config.{js,cjs,mjs,ts}'], { cwd: root, absolute: true, ignore: [...DEFAULT_IGNORE, ...ignore] })
+    .sort();
+
+  for (const file of configFiles) {
+    let code;
+    try {
+      code = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = parseSource(code, file);
+    } catch {
+      continue;
+    }
+    const configObj = findExportedConfigObject(ast);
+    const themeObj = getObjectProp(configObj, 'theme');
+    // theme.colors (replaces Tailwind's defaults) and theme.extend.colors
+    // (adds to them) are both just "keys the consumer declared" for our
+    // purposes — walked in that order so extend wins on a same-name clash,
+    // matching Tailwind's own layering.
+    collectV3Colors(getObjectProp(themeObj, 'colors'), entries, file);
+    collectV3Colors(getObjectProp(getObjectProp(themeObj, 'extend'), 'colors'), entries, file);
+  }
+
+  return { found: configFiles.length > 0, entries, configFiles };
+}
+
+// ---------------------------------------------------------------------------
+// Theme-entry classification — same terminal/state machinery as the CSS
+// alias resolver, scoped to only the Tailwind-sourced property names (not
+// the whole merged graph — this resolver reports on Tailwind's own surface,
+// not the consumer's general CSS aliasing, which tokenAliasResolver already
+// covers).
+// ---------------------------------------------------------------------------
+
+function classifyThemeProperties(propGraph, themeEntryNames, inventory, layers) {
+  const properties = [];
+  const findings = [];
+
+  for (const name of themeEntryNames) {
+    const terminal = resolveTerminal(propGraph, name, ':root', inventory, layers, new Set(), 0);
+    const state = classifyTerminalState(terminal.kind);
+    properties.push({ name, state, terminal });
+
+    if (terminal.kind === 'stk' && terminal.layer === 'primitive') {
+      findings.push({ rule: 'layer-violation', severity: 'critical', property: name, stkToken: terminal.stkToken });
+    }
+    if (terminal.kind === 'stk' && terminal.depth > WARN_DEPTH) {
+      findings.push({ rule: 'deep-alias-chain', severity: 'warning', property: name, depth: terminal.depth });
+    }
+    if (state === 'drift') {
+      findings.push({ rule: 'drift-behind-alias', severity: 'critical', property: name });
+    }
+    if (state === 'broken') {
+      findings.push({ rule: 'broken-alias', severity: 'critical', property: name, reason: terminal.kind });
+    }
+    if (terminal.rawFallbackPresent) {
+      findings.push({ rule: 'raw-fallback', severity: 'info', property: name });
+    }
+  }
+
+  return { properties, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Pass 2 — JSX className utility-class occurrences as usages
+// ---------------------------------------------------------------------------
+
+function extractClassNameString(valueNode) {
+  if (!valueNode) return null;
+  if (valueNode.type === 'StringLiteral') return valueNode.value;
+  if (valueNode.type === 'JSXExpressionContainer') {
+    const expr = valueNode.expression;
+    if (expr.type === 'StringLiteral') return expr.value;
+    if (expr.type === 'TemplateLiteral' && expr.expressions.length === 0) {
+      return expr.quasis.map((q) => q.value.cooked).join('');
+    }
+  }
+  // clsx()/classnames()/ternaries/interpolated templates — dynamic
+  // composition, out of scope (documented, same "static only" boundary the
+  // v3 config parser uses).
+  return null;
+}
+
+export function collectClassNameUsages(moduleGraph) {
+  const usages = [];
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry || entry.parseError) continue;
+    traverse(entry.ast, {
+      JSXAttribute(path_) {
+        const attrName = path_.node.name.name;
+        if (attrName !== 'className' && attrName !== 'class') return;
+        const str = extractClassNameString(path_.node.value);
+        if (str == null) return;
+        for (const cls of str.split(/\s+/).filter(Boolean)) {
+          usages.push({ file, line: path_.node.loc?.start.line ?? null, className: cls });
+        }
+      },
+    });
+  }
+  return usages;
+}
+
+function classifyClassNameUsage(cls, propGraph, themeEntryNames, inventory, layers) {
+  const base = stripVariants(cls);
+
+  const arbitrary = matchArbitraryVar(base);
+  if (arbitrary) {
+    const { name } = arbitrary;
+    if (name.startsWith('--stk-')) {
+      return inventory.has(name)
+        ? { classification: 'direct', stkToken: name }
+        : { classification: 'broken', reason: 'undefined-stk-token' };
+    }
+    const bySelector = propGraph.get(name);
+    if (!bySelector) return { classification: 'broken', reason: 'undefined-property' };
+    const bound = bySelector.has(':root') ? ':root' : [...bySelector.keys()][0];
+    const terminal = resolveTerminal(propGraph, name, bound, inventory, layers, new Set(), 0);
+    const state = classifyTerminalState(terminal.kind);
+    return { classification: state === 'conformant' ? 'aliased' : state, stkToken: terminal.stkToken };
+  }
+
+  const propName = matchUtilityBase(base);
+  if (!propName) return null; // not a utility shape this resolver tracks at all
+  if (!themeEntryNames.has(propName)) return null; // Tailwind's own default scale, not a consumer theme key — out of scope, not a violation
+
+  const terminal = resolveTerminal(propGraph, propName, ':root', inventory, layers, new Set(), 0);
+  const state = classifyTerminalState(terminal.kind);
+  return { classification: state === 'conformant' ? 'aliased' : state, propName, stkToken: terminal.stkToken };
+}
+
+// Same "three numbers, never one" shape as tokenAliasResolver's report — see
+// its summarizeReport for the full rationale. Utility-class usages are never
+// "direct" from the theme map (that classification is reserved for the
+// arbitrary-value var() escape hatch, which really is a call-site literal).
+function summarizeReport(usages) {
+  const counts = { direct: 0, aliased: 0, unresolved: 0 };
+  for (const u of usages) {
+    if (u.classification === 'direct') counts.direct++;
+    else if (u.classification === 'aliased') counts.aliased++;
+    else counts.unresolved++;
+  }
+  const total = counts.direct + counts.aliased + counts.unresolved;
+  const pct = (n) => (total === 0 ? 0 : Math.round((n / total) * 1000) / 10);
+  return {
+    total,
+    direct: counts.direct,
+    directPct: pct(counts.direct),
+    aliased: counts.aliased,
+    aliasedPct: pct(counts.aliased),
+    unresolved: counts.unresolved,
+    unresolvedPct: pct(counts.unresolved),
+    conformancePct: pct(counts.direct + counts.aliased),
+  };
+}
+
+/**
+ * Resolves Tailwind's class-name indirection back to Stark tokens
+ * (ADOPTION_APP_PLAN.md §5a, "Tailwind is the common case"): a `bg-primary`
+ * utility is invisible to a CSS var() scanner, but is a token usage if
+ * `--color-primary` (v4 `@theme`) or `colors.primary` (v3
+ * `theme.extend.colors`) resolves to a Stark token.
+ *
+ * Per the phase-1 promotion criterion's companion rule (§9): detection is
+ * always cheap, resolution isn't. When Tailwind isn't detected at all, or is
+ * detected but no theme entries could be statically resolved (a dynamic
+ * config, or theme keys outside this resolver's namespace table), this
+ * refuses to produce a score rather than reporting a misleadingly low one —
+ * `report` is `null` and `detected`/`themeParseIncomplete` say why.
+ */
+export function resolveTailwindTokens(root, { platform = 'web', ignore = [] } = {}) {
+  if (platform !== 'web') {
+    throw new Error(`resolveTailwindTokens only supports platform "web" (got "${platform}") — Tailwind utility classes have no RN equivalent.`);
+  }
+
+  const stkPkgRoot = stkRoot();
+  const { inventory, layers } = loadTokenInventory(stkPkgRoot);
+  const cssFiles = collectCssFiles(root, ignore);
+
+  const { found: v4Found, entries: v4Entries } = collectV4ThemeEntries(cssFiles);
+  const { found: v3Found, entries: v3Entries, configFiles } = collectV3ThemeEntries(root, ignore);
+
+  const detected = v4Found || v3Found;
+  if (!detected) {
+    return {
+      platform,
+      root,
+      detected: false,
+      reason: 'No @theme{} block or tailwind.config.{js,cjs,mjs,ts} found — Tailwind not in use here, not scored.',
+      themeProperties: [],
+      usages: [],
+      findings: [],
+      report: null,
+    };
+  }
+
+  const themeEntries = new Map([...v4Entries, ...v3Entries]);
+
+  if (themeEntries.size === 0) {
+    return {
+      platform,
+      root,
+      detected: true,
+      themeParseIncomplete: true,
+      reason: 'Tailwind detected but no statically-resolvable theme entries were found — likely a dynamic/function-based tailwind.config theme, or theme keys outside the namespaces this resolver understands (color, spacing, radius, shadow, font). Not scored.',
+      configFiles: configFiles.map((f) => path.relative(root, f)),
+      themeProperties: [],
+      usages: [],
+      findings: [],
+      report: null,
+    };
+  }
+
+  const propGraph = buildPropertyGraph(cssFiles);
+  for (const [name, decl] of themeEntries) {
+    let bySelector = propGraph.get(name);
+    if (!bySelector) {
+      bySelector = new Map();
+      propGraph.set(name, bySelector);
+    }
+    bySelector.set(':root', decl);
+  }
+
+  const themeEntryNames = new Set(themeEntries.keys());
+  const { properties, findings } = classifyThemeProperties(propGraph, themeEntryNames, inventory, layers);
+
+  const moduleGraph = buildModuleGraph(root, { ignore });
+  const rawUsages = collectClassNameUsages(moduleGraph);
+  const usages = [];
+  for (const u of rawUsages) {
+    const result = classifyClassNameUsage(u.className, propGraph, themeEntryNames, inventory, layers);
+    if (!result) continue;
+    usages.push({ file: path.relative(root, u.file), line: u.line, className: u.className, ...result });
+  }
+
+  const report = summarizeReport(usages);
+
+  return {
+    platform,
+    root,
+    detected: true,
+    source: v4Found && v3Found ? 'both' : v4Found ? 'v4' : 'v3',
+    scannedCssFiles: cssFiles.length,
+    scannedJsFiles: moduleGraph.files.length,
+    themeEntryCount: themeEntries.size,
+    tokenInventoryTotal: inventory.size,
+    properties,
+    usages,
+    findings,
+    report,
+  };
+}

package/src/adopt/tailwindResolver.test.js

@@ -0,0 +1,178 @@
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { describe, it, expect, afterEach } from 'vitest';
+
+import { resolveTailwindTokens } from './tailwindResolver.js';
+
+let tmpDirs = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+function fixture(files) {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'stark-adopt-tailwind-'));
+  tmpDirs.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+function usage(result, className) {
+  return result.usages.find((u) => u.className === className);
+}
+
+describe('resolveTailwindTokens — detection', () => {
+  it('reports detected:false with no report when neither a config nor an @theme block exists', () => {
+    const root = fixture({
+      'src/app.css': `.btn { color: red; }`,
+      'src/App.jsx': `export const App = () => <div className="flex p-4" />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(result.detected).toBe(false);
+    expect(result.report).toBeNull();
+  });
+
+  it('detects a v4 @theme block even with no config file', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(result.detected).toBe(true);
+    expect(result.source).toBe('v4');
+  });
+
+  it('detects a v3 tailwind.config.js even with no @theme block', () => {
+    const root = fixture({
+      'tailwind.config.js': `module.exports = { theme: { extend: { colors: { primary: 'var(--stk-surface-brand-1-strong)' } } } };`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(result.detected).toBe(true);
+    expect(result.source).toBe('v3');
+  });
+
+  it('reports themeParseIncomplete instead of a zero score for a dynamic/function-based v3 config', () => {
+    const root = fixture({
+      'tailwind.config.js': `module.exports = { theme: (helpers) => ({ colors: { primary: helpers.colors.blue } }) };`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(result.detected).toBe(true);
+    expect(result.themeParseIncomplete).toBe(true);
+    expect(result.report).toBeNull();
+  });
+});
+
+describe('resolveTailwindTokens — v4 @theme classification', () => {
+  it('classifies a @theme entry aliasing an inventory stk token as conformant', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    const prop = result.properties.find((p) => p.name === '--color-primary');
+    expect(prop.state).toBe('conformant');
+  });
+
+  it('classifies a @theme entry with a raw value as drift', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: #1956dd; }`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    const prop = result.properties.find((p) => p.name === '--color-primary');
+    expect(prop.state).toBe('drift');
+  });
+});
+
+describe('resolveTailwindTokens — v3 tailwind.config theme.extend.colors classification', () => {
+  it('classifies a flat color entry aliasing an inventory stk token as conformant', () => {
+    const root = fixture({
+      'tailwind.config.js': `module.exports = { theme: { extend: { colors: { primary: 'var(--stk-surface-brand-1-strong)' } } } };`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    const prop = result.properties.find((p) => p.name === '--color-primary');
+    expect(prop.state).toBe('conformant');
+  });
+
+  it('classifies a nested DEFAULT/shade color entry', () => {
+    const root = fixture({
+      'tailwind.config.js': `module.exports = { theme: { extend: { colors: { brand: { DEFAULT: 'var(--stk-surface-brand-1-strong)', 500: '#1956dd' } } } } };`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(result.properties.find((p) => p.name === '--color-brand').state).toBe('conformant');
+    expect(result.properties.find((p) => p.name === '--color-brand-500').state).toBe('drift');
+  });
+});
+
+describe('resolveTailwindTokens — JSX className usage scanning', () => {
+  it('classifies a utility class resolving to a conformant theme entry as aliased', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+      'src/App.jsx': `export const App = () => <div className="bg-primary" />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(usage(result, 'bg-primary').classification).toBe('aliased');
+    expect(result.report.aliased).toBe(1);
+  });
+
+  it('classifies a utility class resolving to a drifted theme entry as drift, not aliased', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: #1956dd; }`,
+      'src/App.jsx': `export const App = () => <div className="bg-primary" />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(usage(result, 'bg-primary').classification).toBe('drift');
+  });
+
+  it('strips a variant prefix before matching the base utility', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+      'src/App.jsx': `export const App = () => <div className="hover:bg-primary dark:[&:hover]:bg-primary" />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(usage(result, 'hover:bg-primary').classification).toBe('aliased');
+    expect(usage(result, 'dark:[&:hover]:bg-primary').classification).toBe('aliased');
+  });
+
+  it('classifies an arbitrary-value var() utility as direct', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+      'src/App.jsx': `export const App = () => <div className="bg-[var(--stk-surface-brand-1-strong)]" />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(usage(result, 'bg-[var(--stk-surface-brand-1-strong)]').classification).toBe('direct');
+    expect(result.report.direct).toBe(1);
+  });
+
+  it('does not count an unrelated utility class or Tailwind default-palette color as a usage', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+      'src/App.jsx': `export const App = () => <div className="flex bg-red-500 p-4" />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(usage(result, 'flex')).toBeUndefined();
+    expect(usage(result, 'bg-red-500')).toBeUndefined();
+    expect(usage(result, 'p-4')).toBeUndefined();
+    expect(result.report.total).toBe(0);
+  });
+
+  it('does not count a dynamic className expression (clsx/ternary) since it is not statically resolvable', () => {
+    const root = fixture({
+      'src/app.css': `@theme { --color-primary: var(--stk-surface-brand-1-strong); }`,
+      'src/App.jsx': `export const App = ({ active }) => <div className={active ? 'bg-primary' : 'bg-primary'} />;`,
+    });
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+    expect(result.report.total).toBe(0);
+  });
+});
+
+describe('resolveTailwindTokens — platform scope', () => {
+  it('throws for a non-web platform since Tailwind utility classes have no RN equivalent', () => {
+    const root = fixture({ 'tailwind.config.js': `module.exports = {};` });
+    expect(() => resolveTailwindTokens(root, { platform: 'native' })).toThrow(/web/i);
+  });
+});