TL;DR

Eu taquei o repositório inteiro da Ascent no Claude Design e pedi pra ele me devolver um design system. Em minutos, recebi um projeto navegável com HTML, CSS e tokens. Depois, usei o Claude Code pra compilar tudo num único DESIGN_SYSTEM.md que todo agente de IA lê antes de produzir qualquer peça da marca. Hoje, a identidade da Ascent não vive mais só na minha cabeça.

Gancho

Design system não é PDF bonitinho guardado na pasta do Drive que ninguém abre.

É infraestrutura.

E eu demorei tempo demais pra entender isso.

Tensão

Esses dias, eu estava tentando pedir pro Claude gerar um post da Ascent. Passei o briefing, expliquei a paleta, descrevi a voz. Saiu razoável. Fui pedir de novo, uma semana depois. O resultado era completamente diferente: outra tonalidade de azul, outro tom de copy, outro estilo de título.

O problema não era o Claude. Era eu.

A identidade da Ascent existia só na minha cabeça. As cores “iam mudando ao longo dos anos” (eu mesmo vi isso nos slides antigos: #141F2B, #152238, #0D1628, qual era o azul certo mesmo?). A voz era mais ou menos o que eu lembrava que era. As regras tipográficas eram intuitivas pra mim e para mais ninguém.

Aí entraram os agentes de IA, e o problema virou catastrófico.

Sem regras claras gravadas em algum lugar que a máquina pudesse ler, cada prompt produzia uma versão diferente da Ascent. Hoje saía roxo. Amanhã saía bege. Depois saía amarelo. Marca que vira loteria não ocupa espaço no mercado.

E o pior: eu não tinha como escalar. Cada prestador de serviço que entrava precisava de 30 minutos de briefing verbal. Cada agente novo precisava de um prompt monumental no início da conversa. Era insustentável.

Tinha que transformar o implícito em explícito. Uma vez. De uma forma que tanto humanos quanto máquinas conseguissem ler.

Desenvolvimento

O que eu fiz (e quanto tempo levou)

Resolvi testar uma hipótese: e se eu jogasse tudo que eu tinha no Claude Design e pedisse pra ele engenharia-reversa da minha própria marca?

Subi no Claude Design:

  • O repositório frontend do Ascent.Addin (com todo o CSS, componentes Angular, tokens)
  • A identidade visual antiga (PDF, logos, swatches)
  • Posts do Instagram que eu considerava “no ponto”
  • Anotações espalhadas em Notion e nos commits do Git
  • Apresentações que eu tinha feito pra investidores

Sem briefing. Sem instrução de voz. Sem explicar nada. Só o material.

Em minutos, o Claude Design me devolveu um sistema de design completo e navegável: HTML, CSS, tokens, componentes, páginas linkadas entre si. Tinha paleta, tipografia, guia de componentes, regras de voz, exemplos de copy. Era melhor do que qualquer coisa que eu teria montado num Figma em 3 semanas.

Mas aí surgiu o problema número 2.

Agente de IA não navega site. Agente lê texto.

O sistema era bonito, navegável e totalmente inútil pra qualquer LLM. Precisava de uma segunda etapa.

A compilação via Claude Code

Usei o Claude Code pra ler o projeto inteiro e compilar tudo num único arquivo Markdown: DESIGN_SYSTEM.md. Esse arquivo é denso. Hoje tem 881 linhas. Cobre paleta de cores com hex e tokens CSS, escala tipográfica, componentes canônicos, gradientes autorizados, regras de voz em dois modos (fundador e institucional), copy canônica, nomenclatura exata de produtos, checklist anti-erro, e muito mais.

E esse arquivo vai junto em cada prompt.

Toda vez que algum agente da Ascent precisa produzir algo com a marca, ele lê o DESIGN_SYSTEM.md primeiro. Toda vez que eu peço um post, um slide ou uma landing, o Claude já sabe: Navy #0D1628, Cream #F9D592, Space Grotesk pra display, Inter pra corpo, Roboto Mono pra eyebrows técnicos. Sabe que o blog é modo fundador (1ª pessoa) e a landing é modo institucional (3ª pessoa). Sabe que emerald é exclusivo pra badge // GRÁTIS e botão de download. Sabe que nunca mistura os dois modos de voz num mesmo bloco.

Parei de explicar a marca a cada prompt.

Por que funciona (o princípio técnico por trás)

Existe uma pesquisa publicada por Hardik Pandya que resume bem o que acontece quando você expõe um design system pra LLMs de forma estruturada. O ponto central é este: LLMs fabricam valores onde não encontram regras. Sem token layer fechado, o modelo chuta um azul qualquer. Sem spec de voz, ele mistura tonalidades de copy até sair algo mediano.

A solução não é um briefing verbal a cada prompt. É uma camada de tokens fechada e um arquivo de spec que o modelo carrega antes de qualquer tarefa de marca.

Isso é exatamente o que o DESIGN_SYSTEM.md faz. Não há azul a fabricar porque existe var(--brand-navy). Não há tom de voz a improvisar porque existe a seção §3 com tabela de decisão por canal, exemplos canônicos, Do/Don’t e copy reutilizável.

O resultado prático que Hardik documenta no projeto dele com o Atlaskit foi reduzir 418 valores hardcoded pra zero e garantir que “a 10ª sessão produz a mesma qualidade visual que a 1ª.” No meu caso, o salto foi mais simples: cada carrossel, cada post de blog e cada landing da Ascent agora sai consistente, mesmo quando sou eu, um prestador ou um agente autônomo rodando o prompt.

A estrutura que funcionou: Skills no Claude Code

Uma coisa que fez diferença enorme foi transformar o DESIGN_SYSTEM.md num Skill do Claude Code.

Pra quem não conhece: Skills são recursos baseados em sistema de arquivos que estendem o que o Claude consegue fazer. São como pacotes de expertise modular. Você cria um arquivo SKILL.md, coloca instruções, e o Claude carrega o conteúdo inteiro só quando precisa. Isso resolve um problema crítico: não queima a context window antecipadamente. O Claude sabe que o skill existe e quando usá-lo, mas só puxa o conteúdo completo no momento do uso.

No caso da Ascent, criei o skill ascent-design-system. Qualquer agente que vai produzir artefato com a marca invoca esse skill primeiro. O skill baixa o DESIGN_SYSTEM.md via gh api (o repositório é privado), cacheia localmente, e o agente lê o arquivo antes de escrever uma única palavra.

Isso é governança de marca por infraestrutura, não por briefing verbal.

O que a W3C e a comunidade de design tokens têm a dizer

Em outubro de 2025, o W3C Design Tokens Community Group lançou a primeira versão estável da especificação de Design Tokens (2025.10). Esse foi um marco importante: pela primeira vez, há um padrão aberto e estável pra como tokens devem ser definidos e trocados entre ferramentas, codebases e plataformas.

Ferramentas como Style Dictionary e Tokens Studio já suportam o padrão. Adobe, Google, Meta, Figma, Shopify e Salesforce estão entre as organizações que participaram da especificação.

O que isso significa na prática: quando eu uso var(--brand-navy) no DESIGN_SYSTEM.md, não estou inventando nada. Estou seguindo a lógica de token semântico (o token descreve propósito, não valor primitivo) que a comunidade global de design systems convergiu como padrão.

Tokens semânticos vencem nomes primitivos. --color-cta-primary conta mais do que --blue-500. Porque o LLM aprende não só qual cor usar, mas por que essa cor existe.

As três regras que aprendi no processo

Ao longo de construir isso, algumas decisões que pareciam pequenas se provaram críticas.

1. Paleta restrita pra agentes é diferente da paleta completa do produto.

O sistema de design completo da Ascent tem muito mais cores: cyan, aqua, amarelo, violeta. Essas “vozes vivas” existem pra diferentes módulos e contextos. Mas pra agentes, autorizei apenas 4: Navy, Cream, Paper, Emerald. Menos escolhas significam menos chance de erro. Agente que tem 15 cores chuta. Agente que tem 4 cores acerta.

2. Dois modos de voz, nunca misturados.

Aprendi na marra que a marca fala de dois jeitos completamente diferentes. No Instagram, no blog e nos anúncios: modo fundador (1ª pessoa, “eu, minha, comigo, te conto”). No site, na landing e nos documentos técnicos: modo institucional (3ª pessoa, “a Ascent, nós, nosso”). Misturar os dois no mesmo bloco de copy soa esquizofrênico. Formalizei isso no DESIGN_SYSTEM.md §3 com tabela de decisão por canal, exemplos canônicos e lista de Do/Don’t.

3. O arquivo precisa ser a single source of truth, não uma referência entre várias.

Se o DESIGN_SYSTEM.md é uma referência entre várias, o agente chuta qual prevalece. Quando eu digo que o arquivo é a fonte canônica (com hierarquia explícita: tokens.css acima de DESIGN_SYSTEM.md, acima do PDF antigo, acima de interpretação livre), o comportamento dos agentes muda. Eles param de inventar e começam a consultar.

Insights-chave

  • Design system como infraestrutura operacional: não é um artefato de comunicação interna. É o único arquivo que todos os agentes precisam ler antes de produzir qualquer coisa com a marca.
  • Tokens semânticos fecham o espaço de fabricação: LLMs fabricam valores onde não encontram regras. var(--brand-navy) não deixa espaço pra erro; “tom azul escuro” deixa.
  • Paleta restrita pra agentes: autorize menos cores do que o sistema completo tem. O agente com 4 cores é mais consistente do que o agente com 15.
  • Dois modos de voz com tabela de decisão por canal: redes sociais e blog usam o modo fundador (1ª pessoa); site, doc e landing usam o modo institucional (3ª pessoa). Nunca misturar num mesmo bloco.
  • Skills como governança de marca: transformar o DESIGN_SYSTEM.md num Skill do Claude Code garante que o conteúdo carrega só quando necessário e que qualquer agente novo herda as regras automaticamente.

Aplicação prática

Se tu quer fazer o mesmo, o processo é direto:

Passo 1. Reunir o material bruto. Junta tudo que documenta a tua marca, mesmo que implicitamente: repositório de código com CSS/tokens existentes, identidade visual antiga, posts que tu considera “no ponto”, anotações espalhadas, apresentações, briefings que tu deu verbalmente.

Passo 2. Jogar no Claude Design (ou equivalente multimodal). Sobe o material e pede: “lê tudo isso e me devolve um design system completo, com paleta, tipografia, voz, componentes e regras de aplicação por contexto.” Não escreva um prompt elaborado, deixa o material falar.

Passo 3. Compilar para Markdown. Usa o Claude Code (ou qualquer agente de código) pra ler o projeto gerado e compilar num único DESIGN_SYSTEM.md. Esse arquivo é o que vai junto em cada prompt.

Passo 4. Definir paleta restrita pra agentes. Separa explicitamente no arquivo quais cores são autorizadas pra peças geradas por agentes. Menos é mais.

Passo 5. Documentar os dois modos de voz. Escreve no arquivo, com exemplos canônicos, tabela de decisão por canal e lista de Do/Don’t. Isso é o que vai conter as alucinações de voz.

Passo 6. Transformar em Skill. Se tu usa Claude Code, cria um Skill que aponta pro arquivo. Qualquer agente novo herda as regras sem precisar de briefing manual.

Passo 7. Manter com datas absolutas. Toda vez que o sistema evoluir, atualiza o arquivo com versão e data. O meu hoje está na v1.3, datado de 2026-04-24. Agentes precisam saber qual versão estão lendo.

Como tu documenta a tua marca pra IA hoje? Ainda PDF na pasta do Drive ou já compilou em .md? Comenta no Discord.