What Is Storybook? See Your Components Before You Build the Page

What Is Storybook, Really?

Before we get technical, let's use a real-world analogy.

Imagine you're a finish carpenter. You build cabinet doors, drawer fronts, and decorative moldings. Before you take any of those pieces to the job site, you lay them out in the shop — check the finish, make sure the dimensions are right, test the hardware. You don't install the cabinets and then discover the doors were hung backwards.

That's what Storybook does for UI components. It's a separate mini-application — a workshop, a showroom — where you can see each component by itself, in every configuration, before you install it into your actual app.

When you run Storybook, it starts a local web server (usually on localhost:6006) and opens a browser window that looks nothing like your app. Instead, you see a sidebar with all your components listed. You click on "Button" and see a canvas area showing just the button — no navigation bar, no other content, no database queries running in the background. Just the button.

Then you flip between stories: Primary, Secondary, Disabled, Loading. Each story shows the button in a different state. You can see at a glance which ones look right, which ones have styling issues, and which ones have the wrong label.

Storybook works with React, Vue, Svelte, Angular, and plain HTML/web components. If you're building any kind of UI, it fits. And with over 80,000 GitHub stars, it's one of the most widely used frontend development tools in the world.

Why Storybook Matters When You're Building with AI

If you're building with AI as your primary coding partner, here's the problem you've probably already run into: AI generates components fast. Sometimes too fast. You ask for a card component, you get 80 lines of JSX back, and now you have to actually see it before you know if it's any good.

Without Storybook, that means navigating to the right page in your app, making sure the right data is available, clicking through whatever interaction surfaces the component, and hoping the state you care about is visible. That's a lot of friction for "does this button look disabled when I pass disabled={true}?"

With Storybook, the loop is completely different:

1. AI generates the component
2. AI generates the stories (we'll cover this in detail)
3. You open Storybook and immediately see every state
4. You adjust and iterate without touching the rest of the app

This is especially powerful for component-based development — the practice of building your UI as a library of reusable pieces before assembling them into pages. Storybook is the natural habitat for that workflow.

The other thing Storybook does well for AI-assisted builders: it forces the AI to think clearly about component API design. When you ask AI to generate stories, it has to enumerate every meaningful state and prop combination. That process often surfaces design issues — "oh, we need a loading state, the AI didn't include one" — before you've wired the component into anything.

Component-First Thinking

There's a term in frontend development: "component-first" or "design-system thinking." Instead of building page by page (the old way), you build component by component — each piece isolated, tested, documented — and then assemble pages from those pieces.

Storybook is the tool that makes component-first thinking practical. Without it, keeping components isolated is an aspiration. With it, you have a dedicated environment that enforces the separation.

For vibe coders, this matters because it means you can hand the AI a single, well-scoped task: "build this component." Then you check it in Storybook. Then you move on to the next one. You never have to juggle the whole app in your head at once. That's a much more manageable way to build — and a much better fit for how AI tools work best.

Stories: One Component, Many States

The word "story" in Storybook has a specific meaning: it's a named example of a component in a particular state.

Think about a contractor's sample board — the one with squares of tile, paint chips, and countertop samples all labeled and organized. Each sample is one specific configuration of the material. That's a story. You're not showing every possible configuration, just the meaningful, named ones someone would actually choose from.

A Button component might have these stories:

• Primary — the main call-to-action style, full color
• Secondary — a lower-emphasis outlined style
• Disabled — grayed out, not clickable
• Loading — showing a spinner, not yet clickable
• Small — the small size variant
• Destructive — the danger/delete style in red

Each story is just a function that returns your component with specific props. The story file lives right next to the component file in your project, typically named Button.stories.tsx.

Here's what a complete stories file looks like:

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

// Meta describes the component as a whole
const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  // argTypes let you control props from the Storybook UI
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'destructive'],
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
    disabled: { control: 'boolean' },
    loading: { control: 'boolean' },
  },
};

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

// Each exported const is one story
export const Primary: Story = {
  args: {
    children: 'Save Changes',
    variant: 'primary',
    size: 'md',
  },
};

export const Secondary: Story = {
  args: {
    children: 'Cancel',
    variant: 'secondary',
    size: 'md',
  },
};

export const Disabled: Story = {
  args: {
    children: 'Save Changes',
    variant: 'primary',
    size: 'md',
    disabled: true,
  },
};

export const Loading: Story = {
  args: {
    children: 'Saving...',
    variant: 'primary',
    size: 'md',
    loading: true,
  },
};

export const Destructive: Story = {
  args: {
    children: 'Delete Account',
    variant: 'destructive',
    size: 'md',
  },
};

That's it. Each export const becomes a story in the sidebar. The args object is the set of props that get passed to the component for that story. Storybook renders each one in its own canvas.

