Marcus Andrey Estudo
Read in English Biblioteca

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 montado como um brinquedo: uma base comprida com três encaixes, um redondo, um comprido e um quadradinho, e em cada um a peça que cabe nele. Aponte para um encaixe: a peça sai e mostra o encaixe vazio embaixo, enquanto as peças do lado sobem um pouco. Este passo é isso: um componente é uma moldura com slots nomeados, e o que entra em cada slot precisa caber no formato dele. Este passo tem cinco lições: anatomia e API de um componente, variantes, propriedades e slots, estados e casos de borda, composição em vez de configuração, e componentes acessíveis.Ilustração: Marcus Andrey, desenhada com Hairline (MIT, Lucas Marques).

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

Kestrel Bay → Ilha de Mara

No horário

09:40 · 50 min · sex., 4 de dez.

Passageiros
2 adultos
Veículo
Nenhum
  1. ContêinerTokens de superfície, borda e raio do card. Obrigatório.
  2. RotaTexto, o título do card. Obrigatório. Quebra a linha, nunca é cortado.
  3. Selo de statusUm componente Badge aninhado. Opcional: no horário, atrasado, cancelado.
  4. Linha de partidaHora, duração e data, formatadas pelo sistema, não digitadas à mão.
  5. DetalhesPares de rótulo e valor. Opcional; de zero a quatro.
  6. AçõesUm ou dois Buttons aninhados, no tamanho compacto. O primeiro é o primário.
O Ticket card do Harbour, desmontado. Cada parte numerada tem um nome, uma regra que diz se é obrigatória e o componente ou token de onde vem. O card segue o modo claro ou escuro do site, como os modos do Harbour fariam.

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:

PropTipoPadrãoNo FigmaRegra
childrenstringnenhum, obrigatórioPropriedade de texto LabelUm verbo, só a primeira letra maiúscula, duas ou três palavras: "Reservar travessia"
variant"primary" | "secondary" | "ghost" | "danger""primary"Propriedade de variante VariantUm primário por tela. Danger só para ações que não dá para desfazer
size"default" | "compact""default"Propriedade de variante SizeCompacto é para as tabelas densas do console da equipe; ainda com 32 px de altura
iconStartIconNamenenhumBooleana Show icon + troca de instância IconDecorativo: quem carrega o sentido é o rótulo
loadingbooleanfalsePropriedade de variante State = LoadingMantém o foco e a largura; ignora os cliques seguintes
disabledbooleanfalsePropriedade 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() => voidnenhumInteração do protótipoNunca num div: o componente gera um <button> de verdade
A API do Button do Harbour, preenchida. Cada linha é uma decisão que alguém tomou uma vez, para ninguém precisar tomar de novo: o nome, os valores permitidos, o padrão, como aparece no Figma e a regra de uso. Hover e foco não são props: quem define é o navegador.

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ão color="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. variant aceita 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:

  1. A função. "Dispara uma ação. Não serve para navegar: para isso existe o link."
  2. As partes, obrigatórias e opcionais.
  3. O que muda de um uso para outro: o rótulo, a importância, o tamanho. Cada um vira uma prop.
  4. O que nunca muda: o raio, a fonte, o anel de foco. Isso fica nos tokens.
  5. Os estados que ele precisa ter (veja Estados e casos-limite).
  6. 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)

  1. Escolha um componente que você usa todo dia, como um campo de busca ou um card de produto.
  2. Desenhe e numere as partes. Dê a cada uma um nome que um desenvolvedor também usaria.
  3. 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

Livros, cursos e vídeos para ir mais fundo

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

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar