Como estruturar um Storybook que sirva de contrato

O Storybook não é uma galeria

Em 2024, de quase 17 milhões de sites analisados pelo Web Almanac, só 29% dos sites móveis tinham texto com contraste suficiente. Sete em cada dez não se leem bem num celular, e quase nenhum fez isso de propósito: ninguém verificou. Muitas equipes instalam o Storybook, escrevem vinte histórias e o abandonam em três meses. O problema não é a ferramenta: ela foi usada como vitrine e não como o que pode ser, o contrato visual e de comportamento entre design, desenvolvimento e QA. Um contrato diz o que existe, como se usa, em que estados pode estar e o que não vale. Não substitui as decisões de design nem o contrato das APIs; é a evidência mais útil de como a interface se comporta.

1. Uma hierarquia, com dependências que fluem para baixo

Usamos o Atomic Design como vocabulário de composição —átomos, moléculas, organismos— e o estendemos quando isso ajuda a governar o produto:

Fundamentos → Átomos → Moléculas → Organismos → Seções → Páginas

• Fundamentos: cores, tipografia, espaçamento, padrões visuais. Não são componentes: são as regras.
• Átomos: botão, campo, ícone, selo. Não conhecem regras do negócio, ainda que tenham comportamento próprio.
• Moléculas: um campo com o próprio rótulo e o próprio erro; um cartão.
• Organismos: cabeçalho, rodapé, um formulário completo.
• Seções: blocos de conteúdo configuráveis por propriedades, em vez de copiados página a página.
• Páginas: orquestram dados, rotas e contexto; a lógica de apresentação reutilizável vive embaixo.

É uma convenção de arquitetura, não uma lei universal. A regra que a torna útil é a direção: uma camada base nunca importa uma camada de produto. Isso não impede que uma mudança de token ou de componente compartilhado afete as páginas —deve afetá-las—, mas torna o impacto rastreável e obriga quem o consome a verificar.

Alguém sabe hoje quais telas mudam se amanhã mudar a cor principal da marca?

2. Os fundamentos, como texto que se lê

Antes do primeiro botão, documente os fundamentos como páginas narrativas dentro do próprio Storybook: a paleta e quando se usa cada cor, a tipografia e a hierarquia, os padrões visuais. E que vivam como tokens: a cor não se escreve no componente, é tomada do token. Assim, mudar a marca é mudar um token, e a regressão visual mostra o que mais mudou. (O formato padrão de tokens ainda é um rascunho, e o próprio texto do padrão pede que não seja implementado ainda: os tokens se definem no próprio sistema de design e se exportam quando o padrão se estabilizar.)

3. Cada história responde quatro perguntas

1. O que é e quando se usa (e quando não).
2. Variantes: tamanhos, tons, com ícone ou sem ele.
3. Estados: carregando, vazio, com erro, desabilitado, enviando, e os casos-limite —textos longos, dados incompletos, respostas lentas—. É aí que a experiência se fratura.
4. Acessibilidade: como um leitor de tela a anuncia, o que acontece com o teclado e o foco, o que acontece se o usuário pediu menos movimento.

// Ilustrativo (Storybook 9, CSF3). Pressupõe: type Story = StoryObj<typeof meta>
// e que expect é importado do caminho de utilitários de teste da versão em uso.
export const ConError: Story = {
  args: { etiqueta: "Correo", error: "Escriba un correo válido" },
  play: async ({ canvas }) => {
    const campo = canvas.getByLabelText("Correo");
    await expect(campo).toHaveAttribute("aria-invalid", "true");
    await expect(canvas.getByRole("alert")).toBeVisible();
  },
};

A história fixa um estado de erro e verifica a semântica: que o campo é marcado como inválido e que a mensagem é exposta como alerta. Isso a aproxima de um contrato. Para os fluxos críticos, além disso, valida-se à mão com teclado e com leitor de tela: o automático não cobre tudo.

4. Três tipos de revisão, não um

• Testes de interação: que os estados e o comportamento sejam os esperados, como no exemplo.
• Revisão automática de acessibilidade em cada história: contraste, papéis, nomes acessíveis. Atenção aos limites dessas verificações: em média, os testes automáticos encontram 57% dos problemas de acessibilidade (Deque, sobre mais de 13.000 páginas), e a regra do tamanho mínimo dos alvos de toque do WCAG 2.2 vem desligada de fábrica na ferramenta mais usada. É preciso ligá-la à mão; o resto é coberto pela revisão com teclado e leitor de tela.
• Regressão visual: a que detecta que uma mudança de token mexeu em algo em vinte telas que ninguém abriu.

Juntas, são o que transforma um catálogo em contrato.

5. O contexto, a partir da barra de ferramentas

Se o produto usa vários idiomas ou tema claro e escuro, exponha-os como controles globais do Storybook, conectados por decoradores aos mesmos provedores de contexto da aplicação real. Use-os para explorar as combinações de risco —o botão que não cabe em alemão, o texto que desaparece no escuro— e defina quais combinações são sempre testadas.

6. Publica-se sozinho

Um Storybook que alguém precisa lembrar de publicar já está desatualizado. Ele é publicado automaticamente ao integrar mudanças aprovadas, como referência que design, QA e o cliente podem abrir, com o acesso que a sensibilidade do produto exigir. Essa referência é a que se revisa, não uma captura de tela num chat.

7. Quando algo sobe de nível

Os primitivos da marca —botão, campo, tipografia— nascem como parte do sistema desde o primeiro dia. Para o resto:

• A repetição é um sinal, não um limite. Um padrão se consolida quando a intenção e as variantes já são estáveis; abstrair antes costuma custar mais do que uma duplicata visível. Na prática, isso raramente acontece antes do terceiro uso.
• Compartilhar entre projetos pede governança. Quando um segundo produto precisa dos mesmos componentes, o sistema vira um pacote com dono claro, versões e um caminho de adoção; aí o Storybook costuma se tornar a referência mais útil, sem substituir a documentação de decisões.

O que ainda nos falta, dito em voz alta

Revisamos acessibilidade de forma automática em cada história, mas hoje a revisão avisa e não bloqueia. O passo que muitas equipes adiam —e que exigimos como o próximo— é que uma falha de acessibilidade ou um estado quebrado interrompa a publicação, como um teste vermelho. Um contrato que não pode interromper uma mudança é só uma sugestão.

Próximo da série: Paradigmas do frontend moderno, sem fumaça · O que um frontend profissional precisa ter antes de ir para a produção.