Estados de carregamento, erro e vazio consistentes na web e no mobile

Por que esses estados ficam bagunçados tão rápido

Estados de carregamento, erro e vazio são as telas (ou pequenos blocos de UI) que as pessoas veem quando o app está aguardando, algo falhou ou simplesmente não há nada para mostrar. Eles são normais: redes ficam lentas, permissões são negadas e contas novas começam sem dados.

Ficam bagunçados porque geralmente são adicionados no fim e com pressa. Times constroem primeiro o caminho feliz, depois encaixam um spinner, uma mensagem vermelha e um placeholder de “sem itens” onde a UI quebra. Faça isso em dezenas de telas e você acaba com uma pilha de casos únicos.

Iteração rápida piora isso. Quando a UI é produzida rapidamente (incluindo UI gerada por IA), o layout principal pode aparecer em minutos, mas esses estados são fáceis de pular. Cada nova tela acaba com um estilo de spinner diferente, redação diversa (“Try again” vs “Retry”) e posicionamento distinto do botão. A velocidade ganha no início se transforma em trabalho de polimento pouco antes do lançamento.

Estados desencontrados confundem usuários e custam tempo às equipes. As pessoas não conseguem distinguir se uma lista vazia significa “sem resultados”, “ainda não carregou” ou “você não tem acesso”. A QA precisa testar uma longa cauda de variações pequenas, e bugs passam porque o comportamento difere entre web e mobile.

“Bagunça” costuma parecer com isto:

• Carregamento que esconde ações em uma tela mas não em outra.
• Erros às vezes bloqueiam a página, às vezes aparecem como texto pequeno.
• Estados vazios usam tom, ícones e próximos passos diferentes.
• Web e mobile usam rótulos diferentes para a mesma ação.

O objetivo é simples: uma abordagem compartilhada entre web e mobile. Se seu time gera recursos rapidamente (por exemplo, usando uma plataforma como Koder.ai), ter um padrão de estados importa ainda mais porque toda nova tela já começa coerente por padrão.

Os 5 tipos de estado que valem padronizar primeiro

A maioria dos apps repete os mesmos pontos de pressão: listas, páginas de detalhe, formulários, dashboards. É aí que spinners, banners e mensagens de “nada aqui” se multiplicam.

Comece nomeando e padronizando cinco tipos de estado:

• Initial loading: a primeira vez que uma tela abre, antes de haver qualquer dado.
• Refreshing / updating: a tela já tem dados, mas você está buscando dados mais recentes.
• Empty baseline: realmente não há nada ainda (conta nova, workspace novo, nenhum item criado).
• Zero results: existem dados, mas filtros ou busca não retornam nada.
• Error: requisições falham, permissões bloqueiam acesso ou algo quebra.

Dois casos especiais merecem regras próprias porque se comportam diferente:

• Offline: mostre conteúdo em cache quando possível e diga “You’re offline” claramente.
• Slow network: evite flashes rápidos de erro; após um pequeno atraso, mude para “Still loading…” (ou similar).

Entre telas e plataformas, mantenha a estrutura consistente: onde o estado aparece, o estilo do ícone, o tom e as ações padrão (Retry, Refresh, Clear filters, Create). O que pode variar é o contexto: o nome da tela e uma frase que use as palavras do usuário.

Exemplo: se você gerar uma lista web e uma lista mobile para “Projects”, elas devem compartilhar o mesmo padrão de zero‑results. O rótulo da ação ainda pode casar com a plataforma (“Clear filters” vs “Reset”).

Construa um kit de estados pequeno em vez de soluções pontuais

Se cada tela inventa seu próprio spinner, cartão de erro e mensagem vazia, você vai acabar com uma dúzia de versões levemente diferentes. A correção mais rápida é um pequeno “state kit” que qualquer recurso pode usar.

Comece com três componentes reutilizáveis que funcionem em todo lugar: Loading, Error e Empty. Mantenha‑os propositalmente discretos. Devem ser fáceis de reconhecer e não competir com a UI principal.

