Todos os artigos

Front-end10 min de leitura

Storybook: como começar e até onde vale a pena ir

Storybook 10 do zero: instalar, escrever stories, testar interação e acessibilidade no Vitest e decidir, nível por nível, até onde vale a pena ir no seu projeto.

Também em English, Español, Français

Storybook é uma daquelas ferramentas que todo mundo já ouviu falar e pouca gente usa direito. Ou o projeto nunca instala, ou instala, escreve três stories do botão e abandona, ou tenta cobrir tudo e passa a gastar mais tempo mantendo stories do que escrevendo tela.

Este post faz o caminho do meio: mostra como começar em poucos minutos e organiza o que vem depois em níveis, pra você decidir até onde faz sentido ir no seu projeto.

Um aviso honesto: tudo aqui foi feito num projeto real com Storybook 10.6, React 19 e Vite. As stories do post rodam como testes e passam, e a checagem de acessibilidade foi conferida derrubando de propósito uma story com um botão sem nome.

TL;DR#

  • Storybook é uma vitrine dos seus componentes, fora do app, em todos os estados: vazio, carregando, com erro, com texto enorme.
  • Começar é um comando: npm create storybook@latest. Ele detecta o framework e já configura testes e acessibilidade.
  • Uma story é só um componente com dados. O formato atual (CSF) é um objeto com args.
  • Stories viram testes. Com o addon de Vitest, cada story é renderizada num navegador de verdade, e a play simula o clique e confere o resultado.
  • Até onde ir: pra quase todo projeto, stories dos componentes visuais, testes de interação e acessibilidade bastam. Teste visual e documentação caprichada fazem sentido em design system e componente compartilhado.
  • Não escreva story de página que depende de API. Story boa é de componente que recebe tudo por props.

Pra que serve#

Sem Storybook, pra ver um componente num estado específico você precisa navegar no app até a tela certa, com os dados certos. Ver o cartão de pedido com um nome de cliente enorme significa criar um cliente com nome enorme. Ver a lista vazia significa apagar os pedidos.

Com Storybook, cada estado vira uma story: uma entrada fixa, que abre em um clique. Isso ajuda em quatro coisas:

  • Desenvolver o componente isolado, sem depender de backend, login ou navegação.
  • Pegar casos de borda que quase nunca aparecem no app: texto longo, lista vazia, valor zero.
  • Conversar com design e produto, mostrando todos os estados num lugar só.
  • Testar, porque cada story pode virar um teste automático.

Nível 0: instalar#

Num projeto que já existe, na raiz:

npm create storybook@latest

O instalador olha as dependências do projeto e escolhe a configuração. Num projeto com React e Vite, a versão 10.6 instalou:

  • o Storybook com o framework @storybook/react-vite;
  • @storybook/addon-vitest, que transforma stories em testes;
  • @storybook/addon-a11y, que roda a checagem de acessibilidade;
  • @storybook/addon-docs, que gera a página de documentação de cada componente;
  • @storybook/addon-mcp, a integração com assistentes de IA (mais no fim);
  • o Playwright com o Chromium, que os testes usam pra renderizar as stories.

E criou dois scripts:

npm run storybook        # opens Storybook at localhost:6006
npm run build-storybook  # generates a static site in storybook-static/

A configuração fica em .storybook/:

.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
 
const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-mcp',
  ],
  framework: '@storybook/react-vite',
};
 
export default config;

O instalador também cria uma pasta src/stories com exemplos (botão, cabeçalho, página). Vale olhar uma vez e apagar.

Funciona com Angular também: a documentação lista Angular 18 ou mais novo, e os conceitos abaixo são os mesmos. Os exemplos deste post são em React.

Nível 1: stories dos componentes visuais#

Os exemplos usam os componentes de uma lista de pedidos, os mesmos do post sobre smart e dumb components: OrderCard, OrderList e StatusFilter. Eles recebem tudo por props, e é exatamente por isso que são fáceis de colocar no Storybook.

Uma story mora ao lado do componente, num arquivo .stories.tsx:

OrderCard.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderCard } from './OrderCard';
 
const meta = {
  title: 'Orders/OrderCard',
  component: OrderCard,
  tags: ['autodocs'],
  args: {
    order: { id: '42', customer: 'Ana Souza', total: 189.9, status: 'paid' },
    onSelect: fn(),
  },
} satisfies Meta<typeof OrderCard>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Default: Story = {};
 
export const Selected: Story = {
  args: { selected: true },
};
 
