Dê um design system ao Bolt

De acordo com a documentação do Bolt, um design system fornece ao Bolt um conjunto de regras visuais (cores, tipografia, espaçamento, estilos de componentes) para seguir durante a construção. O benefício declarado é que o Bolt gera código de UI baseado em seus componentes reais, em vez de um código provisório que você teria que substituir depois.

Existem dois níveis, e a diferença é importante antes de você planejar sua estratégia:

Os sistemas pré-carregados são uma maneira genuinamente boa de ver a diferença que um sistema faz: escolha um, clique em *Try example* e compare a qualidade do resultado com um prompt simples. O que você não pode fazer é adaptá-lo à sua marca, pois eles são apenas para leitura. No momento em que você precisar de um visual próprio, terá que escolher entre um plano Team e o terminal.

O modelo do Bolt é de compilação, não de upload. Sua documentação afirma que o Bolt compila seu design system a partir de suas próprias fontes, sua biblioteca de componentes e seu site de design system, e que seu design system *é definido por essas fontes*. Quando as fontes mudam, você sincroniza o Bolt para capturar a versão mais recente.

Este é um modelo limpo com uma consequência que as pessoas percebem mais tarde: o sistema compilado é um snapshot. Entre as sincronizações, o Bolt gera a partir de uma versão do seu sistema que pode não corresponder mais ao que foi publicado. Este é o modo de falha que as equipes de design system já conhecem como token drift — quando a fonte da verdade projetada e a publicada divergem — e um agente que gera com confiança a partir de uma cópia obsoleta produz código pronto para produção sobre a base errada, e mais rápido do que antes. Coloque a sincronização no seu checklist de release, não no seu backlog de manutenção.

O Bolt não é incomum ao precisar de fontes para compilação. Verificamos a documentação atual de cada grande construtor de IA e agente de código, e a estrutura é a mesma em todos eles.

Se você mantém uma biblioteca de componentes e um site de documentação, o compilador do Bolt é a ferramenta certa e você deve assinar o plano Team. Se o seu design system é atualmente "o que quer que o Bolt tenha feito na primeira tela", não há nada para compilar, e o restante desta página é a resposta prática.

O Bolt é um StackBlitz WebContainer, o que significa que ele executa um ambiente Node real com um terminal real no navegador. Quase nenhum outro nesta categoria faz isso. Você pode instalar pacotes, executar geradores e escrever arquivos, portanto, um design system é instalado exatamente como seria na sua máquina, sem restrição de plano e sem etapa de compilação.

1. 1

   Certifique-se de que o projeto use shadcn/ui

   Os starters de React + Tailwind do Bolt funcionam bem. Se o projeto ainda não foi inicializado com shadcn, execute npx shadcn@latest init no terminal do Bolt primeiro.

2. 2

   Instale o conjunto de tokens

   Execute o comando de registro do kit no terminal do Bolt. Ele grava cada função semântica, light e dark, no seu tema, para que componentes que já referenciam bg-primary sejam repintados sem precisar de edição.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

3. 3

   Coloque o brief no repo, não no chat

   Esta é a etapa que as pessoas pulam. A CLI grava um arquivo DESIGN.md completo no projeto, para que as regras sobrevivam a um novo chat, a um reload e à próxima pessoa que abrir o projeto.

   Copy

   npx --yes identityforge@latest apply ambient-sage

4. 4

   Faça prompts baseados no sistema

   Agora faça o build normalmente e nomeie a restrição explicitamente nas primeiras vezes.

   Copy

   Build a landing page using only the theme's design tokens
   and the rules in DESIGN.md. Do not add a new colour or font.

Isso surge todas as vezes, e é um instinto razoável. O repo é a fonte da verdade, então aponte o agente para ele. Dois pontos atrapalham isso.

O primeiro é prático: um repositório não é um design system em um formato que um agente consiga aplicar. São milhares de arquivos, a maioria irrelevante para uma decisão de estilização, com as regras reais distribuídas em uma config do Tailwind, um theme provider, alguns arquivos CSS e a memória coletiva da equipe. A compilação existe precisamente porque algo precisa reduzir isso a tokens, um catálogo de componentes e um conjunto de restrições.

O segundo é que um repo responde *o que existe* e não *o que fazer*. Ele contém um Button com cinco variantes; ele não diz qual variante uma ação destrutiva recebe, que você nunca coloca dois destaques em uma tela, ou o que acontece no dark mode em uma superfície que ainda não tem variante dark. Esses são julgamentos, eles vivem em prosa e, se ninguém os escreveu, o agente fornecerá os seus próprios: de forma plausível, mas diferente a cada vez.

Analisamos 299 arquivos DESIGN.md públicos para ver com que frequência esses julgamentos são escritos. 76% listam apenas preferências e nunca uma proibição. 69% nunca mencionam dark mode. 86% fornecem valores hexadecimais brutos sem nenhuma função semântica atrelada, o que significa que a pergunta "qual a cor de um botão desativado" não tem resposta no arquivo.

Portanto: vincule o repositório se a ferramenta suportar, mas ainda assim escreva as regras. O que um arquivo completo contém está em o que é um DESIGN.md.

Se você está seguindo a rota nativa e se pergunta se deve fornecer ao Bolt um pacote npm, uma estrutura de pastas ou um link de documentação, a resposta honesta é que depende de qual ferramenta você está alimentando, e as ferramentas genuinamente divergem:

• Bolt compila a partir da sua biblioteca de componentes e do seu site de design system, e sincroniza novamente quando eles mudam.
• v0 deseja um pacote instalável: npm, um .tgz ou um diretório de origem com seu próprio package.json, e criará um a partir de fontes menos estruturadas caso você não o tenha.
• Lovable deseja componentes React, entregues como um projeto Lovable dedicado, e os copia para os repositórios conectados.
• Agentes de código não querem nenhum dos dois: eles querem um arquivo de tokens e um briefing escrito dentro do repositório.

O único artefato que os quatro aceitam é o par para o qual todos eles acabam reduzindo de qualquer maneira: um conjunto completo de tokens semânticos e as regras escritas que o acompanham. Produzir isso primeiro não custa nada se você publicar um pacote posteriormente, e é a única versão que funciona hoje em um plano gratuito.

O item do registro em https://identityforge.io/r/<slug>.json contém cada papel semântico, portanto o Bolt nunca improvisa os valores que uma paleta solta deixa indefinidos: texto suavizado, bordas, estados de hover e active, ring, destructive, séries de gráficos e todos eles novamente no dark mode. Entregar três cores de marca define três valores e deixa cerca de vinte e cinco abertos. Veja tokens de cores semânticas explicados.

• Deixar o briefing no chat. Builds longos cortam o contexto. Um DESIGN.md no projeto não é cortado.
• Assumir que um sistema pré-carregado pode ser ajustado para a sua marca. Eles são, por design, apenas para leitura.
• Sincronizar apenas quando algo parece errado. A essa altura, o Bolt já está gerando a partir de um snapshot desatualizado há semanas.
• Dar cores ao Bolt sem papéis. Uma paleta não consegue responder como deve ser um controle desativado, então o Bolt escolhe: de forma diferente em cada tela.
• Ignorar o dark mode. Ele não é uma inversão do light mode, e é onde a improvisação aparece primeiro.