Como pedir ao Claude Code os estados de tela que quase ninguém lembra (vazio, carregando, erro e texto longo)

Fala aí, beleza? Sabe aquela tela que fica linda no print e desmonta no primeiro dia de uso real?

A lista sem nenhum item vira um retângulo branco no meio da página

o spinner gira pra sempre porque ninguém disse o que fazer quando a chamada falha

o erro chega no usuário como objeto cru, com stack e tudo

e o título de nome comprido estoura o card inteiro

O detalhe é que o problema quase nunca é o Claude Code, é o pedido

A gente descreve o caminho feliz ("uma lista de pedidos com nome, valor e status") e recebe exatamente isso: o caminho feliz, com três itens perfeitos que nunca vão existir em produção

Então bora fazer diferente: neste post tu vai ver como escrever os quatro estados que quase ninguém pede (vazio, carregando, erro e conteúdo longo demais) dentro do próprio prompt, pra não voltar três vezes no mesmo componente 🙂

O que ter antes de escrever o pedido

Nada de PC da Nasa aqui, o mínimo é bem simples:

• Claude Code instalado e rodando dentro do repositório do projeto, não numa pasta vazia
• clareza sobre QUAL componente ou tela vai sair dessa conversa
• de onde vêm os dados dessa tela (endpoint, query, arquivo, estado local), porque estado vazio e estado de erro nascem da fonte de dados, não do layout
• as referências visuais separadas, se existirem

Sobre a referência visual: o Claude Code aceita imagem no prompt de três formas, arrastando e soltando na janela, colando com Ctrl+V (no macOS, o Cmd+V funciona no iTerm2) ou passando o caminho do arquivo dentro do texto do pedido, tipo Analyze this image: /path/to/your/image.png

E tem um critério oficial pra decidir quando usar imagem, que está na documentação do Claude Code: use quando a descrição em texto ficaria confusa

Screenshot de design, screenshot de erro, diagrama

Se você consegue explicar em duas linhas, texto resolve, beleza?

Última coisa antes de começar: o plan mode vai ser usado lá no final do checklist

Pra entrar nele, tu aperta Shift+Tab até a barra de status mostrar "plan mode on", ou já inicia a sessão assim:

claude --permission-mode plan

Se você quer a visão geral antes de mergulhar no passo a passo, tem um post aqui sobre os estados da tela no prompt que serve de aquecimento

Passo a passo: como descrever cada estado no pedido

Bora ver na prática? A ideia é que cada passo vire uma linha do teu pedido, e não um novo chat depois que a tela já quebrou

1. Descreva a tela pelo DADO, não pelo layout

Antes de falar de card, cor e espaçamento, diga de onde vem a informação e quantos itens ela pode devolver

Zero, um, muitos

Essa frase sozinha já muda o que o Claude gera, porque ela expõe os casos que o layout esconde

Componente: lista de pedidos da página /pedidos
Fonte dos dados: endpoint interno de pedidos do usuario logado
A lista pode voltar com zero itens, com um item ou com centenas
A chamada pode falhar
Gere o componente cobrindo esses casos, nao so o caso com dados

O erro comum deste passo: pedir "uma lista de pedidos" e receber a versão com três itens lindos, todos com nome curto e valor redondo

2. Estado vazio: são DOIS casos dentro do mesmo estado

Esse aqui é o que mais me pega gente desprevenida

Vazio de verdade (o usuário nunca criou nada) e vazio por filtro/busca (existe dado, mas o recorte não achou nada) são telas diferentes, com textos diferentes e saídas diferentes

A primeira convida a criar o primeiro registro

A segunda tem que oferecer a saída do filtro, senão o cara fica preso achando que perdeu os dados

Estado vazio, dois casos separados:
1) nunca houve pedido: titulo curto explicando, texto de apoio e botao "criar pedido"
2) filtro ou busca sem resultado: mostrar o termo buscado, texto explicando
   que existem pedidos fora desse recorte e acao "limpar filtros"
Nao use a mesma tela para os dois casos

O erro comum deste passo: tratar os dois casos como a mesma tela e deixar o usuário trancado no próprio filtro

3. Estado carregando: peça o comportamento por faixa de tempo

"Coloca um loading" é pedido vago, e pedido vago devolve spinner genérico

