Framework · Design systems · 4 min de leitura
Checklist da API de um componente
Seis perguntas para responder em palavras antes de desenhar um componente (a função, as partes, o que muda, o que nunca muda, os estados e o que ele não é), e três testes que transformam cada resposta em variante, propriedade, slot ou token.
O que ele faz pela pessoa, numa frase.
"Inicia uma ação"Cada parte com nome, obrigatória ou não, e o que acontece quando é longa.
Rota: obrigatória, quebra linhaCada diferença real vira uma prop com nome do significado.
variant="danger", não vermelhoRaio, fonte e anel de foco ficam nos tokens, não em props.
Nada de "só põe color"Os estados que ele precisa ter, listados antes de desenhar.
Veja a matriz de estadosO que ele não é, para não acabar fazendo o trabalho de outro componente.
"Não é um link"Variante se muda várias partes · Propriedade se muda uma camada · Slot se não dá para prever
Use quando
- Um time pede um componente novo, ou uma opção nova num componente que já existe.
- O Figma e o código chamam a mesma coisa por nomes diferentes, e todo handoff começa com "qual é esse?".
- Um componente ganhou tantas opções que ninguém sabe quais combinações funcionam.
Como usar
- Escreva a função numa frase. Diga o que ele faz pela pessoa que usa o produto, e para que ele não serve. Resultado: "Inicia uma ação. Não serve para navegar: para isso existe o link."
- Dê nome a cada parte. Para cada parte, responda quatro perguntas: como se chama, é obrigatória, de onde vem (texto, token, outro componente) e o que acontece quando é longa. Resultado: uma tabela de anatomia, uma linha por parte.
- Liste o que muda entre um uso e outro. Cada diferença real vira uma prop: o rótulo, a importância, o tamanho. O nome vem do significado (
variant="danger"), nunca da aparência (color="red"). Resultado: uma lista de props, cada uma com tipo, valores e padrão. - Escolha o tipo de cada prop. Uma mudança que mexe em várias partes de uma vez é variante. Uma parte que aparece, some, troca ou muda de texto é propriedade. Conteúdo que você não consegue prever vai num slot, com limites. Resultado: o tipo de propriedade do Figma ao lado de cada prop.
- Liste o que nunca muda, e o que ele não é. Raio, fonte e anel de foco ficam nos tokens, não em props. Hover e foco são do navegador. Escreva a linha "não é link, não é toggle". Resultado: duas listas curtas que impedem os overrides.
- Confira os nomes dos dois lados. Mesmos nomes de propriedade, mesmos valores em minúsculas e a mesma ordem no Figma, no código e na documentação. Resultado: um nome por coisa, pronto para a página do componente.
Exemplo
O time do Harbour recebe um pedido de "botão vermelho" para cancelar uma reserva. Antes de abrir o Figma, eles passam pelo checklist.
| Pergunta | Resposta |
|---|---|
| Função | Inicia uma ação. Não serve para navegar, não é toggle |
| Partes | Rótulo (obrigatório, quebra linha), ícone no início (opcional, um Icon aninhado), anel de foco (dos tokens) |
| O que muda | variant: primary, secondary, ghost, danger · size: default, compact · iconStart: booleana mais um instance swap |
| Tipo | variant e size são variantes; o ícone é booleana, o rótulo é propriedade de texto |
| Nunca muda | Raio, fonte, anel de foco, cores de hover e de pressionado |
| Não é | Um link com cara de botão |
"Vermelho" vira variant="danger", um significado. Quando a marca econômica Skiff usar laranja para perigo, nada muda na API. O ícone continua booleano, então o conjunto tem 4 × 2 = 8 frames, e não 16.
Cuidado com
- Props com nome de aparência.
blue,big,withBorderquebram assim que muda o tema ou a marca. Dê o nome do significado. - Uma prop para cada pedido isolado. O pedido de uma tela não é motivo. Espere um segundo time precisar, ou resolva com um slot.
- Sobrescrever tokens por props. "Só põe
color" torna a consistência opcional. Se os times precisam de uma cor nova, a conversa é sobre tokens. - Uma booleana que muda três coisas. É uma variante fingindo ser um interruptor. Use o teste da camada: se dois valores diferem em uma camada só, é propriedade, não variante.
Modelo
Preencha antes de abrir o Figma e cole no topo da página do componente.
Componente: ...
Função: ... (uma frase)
Não serve para: ... (use ... no lugar)
Partes (nome / obrigatória? / vem de / quando é longa):
- ... / sim / texto, token ... / quebra linha
- ... / não / componente ... / ...
Props (nome / tipo / valores / padrão / tipo de propriedade no Figma):
- variant / enum / ..., ..., ... / ... / variante
- size / enum / ..., ... / ... / variante
- ... / boolean / true, false / false / booleana
- ... / slot / no máximo ... itens de ... / vazio / slot
Nunca muda (tokens, navegador): ...
Estados que ele precisa ter: ...
Times que pediram cada prop: ...
- Design SystemsAlla KholmatovaLivro · 2017 (Amazon)
- Design That ScalesDan MallLivro · 2023 (Amazon)
- Explore component propertiesFigma Help (site externo)
- Design system components, recipes, and snowflakesBrad Frost (site externo)
- ButtonCarbon (site externo)
Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.