vibe-design-system 2.8.12 → 2.8.14

package/bin/init.js

@@ -58,7 +58,7 @@ const preview: Preview = {
       storySort: {
         order: [
           "Foundations",
-          ["Introduction", "Page to Components", "Colors", "Typography", "Brand", "Icons", "Component Suggestions", "Changelog"],
+          ["Introduction", "Page to Components", "Colors", "Typography", "Spacing & Layout", "Border & Radius", "Elevation & Shadows", "Motion & Interaction", "Brand", "Icons", "Button Usage", "Component Suggestions", "Changelog"],
           "Layout",
           "Components",
           "Actions",
@@ -304,7 +304,7 @@ const preview: Preview = {
       storySort: {
         order: [
           "Foundations",
-          ["Introduction", "Page to Components", "Colors", "Typography", "Brand", "Icons", "Component Suggestions", "Changelog"],
+          ["Introduction", "Page to Components", "Colors", "Typography", "Spacing & Layout", "Border & Radius", "Elevation & Shadows", "Motion & Interaction", "Brand", "Icons", "Button Usage", "Component Suggestions", "Changelog"],
           "Layout",
           "Components",
           "Actions",

package/package.json

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

package/vds-core-template/scan.mjs

@@ -1211,21 +1211,27 @@ function extractFoundations() {
   const typography = {};
   const cssRadiusVars = {};
   const borderRadiusScale = {};
-  const cssPath = path.join(PROJECT_ROOT, "src", "index.css");
-  const globalsCss = path.join(PROJECT_ROOT, "src", "globals.css");
-  const stylesGlobals = path.join(PROJECT_ROOT, "src", "styles", "globals.css");
-  const appGlobals = path.join(PROJECT_ROOT, "app", "globals.css");
-  const cssToRead = fs.existsSync(cssPath)
-    ? cssPath
-    : fs.existsSync(globalsCss)
-      ? globalsCss
-      : fs.existsSync(stylesGlobals)
-        ? stylesGlobals
-        : appGlobals;
+
+  // Read ALL existing CSS files and combine them (covers Tailwind v4 split configs)
+  const allCssCandidates = [
+    path.join(PROJECT_ROOT, "src", "index.css"),
+    path.join(PROJECT_ROOT, "src", "globals.css"),
+    path.join(PROJECT_ROOT, "src", "styles", "globals.css"),
+    path.join(PROJECT_ROOT, "src", "App.css"),
+    path.join(PROJECT_ROOT, "app", "globals.css"),
+  ];
+  const cssChunks = [];
+  for (const p of allCssCandidates) {
+    if (fs.existsSync(p)) {
+      try { cssChunks.push(fs.readFileSync(p, "utf-8")); } catch (_) {}
+    }
+  }
+  // Also use first found as primary (for legacy logic below)
+  const cssToRead = allCssCandidates.find((p) => fs.existsSync(p)) || "";
 
   try {
-    if (fs.existsSync(cssToRead)) {
-      const css = fs.readFileSync(cssToRead, "utf-8");
+    if (cssChunks.length > 0) {
+      const css = cssChunks.join("\n");
 
       const rootMatch = css.match(/:root\s*\{([\s\S]*?)\}/);
       if (rootMatch) {
@@ -1266,6 +1272,73 @@ function extractFoundations() {
         const val = fvm[2].trim();
         if (!typography[key]) typography[key] = val;
       }
+
+      // Tailwind v4: extract design tokens from @layer theme { :root { ... } } or bare :root
+      // Variables: --spacing (base), --radius-*, --shadow-*, --ease-*, --duration-*, --animate-*
+      const v4ThemeVars = {};
+      // Parse the full @layer theme block (may span many lines)
+      const themeLayerRe = /@layer\s+theme\s*\{([\s\S]*?)\n\}/g;
+      let tlm;
+      while ((tlm = themeLayerRe.exec(css)) !== null) {
+        const varRe = /--([\w-]+)\s*:\s*([^;\n]+);/g;
+        let vm;
+        while ((vm = varRe.exec(tlm[1])) !== null) {
+          v4ThemeVars[vm[1]] = vm[2].trim();
+        }
+      }
+      // Also scan the entire CSS for these variable families in case they're outside @layer theme
+      const v4AllVarRe = /--(spacing|radius|shadow|ease|duration|animate|breakpoint|z-index)([\w-]*)\s*:\s*([^;\n]+);/g;
+      let v4m;
+      while ((v4m = v4AllVarRe.exec(css)) !== null) {
+        const fullName = v4m[1] + (v4m[2] || "");
+        v4ThemeVars[fullName] = v4m[3].trim();
+      }
+
+      // ── spacing: store base unit for synthetic scale generation
+      if (v4ThemeVars["spacing"] && !v4ThemeVars["spacing"].includes("calc")) {
+        // Mark as v4 base unit — will expand in final section
+        cssRadiusVars["__v4SpacingBase"] = v4ThemeVars["spacing"];
+      }
+
+      // ── radius-* vars → borderRadiusScale
+      for (const [k, v] of Object.entries(v4ThemeVars)) {
+        if (k.startsWith("radius-") || k === "radius") {
+          const token = k === "radius" ? "DEFAULT" : k.replace(/^radius-/, "");
+          borderRadiusScale[token] = v;
+        }
+      }
+
+      // ── shadow-* vars → v4Shadows (stored in cssRadiusVars with __v4shadow prefix)
+      for (const [k, v] of Object.entries(v4ThemeVars)) {
+        if (k.startsWith("shadow-") || k === "shadow") {
+          const token = k === "shadow" ? "DEFAULT" : k.replace(/^shadow-/, "");
+          cssRadiusVars[`__v4shadow_${token}`] = v;
+        }
+      }
+
+      // ── ease-* vars → v4Easings
+      for (const [k, v] of Object.entries(v4ThemeVars)) {
+        if (k.startsWith("ease-") || k === "ease") {
+          const token = k === "ease" ? "DEFAULT" : k.replace(/^ease-/, "");
+          cssRadiusVars[`__v4ease_${token}`] = v;
+        }
+      }
+
+      // ── duration-* vars
+      for (const [k, v] of Object.entries(v4ThemeVars)) {
+        if (k.startsWith("duration-") || k === "duration") {
+          const token = k === "duration" ? "DEFAULT" : k.replace(/^duration-/, "");
+          cssRadiusVars[`__v4duration_${token}`] = v;
+        }
+      }
+
+      // ── animate-* vars
+      for (const [k, v] of Object.entries(v4ThemeVars)) {
+        if (k.startsWith("animate-")) {
+          const token = k.replace(/^animate-/, "");
+          cssRadiusVars[`__v4animate_${token}`] = v;
+        }
+      }
     }
   } catch (_) {}
 
@@ -1326,6 +1399,29 @@ function extractFoundations() {
     }
   }
 
+  // Resolve calc() radius expressions relative to base radius
+  // e.g. --radius-sm: calc(var(--radius) - 4px)  →  resolves to base - 4px
+  const baseRadiusVal = cssRadiusVars.radius;
+  if (baseRadiusVal) {
+    const baseRe = /^([\d.]+)(rem|px)$/.exec(baseRadiusVal);
+    const basePx = baseRe
+      ? (baseRe[2] === "rem" ? parseFloat(baseRe[1]) * 16 : parseFloat(baseRe[1]))
+      : null;
+    for (const [k, v] of Object.entries(borderRadiusScale)) {
+      if (v.startsWith("calc(") && basePx !== null) {
+        const addM = v.match(/calc\(var\([^)]+\)\s*([+-])\s*([\d.]+)(rem|px)\)/);
+        if (addM) {
+          const sign = addM[1] === "+" ? 1 : -1;
+          const delta = addM[3] === "rem" ? parseFloat(addM[2]) * 16 : parseFloat(addM[2]);
+          const resolved = Math.max(0, basePx + sign * delta);
+          borderRadiusScale[k] = `${resolved}px`;
+        }
+      } else if (v.includes("var(--radius)") && basePx !== null) {
+        borderRadiusScale[k] = `${basePx}px`;
+      }
+    }
+  }
+
   const radius = {};
   if (cssRadiusVars.radius) radius.base = cssRadiusVars.radius;
   if (Object.keys(borderRadiusScale).length > 0) radius.borderRadius = borderRadiusScale;
@@ -1526,22 +1622,156 @@ function extractFoundations() {
     }
     return out;
   };
+
+  // ── Tailwind v4: extract stored __v4* vars from cssRadiusVars ───────────────
+  const v4Shadows = {};
+  const v4Easings = {};
+  const v4Durations = {};
+  const v4Animations = {};
+  let v4SpacingBase = null;
+
+  for (const [k, v] of Object.entries(cssRadiusVars)) {
+    if (k.startsWith("__v4shadow_")) v4Shadows[k.replace("__v4shadow_", "")] = v;
+    else if (k.startsWith("__v4ease_")) v4Easings[k.replace("__v4ease_", "")] = v;
+    else if (k.startsWith("__v4duration_")) v4Durations[k.replace("__v4duration_", "")] = v;
+    else if (k.startsWith("__v4animate_")) v4Animations[k.replace("__v4animate_", "")] = v;
+    else if (k === "__v4SpacingBase") v4SpacingBase = v;
+  }
+
+  // ── Tailwind v4: generate standard spacing scale from base unit ──────────────
+  let v4SpacingScale = {};
+  if (v4SpacingBase) {
+    const baseRe = /^([\d.]+)(rem|px)$/.exec(v4SpacingBase);
+    if (baseRe) {
+      const baseVal = parseFloat(baseRe[1]);
+      const unit = baseRe[2];
+      // Standard Tailwind scale multipliers
+      const steps = [0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96];
+      for (const s of steps) {
+        const val = s === 0 ? "0px" : `${Math.round(baseVal * s * 1000) / 1000}${unit}`;
+        v4SpacingScale[s === 0 ? "0" : String(s)] = val;
+      }
+      // Also add 'px' = 1px
+      v4SpacingScale["px"] = "1px";
+    }
+  }
+
+  // ── Merge: Tailwind v3 theme takes priority; v4 CSS vars fill gaps ─────────
+  const mergedShadows = { ...v4Shadows, ...normalizeThemeObj(twTheme.shadows) };
+  const mergedSpacing = Object.keys(normalizeThemeObj(twTheme.spacing)).length > 0
+    ? normalizeThemeObj(twTheme.spacing)
+    : v4SpacingScale;
+  const mergedEasings = { ...v4Easings, ...normalizeThemeObj(twTheme.transitionTimingFunction) };
+  const mergedDurations = { ...v4Durations, ...normalizeThemeObj(twTheme.transitionDuration) };
+  const mergedAnimations = { ...v4Animations, ...normalizeThemeObj(twTheme.animation) };
+
   return {
     colors: foundationsColors,
     typography,
     radius,
-    shadows: normalizeThemeObj(twTheme.shadows),
-    spacing: normalizeThemeObj(twTheme.spacing),
+    shadows: mergedShadows,
+    spacing: mergedSpacing,
     breakpoints: normalizeThemeObj(twTheme.breakpoints),
     zIndex: normalizeThemeObj(twTheme.zIndex),
     motion: {
-      transitionDuration: normalizeThemeObj(twTheme.transitionDuration),
-      transitionTimingFunction: normalizeThemeObj(twTheme.transitionTimingFunction),
-      animation: normalizeThemeObj(twTheme.animation),
+      transitionDuration: mergedDurations,
+      transitionTimingFunction: mergedEasings,
+      animation: mergedAnimations,
     },
   };
 }
 
+/**
+ * Counts actual Tailwind utility class usage in src/ files.
+ * Returns top-N used tokens for spacing, shadows, z-index, border-radius.
+ * This shows what the PROJECT ACTUALLY USES — not just theoretical design tokens.
+ */
+function extractTokenUsage() {
+  if (!fs.existsSync(SRC_DIR)) return null;
+  const files = getAllTsxJsxInDir(SRC_DIR);
+  if (!Array.isArray(files) || files.length === 0) return null;
+
+  const spacingCounts = new Map();
+  const shadowCounts = new Map();
+  const zIndexCounts = new Map();
+  const radiusCounts = new Map();
+  const animateCounts = new Map();
+
+  // Spacing utilities: gap-*, p-*, px-*, py-*, pt-*, pb-*, pl-*, pr-*, m-*, mx-*, my-*, mt-*, mb-*, ml-*, mr-*, space-*, w-*, h-*
+  const spacingRe = /\b(gap|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|space-x|space-y|w|h|size|inset|top|bottom|left|right|min-w|min-h|max-w|max-h)-((?:\d+(\.\d+)?|px|full|screen|auto|fit|max|min|svh|dvh|svw|dvw))\b/g;
+  // Shadow utilities: shadow-sm, shadow-md, shadow-lg, shadow-xl, shadow-2xl, shadow-inner, shadow-none, shadow (bare)
+  const shadowRe = /\bshadow(?:-(sm|md|lg|xl|2xl|inner|none))?\b(?!-color|-opacity|-ring)/g;
+  // Z-index utilities: z-0, z-10, z-20, z-30, z-40, z-50, z-auto
+  const zRe = /\bz-(\d+|auto)\b/g;
+  // Border-radius utilities: rounded, rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl, rounded-3xl, rounded-full, rounded-none
+  const roundedRe = /\brounded(?:-(none|sm|md|lg|xl|2xl|3xl|full|t|r|b|l|tl|tr|br|bl|s|e|ss|se|es|ee|[a-z]+(?:-(?:none|sm|md|lg|xl|2xl|3xl|full))?))?(?!\w)/g;
+  // Animate utilities: animate-spin, animate-ping, animate-pulse, animate-bounce, animate-none
+  const animateRe = /\banimate-(spin|ping|pulse|bounce|none|[\w-]+)\b/g;
+
+  for (const rel of files) {
+    if (rel.includes("stories")) continue;
+    let content;
+    try {
+      content = fs.readFileSync(path.join(SRC_DIR, rel), "utf-8");
+    } catch (_) { continue; }
+
+    // Spacing
+    let m;
+    const spacingReCopy = new RegExp(spacingRe.source, "g");
+    while ((m = spacingReCopy.exec(content)) !== null) {
+      const key = `${m[1]}-${m[2]}`;
+      spacingCounts.set(key, (spacingCounts.get(key) || 0) + 1);
+    }
+
+    // Shadows
+    const shadowReCopy = new RegExp(shadowRe.source, "g");
+    while ((m = shadowReCopy.exec(content)) !== null) {
+      const key = m[1] ? `shadow-${m[1]}` : "shadow";
+      shadowCounts.set(key, (shadowCounts.get(key) || 0) + 1);
+    }
+
+    // Z-index
+    const zReCopy = new RegExp(zRe.source, "g");
+    while ((m = zReCopy.exec(content)) !== null) {
+      const key = `z-${m[1]}`;
+      zIndexCounts.set(key, (zIndexCounts.get(key) || 0) + 1);
+    }
+
+    // Border radius
+    const roundedReCopy = new RegExp(roundedRe.source, "g");
+    while ((m = roundedReCopy.exec(content)) !== null) {
+      // Normalize: only count base rounded-* (not directional like rounded-t-lg)
+      const suffix = m[1] || "";
+      const isDirectional = /^(t|r|b|l|tl|tr|br|bl|s|e|ss|se|es|ee)(-|$)/.test(suffix);
+      if (!isDirectional) {
+        const key = suffix ? `rounded-${suffix}` : "rounded";
+        radiusCounts.set(key, (radiusCounts.get(key) || 0) + 1);
+      }
+    }
+
+    // Animate
+    const animateReCopy = new RegExp(animateRe.source, "g");
+    while ((m = animateReCopy.exec(content)) !== null) {
+      const key = `animate-${m[1]}`;
+      animateCounts.set(key, (animateCounts.get(key) || 0) + 1);
+    }
+  }
+
+  const toTop = (map, n) =>
+    [...map.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, n)
+      .map(([token, count]) => ({ token, count }));
+
+  return {
+    spacing: toTop(spacingCounts, 20),
+    shadows: toTop(shadowCounts, 10),
+    zIndex: toTop(zIndexCounts, 10),
+    radius: toTop(radiusCounts, 10),
+    animations: toTop(animateCounts, 8),
+  };
+}
+
 function extractButtonUsage() {
   if (!fs.existsSync(SRC_DIR)) return null;
   const files = getAllTsxJsxInDir(SRC_DIR);
@@ -1650,6 +1880,10 @@ function scan() {
   if (buttonUsage) {
     foundations.buttonUsage = buttonUsage;
   }
+  const tokenUsage = extractTokenUsage();
+  if (tokenUsage) {
+    foundations.tokenUsage = tokenUsage;
+  }
   const componentSuggestions = extractComponentSuggestions();
   const unreleasedSectionCandidates = extractUnreleasedSectionCandidates();
   const output = {

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

@@ -1442,6 +1442,433 @@ function writeFoundationsStories(foundations) {
     fs.writeFileSync(path.join(foundationsDir, "Buttons.stories.tsx"), buttonsContent, "utf-8");
     console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Buttons.stories.tsx")));
   }
+
+  // ── SPACING & LAYOUT ────────────────────────────────────────────────────────
+  {
+    const spacing = foundations?.spacing || {};
+    const breakpoints = foundations?.breakpoints || {};
+
+    function remToPxNum(val) {
+      const m = String(val).match(/^([\d.]+)rem$/);
+      if (m) return Math.round(parseFloat(m[1]) * 16);
+      const m2 = String(val).match(/^([\d.]+)px$/);
+      if (m2) return parseInt(m2[1]);
+      return -1;
+    }
+
+    const spacingRows = Object.entries(spacing)
+      .map(([token, value]) => {
+        const px = remToPxNum(value);
+        const label = px >= 0 ? `${value} · ${px}px` : value;
+        const barWidth = Math.min(Math.max(px, 0), 240);
+        return { token, label, barWidth };
+      })
+      .sort((a, b) => {
+        const na = parseFloat(a.token), nb = parseFloat(b.token);
+        if (!isNaN(na) && !isNaN(nb)) return na - nb;
+        if (!isNaN(na)) return -1;
+        if (!isNaN(nb)) return 1;
+        return a.token.localeCompare(b.token);
+      });
+
+    const breakpointRows = Object.entries(breakpoints)
+      .map(([token, value]) => ({ token, value }))
+      .sort((a, b) => parseInt(a.value) - parseInt(b.value));
+
+    const usedSpacing = (foundations?.tokenUsage?.spacing || []).slice(0, 16);
+    const spacingContent = [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Spacing & Layout\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const spacingTokens: { token: string; label: string; barWidth: number }[] = ${JSON.stringify(spacingRows)};`,
+      `const breakpointTokens: { token: string; value: string }[] = ${JSON.stringify(breakpointRows)};`,
+      `const usedSpacing: { token: string; count: number }[] = ${JSON.stringify(usedSpacing)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div style={{ fontFamily: \"system-ui,sans-serif\", padding: 32, maxWidth: 760, color: \"#111\" }}>",
+      "      <h2 style={{ fontSize: 20, fontWeight: 700, margin: \"0 0 4px\" }}>Spacing Scale</h2>",
+      "      <p style={{ fontSize: 13, color: \"#888\", margin: \"0 0 24px\" }}>Base unit: 0.25rem = 4px · built on an 8px grid system</p>",
+      "      {usedSpacing.length > 0 && (",
+      "        <>",
+      "          <h3 style={{ fontSize: 14, fontWeight: 600, margin: \"0 0 10px\", color: \"#374151\" }}>🎯 Most used in this project</h3>",
+      "          <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 6, marginBottom: 28 }}>",
+      "            {usedSpacing.map(({ token, count }) => (",
+      "              <span key={token} style={{ padding: \"3px 10px\", background: \"#ede9fe\", color: \"#5b21b6\", borderRadius: 20, fontSize: 12, fontWeight: 500 }}>",
+      "                {token} <span style={{ opacity: 0.6 }}>×{count}</span>",
+      "              </span>",
+      "            ))}",
+      "          </div>",
+      "        </>",
+      "      )}",
+      "      {spacingTokens.length === 0 ? (",
+      "        <p style={{ color: \"#999\", fontSize: 13 }}>No spacing tokens detected. Ensure <code>tailwind.config.ts</code> is present.</p>",
+      "      ) : (",
+      "        <div style={{ display: \"flex\", flexDirection: \"column\", gap: 3 }}>",
+      "          {spacingTokens.map(({ token, label, barWidth }) => (",
+      "            <div key={token} style={{ display: \"flex\", alignItems: \"center\", gap: 10, minHeight: 24 }}>",
+      "              <span style={{ width: 40, fontSize: 11, color: \"#9ca3af\", textAlign: \"right\", flexShrink: 0, fontVariantNumeric: \"tabular-nums\" }}>{token}</span>",
+      "              <div style={{ width: Math.max(barWidth, 2), height: 16, background: barWidth === 0 ? \"transparent\" : \"linear-gradient(90deg,#818cf8,#6366f1)\", borderRadius: 3, flexShrink: 0, border: barWidth === 0 ? \"1px dashed #555\" : \"none\", boxSizing: \"border-box\" as any }} />",
+      "              <code style={{ fontSize: 11, color: \"#6b7280\" }}>{label}</code>",
+      "            </div>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "      {breakpointTokens.length > 0 && (",
+      "        <>",
+      "          <h3 style={{ fontSize: 16, fontWeight: 600, margin: \"40px 0 12px\" }}>Breakpoints</h3>",
+      "          <div style={{ display: \"grid\", gridTemplateColumns: \"repeat(auto-fill, minmax(130px, 1fr))\", gap: 8 }}>",
+      "            {breakpointTokens.map(({ token, value }) => (",
+      "              <div key={token} style={{ padding: \"10px 12px\", border: \"1px solid #e5e7eb\", borderRadius: 8, background: \"#fafafa\" }}>",
+      "                <div style={{ fontSize: 14, fontWeight: 600, marginBottom: 2 }}>{token}</div>",
+      "                <code style={{ fontSize: 12, color: \"#6b7280\" }}>{value}</code>",
+      "              </div>",
+      "            ))}",
+      "          </div>",
+      "        </>",
+      "      )}",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+    fs.writeFileSync(path.join(foundationsDir, "Spacing.stories.tsx"), spacingContent, "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Spacing.stories.tsx")));
+  }
+
+  // ── ELEVATION & SHADOWS ─────────────────────────────────────────────────────
+  {
+    const shadows = foundations?.shadows || {};
+    const zIndex = foundations?.zIndex || {};
+
+    const shadowOrder = ["none", "sm", "DEFAULT", "md", "lg", "xl", "2xl", "3xl", "inner"];
+    const shadowRows = Object.entries(shadows)
+      .sort(([a], [b]) => {
+        const ia = shadowOrder.indexOf(a), ib = shadowOrder.indexOf(b);
+        if (ia >= 0 && ib >= 0) return ia - ib;
+        if (ia >= 0) return -1;
+        if (ib >= 0) return 1;
+        return a.localeCompare(b);
+      })
+      .map(([token, value]) => ({ token, value }));
+
+    const zSemanticLabels = { "0": "Base layer", "10": "Low elevation", "20": "Dropdown / popover", "30": "Sticky header", "40": "Fixed overlay", "50": "Modal / dialog", "auto": "Auto" };
+    const zIndexRows = Object.entries(zIndex)
+      .sort(([a], [b]) => {
+        if (a === "auto") return 1;
+        if (b === "auto") return -1;
+        return parseInt(a) - parseInt(b);
+      })
+      .map(([token, value]) => ({ token, value, label: zSemanticLabels[token] || "" }));
+
+    const usedShadows = foundations?.tokenUsage?.shadows || [];
+    const usedZIndex = foundations?.tokenUsage?.zIndex || [];
+
+    // Build shadow CSS values from actual Tailwind defaults (for visual demo when no CSS vars found)
+    const shadowDefaults = {
+      "shadow-sm": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)",
+      "shadow": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
+      "shadow-md": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
+      "shadow-lg": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
+      "shadow-xl": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)",
+      "shadow-2xl": "0 25px 50px -12px rgb(0 0 0 / 0.25)",
+    };
+    // If token CSS values available use those; otherwise use defaults keyed by used token names
+    const shadowDisplayRows = shadowRows.length > 0
+      ? shadowRows
+      : usedShadows.map(({ token }) => ({ token, value: shadowDefaults[token] || "" })).filter((r) => r.value);
+
+    const zIndexSemantics = { "z-0": "Base", "z-10": "Low / hover", "z-20": "Dropdown", "z-30": "Sticky", "z-40": "Fixed", "z-50": "Modal / overlay" };
+
+    const elevationContent = [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Elevation & Shadows\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const shadowTokens: { token: string; value: string }[] = ${JSON.stringify(shadowDisplayRows)};`,
+      `const zIndexTokens: { token: string; value: string; label: string }[] = ${JSON.stringify(zIndexRows)};`,
+      `const usedShadows: { token: string; count: number }[] = ${JSON.stringify(usedShadows)};`,
+      `const usedZIndex: { token: string; count: number }[] = ${JSON.stringify(usedZIndex)};`,
+      `const zSemantics: Record<string, string> = ${JSON.stringify(zIndexSemantics)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div style={{ fontFamily: \"system-ui,sans-serif\", padding: 32, background: \"#f1f5f9\", minHeight: 400 }}>",
+      "      <h2 style={{ fontSize: 20, fontWeight: 700, margin: \"0 0 4px\", color: \"#111\" }}>Elevation & Shadows</h2>",
+      "      <p style={{ fontSize: 13, color: \"#888\", margin: \"0 0 32px\" }}>Depth is communicated through layered shadow levels</p>",
+      "      <h3 style={{ fontSize: 15, fontWeight: 600, margin: \"0 0 14px\", color: \"#374151\" }}>Shadow Scale</h3>",
+      "      {usedShadows.length > 0 && (",
+      "        <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 6, marginBottom: 16 }}>",
+      "          {usedShadows.map(({ token, count }) => (",
+      "            <span key={token} style={{ padding: \"3px 10px\", background: \"#dbeafe\", color: \"#1e40af\", borderRadius: 20, fontSize: 12, fontWeight: 500 }}>",
+      "              {token} <span style={{ opacity: 0.6 }}>×{count}</span>",
+      "            </span>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "      {shadowTokens.length === 0 ? (",
+      "        <p style={{ color: \"#999\", fontSize: 13, marginBottom: 32 }}>No shadow tokens detected.</p>",
+      "      ) : (",
+      "        <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 24, marginBottom: 48 }}>",
+      "          {shadowTokens.map(({ token, value }) => (",
+      "            <div key={token} style={{ display: \"flex\", flexDirection: \"column\", alignItems: \"center\", gap: 10 }}>",
+      "              <div style={{ width: 80, height: 80, background: \"#fff\", borderRadius: 10, boxShadow: value, border: token === \"none\" ? \"1px dashed #ccc\" : \"none\" }} />",
+      "              <span style={{ fontSize: 12, fontWeight: 600, color: \"#374151\" }}>{token === \"DEFAULT\" ? \"default\" : token}</span>",
+      "            </div>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "      <h3 style={{ fontSize: 15, fontWeight: 600, margin: \"0 0 14px\", color: \"#374151\" }}>Z-Index Scale</h3>",
+      "      {usedZIndex.length > 0 && (",
+      "        <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 6, marginBottom: 14 }}>",
+      "          {usedZIndex.map(({ token, count }) => (",
+      "            <span key={token} style={{ padding: \"3px 10px\", background: \"#d1fae5\", color: \"#065f46\", borderRadius: 20, fontSize: 12, fontWeight: 500 }}>",
+      "              {token} <span style={{ opacity: 0.6 }}>×{count}</span>",
+      "            </span>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "      {zIndexTokens.length === 0 && usedZIndex.length === 0 ? (",
+      "        <p style={{ color: \"#999\", fontSize: 13 }}>No z-index tokens detected.</p>",
+      "      ) : zIndexTokens.length > 0 ? (",
+      "        <div style={{ display: \"flex\", flexDirection: \"column\", gap: 6, maxWidth: 380 }}>",
+      "          {zIndexTokens.map(({ token, value, label }) => (",
+      "            <div key={token} style={{ display: \"flex\", alignItems: \"center\", gap: 12, padding: \"8px 14px\", background: \"#fff\", borderRadius: 8, border: \"1px solid #e5e7eb\" }}>",
+      "              <span style={{ width: 36, fontSize: 15, fontWeight: 700, color: \"#6366f1\", textAlign: \"right\", flexShrink: 0, fontVariantNumeric: \"tabular-nums\" }}>{value}</span>",
+      "              <div>",
+      "                <span style={{ fontSize: 12, fontWeight: 600 }}>{token}</span>",
+      "                {label ? <span style={{ fontSize: 11, color: \"#9ca3af\", marginLeft: 8 }}>{label}</span> : null}",
+      "              </div>",
+      "            </div>",
+      "          ))}",
+      "        </div>",
+      "      ) : (",
+      "        <div style={{ display: \"flex\", flexDirection: \"column\", gap: 6, maxWidth: 380 }}>",
+      "          {usedZIndex.map(({ token, count }) => (",
+      "            <div key={token} style={{ display: \"flex\", alignItems: \"center\", gap: 12, padding: \"8px 14px\", background: \"#fff\", borderRadius: 8, border: \"1px solid #e5e7eb\" }}>",
+      "              <span style={{ width: 36, fontSize: 15, fontWeight: 700, color: \"#6366f1\", textAlign: \"right\", flexShrink: 0 }}>{token.replace('z-','')}</span>",
+      "              <div>",
+      "                <span style={{ fontSize: 12, fontWeight: 600 }}>{token}</span>",
+      "                {zSemantics[token] ? <span style={{ fontSize: 11, color: \"#9ca3af\", marginLeft: 8 }}>{zSemantics[token]}</span> : null}",
+      "                <span style={{ fontSize: 11, color: \"#d1d5db\", marginLeft: 8 }}>×{count} usages</span>",
+      "              </div>",
+      "            </div>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+    fs.writeFileSync(path.join(foundationsDir, "Elevation.stories.tsx"), elevationContent, "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Elevation.stories.tsx")));
+  }
+
+  // ── BORDER & RADIUS ─────────────────────────────────────────────────────────
+  {
+    const radiusData = foundations?.radius || {};
+    const baseRadius = radiusData.base || null;
+    const borderRadiusObj = radiusData.borderRadius || {};
+
+    const radiusScale = { ...(baseRadius ? { base: baseRadius } : {}), ...borderRadiusObj };
+    const radiusOrder = ["none", "sm", "DEFAULT", "base", "md", "lg", "xl", "2xl", "3xl", "full"];
+
+    const radiusRows = Object.entries(radiusScale)
+      .sort(([a], [b]) => {
+        const ia = radiusOrder.indexOf(a), ib = radiusOrder.indexOf(b);
+        if (ia >= 0 && ib >= 0) return ia - ib;
+        const va = parseFloat(a), vb = parseFloat(b);
+        if (!isNaN(va) && !isNaN(vb)) return va - vb;
+        return a.localeCompare(b);
+      })
+      .map(([token, value]) => {
+        const m = String(value).match(/^([\d.]+)rem$/);
+        const px = m ? Math.round(parseFloat(m[1]) * 16) + "px" : null;
+        const isFull = parseInt(String(value)) >= 999;
+        const displayValue = px && px !== value ? `${value} · ${px}` : value;
+        return { token, value, displayValue, isFull };
+      });
+
+    const usedRadius = (foundations?.tokenUsage?.radius || []).slice(0, 12);
+
+    const borderContent = [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Border & Radius\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const radiusTokens: { token: string; value: string; displayValue: string; isFull: boolean }[] = ${JSON.stringify(radiusRows)};`,
+      `const usedRadius: { token: string; count: number }[] = ${JSON.stringify(usedRadius)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div style={{ fontFamily: \"system-ui,sans-serif\", padding: 32, maxWidth: 800 }}>",
+      "      <h2 style={{ fontSize: 20, fontWeight: 700, margin: \"0 0 4px\" }}>Border & Radius</h2>",
+      "      <p style={{ fontSize: 13, color: \"#888\", margin: \"0 0 32px\" }}>Corner radius scale — from sharp edges to fully rounded</p>",
+      "      {usedRadius.length > 0 && (",
+      "        <div style={{ marginBottom: 28 }}>",
+      "          <p style={{ fontSize: 12, color: \"#6b7280\", margin: \"0 0 8px\", fontWeight: 500 }}>Most used in this project</p>",
+      "          <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 6 }}>",
+      "            {usedRadius.map(({ token, count }) => (",
+      "              <span key={token} style={{ padding: \"3px 10px\", background: \"#fce7f3\", color: \"#9d174d\", borderRadius: 20, fontSize: 12, fontWeight: 500 }}>",
+      "                {token} <span style={{ opacity: 0.6 }}>×{count}</span>",
+      "              </span>",
+      "            ))}",
+      "          </div>",
+      "        </div>",
+      "      )}",
+      "      {radiusTokens.length === 0 ? (",
+      "        <p style={{ color: \"#999\", fontSize: 13 }}>No border-radius tokens detected. Add <code>borderRadius</code> to <code>tailwind.config.ts</code>.</p>",
+      "      ) : (",
+      "        <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 28 }}>",
+      "          {radiusTokens.map(({ token, value, displayValue, isFull }) => (",
+      "            <div key={token} style={{ display: \"flex\", flexDirection: \"column\", alignItems: \"center\", gap: 10 }}>",
+      "              <div style={{",
+      "                width: isFull ? 64 : 72,",
+      "                height: isFull ? 64 : 56,",
+      "                background: \"linear-gradient(135deg,#818cf8,#6366f1)\",",
+      "                borderRadius: isFull ? \"50%\" : value === \"0px\" || value === \"0\" ? 0 : value,",
+      "                flexShrink: 0,",
+      "              }} />",
+      "              <div style={{ textAlign: \"center\" }}>",
+      "                <div style={{ fontSize: 12, fontWeight: 600, marginBottom: 2 }}>{token === \"DEFAULT\" ? \"default\" : token}</div>",
+      "                <code style={{ fontSize: 11, color: \"#9ca3af\" }}>{displayValue}</code>",
+      "              </div>",
+      "            </div>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+    fs.writeFileSync(path.join(foundationsDir, "BorderRadius.stories.tsx"), borderContent, "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "BorderRadius.stories.tsx")));
+  }
+
+  // ── MOTION & INTERACTION ────────────────────────────────────────────────────
+  {
+    const motion = foundations?.motion || {};
+    const durations = motion.transitionDuration || {};
+    const easings = motion.transitionTimingFunction || {};
+    const animations = motion.animation || {};
+
+    const durationRows = Object.entries(durations)
+      .filter(([k]) => k !== "0" && k !== "DEFAULT")
+      .sort(([a], [b]) => parseInt(a) - parseInt(b))
+      .map(([token, value]) => ({ token, value }));
+
+    const easingRows = Object.entries(easings)
+      .filter(([k]) => k !== "DEFAULT")
+      .map(([token, value]) => ({ token, value }));
+
+    const animationRows = Object.entries(animations)
+      .filter(([k]) => k !== "none")
+      .map(([token, value]) => ({ token, value }));
+
+    const usedAnimations = (foundations?.tokenUsage?.animations || []).slice(0, 8);
+
+    const motionContent = [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "import { useState } from \"react\";",
+      "",
+      "const meta = { title: \"Foundations/Motion & Interaction\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const durationTokens: { token: string; value: string }[] = ${JSON.stringify(durationRows)};`,
+      `const easingTokens: { token: string; value: string }[] = ${JSON.stringify(easingRows)};`,
+      `const animationTokens: { token: string; value: string }[] = ${JSON.stringify(animationRows)};`,
+      `const usedAnimations: { token: string; count: number }[] = ${JSON.stringify(usedAnimations)};`,
+      "",
+      "",
+      "function DurationDemo({ token, value }: { token: string; value: string }) {",
+      "  const [active, setActive] = useState(false);",
+      "  return (",
+      "    <div style={{ display: \"flex\", alignItems: \"center\", gap: 16 }}>",
+      "      <span style={{ width: 40, fontSize: 12, color: \"#9ca3af\", textAlign: \"right\", flexShrink: 0, fontVariantNumeric: \"tabular-nums\" }}>{token}</span>",
+      "      <code style={{ width: 68, fontSize: 12, color: \"#6b7280\", flexShrink: 0 }}>{value}</code>",
+      "      <div",
+      "        style={{ position: \"relative\", width: 220, height: 32, background: \"#f1f5f9\", borderRadius: 8, cursor: \"pointer\", overflow: \"hidden\", flexShrink: 0 }}",
+      "        onClick={() => setActive((a) => !a)}",
+      "      >",
+      "        <div style={{",
+      "          position: \"absolute\",",
+      "          top: 4, left: active ? 172 : 4,",
+      "          width: 44, height: 24,",
+      "          background: \"linear-gradient(90deg,#818cf8,#6366f1)\",",
+      "          borderRadius: 6,",
+      "          transition: `left ${value} cubic-bezier(0.4,0,0.2,1)`,",
+      "        }} />",
+      "      </div>",
+      "      <span style={{ fontSize: 11, color: \"#d1d5db\" }}>click</span>",
+      "    </div>",
+      "  );",
+      "}",
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div style={{ fontFamily: \"system-ui,sans-serif\", padding: 32, maxWidth: 700, color: \"#111\" }}>",
+      "      <h2 style={{ fontSize: 20, fontWeight: 700, margin: \"0 0 4px\" }}>Motion & Interaction</h2>",
+      "      <p style={{ fontSize: 13, color: \"#888\", margin: \"0 0 32px\" }}>Consistent timing and easing for smooth, intentional motion</p>",
+      "      {usedAnimations.length > 0 && (",
+      "        <div style={{ marginBottom: 28 }}>",
+      "          <p style={{ fontSize: 12, color: \"#6b7280\", margin: \"0 0 8px\", fontWeight: 500 }}>Used animations in this project</p>",
+      "          <div style={{ display: \"flex\", flexWrap: \"wrap\", gap: 6 }}>",
+      "            {usedAnimations.map(({ token, count }) => (",
+      "              <span key={token} style={{ padding: \"3px 10px\", background: \"#d1fae5\", color: \"#065f46\", borderRadius: 20, fontSize: 12, fontWeight: 500 }}>",
+      "                {token} <span style={{ opacity: 0.6 }}>×{count}</span>",
+      "              </span>",
+      "            ))}",
+      "          </div>",
+      "        </div>",
+      "      )}",
+      "      <h3 style={{ fontSize: 15, fontWeight: 600, margin: \"0 0 14px\", color: \"#374151\" }}>Duration</h3>",
+      "      {durationTokens.length === 0 ? (",
+      "        <p style={{ color: \"#999\", fontSize: 13, marginBottom: 32 }}>No duration tokens detected.</p>",
+      "      ) : (",
+      "        <div style={{ display: \"flex\", flexDirection: \"column\", gap: 10, marginBottom: 40 }}>",
+      "          {durationTokens.map((d) => <DurationDemo key={d.token} token={d.token} value={d.value} />)}",
+      "        </div>",
+      "      )}",
+      "      <h3 style={{ fontSize: 15, fontWeight: 600, margin: \"0 0 14px\", color: \"#374151\" }}>Easing</h3>",
+      "      {easingTokens.length === 0 ? (",
+      "        <p style={{ color: \"#999\", fontSize: 13, marginBottom: 32 }}>No easing tokens detected.</p>",
+      "      ) : (",
+      "        <div style={{ display: \"flex\", flexDirection: \"column\", gap: 6, marginBottom: 40, maxWidth: 500 }}>",
+      "          {easingTokens.map(({ token, value }) => (",
+      "            <div key={token} style={{ display: \"flex\", alignItems: \"center\", gap: 12, padding: \"8px 12px\", background: \"#f8fafc\", borderRadius: 8, border: \"1px solid #e5e7eb\" }}>",
+      "              <span style={{ width: 64, fontSize: 12, fontWeight: 600, flexShrink: 0 }}>{token}</span>",
+      "              <code style={{ fontSize: 11, color: \"#6b7280\" }}>{value}</code>",
+      "            </div>",
+      "          ))}",
+      "        </div>",
+      "      )}",
+      "      {animationTokens.length > 0 && (",
+      "        <>",
+      "          <h3 style={{ fontSize: 15, fontWeight: 600, margin: \"0 0 14px\", color: \"#374151\" }}>Animations</h3>",
+      "          <div style={{ display: \"flex\", flexDirection: \"column\", gap: 4 }}>",
+      "            {animationTokens.map(({ token, value }) => (",
+      "              <div key={token} style={{ display: \"flex\", gap: 12, padding: \"7px 0\", borderBottom: \"1px solid #f0f0f0\", alignItems: \"flex-start\" }}>",
+      "                <span style={{ width: 128, fontSize: 12, fontWeight: 600, flexShrink: 0, paddingTop: 1 }}>{token}</span>",
+      "                <code style={{ fontSize: 11, color: \"#9ca3af\", wordBreak: \"break-all\" as any }}>{value}</code>",
+      "              </div>",
+      "            ))}",
+      "          </div>",
+      "        </>",
+      "      )}",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+    fs.writeFileSync(path.join(foundationsDir, "Motion.stories.tsx"), motionContent, "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Motion.stories.tsx")));
+  }
 }
 
 function writeComponentSuggestionsStory(componentSuggestions) {