agentic-dev/apps/storybook/AGENTS.md

AGENTS.md — apps/storybook

Centralized Storybook instance for visual component development, documentation, and MCP integration for AI agents. Currently ships with an empty stories list — scaffold @repo/core-ui first to populate it.

Purpose

Visual testing and documentation hub for the design system. When @repo/core-ui is scaffolded, stories live colocated with their components there. Storybook serves as the single source of truth for component usage.

core-ui is optional. Scaffold it with pnpm turbo gen core-package ui, then add the stories glob and CSS import (see next-steps printed by the generator).

Port: 6006

pnpm dev --filter @repo/storybook   # http://localhost:6006

Configuration

.storybook/main.ts

Stories are empty by default. After scaffolding @repo/core-ui, add the glob:

const config: StorybookConfig = {
  framework: "@storybook/react-vite",
  stories: ["../../../packages/core-ui/src/**/*.stories.@(ts|tsx)"],
  addons: ["@storybook/addon-essentials"],
  docs: { autodocs: "tag" },
  async viteFinal(config) {
    const { mergeConfig } = await import("vite");
    const tailwindPlugin = await import("@tailwindcss/vite");
    return mergeConfig(config, {
      plugins: [tailwindPlugin.default()],
    });
  },
};

Key settings:

• stories glob — empty by default; add "../../../packages/core-ui/src/**/*.stories.@(ts|tsx)" after scaffolding core-ui
• viteFinal — adds Tailwind v4 plugin so classes render in Storybook
• autodocs: "tag" — auto-generates docs for tagged stories

.storybook/preview.ts

After scaffolding @repo/core-ui, import global styles here:

import type { Preview } from "@storybook/react";
import "@repo/core-ui/styles/globals.css";

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

Story Organization

Stories are organized by Atomic Design level via the title field:

Level	Title format	Sidebar path
Atom	"Atoms/{ComponentName}"	Atoms > ComponentName
Molecule	"Molecules/{ComponentName}"	Molecules > ComponentName
Organism	"Organisms/{ComponentName}"	Organisms > ComponentName
Template	"Templates/{ComponentName}"	Templates > ComponentName

Example story file (after scaffolding core-ui at packages/core-ui/src/atoms/button/button.stories.tsx):

import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./button";

const meta = {
  title: "Atoms/Button",
  component: Button,
  tags: ["autodocs"],
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: { children: "Click me" },
};

export const Variant: Story = {
  args: { children: "Secondary", variant: "secondary" },
};

MCP Integration

When Storybook runs, the MCP endpoint is available at:

http://localhost:6006/mcp

Available tools:

• list-all-documentation — Lists all component stories and their properties
• get-documentation — Gets detailed component info (props, variants, usage examples)
• run-story-tests — Validates story rendering

Before building new components:

1. Query list-all-documentation to check if a similar component exists
2. Query get-documentation to understand existing props and variants
3. After creating: run-story-tests to validate

Dependencies

Dependency	Purpose
@repo/core-ui	Component source + stories (optional — scaffold with pnpm turbo gen core-package ui)
@storybook/react-vite	Storybook with Vite bundler
@storybook/addon-essentials	Controls, Actions, Docs, Backgrounds
@tailwindcss/vite	Vite plugin for Tailwind v4
storybook	Storybook CLI + dev server
tailwindcss	Tailwind CSS v4
vite	Build tool
react / react-dom	React 19

Cross-References

• Component source (when scaffolded): packages/core-ui/AGENTS.md
• Scaffold core-ui: pnpm turbo gen core-package ui
• Storybook docs: .storybook/ folder