agentic-dev-template/apps/storybook/AGENTS.md

apps/storybook -- Centralized Storybook

Purpose

Centralized Storybook instance that pulls and renders all stories from packages/ui. Provides a visual development environment, component documentation, and MCP integration for AI agents.

Port: 6006

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

Configuration

.storybook/main.ts

import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  framework: "@storybook/react-vite",
  stories: ["../../../packages/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 configuration details:

• stories glob reaches into packages/ui/src/ to find all .stories.tsx files
• viteFinal adds the @tailwindcss/vite plugin so Tailwind v4 classes render correctly in stories
• autodocs: "tag" generates documentation pages for stories tagged with "autodocs"
• @storybook/addon-essentials includes Controls, Actions, Backgrounds, Viewport, Docs

.storybook/preview.ts

import type { Preview } from "@storybook/react";
import "../../../packages/ui/src/styles/globals.css";

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

Key details:

• Imports globals.css from @repo/ui so all Tailwind v4 @theme tokens are available
• Control matchers auto-detect color and date props for appropriate editor widgets

Story Organization

Stories are organized by Atomic Design level via the title field in story metadata. The title determines the sidebar hierarchy in Storybook.

Story Title Convention

Level	Title format	Example	Sidebar path
Atom	"Atoms/{ComponentName}"	"Atoms/Button"	Atoms > Button
Molecule	"Molecules/{ComponentName}"	"Molecules/FormField"	Molecules > FormField
Organism	"Organisms/{ComponentName}"	"Organisms/DataTable"	Organisms > DataTable
Template	"Templates/{ComponentName}"	"Templates/DashboardLayout"	Templates > DashboardLayout

Existing Stories

Story title	Component	Location in @repo/ui
Atoms/Button	Button (5 variants: Default, Secondary, Destructive, Outline, Ghost)	src/atoms/button/button.stories.tsx
Atoms/Input	Input (Default, Disabled)	src/atoms/input/input.stories.tsx
Molecules/FormField	FormField (Default, WithDescription, WithError)	src/molecules/form-field/form-field.stories.tsx

MCP Integration

When Storybook is running, the MCP (Model Context Protocol) endpoint is available at:

http://localhost:6006/mcp

Available MCP tools:

• list-all-documentation -- Lists all documented components and their stories
• get-documentation -- Gets detailed documentation for a specific component (props, variants, usage)
• run-story-tests -- Runs visual tests on stories to validate rendering

Installing addon-mcp

If @storybook/addon-mcp is not already installed:

npx storybook add @storybook/addon-mcp

This adds the addon to .storybook/main.ts and enables the MCP endpoint.

Using MCP in workflows

Always query MCP before creating new UI components:

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

Dependencies

Dependency	Purpose
@repo/ui	Source of all component stories
@storybook/react-vite	Storybook framework using Vite bundler
@storybook/addon-essentials	Controls, Actions, Docs, Backgrounds, Viewport
@tailwindcss/vite	Vite plugin for Tailwind CSS v4
storybook	Storybook core CLI and dev server
tailwindcss	Tailwind CSS v4 engine
vite	Build tool / dev server
react / react-dom	React 19 runtime

Cross-References

• Component source: packages/ui/ -- see packages/ui/AGENTS.md
• Tailwind tokens: packages/ui/src/styles/globals.css