136 lines
4.4 KiB
Markdown
136 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pnpm dev --filter @repo/storybook # http://localhost:6006
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### `.storybook/main.ts`
|
|
|
|
```typescript
|
|
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`
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```bash
|
|
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`
|