Como expor seu design system para LLMs e agentes de IA

LLMs inventam tokens, mudam de valor no meio da sessão e começam cada conversa do zero. Um design system legível para LLMs resolve isso com specs estruturadas, uma camada fechada de tokens e auditoria automática, para que o agente pare de chutar.

TL;DR

O design system já existe como código: bibliotecas de componentes, arquivos de tokens, variáveis do Figma. O problema é que as LLMs não conseguem usar isso direito durante o vibe coding.

Elas inventam nomes de tokens, mudam os valores dentro de uma mesma sessão e perdem todo o contexto entre uma sessão e outra. Também não percebem quando a biblioteca upstream publica mudanças que quebram compatibilidade.

O método descrito aqui reestrutura o design system num formato que as LLMs conseguem consumir de forma confiável: arquivos de spec estruturados, uma camada fechada de tokens e auditoria automatizada que pega toda violação.

Resultado: a décima sessão com IA produz a mesma qualidade visual da primeira.

As LLMs não pensam em design systems

Imagine a cena: você está fazendo vibe coding de um protótipo. Descreve um componente, a IA constrói, fica bom. Descreve outro, também fica bom.

No fim da sessão, são 15 componentes e um layout com cara de profissional. Ótimo primeiro dia. Só que, por baixo do capô, aconteceu outra coisa.

A IA tomou entre 200 e 300 microdecisões visuais durante aquela sessão:

• Qual padding usar neste card
• Qual tom de azul para aquele link
• Qual border radius neste botão
• Quanto espaçamento entre um título e um parágrafo
• Qual font weight para aquele rótulo
• Se usa 12px ou 16px no texto secundário

Cada uma dessas decisões parecia adequada isoladamente:

• O padding do card era 16px em um componente e 12px em outro
• A cor do link era #2563EB na navegação e #1D4ED8 na área de conteúdo
• Um botão tem 6px de border radius, outro tem 8px

Por que você notaria? Cada escolha individual era razoável.

Mas 200 chutes razoáveis não somam um design consistente. Somam um protótipo que parece levemente errado sem que você consiga dizer exatamente por quê.

Piora ao longo de várias sessões de vibe coding

Você volta no dia seguinte. Sessão nova. A IA tem zero memória das decisões de ontem. Não sabe que escolheu #2563EB para os links, 16px de padding no card ou 8px de border radius. Ela começa a chutar de novo, e são chutes diferentes desta vez.

Agora são duas camadas de inconsistência: os 200 chutes de ontem e os 200 chutes diferentes de hoje, lado a lado no mesmo protótipo.

Na quinta sessão, o protótipo parece “estranho” e você não consegue apontar o motivo. Na décima, parece três produtos diferentes construídos por três times que nunca conversaram entre si.

Três limitações das LLMs que causam isso

1. Elas inventam valores. LLMs não consultam os tokens do seu design system, elas geram tokens plausíveis. Se o seu sistema usa --space-200 para 8px, a LLM pode escrever padding: 12px porque 12px é um número razoável. Não está errado em si, só não é o seu.

2. Elas não têm memória entre sessões. Toda sessão nova começa sem contexto. A LLM não sabe que usou #2563EB para os links ontem, então hoje escolhe um azul novo. Na quinta sessão, são três azuis diferentes no mesmo protótipo, todos “aceitáveis”.

3. Elas não conseguem ler a intenção de design no código-fonte. Aponte uma LLM para uma biblioteca de componentes como o Atlaskit e ela enxerga APIs: importe Button, passe appearance="primary", pronto. O que ela não consegue extrair do código-fonte:

• Quando escolher um componente em vez de outro
• Que espaçamento usar entre eles
• Como compor tudo em layouts que seguem as suas convenções

Esse conhecimento mora na cabeça dos designers. As LLMs precisam dele escrito num formato que consigam consumir no início de cada sessão.

É a mesma diferença que separa código que funciona de código que presta: a IA entrega os dois com a mesma confiança.

Como deixar o design system legível para LLMs

A abordagem tem três camadas: arquivos de spec que a LLM lê, uma camada de tokens de onde ela escolhe e uma auditoria que pega o que ela erra.

Em vez de a LLM decidir “que azul este link deveria ter?”, ela lê um arquivo de spec e encontra var(--color-link). Em vez de inventar um valor de espaçamento, lê a referência de tokens e encontra var(--space-200). A decisão de design já foi tomada por um humano, a LLM só consulta.

