AGENTS.md — apps/storybook

Centralized Storybook instance pulling stories from @repo/core-ui. Provides visual component development, documentation, and MCP integration for AI agents.

Purpose

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

Port: 6006

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

Configuration

`.storybook/main.ts`

Stories are discovered from @repo/core-ui:

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 — reaches into packages/core-ui/src/ for all *.stories.tsx files
viteFinal — adds Tailwind v4 plugin so classes render in Storybook
autodocs: "tag" — auto-generates docs for tagged stories

`.storybook/preview.ts`

Imports global styles:

import type { Preview } from "@storybook/react";
import "../../../packages/core-ui/src/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 (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:

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

Dependencies

Dependency	Purpose
`@repo/core-ui`	Component source + stories
`@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: packages/core-ui/AGENTS.md
Storybook docs: .storybook/ folder

3.6 KiB Raw Blame History