vibe-design-system 1.8.4 → 1.9.2

package/bin/init.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 /**
  * VDS installer: npx vibe-design-system init
- * - Kullanıcı projesine dashboard dosyası kopyalanmaz.
- * - Sadece vds-core/scan.mjs ve vds-core/dashboard-server.mjs projeye kopyalanır.
- * - package.json'a vds, vds:watch, vds:dashboard scriptleri eklenir.
- * - Kurulum sonrası otomatik tarama çalıştırılır.
+ *
+ * Single command that:
+ * 1. Copies vds-core files (scan.mjs, story-generator.mjs, dashboard-server.mjs)
+ * 2. Installs Storybook if not present (npx storybook@latest init --yes)
+ * 3. Creates/updates .storybook/preview with index.css import and dark decorator
+ * 4. Runs node vds-core/scan.mjs
+ * 5. Runs node vds-core/story-generator.mjs
+ * 6. Adds all scripts to package.json
  */
 import fs from "fs";
 import path from "path";
@@ -24,6 +28,66 @@ function getProjectRoot() {
   return cwd;
 }
 
+function isStorybookInstalled(projectRoot) {
+  const storybookDir = path.join(projectRoot, ".storybook");
+  if (fs.existsSync(storybookDir)) return true;
+  const pkgPath = path.join(projectRoot, "package.json");
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    const dev = pkg.devDependencies || {};
+    if (dev["@storybook/react-vite"] || dev["storybook"]) return true;
+  } catch (_) {}
+  return false;
+}
+
+function installStorybook(projectRoot) {
+  console.log("📚 Storybook kuruluyor...");
+  const r = spawnSync("npx", ["storybook@latest", "init", "--yes"], {
+    cwd: projectRoot,
+    stdio: "inherit",
+    shell: true,
+  });
+  if (r.status !== 0) {
+    console.warn("⚠️ Storybook init tamamlanamadı; manuel: npx storybook@latest init");
+  }
+}
+
+const PREVIEW_CONTENT = `import type { Preview } from "@storybook/react-vite";
+import React from "react";
+import "../src/index.css";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="dark" style={{ minHeight: "100vh", padding: "1rem" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default preview;
+`;
+
+function ensureStorybookPreview(projectRoot) {
+  const storybookDir = path.join(projectRoot, ".storybook");
+  if (!fs.existsSync(storybookDir)) fs.mkdirSync(storybookDir, { recursive: true });
+
+  const previewTsx = path.join(storybookDir, "preview.tsx");
+  const previewTs = path.join(storybookDir, "preview.ts");
+  if (fs.existsSync(previewTs)) try { fs.unlinkSync(previewTs); } catch (_) {}
+  fs.writeFileSync(previewTsx, PREVIEW_CONTENT, "utf-8");
+  console.log("📝 .storybook/preview.tsx güncellendi (index.css + dark decorator).");
+}
+
 function addScripts(projectRoot) {
   const pkgPath = path.join(projectRoot, "package.json");
   const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
@@ -31,6 +95,9 @@ function addScripts(projectRoot) {
   if (!scripts.vds) scripts.vds = "node vds-core/scan.mjs";
   if (!scripts["vds:watch"]) scripts["vds:watch"] = "node vds-core/scan.mjs --watch";
   if (!scripts["vds:dashboard"]) scripts["vds:dashboard"] = "node vds-core/dashboard-server.mjs";
+  if (!scripts["vds:stories"]) scripts["vds:stories"] = "node vds-core/story-generator.mjs";
+  if (!scripts.storybook) scripts.storybook = "storybook dev -p 6006";
+  if (!scripts["build-storybook"]) scripts["build-storybook"] = "storybook build";
   pkg.scripts = scripts;
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2), "utf-8");
 }
@@ -40,7 +107,7 @@ function addVdsDependency(projectRoot) {
   const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
   const dev = pkg.devDependencies || {};
   if (!dev["vibe-design-system"]) {
-    dev["vibe-design-system"] = "^1.4.1";
+    dev["vibe-design-system"] = "^1.9.0";
     pkg.devDependencies = dev;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2), "utf-8");
     const r = spawnSync("npm", ["install"], { cwd: projectRoot, stdio: "inherit", shell: true });
