Como descrever uma tela no prompt do Claude Code quando você não tem design?

Você pede uma tela, o Claude entrega algo plausível, e aí começa a novela do "na verdade eu queria assim"

Rodada de ajuste visual atrás de rodada de ajuste visual, a tela até fica boa, mas você gastou mais tempo corrigindo do que gastaria desenhando

E quase nunca o problema é o modelo

O problema é a descrição

Quando não existe design, nem Figma, nem rabisco no papel, o prompt vira o ÚNICO alvo que o Claude tem pra mirar. E a Anthropic é bem direta nisso: o desempenho melhora quando existe um alvo explícito pra iterar contra, seja um mock visual, um caso de teste ou outro tipo de saída esperada

Sem alvo, ele chuta plausível

Então a saída não é escrever prompt maior, é escrever prompt com as camadas certas. É isso que vem aqui: um roteiro pra transformar uma ideia de interface em texto, camada por camada, incluindo o que quase todo mundo esquece (o que aparece vazio, o que aparece carregando e o que aparece em erro) 🙂

O que ter em mãos antes de escrever o prompt

Lista curta, sem enrolação:

• Claude Code instalado e o projeto aberto na pasta certa
• Uma noção clara do que a tela precisa resolver, não do componente que você quer usar
• Um CLAUDE.md de projeto, que pode viver em ./CLAUDE.md ou em ./.claude/CLAUDE.md

O terceiro item é o que mais muda o resultado aqui, e vale explicar o porquê

O CLAUDE.md de projeto é onde ficam as instruções que valem pra qualquer pessoa que mexe no repo: comandos de build e teste, padrões de código, decisões de arquitetura, convenções de nome, fluxos comuns

E esse arquivo entra no prompt do Claude

Ou seja: se as suas convenções de componente e nomenclatura já estão lá, você não precisa repetir nada disso na descrição da tela. Seu prompt fica livre pra falar SÓ de interface, que é o assunto difícil

Não tem CLAUDE.md ainda? O comando /init gera um inicial analisando o próprio código do projeto

/init

Tome cuidado com um detalhe: o CLAUDE.md faz parte do prompt, então ele precisa ser refinado como qualquer prompt que você usa muito. O erro comum é ir empilhando conteúdo ali sem nunca testar se aquilo está fazendo efeito, até o arquivo virar um depósito

Pode, poda e testa

Esse mesmo raciocínio de instrução fixa aparece quando você quer manter o padrão das suas notas com o Claude escrevendo no seu lugar: a regra mora no arquivo, não no prompt do dia

Formação Recomendada

Formação Claude Code

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

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Passo a passo: transformando uma ideia de tela em texto

A ideia é simples: a tela tem um objetivo (o cabeçalho da descrição) e CINCO camadas embaixo dele (hierarquia, cheio, vazio, carregando, erro)

Se uma dessas camadas fica vaga, é exatamente ali que o vaivém acontece depois

1. Declare o objetivo da tela e quem usa ela

Antes de qualquer campo, diga qual tarefa a pessoa está tentando terminar nessa tela

Tela: acompanhamento de pedidos do dia
Quem usa: operador de loja, no desktop, olhando a tela o dia inteiro
Tarefa: descobrir em segundos quais pedidos estão atrasados e agir neles

O erro comum deste passo: começar pelo componente ("quero uma tabela com sidebar") em vez da tarefa. Quando você entrega o componente pronto, o Claude só monta a casca e a tela não resolve nada

2. Escreva a hierarquia em ordem de importância, do topo pra baixo

Não basta listar o que existe, tem que dizer o PESO de cada coisa: o que é primário, o que é secundário e o que pode ficar escondido atrás de um clique

Hierarquia (do mais importante pro menos):
1. Primário: contador de pedidos atrasados, grande, no topo
2. Primário: lista dos pedidos atrasados, um por linha
3. Secundário: filtro por status e por período, acima da lista
4. Secundário: total de pedidos do dia, discreto, ao lado do contador
5. Escondido: exportar CSV e configurações, dentro de um menu

O erro comum deste passo: listar os campos sem dizer o peso de cada um. Sem peso, tudo vira o mesmo tamanho e você recebe uma tela plana, onde nada chama atenção

3. Descreva o estado cheio com dados de exemplo CONCRETOS

Nada de "uma lista de itens"

Escreva as linhas de verdade, com o formato real, os tamanhos reais e o pior caso que você espera

Estado cheio, exemplo de 3 linhas:
#4821 | Maria Aparecida de Souza Nascimento | valor alto, com centavos | atrasado 2h
#4822 | João Lima | valor curto, de dois dígitos | atrasado 15min
#4823 | Restaurante Cantinho do Chef Ltda | valor com cinco dígitos | atrasado 4h
Nome longo não pode quebrar a linha, corta com reticências
Valor sempre alinhado à direita

O erro comum deste passo: placeholder genérico. "Lorem ipsum" e "Item 1, Item 2" escondem justamente os casos que quebram o layout (nome gigante, valor com cinco dígitos, texto vazio)

4. Descreva o estado vazio com causa e próxima ação

A orientação da NN/g pra estado vazio é clara: explique por que não há dados e diga o que a pessoa pode fazer, ou em que circunstância os dados apareceriam, em linguagem simples

Estado vazio (nenhum pedido atrasado):
Título: Nenhum pedido atrasado agora
Texto: Os pedidos aparecem aqui assim que passarem do prazo de preparo
Ação: botão secundário "Ver todos os pedidos do dia"

O erro comum deste passo: escrever só "nenhum resultado" e parar por aí. Isso deixa a pessoa sem saber se a tela quebrou, se o filtro está errado ou se está tudo certo mesmo

5. Descreva o carregamento escolhendo o indicador pela duração esperada

Aqui tem régua pronta, não precisa achismo

A NN/g trabalha com três limites de tempo de resposta em design de interação: 0,1 segundo passa a sensação de resposta instantânea, 1 segundo mantém o fluxo de pensamento da pessoa e 10 segundos é o limite da atenção

E a recomendação de indicador segue essa régua:

E o skeleton? O Carbon Design System define skeleton como a versão básica de um componente sem conteúdo, exibida no carregamento INICIAL, e recomenda que ele fique poucos segundos até ser substituído pelo conteúdo real

Tem também a lista do que nunca deve virar skeleton: toast, menu de overflow, item de dropdown, modal e loader. Os elementos DENTRO do modal podem ter skeleton, o modal em si não

Estado carregando:
Carga inicial da lista: skeleton de 5 linhas, some assim que os dados chegam
Refiltro (espera curta, 2 a 9 s): indicador em loop no topo da lista
Exportar CSV (10 s ou mais): indicador de porcentagem concluída
O modal de exportação não tem skeleton, só o conteúdo dentro dele

O erro comum deste passo: usar spinner pra tudo, ou deixar skeleton piscando em cada refiltro. Skeleton é boas-vindas, não é resposta de interação

6. Descreva o estado de erro em linguagem simples

A orientação da NN/g pra mensagem de erro é linguagem simples (sem códigos), apontar o problema com precisão e sugerir uma solução de forma construtiva

Estado de erro:
Falha ao carregar os pedidos:
  Texto: Não conseguimos carregar os pedidos agora
  Solução: botão "Tentar de novo", e aviso de que o último dado é de HH:MM
Falha ao exportar:
  Texto: A exportação não terminou porque o período selecionado é muito grande
  Solução: sugerir exportar por semana
Nunca mostrar o retorno cru da API na tela

O erro comum deste passo: repassar a mensagem bruta da API pro usuário. 500 Internal Server Error não diz o problema com precisão e não sugere solução nenhuma, só empurra a culpa pra frente

7. Rode a descrição em plan mode antes de qualquer arquivo ser tocado

Agora que a descrição está inteira, não manda executar direto

O plan mode do Claude Code faz ele pesquisar e PROPOR as alterações sem aplicar: as edições ficam bloqueadas até você aprovar o plano

Pra acionar, tem dois caminhos: Shift+Tab durante a sessão, ou prefixar um único prompt com /plan

/plan Implemente a tela de acompanhamento de pedidos descrita abaixo.
[cola aqui o objetivo + as cinco camadas dos passos 1 a 6]

O Shift+Tab cicla entre os modos de permissão (default, acceptEdits, plan), e apertar de novo SAI do plan mode sem aprovar o plano. Isso é ótimo quando você leu a proposta e não gostou: não precisa aprovar nada pra sair

