Como padronizar botões, erros e estados vazios na skill de design do Claude Code?

Fala aí, beleza? A tela sai bonita, o espaçamento fecha, o componente responde direitinho

e aí você lê os textos: botão "Enviar", mensagem de erro "Algo deu errado" e uma tela vazia que só sabe dizer "Nenhum item encontrado"

Esse é o ponto cego mais comum de quem já tem uma skill de design rodando: as regras cobrem cor, tipografia e layout, e o texto da interface fica solto, no chute do modelo

O conserto não é pedir de novo no chat a cada tela ("agora melhora os textos, por favor"), porque isso não gruda: some na próxima sessão

O conserto é escrever microcopy como REGRA dentro do SKILL.md, do mesmo jeito que você escreveu as regras visuais

Bora ver como fica na prática?

O que você precisa antes de começar

Pouca coisa, na real

• Claude Code instalado e um projeto aberto
• uma decisão de escopo: skill pessoal em ~/.claude/skills/<nome>/ ou skill do projeto em .claude/skills/<nome>/
• um SKILL.md dentro dessa pasta, que é frontmatter YAML delimitado por --- mais o corpo em markdown com as instruções

A decisão de escopo importa mais do que parece, porque muda quem herda as regras de texto

Regra pessoal vale pra tudo que você tocar na sua máquina, regra de projeto viaja no repositório junto com o código

Se você ainda está na dúvida entre reaproveitar a skill em vários projetos ou manter uma cópia por repositório, resolve isso antes de escrever a seção de copy, senão você escreve duas vezes

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Como o Claude decide ler a sua skill:

Aqui tem um detalhe que muda o jeito de escrever o arquivo

Na inicialização o Claude lê APENAS o name e o description de cada skill

O conteúdo completo do SKILL.md só entra no contexto quando a skill combina com a tarefa (é o tal do carregamento em estágios, progressive disclosure)

Ou seja: o corpo pode ser detalhado, mas o description é o porteiro

"E se o arquivo crescer demais?" A documentação de boas práticas recomenda manter o corpo do SKILL.md abaixo de 500 linhas e dividir o excedente em arquivos separados

Esses arquivos de apoio ao lado do SKILL.md (markdown de referência, exemplos, templates, scripts) são opcionais e só são carregados quando o próprio SKILL.md os referencia

Isso é ótimo pra copy, porque exemplo bom de microcopy é longo por natureza

Duas leituras oficiais antes de escrever a sua:

Antes de inventar do zero, vale abrir duas coisas que a Anthropic mantém no aberto

A primeira é o SKILL.md da skill frontend-design, que serve de referência de estrutura: dá pra ver como uma skill de design de verdade é organizada

A segunda é a skill ux-copy, dentro do plugin design do knowledge-work-plugins, que existe justamente pra escrever ou revisar copy de interface: microcopy, mensagens de erro, estados vazios e CTAs

Se você ainda está decidindo se essas regras moram numa skill ou no CLAUDE.md, esse post resolve a escolha antes de você duplicar instrução em dois lugares

Passo a passo: adicionar a seção de copy na skill de design

1. Escolha o escopo e crie a pasta da skill

Uma pasta por skill, com o SKILL.md dentro

# skill do projeto (vai junto no repositório)
mkdir -p .claude/skills/design-do-produto

# ou skill pessoal (vale pra qualquer projeto seu)
mkdir -p ~/.claude/skills/design-do-produto

O erro comum deste passo: jogar o arquivo solto numa pasta qualquer, ou criar a skill no escopo pessoal quando o time inteiro precisava herdar as mesmas regras de texto

2. Escreva o frontmatter dizendo que a skill também cuida de texto

Os campos name e description são os metadados obrigatórios do frontmatter

E o description é o texto que o Claude compara com o pedido do usuário pra decidir se aciona a skill, então ele precisa dizer o que a skill faz E quando usar

Se o seu description só fala de "componentes e visual", adivinha o que acontece quando o pedido é "revisa as mensagens de erro dessa tela"? A skill não acorda

---
name: design-do-produto
description: Cria e revisa interface do produto, incluindo o texto da interface (rótulo de botão, mensagem de erro, estado vazio e CTA). Use quando o pedido envolver criar tela, revisar componente ou escrever microcopy.
---

O erro comum deste passo: description vago do tipo "ajuda com design", que não dá pro modelo nenhum gancho pra acionar a skill na hora certa

3. Defina voz, tom e os princípios da copy

Essa é a primeira parte da seção nova

