storybook

---
name: storybook
description: >
  Maintain the Storybook component catalog for the portal app. Use this skill when:
  (1) adding new stories for components,
  (2) updating existing stories after component changes,
  (3) running a full Storybook refresh/sync with AI assistance.
compatibility: Storybook 10+, React 19, Vite
metadata:
  version: "1.0.0"
allowed-tools: Bash(npx:*) Bash(pnpm:*) Read Write Edit Glob Grep
---

# Storybook Maintenance

This project uses Storybook 10 as a component catalog for the portal app (`apps/portal/`).

## Updating the Storybook

To regenerate or update stories across the project, run the following command from the `apps/portal/` directory:

```bash
cd apps/portal && npx storybook ai setup
```

**Follow its instructions precisely.** The command analyzes the project's runtime providers, CSS setup, data-fetching patterns, and components, then produces updated stories with proper decorators, MSW handlers, and play functions.

## Key Files

| File | Purpose |
|------|---------|
| `apps/portal/.storybook/main.ts` | Storybook config (framework, stories glob, Vite overrides) |
| `apps/portal/.storybook/preview.tsx` | Shared decorators (QueryClient, MemoryRouter), mswLoader, CSS |
| `apps/portal/.storybook/msw-handlers.ts` | Default MSW network handlers |
| `apps/portal/public/mockServiceWorker.js` | MSW service worker (generated by `npx msw init`) |

## Running Storybook

```bash
# From repo root (uses worktree port offset)
pnpm storybook

# From apps/portal directly
pnpm storybook
```

The dev server uses port `${STORYBOOK_PORT:-6100}` and does not auto-open a browser.

## Writing Stories Manually

Stories are co-located next to their components as `<Component>.stories.tsx`. Follow these conventions:

1. Import `Meta` and `StoryObj` from `@storybook/react-vite`
2. Tag AI-generated stories with `tags: ['ai-generated', 'needs-work']`
3. Use `play` functions for interaction testing
4. Mock API calls with MSW handlers in `parameters.msw.handlers`
5. Create a fresh `QueryClient` inside decorators (not at module scope)

## Building for CI

```bash
cd apps/portal && pnpm build-storybook
```

This produces a static build in `storybook-static/` (git-ignored).

More agent context in microsoft/scope

9 other files this repository gives its agents.