A habilidade de design de frontend do Claude Code: o que ela faz e onde ela falha

Uma habilidade é um conjunto de instruções que é carregado quando é relevante, em vez de em cada requisição — a metade sob demanda da stack de arquivos do agente. A habilidade de design de frontend é carregada quando você solicita trabalho de UI e direciona o modelo para padrões (defaults) mais robustos.

Na prática, as diferenças que aparecem com mais consistência são estas, e são reais, não apenas cosméticas:

• O espaçamento ganha ritmo. Os valores passam a vir de uma escala em vez de serem escolhidos por elemento, fazendo com que o ritmo vertical se mantenha em toda a página.
• A hierarquia torna-se deliberada. Tamanho, peso e cor são usados em conjunto para separar níveis, em vez de usar apenas o tamanho.
• Menos layouts com aparência genérica. A grade reflexiva de três cards iguais aparece com menos frequência quando o conteúdo não sugere, de fato, três elementos equivalentes.
• Estados são tratados. Hover, focus, disabled e erro aparecem sem que sejam solicitados, que é onde a maioria dos componentes gerados é deficitária.

Esse é um salto significativo e é a razão pela qual a habilidade vale a pena ser instalada. É também todo o escopo dela.

Uma habilidade carrega o *como decidir*. Ela não carrega *o que foi decidido*. Essa distinção parece acadêmica até que você observe duas sessões lado a lado.

A habilidade dirá consistentemente ao modelo que uma ação primária precisa de contraste suficiente em relação à sua superfície e não deve competir com uma secundária. Ela não tem como saber que a sua cor primária é oklch(0.55 0.19 45) — porque você nunca disse a ela, e não há lugar em uma habilidade para que isso resida. Então, ela escolhe algo justificável. Na próxima sessão, ela escolhe outra coisa justificável.

Não aceite isso cegamente — o teste é curto e o resultado é inequívoco.

1. 1

   Peça um card de preços em uma sessão nova

   Com a skill ativa e sem um design system presente. Guarde o resultado.

2. 2

   Inicie uma sessão genuinamente nova

   Não apenas uma nova mensagem — uma nova sessão, para que nada seja transferido.

   Copy

   claude

3. 3

   Peça um painel de configurações para o mesmo produto

   Use a mesma descrição sobre o produto, sem referenciar o primeiro componente.

4. 4

   Compare a diferença entre os dois

   Compare a cor primária, o border radius, o tamanho da fonte base e o espaçamento vertical entre o label e o controle.

5. 5

   Analise o resultado honestamente

   Ambos parecerão competentes. Em nossos testes, três ou quatro desses quatro valores divergem — e cada um, individualmente, é uma escolha razoável.

Mantenha a skill. Ela faz um trabalho que nada mais faz. Adicione a camada que ela não consegue conter: um conjunto de tokens mais um DESIGN.md no repo, que o agente lê no início de cada sessão.

A divisão de trabalho fica clara quando ambos estão implementados. O arquivo responde *qual* azul, *qual* radius, *qual* escala tipográfica. A skill responde como compô-los em uma tela que tenha boa leitura. Um não substitui o outro, e o erro comum é assumir que a skill tornou o arquivo desnecessário.

1. 1

   Instale um kit no repo

   Isso escreve o DESIGN.md e os arquivos de tokens que seu agente irá ler.

   Copy

   npx --yes identityforge@latest install --client claude-code

2. 2

   Aplique o kit desejado

   Kits gratuitos não exigem conta.

   Copy

   identityforge apply ambient-sage

3. 3

   Point AGENTS.md at it

   Uma única linha, para que o contrato de design seja descoberto deliberadamente, e não por acaso.

   Copy

   Never hardcode theme colors. Use the semantic tokens in DESIGN.md.

4. 4

   Execute novamente o teste de duas sessões

   Mesmo procedimento de cima. Os valores agora devem coincidir exatamente, pois são lidos em vez de serem decididos novamente.

