fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(agents): write per-app AGENTS.md for cms, web-next, web-tanstack, storybook

Browse Source
This commit is contained in:
Danijel Martinek
2026-05-05 10:00:28 +02:00
parent 0ede53998f
commit 2c6c836206
4 changed files with 232 additions and 381 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
apps/storybook/AGENTS.md
View File

@@ -1,8 +1,10 @@
# apps/storybook -- Centralized Storybook
# 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
Centralized Storybook instance that pulls and renders all stories from `packages/core-ui`. Provides a visual development environment, component documentation, and MCP integration for AI agents.
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
@@ -14,20 +16,17 @@ pnpm dev --filter @repo/storybook # http://localhost:6006
### `.storybook/main.ts`
```typescript
import type { StorybookConfig } from "@storybook/react-vite";
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",
},
docs: { autodocs: "tag" },
async viteFinal(config) {
const { mergeConfig } = await import("vite");
const tailwindPlugin = await import("@tailwindcss/vite");
return mergeConfig(config, {
plugins: [tailwindPlugin.default()],
});
@@ -35,14 +34,15 @@ const config: StorybookConfig = {
};
```
Key configuration details:
- **`stories`** glob reaches into `packages/core-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
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";
@@ -59,77 +59,75 @@ const preview: Preview = {
};
```
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.
Stories are organized by Atomic Design level via the `title` field:
### 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/core-ui` |
| Level | Title format | Sidebar path |
|---|---|---|
| `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` |
| 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 is running, the MCP (Model Context Protocol) endpoint is available at:
When Storybook runs, the MCP endpoint is available at:
```
http://localhost:6006/mcp
```
### Available MCP tools:
### Available 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
- **`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
### Installing addon-mcp
### Before building new components:
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
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` | 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 |
| `@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/` -- see `packages/core-ui/AGENTS.md`
- **Tailwind tokens:** `packages/core-ui/src/styles/globals.css`
- **Component source:** `packages/core-ui/AGENTS.md`
- **Storybook docs:** `.storybook/` folder