vibe-design-system 2.8.74 → 2.8.75

package/package.json

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

package/vds-core-template/scan.mjs

@@ -522,26 +522,74 @@ function extractBrandAssets() {
 function extractLucideIconsUsed(srcDir) {
   const allFiles = getAllTsxJsxInDir(srcDir);
   const files = allFiles.filter((rel) => !/^stories[/\\]/.test(rel.replace(/\\/g, "/")));
+  // Pass 1: collect all imported icon names + track alias renames
   const names = new Set();
+  const aliasMap = new Map(); // localAlias → originalName (for `import { X as Y }`)
   const importRe = /import\s*\{([^}]+)\}\s*from\s*["']lucide-react["']/g;
+  const fileContents = new Map();
   for (const rel of files) {
     const fullPath = path.join(srcDir, rel);
     try {
       const content = fs.readFileSync(fullPath, "utf-8");
+      fileContents.set(rel, content);
       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);
+          const asMatch = trimmed.match(/^(\w+)\s+as\s+(\w+)/);
+          if (asMatch) {
+            names.add(asMatch[1]);
+            aliasMap.set(asMatch[2], asMatch[1]); // Y → X
+          } else {
+            const name = trimmed.split(/\s+/)[0];
+            if (name && /^[A-Z][a-zA-Z0-9]*$/.test(name)) names.add(name);
+          }
         });
       }
     } catch (_) {}
     importRe.lastIndex = 0;
   }
-  return [...names].sort();
+  if (names.size === 0) return [];
+
+  // Pass 2: count JSX usages per icon per component file
+  // Build lookup: all names + aliases → canonical icon name
+  const nameArr = [...names];
+  const allLocalNames = new Set([...nameArr]);
+  for (const [alias, orig] of aliasMap) if (names.has(orig)) allLocalNames.add(alias);
+
+  // usageCounts: iconName → Map<componentName, count>
+  const usageCounts = new Map();
+  for (const n of nameArr) usageCounts.set(n, new Map());
+
+  // JSX tag regex: matches <IconName, <IconName/ or <IconName>
+  const jsxTagRe = new RegExp(`<(${[...allLocalNames].join("|")})(?=[\\s/>])`, "g");
+
+  for (const [rel, content] of fileContents) {
+    const componentName = path.basename(rel).replace(/\.(tsx|jsx|ts|js)$/, "");
+    jsxTagRe.lastIndex = 0;
+    let m;
+    while ((m = jsxTagRe.exec(content)) !== null) {
+      const localName = m[1];
+      const canonName = aliasMap.has(localName) ? aliasMap.get(localName) : localName;
+      if (usageCounts.has(canonName)) {
+        const fm = usageCounts.get(canonName);
+        fm.set(componentName, (fm.get(componentName) || 0) + 1);
+      }
+    }
+  }
+
+  return nameArr
+    .map((name) => {
+      const fileMap = usageCounts.get(name) || new Map();
+      const total = [...fileMap.values()].reduce((a, b) => a + b, 0);
+      const topFiles = [...fileMap.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([f]) => f);
+      return { name, total, topFiles };
+    })
+    .sort((a, b) => b.total - a.total || a.name.localeCompare(b.name));
 }
 
 function extractVdsTags(content) {
@@ -1217,27 +1265,68 @@ function getTailwindExtendColors() {
 }
 
 function parseTailwindThemeFromText(raw) {
-  const result = { shadows: {}, spacing: {}, breakpoints: {}, zIndex: {}, transitionDuration: {}, transitionTimingFunction: {}, animation: {}, colors: {} };
-  try {
-    const spacingM = raw.match(/spacing\s*:\s*\{([\s\S]*?)\}/);
-    if (spacingM) {
-      const re = /["']?([\w.-]+)["']?\s*:\s*["']([^"']+)["']/g;
-      let m;
-      while ((m = re.exec(spacingM[1])) !== null) result.spacing[m[1]] = m[2];
+  const result = {
+    shadows: {}, spacing: {}, breakpoints: {}, zIndex: {},
+    transitionDuration: {}, transitionTimingFunction: {}, animation: {}, colors: {},
+    fontSize: {}, fontWeight: {},
+  };
+  // Helper: extract a shallow key:value block (handles one level of nesting)
+  function extractBlock(key) {
+    // Match "key: {" and capture until the matching closing brace (one level deep)
+    const re = new RegExp(key + "\\s*:\\s*\\{");
+    const start = raw.search(re);
+    if (start === -1) return null;
+    const open = raw.indexOf("{", start);
+    if (open === -1) return null;
+    let depth = 0, i = open;
+    while (i < raw.length) {
+      if (raw[i] === "{") depth++;
+      else if (raw[i] === "}") { depth--; if (depth === 0) return raw.slice(open + 1, i); }
+      i++;
     }
-    const screensM = raw.match(/screens\s*:\s*\{([\s\S]*?)\}/);
-    if (screensM) {
-      const re = /["']?([\w.-]+)["']?\s*:\s*["']([^"']+)["']/g;
-      let m;
-      while ((m = re.exec(screensM[1])) !== null) result.breakpoints[m[1]] = m[2];
+    return null;
+  }
+  // Helper: parse simple key:"value" pairs from a block string
+  function parseKV(block) {
+    const out = {};
+    if (!block) return out;
+    const re = /["']?([\w.-]+)["']?\s*:\s*["']([^"']+)["']/g;
+    let m;
+    while ((m = re.exec(block)) !== null) out[m[1]] = m[2];
+    return out;
+  }
+  // Helper: parse fontSize which can be string OR [string, {...}] (array form)
+  function parseFontSize(block) {
+    const out = {};
+    if (!block) return out;
+    // Array form: "base": ["1rem", { lineHeight: "1.5rem" }]
+    const arrRe = /["']?([\w.-]+)["']?\s*:\s*\[\s*["']([^"']+)["']/g;
+    let m;
+    while ((m = arrRe.exec(block)) !== null) out[m[1]] = m[2];
+    // Simple string form (fills in what array form missed): "xs": "0.75rem"
+    const strRe = /["']?([\w.-]+)["']?\s*:\s*["']([^"']+)["']/g;
+    while ((m = strRe.exec(block)) !== null) {
+      if (!out[m[1]]) out[m[1]] = m[2];
     }
+    return out;
+  }
+
+  try {
+    result.spacing           = parseKV(extractBlock("spacing"));
+    result.breakpoints       = parseKV(extractBlock("screens"));
+    result.zIndex            = parseKV(extractBlock("zIndex"));
+    result.transitionDuration = parseKV(extractBlock("transitionDuration"));
+    result.transitionTimingFunction = parseKV(extractBlock("transitionTimingFunction"));
+    result.animation         = parseKV(extractBlock("animation"));
+    result.fontWeight        = parseKV(extractBlock("fontWeight"));
+    result.fontSize          = parseFontSize(extractBlock("fontSize"));
   } catch (_) {}
   return result;
 }
 
 /** Resolve Tailwind theme for boxShadow, spacing, screens, zIndex, motion. Uses resolveConfig for .js/.mjs, text-parse for .ts. */
 function getTailwindTheme() {
-  const empty = { shadows: {}, spacing: {}, breakpoints: {}, zIndex: {}, transitionDuration: {}, transitionTimingFunction: {}, animation: {}, colors: {} };
+  const empty = { shadows: {}, spacing: {}, breakpoints: {}, zIndex: {}, transitionDuration: {}, transitionTimingFunction: {}, animation: {}, colors: {}, fontSize: {}, fontWeight: {} };
   const twPath = path.join(PROJECT_ROOT, "tailwind.config.js");
   const twPathMjs = path.join(PROJECT_ROOT, "tailwind.config.mjs");
   const twPathTs = path.join(PROJECT_ROOT, "tailwind.config.ts");
@@ -1260,6 +1349,8 @@ function getTailwindTheme() {
         transitionTimingFunction: toObj(theme.transitionTimingFunction),
         animation: toObj(theme.animation),
         colors: toObj(theme.colors),
+        fontSize: toObj(theme.fontSize),
+        fontWeight: toObj(theme.fontWeight),
       };
     } catch (_) {
       return empty;
@@ -1379,6 +1470,14 @@ function extractFoundations() {
         });
       if (typeScale.length > 0) typography.typeScale = typeScale;
 
+      // Tailwind v4: font-weight custom props (--font-weight-*)
+      const fontWeightVarRe = /--font-weight-([\w-]+)\s*:\s*([^;\n]+);/g;
+      let fwvm;
+      while ((fwvm = fontWeightVarRe.exec(css)) !== null) {
+        if (!typography.fontWeightScale) typography.fontWeightScale = {};
+        typography.fontWeightScale[fwvm[1]] = fwvm[2].trim();
+      }
+
       // Tailwind v4: extract design tokens from @layer theme { :root { ... } } or bare :root
       // Variables: --spacing (base), --radius-*, --shadow-*, --ease-*, --duration-*, --animate-*
       const v4ThemeVars = {};
@@ -1778,6 +1877,39 @@ function extractFoundations() {
   const mergedDurations = { ...v4Durations, ...normalizeThemeObj(twTheme.transitionDuration) };
   const mergedAnimations = { ...v4Animations, ...normalizeThemeObj(twTheme.animation) };
 
+  // ── Fallback: build typeScale from twTheme.fontSize if CSS vars produced nothing ──
+  if (!typography.typeScale || typography.typeScale.length === 0) {
+    const fsObj = normalizeThemeObj(twTheme.fontSize);
+    const fsEntries = Object.entries(fsObj);
+    if (fsEntries.length > 0) {
+      // Order: canonical Tailwind steps first, then any custom steps
+      const ORDER = ["xs","sm","base","lg","xl","2xl","3xl","4xl","5xl","6xl","7xl","8xl","9xl"];
+      const ordered = [
+        ...ORDER.filter((k) => fsObj[k]).map((k) => [k, fsObj[k]]),
+        ...fsEntries.filter(([k]) => !ORDER.includes(k)),
+      ];
+      typography.typeScale = ordered.map(([step, size]) => {
+        // fontSize can be "[size, {lineHeight: ...}]" (array serialized) or plain "1rem"
+        // After toObj + toString it looks like "1rem,1.5rem" or just "1rem" or "[object Object]"
+        let resolvedSize = size;
+        // Handle tuple-ish form from resolveConfig: e.g. "0.75rem,..." or ["0.75rem",{lineHeight:"1rem"}]
+        if (resolvedSize && resolvedSize.includes(",")) resolvedSize = resolvedSize.split(",")[0].trim();
+        if (!resolvedSize || resolvedSize === "[object Object]") return null;
+        const pxM = resolvedSize.match(/^([\d.]+)rem$/);
+        const px = pxM ? Math.round(parseFloat(pxM[1]) * 16) + "px" : null;
+        return { step, size: resolvedSize, px, lineHeight: null };
+      }).filter(Boolean);
+    }
+  }
+
+  // ── Fallback: build fontWeightScale from twTheme.fontWeight if CSS vars produced nothing ──
+  if (!typography.fontWeightScale || Object.keys(typography.fontWeightScale).length === 0) {
+    const fwObj = normalizeThemeObj(twTheme.fontWeight);
+    if (Object.keys(fwObj).length > 0) {
+      typography.fontWeightScale = fwObj;
+    }
+  }
+
   return {
     colors: foundationsColors,
     typography,

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

@@ -2605,7 +2605,32 @@ function writeFoundationsStories(foundations, components) {
 
   {
     const typo = foundations?.typography || {};
-    const typeScale = Array.isArray(typo.typeScale) ? typo.typeScale : [];
+    // Tailwind v3 default type scale (canonical sizes)
+    const TW_DEFAULT_TYPE_SCALE = [
+      { step: "xs",   size: "0.75rem",  px: "12px", lineHeight: "1rem" },
+      { step: "sm",   size: "0.875rem", px: "14px", lineHeight: "1.25rem" },
+      { step: "base", size: "1rem",     px: "16px", lineHeight: "1.5rem" },
+      { step: "lg",   size: "1.125rem", px: "18px", lineHeight: "1.75rem" },
+      { step: "xl",   size: "1.25rem",  px: "20px", lineHeight: "1.75rem" },
+      { step: "2xl",  size: "1.5rem",   px: "24px", lineHeight: "2rem" },
+      { step: "3xl",  size: "1.875rem", px: "30px", lineHeight: "2.25rem" },
+      { step: "4xl",  size: "2.25rem",  px: "36px", lineHeight: "2.5rem" },
+      { step: "5xl",  size: "3rem",     px: "48px", lineHeight: "1" },
+    ];
+    const TW_DEFAULT_FONT_WEIGHTS = [
+      { token: "thin",       value: "100" },
+      { token: "extralight", value: "200" },
+      { token: "light",      value: "300" },
+      { token: "normal",     value: "400" },
+      { token: "medium",     value: "500" },
+      { token: "semibold",   value: "600" },
+      { token: "bold",       value: "700" },
+      { token: "extrabold",  value: "800" },
+      { token: "black",      value: "900" },
+    ];
+    let typeScale = Array.isArray(typo.typeScale) ? typo.typeScale : [];
+    const typeScaleIsDefault = typeScale.length === 0;
+    if (typeScaleIsDefault) typeScale = TW_DEFAULT_TYPE_SCALE;
     const usedTextSizes = (foundations?.tokenUsage?.textSizes || []);
     const usedTextMap = Object.fromEntries(usedTextSizes.map(({ token, count }) => [token, count]));
 
@@ -2619,11 +2644,23 @@ function writeFoundationsStories(foundations, components) {
       })
       .filter((r) => r.value);
 
-    // Font weights
+    // Font weights — check fontWeightScale (from twTheme.fontWeight), then legacy specific keys, then Tailwind defaults
     const weightKeys = ["fontWeightNormal", "fontWeightMedium", "fontWeightSemibold", "fontWeightBold"];
-    const weightRows = weightKeys
+    let weightRows = weightKeys
       .filter((k) => typo[k])
       .map((k) => ({ token: k, value: String(typo[k]) }));
+    if (weightRows.length === 0 && typo.fontWeightScale && typeof typo.fontWeightScale === "object") {
+      const WGT_ORDER = ["thin","extralight","light","normal","medium","semibold","bold","extrabold","black"];
+      const wEntries = Object.entries(typo.fontWeightScale);
+      wEntries.sort(([a], [b]) => {
+        const ia = WGT_ORDER.indexOf(a), ib = WGT_ORDER.indexOf(b);
+        if (ia >= 0 && ib >= 0) return ia - ib;
+        return parseInt(a) - parseInt(b) || a.localeCompare(b);
+      });
+      weightRows = wEntries.map(([token, value]) => ({ token, value: String(value) }));
+    }
+    const weightRowsIsDefault = weightRows.length === 0;
+    if (weightRowsIsDefault) weightRows = TW_DEFAULT_FONT_WEIGHTS;
 
     // Reverse type scale for display (largest first)
     const scaleDesc = [...typeScale].reverse();
@@ -2639,9 +2676,11 @@ function writeFoundationsStories(foundations, components) {
       "type Story = StoryObj;",
       "",
       `const typeScale: { step: string; size: string; px: string | null; lineHeight: string | null }[] = ${JSON.stringify(scaleDesc)};`,
+      `const typeScaleIsDefault: boolean = ${typeScaleIsDefault};`,
       `const usedTextSizes: { token: string; count: number }[] = ${JSON.stringify(usedTextSizes)};`,
       `const familyRows: { token: string; value: string }[] = ${JSON.stringify(familyRows)};`,
       `const weightRows: { token: string; value: string }[] = ${JSON.stringify(weightRows)};`,
+      `const weightRowsIsDefault: boolean = ${weightRowsIsDefault};`,
       `const sansFamily = ${JSON.stringify(sansFamily)};`,
       "",
       "export const Default: Story = {",
@@ -2664,10 +2703,8 @@ function writeFoundationsStories(foundations, components) {
       "          </div>",
       "        </div>",
       "      )}",
-      "      {typeScale.length === 0 ? (",
-      "        <p style={{ color: \"#999\", fontSize: 13, marginBottom: 32 }}>No type scale detected.</p>",
-      "      ) : (",
-      "        <div style={{ display: \"flex\", flexDirection: \"column\", gap: 0, marginBottom: 48, border: \"1px solid #e5e7eb\", borderRadius: 10, overflow: \"hidden\" }}>",
+      "      {typeScaleIsDefault && <p style={{ fontSize: 12, color: \"#92400e\", background: \"#fef3c7\", border: \"1px solid #fde68a\", borderRadius: 6, padding: \"6px 12px\", marginBottom: 16, display: \"inline-block\" }}>ℹ️ Tailwind defaults — no custom font sizes found in this project</p>}",
+      "      <div style={{ display: \"flex\", flexDirection: \"column\", gap: 0, marginBottom: 48, border: \"1px solid #e5e7eb\", borderRadius: 10, overflow: \"hidden\" }}>",
       "          {typeScale.map(({ step, size, px, lineHeight }, i) => {",
       "            const usage = usedTextSizes.find(u => u.token === `text-${step}`);",
       "            const usageCount = usage?.count;",
@@ -2701,8 +2738,7 @@ function writeFoundationsStories(foundations, components) {
       "              </div>",
       "            );",
       "          })}",
-      "        </div>",
-      "      )}",
+      "      </div>",
       "",
       "      {/* ── FONT FAMILIES ── */}",
       "      {familyRows.length > 0 && (",
@@ -2725,6 +2761,7 @@ function writeFoundationsStories(foundations, components) {
       "      )}",
       "",
       "      {/* ── FONT WEIGHTS ── */}",
+      "      {weightRowsIsDefault && <p style={{ fontSize: 12, color: \"#92400e\", background: \"#fef3c7\", border: \"1px solid #fde68a\", borderRadius: 6, padding: \"6px 12px\", marginBottom: 12, display: \"inline-block\" }}>ℹ️ Tailwind defaults — no custom font weights found in this project</p>}",
       "      {weightRows.length > 0 && (",
       "        <>",
       "          <h3 style={{ fontSize: 15, fontWeight: 600, margin: \"0 0 14px\", color: \"#374151\" }}>Font Weights</h3>",
@@ -3237,6 +3274,13 @@ function writeFoundationsStories(foundations, components) {
   {
     const spacing = foundations?.spacing || {};
     const breakpoints = foundations?.breakpoints || {};
+    // Tailwind v3 default spacing scale
+    const TW_DEFAULT_SPACING = { "0": "0px", "px": "1px", "0.5": "0.125rem", "1": "0.25rem", "1.5": "0.375rem", "2": "0.5rem", "2.5": "0.625rem", "3": "0.75rem", "3.5": "0.875rem", "4": "1rem", "5": "1.25rem", "6": "1.5rem", "7": "1.75rem", "8": "2rem", "9": "2.25rem", "10": "2.5rem", "11": "2.75rem", "12": "3rem", "14": "3.5rem", "16": "4rem", "20": "5rem", "24": "6rem", "28": "7rem", "32": "8rem", "36": "9rem", "40": "10rem", "44": "11rem", "48": "12rem", "52": "13rem", "56": "14rem", "60": "15rem", "64": "16rem", "72": "18rem", "80": "20rem", "96": "24rem" };
+    const TW_DEFAULT_BREAKPOINTS = { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" };
+    const spacingIsDefault = Object.keys(spacing).length === 0;
+    const spacingSource = spacingIsDefault ? TW_DEFAULT_SPACING : spacing;
+    const breakpointsIsDefault = Object.keys(breakpoints).length === 0;
+    const breakpointsSource = breakpointsIsDefault ? TW_DEFAULT_BREAKPOINTS : breakpoints;
 
     function remToPxNum(val) {
       const m = String(val).match(/^([\d.]+)rem$/);
@@ -3246,7 +3290,7 @@ function writeFoundationsStories(foundations, components) {
       return -1;
     }
 
-    const spacingRows = Object.entries(spacing)
+    const spacingRows = Object.entries(spacingSource)
       .map(([token, value]) => {
         const px = remToPxNum(value);
         const label = px >= 0 ? `${value} · ${px}px` : value;
@@ -3261,7 +3305,7 @@ function writeFoundationsStories(foundations, components) {
         return a.token.localeCompare(b.token);
       });
 
-    const breakpointRows = Object.entries(breakpoints)
+    const breakpointRows = Object.entries(breakpointsSource)
       .map(([token, value]) => ({ token, value }))
       .sort((a, b) => parseInt(a.value) - parseInt(b.value));
 
@@ -3275,7 +3319,9 @@ function writeFoundationsStories(foundations, components) {
       "type Story = StoryObj;",
       "",
       `const spacingTokens: { token: string; label: string; barWidth: number }[] = ${JSON.stringify(spacingRows)};`,
+      `const spacingIsDefault: boolean = ${spacingIsDefault};`,
       `const breakpointTokens: { token: string; value: string }[] = ${JSON.stringify(breakpointRows)};`,
+      `const breakpointsIsDefault: boolean = ${breakpointsIsDefault};`,
       `const usedSpacing: { token: string; count: number }[] = ${JSON.stringify(usedSpacing)};`,
       "",
       "export const Default: Story = {",
@@ -3295,22 +3341,20 @@ function writeFoundationsStories(foundations, components) {
       "          </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 }) => (",
+      "      {spacingIsDefault && <p style={{ fontSize: 12, color: \"#92400e\", background: \"#fef3c7\", border: \"1px solid #fde68a\", borderRadius: 6, padding: \"6px 12px\", marginBottom: 16, display: \"inline-block\" }}>ℹ️ Tailwind defaults — no custom spacing detected in this project</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\" : \"var(--color-primary, #6366f1)\", opacity: barWidth === 0 ? 1 : 0.85, 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>",
-      "      )}",
+      "      </div>",
       "      {breakpointTokens.length > 0 && (",
       "        <>",
       "          <h3 style={{ fontSize: 16, fontWeight: 600, margin: \"40px 0 12px\" }}>Breakpoints</h3>",
+      "          {breakpointsIsDefault && <p style={{ fontSize: 12, color: \"#92400e\", background: \"#fef3c7\", border: \"1px solid #fde68a\", borderRadius: 6, padding: \"6px 12px\", marginBottom: 10, display: \"inline-block\" }}>ℹ️ Tailwind defaults — no custom breakpoints found in this project</p>}",
       "          <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\" }}>",
@@ -3346,7 +3390,11 @@ function writeFoundationsStories(foundations, components) {
       .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)
+    // Tailwind v3 default z-index scale
+    const TW_DEFAULT_Z_INDEX = { "0": "0", "10": "10", "20": "20", "30": "30", "40": "40", "50": "50", "auto": "auto" };
+    const zIndexIsDefault = Object.keys(zIndex).length === 0;
+    const zIndexSource = zIndexIsDefault ? TW_DEFAULT_Z_INDEX : zIndex;
+    const zIndexRows = Object.entries(zIndexSource)
       .sort(([a], [b]) => {
         if (a === "auto") return 1;
         if (b === "auto") return -1;
@@ -3384,6 +3432,7 @@ function writeFoundationsStories(foundations, components) {
       "",
       `const shadowTokens: { token: string; value: string }[] = ${JSON.stringify(shadowDisplayRows)};`,
       `const zIndexTokens: { token: string; value: string; label: string }[] = ${JSON.stringify(zIndexRows)};`,
+      `const zIndexIsDefault: boolean = ${zIndexIsDefault};`,
       `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)};`,
@@ -3434,9 +3483,8 @@ function writeFoundationsStories(foundations, components) {
       "          ))}",
       "        </div>",
       "      )}",
-      "      {zIndexTokens.length === 0 && usedZIndex.length === 0 ? (",
-      "        <p style={{ color: \"#999\", fontSize: 13 }}>No z-index tokens detected.</p>",
-      "      ) : zIndexTokens.length > 0 ? (",
+      "      {zIndexIsDefault && <p style={{ fontSize: 12, color: \"#92400e\", background: \"#fef3c7\", border: \"1px solid #fde68a\", borderRadius: 6, padding: \"6px 12px\", marginBottom: 14, display: \"inline-block\" }}>ℹ️ Tailwind defaults — no custom z-index found in this project</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\" }}>",