vibe-design-system 2.8.20 → 2.8.21

package/package.json

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

package/vds-core-template/scan.mjs

@@ -447,30 +447,163 @@ function extractBrandAssets() {
   return assets;
 }
 
-/** Extract icon names from `import { A, B, C } from "lucide-react"` in app code only (exclude stories so generated Star/defaults don't pollute). */
+/** Extract Lucide icons used in app code with per-component JSX usage counts.
+ *  Returns { name, total, topFiles }[] sorted by total desc.
+ *  Handles aliased imports: `import { ArrowRight as Arrow }` — counted under original name. */
 function extractLucideIconsUsed(srcDir) {
   const allFiles = getAllTsxJsxInDir(srcDir);
   const files = allFiles.filter((rel) => !/^stories[/\\]/.test(rel.replace(/\\/g, "/")));
-  const names = new Set();
+
+  // originalName → { total: number, topFiles: Map<componentName, count> }
+  const iconData = new Map();
   const importRe = /import\s*\{([^}]+)\}\s*from\s*["']lucide-react["']/g;
+
   for (const rel of files) {
     const fullPath = path.join(srcDir, rel);
-    try {
-      const content = fs.readFileSync(fullPath, "utf-8");
-      let m;
-      while ((m = importRe.exec(content)) !== null) {
-        const block = m[1];
-        block.split(",").forEach((part) => {
-          const trimmed = part.trim();
-          const asMatch = trimmed.match(/^(\w+)\s+as\s+/);
-          const name = asMatch ? asMatch[1] : trimmed.split(/\s+/)[0];
-          if (name && /^[A-Z][a-zA-Z0-9]*$/.test(name)) names.add(name);
-        });
-      }
-    } catch (_) {}
+    let content;
+    try { content = fs.readFileSync(fullPath, "utf-8"); } catch (_) { continue; }
+    const componentName = path.basename(rel).replace(/\.(tsx|jsx|ts|js)$/, "");
+
+    // Pass 1 — collect local-name → original-name for this file
     importRe.lastIndex = 0;
+    let m;
+    const localToOriginal = new Map();
+    while ((m = importRe.exec(content)) !== null) {
+      m[1].split(",").forEach((part) => {
+        const trimmed = part.trim();
+        if (!trimmed) return;
+        const asMatch = trimmed.match(/^(\w+)\s+as\s+(\w+)$/);
+        if (asMatch) {
+          const orig = asMatch[1];
+          const local = asMatch[2];
+          if (/^[A-Z][a-zA-Z0-9]*$/.test(orig)) {
+            localToOriginal.set(local, orig);
+            if (!iconData.has(orig)) iconData.set(orig, { total: 0, topFiles: new Map() });
+          }
+        } else {
+          const name = trimmed.split(/\s+/)[0];
+          if (name && /^[A-Z][a-zA-Z0-9]*$/.test(name)) {
+            localToOriginal.set(name, name);
+            if (!iconData.has(name)) iconData.set(name, { total: 0, topFiles: new Map() });
+          }
+        }
+      });
+    }
+
+    // Pass 2 — count JSX usages `<LocalName ` / `<LocalName/` / `<LocalName>`
+    for (const [localName, originalName] of localToOriginal.entries()) {
+      const jsxRe = new RegExp(`<${localName}[\\s/>]`, "g");
+      let count = 0;
+      while (jsxRe.exec(content) !== null) count++;
+      if (count > 0) {
+        const data = iconData.get(originalName);
+        data.total += count;
+        data.topFiles.set(componentName, (data.topFiles.get(componentName) || 0) + count);
+      }
+    }
   }
-  return [...names].sort();
+
+  return [...iconData.entries()]
+    .map(([name, data]) => ({
+      name,
+      total: data.total,
+      topFiles: [...data.topFiles.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([n]) => n),
+    }))
+    .sort((a, b) => b.total - a.total || a.name.localeCompare(b.name));
+}
+
+/** Scan app source for responsive breakpoints, grid column patterns, gaps and max-width usage.
+ *  Returns { breakpoints, gridCols, gaps, maxWidths, containerCount } or null if nothing found. */
+function extractGridSystem(srcDir) {
+  if (!fs.existsSync(srcDir)) return null;
+  const allFiles = getAllTsxJsxInDir(srcDir);
+  const files = allFiles.filter((rel) => !/^stories[/\\]/.test(rel.replace(/\\/g, "/")));
+  if (files.length === 0) return null;
+
+  const BP_NAMES = ["sm", "md", "lg", "xl", "2xl"];
+  const bpData = {};
+  for (const bp of BP_NAMES) bpData[bp] = { count: 0, topFiles: new Map() };
+
+  const colData = {};  // colValue → { count, topFiles: Map }
+  const gapCounts = {};
+  const maxWCounts = {};
+  let containerCount = 0;
+
+  for (const rel of files) {
+    let content;
+    try { content = fs.readFileSync(path.join(srcDir, rel), "utf-8"); } catch (_) { continue; }
+    const componentName = path.basename(rel).replace(/\.(tsx|jsx|ts|js)$/, "");
+
+    // Breakpoints: sm: md: lg: xl: 2xl:
+    const bpRe = /\b(2xl|xl|lg|md|sm):/g;
+    let m;
+    while ((m = bpRe.exec(content)) !== null) {
+      const name = m[1];
+      bpData[name].count++;
+      bpData[name].topFiles.set(componentName, (bpData[name].topFiles.get(componentName) || 0) + 1);
+    }
+
+    // grid-cols-{value}
+    const gcRe = /\bgrid-cols-((?:\[[\w\s\-.,/()*+]+\]|\w+))/g;
+    while ((m = gcRe.exec(content)) !== null) {
+      const val = m[1];
+      if (!colData[val]) colData[val] = { count: 0, topFiles: new Map() };
+      colData[val].count++;
+      colData[val].topFiles.set(componentName, (colData[val].topFiles.get(componentName) || 0) + 1);
+    }
+
+    // gap-{n}, gap-x-{n}, gap-y-{n}
+    const gapRe = /\bgap(?:-[xy])?-((?:\[[\w\s./]+\]|\d[\w.]*|px))\b/g;
+    while ((m = gapRe.exec(content)) !== null) {
+      const val = m[1];
+      gapCounts[val] = (gapCounts[val] || 0) + 1;
+    }
+
+    // max-w-{value}
+    const maxWRe = /\bmax-w-((?:\[[\w\s./]+\]|[\w-]+))/g;
+    while ((m = maxWRe.exec(content)) !== null) {
+      const val = m[1];
+      maxWCounts[val] = (maxWCounts[val] || 0) + 1;
+    }
+
+    // container class
+    let ctrM;
+    const ctrRe = /\bcontainer\b/g;
+    while ((ctrM = ctrRe.exec(content)) !== null) containerCount++;
+  }
+
+  const breakpoints = {};
+  for (const bp of BP_NAMES) {
+    if (bpData[bp].count > 0) {
+      breakpoints[bp] = {
+        count: bpData[bp].count,
+        topFiles: [...bpData[bp].topFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([n]) => n),
+      };
+    }
+  }
+
+  const gridCols = {};
+  for (const [val, data] of Object.entries(colData).sort((a, b) => b[1].count - a[1].count)) {
+    gridCols[val] = {
+      count: data.count,
+      topFiles: [...data.topFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([n]) => n),
+    };
+  }
+
+  const gaps = Object.fromEntries(
+    Object.entries(gapCounts).sort((a, b) => b[1] - a[1]).slice(0, 12)
+  );
+
+  const maxWidths = Object.fromEntries(
+    Object.entries(maxWCounts).sort((a, b) => b[1] - a[1]).slice(0, 10)
+  );
+
+  if (Object.keys(breakpoints).length === 0 && Object.keys(gridCols).length === 0) return null;
+
+  return { breakpoints, gridCols, gaps, maxWidths, containerCount };
 }
 
 function extractVdsTags(content) {
@@ -2051,6 +2184,8 @@ function scan() {
   const colorNames = Object.keys(foundations.colors || {}).filter((k) => k !== "_dark");
   const colorUsage = extractColorUsage(colorNames);
   if (Object.keys(colorUsage).length > 0) foundations.colorUsage = colorUsage;
+  const gridSystem = extractGridSystem(SRC_DIR);
+  if (gridSystem) foundations.gridSystem = gridSystem;
   const componentSuggestions = extractComponentSuggestions();
   const unreleasedSectionCandidates = extractUnreleasedSectionCandidates();
   const output = {

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

@@ -1600,43 +1600,284 @@ function writeFoundationsStories(foundations) {
   fs.writeFileSync(path.join(foundationsDir, "Brand.stories.tsx"), brandContent, "utf-8");
   console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Brand.stories.tsx")));
 
-  const iconNames = Array.isArray(foundations?.icons) ? foundations.icons : [];
-  if (iconNames.length > 0) {
-    const iconsContent =
-      [
-        "import type { Meta, StoryObj } from \"@storybook/react\";",
-        "import * as Lucide from \"lucide-react\";",
-        "",
-        "const meta = { title: \"Foundations/Icons\" } satisfies Meta;",
-        "export default meta;",
-        "type Story = StoryObj;",
-        "",
-        `const iconNames = ${JSON.stringify(iconNames)};`,
-        "",
-        "export const Default: Story = {",
-        "  render: () => (",
-        "    <div style={{ padding: 24 }}>",
-        "      <p style={{ marginBottom: 16, color: \"#888\", fontSize: 14 }}>Icons imported from lucide-react in app code (src/, excluding stories).</p>",
-        "      <div style={{ display: \"grid\", gridTemplateColumns: \"repeat(auto-fill, minmax(100px, 1fr))\", gap: 16 }}>",
-        "      {iconNames.map((name) => {",
-        "        const Icon = Lucide[name];",
-        "        if (!Icon) return null;",
-        "        return (",
-        "          <div key={name} style={{ display: \"flex\", flexDirection: \"column\", alignItems: \"center\", gap: 8, padding: 12, border: \"1px solid #333\", borderRadius: 8 }}>",
-        "            <Icon size={24} />",
-        "            <span style={{ fontSize: 11, color: \"#888\" }}>{name}</span>",
-        "          </div>",
-        "        );",
-        "      })}",
-        "      </div>",
-        "    </div>",
-        "  ),",
-        "};",
-      ].join("\n");
+  const rawIcons = Array.isArray(foundations?.icons) ? foundations.icons : [];
+  if (rawIcons.length > 0) {
+    // Support both old format (string[]) and new format ({ name, total, topFiles }[])
+    const iconData = rawIcons[0] && typeof rawIcons[0] === "object"
+      ? rawIcons
+      : rawIcons.map((name) => ({ name, total: 0, topFiles: [] }));
+
+    const iconsContent = [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "import * as Lucide from \"lucide-react\";",
+      "",
+      "const meta = { title: \"Foundations/Icons\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const iconData = ${JSON.stringify(iconData, null, 2)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => {",
+      "    const usedIcons = iconData.filter((d) => d.total > 0);",
+      "    const unusedIcons = iconData.filter((d) => d.total === 0);",
+      "    const renderCard = (d: { name: string; total: number; topFiles: string[] }) => {",
+      "      const Icon = (Lucide as Record<string, any>)[d.name];",
+      "      if (!Icon) return null;",
+      "      return (",
+      "        <div key={d.name} style={{ display: \"flex\", flexDirection: \"column\", gap: 8, padding: 14,",
+      "          border: \"1px solid #1e293b\", borderRadius: 10, background: \"#0f172a\" }}>",
+      "          <div style={{ display: \"flex\", justifyContent: \"space-between\", alignItems: \"flex-start\" }}>",
+      "            <Icon size={22} strokeWidth={1.5} />",
+      "            {d.total > 0 && (",
+      "              <span style={{ fontSize: 11, fontWeight: 600, background: \"#1e293b\",",
+      "                color: \"#94a3b8\", padding: \"2px 7px\", borderRadius: 999 }}>",
+      "                ×{d.total}",
+      "              </span>",
+      "            )}",
+      "          </div>",
+      "          <span style={{ fontSize: 12, fontWeight: 500, color: \"#e2e8f0\" }}>{d.name}</span>",
+      "          {d.topFiles.length > 0 && (",
+      "            <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 4, marginTop: 2 }}>",
+      "              {d.topFiles.map((f) => (",
+      "                <span key={f} style={{ fontSize: 10, background: \"#1e293b\", color: \"#64748b\",",
+      "                  padding: \"1px 6px\", borderRadius: 4 }}>{f}</span>",
+      "              ))}",
+      "            </div>",
+      "          )}",
+      "        </div>",
+      "      );",
+      "    };",
+      "    return (",
+      "      <div style={{ padding: 24, fontFamily: \"sans-serif\" }}>",
+      "        <div style={{ marginBottom: 24 }}>",
+      "          <p style={{ margin: 0, marginBottom: 4, fontSize: 14, color: \"#94a3b8\" }}>",
+      "            {iconData.length} icons imported from <code style={{ fontSize: 12 }}>lucide-react</code> in app code.",
+      "          </p>",
+      "          <p style={{ margin: 0, fontSize: 12, color: \"#475569\" }}>",
+      "            Sorted by usage frequency · Badge shows total JSX usages · Chips show top components.",
+      "          </p>",
+      "        </div>",
+      "        {usedIcons.length > 0 && (",
+      "          <>",
+      "            <p style={{ margin: \"0 0 12px\", fontSize: 12, fontWeight: 600, color: \"#64748b\",",
+      "              textTransform: \"uppercase\", letterSpacing: \"0.06em\" }}>",
+      "              Active — {usedIcons.length}",
+      "            </p>",
+      "            <div style={{ display: \"grid\", gridTemplateColumns: \"repeat(auto-fill, minmax(160px, 1fr))\",",
+      "              gap: 10, marginBottom: 32 }}>",
+      "              {usedIcons.map(renderCard)}",
+      "            </div>",
+      "          </>",
+      "        )}",
+      "        {unusedIcons.length > 0 && (",
+      "          <>",
+      "            <p style={{ margin: \"0 0 12px\", fontSize: 12, fontWeight: 600, color: \"#334155\",",
+      "              textTransform: \"uppercase\", letterSpacing: \"0.06em\" }}>",
+      "              Imported (not used in JSX) — {unusedIcons.length}",
+      "            </p>",
+      "            <div style={{ display: \"grid\", gridTemplateColumns: \"repeat(auto-fill, minmax(140px, 1fr))\",",
+      "              gap: 8, opacity: 0.45 }}>",
+      "              {unusedIcons.map(renderCard)}",
+      "            </div>",
+      "          </>",
+      "        )}",
+      "      </div>",
+      "    );",
+      "  },",
+      "};",
+    ].join("\n");
     fs.writeFileSync(path.join(foundationsDir, "Icons.stories.tsx"), iconsContent, "utf-8");
     console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Icons.stories.tsx")));
   }
 
+  const gridSystem = foundations?.gridSystem;
+  if (gridSystem && (Object.keys(gridSystem.breakpoints || {}).length > 0 || Object.keys(gridSystem.gridCols || {}).length > 0)) {
+    const bpEntries = Object.entries(gridSystem.breakpoints || {});
+    const colEntries = Object.entries(gridSystem.gridCols || {});
+    const gapEntries = Object.entries(gridSystem.gaps || {});
+    const maxWEntries = Object.entries(gridSystem.maxWidths || {});
+    const containerCount = gridSystem.containerCount || 0;
+
+    const gridContent = [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Grid\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const gridSystem = ${JSON.stringify(gridSystem, null, 2)};`,
+      "",
+      "const BP_CONFIG: Record<string, { px: number; label: string; color: string }> = {",
+      "  sm:  { px: 640,  label: \"Small\",         color: \"#6366f1\" },",
+      "  md:  { px: 768,  label: \"Medium\",        color: \"#8b5cf6\" },",
+      "  lg:  { px: 1024, label: \"Large\",         color: \"#a78bfa\" },",
+      "  xl:  { px: 1280, label: \"Extra Large\",   color: \"#c4b5fd\" },",
+      "  \"2xl\": { px: 1536, label: \"2× Extra Large\", color: \"#e9d5ff\" },",
+      "};",
+      "const ALL_BPS = [\"sm\", \"md\", \"lg\", \"xl\", \"2xl\"];",
+      "",
+      "export const Default: Story = {",
+      "  render: () => {",
+      "    const colEntries = Object.entries(gridSystem.gridCols || {});",
+      "    const gapEntries = Object.entries(gridSystem.gaps || {});",
+      "    const maxWEntries = Object.entries(gridSystem.maxWidths || {});",
+      "    const chip = (label: string) => (",
+      "      <span key={label} style={{ fontSize: 10, background: \"#1e293b\", color: \"#64748b\", padding: \"1px 6px\", borderRadius: 4 }}>{label}</span>",
+      "    );",
+      "    const renderColPreview = (colVal: string) => {",
+      "      const n = parseInt(colVal, 10);",
+      "      if (!isNaN(n) && n >= 1 && n <= 12) {",
+      "        return (",
+      "          <div style={{ display: \"grid\", gridTemplateColumns: `repeat(${n}, 1fr)`, gap: 2, marginBottom: 8 }}>",
+      "            {Array.from({ length: n }).map((_, i) => (",
+      "              <div key={i} style={{ height: 20, borderRadius: 3, background: \"#1e3a5f\" }} />",
+      "            ))}",
+      "          </div>",
+      "        );",
+      "      }",
+      "      return (",
+      "        <div style={{ fontFamily: \"monospace\", fontSize: 10, color: \"#475569\", marginBottom: 8, background: \"#0a0f1a\", padding: \"4px 6px\", borderRadius: 4 }}>",
+      "          grid-cols-{colVal}",
+      "        </div>",
+      "      );",
+      "    };",
+      "    return (",
+      "      <div style={{ padding: 24, fontFamily: \"sans-serif\", maxWidth: 900 }}>",
+      "",
+      "        {/* ── Breakpoints ── */}",
+      "        <section style={{ marginBottom: 40 }}>",
+      "          <p style={{ margin: \"0 0 4px\", fontSize: 12, fontWeight: 600, color: \"#64748b\", textTransform: \"uppercase\", letterSpacing: \"0.06em\" }}>",
+      "            Responsive Breakpoints",
+      "          </p>",
+      "          <p style={{ margin: \"0 0 14px\", fontSize: 12, color: \"#475569\" }}>",
+      "            Tailwind CSS breakpoint prefixes detected in source.",
+      "          </p>",
+      "          <div style={{ position: \"relative\", height: 28, marginBottom: 14, background: \"#0a0f1a\", borderRadius: 8, border: \"1px solid #1e293b\", overflow: \"hidden\" }}>",
+      "            {ALL_BPS.map((bp) => {",
+      "              const cfg = BP_CONFIG[bp];",
+      "              const used = !!(gridSystem.breakpoints as any)?.[bp];",
+      "              const leftPct = (cfg.px / 1600) * 100;",
+      "              return (",
+      "                <div key={bp} style={{ position: \"absolute\", left: `${leftPct}%`, top: 0, bottom: 0,",
+      "                  borderLeft: `2px solid ${used ? cfg.color : \"#1e293b\"}`,",
+      "                  display: \"flex\", alignItems: \"center\", paddingLeft: 4 }}>",
+      "                  <span style={{ fontSize: 9, color: used ? cfg.color : \"#334155\",",
+      "                    whiteSpace: \"nowrap\", fontWeight: 600 }}>{bp}</span>",
+      "                </div>",
+      "              );",
+      "            })}",
+      "          </div>",
+      "          <div style={{ borderRadius: 8, border: \"1px solid #1e293b\", overflow: \"hidden\" }}>",
+      "            <table style={{ width: \"100%\", borderCollapse: \"collapse\", fontSize: 12 }}>",
+      "              <thead>",
+      "                <tr style={{ background: \"#0a0f1a\", borderBottom: \"1px solid #1e293b\" }}>",
+      "                  <th style={{ textAlign: \"left\", padding: \"8px 12px\", color: \"#64748b\", fontWeight: 600 }}>Prefix</th>",
+      "                  <th style={{ textAlign: \"left\", padding: \"8px 12px\", color: \"#64748b\", fontWeight: 600 }}>Min-width</th>",
+      "                  <th style={{ textAlign: \"left\", padding: \"8px 12px\", color: \"#64748b\", fontWeight: 600 }}>Usages</th>",
+      "                  <th style={{ textAlign: \"left\", padding: \"8px 12px\", color: \"#64748b\", fontWeight: 600 }}>Top components</th>",
+      "                </tr>",
+      "              </thead>",
+      "              <tbody>",
+      "                {ALL_BPS.map((bp, i) => {",
+      "                  const cfg = BP_CONFIG[bp];",
+      "                  const data = (gridSystem.breakpoints as any)?.[bp];",
+      "                  return (",
+      "                    <tr key={bp} style={{ borderBottom: i < 4 ? \"1px solid #1e293b\" : \"none\", opacity: data ? 1 : 0.3 }}>",
+      "                      <td style={{ padding: \"8px 12px\" }}>",
+      "                        <code style={{ fontSize: 12, fontWeight: 700, color: data ? cfg.color : \"#475569\" }}>{bp}:</code>",
+      "                      </td>",
+      "                      <td style={{ padding: \"8px 12px\", color: \"#94a3b8\", fontFamily: \"monospace\" }}>{cfg.px}px</td>",
+      "                      <td style={{ padding: \"8px 12px\", color: data ? \"#e2e8f0\" : \"#334155\" }}>",
+      "                        {data ? `×${data.count}` : \"—\"}",
+      "                      </td>",
+      "                      <td style={{ padding: \"8px 12px\" }}>",
+      "                        <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 4 }}>",
+      "                          {(data?.topFiles || []).map(chip)}",
+      "                        </div>",
+      "                      </td>",
+      "                    </tr>",
+      "                  );",
+      "                })}",
+      "              </tbody>",
+      "            </table>",
+      "          </div>",
+      "        </section>",
+      "",
+      "        {/* ── Grid Columns ── */}",
+      "        {colEntries.length > 0 && (",
+      "          <section style={{ marginBottom: 40 }}>",
+      "            <p style={{ margin: \"0 0 4px\", fontSize: 12, fontWeight: 600, color: \"#64748b\", textTransform: \"uppercase\", letterSpacing: \"0.06em\" }}>",
+      "              Grid Columns",
+      "            </p>",
+      "            <p style={{ margin: \"0 0 14px\", fontSize: 12, color: \"#475569\" }}>",
+      "              grid-cols-* patterns detected in source, sorted by usage.",
+      "            </p>",
+      "            <div style={{ display: \"grid\", gridTemplateColumns: \"repeat(auto-fill, minmax(180px, 1fr))\", gap: 12 }}>",
+      "              {(colEntries as [string, { count: number; topFiles: string[] }][]).map(([val, data]) => (",
+      "                <div key={val} style={{ background: \"#0a0f1a\", border: \"1px solid #1e293b\", borderRadius: 8, padding: 12 }}>",
+      "                  {renderColPreview(val)}",
+      "                  <div style={{ display: \"flex\", justifyContent: \"space-between\", alignItems: \"center\", marginBottom: 6 }}>",
+      "                    <code style={{ fontSize: 11, color: \"#a78bfa\" }}>grid-cols-{val}</code>",
+      "                    <span style={{ fontSize: 11, fontWeight: 600, background: \"#1e293b\",",
+      "                      color: \"#94a3b8\", padding: \"1px 6px\", borderRadius: 999 }}>×{data.count}</span>",
+      "                  </div>",
+      "                  <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 4 }}>",
+      "                    {data.topFiles.map(chip)}",
+      "                  </div>",
+      "                </div>",
+      "              ))}",
+      "            </div>",
+      "          </section>",
+      "        )}",
+      "",
+      "        {/* ── Gaps ── */}",
+      "        {gapEntries.length > 0 && (",
+      "          <section style={{ marginBottom: 40 }}>",
+      "            <p style={{ margin: \"0 0 4px\", fontSize: 12, fontWeight: 600, color: \"#64748b\", textTransform: \"uppercase\", letterSpacing: \"0.06em\" }}>",
+      "              Common Gaps",
+      "            </p>",
+      "            <p style={{ margin: \"0 0 12px\", fontSize: 12, color: \"#475569\" }}>gap-* values across all components.</p>",
+      "            <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 8 }}>",
+      "              {(gapEntries as [string, number][]).map(([val, count]) => (",
+      "                <span key={val} style={{ display: \"flex\", alignItems: \"center\", gap: 6,",
+      "                  background: \"#0a0f1a\", border: \"1px solid #1e293b\", borderRadius: 6, padding: \"5px 10px\", fontSize: 12 }}>",
+      "                  <code style={{ color: \"#67e8f9\" }}>gap-{val}</code>",
+      "                  <span style={{ color: \"#475569\", fontSize: 11 }}>×{count}</span>",
+      "                </span>",
+      "              ))}",
+      "            </div>",
+      "          </section>",
+      "        )}",
+      "",
+      "        {/* ── Container / Max-widths ── */}",
+      "        {maxWEntries.length > 0 && (",
+      "          <section>",
+      "            <p style={{ margin: \"0 0 4px\", fontSize: 12, fontWeight: 600, color: \"#64748b\", textTransform: \"uppercase\", letterSpacing: \"0.06em\" }}>",
+      "              Container Widths",
+      "            </p>",
+      `            <p style={{ margin: "0 0 12px", fontSize: 12, color: "#475569" }}>max-w-* usage${containerCount > 0 ? ` · container ×${containerCount}` : ""}.</p>`,
+      "            <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 8 }}>",
+      "              {(maxWEntries as [string, number][]).map(([val, count]) => (",
+      "                <span key={val} style={{ display: \"flex\", alignItems: \"center\", gap: 6,",
+      "                  background: \"#0a0f1a\", border: \"1px solid #1e293b\", borderRadius: 6, padding: \"5px 10px\", fontSize: 12 }}>",
+      "                  <code style={{ color: \"#4ade80\" }}>max-w-{val}</code>",
+      "                  <span style={{ color: \"#475569\", fontSize: 11 }}>×{count}</span>",
+      "                </span>",
+      "              ))}",
+      "            </div>",
+      "          </section>",
+      "        )}",
+      "",
+      "      </div>",
+      "    );",
+      "  },",
+      "};",
+    ].join("\n");
+    fs.writeFileSync(path.join(foundationsDir, "Grid.stories.tsx"), gridContent, "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Grid.stories.tsx")));
+  }
+
   const buttonUsage = foundations?.buttonUsage;
   if (buttonUsage && Array.isArray(buttonUsage.combos) && buttonUsage.combos.length > 0) {
     const combos = buttonUsage.combos.map((c) => ({