twltr/design-system

Design System

Skill folha em Design; acessada por meio de seu domínio ou pelo nome.

Um design system economiza decisões apenas enquanto as equipes confiam nele. A deriva corrói essa confiança silenciosamente: três nomes para um componente, valores hexadecimais fixos ao lado dos tokens que eles duplicam, estados que ninguém documentou. Quando as pessoas param de confiar no sistema, elas constroem ao redor dele. Este método funciona em três modos — auditar o sistema como ele é, documentar um componente para que possa ser usado corretamente, expandir com um padrão que se encaixe — e fundamenta cada um na fonte real: arquivos de tokens, código do componente e o arquivo de design, não uma ideia genérica de um design system.

Um achado de auditoria exemplificado

Situação (fictícia): uma biblioteca React com um arquivo de tokens; a solicitação é "auditar nossos botões e cards".

Nomenclatura    Button, IconBtn e .btn-link nomeiam um conceito de três maneiras.
                → Adotar Button com uma variante `icon` e `link`; criar alias para os nomes
                  antigos por um release.
Tokens          23 cores fixas em Card e Modal. 18 equivalem a um token existente
                (substituir mecanicamente); 5 não correspondem a nenhum.
                → As 5 precisam de uma decisão: um token faltante ou um erro de design a corrigir.
Estados         Card não tem estado de foco embora seja clicável.

A escolha reutilizável é a separação entre um valor que duplica um token, que é uma correção mecânica, e um que não corresponde a nenhum token, que é uma questão de design a ser colocada diante de uma pessoa em vez de adivinhar.

Coletar o sistema

Leia o que existe antes de julgá-lo: a fonte dos tokens, o código ou biblioteca do componente e a documentação. Uma pesquisa como rg -n '#[0-9a-fA-F]{3,8}\b|[0-9]+px' src/components encontra valores fixos em código; adapte o padrão à stack.

Seções marcadas com ~~ nomeiam uma categoria de ferramenta, não um produto: ~~design tool (por exemplo Figma) ou ~~knowledge base (por exemplo Notion). Use a ferramenta conectada daquela categoria que o host fornecer; pule a etapa quando não houver.

Com uma ~~design tool, inspecione nomes de componentes, variantes, estrutura de camadas e uso de tokens no arquivo de design e compare-os com o código. Com uma ~~knowledge base, encontre páginas de componentes existentes e diretrizes de uso e publique documentação atualizada lá apenas quando a pessoa solicitou.

Um sistema tem três camadas; a auditoria e a documentação cobrem cada uma:

Camada	Conteúdo
Tokens	Cor (marca, semântica, neutra), tipografia, espaçamento, raio e borda, elevação, durações de movimento e easing
Componentes	Variantes, estados (padrão, hover, focus, active, disabled, loading, error), tamanhos, comportamento, acessibilidade
Padrões	Formulários, navegação, exibição de dados, feedback — componentes combinados para resolver um problema recorrente

Quando tokens se movem entre ferramentas, o formato Design Tokens Community Group (primeira versão estável 2025.10, outubro de 2025) é o formato de intercâmbio comum; siga o formato que o projeto já usa.

Princípios

1. Consistência sobre novidade. O sistema existe para que as equipes parem de redecidir as mesmas coisas; uma variante única precisa de um motivo que o sistema não tem.
2. Componível dentro de restrições. Prefira uma variante ou uma composição de componentes existentes a um novo componente.
3. Não documentado significa inutilizável. Um estado ou variante que ninguém pode encontrar é reconstruído.
4. Versionar e migrar. Uma renomeação ou remoção que quebra precisa de um caminho de migração, como um alias por um release e um codemod ou uma pesquisa para encontrar usos.

Auditar

Relate contagens e evidências, não uma pontuação: um número sem critérios esconde qual problema importa.

## Auditoria do design system: [escopo]

**Revisado:** [componentes, arquivos de tokens] | **Achados:** [contagem por categoria]

### Nomenclatura
| Problema | Onde | Recomendação |
|---|---|---|

### Cobertura de tokens
| Categoria | Tokens definidos | Valores fixos | Correspondendo a um token existente |
|---|---|---|---|

### Completude dos componentes
| Componente | Estados | Variantes | Docs | Acessibilidade |
|---|---|---|---|---|
| Botão | completo | parcial: sem tamanho só ícone | faltando | anel de foco presente |

### Ações prioritárias
1. [Maior impacto para usuário ou equipe primeiro, com o esforço necessário]

Documentar

Documente um componente reutilizável para todos que o consomem. Use props e o exemplo de código do componente real, não uma API inventada.

## Componente: [Nome]

[O que é e quando usá-lo — e quando usar outra coisa]

### Variantes
| Variante | Use quando |
|---|---|

### Props
| Prop | Tipo | Padrão | Descrição |
|---|---|---|---|

### Estados
| Estado | Visual | Comportamento |
|---|---|---|

### Acessibilidade
- **Papel:** [papel ou elemento nativo]
- **Teclado:** [Tab, Enter, Espaço, Escape, setas]
- **Leitor de tela:** [anunciado como …]

### Faça e não faça
| Faça | Não faça |
|---|---|

### Exemplo
[Um pequeno trecho no framework do projeto]

Expandir

Antes de propor algo novo, liste os componentes existentes que se aproximam e explique por que cada um não é suficiente; a maioria das solicitações termina como uma nova variante. Um novo componente reutiliza tokens existentes e só propõe um novo token com sua justificativa.

## Componente proposto: [Nome]

### Problema
[A necessidade do usuário ou lacuna]

### Opções existentes
| Componente | O que compartilha | Por que não é suficiente |
|---|---|---|

### Design
Props, variantes e estados como no template de documentação; tokens usados.

### Acessibilidade
Papel, comportamento de teclado e leitor de tela.

### Perguntas em aberto
[Decisões que precisam de revisão de design]

Os componentes e tokens do sistema são o assunto deste método. Uma especificação para um recurso ou tela, e a direção visual de um novo produto, são trabalhos de design separados; uma auditoria de sistema também não substitui uma auditoria WCAG.