Como eu estruturo um Design System.

Princípios · o que guia cada decisão.

Antes de tokens e componentes, as regras que não se negociam. Elas resolvem discussão de gosto e mantêm o sistema coerente quando muita gente contribui.

Arquitetura & stack · como o sistema é montado.

Um DS maduro tem metodologia e stack, não é um arquivo de Figma solto. Método claro pra escalar, e a ferramenta certa em cada camada, do visual ao código.

Metodologia · Atomic Design

Pipeline de tokens · do Figma ao código

Uma mudança no Figma propaga pro CSS, iOS e Android sem retrabalho manual. É o que dá consistência multiplataforma de verdade.

Stack por camada

Cor · tokens em 3 camadas.

O valor bruto nunca toca a tela. Ele passa pelo semântico, que é o que troca no dark mode. O componente só enxerga a camada de componente. É essa cadeia que dá theming e escala sem redesenhar nada.

Tipografia · uma escala, não fontes soltas.

Geist para interface, escala definida por token. Cada estilo tem um propósito. Hierarquia é decisão, não acaso.

Espaçamento & raio · ritmo previsível.

Base 4px. Todo padding, gap e margem sai dessa escala, nunca de um número mágico. Raio idem. É o que faz telas de squads diferentes parecerem o mesmo produto.

Espaçamento (px)

Raio (px)

Button · documentado com código.

Um componente, um propósito. Variantes cobrem intenção; estados cobrem interação; tamanhos cobrem contexto. Tudo apontando pros tokens.

Variantes

<!-- intenção define a variante -->
<button class="btn btn-primary">Confirmar</button>
<button class="btn btn-secondary">Cancelar</button>
<button class="btn btn-ghost">Saiba mais</button>
<button class="btn btn-danger">Excluir</button>

Estados · primary

Tamanhos

Input · o mesmo rigor, outro componente.

Prova de que o sistema escala: mesmos tokens de cor, foco, raio e espaçamento, aplicados a um segundo componente. Consistência não é sorte, é a mesma fonte.

<div class="field">
  <label>E-mail</label>
  <input class="inp" placeholder="seu@email.com">
  <!-- .err adiciona borda + hint de erro -->
</div>

Card · onde os átomos viram sistema.

Button e Input são átomos. O Card os combina em algo maior, sem nenhum valor novo: reusa os mesmos tokens de surface, borda, espaçamento e os componentes Badge e Button. É isso que separa uma biblioteca de peças de um sistema de verdade.

<!-- só composição: nenhum token ou cor novo -->
<div class="ds-card">
  <div class="top">
    <span class="title">Transferência</span>
    <span class="badge badge-success">Concluída</span>
  </div>
  <div class="amount">R$ 1.240,00</div>
  <div class="foot">
    <button class="btn btn-primary btn-sm">Repetir</button>
    <button class="btn btn-ghost btn-sm">Ver detalhes</button>
  </div>
</div>

Reusa: surface-raised, border-default, escala de espaçamento, Badge e Button. Troque o tema no menu: o Card acompanha, porque nada nele é fixo.

Governança & operação · o que mantém o sistema vivo.

Componente bonito qualquer um faz. DS maduro é o processo: quem decide, como um componente entra, como versiona e como se mede adoção. É aqui que ele deixa de ser biblioteca e vira sistema.

Modelo · híbrido

Intake · o filtro que vem antes de tudo

Como um componente entra · contribuição

Critérios de entrada: é reutilizável? já existe algo parecido? atende acessibilidade? Sem esse filtro, o DS vira cemitério de componentes.

Changelog · exemplo

Handoff · do token à variável de código.

Single source of truth: o token do Figma é o mesmo que chega no código, sem tradução manual. E um checklist do que entra, pro dev implementar sem adivinhar.

// gerado e auditado por agente
{
  "button-primary-bg": "{action.primary}",
  "button-primary-hover": "{action.primary.hover}",
  "button-radius": "10px",
  "button-height-md": "44px"
}

/* build automático · code parity */
:root {
  --button-primary-bg: #6B5BFF;
  --button-primary-hover: #574AE0;
  --button-radius: 10px;
  --button-height-md: 44px;
}

Estrutura do repositório

Cada componente carrega seu .html, .css e .stories.js (Storybook), versionado no Git. O designer entende o repositório; o dev entende o design. Sem tradução perdida no meio.

IA · não é acabamento, é o que muda a escala.

Design System sempre foi caro em tempo: auditar tokens, documentar componente a componente, checar acessibilidade tela a tela. A IA não faz "o mesmo, mais rápido". Ela faz o que antes não cabia no orçamento de tempo do time. É aqui que eu opero diferente da maioria.

Por que documentei isto · o processo, não a promessa.

Não é um projeto de cliente, é o método que eu uso no dia a dia, do token ao handoff. Mostro o processo aberto porque é assim que eu estruturo um Design System em qualquer time. Prefiro mostrar o processo a prometer o resultado.