The argTypes section in the meta is where Storybook gets clever: it creates a controls panel below the canvas where you can adjust props in real time using dropdowns, toggles, and text inputs — without touching code. Change the variant from "primary" to "destructive" and watch the button update live. It's like having a live configurator for every component you've ever built.

Real Example: Building a Button Component with Storybook

Let's walk through this end to end — component first, then stories, then what you see in Storybook.

The Component

Here's a Button component for a React project using Tailwind CSS. This is exactly the kind of thing you'd ask AI to generate:

// Button.tsx
import { ButtonHTMLAttributes, ReactNode } from 'react';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  children: ReactNode;
  variant?: 'primary' | 'secondary' | 'destructive';
  size?: 'sm' | 'md' | 'lg';
  loading?: boolean;
}

const variantClasses = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700 border border-transparent',
  secondary: 'bg-white text-gray-700 hover:bg-gray-50 border border-gray-300',
  destructive: 'bg-red-600 text-white hover:bg-red-700 border border-transparent',
};

const sizeClasses = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-sm',
  lg: 'px-6 py-3 text-base',
};

export function Button({
  children,
  variant = 'primary',
  size = 'md',
  loading = false,
  disabled,
  className = '',
  ...props
}: ButtonProps) {
  const isDisabled = disabled || loading;

  return (
    <button
      className={[
        'inline-flex items-center justify-center gap-2',
        'font-medium rounded-md',
        'transition-colors duration-150',
        'focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2',
        variantClasses[variant],
        sizeClasses[size],
        isDisabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer',
        className,
      ].join(' ')}
      disabled={isDisabled}
      {...props}
    >
      {loading && (
        <svg
          className="animate-spin h-4 w-4"
          viewBox="0 0 24 24"
          fill="none"
        >
          <circle
            className="opacity-25"
            cx="12" cy="12" r="10"
            stroke="currentColor"
            strokeWidth="4"
          />
          <path
            className="opacity-75"
            fill="currentColor"
            d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
          />
        </svg>
      )}
      {children}
    </button>
  );
}

What You See in Storybook

When you open Storybook with the stories file from the previous section, here's what the experience looks like:

• Sidebar: You see a tree with "Components" expanded, "Button" listed under it, and five story names below: Primary, Secondary, Disabled, Loading, Destructive.
• Canvas: Click any story and the button renders centered in the canvas area. No nav bar, no page layout, no distractions.
• Controls panel: Below the canvas, you see dropdowns for "variant" and "size", toggles for "disabled" and "loading". Change "variant" to "destructive" and the button turns red instantly.
• Actions panel: Click the button and you see the click event logged in an "Actions" tab — useful for verifying event handlers fire correctly.

That's the whole loop. Build the component, write the stories, open Storybook, see everything. No routing, no database, no login flow. Just the component doing its job in isolation.

How AI Generates .stories.tsx Files

Here's where the workflow gets really good for vibe coders.

Story files follow a very consistent, pattern-based format. That means AI tools — Claude, Cursor, Copilot — generate them extremely well. Once you show the AI what a story file looks like, it can produce one for any component you hand it with minimal guidance.

The Prompt That Works

Claude and Cursor both handle this well. The output will be close to production-ready. You might adjust story names or add edge cases, but the structure and wiring will be correct.

The key detail in the prompt is "CSF3 format" — that's Component Story Format version 3, which is the current standard. Mentioning it steers the AI away from older CSF2 syntax that shows up frequently in training data.

AI Discovers Missing Component States

There's a secondary benefit that's easy to overlook. When you ask AI to write stories, it has to think about every state your component should support. And sometimes it'll generate a story for a state you forgot to handle.

For example, you build a Button component and forget to handle the loading state. You ask AI for stories and it includes:

export const Loading: Story = {
  args: {
    children: 'Saving...',
    variant: 'primary',
    loading: true,
  },
};

You open Storybook, click the Loading story, and see... the button doesn't show a spinner. It just looks like a normal primary button because you never wired up the loading prop. The story found the gap.

This is Storybook doing something subtle but valuable: it makes component API design visible. You can see immediately whether the component you built actually supports the states it should support. No integration tests required, no navigating to a specific page. Just click the story.

Generating Stories for Complex Components

For more complex components — a data table, a modal, a multi-step form — the same approach applies but the AI prompt needs more context.

The "mock the data inline" instruction is important. AI will sometimes try to import mock data from a separate file, which creates unnecessary complexity. Keeping everything in the story file makes it self-contained and easier to maintain.

Addons: Extending What Storybook Can Do

Out of the box, Storybook gives you component preview, controls, and actions. But the real power comes from addons — plugins that extend what Storybook can do.

Most Storybook setups come with the Essentials bundle pre-installed, which includes:

• Controls — The prop manipulation panel we covered above
• Actions — Event logging for callbacks and event handlers
• Backgrounds — Switch between light, dark, and custom backgrounds to check contrast
• Viewport — Preview components at different screen sizes without resizing your browser
• Docs — Auto-generates a documentation page for each component from the story metadata and JSDoc comments

