storybook

Storybook

Every reusable UI component must have a Storybook story. A component without a story is not done. Stories are living documentation and the contract for a component's states.

When to use

• Creating a new component, or adding a variant/prop to an existing one.
• Writing or editing *.stories.tsx / *.stories.ts files.
• Configuring args, decorators, parameters, or .storybook/ setup.
• Reviewing a frontend PR — a new component without a co-located story is a blocking gap.

The rule

New or changed component → add or update its story in the same change.

This is automatic and unprompted: create the story as part of building the component, without waiting for the user to ask. After authoring or updating stories, run pnpm build-storybook and fix any failures yourself before reporting done.

Best practices

1. Use CSF 3.0

Prefer Component Story Format 3.0 — concise and type-safe.

// ❌ CSF 2.0 (legacy)
export default {
  title: 'Components/Button',
  component: Button,
};
export const Primary = () => <Button variant="primary">Click me</Button>;

// ✅ CSF 3.0 (preferred)
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  component: Button,
  tags: ['autodocs'],
  args: {
    variant: 'primary',
    children: 'Click me',
  },
} satisfies Meta<typeof Button>;

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

export const Primary: Story = {};

export const Secondary: Story = {
  args: { variant: 'secondary' },
};

2. Args-based stories

Define component props as args so the Controls panel stays interactive.

• Declare defaults in args — not argTypes.defaultValue. Meta-level args become the default selection in Controls.
• Share common args at the Meta level; override only what differs per story.

// ❌ Hard-coded props in render
export const Disabled: Story = {
  render: () => <Button disabled>Disabled</Button>,
};

// ❌ Duplicated args across stories
export const Primary: Story = {
  args: { children: 'Click me', variant: 'primary' },
};
export const Secondary: Story = {
  args: { children: 'Click me', variant: 'secondary' },
};

// ✅ Meta-level shared args; stories override only differences
const meta = {
  component: Button,
  args: {
    children: 'Click me',
    variant: 'primary',
  },
} satisfies Meta<typeof Button>;

export const Primary: Story = {};
export const Secondary: Story = { args: { variant: 'secondary' } };
export const Disabled: Story = { args: { disabled: true } };