Torne os componentes previsíveis definindo um pequeno conjunto de entradas:

• Title (curto e específico)
• Message (uma ou duas frases)
• Primary action label
• Primary action handler (retry, refresh ou próximo passo)
• Optional details (código de erro, ação secundária)

Então trave a aparência. Decida uma vez espaçamento, tipografia, tamanho do ícone e estilo do botão, e trate isso como regra. Quando o tamanho do ícone e o tipo de botão permanecem os mesmos, os usuários param de notar a UI de estado e passam a confiar nela.

Limite as variantes para que o kit não vire um segundo design system. Três tamanhos costumam cobrir: small (inline), default (seção) e full‑page (bloqueante).

Se você gera telas no Koder.ai, uma instrução simples como “use the app StateKit for loading/error/empty with default variant” evita deriva. Também reduz limpeza de última hora em React web e Flutter mobile.

Escreva cópia de estado que permaneça consistente

A cópia faz parte do sistema, não é decoração. Mesmo quando o layout é consistente, frases improvisadas fazem as telas parecerem diferentes.

Escolha uma voz compartilhada: curta, específica, calma. Diga o que aconteceu em termos simples e depois diga ao usuário o que fazer a seguir. A maioria das telas precisa só de um título claro, uma explicação curta e uma ação óbvia.

Use templates para que equipes parem de improvisar

Alguns padrões de mensagem cobrem a maioria das situações. Mantenha‑os curtos para caber em telas pequenas:

• Network: “Can’t connect” + “Check your internet and try again.” + Ação: “Retry”
• Timeout: “Taking longer than expected” + “The request timed out.” + Ação: “Try again”
• Permission: “Permission needed” + “Allow access to continue.” + Ação: “Open settings”
• Not found: “Nothing here” + “This item may have been removed.” + Ação: “Back”
• Validation: “Fix one thing” + “Add a valid email address.” + Ação: “Save”

Evite texto vago como “Something went wrong” sozinho. Se você realmente não sabe a causa, diga o que sabe e o que o usuário pode fazer agora. “We couldn’t load your projects” é melhor que “Error.”

Faça o próximo passo previsível

Estabeleça uma regra: todo erro e estado vazio oferece um próximo passo.

• Se o usuário pode recuperar, ofereça “Retry” ou “Refresh”.
• Se o estado está vazio por filtros, sugira “Clear filters”.
• Se o usuário está bloqueado (permissão), diga exatamente onde alterar.

Isso importa ainda mais com UI gerada por IA, onde telas aparecem rápido. Templates mantêm a cópia consistente para você não reescrever dezenas de mensagens pontuais no polimento final.

Torne ações previsíveis: retry, refresh e próximos passos

Quando telas de estado sugerem ações diferentes de uma página para outra, os usuários hesitam. As equipes então acabam ajustando botões e rótulos pouco antes do lançamento.

Decida qual ação pertence a cada estado e mantenha o posicionamento e o rótulo consistentes. A maioria das telas deve ter uma ação primária. Se adicionar uma segunda, ela deve suportar o caminho principal, não competir com ele.

Um pequeno mapa de ações que escala

Mantenha as ações permitidas restritas:

• Loading: geralmente sem ação (opcionalmente “Cancel” para tarefas longas iniciadas pelo usuário).
• Empty: “Create” quando o usuário pode adicionar algo; “Adjust filters” quando filtros causaram o resultado vazio.
• Error: “Retry” para falhas temporárias; “Refresh” para dados obsoletos; “Contact support” apenas para fluxos bloqueados.
• Success with no data change: “Back” ou “Done.”

Botões discretos são uma característica. Eles tornam a UI familiar e ajudam telas geradas a permanecer coerentes.

Regras de retry e detalhes de erro

Mostre “Retry” apenas quando retry tiver chance real de funcionar (timeouts, rede instável, 5xx). Adicione um pequeno debounce para que toques repetidos não spammem requisições, e mude o botão para estado de carregamento enquanto tenta novamente.