@@ -63,15 +130,18 @@ function ensureVdsCore(projectRoot) {
   const serverSrc = path.join(TEMPLATE_DIR, "dashboard-server.mjs");
   if (fs.existsSync(serverSrc)) {
     fs.copyFileSync(serverSrc, path.join(vdsCoreDest, "dashboard-server.mjs"));
-  } else {
-    console.error("vds-core-template/dashboard-server.mjs bulunamadı.");
-    process.exit(1);
+  }
+
+  const storyGenSrc = path.join(TEMPLATE_DIR, "story-generator.mjs");
+  if (fs.existsSync(storyGenSrc)) {
+    fs.copyFileSync(storyGenSrc, path.join(vdsCoreDest, "story-generator.mjs"));
   }
 }
 
 function runScan(projectRoot) {
   const scanPath = path.join(projectRoot, "vds-core", "scan.mjs");
   if (!fs.existsSync(scanPath)) return;
+  console.log("🔍 VDS taraması çalıştırılıyor...");
   const r = spawnSync("node", [scanPath], {
     cwd: projectRoot,
     stdio: "inherit",
@@ -80,6 +150,18 @@ function runScan(projectRoot) {
   if (r.status !== 0) process.exitCode = r.status ?? 1;
 }
 
+function runStoryGenerator(projectRoot) {
+  const genPath = path.join(projectRoot, "vds-core", "story-generator.mjs");
+  if (!fs.existsSync(genPath)) return;
+  console.log("📖 Story dosyaları oluşturuluyor...");
+  const r = spawnSync("node", [genPath], {
+    cwd: projectRoot,
+    stdio: "inherit",
+    shell: false,
+  });
+  if (r.status !== 0) process.exitCode = r.status ?? 1;
+}
+
 console.log("🎨 VDS kuruluyor...");
 
 const projectRoot = getProjectRoot();
@@ -90,9 +172,29 @@ if (!fs.existsSync(pkgPath)) {
   process.exit(1);
 }
 
+// 1. Copy vds-core files
 ensureVdsCore(projectRoot);
+
+// 2. Install Storybook if not present
+if (!isStorybookInstalled(projectRoot)) {
+  installStorybook(projectRoot);
+} else {
+  console.log("📚 Storybook zaten mevcut.");
+}
+
+// 3. Create/update .storybook/preview with index.css + dark decorator
+ensureStorybookPreview(projectRoot);
+
+// 6. Add all scripts to package.json (before scan so scripts are there)
 addScripts(projectRoot);
 addVdsDependency(projectRoot);
+
+// 4. Run scan
 runScan(projectRoot);
 
-console.log("✅ Kurulum tamamlandı. Dashboard: npm run vds:dashboard ile başlatın; terminalde adres gösterilir.");
+// 5. Run story generator
+runStoryGenerator(projectRoot);
+
+console.log("✅ Kurulum tamamlandı.");
+console.log("   Storybook: npm run storybook");
+console.log("   Dashboard: npm run vds:dashboard");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-design-system",
-  "version": "1.8.4",
+  "version": "1.9.2",
   "description": "Auto-generate design systems for vibe coding projects",
   "type": "module",
   "bin": {

package/vds-core-template/README.md

@@ -24,13 +24,20 @@ Zero-config, autonomous design system. Drop this folder into any Vite + React pr
 
 ## Live component preview (optional)
 
-To see **live renders** of components in the dashboard (instead of a placeholder):
+To see **live renders** of components in the dashboard (isolated, no app chrome):
 
-1. Add the preview route to your app (e.g. in the same router):
+1. Add the preview route **outside** any layout that has your app header, sidebar, or nav. Otherwise every preview iframe will show your full app shell instead of just the component.
    ```tsx
-   import VdsPreview from "./vds-core/VdsPreview";  // or copy VdsPreview.tsx from node_modules/vibe-design-system/vds-core-template/
+   import VdsPreview from "./vds-core/VdsPreview";  // or from node_modules/vibe-design-system/vds-core-template/
    // ...
-   <Route path="/vds-preview" element={<VdsPreview />} />
+   <Routes>
+     {/* Preview must NOT be inside a layout with header/sidebar */}
+     <Route path="/vds-preview" element={<VdsPreview />} />
+     <Route path="/" element={<YourLayoutWithHeader />}>
+       <Route index element={<Home />} />
+       {/* ... */}
+     </Route>
+   </Routes>
    ```
 
 2. If you open the dashboard from the **standalone server** (e.g. `npm run vds:watch` → Dashboard at `http://localhost:3334/vds`), run your app as well (e.g. `npm run dev` on port 5173). The dashboard will load previews from that app. If your app runs on another port (e.g. 3000), set:

package/vds-core-template/VdsPreview.tsx

@@ -1,7 +1,11 @@
 /**
  * VDS Component Preview — mount at /vds-preview so the dashboard can show live component renders.
- * Add to your router, e.g.:
- *   <Route path="/vds-preview" element={<VdsPreview />} />
+ *
+ * Important: Render this route OUTSIDE any layout that contains your app header, sidebar, or nav.
+ * Otherwise every component preview iframe will show your full app shell instead of the component alone.
+ *
+ * Example (React Router):
+ *   <Route path="/vds-preview" element={<VdsPreview />} />   // at root, not inside <LayoutWithHeader>
  *
  * Requires Vite; uses import.meta.glob. Path alias @/components must point to src/components.
  */

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

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+/**
+ * VDS Story generator
+ *
+ * Reads vds-output.json and generates:
+ * - Storybook .stories.tsx files under src/stories for each component
+ * - Foundations MDX: Colors, Typography, Brand under src/stories/foundations/
+ *
+ * Usage:
+ *   node vds-core/story-generator.mjs        # generate for all components
+ *   node vds-core/story-generator.mjs Button # generate only for "Button"
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.join(__dirname, "..");
+const VDS_OUTPUT = path.join(PROJECT_ROOT, "vds-output.json");
+const SRC_DIR = path.join(PROJECT_ROOT, "src");
+const STORIES_DIR = path.join(SRC_DIR, "stories");
+
+// Top of every story file for CSS variables
+const STORY_CSS_HEADER = `// @ts-ignore
+import '../../index.css'
+
+`;
+
+// Components we don't want to auto-generate stories for (project-specific dashboards, heavy UIs, etc.)
+const SKIP_LIST = [
+  "AnalysisDashboard",
+  "ComponentLibrary",
+  "EnterprisePushPanel",
+  "FigmaLibraryGenerator",
+  "IntegrationGuide",
+  "ProjectDropzone",
+  "RepoConnect",
+  "TokensStudioGuide",
+  "NavLink",
+  "CodeInput",
+  "SyncModeSelector",
+  "ToggleGroup",
+  "Sidebar",
+  "TestComponent",
+];
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/** Detect if component uses router (useLocation, useNavigate, or Link from react-router-dom). */
+function needsRouter(source) {
+  if (!source || typeof source !== "string") return false;
+  if (/\buseLocation\b|\buseNavigate\b/.test(source)) return true;
+  if (/from\s+['"]react-router-dom['"]/.test(source) && /\bLink\b/.test(source)) return true;
+  return false;
+}
+
+/** If component has <img and accepts children prop, we should omit children from story args (void element). */
+function componentHasImgAndChildren(source) {
+  if (!source || typeof source !== "string") return false;
+  const hasImg = /return\s+<img|<\s*img\s+/.test(source);
+  if (!hasImg) return false;
+  return /\bchildren\b/.test(source);
+}
+
+function toSafeComponentName(name, file) {
+  if (!name || typeof name !== "string") {
+    const base = (file || "").replace(/\.[^.]+$/, "");
+    const parts = base.split(/[\\/]/g);
+    const last = parts[parts.length - 1] || "Component";
+    return last.charAt(0).toUpperCase() + last.slice(1);
+  }
+  return name
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .replace(/\s+([a-z])/g, (_, c) => c.toUpperCase())
+    .replace(/^\w/, (c) => c.toUpperCase())
+    .replace(/\s+/g, "");
+}
+
+function parseUnionLiterals(type) {
+  if (!type) return [];
+  const matches = String(type).match(/"([^"]+)"/g);
+  if (!matches) return [];
+  return matches.map((s) => s.replace(/"/g, ""));
+}
+
+function capitalize(str) {
+  if (!str) return "";
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function detectExportStyle(source, componentName) {
+  if (!source) return "unknown";
+  const hasDefault = /export\s+default\b/.test(source);
+  const namedPatterns = [
+    new RegExp(`export\\s+\\{[^}]*\\b${componentName}\\b[^}]*\\}`),
+    new RegExp(`export\\s+const\\s+${componentName}\\b`),
+    new RegExp(`export\\s+function\\s+${componentName}\\b`),
+    new RegExp(`export\\s+class\\s+${componentName}\\b`),
+  ];
+  const hasNamed = namedPatterns.some((re) => re.test(source));
+  if (hasDefault && hasNamed) return "both";
+  if (hasDefault) return "default";
+  if (hasNamed) return "named";
+  return "unknown";
+}
+
+function buildSpecialStories(componentName, variants) {
+  const lines = [];
+
+  // Simple input-like primitives
+  if (componentName === "Input") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(`    placeholder: "Enter your email...",`);
+    lines.push(`    type: "email",`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Textarea") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(`    placeholder: "Write your message...",`);
+    lines.push(`    rows: 4,`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Label") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(`    children: "Email address",`);
+    lines.push(`    htmlFor: "email",`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Slider") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(`    defaultValue: [50],`);
+    lines.push(`    max: 100,`);
+    lines.push(`    step: 1,`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Calendar") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {},`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "InputOtp" || componentName === "InputOTP") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(`    maxLength: 6,`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Checkbox") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  render: (args) => (`);
+    lines.push(`    <div className="flex items-center space-x-2">`);
+    lines.push(`      <ComponentRef id="terms" {...args} />`);
+    lines.push(`      <Label htmlFor="terms">Accept terms</Label>`);
+    lines.push(`    </div>`);
+    lines.push(`  ),`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Switch") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  render: (args) => (`);
+    lines.push(`    <div className="flex items-center space-x-2">`);
+    lines.push(`      <ComponentRef id="notifications" {...args} />`);
+    lines.push(`      <Label htmlFor="notifications">Enable notifications</Label>`);
+    lines.push(`    </div>`);
+    lines.push(`  ),`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "RadioGroup") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  render: (args) => (`);
+    lines.push(`    <ComponentRef className="flex flex-col space-y-2" {...args}>`);
+    lines.push(`      <div className="flex items-center space-x-2">`);
+    lines.push(`        <RadioGroupItem value="comfortable" id="comfortable" />`);
+    lines.push(`        <Label htmlFor="comfortable">Comfortable</Label>`);
+    lines.push(`      </div>`);
+    lines.push(`      <div className="flex items-center space-x-2">`);
+    lines.push(`        <RadioGroupItem value="compact" id="compact" />`);
+    lines.push(`        <Label htmlFor="compact">Compact</Label>`);
+    lines.push(`      </div>`);
+    lines.push(`    </ComponentRef>`);
+    lines.push(`  ),`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Select") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: { defaultValue: "apple" },`);
+    lines.push(`  render: (args) => (`);
+    lines.push(`    <ComponentRef {...args}>`);
+    lines.push(`      <SelectTrigger className="w-[180px]">`);
+    lines.push(`        <SelectValue placeholder="Select a fruit" />`);
+    lines.push(`      </SelectTrigger>`);
+    lines.push(`      <SelectContent>`);
+    lines.push(`        <SelectItem value="apple">Apple</SelectItem>`);
+    lines.push(`        <SelectItem value="banana">Banana</SelectItem>`);
+    lines.push(`        <SelectItem value="orange">Orange</SelectItem>`);
+    lines.push(`      </SelectContent>`);
+    lines.push(`    </ComponentRef>`);
+    lines.push(`  ),`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Badge") {
+    const vs = variants && variants.length ? variants : ["default", "secondary", "destructive", "outline"];
+    vs.forEach((v, idx) => {
+      const storyName = capitalize(v);
+      lines.push(`export const ${storyName}: Story = {`);
+      lines.push(`  args: {`);
+      lines.push(`    variant: "${v}",`);
+      lines.push(`    children: "New",`);
+      lines.push(`  },`);
+      lines.push(`};`);
+      if (idx < vs.length - 1) lines.push("");
+    });
+    return lines.join("\n");
+  }
+
+  if (componentName === "Card") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  render: (args) => (`);
+    lines.push(`    <ComponentRef className="w-[340px]" {...args}>`);
+    lines.push(`      <CardHeader>`);
+    lines.push(`        <CardTitle>Card title</CardTitle>`);
+    lines.push(`        <CardDescription>Short description about this card.</CardDescription>`);
+    lines.push(`      </CardHeader>`);
+    lines.push(`      <CardContent>`);
+    lines.push(`        <p>Here is some representative content inside the card body.</p>`);
+    lines.push(`      </CardContent>`);
+    lines.push(`      <CardFooter>Footer content</CardFooter>`);
+    lines.push(`    </ComponentRef>`);
+    lines.push(`  ),`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  if (componentName === "Avatar") {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  render: (args) => (`);
+    lines.push(`    <ComponentRef {...args}>`);
+    lines.push(`      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />`);
+    lines.push(`      <AvatarFallback>JD</AvatarFallback>`);
+    lines.push(`    </ComponentRef>`);
+    lines.push(`  ),`);
+    lines.push(`};`);
+    return lines.join("\n");
+  }
+
+  // Fallback: let the generic variant-based logic handle it
+  return "";
+}
+
+function buildStoryFileContent(comp) {
+  const componentName = toSafeComponentName(comp.name, comp.file);
+  const fileNoExt = comp.file.replace(/\.(tsx|jsx)$/, "");
+  const importPath = `@/components/${fileNoExt}`;
+  const group = comp.group || "Components";
+  const category = comp.category || null;
+  const titleParts = [group, category, componentName].filter(Boolean);
+  const title = titleParts.join("/");
+
+  const props = Array.isArray(comp.props) ? comp.props : [];
+  const variantProp = props.find((p) => p.name === "variant");
+  let variants = parseUnionLiterals(variantProp && variantProp.type);
+
+  // Fallback: if manifest doesn't have variant metadata yet, parse cva() directly from component file.
+  if (!variants.length) {
+    try {
+      const srcPath = path.join(SRC_DIR, "components", comp.file);
+      if (fs.existsSync(srcPath)) {
+        const code = fs.readFileSync(srcPath, "utf-8");
+        // Roughly match shadcn-style: variants: { variant: { ... }, size: { ... } }
+        const m = code.match(/variant\s*:\s*{([\s\S]*?)}\s*,\s*size\s*:/);
+        if (m) {
+          const body = m[1];
+          const names = [];
+          const lineRe = /^\s*([A-Za-z0-9_]+)\s*:/gm;
+          let lm;
+          while ((lm = lineRe.exec(body))) {
+            names.push(lm[1]);
+          }
+          if (names.length) variants = names;
+        }
+      }
+    } catch {
+      // best-effort; ignore parsing errors
+    }
+  }
+
+  // Read component source to detect export style for import
+  let source = "";
+  try {
+    const srcPath = path.join(SRC_DIR, "components", comp.file);
+    if (fs.existsSync(srcPath)) {
+      source = fs.readFileSync(srcPath, "utf-8");
+    }
+  } catch {
+    // ignore
+  }
+  const exportStyle = detectExportStyle(source, componentName);
+  const omitChildren = componentHasImgAndChildren(source);
+
+  const lines = [];
+  lines.push(`import type { Meta, StoryObj } from "@storybook/react";`);
+
+  if (exportStyle === "default") {
+    lines.push(`import ${componentName} from "${importPath}";`);
+    lines.push(`const ComponentRef = ${componentName};`);
+  } else if (exportStyle === "named") {
+    lines.push(`import { ${componentName} } from "${importPath}";`);
+    lines.push(`const ComponentRef = ${componentName};`);
+  } else {
+    const defaultAlias = `${componentName}Default`;
+    const namedAlias = `${componentName}Named`;
+    lines.push(
+      `import ${defaultAlias}, { ${componentName} as ${namedAlias} } from "${importPath}";`,
+    );
+    lines.push(`const ComponentRef = ${namedAlias} ?? ${defaultAlias};`);
+  }
+
+  // Extra imports for composite components
+  if (componentName === "Checkbox" || componentName === "Switch" || componentName === "RadioGroup") {
+    lines.push(`import { Label } from "@/components/ui/label";`);
+  }
+  if (componentName === "RadioGroup") {
+    lines.push(`import { RadioGroupItem } from "@/components/ui/radio-group";`);
+  }
+  if (componentName === "Select") {
+    lines.push(
+      `import { SelectTrigger, SelectValue, SelectContent, SelectItem } from "@/components/ui/select";`,
+    );
+  }
+  if (componentName === "Avatar") {
+    lines.push(`import { AvatarImage, AvatarFallback } from "@/components/ui/avatar";`);
+  }
+  if (componentName === "Card") {
+    lines.push(
+      `import { CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "@/components/ui/card";`,
+    );
+  }
+  const useRouterDecorator = needsRouter(source);
+  if (useRouterDecorator) {
+    lines.push(`import { MemoryRouter } from "react-router-dom";`);
+  }
+
+  lines.push("");
+  lines.push(`const meta = {`);
+  lines.push(`  title: ${JSON.stringify(title)},`);
+  lines.push(`  component: ComponentRef,`);
+  lines.push(`  tags: ["autodocs"],`);
+  if (useRouterDecorator) {
+    lines.push(`  decorators: [(Story) => (`);
+    lines.push(`    <MemoryRouter>`);
+    lines.push(`      <Story />`);
+    lines.push(`    </MemoryRouter>`);
+    lines.push(`  )],`);
+  }
+  lines.push(`} satisfies Meta<typeof ComponentRef>;`);
+  lines.push("");
+  lines.push(`export default meta;`);
+  lines.push(`type Story = StoryObj<typeof meta>;`);
+  lines.push("");
+
+  // Component-specific stories (inputs, composite components, etc.)
+  const specialStories = buildSpecialStories(componentName, variants);
+  if (specialStories) {
+    lines.push(specialStories);
+    return STORY_CSS_HEADER + lines.join("\n");
+  }
+
+  // Generic variant-based stories (omit children for img/void components)
+  if (!variants.length) {
+    lines.push(`export const Default: Story = {`);
+    lines.push(`  args: {`);
+    if (!omitChildren) lines.push(`    children: "${componentName}",`);
+    lines.push(`  },`);
+    lines.push(`};`);
+  } else {
+    const defaultVariant = variants[0];
+    lines.push(`export const ${capitalize(defaultVariant)}: Story = {`);
+    lines.push(`  args: {`);
+    lines.push(`    variant: "${defaultVariant}",`);
+    if (!omitChildren) lines.push(`    children: "${componentName}",`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    lines.push("");
+    for (const v of variants.slice(1)) {
+      const storyName = capitalize(v);
+      lines.push(`export const ${storyName}: Story = {`);
+      lines.push(`  args: {`);
+      lines.push(`    variant: "${v}",`);
+      if (!omitChildren) lines.push(`    children: "${storyName}",`);
+      lines.push(`  },`);
+      lines.push(`};`);
+      lines.push("");
+    }
+  }
+
+  return STORY_CSS_HEADER + lines.join("\n");
+}
+
+/** Build color entries from foundations.colors (skip _dark; flatten to { name, hex }). */
+function getColorEntries(colors) {
+  if (!colors || typeof colors !== "object") return [];
+  const entries = [];
+  for (const [name, v] of Object.entries(colors)) {
+    if (name === "_dark") continue;
+    const hex = v && (v.hex ?? (typeof v.value === "string" && v.value.startsWith("#") ? v.value : null));
+    const value = v && v.value;
+    if (hex) entries.push({ name, hex });
+    else if (value) entries.push({ name, hex: value });
+  }
+  return entries;
+}
+
+function writeFoundationsMdx(foundations) {
+  const foundationsDir = path.join(STORIES_DIR, "foundations");
+  ensureDir(foundationsDir);
+
+  const colors = foundations?.colors;
+  const colorEntries = getColorEntries(colors);
+  if (colorEntries.length > 0) {
+    const colorLines = [
+      "import { Meta } from '@storybook/blocks';",
+      "",
+      "<Meta title=\"Foundations/Colors\" />",
+      "",
+      "# Colors",
+      "",
+      "<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))', gap: '1rem' }}>",
+      ...colorEntries.map(
+        (e) =>
+          `  <div key="${e.name}"><div style={{ backgroundColor: '${e.hex.replace(/'/g, "\\'")}', height: 80, borderRadius: 8, border: '1px solid #333' }} /><p style={{ marginTop: 8, fontSize: 12 }}>${e.name}</p><code style={{ fontSize: 11 }}>${e.hex}</code></div>`,
+      ),
+      "</div>",
+    ];
+    fs.writeFileSync(path.join(foundationsDir, "Colors.stories.mdx"), colorLines.join("\n"), "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Colors.stories.mdx")));
+  }
+
+  const typo = foundations?.typography;
+  if (typo && typeof typo === "object" && Object.keys(typo).length > 0) {
+    const bodyVal = typo.body || typo.bodyFontFamily || "";
+    const monoVal = typo.mono || typo.tailwindMono;
+    const monoStr = Array.isArray(monoVal) ? monoVal.join(", ") : String(monoVal || "");
+    const typoContent = [
+      "import { Meta } from '@storybook/blocks';",
+      "",
+      "<Meta title=\"Foundations/Typography\" />",
+      "",
+      "# Typography",
+      "",
+      "## Font family & scale",
+      "",
+      "| Token | Value |",
+      "| --- | --- |",
+      ...Object.entries(typo).map(([k, v]) => {
+        const val = Array.isArray(v) ? v.join(", ") : String(v);
+        return `| ${k} | ${val} |`;
+      }),
+      "",
+      "## Preview",
+      "",
+      `<p style={{ fontFamily: ${JSON.stringify(bodyVal)}, fontSize: 16 }}>The quick brown fox jumps over the lazy dog.</p>`,
+      `<p style={{ fontFamily: ${JSON.stringify(monoStr)}, fontSize: 14 }}>Code: 0123456789</p>`,
+    ];
+    fs.writeFileSync(path.join(foundationsDir, "Typography.stories.mdx"), typoContent.join("\n"), "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Typography.stories.mdx")));
+  }
+
+  const brandAssets = foundations?.brand?.assets;
+  if (Array.isArray(brandAssets) && brandAssets.length > 0) {
+    const assetRows = brandAssets.map(
+      (a) =>
+        `  <tr key="${(a.path || a.name || "").replace(/"/g, '\\"')}"><td>${a.type || "asset"}</td><td><code>${a.path || a.name || ""}</code></td><td>${a.name || ""}</td></tr>`,
+    );
+    const brandContent = [
+      "import { Meta } from '@storybook/blocks';",
+      "",
+      "<Meta title=\"Foundations/Brand\" />",
+      "",
+      "# Brand",
+      "",
+      "Logo and favicon paths from the project.",
+      "",
+      "<table><thead><tr><th>Type</th><th>Path</th><th>Name</th></tr></thead><tbody>",
+      ...assetRows,
+      "</tbody></table>",
+    ];
+    fs.writeFileSync(path.join(foundationsDir, "Brand.stories.mdx"), brandContent.join("\n"), "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Brand.stories.mdx")));
+  }
+}
+
+function main() {
+  if (!fs.existsSync(VDS_OUTPUT)) {
+    console.error("[VDS] vds-output.json not found. Run `npm run vds` first.");
+    process.exit(1);
+  }
+  const raw = fs.readFileSync(VDS_OUTPUT, "utf-8");
+  const data = JSON.parse(raw);
+  const components = Array.isArray(data.components) ? data.components : [];
+  const foundations = data.foundations || null;
+
+  const onlyName = process.argv[2] || null;
+
+  ensureDir(STORIES_DIR);
+  ensureDir(path.join(STORIES_DIR, "foundations"));
+  writeFoundationsMdx(foundations);
+
+  // Clear existing .stories.* files (except foundations/*.mdx) so only VDS-generated stories remain
+  try {
+    const existing = fs.readdirSync(STORIES_DIR);
+    for (const name of existing) {
+      if (name === "foundations") continue;
+      if (
+        name.endsWith(".stories.tsx") ||
+        name.endsWith(".stories.ts") ||
+        name.endsWith(".stories.jsx") ||
+        name.endsWith(".stories.js")
+      ) {
+        fs.unlinkSync(path.join(STORIES_DIR, name));
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  for (const comp of components) {
+    const componentName = toSafeComponentName(comp.name, comp.file);
+    if (onlyName && componentName !== onlyName) continue;
+    if (SKIP_LIST.includes(componentName)) continue;
+
+    const storyFileName = `${componentName}.stories.tsx`;
+    const storyPath = path.join(STORIES_DIR, storyFileName);
+    const content = buildStoryFileContent(comp);
+    fs.writeFileSync(storyPath, content, "utf-8");
+    console.log(`[VDS] Wrote ${path.relative(PROJECT_ROOT, storyPath)}`);
+  }
+}
+
+main();