134 lines
3.6 KiB
Markdown
134 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pnpm dev --filter @repo/storybook # http://localhost:6006
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### `.storybook/main.ts`
|
|
|
|
Stories are discovered from `@repo/core-ui`:
|
|
|
|
```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** — 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:
|
|
|
|
```typescript
|
|
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`):
|
|
|
|
```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 |
|
|
| `@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
|