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.

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
playsimula 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@latestO 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/:
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:
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:
metadescreve o componente: o nome na barra lateral (title), qual componente é e osargspadrão, que são as props.fn()cria uma função espiã proonSelect. No Storybook, cada chamada aparece no painel de ações.- Cada
exporté uma story.Defaultusa os args padrão,Selectedmuda só o que precisa,LongCustomerNametesta 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.
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:
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=storybookNo 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:
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=storybookNí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:
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:
- 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.argse mude só o necessário em cada story. - Ações sem
fn(). Sem a função espiã, aplaynã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 comfn(). autodocsnos componentes compartilhados.playnos comportamentos importantes (clique, digitação, seleção).npx vitest run --project=storybookrodando 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#
Comentários
Pra comentar, entre com sua conta do GitHub.
Leia também

Front-end8 min de leitura
camelCase, PascalCase, kebab-case e snake_case: quando usar

Front-end10 min de leitura
Signals no Angular 22: signal, computed, effect e além

Front-end12 min de leitura
Smart e dumb components no Angular e no React, em 2026