Storybook

Storybook

Overview

Storybook is a frontend workshop for building UI components and pages in isolation. It helps develop and share hard-to-reach states and edge cases without running the whole app. Use it for UI development, testing, and documentation.

Core concepts: Stories (rendered component states), CSF (Component Story Format), args (props/inputs), decorators (wrappers), play functions (interaction tests).

Requirements: Node.js 20+, npm 10+ or pnpm 9+ or Yarn 4+, Vite 5+ or Webpack 5+, TypeScript 4.9+ (optional).

---

Installation

Reference: Official install guide

Invoke via your package manager (see docs). The CLI detects the framework (Next.js, Vite, React, Vue, Angular, Svelte, etc.). For manual selection: --type nextjs, react, vue3, angular, svelte, sveltekit, etc.

Recommended: Use @storybook/nextjs-vite for Next.js projects (faster than Webpack). Use @storybook/react-vite for Vite + React.

Dev server: typically port 6006.

---

Project structure: system directory

Place components in a `system/` directory, with each component in its own folder. Colocate the story file alongside the component — this keeps documentation and tests next to the source and follows Storybook best practices.

system/
├── Button/
│   ├── Button.tsx
│   └── Button.stories.tsx
├── Card/
│   ├── Card.tsx
│   └── Card.stories.tsx
├── Dialog/
│   ├── Dialog.tsx
│   └── Dialog.stories.tsx

Configure .storybook/main.ts to load stories from system/:

import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../system/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
};

export default config;

---

Component Story Format (CSF)

Stories use CSF 3: a default export (meta) and named exports (stories).

Meta (default export)

import type { Meta } from '@storybook/your-framework';
import { Button } from './Button';

const meta = {
  component: Button,
  title: 'System/Button',  // optional; auto-derived from path if omitted
} satisfies Meta<typeof Button>;

export default meta;

Stories (named exports)

import type { StoryObj } from '@storybook/your-framework';

type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    label: 'Button',
    primary: true,
  },
};

export const Secondary: Story = {
  args: {
    ...Primary.args,
    primary: false,
    label: 'Secondary',
  },
};

Args map to component props. They appear in the Controls panel for live editing.

---

Writing stories

Basic story with args

export const Default: Story = {
  args: {
    label: 'Click me',
    disabled: false,
  },
};

Custom render

Use render when the default (component + args) is not enough:

export const InAlert: Story = {
  args: { label: 'Confirm' },
  render: (args) => (
    <Alert>
      <Button {...args} />
    </Alert>
  ),
};

Play function (interaction tests)

Simulate user interactions and assert outcomes:

import { expect } from 'storybook/test';

export const OpensDialog: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Open' }));
    await expect(canvas.getByRole('dialog')).toBeInTheDocument();
  },
};

Decorators

Wrap stories (e.g. padding, theme, providers):

const meta = {
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ padding: '3em' }}>
        <Story />
      </div>
    ),
  ],
} satisfies Meta<typeof Button>;

Parameters

Static metadata for addons (backgrounds, layout, etc.):

const meta = {
  component: Button,
  parameters: {
    backgrounds: { values: [{ name: 'dark', value: '#333' }] },
  },
} satisfies Meta<typeof Button>;

---

Reusing stories across components

Import story args from child components to compose parent stories:

import * as ButtonStories from '../Button/Button.stories';

export const WithButtons: Story = {
  args: {
    buttons: [
      { ...ButtonStories.Primary.args },
      { ...ButtonStories.Secondary.args },
    ],
  },
};

---

Configuration

main.ts

• stories: Glob patterns for story files.
• addons: e.g. @storybook/addon-essentials, @storybook/addon-a11y.
• framework: e.g. @storybook/nextjs-vite, @storybook/react-vite.
• staticDirs: Static assets (e.g. ['../public']).

preview.ts

Global decorators, parameters, and CSS:

import type { Preview } from '@storybook/react';
import '../app/globals.css';

const preview: Preview = {
  decorators: [
    (Story) => (
      <div style={{ fontFamily: 'system-ui' }}>
        <Story />
      </div>
    ),
  ],
  parameters: {
    layout: 'centered',
  },
};

export default preview;

---

Testing

• Render tests: Every story is a smoke test — it passes if it renders without error.
• Interaction tests: Use play with expect from storybook/test.
• Vitest addon: storybook add @storybook/addon-vitest — runs stories as Vitest tests (invoke via package manager; see docs).
• Accessibility: Enable @storybook/addon-a11y for automated a11y checks.
• Visual testing: Use Chromatic or snapshot tests for visual regression.

---

Best practices

