Danijel Martinek
ae456a5436
- AGENTS.md (root): marks core-ui as optional in the package table and boundary rules; points per-package docs to the .hbs template - apps/storybook/AGENTS.md: rewrites around no-core-ui-by-default; stories glob and globals.css import described as post-scaffold steps - apps/web-next/AGENTS.md: cross-reference updated to template file - apps/web-tanstack/AGENTS.md: cross-reference updated to template file - docs/architecture/data-flow-explainer.html: core-ui bullet notes optional status + generator command Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
137 lines
4.1 KiB
Markdown
137 lines
4.1 KiB
Markdown
# 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
|