Component to documented states
A reusable component becomes a set of intentional states, reviewable documentation, and automated checks before it reaches a product.
Storybook is not a prettier dev server. It is a contract for components that will outlive the page that first needed them.
If you maintain a library used across projects, themes, or teams, isolated states save review time and catch regressions. If you are building one short lived page with page specific markup, a Storybook can become maintenance theatre. Pick based on the component's future, not the current trend.
Use it when a component has a life of its own
Good candidates have variants, loading and error states, interaction rules, or more than one consumer. An Expandable Card is a good candidate because its closed, open, keyboard, and mobile states all matter. A one off hero composition usually needs a page preview more than a component catalogue.
- Use Storybook for shared primitives and product patterns.
- Use it for a component library with multiple releases or consumers.
- Use it when designers or reviewers need to inspect states without recreating app data.
- Skip it for a single page element that will not be reused or maintained.
Write states, not screenshots
Current Storybook uses Component Story Format. A story is a component plus serialisable args. The useful minimum is not every prop permutation. It is every state that can break a customer journey.
import type { Meta, StoryObj } from '@storybook/react';
import { CtaCard } from './CtaCard';
const meta = {
title: 'Conversion/CtaCard',
component: CtaCard,
tags: ['autodocs'],
parameters: {
a11y: { test: 'error' },
},
args: {
title: 'Build the next thing properly.',
actionLabel: 'Browse components',
href: '/components/',
},
} satisfies Meta<typeof CtaCard>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Default: Story = {};
export const LongLabel: Story = {
args: {
actionLabel: 'See every component in the maintained library',
},
};
export const Loading: Story = {
args: {
isPending: true,
},
};Keep the story data realistic. A long button label, empty state, error state, keyboard focus, and narrow container reveal more than a perfectly centered desktop screenshot.
Make accessibility checks part of the definition
Storybook can run accessibility checks against rendered stories. Setting a story or component to a11y: { test: 'error' } makes violations fail in the UI and CI when the configured test suite runs. It does not replace keyboard and screen reader testing. It catches obvious regressions early.
// .storybook/preview.ts
import type { Preview } from '@storybook/react';
const preview: Preview = {
parameters: {
a11y: {
test: 'error',
},
},
};
export default preview;Do not disable accessibility checks to make a dashboard green. If a story intentionally demonstrates an anti pattern, name it as such and isolate it from production examples.
Use it to improve the Velocity Components subscription
A library subscription is more than a zip of UI. Developers need to see how a component behaves, what it needs, and where it fails before they install it. Storybook is useful behind a component like Shader Backgrounds because it can show a static fallback, reduced motion state, dark palette, and real copy overlay as named examples.
That makes the public component page more credible too. The article teaches why these states matter. The component route gives developers a live preview and source path.
Start small
npx storybook@latest init
npm run storybookAdd stories as you stabilise reusable components. Do not pause product work to document a speculative library. The catalogue should grow from components that have already earned maintenance.