learning_ai_common_plat/docs/STORYBOOK_TEMPLATE.md

# Storybook Template for `@bytelyst/*` Packages

> ROADMAP TODO #5 — canonical pattern for adding Storybook 8 to each
> visual `@bytelyst/*` package.

## Status

| Package                          | Has Storybook | Stories                                                         | A11y addon |
| -------------------------------- | ------------- | --------------------------------------------------------------- | ---------- |
| `@bytelyst/ui`                   | ✅            | 5 (`Button`, `Card`, `Controls`, `Input`, `OperationalPreview`) | ✅         |
| `@bytelyst/auth-ui`              | ❌            | —                                                               | —          |
| `@bytelyst/dashboard-components` | ❌            | —                                                               | —          |
| `@bytelyst/dashboard-shell`      | ❌            | —                                                               | —          |
| `@bytelyst/celebrations`         | ❌            | —                                                               | —          |
| `@bytelyst/gentle-notifications` | ❌            | —                                                               | —          |
| `@bytelyst/quick-actions`        | ❌            | —                                                               | —          |
| `@bytelyst/react-auth`           | ❌            | —                                                               | —          |

Rollout is incremental — each package added separately so failures are
diagnosable.

## Canonical setup (mirrors `@bytelyst/ui`)

### 1. Add devDependencies

```sh
pnpm --filter @bytelyst/<pkg> add -D \
  storybook@^8.5.0 \
  @storybook/react@^8.5.0 \
  @storybook/react-vite@^8.5.0 \
  @storybook/addon-essentials@^8.5.0 \
  @storybook/addon-a11y@^8.5.0
```

### 2. Add scripts to `package.json`

```json
{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}
```

### 3. Create `.storybook/main.ts`

```ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-a11y'],
  framework: { name: '@storybook/react-vite', options: {} },
};

export default config;
```

### 4. Create `.storybook/preview.ts`

```ts
import type { Preview } from '@storybook/react';
import '@bytelyst/design-tokens/css';

const preview: Preview = {
  parameters: {
    backgrounds: {
      default: 'dark',
      values: [
        { name: 'dark', value: '#06070A' },
        { name: 'elevated', value: '#0E1118' },
        { name: 'light', value: '#F8F9FC' },
      ],
    },
  },
};

export default preview;
```

### 5. Add at least one `*.stories.tsx`

Pattern — one story file per component, **co-located** in `src/`:

```tsx
// src/components/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button.js';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: { layout: 'centered' },
  tags: ['autodocs'],
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { children: 'Click me' } };
export const Disabled: Story = { args: { children: 'Disabled', disabled: true } };
```

## Hosting

**Decision (`docs/ROADMAP_2026_DECISIONS.md` §9):** self-hosted on
Gitea Pages.

A future Gitea Actions workflow at `.gitea/workflows/storybook.yml`
will build each package's Storybook on push to `main` and deploy the
combined output to `storybook.bytelyst.com` (or equivalent).

Until that workflow lands, developers run `pnpm --filter @bytelyst/<pkg>
run storybook` locally on `:6006`.