---
title: "Design system legível para LLMs: especificações, tokens e auditoria automática"
description: "Como transformar um design system em material que agentes de código realmente consomem — specs estruturadas, camada de tokens fechada, script de auditoria no CI e detecção de drift — com o caso do Atlaskian e implementações open source."
canonical: "https://ronanrodrigo.dev/notes/design-system-legivel-para-llms"
markdown: "https://ronanrodrigo.dev/notes/design-system-legivel-para-llms.md"
last-updated: "2026-09-25"
---
## Expose your design system to LLMs: specs, tokens fechados e auditoria em CI

O argumento do texto é direto: um design system já existe como código — biblioteca de componentes, arquivo de tokens, variáveis no Figma — mas o modelo não consegue usá-lo, porque inventa nomes de token, varia valores dentro da mesma sessão, perde todo o contexto entre sessões e não percebe quando a biblioteca upstream publica mudanças incompatíveis. A saída proposta é reestruturar o design system em quatro peças: arquivos de especificação em Markdown lidos no início de cada sessão, uma camada de tokens fechada que o modelo escolhe em vez de inventar, um script de auditoria que aponta cada violação com o token correto e roda no CI, e uma rotina de detecção de drift para avisar quais specs estão desatualizadas. A analogia é a de Infrastructure as Code: antes do IaC cada servidor era configurado à mão; specs estruturadas tornam a decisão de design reproduzível e auditável. O caso relatado é um projeto React + TypeScript + Vite sobre o Atlaskit, que terminou com 418 valores hardcoded substituídos, 64 specs em três níveis e 230+ tokens mapeados. A página traz também um prompt único, de seis passos, para rodar isso dentro de um agente de código.

[Acesse a fonte original](https://hvpandya.com/llm-design-systems)

## LLM context design: a mesma receita com três camadas, do ponto de vista do Figma

A Figma descreve o mesmo problema com a terminologia de context engineering: um modelo não consegue preencher o que a documentação de design deixa de fora. A primeira camada é a camada de tokens, precisa distinguir token primitivo — o valor cru, um hex ou um número de pixel — de token semântico, que nomeia aquele valor pelo papel que cumpre na interface. Um hex solto não dá âncora ao modelo, então ele chega perto e chama aquilo de certo. A segunda são as regras de uso escritas dentro da própria spec, não só a aparência: a spec visual de um alerta cobre cor e ícone de aviso contra erro, mas não cobre o julgamento, como nunca empilhar um aviso atrás de um erro — sem essa regra o modelo recorre ao padrão que mais aparece no código que já viu. A terceira é o laço de auditoria, que não precisa ser pesado: puxar algumas telas geradas por IA por semana e compará-las com a biblioteca. A recomendação de partida é não esperar o design system inteiro ficar pronto — escolher um componente comum, documentar tokens e regras, rodar uma variante gerada pela auditoria e usar as lacunas aparecidas para decidir o próximo componente.

[Acesse a fonte original](https://www.figma.com/resource-library/llm-context-design/)

## agentic-spec: contrato fechado por componente, validado em CI e servido por MCP

Esse projeto ataca o mesmo alvo pelo lado do contrato verificável. Em vez de specs em prosa, cada componente ganha dois arquivos: um `index.md` com o contrato em frontmatter mais texto humano e um `tokens.json` com a lista fechada de tokens que aquele componente pode usar. O frontmatter é o que fecha o sistema — `token_contract` é exaustivo, `semantic_parts` nomeia cada região que um token pode atingir, `required_aria` e `interaction_states` são enumerados, e `sources` aponta para os arquivos reais de código, story e token; qualquer coisa fora disso é falha de lint. A ferramenta valida em dois lugares: uma CLI que quebra o build quando o código diverge do contrato e um servidor MCP que entrega o contrato ao agente antes de ele escrever código e deixa o agente conferir o próprio trabalho, com `list_components`, `get_contract`, `resolve_token` e `validate_contract` entre as ferramentas. A referência é um design system React de 121 componentes construído inteiro nesse formato, com os 121 passando na validação. A documentação de adoção traz exemplos completos em MUI, shadcn e Astryx.

[Acesse a fonte original](https://github.com/tishsingh399/agentic-spec)

## work-with-design-systems: a Fase 6 que leva as specs da Figma para o repositório

Skill para Claude Code que trabalha com design systems no Figma em dois modos — inspect, só leitura, com auditorias de WCAG, pontuação de componentes e documentação de handoff, e build, criando componentes, corrigindo fundações, adicionando slots e escrevendo descrições — com pausa obrigatória entre os dois. A parte relevante para o tema é a Fase 6, opcional e desligada por padrão, que sincroniza para o código: gera `tokens.css` com indireção de três camadas, um arquivo de regras para o agente no IDE e o script de auditoria pronto para CI, fechando o ciclo Figma ↔ código. A indireção de três camadas é a mesma defendida no artigo principal — primitivos do design system, aliases de projeto com o valor cru como fallback, componentes consumindo só o alias. O README credita explicitamente o artigo do Hardik Pandya como inspiração para a arquitetura dessa fase, e a escolha dos caminhos de regras é justificada: `.claude/rules/design-system.md` e afins existem justamente porque arquivos de topo como `CLAUDE.md` e `AGENTS.md` são gerenciados pelo usuário e sobrescrevê-los é destrutivo. Licença MIT, 47 estrelas.

[Acesse a fonte original](https://github.com/natdexterra/work-with-design-systems)

## Atlassian: uma fonte de conteúdo estruturado, três portas de entrada e benchmark

O time do Atlassian resolve o mesmo problema pela via estruturada e relata o que aprendeu medindo. Tudo nasce do mesmo conteúdo — APIs de componentes e orientação de uso, tokens, ícones, acessibilidade e regras de lint — mantido junto do código em schemas tipados, o que dá um conjunto gerado em vez de documentação mantida à mão. Esse conteúdo chega ao agente por três portas: a skill, que o agente carrega quando a tarefa parece trabalho de UI da Atlassian; o servidor MCP, que expõe o conteúdo como ferramentas e serve quando o agente vive dentro do produto de outra pessoa; e a CLI, que expõe o mesmo conteúdo como comandos de terminal, para desenvolvimento local, scripts, CI e agentes sem cliente MCP configurado. CLI e MCP chamam os mesmos handlers e os arquivos de referência da skill são gerados da mesma fonte, então não há drift possível entre os três. O argumento para existir a CLI é distribuição: nem toda ferramenta tem cliente MCP, e um agente que já tem terminal só precisa rodar um comando. A primeira versão levou uma semana porque a lógica de busca e ranqueamento já vivia em módulos compartilhados. O rollout foi tratado como experimento, medindo taxa de aprovação, tempo por tarefa, tokens e chamadas de ferramenta em um banco de tarefas reais de front-end, alternando só a forma de buscar o contexto. O resultado publicado: sessões 8% mais rápidas, 8% menos tokens e uso da CLI superando o MCP em 60%, o que levou a skill a sugerir a CLI por padrão e só recorrer ao MCP quando o sandbox não tem terminal. As lições: não dar vibe em ferramentas agentic e manter em sincronia, julgar a tarefa inteira em vez de só o payload, ler os transcripts além do dashboard, e tratar skill, CLI e MCP como produto.

[Acesse a fonte original](https://www.atlassian.com/blog/ai-at-work/giving-ai-agents-design-system-context-from-the-terminal-what-we-learned-building-a-cli)