Aqui vale ancorar em algo conhecido: os três limites clássicos de tempo de resposta formulados por Jakob Nielsen, descritos no artigo do NN/g sobre tempos de resposta

0,1 segundo é a faixa da resposta instantânea

1 segundo é onde o usuário percebe a espera mas mantém o fluxo de pensamento

10 segundos é o limite da atenção dele

E pra operação que passa de uns 10 segundos, a recomendação do NN/g é indicador de progresso com percentual concluído mais uma estimativa de quando termina

Estado carregando, por faixa de tempo:
- resposta rapida: nao piscar spinner, manter o layout estavel
- espera perceptivel: skeleton com o mesmo formato das linhas da lista
- operacao acima de ~10s: barra com percentual concluido e estimativa de termino
O botao que dispara a acao fica desabilitado enquanto carrega, com rotulo trocado

O erro comum deste passo: pedir "um loading" e ganhar spinner infinito justamente na operação longa, que é onde o usuário mais precisa saber se a coisa ainda está viva

4. Estado de erro: mensagem, recuperação e o que sobra na tela

Erro tem três perguntas obrigatórias, e o pedido tem que responder as três: o que aparece no lugar do conteúdo, qual a ação de recuperação e o que acontece com o que já estava na tela

Se erro de rede, erro do servidor e erro de permissão levam a saídas diferentes no teu produto, separe no prompt

Se levam ao mesmo lugar, não invente três telas

Estado de erro:
- mensagem em linguagem humana no lugar do conteudo, sem imprimir o objeto do erro
- acao de recuperacao explicita: botao "tentar de novo" que refaz a chamada
- os dados ja carregados continuam na tela, o erro aparece como faixa acima da lista
- erro de permissao nao oferece "tentar de novo", oferece voltar para a home

Uma dica: mensagem de erro é ponto clássico de leitor de tela ignorar o aviso, então vale rodar depois um passe de contraste, foco e leitura de tela nesses componentes

O erro comum deste passo: escrever só "mostrar mensagem de erro" e receber o error inteiro estampado na cara do usuário

5. Conteúdo longo demais: diga o limite REAL

O componente não trunca sozinho, e a IA não adivinha o teu pior dado

Então diga qual é o pior dado: título gigante, nome sem espaço (aquele e-mail que não quebra linha), lista com centenas de itens, número com muitas casas

E diga o que fazer em cada caso: truncar com reticências, quebrar linha, limitar a duas linhas, abreviar, paginar

Conteudo longo demais:
- titulo do pedido pode ter 120 caracteres: limitar a 2 linhas e truncar,
  com o texto completo no title do elemento
- e-mail longo sem espaco nao pode estourar o card, quebrar dentro da palavra
- valor pode passar de milhao: formatar com separador e nao deixar quebrar linha
- lista acima de 50 itens: paginar

O erro comum deste passo: assumir que "o CSS resolve" e descobrir o estouro só quando um cliente com nome comprido entra na base

6. Feche o pedido no plan mode antes de gerar código

Agora sim: Shift+Tab até aparecer "plan mode on" (ou a sessão iniciada com claude --permission-mode plan)

Nesse modo o Claude explora o código e produz um plano SEM editar os arquivos fonte, e edição de arquivo nunca é auto aprovada ali

Ele pode fazer perguntas de esclarecimento antes de fechar o plano, e a saída do modo acontece quando você aprova o plano ou aperta Shift+Tab de novo

No VS Code o plano abre como documento Markdown completo, e dá pra deixar comentário inline no que ficou de fora antes de qualquer execução

É o momento mais barato de descobrir que o vazio por filtro sumiu do plano 😀

O erro comum deste passo: aprovar o plano no impulso, sem ler se os quatro estados estão lá

7. Confira a tela renderizada, não só o código

Ler o diff e achar que "tá certo" é diferente de ver a tela vazia com os próprios olhos

A Anthropic descreve o uso de um servidor MCP de navegador (como o Playwright) pra montar loop de feedback visual: tirar screenshot do HTML renderizado, capturar diferentes tamanhos de viewport e testar elementos interativos dentro do fluxo do agente

Servidor MCP local se adiciona por linha de comando com transporte stdio:

claude mcp add --transport stdio <nome> -- <comando>

Tome cuidado com uma coisa: esse comando não valida credencial nenhuma