A skill frontend-design já recomenda registro conversacional, verbos simples, sentence case, sem enchimento e tom ajustado à marca e ao público

A ux-copy trabalha com quatro princípios: claro (sem jargão nem ambiguidade), conciso (o menor número de palavras que transmite o sentido), consistente (mesmos termos pras mesmas coisas) e útil (cada palavra ajuda o usuário a concluir a tarefa)

Junta os dois e você já tem a espinha da sua seção, sem precisar inventar filosofia nova

O erro comum deste passo: escrever adjetivo em vez de regra. "Tom amigável e moderno" não é instrução, é decoração: o modelo não consegue verificar se cumpriu

4. Regra de rótulo de botão: começa por verbo

A ux-copy define que rótulo de botão começa com verbo, com exemplos do tipo Start free trial, Save changes e Download report

É a regra mais barata de todas e a que mais muda o resultado, porque mata o "Enviar", o "OK" e o "Continuar" genéricos de uma vez

Na sua skill, troque os exemplos pelo vocabulário do SEU produto: se no seu app a pessoa não "salva", ela "publica", o exemplo tem que dizer publica

O erro comum deste passo: escrever a regra e não escrever o exemplo. Regra sem exemplo o modelo interpreta do jeito dele, e aí volta "Enviar formulário"

5. Regra de mensagem de erro em três partes

Aqui mora o "Algo deu errado"

A ux-copy define que a mensagem de erro explica o que deu errado, de quem é a responsabilidade e qual o próximo passo, sem culpar o usuário

E a frontend-design vai na mesma direção quando trata erro como momento de direção: explicar o que aconteceu e como resolver, na voz da interface, com erro que não pede desculpa e nunca é vago

Três partes, sempre. Se faltar o próximo passo, o texto virou aviso, não ajuda

O erro comum deste passo: deixar a regra genérica ("mensagens de erro devem ser claras") em vez de fixar o FORMATO em três partes, que é o que dá pra conferir depois

6. Regra de estado vazio: orientar, explicar, oferecer o próximo passo

Estado vazio é a tela mais esquecida do produto e a mais fácil de padronizar

A ux-copy define o estado vazio em três partes também: orienta o usuário, explica por que a tela está vazia e oferece um próximo passo

A frontend-design trata a tela vazia como convite à ação, na mesma linha

Ou seja: nada de "Nenhum item encontrado" sozinho no meio da tela

O erro comum deste passo: confundir estado vazio de primeira vez (a pessoa ainda não criou nada) com estado vazio de filtro (existe conteúdo, mas a busca não achou). São textos diferentes, escreva os dois na regra

7. Escreva a lista do que evitar

A frontend-design tem um recurso que vale roubar: uma lista explícita de padrões a evitar dentro do próprio SKILL.md

No visual, ela cita fontes batidas (Inter, Roboto, Arial, fontes do sistema), esquemas de cor clichê como gradiente roxo em fundo branco e layouts previsíveis

Faça o mesmo com texto, porque proibição explícita funciona melhor do que só o exemplo bom

O erro comum deste passo: listar só o que fazer. O modelo tende ao caminho mais provável do treino, e o caminho mais provável é justamente o texto genérico que você quer matar

8. Mande exemplo longo pra um arquivo de apoio

Quando a seção de copy começar a virar um catálogo (dez exemplos de erro, oito de estado vazio, glossário de termos do produto), tira do SKILL.md

Cria um arquivo ao lado e referencia ele no corpo

.claude/skills/design-do-produto/
  SKILL.md
  copy-exemplos.md

Assim o corpo fica abaixo das 500 linhas recomendadas e o arquivo extra só é carregado quando o SKILL.md aponta pra ele

O erro comum deste passo: criar o arquivo de apoio e esquecer de citar ele no SKILL.md. Arquivo não referenciado não é carregado, e você fica achando que a regra está valendo

Outro tropeço frequente por aqui: mexer no allowed-tools do frontmatter achando que vale em todo lugar. Esse campo só é suportado na CLI do Claude Code e não se aplica quando a skill roda pelo SDK

O modelo de seção de copy pra colar no SKILL.md:

Se liga nisso: esse bloco vai no CORPO do arquivo, depois do frontmatter

Não existe campo de frontmatter dedicado a microcopy, é conteúdo markdown normal mesmo

## Texto de interface (copy)

### Voz e tom
- Registro conversacional, verbos simples, sentence case
- Sem enchimento: se a palavra sai e a frase continua clara, ela sai
- Tom ajustado à marca e ao público do produto

