Marcus Andrey Estudo
Read in English Biblioteca

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

Reservar travessia Reservar travessia Ver horários Ver horários Cancelar reserva Cancelar reserva
Controls
variant
size
disabled

args: { variant: 'primarysecondarydanger', size: 'defaultcompact', disabled: falsetrue }

Experimente: mude os controles e a story é desenhada de novo, como no painel Controls do Storybook. É uma imitação em CSS feita para esta página, não o Storybook, mas a ideia é a mesma: cada combinação que alguém desenhou no Figma fica a um clique no componente de verdade, no claro e no escuro (troque o tema do site). O botão primário mede 6,35 para 1 no modo claro (branco sobre #1F5FAE) e 5,32 para 1 no escuro (#14202B sobre #5B95DB).

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 design com 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)

  1. Escolha um componente e liste cada estado que um usuário pode ver: padrão, hover, foco, desativado, carregando, erro, texto longo, vazio.
  2. 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.
  3. 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

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

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar