Marcus Andrey Study
Ler em português Library

Design Systems · Step 5 · 6 min read

Storybook and living documentation

Documentation that is written once goes stale. Documentation that renders the real component can't. What Storybook is, what a story is, how stories become docs, accessibility checks and visual tests, and how it links to Figma, so designers can see what's really built.

A screenshot of a component is a promise. A story is proof. The Figma library shows what the Button should be; the code is what it is. Storybook puts the code on a page where anyone can see every state, try every option and spot the difference. For a designer, it's the fastest way to answer "what did we actually build?" without opening a pull request.

What you'll be able to do after reading:

  • Explain what Storybook is and what a story is, in plain words
  • Read a story file and know which states it covers
  • Use Storybook to review components as a designer
  • Describe what automated accessibility checks and visual tests catch, and what they miss

1. A workshop, not a website

Storybook describes itself as "a frontend workshop for building UI components and pages in isolation" (Storybook docs). In isolation means outside the app: no login, no real data, no need to find the one screen where the error state appears. Each component sits on its own page with its states listed down the side.

The unit is the story: "a story captures the rendered state of a UI component", and "each story describes a different component state" (Storybook docs). For the Harbour Button, the stories are Primary, Secondary, Danger, Compact, Disabled and Long label. That list should look familiar: it's the variants and edge cases from States and edge cases, written as code.


2. What a story looks like

You don't need to write stories to use Storybook, but reading one helps. This is the shape of a story file in Storybook's own format (Component Story Format), for the Harbour Button:

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

const meta = {
  component: Button,
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;

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

export const Primary: Story = {
  args: { variant: 'primary', children: 'Book sailing' },
};

export const Compact: Story = {
  args: { variant: 'primary', size: 'compact', children: 'Check in' },
};

Storybook uses "the generic term arguments (args for short)" for a component's props (Storybook, How to write stories). Each exported story is one set of args. The tags: ['autodocs'] line is the next section.


3. Controls: every combination, one click away

Book sailing Book sailing View timetable View timetable Cancel booking Cancel booking
Controls
variant
size
disabled

args: { variant: 'primarysecondarydanger', size: 'defaultcompact', disabled: falsetrue }

Try it: change the controls and the story re-renders, the way Storybook's Controls panel does. This is a CSS imitation built for this page, not Storybook itself, but the idea is the same: every combination a designer drew in Figma is one click away in the real component, in light and dark (switch the site's theme). The primary button measures 6.35 to 1 in light mode (white on #1F5FAE) and 5.32 to 1 in dark (#14202B on #5B95DB).

The Controls panel lets anyone change a story's args and watch the component re-render. For a designer this is a review tool: set the Button to danger and compact, switch the theme, type a label in German, and compare with the Figma component next to it. If a combination looks wrong in code but right in Figma, you've found drift before a user did.


4. From stories to docs

Add the autodocs tag and Storybook "automatically generates a documentation page" for the component: the first story at the top, "an interactive table with all the relevant args", and an overview of the other stories (Storybook, Autodocs). It updates every time the code changes, which is what living documentation means: it can't describe a prop that no longer exists.

What it can't do is explain. A props table says variant accepts danger; it doesn't say "only for actions that can't be undone, always with a confirmation". That's why Storybook is one layer of the docs, not all of it. The usage guidance belongs on the doc page (Component docs people use), and Storybook's MDX pages can hold it next to the live examples.


5. Checks that run on every story

  • Accessibility. Storybook's accessibility addon is built on Deque's axe-core, which, in Storybook's words, "automatically catches up to 57% of WCAG issues" (Storybook, Accessibility tests). Read that number from the other side: more than four in ten issues need a person. Automated checks find a missing label or low contrast; they can't tell whether the focus order makes sense or the label means anything (see Accessible components).
  • Visual tests. Storybook can take snapshots of every story and "compare those snapshots to baselines", the last known good ones, using Chromatic, a cloud service from the Storybook team (Storybook, Visual tests). Change a token, and every story that moved by a pixel shows up for review. That's how a system team knows what a release will change before it ships (Versioning and releases).

6. Linking Storybook and Figma

Storybook's docs describe two ways (Storybook, Design integrations):

  • Figma in Storybook, with the Designs addon: add a design parameter with the Figma URL to a story, and the design appears in a tab next to the component.
  • Storybook in Figma, with the Storybook Connect plugin, which links stories to Figma components and variants. It needs the Storybook published to Chromatic.

Either way, the point is to put the two copies side by side, so the comparison takes seconds instead of a meeting.


7. Common mistakes

  • Stories only for the happy path: no error, no long label, no disabled.
  • Treating the generated props table as the whole documentation.
  • Reading "no accessibility violations" as "accessible".
  • A Storybook that designers don't know exists, or can't open without asking for access.
  • Stories with fake wrappers and styles that the real app doesn't have, so the story lies.

8. Vocabulary

Term Meaning
Storybook A workshop for building and viewing UI components outside the app
Story One rendered state of a component, defined by its args
Args Storybook's word for a component's props
Controls The panel where you change args and watch the component update
Autodocs A doc page Storybook generates from the stories and props
Visual test A snapshot of a story compared against an approved baseline
Living documentation Docs that render the real component, so they change when it changes

9. Try it (no tools needed)

  1. Pick a component and list every state a user could see: default, hover, focus, disabled, loading, error, long text, empty.
  2. Next to each, write whether it exists in your Figma file and whether a developer could show it to you in under a minute.
  3. The gaps are the stories your team is missing.

Reflection questions: If your team has a Storybook, when did you last open it? Which decision would have gone faster if you had?


10. If you already practise

  • Review new components in Storybook before they merge, with the Figma frame in the Designs tab.
  • Ask for a story for every edge case you draw.
  • Keep a short manual accessibility pass for each component, next to the automated one.
  • Use visual test results in release reviews: they show exactly what a token change touched.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

States and edge cases · Accessible components · Component docs people use · Code Connect and the design-code bridge · Documenting motion in a design system

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close