E ler o plano é justamente o momento de perguntar antes de aceitar, porque depois que a edição acontece o custo de voltar atrás é bem maior

O erro comum deste passo: aprovar o plano no automático, batendo o olho no primeiro parágrafo. Se o plano não menciona os quatro estados, a sua descrição não foi lida do jeito que você acha que foi

Bora ver na prática?

Três telas descritas do zero: dashboard, formulário e lista com filtro

O roteiro é o mesmo nas três, mas o PESO de cada camada muda bastante. Dá uma olhada

Dashboard: a camada que mais pesa é a hierarquia

Dashboard sem hierarquia vira parede de números onde ninguém olha pra nada

Tela: dashboard de vendas do mês
Quem usa: dono da loja, olhada rápida no celular, uma vez por dia
Tarefa: saber em 5 segundos se o mês está bom ou ruim

Hierarquia:
1. Primário: faturamento do mês, número gigante, com variação vs mês anterior
2. Secundário: gráfico de linha dos últimos 30 dias
3. Secundário: 3 cards menores (ticket médio, pedidos, cancelamentos)
4. Escondido: comparativo por canal, atrás de "ver detalhes"

Cheio: faturamento do mês em destaque, com a variação percentual vs mês
  anterior logo abaixo, em verde quando positiva e em vermelho quando negativa
Vazio: mês sem venda nenhuma mostra "Nenhuma venda registrada neste mês" +
  "Os valores aparecem aqui após o primeiro pedido pago"
Carregando: skeleton só na carga inicial dos cards, poucos segundos
Erro: "Não conseguimos atualizar os números agora" + botão de tentar de novo

Formulário: a camada que mais pesa é o erro

No formulário, o estado de erro não é detalhe, é metade da tela

Tela: cadastro de novo produto
Quem usa: quem repõe estoque, no desktop, várias vezes por dia
Tarefa: cadastrar um produto sem precisar refazer tudo por causa de um campo

Hierarquia:
1. Primário: nome, preço, estoque
2. Secundário: categoria, descrição
3. Escondido: SEO, dimensões e peso, dentro de uma seção recolhida

Erro (esta é a camada crítica aqui):
  Erro por campo, ancorado embaixo do campo, não em um alerta no topo
  Preço vazio: "Informe o preço de venda"
  Preço com letra: "Use apenas números, sem letras nem símbolos"
  Nome duplicado: "Já existe um produto com este nome" +
    link "abrir o produto existente"
  Falha ao salvar: mantém TODOS os campos preenchidos e mostra
    "Não conseguimos salvar agora, seus dados continuam aqui"
  Nunca limpar o formulário depois de um erro

Carregando: botão salvar vira estado de espera, formulário fica desabilitado
Vazio: não se aplica, formulário nasce vazio por definição

Lista com filtro: a camada que mais pesa é o vazio

E aqui tem a pegadinha que quase todo mundo passa batido: vazio inicial é uma coisa, vazio por filtro é OUTRA coisa completamente diferente

Tela: lista de clientes com filtro
Quem usa: time de suporte procurando um cliente específico
Tarefa: achar o cliente certo rápido

Vazio inicial (a base ainda não tem cliente nenhum):
  Título: Nenhum cliente cadastrado ainda
  Texto: Os clientes aparecem aqui automaticamente após a primeira compra
  Ação: botão "Cadastrar cliente manualmente"

Vazio por filtro (tem cliente, o filtro é que não achou):
  Título: Nenhum cliente com esses filtros
  Texto: mostrar quais filtros estão ativos, em texto
  Ação: botão "Limpar filtros" (primário)
  Nunca sugerir cadastrar cliente aqui, o problema é o filtro

Carregando: refiltro usa indicador em loop, a lista antiga continua na tela
  em opacidade menor até o novo resultado chegar
Erro: "Não conseguimos aplicar o filtro agora" + botão tentar de novo

Repara que o texto do prompt não é bonito, é ESPECÍFICO

É pra copiar e adaptar, não pra emoldurar 😀

E se você tiver alguma referência visual? Como usar imagem no prompt

"Não tenho design" não é a mesma coisa que "não tenho referência"

Print de um concorrente, screenshot de uma tela que já existe no seu próprio produto, foto de um rabisco no caderno: tudo isso serve de alvo