Após falhas repetidas, mantenha o mesmo botão primário e melhore a ajuda secundária (por exemplo, uma dica “Check connection” ou “Try again later”). Evite introduzir novos layouts só porque algo falhou duas vezes.

Para detalhes de erro, mostre uma razão prática que o usuário possa agir (“Sua sessão expirou. Faça login novamente.”). Oculte detalhes técnicos por padrão. Se precisar deles, coloque‑os atrás de um affordance “Details” consistente entre plataformas.

Exemplo: uma lista “Projects” falha ao carregar no mobile. Ambas as plataformas mostram a mesma ação primária “Retry”, desabilitam enquanto tentam de novo e, após duas falhas, adicionam uma dica pequena sobre conexão em vez de mudar todo o layout do botão.

Implantando o sistema sem desacelerar as equipes

Trate consistência de estados como uma pequena mudança de produto, não um redesign. Vá incremental e torne a adoção fácil.

Comece com um rápido snapshot do que já existe. Não busque perfeição. Capture as variações comuns: spinners vs skeletons, erros full‑page vs banners, telas de “no results” com tons diferentes.

Um plano de rollout prático:

• Faça um inventário de 15 a 30 telas-chave entre web e mobile e agrupe os padrões mais comuns.
• Escolha 3 a 4 colocações canônicas que você suportará primeiro (full page, section, inline, toast).
• Construa componentes correspondentes para web e mobile que compartilhem os mesmos props e nomes.
• Escreva regras curtas de uso para que novas telas escolham do kit em vez de inventar uma versão nova.
• Substitua uma área do produto por vez (busca, inbox, cobrança) para que os releases fiquem seguros.

Quando os componentes existirem, o verdadeiro ganho de tempo é um conjunto curto de regras que remove debate: quando um estado bloqueia a página inteira vs apenas um card, e quais ações devem estar presentes.

Mantenha as regras curtas:

• Todo erro mostra um próximo passo claro (retry, refresh ou contatar suporte).
• Estados vazios oferecem uma ação primária (create, import ou explore).
• Estados de loading não pulam o layout quando os dados chegam.

Se você usa um gerador de UI como o Koder.ai, essas regras dão retorno rápido. Você pode pedir “use the state kit components” e obter telas que combinam com seu sistema tanto em React web quanto em Flutter mobile com menos limpeza.

Erros comuns que geram trabalho de polimento no fim

Trabalho de polimento de última hora geralmente acontece porque o tratamento de estados foi feito como gambiarras. Uma tela “funciona”, mas a experiência parece diferente toda vez que algo demora, falha ou não tem dados.

Carregamento que parece travado

Skeletons ajudam, mas deixá‑los por muito tempo faz as pessoas pensarem que o app travou. Uma causa comum é mostrar um skeleton completo em uma chamada lenta sem sinal de que algo está progredindo.

Defina um limite de tempo: após um pequeno atraso, mude para uma mensagem mais leve “Still loading…” ou mostre progresso quando possível.

Deriva de cópia entre telas

Times frequentemente escrevem uma nova mensagem toda vez, mesmo quando o problema é o mesmo. “Something went wrong”, “Unable to fetch” e “Network error” podem descrever um caso só, mas parecem inconsistentes e dificultam o suporte.

Escolha um rótulo por tipo de erro e reaplique‑o em web e mobile, com o mesmo tom e nível de detalhe.

Vazio vs erro vs ainda não carregado

Outro erro clássico é mostrar um estado vazio antes dos dados terminarem de carregar, ou mostrar “No items” quando o problema real é uma requisição falhada. O usuário toma a ação errada (como adicionar conteúdo quando deveria tentar novamente).

Deixe explícita a ordem de decisão: loading primeiro, depois error se houve falha, e só então empty quando você souber que a requisição teve sucesso.

Ações ausentes ou sobrecarregadas

Um erro sem ação de recuperação cria becos sem saída. O oposto também é comum: três botões competindo por atenção.

Mantenha‑o enxuto:

• Para erros, padrão é uma ação primária (geralmente “Retry”).
• Para estados vazios, ofereça um próximo passo claro.
• Use ações secundárias só quando realmente necessárias.

Desencontros visuais entre plataformas

Pequenas diferenças somam: estilo de ícone, padding, formato de botão. Isso também é onde UI gerada por IA pode derivar se prompts variam por tela.

Trave espaçamento, conjunto de ícones e layout para componentes de estado para que cada nova tela herde a mesma estrutura.

Regras práticas para comportamento de carregamento e acessibilidade

Se quiser tratamento de estados consistente entre web e mobile, torne as regras “sem graça” explícitas. A maior parte do polimento tardio acontece porque cada tela inventa seu próprio comportamento de loading, timeouts e rótulos.

Regras de loading que parecem rápidas (mesmo quando não são)

Para carregamento full page, escolha um padrão: skeletons para telas ricas em conteúdo (listas, cards, dashboards) e spinner apenas para esperas curtas onde o layout é desconhecido.

Adicione um limite de tempo para que a UI não fique pendurada silenciosamente. Se o carregamento passar de cerca de 8 a 10 segundos, mude para uma mensagem clara e uma ação visível como “Retry.”

Para carregamentos parciais, não deixe a tela em branco. Mantenha o conteúdo existente visível e mostre um indicador de progresso perto da seção que está atualizando (por exemplo, uma barra fina no cabeçalho ou um spinner inline).

Para dados em cache, prefira “stale but usable.” Mostre o conteúdo em cache imediatamente e adicione um sutil indicador “Refreshing…” para que as pessoas entendam que os dados podem mudar.

Offline é um estado próprio. Diga claramente e informe o que ainda funciona. Exemplo: “You’re offline. You can view saved projects, but syncing is paused.” Ofereça um único próximo passo como “Try again” ou “Open saved items.”

Noções básicas de acessibilidade que você pode aplicar em todo lugar

Mantenha estas consistentes entre plataformas:

• Ordem de foco: mova o foco para a mensagem de estado e para a ação primária quando o estado aparecer.
• Labels para leitores de tela: anuncie loading e erros com texto curto e claro.
• Alvos de toque: deixe botões fáceis de encostar no mobile, evite links inline minúsculos.
• Movimento: mantenha spinners sutis e não dependa apenas de animação.
• Cor: nunca use só cor como sinal (combine com texto e ícones).

Se você gera UI com uma ferramenta como Koder.ai, incorporar essas regras em um StateKit compartilhado ajuda cada nova tela a ser consistente por padrão.

Exemplo: uma feature, três estados, duas plataformas

Imagine um CRM simples com uma tela de Contacts list e uma tela de Contact details. Se tratar loading, error e empty como casos isolados, web e mobile derivam rápido. Um sistema pequeno mantém as coisas alinhadas mesmo quando a UI é produzida com rapidez.

First-time empty state (Contacts list): o usuário abre Contacts e não vê nada ainda. Em web e mobile, o título permanece o mesmo (“Contacts”), a mensagem vazia explica o porquê (“No contacts yet”) e um próximo passo claro é oferecido (“Add your first contact”). Se for preciso alguma configuração (como conectar uma caixa de entrada ou importar CSV), o estado vazio aponta esse passo exato.

Slow network loading: o usuário abre a página de Contact details. Ambas as plataformas mostram um skeleton previsível que corresponde à estrutura final da página (cabeçalho, campos principais, notas). O botão voltar continua funcionando, o título da página é visível e você evita spinners aleatórios em lugares diferentes.

Server error: a requisição de detalhes falha. O mesmo padrão aparece em web e mobile: uma manchete curta, uma frase e uma ação primária (“Retry”). Se o retry falhar novamente, ofereça uma segunda opção como “Go back to Contacts”, para que o usuário não fique preso.

O que permanece consistente é simples:

