Design systems · Passo 5 · 7 min de leitura
Storybook e documentação viva
Documentação escrita uma vez fica velha. Documentação que desenha o componente real não tem como ficar. O que é o Storybook, o que é uma story, como as stories viram documentação, verificações de acessibilidade e testes visuais, e como ligar tudo ao Figma para o design ver o que foi construído de verdade.
Uma captura de tela de um componente é uma promessa. Uma story é a prova. A biblioteca do Figma mostra o que o Button deveria ser; o código é o que ele é. O Storybook coloca o código numa página onde qualquer pessoa vê cada estado, testa cada opção e percebe a diferença. Para quem desenha, é o jeito mais rápido de responder "o que a gente construiu de fato?" sem abrir um pull request.
O que você vai conseguir fazer depois de ler:
- Explicar em palavras simples o que é o Storybook e o que é uma story
- Ler um arquivo de stories e saber quais estados ele cobre
- Usar o Storybook para revisar componentes como designer
- Descrever o que as verificações automáticas de acessibilidade e os testes visuais pegam, e o que deixam passar
1. Uma oficina, não um site
O Storybook se descreve como "a frontend workshop for building UI components and pages in isolation", uma oficina de frontend para construir componentes e páginas isolados (Storybook docs). Isolado quer dizer fora do app: sem login, sem dados reais, sem precisar achar a única tela onde aparece o estado de erro. Cada componente fica na sua página, com os estados listados ao lado.
A unidade é a story: "a story captures the rendered state of a UI component", uma story captura um estado do componente, e "each story describes a different component state", cada story descreve um estado diferente (Storybook docs). Para o Button do Harbour, as stories são Primary, Secondary, Danger, Compact, Disabled e Long label. A lista deve parecer familiar: são as variantes e os casos-limite de Estados e casos-limite, escritos como código.
2. Como é uma story
Você não precisa escrever stories para usar o Storybook, mas saber ler uma ajuda. Este é o formato de um arquivo de stories no padrão do próprio Storybook (Component Story Format), para o Button do Harbour:
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' },
};
O Storybook usa "the generic term arguments (args for short)", o termo genérico argumentos, ou args, para as props de um componente (Storybook, How to write stories). Cada story exportada é um conjunto de args. A linha tags: ['autodocs'] é assunto da próxima seção.
3. Controls: cada combinação a um clique
args: { variant: 'primarysecondarydanger', size: 'defaultcompact', disabled: falsetrue }
O painel Controls deixa qualquer pessoa mudar os args de uma story e ver o componente se redesenhar. Para quem desenha, é uma ferramenta de revisão: coloque o Button em danger e compact, troque o tema, digite um rótulo em alemão e compare com o componente do Figma ao lado. Se uma combinação parece errada no código mas certa no Figma, você achou o afastamento antes de um usuário.
4. Das stories à documentação
Adicione a tag autodocs e o Storybook "automatically generates a documentation page", gera sozinho uma página de documentação do componente: a primeira story no topo, "an interactive table with all the relevant args", uma tabela interativa com os args, e um resumo das outras stories (Storybook, Autodocs). Ela se atualiza toda vez que o código muda, e é isso que documentação viva quer dizer: ela não tem como descrever uma prop que não existe mais.
O que ela não faz é explicar. Uma tabela de props diz que variant aceita danger; não diz "só para ações que não têm volta, sempre com confirmação". Por isso o Storybook é uma camada da documentação, não ela toda. A orientação de uso fica na página de documentação (Documentação de componentes que as pessoas usam), e as páginas MDX do Storybook podem trazer essa orientação ao lado dos exemplos vivos.
5. Verificações que rodam em cada story
- Acessibilidade. O addon de acessibilidade do Storybook é feito sobre o axe-core, da Deque, que, nas palavras do Storybook, "automatically catches up to 57% of WCAG issues", pega automaticamente até 57% dos problemas de WCAG (Storybook, Accessibility tests). Leia esse número pelo outro lado: mais de quatro em cada dez problemas precisam de uma pessoa. A verificação automática acha um rótulo faltando ou contraste baixo; não sabe se a ordem do foco faz sentido ou se o rótulo quer dizer alguma coisa (veja Componentes acessíveis).
- Testes visuais. O Storybook pode tirar snapshots de cada story e "compare those snapshots to baselines", comparar com as referências, as últimas versões aprovadas, usando o Chromatic, um serviço na nuvem do próprio time do Storybook (Storybook, Visual tests). Mude um token, e toda story que mexeu um pixel aparece para revisão. É assim que o time do sistema sabe o que uma versão vai mudar antes de ela sair (Versões e releases).
6. Ligar o Storybook e o Figma
A documentação do Storybook descreve dois caminhos (Storybook, Design integrations):
- O Figma dentro do Storybook, com o addon Designs: adicione um parâmetro
designcom a URL do Figma a uma story, e o design aparece numa aba ao lado do componente. - O Storybook dentro do Figma, com o plugin Storybook Connect, que liga stories a componentes e variantes do Figma. Ele exige o Storybook publicado no Chromatic.
Nos dois casos, a ideia é colocar as duas cópias lado a lado, para a comparação levar segundos em vez de uma reunião.
7. Erros comuns
- Stories só do caminho feliz: sem erro, sem rótulo longo, sem desativado.
- Tratar a tabela de props gerada como a documentação inteira.
- Ler "nenhuma violação de acessibilidade" como "acessível".
- Um Storybook que o design não sabe que existe, ou não consegue abrir sem pedir acesso.
- Stories com wrappers e estilos falsos que o app real não tem, então a story mente.
8. Vocabulário
| Termo | Significado |
|---|---|
| Storybook | Uma oficina para construir e ver componentes de interface fora do app |
| Story | Um estado desenhado de um componente, definido pelos seus args |
| Args | A palavra do Storybook para as props de um componente |
| Controls | O painel onde você muda os args e vê o componente se atualizar |
| Autodocs | Uma página de documentação que o Storybook gera a partir das stories e das props |
| Teste visual | Um snapshot de uma story comparado com uma referência aprovada |
| Documentação viva | Documentação que desenha o componente real, então muda quando ele muda |
9. Experimente (sem ferramentas)
- Escolha um componente e liste cada estado que um usuário pode ver: padrão, hover, foco, desativado, carregando, erro, texto longo, vazio.
- Ao lado de cada um, escreva se ele existe no seu arquivo do Figma e se alguém do desenvolvimento conseguiria mostrar para você em menos de um minuto.
- Os buracos são as stories que faltam no seu time.
Perguntas para refletir: Se o seu time tem um Storybook, quando você abriu pela última vez? Qual decisão teria sido mais rápida se você tivesse aberto?
10. Se você já pratica
- Revise componentes novos no Storybook antes do merge, com o frame do Figma na aba Designs.
- Peça uma story para cada caso-limite que você desenhar.
- Mantenha uma revisão manual curta de acessibilidade para cada componente, ao lado da automática.
- Use os resultados dos testes visuais nas revisões de versão: eles mostram exatamente o que uma mudança de token tocou.
Checklist
Para saber mais
- Storybook docs (versão 10.6, conferida em novembro de 2026): Introduction · How to write stories · Autodocs · Accessibility tests · Visual tests · Design integrations
Livros, cursos e vídeos para ir mais fundo
Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.
Relacionadas
Estados e casos-limite · Componentes acessíveis · Documentação de componentes que as pessoas usam · Code Connect e a ponte entre design e código · Documentar o movimento num design system