E dá pra colocar imagem direto no prompt do Claude Code de duas formas: copiar e colar, ou arrastar e soltar

O fluxo visual que a Anthropic recomenda nas boas práticas do Claude Code é este:

1. Dê ao Claude alguma forma de tirar screenshot do navegador. As opções citadas são servidor MCP do Puppeteer, MCP de simulador iOS ou a colagem manual mesmo
2. Forneça o mock visual, colando ou arrastando a imagem no prompt
3. Peça a implementação em código, com o mock como alvo
4. Peça o screenshot do resultado e compare com o mock
5. Itere até bater

E tem um número aqui que vale guardar: a Anthropic afirma que a saída melhora de forma significativa com iteração, e que a primeira versão pode até ser boa, mas depois de 2 a 3 iterações costuma ficar bem melhor

Então vale separar duas coisas que parecem iguais e não são: 2 a 3 rodadas de refino com um alvo claro na mão é o esperado, faz parte do processo. Vaivém sem fim, aquele de ficar corrigindo a mesma tela indefinidamente, é sintoma de descrição vaga, não de iteração

Ou seja: se você olha o primeiro resultado e já sai xingando, você parou cedo demais

O ponto que amarra tudo continua o mesmo do começo do post: o desempenho melhora quando existe um alvo explícito pra iterar contra. Com imagem, o alvo é o mock. Sem imagem, o alvo são as cinco camadas que você escreveu

O que fazer quando a tela sai errada mesmo assim

Vai sair errada às vezes, e tudo bem

O que NÃO fazer é empilhar pedido de ajuste em cima de uma base torta, porque cada correção nova herda o defeito da anterior e a conversa vira um novelo

1. Volte pra um ponto anterior em vez de corrigir por cima. O comando /rewind (ou apertar Esc duas vezes) volta código, conversa ou ambos pra um ponto anterior

/rewind

O erro comum deste passo: insistir em "agora arruma isso, agora arruma aquilo" numa base que já nasceu errada. Sai mais barato voltar e reescrever o prompt

2. Identifique qual das cinco camadas estava vaga e reescreva SÓ ela. Se a tela veio plana, o problema foi hierarquia. Se ela quebrou com nome grande, foi o estado cheio sem dado concreto. Se ela mostra spinner eterno, foi o carregamento

O erro comum deste passo: reescrever o prompt inteiro do zero. Você perde a parte que já tinha acertado e recomeça a loteria

3. Quando a descrição de estados se repete em toda tela, transforme ela em instrução fixa. Se todo projeto seu usa a mesma régua de vazio, carregando e erro, isso não é assunto de prompt, é assunto de CLAUDE.md

Tem um bônus aqui: o CLAUDE.md da raiz do projeto sobrevive à compactação. Depois do /compact, o Claude relê o arquivo do disco e reinjeta ele na sessão

4. Ou transforme em comando reutilizável. Comandos customizados em .claude/commands/ continuam funcionando, e o nome do arquivo vira o nome do comando: um .claude/commands/deploy.md cria o /deploy

.claude/commands/tela.md   ->  vira o comando /tela

Só que o equivalente moderno, e recomendado, são as skills: .claude/skills/<nome>/SKILL.md. No caso do exemplo acima, .claude/skills/deploy/SKILL.md

O erro comum deste passo: escrever a mesma régua de estados na mão em cada prompt novo. Você já sabe o texto de cor, coloca ele num lugar que o Claude lê sozinho

Conclusão

Descrever tela no prompt do Claude Code sem design não é escrever mais, é escrever as camadas certas

E o segredo tá nos estados, não no layout

Layout todo mundo consegue imaginar. Agora o que aparece quando a lista está vazia, quando a resposta passa do limite da atenção, quando a API cai no meio do salvamento: é AÍ que a interface realmente decide como ela trata quem está do outro lado, e é exatamente isso que o design ia responder por você

Sem design, essa resposta tem que estar no texto

Próximo passo, bem concreto: pega a próxima tela que você precisa construir no projeto, abre um arquivo de texto e escreve o objetivo mais as cinco camadas (hierarquia, cheio, vazio, carregando, erro)

Depois roda em plan mode com Shift+Tab ou /plan, lê o plano inteiro e só aprova se ele mencionar os quatro estados

Faça o teste na próxima tela e compara com o vaivém de antes 😀

até o próximo post!