### Princípios
- Claro: sem jargão nem ambiguidade
- Conciso: o menor número de palavras que transmite o sentido
- Consistente: mesmos termos para as mesmas coisas em todas as telas
- Útil: cada palavra ajuda o usuário a concluir a tarefa

### Rótulo de botão
- Começa por verbo, sempre
- Diz a ação que vai acontecer, não a mecânica do sistema
- Bom: "Salvar alterações", "Baixar relatório", "Publicar página"
- Ruim: "Enviar", "OK", "Continuar", "Confirmar"

### Mensagem de erro (três partes, sempre)
1. O que deu errado, em linguagem do usuário
2. De quem é a responsabilidade (sem culpar o usuário)
3. Qual o próximo passo, com a ação disponível ali
- Não pede desculpa e nunca é vaga
- Ruim: "Algo deu errado", "Erro inesperado", "Falha na operação"

### Estado vazio (três partes, sempre)
1. Orienta: diz o que essa tela mostra quando tem conteúdo
2. Explica por que ela está vazia agora
3. Oferece o próximo passo, com um botão que começa por verbo
- Vazio de primeira vez e vazio de filtro são textos diferentes

### Evitar
- Erro vago, erro que pede desculpa, erro sem próximo passo
- Jargão técnico e nome interno de sistema vazando pra tela
- Palavra de enchimento ("simplesmente", "apenas", "por favor")
- Termos trocados para a mesma coisa ("projeto" numa tela, "workspace" na outra)
- Estado vazio que só informa a ausência

### Vocabulário do produto
- (liste aqui os termos oficiais do seu produto e os proibidos)

Exemplos completos em copy-exemplos.md

Ajustou os exemplos pro seu produto? Então pede uma tela nova e compara com a de ontem, a diferença aparece no primeiro botão 🙂

Aproveitar as skills oficiais em vez de escrever tudo do zero

Você não precisa começar da página em branco, e às vezes nem precisa escrever skill nenhuma

Existem três caminhos, e eles não competem tanto quanto parece

Caminho 1: instalar o plugin oficial Frontend Design

O plugin Frontend Design é mantido pela Anthropic e está publicado no marketplace oficial claude-plugins-official

/plugin install frontend-design@claude-plugins-official

O Claude Code adiciona esse marketplace automaticamente na primeira execução interativa

"E se ele não entrar sozinho?" Aí você adiciona na mão:

/plugin marketplace add anthropics/claude-plugins-official

Pra fuçar o catálogo de dentro do Claude Code, roda /plugin e abre a aba Discover (o catálogo também está no site, em claude.com/plugins)

Esse caminho já te dá as diretrizes de voz e tom e o tratamento de erro e vazio como momento de direção, sem você escrever uma linha

Caminho 2: instalar o plugin design pela skill ux-copy

A Anthropic mantém a skill ux-copy dentro do plugin design, no repositório knowledge-work-plugins, junto com outras skills de design (accessibility-review, design-critique, design-handoff, design-system, research-synthesis e user-research)

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install design@knowledge-work-plugins

Detalhe importante: esse plugin foi pensado principalmente para o Claude Cowork, mas também funciona no Claude Code

É dele que saem os quatro princípios, o formato de erro em três partes e a regra do rótulo por verbo que você viu ali em cima

Caminho 3: copiar a estrutura pra uma skill própria

Esse é o caminho que a maioria dos produtos acaba tomando, e é o que o modelo lá de cima resolve

Você pega a estrutura das skills oficiais e troca os exemplos pelo vocabulário do SEU produto, com os termos que o seu usuário usa e os que você proibiu

Nenhum plugin genérico sabe que no seu app é "espaço" e não "workspace", isso só existe se você escrever

Dá pra combinar, inclusive: instala o oficial pra ter a base e mantém uma skill do projeto só com o vocabulário e as exceções da sua casa

Conclusão

Texto de interface só fica previsível quando vira regra escrita

Enquanto for pedido repetido no chat ("melhora esses textos", "esse erro ficou vago"), você vai reescrever a mesma coisa na próxima tela, e na próxima sessão, e no próximo projeto

Dentro do SKILL.md a regra viaja junto: o description aciona, o corpo entra no contexto quando combina com a tarefa e o exemplo longo fica no arquivo de apoio

Próximo passo bem objetivo pra hoje: abre o SKILL.md da sua skill de design, cola o modelo de seção de copy, ajusta os rótulos e as mensagens pro vocabulário do seu produto e pede uma tela nova

Olha o primeiro botão que aparecer

Se ele começar com verbo e o estado vazio te oferecer um caminho, a regra pegou 😀

até o próximo post!