Beyond Essentials, the most useful addons for vibe coders building with AI:

@storybook/addon-a11y — Runs accessibility checks on each story automatically. It highlights contrast failures, missing alt text, and ARIA issues right in the Storybook UI. This is the kind of thing AI often misses, and this addon catches it without you needing to know the accessibility rules by heart.

@chromatic/storybook-addon — Connects Storybook to Chromatic, a visual testing service that takes screenshots of every story and alerts you when something changes visually. It's like having a before/after photo of every component after every code change.

storybook-addon-designs — Lets you embed Figma frames alongside your stories. If someone hands you a design file, you can put the design and the implementation side by side in Storybook and compare them directly.

The Docs Addon Is Especially Useful

The Docs addon deserves a mention of its own. When it's installed, Storybook automatically generates a "Docs" page for each component that shows:

• A rendered preview of the default story
• A props table with every prop, its type, its default value, and a description
• All the stories displayed in a single scrollable page

The props table is pulled from TypeScript types automatically. If your component has a well-typed interface (which AI typically generates), the docs write themselves. You get a living reference document that always reflects the actual component code — no manual documentation maintenance required.

Setting Up Storybook in a New Project

Getting Storybook running is a one-command process in most cases:

# In your existing React/Vite/Next.js project
npx storybook@latest init

The CLI detects your framework automatically — React, Vue, Next.js, Remix, whatever — and installs the right dependencies, generates a .storybook/ configuration directory, and creates a few example story files to get you started.

After init, you'll have:

your-project/
├── .storybook/
│   ├── main.ts          ← tells Storybook what framework, addons, and story patterns to use
│   └── preview.ts       ← global decorators, parameters, and CSS imports
├── src/
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Button.stories.tsx   ← story files live next to components
│   └── stories/
│       └── Introduction.mdx     ← example docs page
└── package.json

To run it:

npm run storybook

That starts the dev server and opens localhost:6006. From there, any .stories.tsx file you add anywhere in src/ will automatically appear in the sidebar.

What's in the Config Files

The .storybook/main.ts file is where you tell Storybook how to find your stories and which addons to enable:

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

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

export default config;

The preview.ts file is for global setup — importing your global CSS, setting up decorators (wrappers that add context like a theme provider to every story), and configuring global parameters:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';
import '../src/index.css'; // import your global styles

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#0A0E1A' },
      ],
    },
  },
};

export default preview;

You rarely need to edit these files manually. AI can handle them if you describe what you need — "add Tailwind CSS support to Storybook" or "add a dark background option."

Storybook and Testing: Two Tools That Work Together

Storybook isn't a test runner by itself, but it integrates tightly with testing tools. Stories are a natural foundation for tests because each story already represents a specific, reproducible component state.

If you're using Vitest for unit testing, you can import your stories directly into test files and run assertions against them. The @storybook/testing-library package makes this straightforward:

// Button.test.tsx
import { render, screen } from '@testing-library/react';
import { composeStories } from '@storybook/testing-library';
import * as stories from './Button.stories';

const { Primary, Disabled, Loading } = composeStories(stories);

describe('Button', () => {
  it('renders primary button with correct text', () => {
    render(<Primary />);
    expect(screen.getByRole('button', { name: 'Save Changes' })).toBeInTheDocument();
  });

  it('disables the button when disabled prop is true', () => {
    render(<Disabled />);
    expect(screen.getByRole('button')).toBeDisabled();
  });

  it('disables the button when loading', () => {
    render(<Loading />);
    expect(screen.getByRole('button')).toBeDisabled();
  });
});

The advantage here is that your stories and your tests stay in sync. The story defines what "Disabled" looks like; the test verifies it behaves correctly. If you change the component, both the visual story and the behavioral test update together. No duplication, no divergence.

This is one of those workflow patterns that sounds abstract until you experience the alternative: maintaining tests that describe component states you can't easily visualize, and stories that don't connect to any test coverage. Storybook bridges that gap.

What to Learn Next

You now have a solid foundation for using Storybook in your AI-assisted workflow. Here's where to go from here:

• What Is a Component? — If you want to understand the deeper concept behind what Storybook is organizing, start here. Components are the fundamental building block that makes Storybook useful.
• What Is React? — Storybook works with many frameworks, but React is the most common. Understanding how React components work makes Storybook stories click immediately.
• What Is Vitest? — The natural pairing with Storybook for testing. Vitest runs your unit tests fast; Storybook shows you what the component looks like. Together they cover behavior and appearance.

The broader principle here is worth naming: the best AI-assisted development workflow is one where you can see what you're building incrementally, in isolation, without needing everything to be connected and working at once. Storybook gives you that for UI components. It's the showroom that lets you approve each piece before it goes to the job site.

Frequently Asked Questions