vibe-design-system 2.8.20 → 2.8.22

package/package.json

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

package/vds-core-template/scan.mjs

@@ -375,6 +375,62 @@ function classifyByPath(rel) {
   return { group: "Components", category: "Components" };
 }
 
+/**
+ * Infer the reusability tier of a component from path + content signals.
+ *   primitive  → src/components/ui/ (shadcn atoms)
+ *   component  → small, focused domain component (< 200 lines, ≤ 6 local imports)
+ *   feature    → medium, contains state / multiple sub-parts
+ *   page       → full page/view — reference only, not for direct reuse
+ */
+function inferTier(rel, content) {
+  const normalized = rel.replace(/\\/g, "/");
+  if (normalized.startsWith("ui/") || normalized.includes("/ui/")) return "primitive";
+
+  const lines = content.split("\n").length;
+  // Count relative imports (../ ./) AND path-alias imports (@/components/) as local dependencies
+  const localImports = (content.match(/from\s+['"](?:\.\.?\/?|@\/components\/)/g) || []).length;
+
+  if (lines >= 400 || localImports >= 12) return "page";
+  if (lines >= 200 || localImports >= 7)  return "feature";
+  return "component";
+}
+
+// Tailwind pseudo-class modifiers that appear inside class strings — never valid cva option names
+const CVA_SKIP = new Set([
+  "hover","focus","active","disabled","dark","group","peer","placeholder",
+  "before","after","visited","checked","required","invalid","valid","not",
+  "open","closed","empty","enabled","first","last","odd","even",
+]);
+
+/**
+ * Extract cva() variant options from a file, e.g.:
+ *   variants: { variant: { default, destructive, ghost }, size: { sm, md, lg } }
+ * Returns { variant: ["default","destructive",...], size: [...] } or null.
+ * Filters out Tailwind pseudo-class modifiers that appear inside class strings.
+ */
+function extractCvaVariants(content) {
+  const block = content.match(/variants\s*:\s*\{([\s\S]*?)\}\s*,?\s*defaultVariants/);
+  if (!block) return null;
+  const result = {};
+  // Each top-level key is a variant dimension (variant, size, intent…)
+  // Match: variantName: { optionA: "...", optionB: "..." }
+  const keyRe = /(\w+)\s*:\s*\{([^}]+)\}/g;
+  let m;
+  while ((m = keyRe.exec(block[1])) !== null) {
+    const dimName = m[1];
+    if (CVA_SKIP.has(dimName)) continue; // skip pseudo-class keys at outer level
+    // Extract option names: only words at the start of a line (key: "value")
+    const optRe = /^\s{6,}(\w[\w-]*)\s*:/gm;
+    let om;
+    const options = [];
+    while ((om = optRe.exec(m[2])) !== null) {
+      if (!CVA_SKIP.has(om[1])) options.push(om[1]);
+    }
+    if (options.length > 0) result[dimName] = options;
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
 function getAllComponentFiles(dir, baseDir = dir) {
   const entries = fs.readdirSync(dir, { withFileTypes: true });
   const files = [];
@@ -447,30 +503,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) {
@@ -2018,7 +2207,11 @@ function scan() {
       description = "";
     }
     const tokens = extractTailwindTokens(content);
-    results.push({ file: rel, name, group, category, description, tokens });
+    const tier = inferTier(rel, content);
+    const variants = (tier === "primitive") ? extractCvaVariants(content) : null;
+    const lineCount = content.split("\n").length;
+    const localImportCount = (content.match(/from\s+['"]\.\.\?\//g) || []).length;
+    results.push({ file: rel, name, group, category, description, tokens, tier, lines: lineCount, localImports: localImportCount, ...(variants ? { variants } : {}) });
   }
   if (PAGES_DIR && fs.existsSync(PAGES_DIR)) {
     const pageFiles = getAllComponentFiles(PAGES_DIR);
@@ -2027,6 +2220,7 @@ function scan() {
       const content = fs.readFileSync(fullPath, "utf-8");
       const name = humanizeName(rel);
       const tokens = extractTailwindTokens(content);
+      const lineCount = content.split("\n").length;
       results.push({
         file: path.relative(PROJECT_ROOT, PAGES_DIR).replace(/\\/g, "/") + "/" + rel,
         name,
@@ -2034,6 +2228,9 @@ function scan() {
         category: "Pages",
         description: "",
         tokens,
+        tier: "page",
+        lines: lineCount,
+        localImports: 0,
       });
     }
   }
@@ -2051,6 +2248,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) => ({
@@ -2245,6 +2486,195 @@ function writeChangelogStory(changelog) {
   console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Changelog.stories.tsx")));
 }
 
+/** Generate .cursor/rules — structured design system context for AI agents.
+ *  Components are split into tiers so the agent knows what to reuse vs reference.
+ *  Foundations (colors, icons, spacing, breakpoints) are inlined as tables/lists.
+ *  The file is written to PROJECT_ROOT/.cursor/rules so Cursor injects it automatically. */
+function writeCursorRules(components, foundations) {
+  const lines = [];
+  const now = new Date().toISOString().slice(0, 10);
+
+  lines.push(`# VDS Design System — Agent Context`);
+  lines.push(`> Auto-generated by VDS on ${now}. Do not edit — regenerated on every \`npm run vds\`.`);
+  lines.push(``);
+
+  // ── Ground rules ──────────────────────────────────────────────────────────
+  const gaps = foundations?.gridSystem?.gaps || {};
+  const topGaps = Object.entries(gaps).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([v]) => `gap-${v}`).join(", ");
+  const bpUsed = Object.keys(foundations?.gridSystem?.breakpoints || {});
+  const bpAll  = ["sm","md","lg","xl","2xl"];
+  const bpUnused = bpAll.filter(b => !bpUsed.includes(b));
+
+  lines.push(`## ⚙️ Rules`);
+  lines.push(`1. Before creating a new component, check the component lists below.`);
+  lines.push(`2. **Never hardcode colors or hex values** — use the token table.`);
+  lines.push(`3. **Always import icons from \`lucide-react\`** — never other icon libraries.`);
+  if (topGaps) lines.push(`4. **Spacing convention**: ${topGaps} are the standard gaps in this project.`);
+  if (bpUsed.length)   lines.push(`5. **Breakpoints in use**: ${bpUsed.map(b=>`\`${b}:\``).join(" ")} — prefer these.`);
+  if (bpUnused.length) lines.push(`6. **Breakpoints NOT used**: ${bpUnused.map(b=>`\`${b}:\``).join(" ")} — avoid unless explicitly needed.`);
+  lines.push(``);
+  lines.push(`---`);
+  lines.push(``);
+
+  // ── Component tiers ───────────────────────────────────────────────────────
+  const byTier = { primitive: [], component: [], feature: [], page: [] };
+  for (const c of components) {
+    const t = c.tier || "component";
+    if (byTier[t]) byTier[t].push(c);
+  }
+
+  // Tier 1 — Primitives
+  if (byTier.primitive.length > 0) {
+    lines.push(`## 🧱 Primitives — Use first for all UI elements`);
+    lines.push(`> Atomic components from \`src/components/ui/\`. Always prefer over building from scratch.`);
+    lines.push(``);
+    for (const c of byTier.primitive.sort((a, b) => a.name.localeCompare(b.name))) {
+      let entry = `- **${c.name}** \`${c.file}\``;
+      if (c.variants) {
+        const parts = Object.entries(c.variants).map(([k, vs]) => `${k}: ${vs.join(" | ")}`);
+        entry += `  — ${parts.join(" · ")}`;
+      }
+      lines.push(entry);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // Tier 2 — Components
+  if (byTier.component.length > 0) {
+    lines.push(`## 🔷 Components — Reusable domain components`);
+    lines.push(`> Project-specific, small, focused. Use before creating new ones.`);
+    lines.push(``);
+    for (const c of byTier.component.sort((a, b) => a.name.localeCompare(b.name))) {
+      let entry = `- **${c.name}** \`${c.file}\``;
+      if (c.description) entry += ` — ${c.description}`;
+      lines.push(entry);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // Tier 3 — Features
+  if (byTier.feature.length > 0) {
+    lines.push(`## ⚙️ Feature Components — Extract patterns, don't import whole`);
+    lines.push(`> Complex components with internal state. Reuse sub-patterns, not the whole file.`);
+    lines.push(``);
+    for (const c of byTier.feature.sort((a, b) => a.name.localeCompare(b.name))) {
+      lines.push(`- **${c.name}** \`${c.file}\``);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // Tier 4 — Pages (just names, no need to list file paths)
+  if (byTier.page.length > 0) {
+    lines.push(`## 📄 Pages & Views — Reference only`);
+    lines.push(`> Full page views. Study for patterns but do not import into new features.`);
+    lines.push(``);
+    lines.push(byTier.page.map(c => c.name).sort().join(", "));
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // ── Color tokens ──────────────────────────────────────────────────────────
+  const colors = foundations?.colors || {};
+  const colorUsage = foundations?.colorUsage || {};
+  const colorEntries = Object.entries(colors)
+    .filter(([k]) => k !== "_dark" && !k.startsWith("arbitrary-") && !k.startsWith("inline-"))
+    .sort((a, b) => {
+      const ua = colorUsage[a[0]]?.total || 0;
+      const ub = colorUsage[b[0]]?.total || 0;
+      return ub - ua;
+    })
+    .slice(0, 20);
+
+  if (colorEntries.length > 0) {
+    lines.push(`## 🎨 Color Tokens — Never hardcode hex values`);
+    lines.push(`> Use Tailwind utility classes: \`bg-{token}\`, \`text-{token}\`, \`border-{token}\``);
+    lines.push(``);
+    lines.push(`| Token | Value | Usages |`);
+    lines.push(`|-------|-------|--------|`);
+    for (const [token, val] of colorEntries) {
+      const hex = typeof val === "string" ? val : (val?.DEFAULT || val?.value || "");
+      const usage = colorUsage[token]?.total || 0;
+      lines.push(`| \`${token}\` | ${hex} | ${usage > 0 ? `×${usage}` : "—"} |`);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // ── Typography ────────────────────────────────────────────────────────────
+  const typo = foundations?.typography || {};
+  if (typo.fontFamily && Object.keys(typo.fontFamily).length > 0) {
+    lines.push(`## 🔤 Typography`);
+    const families = Object.entries(typo.fontFamily).map(([k, v]) => `${k}: ${Array.isArray(v) ? v[0] : v}`).join(" · ");
+    lines.push(`Font: ${families}`);
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // ── Spacing / Grid ────────────────────────────────────────────────────────
+  const gridSystem = foundations?.gridSystem;
+  if (gridSystem) {
+    lines.push(`## 📐 Spacing & Layout (detected in this project)`);
+    if (Object.keys(gaps).length > 0) {
+      const gapLine = Object.entries(gaps).sort((a,b)=>b[1]-a[1]).slice(0,8)
+        .map(([v, c]) => `\`gap-${v}\` ×${c}`).join("  ·  ");
+      lines.push(`**Common gaps:** ${gapLine}`);
+    }
+    if (Object.keys(gridSystem.gridCols || {}).length > 0) {
+      const colLine = Object.entries(gridSystem.gridCols).sort((a,b)=>b[1].count-a[1].count).slice(0,6)
+        .map(([v, d]) => `\`grid-cols-${v}\` ×${d.count}`).join("  ·  ");
+      lines.push(`**Grid columns:** ${colLine}`);
+    }
+    if (Object.keys(gridSystem.maxWidths || {}).length > 0) {
+      const mwLine = Object.entries(gridSystem.maxWidths).slice(0,5)
+        .map(([v, c]) => `\`max-w-${v}\` ×${c}`).join("  ·  ");
+      lines.push(`**Container widths:** ${mwLine}`);
+    }
+    if (bpUsed.length > 0) {
+      const bpLine = bpUsed.map(bp => {
+        const d = gridSystem.breakpoints[bp];
+        return `\`${bp}:\` ×${d.count}`;
+      }).join("  ·  ");
+      lines.push(`**Active breakpoints:** ${bpLine}`);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(``);
+  }
+
+  // ── Icons ─────────────────────────────────────────────────────────────────
+  const icons = Array.isArray(foundations?.icons) ? foundations.icons : [];
+  const activeIcons = icons.filter(i => i && typeof i === "object" ? i.total > 0 : true);
+  if (activeIcons.length > 0) {
+    lines.push(`## 🎯 Icons — \`import { Name } from "lucide-react"\``);
+    lines.push(`> ${activeIcons.length} icons active in this project. See Foundations/Icons in Storybook for full list.`);
+    lines.push(``);
+    const top = activeIcons.slice(0, 16);
+    const iconLine = top.map(i => {
+      const n = typeof i === "string" ? i : i.name;
+      const t = typeof i === "object" ? i.total : 0;
+      return t > 0 ? `\`${n}\` ×${t}` : `\`${n}\``;
+    }).join("  ·  ");
+    lines.push(`**Most used:** ${iconLine}`);
+    if (icons.length > top.length) lines.push(`*(+ ${icons.length - top.length} more)*`);
+    lines.push(``);
+  }
+
+  const cursorDir = path.join(PROJECT_ROOT, ".cursor");
+  if (!fs.existsSync(cursorDir)) fs.mkdirSync(cursorDir, { recursive: true });
+  const outPath = path.join(cursorDir, "rules");
+  fs.writeFileSync(outPath, lines.join("\n"), "utf-8");
+  console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, outPath));
+}
+
 function main() {
   if (!fs.existsSync(VDS_OUTPUT)) {
     console.error("[VDS] vds-output.json not found. Run `npm run vds` first.");
@@ -2262,6 +2692,7 @@ function main() {
   ensureDir(STORIES_DIR);
   ensureDir(path.join(STORIES_DIR, "foundations"));
   writeFoundationsStories(foundations);
+  writeCursorRules(components, foundations);
   const componentSuggestions = data.componentSuggestions;
   if (componentSuggestions?.length) {
     writeComponentSuggestionsStory(componentSuggestions);