Marcus Andrey Estudo
Read in English Biblioteca

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.

1Função

O que ele faz pela pessoa, numa frase.

"Inicia uma ação"
2Partes

Cada parte com nome, obrigatória ou não, e o que acontece quando é longa.

Rota: obrigatória, quebra linha
3O que muda

Cada diferença real vira uma prop com nome do significado.

variant="danger", não vermelho
4Nunca muda

Raio, fonte e anel de foco ficam nos tokens, não em props.

Nada de "só põe color"
5Estados

Os estados que ele precisa ter, listados antes de desenhar.

Veja a matriz de estados
6O que não é

O 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

Seis perguntas para responder em palavras antes de desenhar um componente, e a regra que transforma cada mudança em variante, propriedade ou slot.

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

  1. 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."
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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, withBorder quebram 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: ...
Fonte
Prática padrão de design systems, como descrita nas lições do curso. Propriedades de componente (variante, booleana, texto, instance swap, slot): Figma Help. Componentes, receitas e snowflakes: Brad Frost (2021)

Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.

Salvo só neste dispositivo.

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