vibe-design-system 2.8.81 → 2.9.0

package/bin/init.js

@@ -241,12 +241,22 @@ function detectFramework(pkg) {
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
   if (deps["next"]) return "nextjs";
   if (deps["@remix-run/react"] || deps["@remix-run/node"]) return "remix";
+  if (deps["react-scripts"]) return "cra"; // Phase E2 — Create React App
+  // Phase F — Vue/Svelte/Angular detection
+  if (deps["vue"] || deps["nuxt"]) return "vue";
+  if (deps["svelte"] || deps["@sveltejs/kit"]) return "svelte";
+  if (deps["@angular/core"]) return "angular";
   return "vite";
 }
 
 /** Framework'e göre Storybook framework paket adı */
 function storybookFrameworkPackage(framework) {
   if (framework === "nextjs") return "@storybook/nextjs";
+  if (framework === "cra") return "@storybook/react-webpack5"; // Phase E2 — CRA uses webpack5
+  // Phase F — Cross-framework support
+  if (framework === "vue") return "@storybook/vue3-vite";
+  if (framework === "svelte") return "@storybook/svelte-vite";
+  if (framework === "angular") return "@storybook/angular";
   return "@storybook/react-vite"; // vite & remix
 }
 
@@ -257,6 +267,48 @@ function buildStorybookMainTs(framework, srcPrefix) {
     ? `\n    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)",`
     : "";
 
+  // Phase F — Vue framework
+  if (framework === "vue") {
+    return `import type { StorybookConfig } from "@storybook/vue3-vite";
+
+const config: StorybookConfig = {
+  stories: ["../${srcPrefix}/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  addons: ["@storybook/addon-essentials"],
+  framework: { name: "@storybook/vue3-vite", options: {} },
+};
+
+export default config;
+`;
+  }
+
+  // Phase F — Svelte framework
+  if (framework === "svelte") {
+    return `import type { StorybookConfig } from "@storybook/svelte-vite";
+
+const config: StorybookConfig = {
+  stories: ["../${srcPrefix}/**/*.stories.@(js|ts|svelte)"],
+  addons: ["@storybook/addon-essentials"],
+  framework: { name: "@storybook/svelte-vite", options: {} },
+};
+
+export default config;
+`;
+  }
+
+  // Phase F — Angular framework
+  if (framework === "angular") {
+    return `import type { StorybookConfig } from "@storybook/angular";
+
+const config: StorybookConfig = {
+  stories: ["../${srcPrefix}/**/*.stories.@(js|ts)"],
+  addons: ["@storybook/addon-essentials"],
+  framework: { name: "@storybook/angular", options: {} },
+};
+
+export default config;
+`;
+  }
+
   if (framework === "nextjs") {
     return `import type { StorybookConfig } from "@storybook/nextjs";
 
@@ -297,10 +349,36 @@ const config: StorybookConfig = {
     options: {},
   },
   async viteFinal(config) {
+    // Phase C2 — read tsconfig.json paths and inject as Vite aliases
+    const extraAliases = (() => {
+      try {
+        const tsConfigPaths = [
+          path.resolve(process.cwd(), "tsconfig.json"),
+          path.resolve(process.cwd(), "tsconfig.app.json"),
+          path.resolve(process.cwd(), "${srcPrefix}", "..", "tsconfig.json"),
+        ];
+        for (const tcp of tsConfigPaths) {
+          if (!require("fs").existsSync(tcp)) continue;
+          const raw = JSON.parse(require("fs").readFileSync(tcp, "utf-8").replace(/\/\/[^\n]*/g, "").replace(/,(\s*[}\]])/g, "$1"));
+          const paths = raw?.compilerOptions?.paths || {};
+          const aliases: Record<string, string> = {};
+          for (const [alias, targets] of Object.entries(paths) as [string, string[]][]) {
+            const cleanAlias = alias.replace(/\/\*$/, "");
+            const target = targets[0]?.replace(/\/\*$/, "") || "";
+            if (cleanAlias && target && cleanAlias !== "@") {
+              aliases[cleanAlias] = path.resolve(process.cwd(), target);
+            }
+          }
+          if (Object.keys(aliases).length > 0) return aliases;
+        }
+      } catch (_) {}
+      return {};
+    })();
     return mergeConfig(config, {
       resolve: {
         alias: {
           "@": path.resolve(process.cwd(), "${srcPrefix}"),
+          ...extraAliases,
         },
       },
     });
@@ -673,18 +751,42 @@ if (!pkg) {
 // Monorepo kök dizininde mi?
 const monorepoPackages = detectMonorepoPackages(projectRoot);
 if (monorepoPackages.length > 0 && pkg.workspaces) {
-  console.warn("⚠️  Bu dizin bir monorepo kök dizini gibi görünüyor.");
-  console.warn("   VDS'yi her uygulama klasöründe ayrı ayrı kurmanız gerekiyor.\n");
-  console.warn("   Tespit edilen paketler:");
-  for (const p of monorepoPackages) {
+  // Phase E3 — Monorepo guidance: show all workspaces with React deps, auto-install in first one
+  const reactPackages = monorepoPackages.filter(p => {
+    try {
+      const pkgPath = path.join(p, "package.json");
+      if (!fs.existsSync(pkgPath)) return false;
+      const wpkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+      const deps = { ...wpkg.dependencies, ...wpkg.devDependencies };
+      return !!deps["react"];
+    } catch (_) { return false; }
+  });
+  const targetPackages = reactPackages.length > 0 ? reactPackages : monorepoPackages;
+
+  console.log("📦 Monorepo tespit edildi — React içeren workspace'ler:");
+  for (const p of targetPackages) {
     const rel = path.relative(projectRoot, p);
-    console.warn(`   → ${rel}`);
+    console.log(`   → ${rel}`);
+  }
+  console.log("");
+  console.log("💡 Her workspace için ayrı kurulum komutları:");
+  for (const p of targetPackages) {
+    const rel = path.relative(projectRoot, p);
+    console.log(`   cd ${rel} && npx vibe-design-system init`);
+  }
+  console.log("");
+  if (!process.env.VDS_COMPONENTS_DIR) {
+    // Auto-select first React workspace and continue installation there
+    const firstReact = targetPackages[0];
+    if (firstReact) {
+      const rel = path.relative(projectRoot, firstReact);
+      console.log(`🚀 İlk React workspace'e otomatik kurulum yapılıyor: ${rel}`);
+      console.log("   (VDS_COMPONENTS_DIR env değişkeni ile farklı bir workspace seçebilirsiniz)\n");
+      process.chdir(firstReact);
+      // Update projectRoot for remaining steps
+      Object.assign(global, { __vdsProjectRoot: firstReact });
+    }
   }
-  console.warn("\n   Örnek kullanım:");
-  const firstRel = path.relative(projectRoot, monorepoPackages[0]);
-  console.warn(`   cd ${firstRel} && npx vibe-design-system init`);
-  console.warn("\n   VDS'yi bu dizinden çalıştırmaya devam etmek istiyorsanız,");
-  console.warn("   VDS_COMPONENTS_DIR env değişkeni ile hedef klasörü belirtin.\n");
 }
 
 const framework = detectFramework(pkg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-design-system",
-  "version": "2.8.81",
+  "version": "2.9.0",
   "description": "Auto-generate design systems for vibe coding projects",
   "homepage": "https://vibedesign.tech",
   "repository": {

package/vds-core-template/scan.mjs

@@ -945,7 +945,7 @@ function extractComponentSuggestions() {
 
 /** src/pages/ içinde tanımlı ama src/components'a çıkarılmamış visual section'ları listele (component adayı raporu). */
 function extractUnreleasedSectionCandidates() {
-  if (!fs.existsSync(PAGES_DIR)) return [];
+  if (!PAGES_DIR || !fs.existsSync(PAGES_DIR)) return [];
   const suggestions = extractComponentSuggestions();
   return suggestions.map((s) => ({
     suggestedName: s.suggestedName,
@@ -1393,6 +1393,58 @@ function extractFoundations() {
   // Also use first found as primary (for legacy logic below)
   const cssToRead = allCssCandidates.find((p) => fs.existsSync(p)) || "";
 
+  // Phase C — JSON token file reader (W3C DTCG + Style Dictionary)
+  {
+    const tokenFileCandidates = [
+      path.join(PROJECT_ROOT, "tokens.json"),
+      path.join(PROJECT_ROOT, "design-tokens.json"),
+      path.join(PROJECT_ROOT, "src", "tokens.json"),
+      path.join(PROJECT_ROOT, "src", "design-tokens.json"),
+      path.join(PROJECT_ROOT, "tokens", "tokens.json"),
+      path.join(PROJECT_ROOT, "tokens", "design-tokens.json"),
+    ];
+    // Also scan tokens/ directory for any .json files
+    const tokensDir = path.join(PROJECT_ROOT, "tokens");
+    if (fs.existsSync(tokensDir)) {
+      try {
+        for (const f of fs.readdirSync(tokensDir)) {
+          if (f.endsWith(".json")) tokenFileCandidates.push(path.join(tokensDir, f));
+        }
+      } catch (_) {}
+    }
+    for (const tf of tokenFileCandidates) {
+      if (!fs.existsSync(tf)) continue;
+      try {
+        const raw = JSON.parse(fs.readFileSync(tf, "utf-8"));
+        // W3C DTCG: { "color": { "primary": { "$value": "#...", "$type": "color" } } }
+        // Style Dictionary: { "color-primary": { "value": "#..." } }
+        const flatTokens = {};
+        function flattenDTCG(obj, prefix) {
+          for (const [k, v] of Object.entries(obj)) {
+            if (v && typeof v === "object") {
+              if ("$value" in v) {
+                if (!v.$type || v.$type === "color") {
+                  flatTokens[(prefix ? prefix + "-" : "") + k] = v.$value;
+                }
+              } else if ("value" in v) {
+                flatTokens[(prefix ? prefix + "-" : "") + k] = v.value;
+              } else {
+                flattenDTCG(v, (prefix ? prefix + "-" : "") + k);
+              }
+            }
+          }
+        }
+        flattenDTCG(raw, "");
+        for (const [name, value] of Object.entries(flatTokens)) {
+          const cleanName = name.replace(/^color[-_]/i, "").replace(/^-/, "");
+          if (!colors[cleanName] && (typeof value === "string") && (value.startsWith("#") || /^(rgb|hsl|oklch|transparent)/.test(value))) {
+            colors[cleanName] = { value, hex: value };
+          }
+        }
+      } catch (_) {}
+    }
+  }
+
   try {
     if (cssChunks.length > 0) {
       const css = cssChunks.join("\n");
@@ -1429,11 +1481,33 @@ function extractFoundations() {
         }
       }
 
-      // body { font-family } — supports nested @layer base { body { } } structure
-      const bodyMatch = css.match(/\bbody\s*\{[\s\S]*?font-family:\s*([^;]+);/) ||
-                        css.match(/body\s*\{[^}]*font-family:\s*([^;]+);/s);
+      // Phase B — @font-face declarations (variable fonts, custom webfonts)
+      const fontFaceDecls = [];
+      const fontFaceRe = /@font-face\s*\{([^}]+)\}/g;
+      let ffm;
+      while ((ffm = fontFaceRe.exec(css)) !== null) {
+        const block = ffm[1];
+        const fam = block.match(/font-family:\s*['"]?([^;'"]+)['"]?;/)?.[1]?.trim();
+        const wgt = block.match(/font-weight:\s*([^;]+);/)?.[1]?.trim();
+        const sty = block.match(/font-style:\s*([^;]+);/)?.[1]?.trim() || "normal";
+        if (fam) {
+          const isVariable = wgt ? /^\d+\s+\d+$/.test(wgt.trim()) : false;
+          fontFaceDecls.push({ family: fam, weight: wgt || null, style: sty, isVariable });
+        }
+      }
+      if (fontFaceDecls.length > 0) typography.fontFaces = fontFaceDecls;
+
+      // body { font-family } — Tailwind v4 sets font on html/:host, NOT body
+      // Use [^}]* to stay within block boundaries ([\s\S]*? crosses blocks → mono font false-positive)
+      const bodyMatch =
+        css.match(/\bbody\s*\{[^}]*font-family:\s*([^;]+);/) ||
+        css.match(/html\s*(?:,\s*:host)?\s*\{[^}]*font-family:\s*([^;]+);/); // Tailwind v4
       if (bodyMatch) typography.body = bodyMatch[1].trim();
-      const monoMatch = css.match(/code,\s*pre,\s*\.font-mono\s*\{[^}]*font-family:\s*([^;]+);/s);
+      // Mono: code/kbd/samp/pre block (Tailwind v4 uses code,kbd,samp,pre not code,pre,.font-mono)
+      const monoMatch =
+        css.match(/code,\s*pre,\s*\.font-mono\s*\{[^}]*font-family:\s*([^;]+);/) ||
+        css.match(/code,\s*kbd[^{]*\{[^}]*font-family:\s*([^;]+);/) ||
+        css.match(/\bcode\b[^{,]*\{[^}]*font-family:\s*([^;]+);/);
       if (monoMatch) typography.mono = monoMatch[1].trim();
       // CSS custom properties for fonts (--font-sans, --font-mono, --font-display, etc.)
       const fontVarRe = /--font([\w-]*):\s*([^;\n]+);/g;
@@ -1444,14 +1518,27 @@ function extractFoundations() {
         if (!typography[key]) typography[key] = val;
       }
       // Resolve var(--font-*) references in body/mono to actual font names
-      // Key construction must match the fontVarRe loop: --font-sans → "font-sans" → "fontSans"
+      // Also handles Tailwind v4 --default-font-family / --default-mono-font-family chain
       function resolveTypoVar(val) {
         if (!val || !val.startsWith("var(")) return val;
+        // Direct --font-* reference: var(--font-sans) → typography.fontSans
         const m = val.match(/var\(--font-([\w-]+)\)/);
-        if (!m) return val;
-        // prepend "-" so camelCase conversion matches: "font-" + "sans" → "fontSans"
-        const key = `font-${m[1]}`.replace(/-([a-zA-Z])/g, (_, c) => c.toUpperCase());
-        return (typography[key] && !typography[key].startsWith("var(")) ? typography[key] : val;
+        if (m) {
+          const key = `font-${m[1]}`.replace(/-([a-zA-Z])/g, (_, c) => c.toUpperCase());
+          return (typography[key] && !typography[key].startsWith("var(")) ? typography[key] : val;
+        }
+        // Tailwind v4: var(--default-font-family, ...) → resolve via fontSans
+        if (val.includes("--default-font-family") && !val.includes("--default-mono")) {
+          if (typography.fontSans && !typography.fontSans.startsWith("var(")) return typography.fontSans;
+          // Fallback: strip the var() wrapper to get the fallback list
+          return val.replace(/^var\(--default-font-family,\s*/, "").replace(/\)\s*$/, "").trim() || val;
+        }
+        // Tailwind v4: var(--default-mono-font-family, ...) → resolve via fontMono
+        if (val.includes("--default-mono-font-family")) {
+          if (typography.fontMono && !typography.fontMono.startsWith("var(")) return typography.fontMono;
+          return val.replace(/^var\(--default-mono-font-family,\s*/, "").replace(/\)\s*$/, "").trim() || val;
+        }
+        return val;
       }
       if (typography.body) typography.body = resolveTypoVar(typography.body);
       if (typography.mono) typography.mono = resolveTypoVar(typography.mono);
@@ -1956,6 +2043,41 @@ function extractFoundations() {
     if (arbFonts.size > 0) typography.arbitraryFonts = Array.from(arbFonts);
   }
 
+  // Phase B — next/font detection
+  {
+    const nextFonts = [];
+    const allTsxForFonts = getAllTsxJsxInDir(SRC_DIR);
+    const nextFontRe = /import\s*\{\s*([\w,\s]+)\s*\}\s*from\s*['"]next\/font\/(google|local)['"]/g;
+    const fontCallRe = /const\s+(\w+)\s*=\s*(\w+)\s*\(\s*\{([^}]+)\}\s*\)/g;
+    for (const file of allTsxForFonts) {
+      let src;
+      try { src = fs.readFileSync(file, "utf-8"); } catch (_) { continue; }
+      nextFontRe.lastIndex = 0;
+      let nm;
+      while ((nm = nextFontRe.exec(src)) !== null) {
+        const source = `next/font/${nm[2]}`;
+        const imported = nm[1].split(",").map(s => s.trim()).filter(Boolean);
+        for (const fontName of imported) {
+          fontCallRe.lastIndex = 0;
+          let cm;
+          while ((cm = fontCallRe.exec(src)) !== null) {
+            if (cm[2] === fontName) {
+              const varM = cm[3].match(/variable:\s*['"]([^'"]+)['"]/);
+              const subM = cm[3].match(/subsets?:\s*\[([^\]]+)\]/);
+              nextFonts.push({
+                source,
+                family: fontName,
+                variable: varM ? varM[1] : null,
+                subsets: subM ? subM[1].replace(/['"]/g, "").split(",").map(s=>s.trim()) : [],
+              });
+            }
+          }
+        }
+      }
+    }
+    if (nextFonts.length > 0) typography.nextFonts = nextFonts;
+  }
+
   return {
     colors: foundationsColors,
     typography,
@@ -2089,6 +2211,88 @@ function extractTokenUsage() {
   };
 }
 
+/**
+ * Phase A — Color Intelligence v2.9.0
+ * Counts how many times each color token is used in src/ files.
+ * Tracks bg/text/border/ring/fill/stroke/other categories and dark: usage separately.
+ * O(files) complexity — single readFileSync per file, one combined regex for all color names.
+ */
+function extractColorUsage(colorTokenNames) {
+  if (!fs.existsSync(SRC_DIR) || !colorTokenNames || colorTokenNames.length === 0) return null;
+  const allSrcFiles = getAllTsxJsxInDir(SRC_DIR).filter(f => !f.includes("stories"));
+  if (allSrcFiles.length === 0) return null;
+  const prefixes = ["bg","text","border","ring","fill","stroke","from","to","via","shadow","outline","decoration","placeholder","accent"];
+  const escapedNames = colorTokenNames.map(n => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const combined = new RegExp(
+    `\\b(dark:)?(${prefixes.join("|")})-(${escapedNames.join("|")})(?:\\/\\d+)?\\b`,
+    "g"
+  );
+  const usage = {};
+  const fileMap = {};
+  for (const file of allSrcFiles) {
+    const compName = path.basename(file, path.extname(file));
+    let content;
+    try { content = fs.readFileSync(path.join(SRC_DIR, file), "utf-8"); } catch (_) { continue; }
+    combined.lastIndex = 0;
+    let m;
+    while ((m = combined.exec(content)) !== null) {
+      const isDark = !!m[1];
+      const prefix = m[2];
+      const colorName = m[3];
+      if (!usage[colorName]) {
+        usage[colorName] = { bg:0, text:0, border:0, ring:0, fill:0, stroke:0, other:0, total:0, dark:0 };
+      }
+      if (isDark) { usage[colorName].dark++; continue; }
+      const cat = prefix === "bg" ? "bg" : prefix === "text" ? "text" : prefix === "border" ? "border"
+        : prefix === "ring" ? "ring" : prefix === "fill" ? "fill" : prefix === "stroke" ? "stroke" : "other";
+      usage[colorName][cat]++;
+      usage[colorName].total++;
+      if (!fileMap[colorName]) fileMap[colorName] = new Map();
+      fileMap[colorName].set(compName, (fileMap[colorName].get(compName) || 0) + 1);
+    }
+  }
+  for (const [name, u] of Object.entries(usage)) {
+    const sorted = [...(fileMap[name]?.entries() || [])].sort((a,b) => b[1]-a[1]).slice(0, 5);
+    u.topFiles = sorted.map(([f]) => f);
+  }
+  return Object.keys(usage).length > 0 ? usage : null;
+}
+
+/**
+ * Phase E — Dark mode strategy detection v2.13.0
+ * Detects whether the project uses class-based, media-query, or data-attribute dark mode.
+ */
+function detectDarkModeStrategy(projectRoot) {
+  // 1. Check tailwind.config.js/ts
+  const twConfigs = ["tailwind.config.js","tailwind.config.ts","tailwind.config.mjs","tailwind.config.cjs"];
+  for (const cfg of twConfigs) {
+    const p = path.join(projectRoot, cfg);
+    if (!fs.existsSync(p)) continue;
+    try {
+      const src = fs.readFileSync(p, "utf-8");
+      const m = src.match(/darkMode\s*:\s*['"]?(class|media|selector)['"]?/);
+      if (m) return m[1] === "selector" ? "data-attribute" : m[1];
+    } catch (_) {}
+  }
+  // 2. Check CSS files for .dark {} or [data-theme="dark"] or @media (prefers-color-scheme)
+  const cssCandidates = [
+    path.join(projectRoot, "src", "index.css"),
+    path.join(projectRoot, "src", "globals.css"),
+    path.join(projectRoot, "src", "styles", "globals.css"),
+    path.join(projectRoot, "app", "globals.css"),
+  ];
+  for (const cp of cssCandidates) {
+    if (!fs.existsSync(cp)) continue;
+    try {
+      const css = fs.readFileSync(cp, "utf-8");
+      if (/\[data-theme\s*=\s*['"]dark['"]\]/.test(css)) return "data-attribute";
+      if (/\.dark\s*[{,]/.test(css)) return "class";
+      if (/@media\s*\(prefers-color-scheme\s*:\s*dark\)/.test(css)) return "media";
+    } catch (_) {}
+  }
+  return "unknown";
+}
+
 function extractButtonUsage() {
   if (!fs.existsSync(SRC_DIR)) return null;
   const files = getAllTsxJsxInDir(SRC_DIR);
@@ -2147,6 +2351,50 @@ function extractButtonUsage() {
   };
 }
 
+/**
+ * Phase D — CSS Modules Support v2.12.0
+ * Reads .module.css files imported by a component and extracts design-relevant CSS properties.
+ */
+function extractCssModuleTokens(compFilePath) {
+  if (!compFilePath || !fs.existsSync(compFilePath)) return null;
+  let src;
+  try { src = fs.readFileSync(compFilePath, "utf-8"); } catch (_) { return null; }
+  // Find `import styles from './Foo.module.css'` or named imports
+  const moduleImportRe = /import\s+(?:[\w{},\s]+\s+from\s+)?['"]([^'"]+\.module\.css)['"]/g;
+  const dir = path.dirname(compFilePath);
+  const classNames = [];
+  const properties = {};
+  let found = false;
+  let m;
+  while ((m = moduleImportRe.exec(src)) !== null) {
+    const cssPath = path.resolve(dir, m[1]);
+    if (!fs.existsSync(cssPath)) continue;
+    let css;
+    try { css = fs.readFileSync(cssPath, "utf-8"); } catch (_) { continue; }
+    found = true;
+    // Extract class names and design-relevant properties
+    const classBlockRe = /\.(\w[\w-]*)\s*\{([^}]+)\}/g;
+    let cb;
+    while ((cb = classBlockRe.exec(css)) !== null) {
+      const className = cb[1];
+      if (!classNames.includes(className)) classNames.push(className);
+      const block = cb[2];
+      const DESIGN_PROPS = ["background","background-color","color","font-family","font-size","font-weight","padding","padding-top","padding-right","padding-bottom","padding-left","margin","border-radius","gap","border","border-color","border-width","box-shadow","opacity","width","height"];
+      for (const prop of DESIGN_PROPS) {
+        const re = new RegExp(`${prop}:\\s*([^;]+);`);
+        const pm = block.match(re);
+        if (pm) {
+          if (!properties[prop]) properties[prop] = [];
+          const val = pm[1].trim();
+          if (!properties[prop].includes(val)) properties[prop].push(val);
+        }
+      }
+    }
+  }
+  if (!found || classNames.length === 0) return null;
+  return { classNames, properties };
+}
+
 /**
  * Scan all non-component source files and count how many times each variant value
  * is explicitly used for each component (e.g. <Button variant="destructive">).
@@ -2247,7 +2495,11 @@ function scan() {
     }
     const tokens = extractTailwindTokens(content);
     const isPageComponent = isComplexPageComponent(content);
-    results.push({ file: rel, name, group, category, description, tokens, ...(isPageComponent ? { isPageComponent: true } : {}) });
+    const comp = { file: rel, name, group, category, description, tokens, ...(isPageComponent ? { isPageComponent: true } : {}) };
+    // Phase D — CSS Module tokens
+    const cssModuleTokens = extractCssModuleTokens(COMPONENTS_DIR ? path.join(COMPONENTS_DIR, rel) : null);
+    if (cssModuleTokens) comp.cssModuleTokens = cssModuleTokens;
+    results.push(comp);
   }
   if (PAGES_DIR && fs.existsSync(PAGES_DIR)) {
     const pageFiles = getAllComponentFiles(PAGES_DIR);
@@ -2271,6 +2523,8 @@ function scan() {
 
   const foundations = extractFoundations();
   foundations.icons = extractLucideIconsUsed(SRC_DIR);
+  // Phase E — Dark mode strategy
+  foundations.darkModeStrategy = detectDarkModeStrategy(PROJECT_ROOT);
   foundations.brand = { assets: extractBrandAssets() };
   const buttonUsage = extractButtonUsage();
   if (buttonUsage) {
@@ -2280,6 +2534,10 @@ function scan() {
   if (tokenUsage) {
     foundations.tokenUsage = tokenUsage;
   }
+  // Phase A — Color Intelligence
+  const colorTokenNames = Object.keys(foundations.colors || {}).filter(k => k !== "_dark");
+  const colorUsage = extractColorUsage(colorTokenNames);
+  if (colorUsage) foundations.colorUsage = colorUsage;
   const componentSuggestions = extractComponentSuggestions();
   const unreleasedSectionCandidates = extractUnreleasedSectionCandidates();
   const output = {

package/vds-core-template/story-generator.mjs

@@ -1792,6 +1792,138 @@ function buildRecipeStoryContent(comp, componentName, importPath, title, source,
     }
     lines.push(`};`);
   }
+
+  // --- Design Tokens story (same block as generateStoryFile) ---
+  {
+    const compTokens = Array.isArray(comp.tokens) ? comp.tokens : [];
+    const foundColors = FOUNDATIONS_DATA?.colors || {};
+    if (compTokens.length >= 3) {
+      const cleanTokens = compTokens.filter(t => !/:/.test(t));
+      const colorRaw      = cleanTokens.filter(t =>
+        /^(bg|text|border|ring|from|to|fill|stroke)-/.test(t) &&
+        !/^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|\d)/.test(t)
+      );
+      const spacingRaw    = cleanTokens.filter(t => /^(p[xylrbt]?-|m[xylrbt]?-|gap|space-[xy]|w-|h-|min-[wh]|max-[wh]|size-)/.test(t));
+      const typographyRaw = cleanTokens.filter(t => /^(text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl)|font-)/.test(t));
+      const radiusRaw     = cleanTokens.filter(t => /^rounded/.test(t));
+      const animRaw       = cleanTokens.filter(t => /^(transition|duration|animate|ease|delay)-/.test(t));
+      const resolvedColors = colorRaw.map(token => {
+        const m = token.match(/^(?:bg|text|border|ring|from|to|fill|stroke)-(.+)$/);
+        const key = m ? m[1] : null;
+        const baseKey = key ? key.replace(/\/[\d.]+$/, "") : null;
+        const entry = key ? (foundColors[key] || (baseKey !== key ? foundColors[baseKey] : null)) : null;
+        const isValidCssColor = (v) => /^#[0-9a-fA-F]{3,8}$/.test(v) || /^(rgb|rgba|hsl|hsla|oklch|oklab|lch|lab|color)\s*\(/.test(v) || v === 'transparent';
+        const hex = entry?.hex && isValidCssColor(entry.hex) ? entry.hex : null;
+        return { token, hex, label: baseKey || key };
+      });
+      const hasContent = resolvedColors.length > 0 || spacingRaw.length > 0 || typographyRaw.length > 0 || radiusRaw.length > 0 || animRaw.length > 0;
+      if (hasContent) {
+        lines.push("");
+        lines.push(`export const Tokens: Story = {`);
+        lines.push(`  name: "Design Tokens",`);
+        lines.push(`  parameters: { layout: "fullscreen" },`);
+        lines.push(`  render: () => {`);
+        lines.push(`    const colorTokens = ${JSON.stringify(resolvedColors)};`);
+        lines.push(`    const spacingTokens = ${JSON.stringify(spacingRaw)};`);
+        lines.push(`    const typographyTokens = ${JSON.stringify(typographyRaw)};`);
+        lines.push(`    const radiusTokens = ${JSON.stringify(radiusRaw)};`);
+        lines.push(`    const animationTokens = ${JSON.stringify(animRaw)};`);
+        lines.push(`    const chip = (label: string, bg: string, color: string) => (`);
+        lines.push(`      <span key={label} style={{ fontFamily: "monospace", fontSize: 11, background: bg, color, padding: "3px 9px", borderRadius: 5, border: \`1px solid \${bg === "#f9fafb" ? "#e5e7eb" : bg}\`, whiteSpace: "nowrap" as any }}>{label}</span>`);
+        lines.push(`    );`);
+        lines.push(`    const section = (title: string, children: any) => (`);
+        lines.push(`      <section style={{ marginBottom: 28 }}>`);
+        lines.push(`        <p style={{ margin: "0 0 10px", fontSize: 11, fontWeight: 700, color: "#6b7280", textTransform: "uppercase", letterSpacing: "0.08em" }}>{title}</p>`);
+        lines.push(`        {children}`);
+        lines.push(`      </section>`);
+        lines.push(`    );`);
+        lines.push(`    return (`);
+        lines.push(`      <div style={{ padding: 40, background: "#fff", fontFamily: "system-ui,sans-serif", color: "#111", minHeight: "100vh", width: "100%" }}>`);
+        lines.push(`        <h2 style={{ fontSize: 22, fontWeight: 700, margin: "0 0 6px" }}>Design Tokens</h2>`);
+        lines.push(`        <p style={{ fontSize: 13, color: "#6b7280", margin: "0 0 32px" }}>Tailwind utilities used in <code style={{ background: "#f3f4f6", padding: "1px 6px", borderRadius: 4, fontSize: 12 }}>${componentName}</code> — resolved to project values.</p>`);
+        lines.push(`        {colorTokens.length > 0 && section("Color", (`);
+        lines.push(`          <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>`);
+        lines.push(`            {colorTokens.map(({ token, hex, label }) => (`);
+        lines.push(`              <div key={token} style={{ display: "flex", alignItems: "center", gap: 7, padding: "7px 12px", border: "1px solid #e5e7eb", borderRadius: 8, background: "#f9fafb" }}>`);
+        lines.push(`                {hex && <span style={{ display: "inline-block", width: 16, height: 16, borderRadius: 4, background: hex, border: "1px solid rgba(0,0,0,0.1)", flexShrink: 0 }} />}`);
+        lines.push(`                <code style={{ fontSize: 12, color: "#374151", fontWeight: 600 }}>{token}</code>`);
+        lines.push(`                {hex && <span style={{ fontSize: 11, color: "#9ca3af" }}>{hex}</span>}`);
+        lines.push(`              </div>`);
+        lines.push(`            ))}`);
+        lines.push(`          </div>`);
+        lines.push(`        ))}`);
+        lines.push(`        {spacingTokens.length > 0 && section("Spacing", (`);
+        lines.push(`          <div style={{ display: "flex", flexWrap: "wrap", gap: 6 }}>{spacingTokens.map(t => chip(t, "#faf5ff", "#6d28d9"))}</div>`);
+        lines.push(`        ))}`);
+        lines.push(`        {typographyTokens.length > 0 && section("Typography", (`);
+        lines.push(`          <div style={{ display: "flex", flexWrap: "wrap", gap: 6 }}>{typographyTokens.map(t => chip(t, "#fffbeb", "#92400e"))}</div>`);
+        lines.push(`        ))}`);
+        lines.push(`        {radiusTokens.length > 0 && section("Border Radius", (`);
+        lines.push(`          <div style={{ display: "flex", gap: 16, flexWrap: "wrap", alignItems: "flex-end" }}>`);
+        lines.push(`            {radiusTokens.map(t => {`);
+        lines.push(`              const px = t === "rounded-none" ? 0 : t === "rounded-sm" ? 2 : t === "rounded" ? 4 : t === "rounded-md" ? 6 : t === "rounded-lg" ? 8 : t === "rounded-xl" ? 12 : t === "rounded-2xl" ? 16 : t === "rounded-3xl" ? 24 : t === "rounded-full" ? 9999 : 4;`);
+        lines.push(`              return (`);
+        lines.push(`                <div key={t} style={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 6 }}>`);
+        lines.push(`                  <div style={{ width: 44, height: 44, background: "#6366f1", borderRadius: px }} />`);
+        lines.push(`                  <code style={{ fontSize: 10, color: "#6b7280" }}>{t}</code>`);
+        lines.push(`                </div>`);
+        lines.push(`              );`);
+        lines.push(`            })}`);
+        lines.push(`          </div>`);
+        lines.push(`        ))}`);
+        lines.push(`        {animationTokens.length > 0 && section("Motion", (`);
+        lines.push(`          <div style={{ display: "flex", flexWrap: "wrap", gap: 6 }}>{animationTokens.map(t => chip(t, "#f0fdf4", "#166534"))}</div>`);
+        lines.push(`        ))}`);
+        lines.push(`      </div>`);
+        lines.push(`    );`);
+        lines.push(`  },`);
+        lines.push(`};`);
+      }
+    }
+    // Phase D2 — CSS Module Classes section
+    const cssModTokens = comp.cssModuleTokens || null;
+    if (cssModTokens && Array.isArray(cssModTokens.classNames) && cssModTokens.classNames.length > 0) {
+      lines.push("");
+      lines.push(`export const CssModuleClasses: Story = {`);
+      lines.push(`  name: "CSS Module Classes",`);
+      lines.push(`  parameters: { layout: "fullscreen" },`);
+      lines.push(`  render: () => {`);
+      lines.push(`    const classNames = ${JSON.stringify(cssModTokens.classNames)};`);
+      lines.push(`    const properties = ${JSON.stringify(cssModTokens.properties)};`);
+      lines.push(`    return (`);
+      lines.push(`      <div style={{ padding: 40, background: "#fff", fontFamily: "system-ui,sans-serif", color: "#111", minHeight: "100vh" }}>`);
+      lines.push(`        <h2 style={{ fontSize: 22, fontWeight: 700, margin: "0 0 6px" }}>CSS Module Classes</h2>`);
+      lines.push(`        <p style={{ fontSize: 13, color: "#6b7280", margin: "0 0 24px" }}>Classes from <code style={{ background: "#f3f4f6", padding: "1px 6px", borderRadius: 4, fontSize: 12 }}>.module.css</code> files imported by <code style={{ background: "#f3f4f6", padding: "1px 6px", borderRadius: 4, fontSize: 12 }}>${componentName}</code></p>`);
+      lines.push(`        <div style={{ display: "flex", flexWrap: "wrap", gap: 8, marginBottom: 32 }}>`);
+      lines.push(`          {classNames.map((cls: string) => (`);
+      lines.push(`            <span key={cls} style={{ fontFamily: "monospace", fontSize: 12, background: "#f0fdf4", color: "#166534", padding: "4px 10px", borderRadius: 6, border: "1px solid #bbf7d0" }}>source: CSS Module</span>`);
+      lines.push(`          ))}`);
+      lines.push(`          {classNames.map((cls: string) => (`);
+      lines.push(`            <code key={cls} style={{ fontSize: 12, background: "#f9fafb", color: "#374151", padding: "4px 10px", borderRadius: 6, border: "1px solid #e5e7eb" }}>.{cls}</code>`);
+      lines.push(`          ))}`);
+      lines.push(`        </div>`);
+      lines.push(`        {Object.entries(properties).length > 0 && (`);
+      lines.push(`          <div>`);
+      lines.push(`            <p style={{ fontSize: 11, fontWeight: 700, color: "#6b7280", textTransform: "uppercase", letterSpacing: "0.08em", marginBottom: 12 }}>Extracted Properties</p>`);
+      lines.push(`            <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>`);
+      lines.push(`              {Object.entries(properties).map(([prop, values]: [string, string[]]) => (`);
+      lines.push(`                <div key={prop} style={{ display: "flex", gap: 8, alignItems: "flex-start", padding: "8px 12px", border: "1px solid #e5e7eb", borderRadius: 6, background: "#f9fafb" }}>`);
+      lines.push(`                  <code style={{ fontSize: 11, color: "#6b7280", minWidth: 140, flexShrink: 0 }}>{prop}</code>`);
+      lines.push(`                  <div style={{ display: "flex", flexWrap: "wrap", gap: 4 }}>`);
+      lines.push(`                    {values.map((v: string) => <code key={v} style={{ fontSize: 11, background: "#fff", color: "#374151", padding: "1px 6px", borderRadius: 4, border: "1px solid #e5e7eb" }}>{v}</code>)}`);
+      lines.push(`                  </div>`);
+      lines.push(`                </div>`);
+      lines.push(`              ))}`);
+      lines.push(`            </div>`);
+      lines.push(`          </div>`);
+      lines.push(`        )}`);
+      lines.push(`      </div>`);
+      lines.push(`    );`);
+      lines.push(`  },`);
+      lines.push(`};`);
+    }
+  }
+
   return lines.join("\n");
 }
 
@@ -2115,42 +2247,46 @@ function buildStoryFileContent(comp) {
   // Component-specific stories for non-variant components (Input, Textarea, etc.)
   // Skip buildSpecialStories when multi-dimension detection found CVA dimensions —
   // generic detection produces better stories than hardcoded ones.
+  let generatedSpecialStories = false;
   if (!hasDimensions) {
     const specialStories = buildSpecialStories(componentName, variants);
     if (specialStories) {
       lines.push(specialStories);
-      return lines.join("\n");
+      generatedSpecialStories = true;
+      // Do NOT return here — fall through to Tokens + Usage stories below
     }
   }
 
-  // Profile-driven render + children — single source of truth via getStoryProfile()
-  const useSafeWrapper = profile === "SAFE";
-  const RenderTarget   = useSafeWrapper ? "SafeWrapper" : "ComponentRef";
-  const argsFallback   = !useSafeWrapper && (componentName && RENDER_ARGS_FALLBACKS[componentName]) || "";
-  const renderLine     = buildProfileRenderLine(profile, RenderTarget, argsFallback);
-  const childrenArgLine = buildProfileChildrenArgLine(profile);
+  if (!generatedSpecialStories) {
+    // Profile-driven render + children — single source of truth via getStoryProfile()
+    const useSafeWrapper = profile === "SAFE";
+    const RenderTarget   = useSafeWrapper ? "SafeWrapper" : "ComponentRef";
+    const argsFallback   = !useSafeWrapper && (componentName && RENDER_ARGS_FALLBACKS[componentName]) || "";
+    const renderLine     = buildProfileRenderLine(profile, RenderTarget, argsFallback);
+    const childrenArgLine = buildProfileChildrenArgLine(profile);
 
-  if (hasDimensions) {
-    const multiStories = buildMultiDimensionStories(
-      variantMap, renderLine, childrenArgLine, defaultArgLines, componentName,
-      comp.variantUsage || null
-    );
-    if (multiStories) {
-      lines.push(multiStories);
-    }
-  } else {
-    // No dimensions detected: single Default story
-    lines.push(`export const Default: Story = {`);
-    lines.push(renderLine);
-    const storyArgLines = [];
-    if (childrenArgLine(componentName)) storyArgLines.push(childrenArgLine(componentName));
-    for (const line of defaultArgLines) storyArgLines.push(line);
-    if (storyArgLines.length > 0) {
-      lines.push(`  args: {`);
-      for (const line of storyArgLines) lines.push(line);
-      lines.push(`  },`);
+    if (hasDimensions) {
+      const multiStories = buildMultiDimensionStories(
+        variantMap, renderLine, childrenArgLine, defaultArgLines, componentName,
+        comp.variantUsage || null
+      );
+      if (multiStories) {
+        lines.push(multiStories);
+      }
+    } else {
+      // No dimensions detected: single Default story
+      lines.push(`export const Default: Story = {`);
+      lines.push(renderLine);
+      const storyArgLines = [];
+      if (childrenArgLine(componentName)) storyArgLines.push(childrenArgLine(componentName));
+      for (const line of defaultArgLines) storyArgLines.push(line);
+      if (storyArgLines.length > 0) {
+        lines.push(`  args: {`);
+        for (const line of storyArgLines) lines.push(line);
+        lines.push(`  },`);
+      }
+      lines.push(`};`);
     }
-    lines.push(`};`);
   }
 
   // --- Project-specific usage stories ---
@@ -2190,7 +2326,7 @@ function buildStoryFileContent(comp) {
         /^(bg|text|border|ring|from|to|fill|stroke)-/.test(t) &&
         !/^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|\d)/.test(t)
       );
-      const spacingRaw    = cleanTokens.filter(t => /^(p[xylrbt]?|m[xylrbt]?|gap|space-[xy]|w-|h-|min-[wh]|max-[wh]|size-)/.test(t));
+      const spacingRaw    = cleanTokens.filter(t => /^(p[xylrbt]?-|m[xylrbt]?-|gap|space-[xy]|w-|h-|min-[wh]|max-[wh]|size-)/.test(t));
       const typographyRaw = cleanTokens.filter(t => /^(text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl)|font-)/.test(t));
       const radiusRaw     = cleanTokens.filter(t => /^rounded/.test(t));
       const animRaw       = cleanTokens.filter(t => /^(transition|duration|animate|ease|delay)-/.test(t));
@@ -2271,6 +2407,48 @@ function buildStoryFileContent(comp) {
         lines.push(`};`);
       }
     }
+    // Phase D2 — CSS Module Classes section
+    const cssModTokens = comp.cssModuleTokens || null;
+    if (cssModTokens && Array.isArray(cssModTokens.classNames) && cssModTokens.classNames.length > 0) {
+      lines.push("");
+      lines.push(`export const CssModuleClasses: Story = {`);
+      lines.push(`  name: "CSS Module Classes",`);
+      lines.push(`  parameters: { layout: "fullscreen" },`);
+      lines.push(`  render: () => {`);
+      lines.push(`    const classNames = ${JSON.stringify(cssModTokens.classNames)};`);
+      lines.push(`    const properties = ${JSON.stringify(cssModTokens.properties)};`);
+      lines.push(`    return (`);
+      lines.push(`      <div style={{ padding: 40, background: "#fff", fontFamily: "system-ui,sans-serif", color: "#111", minHeight: "100vh" }}>`);
+      lines.push(`        <h2 style={{ fontSize: 22, fontWeight: 700, margin: "0 0 6px" }}>CSS Module Classes</h2>`);
+      lines.push(`        <p style={{ fontSize: 13, color: "#6b7280", margin: "0 0 24px" }}>Classes from <code style={{ background: "#f3f4f6", padding: "1px 6px", borderRadius: 4, fontSize: 12 }}>.module.css</code> files imported by <code style={{ background: "#f3f4f6", padding: "1px 6px", borderRadius: 4, fontSize: 12 }}>${componentName}</code></p>`);
+      lines.push(`        <div style={{ display: "flex", flexWrap: "wrap", gap: 8, marginBottom: 32 }}>`);
+      lines.push(`          {classNames.map((cls: string) => (`);
+      lines.push(`            <span key={cls} style={{ fontFamily: "monospace", fontSize: 12, background: "#f0fdf4", color: "#166534", padding: "4px 10px", borderRadius: 6, border: "1px solid #bbf7d0" }}>source: CSS Module</span>`);
+      lines.push(`          ))}`);
+      lines.push(`          {classNames.map((cls: string) => (`);
+      lines.push(`            <code key={cls} style={{ fontSize: 12, background: "#f9fafb", color: "#374151", padding: "4px 10px", borderRadius: 6, border: "1px solid #e5e7eb" }}>.{cls}</code>`);
+      lines.push(`          ))}`);
+      lines.push(`        </div>`);
+      lines.push(`        {Object.entries(properties).length > 0 && (`);
+      lines.push(`          <div>`);
+      lines.push(`            <p style={{ fontSize: 11, fontWeight: 700, color: "#6b7280", textTransform: "uppercase", letterSpacing: "0.08em", marginBottom: 12 }}>Extracted Properties</p>`);
+      lines.push(`            <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>`);
+      lines.push(`              {Object.entries(properties).map(([prop, values]: [string, string[]]) => (`);
+      lines.push(`                <div key={prop} style={{ display: "flex", gap: 8, alignItems: "flex-start", padding: "8px 12px", border: "1px solid #e5e7eb", borderRadius: 6, background: "#f9fafb" }}>`);
+      lines.push(`                  <code style={{ fontSize: 11, color: "#6b7280", minWidth: 140, flexShrink: 0 }}>{prop}</code>`);
+      lines.push(`                  <div style={{ display: "flex", flexWrap: "wrap", gap: 4 }}>`);
+      lines.push(`                    {values.map((v: string) => <code key={v} style={{ fontSize: 11, background: "#fff", color: "#374151", padding: "1px 6px", borderRadius: 4, border: "1px solid #e5e7eb" }}>{v}</code>)}`);
+      lines.push(`                  </div>`);
+      lines.push(`                </div>`);
+      lines.push(`              ))}`);
+      lines.push(`            </div>`);
+      lines.push(`          </div>`);
+      lines.push(`        )}`);
+      lines.push(`      </div>`);
+      lines.push(`    );`);
+      lines.push(`  },`);
+      lines.push(`};`);
+    }
   }
 
   // --- Usage story ---
@@ -2502,7 +2680,8 @@ function writeFoundationsStories(foundations, components) {
           const hex = c?.hex || c?.value || "";
           const u = colorUsage[name] || null;
           return { name, hex, cssVar: `--${name}`, description: DESCRIPTIONS[name] || "", usage: u };
-        });
+        })
+        .sort((a, b) => (b.usage?.total || 0) - (a.usage?.total || 0));
       return { key: group.key, label: group.label, colors };
     }).filter((g) => g.colors.length > 0);
 
@@ -2566,6 +2745,11 @@ function writeFoundationsStories(foundations, components) {
       "                        ×{usage.total}",
       "                      </span>",
       "                    )}",
+      "                  {usage && usage.dark > 0 && (",
+      "                      <span style={{ position: \"absolute\", top: 8, left: 8, fontSize: 9, fontWeight: 700, padding: \"2px 6px\", borderRadius: 99, background: \"rgba(109,40,217,0.85)\", color: \"#fff\", backdropFilter: \"blur(2px)\" }}>",
+      "                        dark ×{usage.dark}",
+      "                      </span>",
+      "                    )}",
       "                  </div>",
       "                  {/* Info */}",
       "                  <div style={{ padding: \"12px 14px\" }}>",
@@ -2617,6 +2801,74 @@ function writeFoundationsStories(foundations, components) {
       "    </div>",
       "  ),",
       "};",
+      "",
+      "export const UsedOnly: Story = {",
+      "  name: \"Used Colors\",",
+      "  render: () => {",
+      `    const usedGroups = colorGroups.map(g => ({ ...g, colors: g.colors.filter(c => c.usage && c.usage.total > 0) })).filter(g => g.colors.length > 0);`,
+      "    return (",
+      "    <div style={{ fontFamily: \"system-ui,sans-serif\", padding: 32, background: \"#fff\", minHeight: \"100vh\", width: \"100%\", color: \"#111\" }}>",
+      "      <h2 style={{ fontSize: 20, fontWeight: 700, margin: \"0 0 4px\" }}>Used Colors</h2>",
+      "      <p style={{ fontSize: 13, color: \"#888\", margin: \"0 0 40px\" }}>Only colors actually used in source — sorted by usage frequency</p>",
+      "      {usedGroups.map(group => (",
+      "        <div key={group.key} style={{ marginBottom: 40 }}>",
+      "          <h3 style={{ fontSize: 14, fontWeight: 700, textTransform: \"uppercase\", letterSpacing: \"0.08em\", color: \"#6b7280\", margin: \"0 0 16px\", borderBottom: \"1px solid #e5e7eb\", paddingBottom: 8 }}>{group.label}</h3>",
+      "          <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 12 }}>",
+      "            {group.colors.map(({ name, hex, usage }) => (",
+      "              <div key={name} style={{ display: \"flex\", flexDirection: \"column\", gap: 4, width: 80 }}>",
+      "                <div style={{ width: 80, height: 48, borderRadius: 8, background: hex, border: \"1px solid #e5e7eb\" }} />",
+      "                <code style={{ fontSize: 10, color: \"#374151\", wordBreak: \"break-all\" as any }}>{name}</code>",
+      "                <span style={{ fontSize: 10, color: \"#6b7280\" }}>×{usage?.total}</span>",
+      "              </div>",
+      "            ))}",
+      "          </div>",
+      "        </div>",
+      "      ))}",
+      "      {usedGroups.length === 0 && <p style={{ color: \"#9ca3af\", fontSize: 14 }}>No colorUsage data — run scan.mjs to generate.</p>}",
+      "    </div>",
+      "    );",
+      "  },",
+      "};",
+      "",
+      "export const ColorUsageByComponent: Story = {",
+      "  name: \"Component → Color\",",
+      "  render: () => {",
+      "    // Build reverse map: component → colors used",
+      "    const compMap: Record<string, {name:string;hex:string;total:number}[]> = {};",
+      "    for (const group of colorGroups) {",
+      "      for (const { name, hex, usage } of group.colors) {",
+      "        if (!usage || usage.total === 0) continue;",
+      "        for (const comp of (usage.topFiles || [])) {",
+      "          if (!compMap[comp]) compMap[comp] = [];",
+      "          if (!compMap[comp].find(c => c.name === name)) compMap[comp].push({ name, hex, total: usage.total });",
+      "        }",
+      "      }",
+      "    }",
+      "    const compEntries = Object.entries(compMap).sort((a,b) => b[1].length - a[1].length).slice(0, 30);",
+      "    return (",
+      "    <div style={{ fontFamily: \"system-ui,sans-serif\", padding: 32, background: \"#fff\", minHeight: \"100vh\", width: \"100%\", color: \"#111\" }}>",
+      "      <h2 style={{ fontSize: 20, fontWeight: 700, margin: \"0 0 4px\" }}>Component → Color</h2>",
+      "      <p style={{ fontSize: 13, color: \"#888\", margin: \"0 0 32px\" }}>Which components use which color tokens</p>",
+      "      <div style={{ display: \"flex\", flexDirection: \"column\", gap: 16 }}>",
+      "        {compEntries.map(([comp, colors]) => (",
+      "          <div key={comp} style={{ padding: \"14px 18px\", border: \"1px solid #e5e7eb\", borderRadius: 10, background: \"#f9fafb\" }}>",
+      "            <div style={{ fontSize: 13, fontWeight: 700, color: \"#111\", marginBottom: 10, fontFamily: \"monospace\" }}>{comp}</div>",
+      "            <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 6 }}>",
+      "              {colors.map(({ name, hex }) => (",
+      "                <div key={name} style={{ display: \"flex\", alignItems: \"center\", gap: 5, background: \"#fff\", border: \"1px solid #e5e7eb\", borderRadius: 6, padding: \"3px 9px\" }}>",
+      "                  <span style={{ display: \"inline-block\", width: 10, height: 10, borderRadius: 2, background: hex, border: \"1px solid rgba(0,0,0,0.1)\", flexShrink: 0 }} />",
+      "                  <code style={{ fontSize: 11, color: \"#374151\" }}>{name}</code>",
+      "                </div>",
+      "              ))}",
+      "            </div>",
+      "          </div>",
+      "        ))}",
+      "        {compEntries.length === 0 && <p style={{ color: \"#9ca3af\", fontSize: 14 }}>No colorUsage data — run scan.mjs to generate.</p>}",
+      "      </div>",
+      "    </div>",
+      "    );",
+      "  },",
+      "};",
     ].join("\n");
 
     fs.writeFileSync(path.join(foundationsDir, "Colors.stories.tsx"), colorsContent, "utf-8");
@@ -2708,6 +2960,9 @@ function writeFoundationsStories(foundations, components) {
       ? `'${typo.arbitraryFonts[0]}', sans-serif` : null;
     const sansFamily = typo.fontSans || typo.body || firstArbitraryFont || typo.tailwindSans || "system-ui, sans-serif";
 
+    const fontFaces = Array.isArray(typo.fontFaces) ? typo.fontFaces : [];
+    const nextFonts = Array.isArray(typo.nextFonts) ? typo.nextFonts : [];
+
     const typoContent = [
       "import React from \"react\";",
       "import type { Meta, StoryObj } from \"@storybook/react\";",
@@ -2723,6 +2978,8 @@ function writeFoundationsStories(foundations, components) {
       `const weightRows: { token: string; value: string }[] = ${JSON.stringify(weightRows)};`,
       `const weightRowsIsDefault: boolean = ${weightRowsIsDefault};`,
       `const sansFamily = ${JSON.stringify(sansFamily)};`,
+      `const fontFamilyRows: { token: string; value: string }[] = ${JSON.stringify(familyRows)};`,
+      `const fontSourceRows: { type: string; family: string; weight: string | null; isVariable: boolean; variable: string | null }[] = ${JSON.stringify([...fontFaces.map(f => ({ type: "css", family: f.family, weight: f.weight, isVariable: f.isVariable, variable: null })), ...nextFonts.map(f => ({ type: "next", family: f.family, weight: null, isVariable: false, variable: f.variable }))])};`,
       "",
       "export const Default: Story = {",
       "  render: () => (",
@@ -2801,6 +3058,26 @@ function writeFoundationsStories(foundations, components) {
       "        </>",
       "      )}",
       "",
+      "      {/* Phase B4 — Letter Specimens */}",
+      "      {fontFamilyRows.length > 0 && (",
+      "        <div style={{ marginBottom: 48 }}>",
+      "          <h3 style={{ fontSize: 14, fontWeight: 700, textTransform: \"uppercase\", letterSpacing: \"0.08em\", color: \"#6b7280\", margin: \"0 0 24px\", borderBottom: \"1px solid #e5e7eb\", paddingBottom: 8 }}>Letter Specimens</h3>",
+      "          <div style={{ display: \"flex\", flexDirection: \"column\", gap: 32 }}>",
+      "            {fontFamilyRows.map(({ token, value }) => {",
+      "              const family = value.split(',')[0].trim().replace(/['\\\"/]/g, '');",
+      "              return (",
+      "                <div key={token} style={{ padding: 24, border: \"1px solid #e5e7eb\", borderRadius: 12, background: \"#fafafa\" }}>",
+      "                  <div style={{ fontSize: 11, fontWeight: 600, color: \"#9ca3af\", marginBottom: 12, textTransform: \"uppercase\", letterSpacing: \"0.08em\", fontFamily: \"system-ui\" }}>{token} — {value.length > 50 ? value.slice(0,50)+'…' : value}</div>",
+      "                  <div style={{ fontFamily: value, fontSize: 48, fontWeight: 700, color: \"#111\", lineHeight: 1.1, marginBottom: 8 }}>Aa Bb Cc</div>",
+      "                  <div style={{ fontFamily: value, fontSize: 18, color: \"#374151\", lineHeight: 1.6, marginBottom: 8 }}>The quick brown fox jumps over the lazy dog</div>",
+      "                  <div style={{ fontFamily: value, fontSize: 14, color: \"#6b7280\", letterSpacing: \"0.1em\" }}>0123456789 ! @ # $ %</div>",
+      "                </div>",
+      "              );",
+      "            })}",
+      "          </div>",
+      "        </div>",
+      "      )}",
+      "",
       "      {/* ── FONT WEIGHTS ── */}",
       "      {weightRowsIsDefault && <p style={{ fontSize: 12, color: \"#92400e\", background: \"#fef3c7\", border: \"1px solid #fde68a\", borderRadius: 6, padding: \"6px 12px\", marginBottom: 12, display: \"inline-block\" }}>ℹ️ Tailwind defaults — no custom font weights found in this project</p>}",
       "      {weightRows.length > 0 && (",
@@ -2819,6 +3096,21 @@ function writeFoundationsStories(foundations, components) {
       "          </div>",
       "        </>",
       "      )}",
+      "      {fontSourceRows.length > 0 && (",
+      "        <div style={{ marginBottom: 48 }}>",
+      "          <h3 style={{ fontSize: 14, fontWeight: 700, textTransform: \"uppercase\", letterSpacing: \"0.08em\", color: \"#6b7280\", margin: \"0 0 16px\", borderBottom: \"1px solid #e5e7eb\", paddingBottom: 8 }}>Font Sources</h3>",
+      "          <div style={{ display: \"flex\", flexDirection: \"column\", gap: 8 }}>",
+      "            {fontSourceRows.map((f, i) => (",
+      "              <div key={i} style={{ display: \"flex\", alignItems: \"center\", gap: 12, padding: \"10px 16px\", border: \"1px solid #e5e7eb\", borderRadius: 8, background: \"#f9fafb\" }}>",
+      "                <span style={{ fontSize: 10, fontWeight: 700, padding: \"2px 7px\", borderRadius: 4, background: f.type === 'next' ? '#dbeafe' : '#d1fae5', color: f.type === 'next' ? '#1e40af' : '#065f46' }}>{f.type === 'next' ? 'next/font' : '@font-face'}</span>",
+      "                <code style={{ fontSize: 12, fontWeight: 600, color: \"#111\" }}>{f.family}</code>",
+      "                {f.isVariable && <span style={{ fontSize: 10, padding: \"2px 7px\", borderRadius: 4, background: \"#fef9c3\", color: \"#854d0e\" }}>variable {f.weight}</span>}",
+      "                {f.variable && <code style={{ fontSize: 10, color: \"#9ca3af\" }}>{f.variable}</code>}",
+      "              </div>",
+      "            ))}",
+      "          </div>",
+      "        </div>",
+      "      )}",
       "    </div>",
       "  ),",
       "};",