• Colocação: mensagem na área de conteúdo, ações em um local óbvio.
• Cópia: um tom só, mesmos rótulos de botão (Retry, Add contact).
• Comportamento: mesmos gatilhos para skeletons, mesmas regras de retry.
• Segurança: desabilitar ações duplicadas enquanto carrega.

Checklist rápido antes de enviar

Um release pode parecer “pronto” até alguém cair numa conexão lenta, numa conta nova ou numa API instável. Este checklist ajuda a identificar lacunas de última hora sem transformar a QA numa caça ao tesouro.

Verificações de consistência de UI

Comece por telas de lista, porque elas se multiplicam. Escolha três listas comuns (resultados de busca, itens salvos, atividade recente) e verifique se todas usam a mesma estrutura de estado vazio: título claro, uma frase útil e uma ação primária.

Assegure que estados vazios nunca apareçam enquanto os dados ainda estão carregando. Se você piscar “Nothing here yet” por um split second e depois substituir por conteúdo, a confiança cai rápido.

Cheque indicadores de loading por consistência: tamanho, posição e uma duração mínima sensata para que não pisquem. Se web mostra um spinner na barra superior mas mobile mostra um skeleton full‑screen para a mesma tela, parece que são dois produtos diferentes.

Erros e verificações de QA

Erros devem sempre responder “e agora?”. Todo erro precisa de um próximo passo: retry, refresh, limpar filtros, logar novamente ou contatar suporte.

Uma verificação rápida antes de considerar o build pronto:

• Estados vazios: mesmo layout, estilo de ícone e tom nas telas de lista.
• Loading: nunca substituído por empty cedo demais; indicadores casam entre web e mobile.
• Erros: uma ação clara em cada tela de erro ou toast.
• Regras de cópia: padronização de palavras entre plataformas (títulos, pontuação, verbos de botão).
• Script de QA: um conjunto curto e repetível de passos que dispare carregamento, empty e error.

Se você usa um construtor de IA como o Koder.ai, essas verificações valem ainda mais porque telas podem ser geradas rápido, mas a consistência depende de um kit compartilhado e de regras de cópia.

Próximos passos: manter a consistência conforme o app cresce

Consistência é mais fácil quando faz parte do dia a dia, não de uma limpeza pontual. Toda nova tela deve usar os mesmos padrões sem que alguém lembre “faça combinar” no final.

Faça o comportamento de estado parte da definição de pronto. Uma tela não está finalizada até ter um estado de loading, um estado vazio (quando aplicável) e um estado de erro com uma ação clara.

Mantenha as regras leves, mas documente. Um documento curto com algumas capturas e os padrões exatos de cópia costuma bastar. Trate novas variantes como exceção. Quando alguém propuser um novo design de estado, pergunte se é realmente um caso novo ou se cabe no kit.

Se for refatorar muitas telas, reduza risco fazendo em passos controlados: atualize um fluxo por vez, verifique em web e mobile e continue. No Koder.ai, snapshots e rollback podem tornar mudanças maiores mais seguras, e o planning mode ajuda a definir o StateKit compartilhado para que telas novas sigam seus padrões desde o início.

Uma forma prática de avançar

Escolha esta semana uma área onde problemas de estado geram correções de última hora (muitas vezes busca, onboarding ou feed de atividade). Então:

• Adicione requisitos de estado ao checklist de aceitação dessa área.
• Substitua estados one‑off por seus componentes compartilhados.
• Registre 2 a 3 exemplos (bons e ruins) no documento.
• Faça uma revisão rápida entre plataformas (mesmo significado, mesmas ações, layout similar).
• Acompanhe quantos tickets de polimento você abrir no próximo sprint e compare.

Um sinal concreto de que está funcionando: menos tickets pequenos como “adicionar retry”, “estado vazio estranho” ou “spinner bloqueia a página”.

Mantenha a propriedade clara

Atribua um único proprietário para padrões de estado (um designer, um tech lead, ou ambos). Não precisam aprovar tudo, mas devem proteger o kit de se fragmentar em novas variantes que parecem similares, se comportam diferente e custam tempo depois.