Ele aceita e segue a vida

A confirmação de que está tudo certo é o /mcp mostrando o servidor como "connected"

O erro comum deste passo: dar a tarefa como concluída sem nunca ter visto, de verdade, a tela sem dados e a tela com erro

8. Transforme o checklist em regra permanente

Se você vai repetir isso em todo componente, para de digitar

O CLAUDE.md guarda instruções persistentes do projeto e é lido pelo Claude no início de cada sessão, e a orientação oficial é justamente essa: comandos de build, convenções, layout do projeto e regras do tipo "sempre faça X"

Os quatro estados são um "sempre faça X" perfeito

O /init gera o CLAUDE.md do projeto e o /memory lista os arquivos de memória por escopo (CLAUDE.md, CLAUDE.local.md e companhia)

A outra opção é empacotar o checklist como skill, que é uma pasta com um SKILL.md (frontmatter YAML mais conteúdo Markdown):

.claude/skills/estados-de-tela/SKILL.md

Project Skills ficam em .claude/skills/ e User Skills em ~/.claude/skills/

E se você ainda usa .claude/commands/, se liga: esse é o formato legado

O recomendado hoje é .claude/skills/<nome>/SKILL.md, que aceita a mesma invocação por /nome e ainda pode ser acionado sozinho pelo Claude quando fizer sentido

O erro comum deste passo: colar o mesmo checklist no chat toda semana e achar que isso é processo

Como o checklist muda em cada tipo de tela

Os quatro estados são os mesmos, mas o que significa "vazio" e o que significa "longo demais" muda bastante de tela pra tela

Lista e tabela:

Aqui o vazio real e o filtro sem resultado são os protagonistas, como já vimos

Acrescente ao prompt o comportamento da paginação quando a página atual fica sem itens (voltar pra primeira página em vez de mostrar tabela oca) e o que acontece com célula de texto enorme: truncar por coluna, largura mínima e máxima, e nada de a tabela inteira ganhar scroll horizontal por causa de uma célula

Formulário:

Carregando aqui não é a tela, é o envio: botão desabilitado, rótulo trocado, campo bloqueado pra não gerar dois registros no duplo clique

Separe erro de validação (fica no campo, com o texto do que corrigir) de erro de servidor (fica no topo, com ação de tentar de novo)

E peça explicitamente o que quase sempre falta: o que o usuário digitou continua lá depois da falha

Perder um formulário inteiro por causa de um 500 é o tipo de coisa que queima confiança na hora

Dashboard de métricas:

O vazio do dashboard é o período sem dados, e ele é diferente de zero

"Nenhuma venda nesse período" não é a mesma coisa que uma venda registrada com valor zerado, diga isso no pedido

Acrescente o formato do número com muitas casas (abreviar, arredondar, separador) e o carregamento parcial: se um card depende de uma consulta lenta, ele carrega sozinho sem segurar o resto do painel refém

Busca:

A busca tem um caso a mais que ninguém lembra: a tela inicial, antes de digitar qualquer coisa

Tela em branco ali é desperdício, peça sugestões, buscas recentes ou uma dica do que dá pra procurar

Depois vêm o "nenhum resultado para X" (com sugestão de correção ou de limpar) e a consulta longa, que cai direto na faixa de tempo do passo 3

O próximo passo

Descrever estado é barato

Voltar três vezes no mesmo componente porque a tela quebrou no vazio, depois no erro, depois no título gigante, isso sim é caro (e chato demais)

O próximo passo é bem concreto: pega UM componente que já existe no teu projeto, roda o checklist dos quatro estados em cima dele em plan mode, lê o plano com calma e vê se vazio, carregando, erro e conteúdo longo aparecem lá

Se o resultado se provar, fixa a regra no CLAUDE.md ou empacota numa skill e nunca mais digita isso à mão

Ah, e pra quem gosta de explorar o visual antes de escrever o pedido: existe o Claude Design, um produto separado do Claude Code, do Anthropic Labs, pra criar protótipos, slides e one-pagers conversando com o Claude

Ele está em research preview nos planos Pro, Max, Team e Enterprise e é movido pelo Claude Opus 4.7

Coisa diferente do Claude Code, mas vale saber que existe quando a ideia ainda está crua…

Espero que ajude, e até o próximo post! =)