Design systems · Passo 3 · 8 min de leitura
Anatomia e API de um componente
Um componente é uma promessa: estas partes, estas opções, estas regras, iguais no Figma e no código. Como desmontar um componente em partes com nome, como escrever a API antes de desenhar, e por que a tabela de props é a página mais útil do sistema.
Um componente é uma promessa, e a anatomia e a API são as letras miúdas. Quando uma designer arrasta o Ticket card do Harbour para uma tela e um desenvolvedor importa o mesmo componente no código, os dois esperam as mesmas partes, as mesmas opções e os mesmos limites. Isso só funciona se alguém escreveu tudo: como as partes se chamam, quais são obrigatórias, o que dá para mudar e o que não dá. Faça isso antes de desenhar as variantes, e metade das discussões dos próximos seis meses nem acontece.
O que você vai conseguir fazer depois de ler:
- Desmontar um componente em partes com nome e dizer quais são obrigatórias
- Escrever a API de um componente (props, tipos, padrões) antes de desenhá-lo
- Ligar cada prop à sua propriedade no Figma, para design e código baterem
- Diferenciar uma API boa de uma que vai sair do controle
1. O que é um componente, num sistema
Em O que é um design system você viu os componentes como uma das quatro partes de um sistema. Aqui vai uma definição mais precisa, de Brad Frost: componentes de design system são "compartilhados, independentes de conteúdo e de contexto, feitos para o máximo de reúso" (Frost, Design system components, recipes, and snowflakes, 2021). Um Button não sabe que está na tela de reserva; um Card não sabe que guarda um bilhete.
Todo componente tem duas faces:
- Anatomia: as partes de que ele é feito, com nomes. O que você vê.
- API: o que quem usa pode mudar, e como. O que você pode mexer.
Os sistemas públicos colocam as duas em cada página de componente. As diretrizes de botão do IBM Carbon abrem a seção de formatação com a anatomia do botão (Carbon, Button); o GOV.UK Design System dá a cada componente "When to use this component" (quando usar), "When not to use" (quando não usar) e "How it works" (como funciona) (GOV.UK, Button). O Harbour faz o mesmo.
2. Anatomia: dê nome a cada parte
2Kestrel Bay → Ilha de Mara
3No horário409:40 · 50 min · sex., 4 de dez.
- 1ContêinerTokens de superfície, borda e raio do card. Obrigatório.
- 2RotaTexto, o título do card. Obrigatório. Quebra a linha, nunca é cortado.
- 3Selo de statusUm componente Badge aninhado. Opcional: no horário, atrasado, cancelado.
- 4Linha de partidaHora, duração e data, formatadas pelo sistema, não digitadas à mão.
- 5DetalhesPares de rótulo e valor. Opcional; de zero a quatro.
- 6AçõesUm ou dois Buttons aninhados, no tamanho compacto. O primeiro é o primário.
O Ticket card é o componente do Harbour que as pessoas mais veem no app de reservas. Desmontado, ele tem seis partes. Para cada uma, a anatomia responde quatro perguntas:
| Pergunta | Ticket card, parte "Rota" |
|---|---|
| Como se chama? | Rota. A mesma palavra no Figma, no código e na documentação |
| É obrigatória? | Sim. Um bilhete sem rota é um bug |
| De onde vem? | Texto, font.size.300, seminegrito; cor color.text.default |
| O que acontece quando é longa? | Quebra a linha. Nunca é cortada, porque "Porto Velho da Ilha de Ma…" é outro porto |
Duas das partes são outros componentes: o status é um Badge e as ações são Buttons. Isso é normal, e a anatomia deve dizer, porque significa que o card herda as regras deles. Se o anel de foco do Button mudar, o do card muda junto.
Os nomes importam mais do que parece. Se a designer chama de "título", o desenvolvedor de heading e a documentação de "rota", três pessoas vão gastar uma reunião para descobrir que falam da mesma coisa. Escolha um, na língua do produto (um bilhete de ferry tem rota), e use em todo lugar.
3. API: o que dá para mudar
A API é o contrato com quem usa o componente. No código, são as props; no Figma, as propriedades do componente. Esta é a do Button, preenchida:
| Prop | Tipo | Padrão | No Figma | Regra |
|---|---|---|---|---|
children | string | nenhum, obrigatório | Propriedade de texto Label | Um verbo, só a primeira letra maiúscula, duas ou três palavras: "Reservar travessia" |
variant | "primary" | "secondary" | "ghost" | "danger" | "primary" | Propriedade de variante Variant | Um primário por tela. Danger só para ações que não dá para desfazer |
size | "default" | "compact" | "default" | Propriedade de variante Size | Compacto é para as tabelas densas do console da equipe; ainda com 32 px de altura |
iconStart | IconName | nenhum | Booleana Show icon + troca de instância Icon | Decorativo: quem carrega o sentido é o rótulo |
loading | boolean | false | Propriedade de variante State = Loading | Mantém o foco e a largura; ignora os cliques seguintes |
disabled | boolean | false | Propriedade de variante State = Disabled | Último recurso. Diga o motivo ao lado |
type | "button" | "submit" | "button" | nenhum (só no código) | Só a ação principal do formulário é submit |
onClick | () => void | nenhum | Interação do protótipo | Nunca num div: o componente gera um <button> de verdade |
Leia como uma lista de decisões tomadas uma vez:
- O nome de cada prop diz o que ela significa, não como ela parece.
variant="danger", nãocolor="red". Quando a Skiff, a marca econômica do Passo 7, usar laranja para perigo, a API não muda. - O tipo limita as escolhas.
variantaceita quatro valores, não qualquer texto. O que não está na lista é uma conversa com o time do sistema, não um ajuste escondido. - O padrão é o caso mais comum. A maioria dos botões é primária e de tamanho padrão, então quem escreve
<Button>Reservar travessia</Button>já recebe o certo. - Toda prop tem uma gêmea no Figma, com o mesmo nome. O Figma tem cinco tipos de propriedade de componente: booleana, troca de instância, texto, variante e slot (Figma Help, Explore component properties). A próxima lição é sobre como escolher entre eles.
- Algumas coisas não são props. Hover e foco são do navegador; a fonte do rótulo é dos tokens. Se uma prop deixa mudar isso, a consistência vira opcional.
4. Escreva a API antes de desenhar
Dá vontade de desenhar o componente primeiro e deixar a API sair do frame. Faça ao contrário. Antes de abrir o Figma, escreva em palavras simples:
- A função. "Dispara uma ação. Não serve para navegar: para isso existe o link."
- As partes, obrigatórias e opcionais.
- O que muda de um uso para outro: o rótulo, a importância, o tamanho. Cada um vira uma prop.
- O que nunca muda: o raio, a fonte, o anel de foco. Isso fica nos tokens.
- Os estados que ele precisa ter (veja Estados e casos-limite).
- O que ele não é. "Não é um link com cara de botão. Não é um botão de alternância."
Depois compare com dois sistemas públicos. O Material 3 tem cinco tipos comuns de botão: elevated, filled, filled tonal, outlined e text (Material Web, Button). O Carbon tem primary, secondary, tertiary, ghost e danger (Carbon, Button). O Harbour tem quatro. Menos não é problema, desde que você saiba dizer para que serve cada um.
Uma API pequena é uma qualidade. Cada prop nova é mais uma coisa para desenhar, construir, testar, documentar e manter para sempre. Acrescente uma prop quando dois ou mais times precisarem dela, não quando uma tela talvez precise.
5. Erros comuns
- Desenhar o componente primeiro e inventar a API no handoff (veja Handoff para desenvolvedores).
- Dar nome às props pela aparência:
blue,big,withBorder. - Nomes diferentes para a mesma parte no Figma, no código e na documentação.
- Uma prop para cada pedido avulso, até ninguém saber quais combinações funcionam.
- Deixar as pessoas sobrescreverem tokens por props ("é só acrescentar
color"). - Esquecer a linha do "o que ele não é", e o Button acaba fazendo o trabalho de um link.
6. Vocabulário
| Termo | Significado |
|---|---|
| Anatomia | As partes de um componente, com nome, e quais são obrigatórias |
| API | O que quem usa o componente pode mudar: props no código, propriedades no Figma |
| Prop | Uma entrada de um componente em código, com nome, tipo e valor padrão |
| Propriedade de componente | A versão do Figma de uma prop: booleana, troca de instância, texto, variante ou slot |
| Padrão (default) | O valor de uma prop quando ninguém define; o caso mais comum |
| Componente aninhado | Um componente dentro de outro, como o Button dentro do Ticket card |
7. Experimente (sem ferramentas)
- Escolha um componente que você usa todo dia, como um campo de busca ou um card de produto.
- Desenhe e numere as partes. Dê a cada uma um nome que um desenvolvedor também usaria.
- Escreva a API como uma lista: prop, valores permitidos, padrão. Pare em seis props.
Perguntas para refletir: Quais das suas props descrevem um significado, e quais descrevem uma aparência? Que parte você poderia tirar e continuar com o mesmo componente?
8. Se você já pratica
- Coloque a tabela de props no topo da página de documentação de cada componente, e gere a tabela a partir do código quando der, para ela não se desatualizar.
- Revise props novas como componentes novos: quem precisa, em quantas telas e quanto custa manter.
- Mantenha, para cada componente, uma lista curta de "não é este componente", com o que usar no lugar.
Checklist
Para saber mais
- Brad Frost, Design system components, recipes, and snowflakes (2021)
- Figma Help, Explore component properties
- Páginas de componente: Carbon, Button · GOV.UK, Button · Material Web, Button
Livros, cursos e vídeos para ir mais fundo
- Design SystemsAlla KholmatovaLivro · Smashing Magazine, 2017 (Amazon)
- Design That ScalesDan MallLivro · Rosenfeld Media, 2023 (Amazon)
Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.
Relacionadas
Tokens do Figma ao código · Variantes, propriedades e slots · Estados e casos-limite · O que é um design system · Handoff para desenvolvedores · Documentação de componentes que as pessoas usam · Code Connect e a ponte entre design e código · Checklist da API de um componente