Design System

Storybook & Documentação de UI

Storybook como ferramenta de desenvolvimento isolado, documentação viva e testes visuais.

Definição

Storybook é um workshop para desenvolver, documentar e testar componentes em isolamento. Cada Story representa um estado específico do componente. Funciona como: 1) Ambiente de desenvolvimento (sem precisar de back-end). 2) Documentação viva (auto-gerada de TypeScript). 3) Testes visuais (Chromatic, Percy). 4) Playground para design colaborar com dev.

Problema → Solução

Problema

Desenvolver um componente que depende de 5 providers, dados da API e estado da aplicação. Ou descobrir que o componente quebra num estado específico só em produção. Ou design não ter como verificar se a implementação bate com o Figma.

Solução

Storybook para desenvolver em isolamento com mock de dados. Stories para cada estado relevante (empty, loading, error, populated, edge cases). Chromatic para testes de regressão visual automáticos (detecta mudanças de pixel).

Dica de entrevista

Tip

Escreva stories enquanto desenvolve, não depois. Stories forçam você a pensar na API do componente antes de implementar. Se é difícil escrever uma story, provavelmente o componente tem acoplamento excessivo.

Código

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

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],           // gera documentação automática
  argTypes: {
    variant: {
      description: 'Estilo visual do botão',
      control: { type: 'select' },
    },
  },
}
export default meta
type Story = StoryObj<typeof Button>

export const Primary: Story = {
  args: { children: 'Salvar', variant: 'primary' },
}

export const Danger: Story = {
  args: { children: 'Deletar', variant: 'danger' },
}

export const Loading: Story = {
  args: { children: 'Salvando...', disabled: true },
}

// Teste de interação com play function
export const ClickTest: Story = {
  args: { children: 'Clicar' },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    await userEvent.click(canvas.getByRole('button'))
    await expect(canvas.getByRole('button')).toHaveFocus()
  },
}

Perguntas de entrevista

Q.Diferença entre Story e teste de componente?▾

A.Story é documentação e desenvolvimento visual — mostra como o componente parece em diferentes estados. Teste (Jest/RTL) verifica comportamento e lógica. São complementares: stories para visual, testes para funcional. Storybook pode executar testes de acessibilidade automáticos via addon.

Q.Como fazer testes de regressão visual?▾

A.Chromatic (do time do Storybook): faz screenshot de cada story em cada commit e compara com baseline. Detecta mudanças visuais não intencionais automaticamente. Alternativas: Percy, Playwright (screenshot testing), ou Happo. Essencial em DS para garantir que mudança de token não quebre componentes.

Q.Como organizar stories em projetos grandes?▾

A.Hierarquia: Componentes/Atoms/Button.stories.tsx. Usar tags para filtrar (is:new, status:deprecated). Stories por estado: Default, Hover (play function), Disabled, Loading, Error. Usar argTypes para documentar props com descrições e controles interativos.

63/122← →