Storybook: histórias, controlos e documentação
Escrever histórias para cada estado do componente, utilizar Controls para ajustar propriedades de forma interativa e gerar páginas de Docs a partir de JSDoc e argTypes.
Storybook: histórias, controlos e documentação é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.
O que é o Storybook?
Storybook é uma oficina para componentes de interface, isolada da sua aplicação. Você escreve “histórias” — exemplos de uso de cada componente em vários estados — e navega por elas em um servidor de desenvolvimento. É indispensável para sistemas de design.
Por que usar o Storybook?
1) Desenvolva componentes isoladamente, sem configurar o contexto de uma aplicação. 2) Revise visualmente todos os estados (carregando, erro e vazio). 3) Pessoas designers e gerentes de produto podem navegar pelo catálogo. 4) Gere documentação. 5) Automatize os testes de regressão visual.
Instalando o Storybook
Use o inicializador oficial — ele detecta seu framework e configura tudo.
npx storybook@latest init
# Adds:
# .storybook/ config
# src/stories/ example stories
# scripts: 'storybook' and 'build-storybook'
npm run storybook # opens http://localhost:6006Escrevendo uma história (CSF 3.0)
Formato de histórias de componentes 3: a exportação padrão = metadados; as exportações nomeadas = histórias.
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
title: 'Atoms/Button',
component: Button,
tags: ['autodocs']
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: { label: 'Save', variant: 'primary' }
};
export const Disabled: Story = {
args: { label: 'Save', variant: 'primary', disabled: true }
};Várias histórias por componente
Tenha uma história para cada estado importante: padrão, ao passar o cursor, carregando, erro, vazio e preenchido. As pessoas responsáveis pela revisão podem clicar entre elas e ver todas as variações de uma só vez.
export const Loading: Story = { args: { state: 'loading' } };
export const Error: Story = { args: { state: 'error', message: 'Network failed' } };
export const Empty: Story = { args: { items: [] } };
export const Populated: Story = { args: { items: mockItems } };Controles (tabela de argumentos)
O complemento Controls do Storybook transforma o objeto de argumentos em controles de formulário interativos. Ajuste os valores das propriedades ao vivo na interface para testar casos extremos.
const meta: Meta<typeof Button> = {
component: Button,
argTypes: {
variant: {
control: 'select',
options: ['primary', 'secondary', 'danger']
},
onClick: { action: 'clicked' }
}
};Complemento de ações
Use action() para registrar chamadas de manipuladores de eventos no painel de ações. É ótimo para testar funções de retorno sem configurar um estado real.
argTypes: {
onClick: { action: 'clicked' },
onChange: { action: 'changed' }
}Autodocs — documentação gerada automaticamente
Adicione tags: ['autodocs'] aos metadados; o Storybook gera uma página de documentação com a tabela de propriedades do componente, descrições e exemplos renderizáveis.
MDX para documentação detalhada
Escreva a documentação dos componentes em MDX — Markdown com JSX incorporado. Misture texto explicativo com exemplos de componentes ao vivo.
{/* Button.mdx */}
import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
<Meta of={ButtonStories} />
# Button
The primary action element.
## Variants
<Canvas of={ButtonStories.Primary} />
<Canvas of={ButtonStories.Secondary} />Decorators — envolvendo histórias com contexto
Envolva as histórias em provedores (Theme, Router, Redux) usando decorators.
export const decorators = [
(Story) => (
<ThemeProvider theme={lightTheme}>
<Story />
</ThemeProvider>
)
];Testes de regressão visual
O Chromatic (da equipe do Storybook) captura uma imagem de cada história em cada commit e compara com a linha de base. Ele detecta regressões visuais automaticamente.
Publicando o Storybook
npm run build-storybook produz um site estático em storybook-static/. Publique no Netlify, Vercel ou GitHub Pages — isso oferece às pessoas que não desenvolvem software um catálogo de componentes navegável.
Verificação rápida
O que adicionar tags: ['autodocs'] aos metadados de um componente no Storybook faz?
Recapitulação: Storybook
Oficina isolada para componentes de interface. CSF 3.0: exportação padrão = meta; exportações nomeadas = histórias. argTypes para os Controls. action() para registrar retornos de chamada. tags: ['autodocs'] para documentação gerada automaticamente. MDX para texto detalhado + JSX. Decorators injetam provedores. Chromatic para regressão visual. Compilação do Storybook para hospedagem estática.
Perguntas Frequentes
A aula “Storybook: histórias, controlos e documentação” é grátis?
Sim — o texto completo de “Storybook: histórias, controlos e documentação” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.
O que vou aprender em “Storybook: histórias, controlos e documentação”?
Escrever histórias para cada estado do componente, utilizar Controls para ajustar propriedades de forma interativa e gerar páginas de Docs a partir de JSDoc e argTypes. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Frontend Academy?
Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Storybook: histórias, controlos e documentação”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Frontend Academy?
Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Storybook: histórias, controlos e documentação
- Tokens de design com Style Dictionary
- Versionamento e publicação no npm
- Consumo de um sistema de design