vds-test-empty 1.0.0

package/vds-core/story-generator.mjs

@@ -0,0 +1,880 @@
+#!/usr/bin/env node
+/**
+ * VDS Story generator
+ *
+ * Reads vds-output.json and generates:
+ * - Storybook .stories.tsx files under src/stories for each component
+ * - Foundations .stories.tsx: 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");
+
+// CSS is loaded from .storybook/preview.tsx — never add CSS import to story files.
+
+// 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",
+  "Chart",
+  "InputOtp",
+  "Resizable",
+  "Sonner",
+  "ImageWithFallback",
+  "ConnectionLines",
+  "ScrollToTop",
+  "Form",
+  "Toaster",
+  "Toast",
+];
+
+/** shadcn/ui composite component recipes: component name → imports + render. */
+const RECIPES = {
+  Accordion: {
+    imports: ["AccordionItem", "AccordionTrigger", "AccordionContent"],
+    render: `(args) => (
+      <ComponentRef type="single" collapsible {...args}>
+        <AccordionItem value="item-1">
+          <AccordionTrigger>Is it accessible?</AccordionTrigger>
+          <AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="item-2">
+          <AccordionTrigger>Is it styled?</AccordionTrigger>
+          <AccordionContent>Yes. It comes with default styles.</AccordionContent>
+        </AccordionItem>
+      </ComponentRef>
+    )`,
+  },
+  Dialog: {
+    imports: ["DialogTrigger", "DialogContent", "DialogHeader", "DialogTitle", "DialogDescription"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <DialogTrigger asChild><button>Open Dialog</button></DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Dialog Title</DialogTitle>
+            <DialogDescription>This is a dialog description.</DialogDescription>
+          </DialogHeader>
+        </DialogContent>
+      </ComponentRef>
+    )`,
+  },
+  AlertDialog: {
+    imports: ["AlertDialogTrigger", "AlertDialogContent", "AlertDialogHeader", "AlertDialogTitle", "AlertDialogDescription", "AlertDialogFooter", "AlertDialogCancel", "AlertDialogAction"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <AlertDialogTrigger asChild><button>Open</button></AlertDialogTrigger>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction>Continue</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </ComponentRef>
+    )`,
+  },
+  Alert: {
+    imports: ["AlertTitle", "AlertDescription"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <AlertTitle>Heads up!</AlertTitle>
+        <AlertDescription>You can add components to your app using the CLI.</AlertDescription>
+      </ComponentRef>
+    )`,
+  },
+  Tooltip: {
+    imports: ["TooltipProvider", "TooltipTrigger", "TooltipContent"],
+    render: `(args) => (
+      <TooltipProvider>
+        <ComponentRef {...args}>
+          <TooltipTrigger asChild><button>Hover me</button></TooltipTrigger>
+          <TooltipContent><p>Tooltip content</p></TooltipContent>
+        </ComponentRef>
+      </TooltipProvider>
+    )`,
+  },
+  Popover: {
+    imports: ["PopoverTrigger", "PopoverContent"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <PopoverTrigger asChild><button>Open Popover</button></PopoverTrigger>
+        <PopoverContent>Place content here.</PopoverContent>
+      </ComponentRef>
+    )`,
+  },
+  HoverCard: {
+    imports: ["HoverCardTrigger", "HoverCardContent"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <HoverCardTrigger asChild><button>Hover</button></HoverCardTrigger>
+        <HoverCardContent>Card content on hover.</HoverCardContent>
+      </ComponentRef>
+    )`,
+  },
+  Tabs: {
+    imports: ["TabsList", "TabsTrigger", "TabsContent"],
+    render: `(args) => (
+      <ComponentRef defaultValue="tab1" {...args}>
+        <TabsList>
+          <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+          <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+        </TabsList>
+        <TabsContent value="tab1">Content for tab 1</TabsContent>
+        <TabsContent value="tab2">Content for tab 2</TabsContent>
+      </ComponentRef>
+    )`,
+  },
+  Table: {
+    imports: ["TableHeader", "TableBody", "TableRow", "TableHead", "TableCell"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader>
+        <TableBody><TableRow><TableCell>Item 1</TableCell><TableCell>Active</TableCell></TableRow></TableBody>
+      </ComponentRef>
+    )`,
+  },
+  DropdownMenu: {
+    imports: ["DropdownMenuTrigger", "DropdownMenuContent", "DropdownMenuItem"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <DropdownMenuTrigger asChild><button>Open Menu</button></DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuItem>Profile</DropdownMenuItem>
+          <DropdownMenuItem>Settings</DropdownMenuItem>
+          <DropdownMenuItem>Logout</DropdownMenuItem>
+        </DropdownMenuContent>
+      </ComponentRef>
+    )`,
+  },
+  ContextMenu: {
+    imports: ["ContextMenuTrigger", "ContextMenuContent", "ContextMenuItem"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <ContextMenuTrigger><div style={{padding: 40, border: '1px dashed #ccc'}}>Right click here</div></ContextMenuTrigger>
+        <ContextMenuContent>
+          <ContextMenuItem>Back</ContextMenuItem>
+          <ContextMenuItem>Forward</ContextMenuItem>
+          <ContextMenuItem>Reload</ContextMenuItem>
+        </ContextMenuContent>
+      </ComponentRef>
+    )`,
+  },
+  Select: {
+    imports: ["SelectTrigger", "SelectValue", "SelectContent", "SelectItem"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <SelectTrigger className="w-[180px]"><SelectValue placeholder="Select a fruit" /></SelectTrigger>
+        <SelectContent>
+          <SelectItem value="apple">Apple</SelectItem>
+          <SelectItem value="banana">Banana</SelectItem>
+          <SelectItem value="orange">Orange</SelectItem>
+        </SelectContent>
+      </ComponentRef>
+    )`,
+  },
+  Card: {
+    imports: ["CardHeader", "CardTitle", "CardDescription", "CardContent", "CardFooter"],
+    render: `(args) => (
+      <ComponentRef className="w-[340px]" {...args}>
+        <CardHeader>
+          <CardTitle>Card title</CardTitle>
+          <CardDescription>Short description.</CardDescription>
+        </CardHeader>
+        <CardContent><p>Card body content here.</p></CardContent>
+        <CardFooter>Footer</CardFooter>
+      </ComponentRef>
+    )`,
+  },
+  Avatar: {
+    imports: ["AvatarImage", "AvatarFallback"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+        <AvatarFallback>JD</AvatarFallback>
+      </ComponentRef>
+    )`,
+  },
+  Checkbox: {
+    render: `(args) => (
+      <div className="flex items-center space-x-2">
+        <ComponentRef id="terms" {...args} />
+        <label htmlFor="terms" className="text-sm font-medium">Accept terms</label>
+      </div>
+    )`,
+  },
+  Switch: {
+    render: `(args) => (
+      <div className="flex items-center space-x-2">
+        <ComponentRef id="switch" {...args} />
+        <label htmlFor="switch" className="text-sm font-medium">Enable notifications</label>
+      </div>
+    )`,
+  },
+  RadioGroup: {
+    imports: ["RadioGroupItem"],
+    render: `(args) => (
+      <ComponentRef className="flex flex-col space-y-2" {...args}>
+        <div className="flex items-center space-x-2">
+          <RadioGroupItem value="comfortable" id="comfortable" />
+          <label htmlFor="comfortable" className="text-sm font-medium">Comfortable</label>
+        </div>
+        <div className="flex items-center space-x-2">
+          <RadioGroupItem value="compact" id="compact" />
+          <label htmlFor="compact" className="text-sm font-medium">Compact</label>
+        </div>
+      </ComponentRef>
+    )`,
+  },
+  Sheet: {
+    imports: ["SheetTrigger", "SheetContent", "SheetHeader", "SheetTitle", "SheetDescription"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <SheetTrigger asChild><button>Open Sheet</button></SheetTrigger>
+        <SheetContent>
+          <SheetHeader>
+            <SheetTitle>Sheet Title</SheetTitle>
+            <SheetDescription>Sheet description here.</SheetDescription>
+          </SheetHeader>
+        </SheetContent>
+      </ComponentRef>
+    )`,
+  },
+  Drawer: {
+    imports: ["DrawerTrigger", "DrawerContent", "DrawerHeader", "DrawerTitle", "DrawerDescription"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <DrawerTrigger asChild><button>Open Drawer</button></DrawerTrigger>
+        <DrawerContent>
+          <DrawerHeader>
+            <DrawerTitle>Drawer Title</DrawerTitle>
+            <DrawerDescription>Drawer description here.</DrawerDescription>
+          </DrawerHeader>
+        </DrawerContent>
+      </ComponentRef>
+    )`,
+  },
+  Command: {
+    imports: ["CommandInput", "CommandList", "CommandEmpty", "CommandGroup", "CommandItem"],
+    render: `(args) => (
+      <ComponentRef className="rounded-lg border shadow-md" {...args}>
+        <CommandInput placeholder="Type a command..." />
+        <CommandList>
+          <CommandEmpty>No results found.</CommandEmpty>
+          <CommandGroup heading="Suggestions">
+            <CommandItem>Calendar</CommandItem>
+            <CommandItem>Search</CommandItem>
+            <CommandItem>Settings</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </ComponentRef>
+    )`,
+  },
+  Carousel: {
+    imports: ["CarouselContent", "CarouselItem", "CarouselPrevious", "CarouselNext"],
+    render: `(args) => (
+      <ComponentRef className="w-full max-w-xs" {...args}>
+        <CarouselContent>
+          <CarouselItem><div className="p-4 text-center border rounded">Slide 1</div></CarouselItem>
+          <CarouselItem><div className="p-4 text-center border rounded">Slide 2</div></CarouselItem>
+          <CarouselItem><div className="p-4 text-center border rounded">Slide 3</div></CarouselItem>
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+      </ComponentRef>
+    )`,
+  },
+  Collapsible: {
+    imports: ["CollapsibleTrigger", "CollapsibleContent"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <CollapsibleTrigger asChild><button className="text-sm font-medium">Toggle content</button></CollapsibleTrigger>
+        <CollapsibleContent className="mt-2 p-2 border rounded">Hidden content revealed.</CollapsibleContent>
+      </ComponentRef>
+    )`,
+  },
+  Menubar: {
+    imports: ["MenubarMenu", "MenubarTrigger", "MenubarContent", "MenubarItem"],
+    render: `(args) => (
+      <ComponentRef {...args}>
+        <MenubarMenu>
+          <MenubarTrigger>File</MenubarTrigger>
+          <MenubarContent>
+            <MenubarItem>New</MenubarItem>
+            <MenubarItem>Open</MenubarItem>
+            <MenubarItem>Save</MenubarItem>
+          </MenubarContent>
+        </MenubarMenu>
+      </ComponentRef>
+    )`,
+  },
+};
+
+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;
+}
+
+/** Void HTML elements: img, input, hr, br — must not receive children. If component wraps one and has children in props, omit children in story args. */
+function componentWrapsVoidElement(source) {
+  if (!source || typeof source !== "string") return false;
+  const hasVoid = /return\s+<(?:img|input|hr|br)\b|<\s*(?:img|input|hr|br)\s+/.test(source);
+  if (!hasVoid) return false;
+  return /\bchildren\b/.test(source);
+}
+
+function toSafeComponentName(name, file) {
+  if (name && typeof name === "string") {
+    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, "");
+  }
+  const base = (file || "").replace(/\.[^.]+$/, "");
+  const parts = base.split(/[\\/]/g);
+  const last = parts[parts.length - 1] || "Component";
+  return last.charAt(0).toUpperCase() + last.slice(1);
+}
+
+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 === "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");
+  }
+
+  // Fallback: let the generic variant-based logic or RECIPES handle it
+  return "";
+}
+
+function buildRecipeStoryContent(comp, componentName, importPath, title, source, exportStyle, recipe) {
+  const lines = [];
+  lines.push(`import type { Meta, StoryObj } from "@storybook/react";`);
+  const useRouterDecorator = needsRouter(source);
+  if (exportStyle === "default") {
+    lines.push(`import ${componentName} from "${importPath}";`);
+    if (recipe.imports?.length) {
+      lines.push(`import { ${recipe.imports.join(", ")} } from "${importPath}";`);
+    }
+    lines.push(`const ComponentRef = ${componentName};`);
+  } else if (exportStyle === "named") {
+    const names = recipe.imports?.length ? [componentName, ...recipe.imports] : [componentName];
+    lines.push(`import { ${names.join(", ")} } from "${importPath}";`);
+    lines.push(`const ComponentRef = ${componentName};`);
+  } else {
+    const defaultAlias = `${componentName}Default`;
+    const namedAlias = `${componentName}Named`;
+    const extra = recipe.imports?.length ? ", " + recipe.imports.join(", ") : "";
+    lines.push(`import ${defaultAlias}, { ${componentName} as ${namedAlias}${extra} } from "${importPath}";`);
+    lines.push(`const ComponentRef = ${namedAlias} ?? ${defaultAlias};`);
+  }
+  for (const ext of recipe.extraImports || []) {
+    lines.push(`import { ${ext.names.join(", ")} } from "${ext.from}";`);
+  }
+  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("");
+  lines.push(`export const Default: Story = {`);
+  lines.push(`  render: ${recipe.render},`);
+  lines.push(`};`);
+  return lines.join("\n");
+}
+
+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 = componentWrapsVoidElement(source);
+
+  if (RECIPES[componentName]) {
+    return buildRecipeStoryContent(comp, componentName, importPath, title, source, exportStyle, RECIPES[componentName]);
+  }
+
+  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};`);
+  }
+
+  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 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 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 writeFoundationsStories(foundations) {
+  const foundationsDir = path.join(STORIES_DIR, "foundations");
+  ensureDir(foundationsDir);
+
+  const colorEntries = getColorEntries(foundations?.colors);
+  const colorsContent =
+    [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Colors\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const colors = ${JSON.stringify(colorEntries)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div style={{ display: \"grid\", gridTemplateColumns: \"repeat(auto-fill, minmax(140px, 1fr))\", gap: \"1rem\" }}>",
+      "      {colors.map(({ name, hex }) => (",
+      "        <div key={name}>",
+      "          <div style={{ backgroundColor: hex, height: 80, borderRadius: 8, border: \"1px solid #333\" }} />",
+      "          <p style={{ marginTop: 8, fontSize: 12 }}>{name}</p>",
+      "          <code style={{ fontSize: 11 }}>{hex}</code>",
+      "        </div>",
+      "      ))}",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+  fs.writeFileSync(path.join(foundationsDir, "Colors.stories.tsx"), colorsContent, "utf-8");
+  console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Colors.stories.tsx")));
+
+  const typo = foundations?.typography;
+  if (typo && typeof typo === "object" && Object.keys(typo).length > 0) {
+    const typoRows = Object.entries(typo).map(([k, v]) => ({
+      token: k,
+      value: Array.isArray(v) ? v.join(", ") : String(v),
+    }));
+    const typoContent =
+      [
+        "import type { Meta, StoryObj } from \"@storybook/react\";",
+        "",
+        "const meta = { title: \"Foundations/Typography\" } satisfies Meta;",
+        "export default meta;",
+        "type Story = StoryObj;",
+        "",
+        `const typography = ${JSON.stringify(typoRows)};`,
+        "",
+        "export const Default: Story = {",
+        "  render: () => (",
+        "    <div>",
+        "      <h2 style={{ marginBottom: 16 }}>Font family & scale</h2>",
+        "      <table style={{ borderCollapse: \"collapse\", width: \"100%\" }}>",
+        "        <thead><tr><th style={{ textAlign: \"left\", padding: 8, borderBottom: \"1px solid #333\" }}>Token</th><th style={{ textAlign: \"left\", padding: 8, borderBottom: \"1px solid #333\" }}>Value</th></tr></thead>",
+        "        <tbody>",
+        "          {typography.map(({ token, value }) => (",
+        "            <tr key={token}><td style={{ padding: 8, borderBottom: \"1px solid #222\" }}>{token}</td><td style={{ padding: 8, borderBottom: \"1px solid #222\" }}>{value}</td></tr>",
+        "          ))}",
+        "        </tbody>",
+        "      </table>",
+        "    </div>",
+        "  ),",
+        "};",
+      ].join("\n");
+    fs.writeFileSync(path.join(foundationsDir, "Typography.stories.tsx"), typoContent, "utf-8");
+    console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Typography.stories.tsx")));
+  }
+
+  const brandAssets = foundations?.brand?.assets;
+  const assets = Array.isArray(brandAssets) ? brandAssets : [];
+  const brandContent =
+    [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Brand\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const assets = ${JSON.stringify(assets)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div>",
+      "      <h2 style={{ marginBottom: 16 }}>Logo and favicon paths</h2>",
+      "      <ul style={{ listStyle: \"none\", padding: 0 }}>",
+      "        {assets.length === 0 ? <li>No brand assets found.</li> : assets.map((a, i) => (",
+      "          <li key={i} style={{ padding: \"8px 0\", borderBottom: \"1px solid #222\" }}>",
+      "            <strong>{a.type || \"asset\"}</strong>: <code>{a.path || a.name || \"\"}</code>",
+      "          </li>",
+      "        ))}",
+      "      </ul>",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+  fs.writeFileSync(path.join(foundationsDir, "Brand.stories.tsx"), brandContent, "utf-8");
+  console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "Brand.stories.tsx")));
+}
+
+function writeComponentSuggestionsStory(componentSuggestions) {
+  if (!Array.isArray(componentSuggestions) || componentSuggestions.length === 0) return;
+  const foundationsDir = path.join(STORIES_DIR, "foundations");
+  ensureDir(foundationsDir);
+  const suggestions = componentSuggestions.map((s) => ({
+    suggestedName: s.suggestedName,
+    occurrences: s.occurrences,
+    foundIn: s.foundIn,
+    pattern: s.pattern,
+    snippet: s.snippet,
+    reason: s.reason,
+  }));
+  const content =
+    [
+      "import type { Meta, StoryObj } from \"@storybook/react\";",
+      "",
+      "const meta = { title: \"Foundations/Component Suggestions\" } satisfies Meta;",
+      "export default meta;",
+      "type Story = StoryObj;",
+      "",
+      `const suggestions = ${JSON.stringify(suggestions)};`,
+      "",
+      "export const Default: Story = {",
+      "  render: () => (",
+      "    <div style={{ padding: 24, fontFamily: \"system-ui, sans-serif\" }}>",
+      "      <h2 style={{ marginBottom: 16 }}>Repeated className patterns (component candidates)</h2>",
+      "      <p style={{ color: \"#888\", marginBottom: 24 }}>Patterns with 3+ classes appearing 2+ times across src/pages. Consider extracting as components.</p>",
+      "      <div style={{ display: \"flex\", flexDirection: \"column\", gap: 24 }}>",
+      "        {suggestions.map((s, i) => (",
+      "          <div key={i} style={{ border: \"1px solid #333\", borderRadius: 8, padding: 16, background: \"#111\" }}>",
+      "            <div style={{ fontWeight: 600, marginBottom: 8 }}>{s.suggestedName}</div>",
+      "            <div style={{ fontSize: 12, color: \"#888\", marginBottom: 8 }}>{s.reason} · {s.foundIn.join(\", \")}</div>",
+      "            <pre style={{ margin: 0, padding: 12, background: \"#000\", borderRadius: 4, overflow: \"auto\", fontSize: 12 }}><code>{s.snippet}</code></pre>",
+      "          </div>",
+      "        ))}",
+      "      </div>",
+      "    </div>",
+      "  ),",
+      "};",
+    ].join("\n");
+  fs.writeFileSync(path.join(foundationsDir, "ComponentSuggestions.stories.tsx"), content, "utf-8");
+  console.log("[VDS] Wrote " + path.relative(PROJECT_ROOT, path.join(foundationsDir, "ComponentSuggestions.stories.tsx")));
+}
+
+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"));
+  writeFoundationsStories(foundations);
+  const componentSuggestions = data.componentSuggestions;
+  if (componentSuggestions?.length) {
+    writeComponentSuggestionsStory(componentSuggestions);
+  }
+  try {
+    const fd = path.join(STORIES_DIR, "foundations");
+    if (fs.existsSync(fd)) {
+      for (const name of fs.readdirSync(fd)) {
+        if (name.endsWith(".stories.mdx")) fs.unlinkSync(path.join(fd, name));
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  // 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 requiredCount = Array.isArray(comp.props) ? comp.props.filter((p) => p.required === true).length : 0;
+    if (requiredCount > 3) 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();
+