export const LongCustomerName: Story = {
  args: {
    order: { id: '43', customer: 'Maria Aparecida dos Santos Albuquerque Ferreira', total: 12999.5, status: 'pending' },
  },
};
 
export const ClickingDetailsSendsTheId: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Details' }));
    await expect(args.onSelect).toHaveBeenCalledWith('42');
  },
};

Lendo de cima pra baixo:

  • meta descreve o componente: o nome na barra lateral (title), qual componente é e os args padrão, que são as props.
  • fn() cria uma função espiã pro onSelect. No Storybook, cada chamada aparece no painel de ações.
  • Cada export é uma story. Default usa os args padrão, Selected muda só o que precisa, LongCustomerName testa o caso de borda do nome enorme.
  • tags: ['autodocs'] gera uma página de documentação com todas as stories e uma tabela das props, tirada dos tipos do TypeScript.

O que vale virar story é estado, não variação aleatória. Pra um cartão de pedido: o padrão, o selecionado, o nome longo, o valor alto. Pra uma lista: vazia e com itens.

OrderList.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderList } from './OrderList';
 
const meta = {
  title: 'Orders/OrderList',
  component: OrderList,
  args: { selectedId: null, onSelect: fn(), orders: [] },
} satisfies Meta<typeof OrderList>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Empty: Story = {
  play: async ({ canvas }) => {
    await expect(canvas.getByText('No orders here yet.')).toBeVisible();
  },
};
 
export const WithOrders: Story = {
  args: {
    selectedId: '2',
    orders: [
      { id: '1', customer: 'Ana', total: 89, status: 'paid' },
      { id: '2', customer: 'Bruno', total: 240, status: 'pending' },
      { id: '3', customer: 'Carla', total: 1320, status: 'shipped' },
    ],
  },
};

Nível 2: controls e documentação#

Esse nível vem quase de graça. Como as props estão em args, o Storybook monta o painel Controls sozinho: dá pra mudar o nome do cliente, o status ou o valor direto na tela e ver o componente reagir. É ótimo pra mostrar o componente pra quem não programa.

E o autodocs junta tudo numa página por componente. Pra componente compartilhado, essa página costuma substituir um README que ninguém atualiza.

Nível 3: testes de interação#

Aqui o Storybook deixa de ser vitrine e vira ferramenta de teste. A função play roda depois que a story aparece na tela: ela clica, digita e confere.

Volte na última story do OrderCard: ClickingDetailsSendsTheId clica no botão "Details" e confere que onSelect foi chamado com o id '42'. Componentes com estado próprio também funcionam:

StatusFilter.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { useState } from 'react';
import { expect } from 'storybook/test';
import { StatusFilter, type StatusFilterValue } from './StatusFilter';
 
const meta = {
  title: 'Orders/StatusFilter',
  component: StatusFilter,
  args: { value: 'all', onChange: () => {} },
  // Keeps the value in local state so the story behaves like the real screen.
  render: function Render(args) {
    const [value, setValue] = useState<StatusFilterValue>(args.value);
    return <StatusFilter value={value} onChange={setValue} />;
  },
} satisfies Meta<typeof StatusFilter>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Interactive: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'paid' }));
    await expect(canvas.getByRole('button', { name: 'paid' })).toHaveClass('active');
  },
};

O render guarda o valor num useState, pra que a story se comporte como a tela de verdade, e a play clica em "paid" e confere que o botão ficou ativo.

O mais importante: com o addon de Vitest, toda story é um teste, mesmo as que não têm play. A story que só renderiza já testa que o componente não quebra com aqueles dados. Pra rodar tudo:

npx vitest run --project=storybook

No projeto do post: 6 arquivos, 15 testes, todos passando, num Chromium de verdade, sem abrir janela. E dá pra rodar o mesmo comando na CI:

.github/workflows/storybook.yml
name: Storybook tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx vitest run --project=storybook

Nível 4: acessibilidade#

O addon de acessibilidade roda o axe, a mesma biblioteca de várias extensões de navegador, em cada story. O instalador configura assim:

.storybook/preview.tsx
import type { Preview } from '@storybook/react-vite';
 
const preview: Preview = {
  parameters: {
    a11y: {
      // 'todo': shows violations in the UI only. 'error': fails the test.
      test: 'todo',
    },
  },
};
 
export default preview;

