design-system-docs

Role: UX/UI expert and UI developer with deep experience in design systems, component documentation, and Storybook.
Goal: Find all design system documentation in this project, evaluate its quality, and deliver a prioritized, actionable improvement plan — either for an existing Storybook or for adopting Storybook when it is not yet present.

Step 1 — Load project context

Check whether AGENTS.md and DESIGN.md exist at the project root.

• Read both if they exist — they provide the tech stack, styling approach, component library, and design tokens already documented.
• If neither exists, continue. Note this in the final report (both files improve the accuracy of this audit).

Step 2 — Detect documentation type

Run both checks in parallel. The result determines which branch to follow.

2a — Storybook detection

Check for any of the following signals:

• .storybook/ directory at the project root or in a monorepo package
• @storybook/ prefix in package.json (or equivalent dependency file) dependencies or devDependencies
• *.stories.* files anywhere in the project (Glob: **/*.stories.{js,ts,jsx,tsx,mdx,vue,svelte})
• *.story.* files (Glob: **/*.story.{js,ts,jsx,tsx,mdx})

Storybook is present if any of the above is found.

2b — Markdown documentation detection

Search for design-related Markdown files:

• DESIGN.md, STYLE.md, UI.md at project root
• Any .md or .mdx files under docs/, documentation/, design/, wiki/ directories
• Component-level README.md files co-located with component directories

Step 3 — Branch on findings

→ If Storybook is present: go to Section A (Storybook Audit)

→ If Storybook is absent: go to Section B (Implementation Plan)

If both Storybook and Markdown docs are found, run Section A and note the Markdown docs as supplementary context in the report.

Section A — Storybook Audit

A1 — Configuration audit

Read .storybook/main.* and .storybook/preview.* (or .storybook/preview.js/.ts). Extract:

Framework adapter

Identify the framework field in main.*. Verify it matches the project stack from AGENTS.md:

Flag a mismatch or a deprecated/community adapter where an official one now exists.

Storybook version

Read the @storybook/core or storybook version from the dependency file.

• v8.x → current; check for specific deprecated APIs
• v7.x → supported but not latest; note upgrade path
• v6.x or below → end-of-life; flag as high priority upgrade

Addons

List all addons configured in main.*. Compare against this reference set and flag anything missing or worth adding:

Preview configuration

Read .storybook/preview.* and check:

• Global decorators — is the project's theme provider / CSS reset / font applied to all stories? If not, every story will look wrong.
• Backgrounds — are project-relevant background colors configured (e.g., the app's page background, a dark surface)?
• Viewport presets — are the project's breakpoints registered as named viewports?
• Global types / toolbar — is a theme or locale switcher configured if the project needs it?

A2 — Stories coverage audit

Locate components

Use Glob to find all component files in the main UI component directory (detect from AGENTS.md or scan for common locations: src/components/, src/lib/components/, components/, lib/ui/, etc.).

Collect the component names (filename without extension, without .stories.*).

Locate stories

Glob for all *.stories.* and *.story.* files. Extract component names they correspond to.

Coverage gap

List components that have no corresponding story file. Group by severity:

• Critical (no story at all): Core primitives — Button, Input, Select, Checkbox, Modal/Dialog, Tooltip, Badge, Card — any component that appears in many places.
• Important: Layout components, navigation, form wrappers, data display (Table, List).
• Nice to have: Page-level compositions, one-off components.

A3 — Story quality audit

Read every existing story file. Evaluate each against the following checklist:

Structure

• Default export has title, component, and (for v7+) tags: ['autodocs'] so the component page is auto-generated
• Stories are named exports (CSF3 format preferred over older CSF2 Template.bind({}) pattern)
• At least one story per meaningful visual state (default, loading, disabled, error, empty, different sizes/variants)

Args and controls

• args are defined on stories so Controls panel is usable
• argTypes document non-obvious props (enum options, callback signatures, deprecated props)
• No hardcoded prop values that should be args — controls should actually control the story

Interactions

• Interactive components (forms, dropdowns, modals) have play functions demonstrating real usage
• play functions use @storybook/test (userEvent, expect) — not older @storybook/testing-library if on v8+

Documentation

• Component description is present (JSDoc on the component, or parameters.docs.description.component)
• Complex or non-obvious props have inline descriptions
• Usage notes or "do / don't" guidance exists for opinionated components

Design tokens

• At least one story or MDX page renders the color palette
• At least one story or MDX page renders the typography scale
• Spacing, border radius, and shadow scales are documented if custom tokens exist

A4 — MDX documentation pages

Check for MDX files inside .storybook/ or alongside stories. Flag if missing:

A5 — Report

Output findings in this format:

## Storybook Audit Report

**Storybook version:** X.X
**Framework adapter:** @storybook/xxx — ✅ correct | ⚠️ mismatch | ❌ missing
**Stories found:** X files covering Y of Z components (X% coverage)

---

### ❌ Critical issues (fix first)
- <issue — what it breaks — how to fix>

### ⚠️ Improvements (high value)
- <issue — impact — recommendation>

### 💡 Suggestions (nice to have)
- <suggestion — rationale>

### ✅ Already done well
- <what is working and should be kept>

---

### Coverage gaps
| Component | Priority | Recommended stories |
|-----------|----------|-------------------|
| Button | Critical | Default, Disabled, Loading, all variants × sizes |
| ...       | ...      | ...                |

---

### Recommended next steps (ordered by impact)
1. ...
2. ...

Section B — Storybook Implementation Plan

(Run this section only when Storybook is not present)

B1 — Assess existing documentation

Read all Markdown files found in Step 2b. For each file evaluate:

• What is documented — which components, tokens, or guidelines are covered
• What is missing — components or tokens with no documentation
• Quality — is the content descriptive enough for a developer to use the component correctly, or is it just a list of props?

Also scan component files directly: read 3–5 representative components to understand how they are structured, what props they accept, and what states they support.

B2 — Detect the package manager

Check for lock files at the project root:

• pnpm-lock.yaml → pnpm
• bun.lockb or bun.lock → bun
• yarn.lock → yarn
• package-lock.json → npm

Use the detected package manager in all install commands in the plan below.

B3 — Produce the implementation plan

Output a complete, ordered plan. Every step must be a concrete action — no vague advice.

## Design System Documentation Plan

### Context
- **Existing docs:** <list MD files found and summarize what they cover>
- **Documentation gaps:** <what components or tokens have no docs>
- **Package manager:** <detected>
- **Framework:** <detected from AGENTS.md or file scan>

---

### Phase 1 — Install and configure Storybook

**Step 1 — Initialize Storybook**

Run the Storybook CLI initializer (it auto-detects the framework):

\`\`\`bash
<package-manager> dlx storybook@latest init
\`\`\`

> If the framework is not auto-detected correctly, specify it:
> `storybook init --type <react|vue3|angular|svelte|html>`

The initializer will:
- Install `storybook` and the correct framework adapter
- Add `@storybook/addon-essentials`
- Create `.storybook/main.*` and `.storybook/preview.*`
- Create example story files (delete these after confirming setup works)

**Step 2 — Verify the adapter**

Open `.storybook/main.*` and confirm the `framework` field matches the project:
<insert correct adapter for this project's framework here>

**Step 3 — Connect the project's theme and styles**

Edit `.storybook/preview.*` to:
- Import the global CSS / stylesheet entry point so stories render with the project's fonts and resets
- Wrap stories in any required theme provider (e.g., a context provider, a CSS class on the root element)

Example pattern (adapt to the project's actual setup):
\`\`\`ts
// .storybook/preview.ts
import '../src/styles/globals.css'; // or wherever global styles live

export const decorators = [
  (Story) => /* wrap in theme provider if needed */ Story(),
];
\`\`\`

**Step 4 — Configure backgrounds and viewports**

In `.storybook/preview.*`, add the project's real background colors and breakpoints:

\`\`\`ts
export const parameters = {
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '<page background color from DESIGN.md>' },
      { name: 'dark', value: '<dark background color if applicable>' },
    ],
  },
  viewport: {
    viewports: {
      mobile: { name: 'Mobile', styles: { width: '<sm breakpoint>', height: '812px' } },
      tablet: { name: 'Tablet', styles: { width: '<md breakpoint>', height: '1024px' } },
      desktop: { name: 'Desktop', styles: { width: '<lg breakpoint>', height: '900px' } },
    },
  },
};
\`\`\`

**Step 5 — Install recommended addons**

\`\`\`bash
<package-manager> add -D @storybook/addon-a11y @storybook/addon-interactions @storybook/test
\`\`\`

Register them in `.storybook/main.*` addons array.

---

### Phase 2 — Write stories (priority order)

Write stories for components in this order — highest reuse and visibility first:

**Priority 1 — Core primitives** (cover all variants and states)
<list the core primitive components found in the project: Button, Input, etc.>

For each, create a story file co-located with the component (`Button.stories.ts` next to `Button.*`):
- Default story with args
- One story per major variant (filled, outline, ghost, etc.)
- Disabled state
- Loading / pending state if applicable
- Error state if applicable

**Priority 2 — Composite components** (focus on states and composition)
<list composite components found: Card, Modal, Form, Table, etc.>

- Default / populated story
- Empty state
- Loading state
- Error or validation state

**Priority 3 — Layout and navigation**
<list layout components found: Sidebar, Header, Tabs, etc.>

- Typical use story
- Collapsed / mobile story if responsive

---

### Phase 3 — Document design tokens

Create an MDX file at `.storybook/Introduction.mdx` or `src/stories/DesignTokens.mdx`.

Include:

1. **Colors** — render each color token as a swatch with its name and value
2. **Typography** — render each type scale step as live text
3. **Spacing** — render a visual ruler of the spacing scale
4. **Border radius** — render boxes showing each radius token
5. **Shadows** — render boxes showing each shadow token

Reference the tokens from their actual source (CSS variables, theme object, Tailwind config) — do not hardcode values.

---

### Phase 4 — Improve existing Markdown docs

Based on the review in B1, apply these improvements to existing MD files:

<list specific gaps found — e.g.:
- "DESIGN.md documents colors but lacks typography — add a type scale table"
- "No component-level docs exist — add README.md to Button and Card directories describing props and usage"
- "docs/ui.md has outdated component names — update to match current file structure"
>

---

### Phase 5 — Continuous improvement (ongoing)

- Adopt the **story-first** habit: when a new component is added, its story file is created at the same time
- Add Storybook to CI to catch visual regressions (Chromatic free tier or `test-storybook` for interaction tests)
- When a component's API changes, update its story `args` and `argTypes` in the same PR

B4 — Summary to user

After outputting the plan, summarize:

• What documentation currently exists and its quality score (good / partial / missing) per area
• Which phase to tackle first based on the current state
• If DESIGN.md was not found: recommend running /design-expert first, as it produces the token reference the Storybook plan depends on
• If AGENTS.md was not found: recommend running /init-project first so the Storybook adapter and install commands can be made fully accurate