vibe-design-system 2.8.82 → 2.9.1

package/bin/init.js

@@ -24,6 +24,7 @@ const TEMPLATE_DIR = path.join(INSTALLER_ROOT, "vds-core-template");
 const STORYBOOK_MAIN_TS = `import type { StorybookConfig } from "@storybook/react-vite";
 import { mergeConfig } from "vite";
 import path from "path";
+import fs from "fs";
 
 const config: StorybookConfig = {
   stories: ["../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
@@ -33,10 +34,48 @@ 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"),
+        ];
+        for (const tcp of tsConfigPaths) {
+          if (!fs.existsSync(tcp)) continue;
+          const raw = JSON.parse(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, {
+      plugins: [
+        {
+          // Mock figma:asset/* imports — returns empty string so components render without crashing in Storybook
+          name: "vds-figma-asset-mock",
+          enforce: "pre" as const,
+          resolveId(id: string) {
+            if (id.startsWith("figma:asset")) return "\\0vds-figma-asset-mock";
+          },
+          load(id: string) {
+            if (id === "\\0vds-figma-asset-mock") return "export default '';";
+          },
+        },
+      ],
       resolve: {
         alias: {
           "@": path.resolve(process.cwd(), "src"),
+          ...extraAliases,
         },
       },
     });
@@ -241,12 +280,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 +306,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";
 
@@ -286,6 +377,7 @@ export default config;
   return `import type { StorybookConfig } from "@storybook/react-vite";
 import { mergeConfig } from "vite";
 import path from "path";