Com 'todo', os problemas aparecem no painel mas não derrubam nada. Com 'error', viram falha de teste. Pra conferir, criei uma story com um botão que só tem um ícone e nenhum texto. Com 'error', o teste falhou com a regra button-name do axe: botões precisam de um texto que um leitor de tela consiga ler.

Um caminho que funciona bem: comece com 'todo', corrija o que aparecer e passe pra 'error' quando estiver limpo. A partir daí, componente novo com problema de acessibilidade não entra.

Um limite importante: checagem automática pega uma parte dos problemas, como falta de nome, contraste e atributos errados. Ordem de leitura, foco e se a experiência faz sentido com leitor de tela continuam precisando de teste manual.

Nível 5: teste visual#

Teste de interação confere comportamento. Teste visual confere aparência: tira um print de cada story e compara com o anterior, avisando quando um pixel mudou. É o que pega a mudança de CSS que quebrou um componente em outra tela.

O addon que o instalador adicionou (@chromatic-com/storybook) liga o Storybook ao Chromatic, serviço pago da mesma equipe do Storybook. Em novembro de 2026, o plano gratuito dava 5.000 snapshots por mês, só no Chrome.

Vale a pena quando muita gente mexe nos mesmos componentes, como num design system. Num app pequeno, costuma custar mais atenção (revisar diferenças que eram esperadas) do que economiza.

Nível 6: IA#

O addon-mcp liga o Storybook a assistentes de IA. Segundo a documentação, o agente passa a conhecer seus componentes e a documentação deles, gera stories e roda os testes de interação e acessibilidade pra conferir o próprio trabalho. A própria documentação avisa que esses recursos estão em preview e podem mudar.

O valor real aparece quando o Storybook já está bem cuidado: o agente reaproveita os componentes que existem em vez de inventar outros. Num Storybook com três stories abandonadas, ele não tem muito o que aprender.

Até onde ir#

Minha recomendação, por tipo de projeto:

Até o nível 4 vale pra quase todo projeto. Daí pra cima, depende de quantas pessoas usam os mesmos componentes
  • App pequeno, uma ou duas pessoas: níveis 0 a 3, só nos componentes visuais que você reaproveita. O ganho é desenvolver isolado e ter testes de interação de graça.
  • App de time: níveis 0 a 4, com os testes rodando na CI e a acessibilidade em 'error'.
  • Design system ou biblioteca compartilhada: todos os níveis. Aqui o Storybook é o produto: documentação, catálogo e garantia de que nada mudou sem querer.

E o que eu não faria em nenhum caso:

  • Story de página inteira que busca dados. Exige simular API, autenticação e rota, e quebra a cada mudança no backend. Se a tela tem uma parte visual importante, separe essa parte num componente que recebe props e faça a story dele.
  • Story pra cada combinação de props. Seis tamanhos vezes quatro cores vezes dois estados não ajudam ninguém. Escolha os estados que importam e deixe o resto pro painel de controls.
  • Perseguir 100% de cobertura. Story de componente que ninguém reaproveita e ninguém mexe é manutenção sem retorno.
  • Story que ninguém roda. Se as stories não estão na CI, elas quebram em silêncio e o Storybook vira museu.

Erros comuns#

  • Componente que busca dados dentro dele. Ele não entra no Storybook sem simular a API. A solução quase sempre é separar a parte visual, recebendo tudo por props.
  • Args grandes copiados em toda story. Coloque os dados padrão no meta.args e mude só o necessário em cada story.
  • Ações sem fn(). Sem a função espiã, a play não consegue conferir o que foi chamado, e o painel de ações fica vazio.
  • Deixar os exemplos do instalador. O botão e a página de exemplo poluem a barra lateral e os testes.
  • Acessibilidade sempre em 'todo'. Aviso que nunca vira erro acaba ignorado.

Checklist#

  • Storybook instalado com npm create storybook@latest, exemplos apagados.
  • Stories ao lado dos componentes visuais, com os estados que importam (padrão, vazio, longo, erro).
  • Dados padrão em meta.args, funções de evento com fn().
  • autodocs nos componentes compartilhados.
  • play nos comportamentos importantes (clique, digitação, seleção).
  • npx vitest run --project=storybook rodando na CI.
  • Acessibilidade em 'error' quando o projeto estiver limpo.
  • Teste visual só se muita gente mexe nos mesmos componentes.
  • Nenhuma story de página que depende de API.

Referências#

  • Front-end
  • storybook
  • react
  • testes
  • design-system
  • acessibilidade

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.

Comentários

Pra comentar, entre com sua conta do GitHub.