How to structure a Storybook that works as a contract

Storybook is not a gallery

In 2024, of almost 17 million sites analyzed by the Web Almanac, only 29% of mobile sites had text with sufficient contrast. Seven out of ten are hard to read on a phone, and almost none did it on purpose: nobody checked. Many teams install Storybook, write twenty stories and abandon it after three months. The problem is not the tool: it was used as a showcase and not as what it can be, the visual and behavioral contract between design, development and QA. A contract says what exists, how it is used, which states it can be in and what is not allowed. It does not replace design decisions or the API contract; it is the most useful evidence of how the interface behaves.

1. A hierarchy, with dependencies that flow downward

We use Atomic Design as a composition vocabulary —atoms, molecules, organisms— and extend it when that helps govern the product:

Foundations → Atoms → Molecules → Organisms → Sections → Pages

• Foundations: colors, typography, spacing, visual patterns. They are not components: they are the rules.
• Atoms: button, field, icon, badge. They know nothing about business rules, even if they have behavior of their own.
• Molecules: a field with its label and its error; a card.
• Organisms: header, footer, a complete form.
• Sections: content blocks configurable through properties, instead of being copied page by page.
• Pages: they orchestrate data, routes and context; reusable presentation logic lives below.

It is an architecture convention, not a universal law. The rule that makes it useful is the direction: a base layer never imports a product layer. That does not prevent a change to a token or a shared component from affecting the pages —it should affect them—, but it makes the impact traceable and obliges whoever consumes it to verify.

Do you know today which screens change if your brand's main color changes tomorrow?

2. Foundations, as text you can read

Before the first button, document the foundations as narrative pages inside Storybook itself: the palette and when each color is used, the typography and its hierarchy, the visual patterns. And let them live as tokens: color is not written in the component, it is taken from the token. That way, changing the brand means changing a token, and visual regression tells you what else changed. (The standard token format is still a draft, and its own text asks not to implement it yet: tokens are defined in your system and exported when the standard stabilizes.)

3. Every story answers four questions

1. What it is and when it is used (and when it is not).
2. Its variants: sizes, tones, with an icon or without.
3. Its states: loading, empty, with an error, disabled, submitting, and the edge cases —long texts, incomplete data, slow responses—. That is where the experience breaks.
4. Its accessibility: how a screen reader announces it, what happens with the keyboard and focus, what happens if the user asked for less motion.

// Illustrative (Storybook 9, CSF3). Assumes: type Story = StoryObj<typeof meta>
// and that expect is imported from your version's test utilities path.
export const ConError: Story = {
  args: { etiqueta: "Correo", error: "Escriba un correo válido" },
  play: async ({ canvas }) => {
    const campo = canvas.getByLabelText("Correo");
    await expect(campo).toHaveAttribute("aria-invalid", "true");
    await expect(canvas.getByRole("alert")).toBeVisible();
  },
};

The story fixes an error state and checks its semantics: that the field is marked as invalid and that the message is exposed as an alert. That brings it closer to a contract. For critical flows, in addition, it is validated by hand with keyboard and screen reader: automation does not cover everything.

4. Three kinds of review, not one

• Interaction tests: that states and behavior are the expected ones, as in the example.
• Automated accessibility review on every story: contrast, roles, accessible names. Mind its limits: on average, automated tests find 57% of accessibility problems (Deque, across more than 13,000 pages), and the WCAG 2.2 rule for the minimum size of touch targets comes switched off by default in the most widely used tool. It has to be turned on by hand; the rest is covered by keyboard and screen reader review.
• Visual regression: the one that detects that a token change moved something on twenty screens nobody opened.

Together they are what turns a catalog into a contract.

5. Context, from the toolbar

If your product uses several languages or a light and dark theme, expose them as Storybook global controls, connected through decorators to the same context providers as the real application. Use them to explore the risky combinations —the button that doesn't fit in German, the text that disappears in dark mode— and define which combinations are always tested.

6. It publishes itself

A Storybook that someone has to remember to publish is already out of date. It is published automatically when approved changes are integrated, as a reference that design, QA and the client can open, with the access the sensitivity of the product requires. That reference is the one that gets reviewed, not a screenshot in a chat.

7. When something moves up a level

The brand's primitives —button, field, typography— are born as part of the system from day one. For everything else:

• Repetition is a signal, not a threshold. A pattern is consolidated when its intent and its variants are already stable; abstracting earlier tends to cost more than a visible duplicate. In practice, that rarely happens before the third use.
• Sharing across projects calls for governance. When a second product needs the same components, the system becomes a package with a clear owner, versions and an adoption path; that is where Storybook tends to become the most useful reference, without replacing the documentation of decisions.

What we still lack, said out loud

We review accessibility automatically on every story, but today the review warns and does not block. The step many teams postpone —and that we require as the next one— is for an accessibility failure or a broken state to stop publication, just like a red test. A contract that cannot stop a change is only a suggestion.

Next in the series: Modern frontend paradigms, without the hype · What a professional frontend needs before going to production.