Atomic Design e Storybook — Construindo Componentes que Escalam

Atomic Design, proposta por Brad Frost em 2013, oferece uma taxonomia para organizar componentes de UI em cinco níveis de abstração: átomos, moléculas, organismos, templates e páginas. Mais de uma década depois, a metodologia permanece relevante — não como prescrição rígida, mas como framework mental para tomar decisões de composição que se mantêm coerentes à medida que o design system cresce. Combinado com Storybook como ambiente de desenvolvimento e documentação, Atomic Design cria uma base técnica que permite que times de design e desenvolvimento trabalhem de forma mais independente e com maior confiança. Este artigo examina como aplicar a metodologia na prática e como extrair o máximo do Storybook como ferramenta central do design system.

Atomic Design na prática: além da taxonomia

A taxonomia de Atomic Design é um ponto de partida, não uma lei. Times que tentam aplicá-la rigidamente frequentemente travam em debates sobre se um componente específico é uma "molécula" ou um "organismo". O valor real da metodologia não está em classificar corretamente cada componente — está no princípio subjacente: componentes são compostos de partes menores, e as partes menores devem ser independentes o suficiente para funcionar em contextos diferentes.

Na prática, a estrutura mais funcional que encontramos em projetos complexos usa três categorias principais:

Primitivos (equivalente a átomos): Elementos sem estado e sem lógica de negócio. Button, Input, Icon, Badge, Avatar. Estilizados apenas com design tokens, sem layout ou posicionamento próprio.

Compostos (equivalente a moléculas e organismos simples): Combinações de primitivos com lógica de apresentação. FormField (Label + Input + ErrorMessage), Card (imagem + título + descrição + ação), NavigationItem (ícone + label + indicador de estado ativo).

Seções (equivalente a organismos complexos): Blocos de UI que representam uma área funcional completa. Header, ProductGrid, CheckoutSummary. Podem conter lógica de negócio e conexões com estado global.

Templates e páginas existem no nível da aplicação, não do design system — eles são responsabilidade do produto, não da biblioteca de componentes.

Storybook: do catálogo à ferramenta de desenvolvimento

Storybook começou como uma ferramenta de documentação de componentes mas evoluiu para um ambiente de desenvolvimento completo. Cada "story" é um estado renderizável de um componente — e o conjunto de stories de um componente é tanto a documentação quanto a especificação de comportamento.

Uma story bem escrita documenta: o estado padrão do componente, todas as variantes relevantes, estados de edge case (texto muito longo, lista vazia, estado de loading, estado de erro), e comportamento em diferentes tamanhos de viewport.

```typescript // button.stories.tsx import type { Meta, StoryObj } from '@storybook/react'; import { Button } from './Button';

const meta: Meta = { component: Button, argTypes: { variant: { control: 'select', options: ['primary', 'secondary', 'ghost'] }, size: { control: 'select', options: ['sm', 'md', 'lg'] }, disabled: { control: 'boolean' }, }, }; export default meta;

type Story = StoryObj;

export const Primary: Story = { args: { variant: 'primary', children: 'Confirmar' } }; export const Loading: Story = { args: { variant: 'primary', loading: true, children: 'Salvando...' } }; export const LongText: Story = { args: { children: 'Um label de botão muito mais longo do que o esperado para testar overflow' } }; ```

Integrando design tokens no Storybook

O Storybook com o addon `@storybook/addon-themes` ou configuração de globals permite alternar entre temas (light/dark, brand themes) diretamente na interface. Isso torna o Storybook o ambiente canônico para verificar se os componentes respondem corretamente às variações de token.

Para conectar os tokens ao Storybook, importe o CSS ou JS com os tokens na configuração do Storybook (`preview.ts`). Qualquer mudança nos tokens se reflete automaticamente em todos os componentes documentados — sem necessidade de atualizar screenshots ou documentação manual.

Testes no Storybook

O ecossistema de addons do Storybook transforma stories em casos de teste:

Accessibility tests (axe-core): O addon `@storybook/addon-a11y` executa axe-core em cada story e exibe violações de acessibilidade diretamente no painel. Cada componente tem uma tab "Accessibility" com o resultado da auditoria automática. Isso transforma acessibilidade em verificação contínua, não em auditoria periódica.

Visual regression tests (Chromatic): Chromatic (da equipe do Storybook) tira screenshots de cada story a cada commit e compara com a baseline. Mudanças visuais inesperadas são sinalizadas para revisão. Isso é especialmente valioso quando mudanças em tokens ou componentes primitivos podem ter efeitos colaterais em componentes compostos.

Interaction tests: O addon `@storybook/addon-interactions` permite escrever testes de interação que executam dentro do Storybook usando Testing Library. Um teste de interação pode simular um clique, verificar que um modal abre, digitar em um input e verificar validação — tudo no ambiente isolado da story.

Documentação automática com autodocs

O Storybook com `tags: ['autodocs']` na meta da story gera automaticamente uma página de documentação com a tabela de props, os controles interativos e as stories. Isso garante que a documentação seja sempre consistente com o código real — sem documentação que diverge da implementação.

Para componentes mais complexos, comentários JSDoc no TypeScript são extraídos automaticamente e aparecem na documentação gerada:

```typescript interface ButtonProps { / Variante visual do botão */ variant: 'primary' | 'secondary' | 'ghost'; / Desabilita o botão e aplica estilo visual de disabled */ disabled?: boolean; / Exibe spinner de loading e bloqueia interação */ loading?: boolean; } ```

O Storybook como contrato entre design e desenvolvimento

Um dos maiores valores do Storybook é criar um artefato compartilhado que representa o estado real dos componentes — não o que está no Figma, não o que está na documentação estática, mas o que está no código rodando. Quando design e desenvolvimento usam o Storybook como referência comum, discussões sobre "isso está certo?" passam a ter uma fonte objetiva de resposta.

Esse contrato só funciona se o Storybook for mantido atualizado. Stories desatualizadas são piores do que ausência de stories — criam falsa confiança. Incluir atualização de stories na definition of done de cada mudança de componente é a prática que mantém o Storybook como fonte viva de verdade.