Esta é a pergunta que as pessoas realmente fazem sobre skills de design, e quase nada do que foi escrito sobre elas a responde. A resposta honesta: uma skill respeita seu tema apenas na medida em que seu tema existe como valores que ela possa ler. Uma skill consiste em instruções sobre como trabalhar. Ela não é a fonte dos seus valores.

Essa distinção define o resultado em uma base de código existente:

Existe uma versão mensurável disso. Analisamos 299 arquivos DESIGN.md públicos e descobrimos que, dos 72 que descreviam um sistema visual, 86% não usavam nomes de funções de cores semânticas — eles listavam hexes ou nomeavam cores por matiz. Uma skill que recebe --primary pode aplicar seu sistema a um componente que ninguém descreveu. Uma skill que recebe uma tabela de hexes consegue apenas copiar, e é na cópia que ela começa a adivinhar.

1. 1

   Verifique se o seu tema é legível

   Procure por um DESIGN.md ou um arquivo de tokens na raiz do repositório. Se a única fonte for o Figma, a skill não terá base para trabalhar.

2. 2

   Torne os valores semânticos

   Use funções em vez de matizes, para que a skill possa posicioná-los corretamente em casos que você nunca documentou.

3. 3

   Referencie-os no AGENTS.md como uma proibição

   Copy

   Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

4. 4

   Execute a mesma build em uma nova sessão

   O mesmo primary e o mesmo raio significam que ela está lendo. Aproximações significam que ela está lembrando, e a memória degrada.

A maior parte do conteúdo sobre isso são listas, e essas listas usam os três termos indistintamente. Eles não são a mesma coisa, e a diferença define se o que você instalou consegue sequer ser carregado.

A consequência prática é a condição de carregamento. Uma skill é selecionada pelo modelo com base em sua descrição, portanto, ela só atua quando sua solicitação parece um trabalho de design. Peça "uma página de configurações" e ela será acionada. Peça para "corrigir o padding na linha 40" e ela pode não ser, pois isso parece uma edição e não uma tarefa de design — e você receberá uma edição comum, sem o refinamento técnico pelo qual instalou a skill.

Esta é a pergunta que as análises comparativas ignoram completamente, e é a que importa quando você tem ambos. Eles conflitam porque são escritos por pessoas diferentes para propósitos diferentes. Seu arquivo diz que a cor primária é oklch(0.55 0.19 45). O julgamento da skill diz que uma cor primária precisa superar um limite de contraste em relação à superfície onde está. Em um card claro, eles concordam. Em sua superfície escura elevada, podem não concordar.

Nenhuma das camadas está errada e não há um árbitro nativo — o modelo resolve a questão e, por padrão, prioriza a instrução que for mais específica e lida mais recentemente. É por isso que a resolução deve ser documentada em vez de presumida:

1. Valores não são negociáveis; a composição sim. Declare isso no AGENTS.md. O hex, o radius e a escala tipográfica vêm do arquivo. Como eles são organizados na tela é decisão da skill.
2. Dê ao arquivo a saída de emergência que a skill precisa. O conflito acima só existe porque o sistema tem apenas uma cor primária. Forneça uma primária que seja legível também em suas superfícies escuras, ou um par documentado, e a divergência desaparece em vez de ser julgada a cada sessão.
3. Escreva proibições, não preferências. "Prefira tokens semânticos" perde para um argumento específico de contraste. "Nunca use cores de tema hardcoded" não perde, pois não deixa margem para ponderação.
4. Espere silêncio em caso de conflito. O modelo não avisará que sobrescreveu seu token. A única detecção confiável é fazer um grep no diff em busca de valores literais de cor e espaçamento.

# the only conflict detector that actually fires: literals in the diff
git diff | grep -nE '#[0-9a-fA-F]{3,8}|oklch\(|rgb\(|[0-9]+px'

Execute isso em cada diff gerado por um agente. Um resultado limpo significa que os valores foram lidos. Qualquer retorno é um ponto onde o julgamento substituiu silenciosamente uma decisão que você já havia tomado — que é a mesma deriva do teste de duas sessões, apenas chegando por outra porta.