Communitygithub.com

design-system

Use ao iniciar um sistema de design, guia de estilo ou conjunto de tokens, adicionar ou alterar um componente ou token, padronizar telas que divergiram ou auditar um guia em busca de cores soltas, peças únicas, estados faltantes ou telas que não correspondem a ele.

O que é design-system?

Esta skill orienta a criação, modificação ou auditoria de um sistema de design de forma estruturada, priorizando a consistência e a escalabilidade. Ela é útil para evitar a proliferação de valores soltos (como hexadecimais) e peças únicas que causam divergência visual e técnica entre telas e componentes. A skill suporta ferramentas como Paper, Figma ou HTML, adaptando-se por meio de adaptadores de referência. O processo é dividido em camadas: começa com fundações (tokens de cor, tipografia, espaçamento), depois regras de interação, e só então componentes. Cada etapa inclui uma parada para aprovação antes de prosseguir, evitando retrabalho. Uma auditoria gera um relatório classificado por severidade, mas nenhuma alteração é feita sem aprovação explícita, garantindo que o dono do projeto concorde com as correções propostas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/design-skills/tree/HEAD/skills/design-system

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Sistema de design

Visão geral

Um sistema de design é o lugar onde uma decisão é tomada uma vez e depois reutilizada em todo lugar. Cada cor é um token, cada peça interativa mostra todos os seus estados e cada alteração atinge todas as telas que usam a peça. Construa em camadas, fundações primeiro, e pare para aprovação em cada camada. Uma auditoria relata e nunca corrige por conta própria.

Quando usar

  • "Iniciar um guia de estilo / sistema de design / tokens para …"
  • Adicionar um componente, variante ou token, ou alterar um existente.
  • "Tornar estas telas consistentes", "padronizar", "auditar o guia", ou valores hexadecimais soltos e peças únicas nas telas.

Quando NÃO usar

  • Uma pergunta sobre um único valor ("qual é nossa cor primária?"): responda-a.
  • Uma pequena edição que a pessoa descreveu exatamente (um valor, um rótulo, um tamanho), mesmo em uma peça compartilhada: altere-a uma vez onde está definida e diga quais telas afeta. Sem matriz de estados, sem parada.

Antes de começar

  1. Leia DESIGN.md na raiz do projeto, se existir: ele é o resumo de design do projeto.
  2. Descubra o que existe: tokens, o guia, os componentes, as telas e o código. Um guia existente vence na aparência. Siga suas regras mesmo onde elas diferirem dos padrões abaixo e mencione a diferença uma vez.
  3. Escolha o adaptador da sua ferramenta em references/adapters/ (paper.md, figma.md, html.md). Se nenhum adaptador corresponder à sua ferramenta, faça os mesmos verbos em sua ferramenta e diga quais você mapeou manualmente. Sem ferramenta de design, construa em HTML (html.md). Se tudo o que você tem é uma imagem, diga que os valores lidos dela são estimativas.
  4. Decida o modo: criar, adicionar ou alterar ou auditar.

Etapas · criar

  1. Rascunho das fundações:

    • papéis de cor (papéis de token);
    • escala tipográfica;
    • espaçamento;
    • raio;
    • sombras (no máximo duas);
    • larguras de layout;
    • durações de movimento;
    • uma seção curta "como escrevemos".

    Nomeie tokens por papel (texto-suave, borda-hover, perigo-fundo), nunca apenas por valor (cinza-500).

  2. Regras de interação, uma vez: para peças com borda, peças sem borda e a ação primária, escreva como ficam os estados hover, pressionado, foco (apenas teclado), desabilitado, carregando e selecionado. Os componentes seguem essas regras em vez de cada um inventar as suas.

  3. Pare e mostre à pessoa as fundações e as regras de interação. Não construa componentes ainda.

  4. Componentes um de cada vez, na ordem que as primeiras telas precisam deles. Cada um recebe uma seção do guia com a anatomia do componente: uma legenda com a regra e o porquê, exemplos e uma matriz de estados de variantes × estados. Adicione cada um ao índice de componentes.