+import fs from "fs";
 
 const config: StorybookConfig = {
   stories: [
@@ -297,10 +389,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 (!fs.existsSync(tcp)) continue;
+          const raw = JSON.parse(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 +791,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.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.warn(`   → ${rel}`);
+    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.82",
+  "version": "2.9.1",
   "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,
@@ -1145,6 +1145,8 @@ function extractTailwindTokens(content) {
     /className\s*=\s*\{\s*["'`]([^"'`]+)["'`]/g,
     /cn\s*\(\s*["'`]([^"'`]+)["'`]/g,
     /cva\s*\(\s*["'`]([^"'`]+)["'`]/g,
+    // CVA variant values: captures `default: "bg-x text-y"`, `destructive: "border-x..."` etc.
+    /\b\w+\s*:\s*["'`]([a-zA-Z0-9_\-\/\s\[\]&>:%.]+)["'`]/g,
     /["'`]([a-zA-Z0-9_\-\/\s\[\]&:%.]+(?:hover|focus|active|disabled|sm|md|lg|xl|2xl|dark:)[a-zA-Z0-9_\-\/\s\[\]&:%.]*)["'`]/g,
   ];
   for (const re of patterns) {
@@ -1393,6 +1395,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,6 +1483,22 @@ function extractFoundations() {
         }
       }
 
+      // 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 =
@@ -1975,6 +2045,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,
@@ -2108,6 +2213,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);
@@ -2166,6 +2353,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">).
@@ -2241,6 +2472,26 @@ function isComplexPageComponent(content) {
   return true;
 }
 
+/**
+ * Extract top-level (no indentation) PascalCase component names from a source file.
+ * Used for isPageComponent files to find internal sub-components that can be auto-exported.
+ * Only matches declarations at column 0 (^) to exclude nested arrow functions.
+ */
+function extractTopLevelInternalComponentNames(content) {
+  // Match only unindented `const ComponentName = (` or `const ComponentName: React.FC = (`
+  const re = /^(?:export\s+)?const\s+([A-Z][A-Za-z0-9]+)\s*[:=]\s*(?:\(|\bReact\.)/gm;
+  const names = [];
+  const seen = new Set();
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    if (!seen.has(m[1])) {
+      seen.add(m[1]);
+      names.push(m[1]);
+    }
+  }
+  return names;
+}
+
 function scan() {
   const relativeFiles = COMPONENTS_DIR ? getAllComponentFiles(COMPONENTS_DIR) : [];
   if (!COMPONENTS_DIR) {
@@ -2266,7 +2517,14 @@ function scan() {
     }
     const tokens = extractTailwindTokens(content);
     const isPageComponent = isComplexPageComponent(content);
-    results.push({ file: rel, name, group, category, description, tokens, ...(isPageComponent ? { isPageComponent: true } : {}) });
+    const internalComponentNames = isPageComponent
+      ? extractTopLevelInternalComponentNames(content).filter(n => n !== name)
+      : undefined;
+    const comp = { file: rel, name, group, category, description, tokens, ...(isPageComponent ? { isPageComponent: true, internalComponentNames } : {}) };
+    // 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);
@@ -2290,6 +2548,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) {
@@ -2299,6 +2559,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

@@ -1880,6 +1880,48 @@ function buildRecipeStoryContent(comp, componentName, importPath, title, source,
         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");
@@ -2166,8 +2208,11 @@ function buildStoryFileContent(comp) {
   lines.push(`  component: ComponentRef,`);
   // SECTION: no props/args → autodocs tries to render React.lazy without Suspense → useRef crash
   if (profile !== "SECTION") lines.push(`  tags: ["autodocs"],`);
-  // Center small components (VARIANT, WRAPPER, CONFIGURED, SAFE) to prevent vertical stretching
-  if (profile !== "SECTION") lines.push(`  parameters: { layout: "centered" },`);
+  // Center small components; fullscreen for complex page-level components
+  if (profile !== "SECTION") {
+    const layout = comp.isPageComponent ? "fullscreen" : "centered";
+    lines.push(`  parameters: { layout: "${layout}" },`);
+  }
   // Wrap with QueryClientProvider for components that use @tanstack/react-query hooks
   if (needsQueryClient) {
     lines.push(`  decorators: [(Story: any) => React.createElement(QueryClientProvider, { client: _queryClient }, React.createElement(Story))],`);
@@ -2365,6 +2410,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 ---
@@ -2596,7 +2683,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);
 
@@ -2660,6 +2748,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\" }}>",
@@ -2711,6 +2804,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");
@@ -2802,6 +2963,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\";",
@@ -2817,6 +2981,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: () => (",
@@ -2895,6 +3061,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 && (",
@@ -2913,6 +3099,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>",
       "  ),",
       "};",
@@ -5002,11 +5203,8 @@ function main() {
     const storyFileName = `${componentName}.stories.tsx`;
     const storyPath = path.join(STORIES_DIR, storyFileName);
     if (SKIP_LIST.includes(componentName)) continue;
-    // Skip complex page-level components detected by scan (500+ lines, 4+ inline sub-components)
-    if (comp.isPageComponent) {
-      console.log(`[VDS] ${componentName} → skipped (complex page component — add to extraSkipList to suppress this message)`);
-      continue;
-    }
+    // Complex page-level components (500+ lines, 4+ inline sub-components) — generate fullscreen story instead of skipping
+    // (Previously skipped; now a simplified fullscreen story is generated so they appear in Storybook)
     const requiredCount = Array.isArray(comp.props) ? comp.props.filter((p) => p.required === true).length : 0;
     if (requiredCount > 3) {
       console.log(`[VDS] ${componentName} → skipped (${requiredCount} required props — too complex to auto-generate)`);
@@ -5026,6 +5224,12 @@ function main() {
     writtenCount++;
   }
 
+  // Phase I — Internal component sub-stories for isPageComponent files
+  for (const comp of components) {
+    if (!comp.isPageComponent || !Array.isArray(comp.internalComponentNames) || comp.internalComponentNames.length === 0) continue;
+    generateInternalComponentStories(comp);
+  }
+
   // Summary
   if (writtenCount === 0 && components.length > 0) {
     const hasShadcnGroup = components.some(c => {
@@ -5042,5 +5246,264 @@ function main() {
   }
 }
 
+// ─── Phase I: Internal Component Sub-Story Engine ─────────────────────────────
+/**
+ * Adds `export` to top-level internal component declarations in a source file.
+ * Non-destructive: only adds `export` keyword, no logic changes.
+ * Returns the list of names that were newly exported.
+ */
+function autoExportInternalComponents(sourceFilePath, names) {
+  let src = fs.readFileSync(sourceFilePath, "utf-8");
+  const newly = [];
+  for (const n of names) {
+    // Already exported? skip
+    if (new RegExp(`^export\\s+const\\s+${n}\\b`, "m").test(src)) continue;
+    // Exists as unexported top-level const?
+    const re = new RegExp(`^(const\\s+${n}\\b)`, "m");
+    if (!re.test(src)) continue;
+    src = src.replace(re, "export $1");
+    newly.push(n);
+  }
+  if (newly.length > 0) fs.writeFileSync(sourceFilePath, src, "utf-8");
+  return newly;
+}
+
+/**
+ * Parse top-level relative import statements (local files only).
+ * Returns [{importPath, symbols}]
+ */
+function parseLocalDataImports(content) {
+  const re = /^import\s*\{([^}]+)\}\s*from\s*["'](\.[^"']+)["']/gm;
+  const results = [];
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const symbols = m[1].split(",").map(s => s.trim().replace(/\s+as\s+\w+$/, "").trim()).filter(Boolean);
+    results.push({ importPath: m[2], symbols });
+  }
+  return results;
+}
+
+/**
+ * Detect named exports from a data file: returns { exportName → 'array' | 'object' | 'scalar' }
+ */
+function parseDataFileExports(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const src = fs.readFileSync(filePath, "utf-8");
+  const result = {};
+  const re = /^export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*[=:]/gm;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    const name = m[1];
+    const afterIdx = src.indexOf("=", m.index) + 1;
+    const afterSlice = src.slice(afterIdx, afterIdx + 10).trimStart();
+    result[name] = afterSlice.startsWith("[") ? "array" : afterSlice.startsWith("{") ? "object" : "scalar";
+  }
+  return result;
+}
+
+/**
+ * Extract inline TypeScript prop types for a named component from source content.
+ * Handles: `const Foo = ({ a, b }: { a: boolean; b: string }) =>`
+ * Handles nested object types (e.g., `data: { subStation: SubStation; } | null`)
+ * Returns [{name, type}]
+ */
+function extractComponentProps(content, componentName) {
+  const esc = componentName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const declRe = new RegExp(`(?:export\\s+)?const\\s+${esc}\\s*[:=]\\s*\\(`, "g");
+  const declMatch = declRe.exec(content);
+  if (!declMatch) return [];
+  const slice = content.slice(declMatch.index, declMatch.index + 5000);
+  // Find `}: {` — start of inline type annotation
+  const typeHeaderIdx = slice.search(/\}\s*:\s*\{/);
+  if (typeHeaderIdx === -1) return [];
+  const braceStart = slice.indexOf("{", typeHeaderIdx);
+  // Walk forward tracking brace depth to find the matching closing brace
+  let depth = 0, braceEnd = -1;
+  for (let i = braceStart; i < slice.length; i++) {
+    if (slice[i] === "{") depth++;
+    else if (slice[i] === "}") { depth--; if (depth === 0) { braceEnd = i; break; } }
+  }
+  if (braceEnd === -1) return [];
+  const typeBody = slice.slice(braceStart + 1, braceEnd);
+  // Smart prop parser: tracks depth so `;` inside nested types is skipped
+  const props = [];
+  let i = 0;
+  while (i < typeBody.length) {
+    while (i < typeBody.length && /\s/.test(typeBody[i])) i++;
+    if (i >= typeBody.length) break;
+    const nameMatch = typeBody.slice(i).match(/^(\w+)\??(\s*:\s*)/);
+    if (!nameMatch) { i++; continue; }
+    const propName = nameMatch[1];
+    i += nameMatch[0].length;
+    let typeDepth = 0;
+    const typeStartIdx = i;
+    while (i < typeBody.length) {
+      const ch = typeBody[i];
+      if ("{([<".includes(ch)) typeDepth++;
+      // `>` only closes angle brackets (generics), not `=>` arrow functions
+      else if ("})]".includes(ch) || (ch === ">" && typeDepth > 0)) typeDepth--;
+      else if (ch === ";" && typeDepth === 0) break;
+      i++;
+    }
+    const type = typeBody.slice(typeStartIdx, i).trim();
+    if (propName && type && !propName.startsWith("//") && propName !== "readonly") {
+      props.push({ name: propName, type });
+    }
+    i++; // skip `;`
+  }
+  return props;
+}
+
+/**
+ * Generate a mock value string for a TypeScript type, using available data exports.
+ */
+function mockValueForType(type, localExports) {
+  const t = type.trim();
+  if (t === "boolean") return "false";
+  if (t === "string") return '""';
+  if (t === "number") return "0";
+  if (t === "null" || t === "undefined") return "null";
+  if (t.startsWith("() =>") || t === "VoidFunction") return "() => {}";
+  if (t.startsWith("(") && t.includes("=>")) return "() => {}";
+  // Inline object type → null (complex; user fills it in)
+  if (t.startsWith("{")) return "null";
+  // Union ending in null/undefined → null
+  if (t.endsWith("| null") || t.endsWith("| undefined") || t.startsWith("null |")) return "null";
+  // String literal union → pick first quoted value
+  const firstLiteral = t.match(/["']([^"']+)["']/);
+  if (firstLiteral && (t.startsWith('"') || t.startsWith("'"))) return `"${firstLiteral[1]}"`;
+
+  // Try matching named type to available array exports
+  // Strip common suffixes to get the "base" name (e.g., RouteDef→route, SubStation→substation)
+  const typeLower = t.toLowerCase().replace(/def$|id$|key$|type$|interface$|kind$/i, "");
+  if (typeLower.length >= 3) {
+    for (const [expName, expKind] of Object.entries(localExports)) {
+      if (expKind !== "array") continue;
+      const expBase = expName.toLowerCase().replace(/_/g, "").replace(/s$/, "").replace(/data$/, "");
+      // Direct match: RouteDef → ROUTES (routedef→rout vs routes→rout)
+      if (expBase.slice(0, 4) === typeLower.slice(0, 4) || typeLower.slice(0, 4) === expBase.slice(0, 4)) {
+        return `${expName}[0]`;
+      }
+    }
+  }
+  return "undefined as any";
+}
+
+/**
+ * Build the story file content for a single internal component.
+ */
+function buildInternalComponentStoryContent(compName, parentImportPath, dataImportPath, dataSymbols, localExports, props, parentComp) {
+  const lines = [];
+  lines.push(`// @vds-regenerate — VDS auto-generated. Remove this line to prevent overwrite.`);
+  lines.push(`import React from "react";`);
+  lines.push(`import type { Meta, StoryObj } from "@storybook/react";`);
+  lines.push(`import { ${compName} } from "${parentImportPath}";`);
+  if (dataImportPath && dataSymbols.length > 0) {
+    lines.push(`import { ${dataSymbols.join(", ")} } from "${dataImportPath}";`);
+  }
+  lines.push(``);
+  lines.push(`/**`);
+  lines.push(` * **${compName}** — sub-component of ${parentComp.name}.`);
+  lines.push(` * Auto-exported by VDS for isolated Storybook documentation.`);
+  lines.push(` */`);
+  lines.push(`const meta: Meta<typeof ${compName}> = {`);
+  lines.push(`  title: "${parentComp.group || "Screens"}/${parentComp.name}/${compName}",`);
+  lines.push(`  component: ${compName},`);
+  lines.push(`  parameters: {`);
+  lines.push(`    layout: "centered",`);
+  lines.push(`    backgrounds: { default: "dark" },`);
+  lines.push(`  },`);
+  lines.push(`};`);
+  lines.push(`export default meta;`);
+  lines.push(`type Story = StoryObj<typeof meta>;`);
+  lines.push(``);
+
+  if (props.length > 0) {
+    const argLines = props.map(p => `    ${p.name}: ${mockValueForType(p.type, localExports)},`).join("\n");
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(argLines);
+    lines.push(`  },`);
+    lines.push(`};`);
+  } else {
+    lines.push(`export const Default: Story = {};`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Main orchestrator: auto-exports internal components + generates individual story files.
+ * Called for each comp with isPageComponent: true.
+ */
+function generateInternalComponentStories(comp) {
+  const names = comp.internalComponentNames || [];
+  if (names.length === 0) return;
+
+  // Locate the source file (COMPONENTS_REL_DIR is a module-level variable set in main())
+  const sourceFile = path.join(PROJECT_ROOT, COMPONENTS_REL_DIR, comp.file);
+  if (!fs.existsSync(sourceFile)) return;
+
+  const sourceContent = fs.readFileSync(sourceFile, "utf-8");
+
+  // Step 1: Auto-export internal components
+  const newly = autoExportInternalComponents(sourceFile, names);
+  if (newly.length > 0) {
+    console.log(`[VDS] ${comp.name} → auto-exported ${newly.length} sub-components: ${newly.join(", ")}`);
+  }
+
+  // Step 2: Find best local data import (most array-typed exports)
+  const localImports = parseLocalDataImports(sourceContent);
+  let bestImportPath = null;
+  let bestSymbols = [];
+  let bestExports = {};
+  for (const li of localImports) {
+    const resolved = path.resolve(path.dirname(sourceFile), li.importPath);
+    const exts = ["", ".ts", ".tsx", ".js", ".jsx"];
+    let found = null;
+    for (const ext of exts) {
+      const p = resolved + ext;
+      if (fs.existsSync(p)) { found = p; break; }
+    }
+    if (!found) continue;
+    const exports = parseDataFileExports(found);
+    const arrayCount = Object.values(exports).filter(k => k === "array").length;
+    if (arrayCount > Object.values(bestExports).filter(k => k === "array").length) {
+      bestImportPath = li.importPath;
+      bestSymbols = li.symbols;
+      bestExports = exports;
+    }
+  }
+
+  // Step 3: Compute import paths relative to STORIES_DIR
+  const storiesRelToSource = path.relative(path.dirname(sourceFile), path.join(PROJECT_ROOT, "src", "stories"));
+  const sourceRelFromStories = path.relative(
+    path.join(PROJECT_ROOT, "src", "stories"),
+    sourceFile.replace(/\.(tsx?|jsx?)$/, "")
+  ).replace(/\\/g, "/");
+  const parentImportPath = sourceRelFromStories.startsWith(".") ? sourceRelFromStories : "./" + sourceRelFromStories;
+
+  let dataImportFromStories = null;
+  if (bestImportPath) {
+    const dataAbsolute = path.resolve(path.dirname(sourceFile), bestImportPath);
+    dataImportFromStories = path.relative(
+      path.join(PROJECT_ROOT, "src", "stories"),
+      dataAbsolute
+    ).replace(/\\/g, "/").replace(/\.(tsx?|jsx?)$/, "");
+    if (!dataImportFromStories.startsWith(".")) dataImportFromStories = "./" + dataImportFromStories;
+  }
+
+  // Step 4: Generate individual story files
+  for (const name of names) {
+    const storyFile = path.join(STORIES_DIR, `${name}.stories.tsx`);
+    if (fs.existsSync(storyFile)) continue; // Never overwrite existing stories
+    const props = extractComponentProps(sourceContent, name);
+    const content = buildInternalComponentStoryContent(
+      name, parentImportPath, dataImportFromStories, bestSymbols, bestExports, props, comp
+    );
+    fs.writeFileSync(storyFile, content, "utf-8");
+    console.log(`[VDS] Wrote ${path.relative(PROJECT_ROOT, storyFile)} (sub-component of ${comp.name})`);
+  }
+}
+
 main();