Pense nisso como Infrastructure as Code. Antes do IaC, cada servidor era configurado na mão e não havia dois iguais. O IaC tornou a configuração de servidores reproduzível e auditável. Aqui a ideia é a mesma para decisões de design: torná-las legíveis por máquina para que as LLMs parem de chutar.

São quatro partes, cada uma mirando uma limitação específica das LLMs:

1. Arquivos de spec que a LLM lê a cada sessão. Resolve o problema de memória. Suas regras de espaçamento, escolhas de cor e diretrizes de uso de componentes vão para arquivos markdown estruturados, que a LLM lê no início da sessão. Sem arquivo de spec, a LLM chuta. Com arquivo de spec, ela consulta.

2. Uma camada fechada de tokens de onde a LLM escolhe. Resolve o problema da invenção. Em vez de padding: 16px espalhado por 30 arquivos, você cria var(--space-200) e usa em todo lugar. A LLM escolhe dentro de um conjunto fechado de variáveis nomeadas em vez de inventar valores plausíveis.

3. Um script de auditoria que pega o que a LLM erra. Resolve o problema do desvio. Ele varre os arquivos CSS e sinaliza todo valor cru junto com o token correto a usar no lugar. Se a LLM escrever color: #2563EB, o script diz “use var(--color-link)”. Roda no CI, e zero violações é o requisito.

4. Detecção de desvio para atualizações do design system upstream. Resolve o problema das premissas desatualizadas. Quando a biblioteca do design system publica atualizações, uma rotina de sync sinaliza quais arquivos de spec precisam ser revistos. A LLM sempre lê specs atuais, não specs escritas contra uma versão de três meses atrás.

O setup

Tudo o que foi descrito acima (os arquivos de spec, a camada de tokens, o script de auditoria, a detecção de desvio) pode ser implementado com um único prompt.

Cole isto no Claude Code, ou em qualquer agente de IA para código, na raiz do seu projeto:

Audite este projeto e deixe o design system legível para LLMs.

Passo 1: Auditoria
Varra todos os arquivos CSS/SCSS. Liste todo valor visual
hardcoded: cores hex, cores rgb/rgba, espaçamentos em pixel,
tamanhos de fonte crus, font weights, border radius, valores
de z-index, box shadows e durações de transição. Agrupe por
categoria. Conte os totais. Informe quais arquivos têm mais
valores hardcoded.

Passo 2: Camada de tokens
Crie um arquivo tokens.css com três camadas:
- Camada 1: tokens do design system upstream (use os
  existentes se o projeto já usa um design system, senão
  derive primitivos sensatos a partir da auditoria)