Etapas · adicionar ou alterar uma peça

  1. Verifique se um componente existente mais uma variante cobre a necessidade. Prefira reutilização a uma peça única.
  2. Desenhe com a anatomia, incluindo a matriz de estados completa. Uma nova cor, tamanho ou ícone se torna um token ou uma entrada do conjunto de ícones agora, não depois.
  3. Liste cada tela e local no código que usa a peça.
  4. Pare e mostre à pessoa a alteração e essa lista.
  5. Após aprovação, propague:
    • atualize cada tela na lista;
    • atualize o código, se houver;
    • atualize o índice de componentes;
    • relate o que mudou e onde.

Etapas · auditar

  1. Execute a lista de verificação de auditoria sobre o guia, as telas e o código, se houver.
  2. Escreva o relatório: descobertas classificadas por gravidade, cada uma com onde está, por que importa e a correção proposta.
  3. Pare e mostre à pessoa o relatório. Não altere nenhum arquivo até que eles digam quais correções fazer. Salvar cópias dos originais não torna aceitável editá-los.

Regras

Rígidas (qualquer projeto):

RegraPor quê
Cada cor é um token; sem valores hexadecimais soltos em telas ou códigoValores soltos se desviam para quase duplicatas que ninguém pode alterar de uma vez
Um conjunto de íconesConjuntos mistos parecem produtos mistos
Design e código mudam juntos, design primeiroCaso contrário, o guia para de ser a verdade em uma semana
Cada peça interativa tem uma matriz de estadosEstados desenhados ad hoc em telas nunca concordam
Uma alteração em uma peça compartilhada é listada com as telas que afeta antes de ser propagadaCaso contrário, uma "pequena" alteração redesenha silenciosamente vinte telas

Padrões (um guia existente os sobrepõe):

PadrãoPor quê
Ao passar o mouse, peças com borda apenas escurecem a bordaUm fundo que muda em cartões e campos parece pesado
Hover é mais sutil que selecionadoQuando hover parece selecionado, as pessoas pensam que duas coisas estão escolhidas
Selecionar nunca altera o peso da fonteUma alteração de peso desloca a largura do texto
Placeholders são mais claros que texto suaveCaso contrário, um placeholder parece texto digitado
Itens em listas empilhadas e menus têm um pequeno espaço, nunca tocandoDestaques que se tocam se fundem em um bloco
O anel de foco aparece apenas do tecladoUm anel após um clique de mouse parece um bug
Carregando mantém o tamanho exato do elementoMudança de layout
Sombras apenas em coisas flutuantes (menus, popovers, diálogos, toasts), em duas intensidadesSombras em todo lugar nivelam a hierarquia que deveriam criar
No máximo uma ação primária por telaDuas primárias significa que a tela não decidiu

Concluído quando

  • Criar: fundações e regras de interação aprovadas; cada componente tem sua anatomia, matriz de estados e uma linha no índice.
  • Alterar: cada tela e local de código listado atualizado, e o índice atualizado.
  • Auditar: um relatório classificado entregue e nenhum arquivo alterado.

Erros comuns

PensamentoRealidade
"Vou construir o guia inteiro de uma vez: tokens e dez componentes"Dez componentes sobre fundações não aprovadas significa dez retrabalhos. Fundações, pare, depois componentes.
"A auditoria encontrou problemas, vou apenas corrigi-los"A pessoa pode discordar de metade das correções. Relate, pare, corrija apenas o que eles escolherem.
"Mantive os originais em uma pasta de backup, então corrigir é seguro"Um backup não faz a pessoa concordar com as correções. Relate primeiro.
"Botões têm hover e desabilitado, bom o suficiente"Uma matriz de estados tem cada estado × cada variante: normal, hover, pressionado, foco, desabilitado, carregando, selecionado.
"--teal-600 é um token"É um valor. Componentes precisam de papéis (--cor-primaria) para que o valor possa mudar em um só lugar.
"Esta tela precisa de um cartão ligeiramente diferente"Torne-o uma variante do cartão, ou use o cartão. Uma peça única é o início da divergência.

Habilidades Relacionadas