Storybook

O que é o Storybook?

O Storybook é um workshop para componentes de UI. Ele renderiza um componente de forma isolada, fora da sua aplicação, permitindo que você o desenvolva sem precisar navegar até a página correta ou satisfazer condições específicas. Cada estado relevante torna-se uma story, e a coleção de stories transforma-se em uma documentação viva.

O que começou como uma ferramenta de desenvolvimento evoluiu para muito mais: um auditor de acessibilidade, uma superfície para testes de interação e um alvo para regressão visual. Para equipes que constroem design systems ou bibliotecas de componentes compartilhadas, ele é frequentemente a ferramenta de front-end mais valiosa depois do próprio framework.

Stories

Um arquivo de story exporta um objeto meta padrão e um export nomeado para cada estado.

// Button.stories.jsx
import { Button } from "./Button";

export default {
  title: "Components/Button",
  component: Button,
  args: { children: "Save" },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "ghost"],
    },
  },
};

export const Primary = {
  args: { variant: "primary" },
};

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

export const Disabled = {
  args: { disabled: true },
};

O title determina onde o componente aparece na barra lateral. O component vincula a story ao componente para que o Storybook possa inferir as props e gerar a documentação. Cada export nomeado é uma story.

Args e controls

Args são as props que uma story passa para o componente. O Storybook as transforma em um painel de controls, permitindo que você altere os valores em tempo real sem precisar editar o código.

// Card.stories.jsx
export default {
  title: "Components/Card",
  component: Card,
  args: {
    title: "Pro plan",
    description: "Everything you need to ship.",
    elevated: false,
  },
};

Como os args são dados estruturados, eles também alimentam o autodocs, podem ser compartilhados entre stories e podem ser reutilizados por testes de interação. Definir a marcação inline em uma função render funciona, mas você perde os controls em tempo real e a fonte única de verdade, por isso, prefira usar args.

Decorators e contexto

Alguns componentes precisam de um provider, um tema ou um wrapper de layout. Os Decorators fornecem esse contexto ao redor de uma story.

// preview.jsx
export default {
  decorators: [
    (Story) => (
      <ThemeProvider theme="dark">
        <div style={{ padding: "1rem" }}>
          <Story />
        </div>
      </ThemeProvider>
    ),
  ],
};

Um decorator pode ser global, por arquivo ou por story, o que facilita a revisão de um componente em diferentes temas ou locales sem a necessidade de alterar o próprio componente.

Autodocs

O Storybook pode gerar uma página de documentação a partir das suas stories e seus args. Com o autodocs habilitado, cada componente recebe uma página listando suas props, controls e cada story, que permanece sincronizada automaticamente por ser gerada a partir da mesma fonte. Você pode enriquecê-la com descrições, notas de uso e exemplos de código utilizando a API parameters.docs.

Testes de interação

Uma story pode definir uma play function que é executada após a renderização do componente. Ela utiliza as mesmas queries e eventos do Testing Library, portanto, o modelo mental é transferido diretamente.

// Search.stories.jsx
import { expect, userEvent, within } from "@storybook/test";

export const TypesAndSubmits = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText("Search"), "vitest");
    await userEvent.click(canvas.getByRole("button", { name: "Go" }));

    await expect(canvas.getByText("3 results")).toBeVisible();
  },
};

Como o teste é executado dentro do Storybook, você pode acompanhá-lo passo a passo, o que torna a depuração muito mais fácil do que analisar uma falha no CI. As mesmas stories podem ser executadas em modo headless no CI utilizando o test runner do Storybook.

Acessibilidade e testes visuais

O addon de acessibilidade executa o axe em cada story e reporta violações no painel do addon, agrupadas por impacto. Ele detecta labels ausentes, contraste insuficiente, ARIA inválido e problemas semelhantes enquanto você desenvolve, o que é muito mais barato do que corrigi-los posteriormente.

Ferramentas de regressão visual capturam um screenshot por story e o comparam com um baseline. Como cada estado já é um story, você obtém uma ampla cobertura visual com pouco esforço extra. Um screenshot alterado sinaliza uma mudança visual não intencional para revisão.

Onde o Storybook se encaixa

O Storybook fica posicionado entre os testes unitários e os testes end-to-end. Ele não substitui nenhum dos dois. Use-o para desenvolver e documentar componentes isoladamente, testar estados interativos com play functions e auditar a acessibilidade e o visual. Mantenha os testes de lógica rápidos no Vitest, o comportamento dos componentes no Testing Library e as jornadas completas no Playwright.

Melhores práticas

• Escreva uma story para cada estado relevante, incluindo loading, vazio e erro.
• Prefira args em vez de markup inline para que os controles e a documentação permaneçam precisos.
• Coloque as stories junto aos seus componentes e nomeie-as de acordo com a finalidade.
• Use decorators para providers, temas e layout em vez de duplicar wrappers.
• Adicione play functions para interações e execute-as no CI.
• Ative o addon de acessibilidade e corrija as violações conforme elas surgirem.
• Publique o Storybook buildado como documentação viva.

Erros comuns

• Escrever apenas uma story “Default” e ignorar estados reais.
• Fazer hardcode de props em render, perdendo os controles e a documentação.
• Tratar o Storybook como um substituto para testes unitários ou end-to-end.
• Deixar que as stories fiquem defasadas em relação às props reais do componente.
• Ignorar avisos de acessibilidade até que eles se acumulem.
• Duplicar a configuração de providers em cada story em vez de usar um decorator.

Próximos passos

O Storybook transforma componentes em um catálogo documentado e testável. Combine-o com Testing Library para as queries dentro das play functions, Vitest para testes de lógica e Playwright para fluxos end-to-end. Agora, escolha o seu componente mais reutilizado e crie stories para cada estado possível dele.