# 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

```bash
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:

```typescript
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:

```typescript
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`):

```typescript
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