• Colocate stories with components in system/<ComponentName>/.
• Use args instead of hardcoding props; enables Controls and reuse.
• One story per meaningful state (default, loading, error, empty, etc.).
• Reuse child story args when composing parent stories.
• Use `play` for interaction tests instead of manual E2E when possible.
• Keep stories focused — one component per story file; use render for composition.

---

Common mistakes

• Stories in separate folder: Prefer colocation (Component.stories.tsx next to Component.tsx).
• Missing `component` in meta: Required for autodocs and Controls; use satisfies Meta<typeof Component>.
• Hardcoded props: Use args so Controls work and stories are reusable.
• Wrong framework import: Use @storybook/nextjs-vite, @storybook/react-vite, etc., not generic @storybook/react.
• Glob not matching system/: Ensure stories in main.ts includes ../system/**/*.stories.*.

---

Additional resources

• reference.md — Official Storybook docs links, frameworks, addons, testing.
• Official: https://storybook.js.org/docs
• Writing stories: https://storybook.js.org/docs/writing-stories
• Testing: https://storybook.js.org/docs/writing-tests

License

Skill License - Free Use

This skill (the documentation, structure, and implementation) was created by Ender Puentes <Endev/> and is provided for free and open use. You are free to:

• Use this skill in any project, personal or commercial
• Modify the skill to fit your needs
• Distribute the skill to others
• Share modified versions of the skill
• Include this skill in your own skill collections

No restrictions apply – this skill is available for unrestricted use. Attribution is appreciated but not required.

Note: This skill documents and references Storybook; the skill itself is an independent work. Storybook is a separate work by Chroma (Storybook team) with its own license (MIT).

Storybook — Reference & Official Documentation

This file complements the storybook skill with official documentation links and sections for indexing.

Official documentation (indexable)

• Docs home: https://storybook.js.org/docs
• Get started: https://storybook.js.org/docs/get-started
• Installation: https://storybook.js.org/docs/get-started/install
• Writing stories: https://storybook.js.org/docs/writing-stories
• Writing docs: https://storybook.js.org/docs/writing-docs
• Writing tests: https://storybook.js.org/docs/writing-tests
• Configure: https://storybook.js.org/docs/configure
• Sharing: https://storybook.js.org/docs/sharing
• Essential features: https://storybook.js.org/docs/essentials
• Addons: https://storybook.js/addons
• FAQ: https://storybook.js.org/docs/faq

Frameworks

• Next.js (Vite): https://storybook.js.org/docs/get-started/frameworks/nextjs-vite — Recommended for Next.js
• Next.js (Webpack): https://storybook.js.org/docs/get-started/frameworks/nextjs
• React + Vite: https://storybook.js.org/docs/get-started/frameworks/react-vite
• Vue 3 + Vite: https://storybook.js.org/docs/get-started/frameworks/vue3-vite
• Angular: https://storybook.js.org/docs/get-started/frameworks/angular
• SvelteKit: https://storybook.js.org/docs/get-started/frameworks/sveltekit
• Svelte + Vite: https://storybook.js.org/docs/get-started/frameworks/svelte-vite
• Web Components: https://storybook.js.org/docs/get-started/frameworks/web-components-vite

Core concepts

• Stories: Rendered component states; one story = one configuration
• CSF (Component Story Format): ES module standard; default export = meta, named exports = stories
• Args: Props/inputs; editable via Controls panel
• Decorators: Wrappers for stories (layout, providers, padding)
• Parameters: Static metadata for addons (backgrounds, layout, etc.)
• Play function: Async code that runs after story render; used for interaction tests

Configuration

• main.ts: stories, addons, framework, staticDirs, viteFinal, webpackFinal
• preview.ts: decorators, parameters, globalTypes
• Story loading: Glob patterns, directory config, titlePrefix, custom files

Testing

• Vitest addon: https://storybook.js.org/docs/writing-tests/integrations/vitest-addon
• Test runner: https://storybook.js.org/docs/writing-tests/integrations/test-runner
• Interaction testing: https://storybook.js.org/docs/writing-tests/interaction-testing
• Accessibility: https://storybook.js.org/docs/writing-tests/accessibility-testing
• Visual testing: https://storybook.js.org/docs/writing-tests/visual-testing
• CI: https://storybook.js.org/docs/writing-tests/in-ci

Addons (common)

• @storybook/addon-essentials: Controls, Actions, Viewport, Backgrounds, Toolbars, Measure, Outline
• @storybook/addon-a11y: Accessibility checks
• @storybook/addon-vitest: Run stories as Vitest tests
• @storybook/addon-docs: Autodocs, MDX

Project requirements (from install guide)

• Node.js 20+
• npm 10+ / pnpm 9+ / Yarn 4+
• Vite 5+ or Webpack 5+
• TypeScript 4.9+ (optional)
• Next.js 14+, Vue 3+, React 18+, etc. (framework-specific)