- Camada 2: aliases do projeto que referenciam a Camada 1
  com fallbacks, ex.: --color-text: var(--ds-text, #292A2E)
- A Camada 3 são os próprios componentes: eles só
  referenciam aliases da Camada 2, nunca valores crus

Inclua tokens para: cores (texto, fundo, link, borda, estados
interativos), espaçamento (pelo menos 8 passos), tipografia
(famílias, tamanhos, pesos, alturas de linha), border radius,
elevação/sombra, z-index e motion/transições.

Passo 3: Arquivos de spec
Crie um diretório specs/. Escreva specs em markdown
estruturado:
- specs/foundations/: color.md, spacing.md, typography.md,
  radius.md, elevation.md, motion.md
- specs/tokens/: token-reference.md (mapa mestre de cada
  variável CSS, seu valor e quando usar)
- specs/components/: um arquivo por componente relevante do
  projeto. Cada spec segue este template:
  1. Metadados (nome, categoria, status)
  2. Visão geral (quando usar, quando não usar)
  3. Anatomia (partes do componente)
  4. Tokens usados (quais variáveis CSS ele referencia)
  5. Props/API (se aplicável)
  6. Estados (default, hover, active, focus, disabled, error)
  7. Exemplo de código
  8. Referências cruzadas (componentes relacionados)

Faça spec apenas dos componentes que realmente existem
neste projeto.

Passo 4: Script de auditoria
Crie scripts/token-audit.js (ou .sh) que:
- Varra todos os arquivos CSS em busca de valores hardcoded
- Sugira o token correto para cada violação
- Imprima arquivo, número da linha, violação e sugestão
- Retorne exit code 1 se encontrar erros (pronto para CI)
- Separe erros (cores e espaçamentos hardcoded) de avisos
  (durações cruas, valores incomuns)

Passo 5: Substituir os valores hardcoded
Percorra todos os arquivos CSS e substitua os valores
hardcoded pelos tokens do Passo 2. Todo color:, background:,
padding:, margin:, gap:, border-radius:, font-size:,
font-weight:, box-shadow:, z-index: e transition: deve
referenciar um var(--token). Nenhum valor cru deve restar.

Passo 6: Instruções do projeto
Adicione uma seção ao arquivo de instruções de IA do projeto
(CLAUDE.md, .cursorrules ou equivalente) dizendo:
"Antes de escrever ou modificar qualquer código de UI, leia o
arquivo de spec correspondente em specs/. Use apenas tokens
de tokens.css. Rode o script de auditoria de tokens antes de
commitar. Zero erros é obrigatório."

Rode o script de auditoria no final e confirme zero violações.

Revise a saída, ajuste os valores dos tokens ao seu gosto e faça o commit. O que você recebe de volta:

• Um arquivo tokens.css com indireção em três camadas
• Arquivos de spec de fundação e de componentes para tudo que existe no projeto
• Um script de auditoria de tokens que pega valores hardcoded no CI
• Todo valor CSS hardcoded substituído pelo token correto
• Um arquivo de instruções do projeto para toda sessão futura com IA

O que o prompt faz

São seis passos, cada um produzindo algo que vale revisar.

Passo 1: encontrar todo valor hardcoded

O prompt varre todos os arquivos CSS e conta os valores hardcoded: cores hexadecimais, espaçamentos em pixel, tamanhos de fonte crus, border radius.

Essa contagem vira a sua linha de base. Se ele encontrar centenas de violações espalhadas por dezenas de arquivos, você sabe o tamanho do desvio.

Passo 2: criar tokens nomeados para cada valor

O prompt cria um arquivo tokens.css com três camadas de indireção.

Primeiro, os tokens upstream do seu design system chegam em variáveis com prefixo:

--ds-text: #292A2E;
--ds-space-100: 8px;
--ds-radius-200: 8px;

Em seguida, o seu projeto cria um alias para cada um, com o valor cru como fallback:

--color-text: var(--ds-text, #292A2E);
--space-100: var(--ds-space-100, 8px);
--radius-200: var(--ds-radius-200, 8px);

Os componentes só referenciam o alias, nunca o token upstream:

color: var(--color-text);
padding: var(--space-100);
border-radius: var(--radius-200);

A camada de alias é o que protege você. Se o design system renomear um token upstream, você atualiza um alias só. Dark mode, alto contraste, qualquer tema futuro: tudo se resolve automaticamente pela cadeia.

Vale nomear os tokens pela função, não pela aparência. É o que evita armadilhas como o problema de contraste dos botões, em que o fundo tem token e o texto não.

Aprenda o que os tutoriais não mostram! Camadas de token só se sustentam sobre uma arquitetura CSS bem definida. Aprenda as metodologias que tornam o seu CSS realmente escalável.

Conheça o curso

Passo 3: escrever arquivos de spec para cada componente

O prompt gera specs em markdown estruturado, organizadas em níveis:

• Fundações: cor, espaçamento, tipografia, radius, elevação, motion
• Referência de tokens: o mapa mestre de cada variável CSS
• Átomos: button, input, icon-button. Elementos de propósito único
• Moléculas e organismos: componentes compostos, específicos do seu produto
• Padrões: regras de layout, fluxo de conteúdo, espaçamento entre elementos
• Referências cruzadas: links de “usa” e “é usado por” entre todos os arquivos

Cada arquivo segue um template consistente de 8 seções: metadados, visão geral, anatomia, tokens, props/API, estados, exemplos de código e referências cruzadas.

Revise primeiro as specs de fundação. Cor e espaçamento governam tudo que vem depois, então, se essas estiverem certas, as specs de componente vêm atrás.

Passo 4: conectar scripts de auditoria e instruções para a IA

O prompt conecta três coisas.

Um arquivo de instruções do projeto que exige a consulta às specs antes de qualquer trabalho de UI. É lido no início de toda sessão com IA.

Um script de auditoria de tokens que varre os arquivos CSS, encontra valores hardcoded e sugere o token correto. Ele retorna exit code 1 em caso de erro, então dá para colocar no CI.

Exemplo de saída:

Token Audit
Scanning 28 CSS file(s)...

src/components/Nav.css
  x L42: Hardcoded color #1868DB, use var(--color-link)
  x L78: Raw spacing 12px in padding, use var(--space-150)
  ! L96: Raw duration 0.2s, consider using --motion-* token

=== Summary ===
Files scanned:      28
Files with issues:  0
Errors:             0
Warnings:           0

Um checklist de revisão de design cobrindo valores hardcoded, cobertura de estados, anatomia de componentes, consistência de espaçamento, tipografia, motion, acessibilidade e documentação de divergências.

Passo 5: substituir todo valor hardcoded por um token

O prompt percorre cada arquivo CSS e substitui os valores hardcoded pelos tokens que criou. Todo color:, padding:, border-radius: e font-size: passa por var(--token) agora.

Passo 6: detectar desvio do design system upstream

O prompt configura uma rotina de sync que fixa as versões dos pacotes do design system e detecta desvios. Quando a biblioteca upstream publica atualizações, ela sinaliza quais arquivos de spec talvez precisem ser atualizados. Não é bloqueante: reporta os achados, mas não modifica as specs sozinha.

Depois do setup inicial, a manutenção é mínima:

• Componente novo? Adicione um arquivo de spec antes ou durante a construção.
• Atualização do design system? A rotina de sync sinaliza. Atualize os documentos afetados.
• Padrão novo? Se um designer corrige a mesma coisa em duas revisões de PR, isso é um padrão. Escreva.
• Auditoria de tokens falhando? Corrija o valor hardcoded, não o script de auditoria.

O método testado com o design system da Atlassian

O experimento rodou em um projeto React + TypeScript + Vite usando o Atlaskit, o design system público da Atlassian. O método funciona com qualquer biblioteca de componentes.

64 arquivos de spec em 3 níveis

A hierarquia de arquivos

O diretório specs/ completo:

your-project/
├── specs/
│   ├── foundations/                     # Nível 1: primitivos visuais
│   │   ├── color.md
│   │   ├── typography.md
│   │   ├── spacing.md
│   │   ├── radius.md
│   │   ├── elevation.md
│   │   ├── motion.md
│   │   ├── z-index.md
│   │   ├── iconography.md
│   │   ├── accessibility.md
│   │   ├── breakpoints.md
│   │   ├── grid.md
│   │   ├── borders.md
│   │   └── opacity.md
│   │
│   ├── tokens/                         # Nível 1: referência de variáveis CSS
│   │   ├── token-reference.md
│   │   ├── color-tokens.md
│   │   ├── spacing-tokens.md
│   │   ├── typography-tokens.md
│   │   ├── elevation-tokens.md
│   │   └── motion-tokens.md
│   │
│   ├── atoms/                          # Nível 2: componentes
│   │   ├── button.md
│   │   ├── icon-button.md
│   │   ├── input.md
│   │   ├── textarea.md
│   │   ├── checkbox.md
│   │   ├── radio.md
│   │   ├── toggle.md
│   │   ├── avatar.md
│   │   ├── badge.md
│   │   ├── lozenge.md
│   │   ├── tag.md
│   │   ├── spinner.md
│   │   └── link.md
│   │
│   ├── molecules/                      # Nível 2: componentes compostos
│   │   ├── tabs.md
│   │   ├── breadcrumbs.md
│   │   ├── dropdown-menu.md
│   │   ├── modal-dialog.md
│   │   ├── banner.md
│   │   ├── flag.md
│   │   ├── inline-message.md
│   │   ├── tooltip.md
│   │   ├── form.md
│   │   ├── select.md
│   │   ├── date-picker.md
│   │   ├── pagination.md
│   │   ├── inline-edit.md
│   │   ├── search.md
│   │   ├── popup.md
│   │   ├── progress-bar.md
│   │   ├── side-navigation.md
│   │   └── empty-state.md
│   │
│   ├── organisms/                      # Nível 2: montagens específicas do produto
│   │   ├── table.md
│   │   ├── navigation.md
│   │   ├── page-header.md
│   │   ├── content-panel.md
│   │   ├── chat-panel.md
│   │   ├── dashboard-card.md
│   │   └── work-item-header.md
│   │
│   └── patterns/                       # Nível 3: regras de layout e composição
│       ├── canvas-content-flow.md
│       ├── three-column-layout.md
│       ├── responsive-grid.md
│       ├── panel-expand-collapse.md
│       ├── form-layout.md
│       ├── list-detail.md
│       └── error-handling.md
│
├── tokens.css                          # ← Toda variável CSS (indireção em 3 camadas)
├── scripts/
│   └── token-audit.js                  # ← Pega valores hardcoded no CI
└── CLAUDE.md                           # ← A IA lê isto no início de cada sessão

Cada nível só referencia o nível acima:

• Fundações + tokens definem os valores crus e os nomeiam como variáveis CSS: que azuis existem, que passos de espaçamento existem e para que --color-link ou --space-200 resolvem
• Componentes (átomos, moléculas e organismos) usam esses tokens para estilizar elementos. Um botão conhece seu token de padding, de cor e de radius. Um dropdown compõe button, popup e itens de lista. Uma barra de navegação monta dropdown, breadcrumbs e avatar
• Padrões descrevem como organizar componentes numa página: regras de layout de três colunas, espaçamento entre seções de conteúdo, como painéis expandem e recolhem

Quando a IA constrói um formulário, ela lê patterns/form-layout.md para as regras de espaçamento, molecules/form.md para a estrutura do formulário, atoms/input.md para o componente de input e tokens/spacing-tokens.md para os valores exatos. Toda decisão é uma consulta.

Todo valor visual ganha um nome

Depois de rodar o prompt, todo valor visual hardcoded do projeto foi substituído por uma variável CSS nomeada.

A auditoria encontrou 418 valores crus espalhados por 28 arquivos. O prompt mapeou todos eles para mais de 230 tokens guardados em tokens.css:

• 69 cores (fundos, texto, bordas, links, estados interativos)
• 12 valores de espaçamento (padding, margin, gap, todos numa grade base de 4px)
• 8 tamanhos de fonte (de caption a display)
• 7 radii (do sutil 2px ao totalmente arredondado)
• 8 níveis de z-index (dropdowns, modais, tooltips, toasts)

Nenhum arquivo contém mais uma cor hexadecimal crua ou um valor em pixel. A IA não consegue escolher o azul errado porque só existe var(--color-link).

Antes e depois

Por que isso importa em protótipos grandes

Protótipos feitos com vibe coding desmoronam depois de algumas sessões porque as LLMs acumulam erros silenciosamente. Cada sessão introduz valores inventados, inconsistências novas e desvio em relação ao design system de origem. Na décima sessão, o protótipo parece três produtos diferentes.

Um design system legível restringe a LLM em cada ponto onde ela chutaria. As specs dão memória entre sessões. A camada de tokens dá um conjunto fechado de valores em vez de valores inventados. A auditoria pega o que escapa, e a detecção de desvio mantém tudo alinhado com o upstream.

A sua décima sessão produz a mesma qualidade visual da primeira.

Os resultados obtidos

Os números importam menos do que a mudança na forma de trabalhar. A equipe por trás do experimento parou de revisar a saída da LLM em busca de consistência visual porque as restrições dão conta disso.

A LLM lê a spec, usa o token, e a auditoria pega o que passar. O gosto humano entra uma vez e, daí em diante, a LLM o segue mecanicamente.

Perguntas frequentes

”Isso não é só documentação?”

Documentação diz o que existe. Isto também bloqueia o que não deveria existir.

O script de auditoria retorna exit code 1 se qualquer valor hardcoded aparecer no CSS. O arquivo de instruções do projeto condiciona toda mudança de UI à consulta das specs. Não dá para fazer merge de código que viola a camada de tokens.

”3 a 4 dias de setup parece muito”

Essa é a estimativa manual. O prompt de setup mostrado acima leva um agente de IA pelos seis passos numa sessão só. Você revisa a saída, ajusta os valores dos tokens ao seu gosto e faz o commit. O tempo típico é de algumas horas.

”As specs não vão ficar desatualizadas?”

Os arquivos de spec moram no repositório, ao lado do código que governam, não num wiki ou num comentário do Figma. Quando um componente muda num PR, o arquivo de spec está ali no mesmo diff. A rotina de detecção de desvio sinaliza atualizações do design system upstream que afetam as suas specs.

”A IA não pode simplesmente ler o código-fonte?”

Ela consegue ler as APIs dos componentes. O que ela não consegue ler são as suas opiniões: quando usar um modal em vez de uma mensagem inline, que convenção de espaçamento você segue entre seções, como o seu layout de três colunas se comporta em breakpoints de tablet.

O código-fonte mostra o que foi construído. As specs descrevem como construir a próxima coisa.

”Nossos designers já sabem disso tudo”

Conhecimento não escrito não se transfere para sessões de IA, para quem acabou de entrar no time nem para prestadores. Também não sobrevive à saída de alguém da equipe.

Arquivos de spec colocam esse conhecimento sob controle de versão, onde ele é lido no início de toda sessão com IA e de todo onboarding.