storybook-component

Storybook 10 Component Development

Philosophy

Components are designed in Storybook first, then integrated into the app. Every component gets a .stories.tsx file co-located next to it.

components/
  ChatMessage.tsx
  ChatMessage.stories.tsx
  ChatInput.tsx
  ChatInput.stories.tsx

Story File Template (CSF3)

import type { Meta, StoryObj } from '@storybook/react-vite';
import { fn } from 'storybook/test';
import { MyComponent } from './MyComponent';

const meta = {
  component: MyComponent,
  tags: ['autodocs'],
  // Decorators use design token classes, NEVER inline style with hex
  decorators: [
    (Story) => (
      <div className="bg-bg text-text p-4">
        <Story />
      </div>
    ),
  ],
  // Default args shared across all stories
  args: {
    onClick: fn(),
  },
} satisfies Meta<typeof MyComponent>;

export default meta;
type Story = StoryObj<typeof meta>;

Writing Stories — One Story Per State

Each named export = one visual state. Cover: default, edge cases, loading, error, disabled.

export const Default: Story = {
  args: {
    label: 'Click me',
    variant: 'primary',
  },
};

export const Disabled: Story = {
  args: {
    ...Default.args,
    disabled: true,
  },
};

export const LongContent: Story = {
  args: {
    label: 'A very long label that might overflow the button container',
  },
};

export const Empty: Story = {
  args: {
    label: '',
  },
};

Interaction Testing with Play Functions

Use play functions to verify interactive behavior directly in Storybook. This replaces basic render tests — no need to duplicate in vitest.

import { expect, fn, within, userEvent } from 'storybook/test';

export const SubmitForm: Story = {
  args: {
    onSubmit: fn(),
  },
  play: async ({ args, canvas, userEvent, step }) => {
    await step('Fill in form', async () => {
      await userEvent.type(canvas.getByLabelText('Email'), '[email protected]');
      await userEvent.type(canvas.getByLabelText('Password'), 'secret123');
    });

    await step('Submit', async () => {
      await userEvent.click(canvas.getByRole('button', { name: 'Submit' }));
    });

    await expect(args.onSubmit).toHaveBeenCalledOnce();
  },
};