Status: Approved · v2.2 · SPEC-UX-STATES-001

depends_on: SPEC-CONTRACTS-RESPONSE-001, SPEC-UX-VISUAL-001, SPEC-UX-TOKENS-001

used_by: ALL_MVP_SCREENS, IS-MVP-17.2, IS-MVP-17.3, IS-MVP-17.4

Estados de loading, vazio, erro e bloqueio

Alinhado ao capítulo 13 do design/RaizFC Book.dc.html: preservar hierarquia, explicar contexto, oferecer recuperação e manter conteúdo seguro.

1. Modelo obrigatório

Estado não é placeholder genérico. Cada tela/seção documenta:

• o que já é conhecido e pode permanecer visível;
• o que está carregando, vazio, indisponível ou bloqueado;
• se o efeito é total ou parcial;
• a ação segura de recuperação;
• a copy específica e, em erro técnico, o identificador de suporte aplicável.

Loading, empty, error, blocked e success precisam ocupar a mesma hierarquia sem saltos indevidos. Tema dark/light muda tokens, não o significado do estado.

2. Loading: skeleton editorial

O skeleton reproduz a anatomia final. Hero usa placeholder de escudo/avatar + duas linhas; ações usam blocos com a altura real; spotlight/lista preserva número e ordem aproximados. Não usar uma grade genérica quando a tela final é editorial.

Regras:

• página pública conhecida: skeleton de hero, ações, spotlight e seções;
• lista/tabela: preservar colunas/linhas essenciais e largura relativa do conteúdo;
• placar: manter duas áreas de participante e centro numérico, sem exibir 0–0 falso;
• mutation: loading no controle acionado, mesma largura/label acessível, duplo envio bloqueado;
• conteúdo prévio seguro permanece com indicador de atualização; spinner full-screen só antes de qualquer estrutura conhecida;
• requests obsoletas são canceladas/ignoradas;
• shimmer segue tokens v2 e respeita reduced motion.

3. Empty: explicação + ação

Empty é sucesso sem dados. Sempre responde “por que está vazio?” e “qual próximo passo está disponível?”. Anatomia:

1. ícone/objeto sóbrio opcional;
2. título específico;
3. uma explicação factual;
4. CTA permitido e relacionado ao contexto;
5. alternativa/saída quando relevante.

Contexto	Copy documental de referência	Ação
Feed novo	Seu feed ainda está em aquecimento. + explicar que seguir entidades/território traz resultados e jogos	Explorar {território}
Ranking	Ainda não há partidas validadas para este período.	alterar período/filtro
Busca	Nenhum resultado para “{termo}” neste escopo.	limpar filtro ou ampliar escopo
Elenco	Este time ainda não publicou jogadores nesta categoria.	convidar/adicionar somente com permissão
Carteira/apoio	explicar ausência de movimentação sem urgência financeira	compartilhar apoio quando permitido

Nunca mostrar ação de gestão para visitante sem permissão. Proibido Nada por aqui!, personagem triste, culpa, urgência artificial ou dado fictício para preencher espaço.

4. Falha parcial: conteúdo seguro + retry local

Uma seção pode falhar sem derrubar a página. Exemplo canônico: Não conseguimos atualizar o ranking. O resto da página continua atualizado. O banner aparece no lugar/contexto da seção, oferece Tentar de novo e mantém identidade, jogos ou dados anteriores seguros.

• retries são independentes por seção quando viável;
• dados antigos recebem indicação de desatualização quando isso muda a decisão do usuário;
• falha de ranking/feed/card não remove hero e ações não dependentes;
• falha de permissão, identidade fundamental ou privacy interrompe o conteúdo potencialmente privado;
• recuperação não recarrega a página inteira sem necessidade.

5. Erro documental

Erro documental explica o que ocorreu, efeito, próxima ação e referência técnica quando útil. O caso canônico de 410 é: O Pix expirou. Gere um novo para continuar o apoio a {entidade}. + Gerar novo Pix + requestId em detalhe de suporte.

Código/condição	Comportamento e recuperação
offline/rede	informar conexão; preservar rascunho/dados seguros; retry
validação de formulário	mensagem junto do campo + resumo quando necessário; foco no primeiro erro
401	preservar AuthIntent e iniciar login contextual
403	explicar que falta acesso; não sugerir ação impossível
404	dizer qual conteúdo não foi encontrado; voltar/buscar
409	explicar mudança concorrente e recarregar estado canônico
410	explicar expiração e oferecer regeneração/recriação
429	informar espera de maneira acionável, sem loop automático agressivo
500/inesperado	mensagem humana, retry seguro e requestId em detalhe copiável

requestId não substitui a mensagem nem expõe stack, endpoint interno ou dado sensível.

6. Bloqueios e estados de entidade

• inactive/closed: histórico visível e ações limitadas;
• abandoned: aviso e reivindicação somente quando elegível;
• suspended: conteúdo limitado conforme política, sem acusação além do estado público;
• duplicated/merged: redirect canônico;
• under review: banner neutro;
• sem permissão: contexto visível quando público, ação desabilitada/oculta conforme spec de permissão, explicação acessível.

7. Componentes e tokens

• skeleton: surface-alt, border, radius 8;
• empty: background/surface, text, text-muted, CTA primary;
• falha parcial: danger em borda/ícone/texto de estado, sem preencher toda a página;
• sucesso/aviso: success/accent + label/ícone;
• foco do retry/CTA: ring de 2 px;
• motion: 120–240 ms e reduced motion.

8. Acessibilidade e analytics

• loading anuncia progresso sem repetir a cada skeleton;
• toast/banner crítico usa região live apropriada e não rouba foco indevidamente;
• retry é alcançável por teclado e touch target mínimo 44×44;
• cor nunca é o único indicador;
• evento de erro registra código estável e requestId, nunca copy ou dado pessoal bruto;
• fonte aumentada não corta explicação, ação nem id de suporte.

9. Critérios de aceite

• Toda tela/seção descreve loading, success, empty, error, partial failure e permission/status aplicáveis.
• Skeleton espelha a hierarquia final e não mostra dado esportivo falso.
• Empty contém causa contextual e ação permitida; não usa copy genérica.
• Falha parcial mantém conteúdo seguro e retry local.
• Erro documental mapeia código, efeito, recuperação e requestId quando aplicável.
• Mutation impede duplo envio e preserva dimensões do controle.
• Dark/light, teclado, leitor de tela, fonte ampliada, offline e reduced motion são cobertos proporcionalmente ao risco.

10. Histórico

• 2.2 — alinhamento explícito ao capítulo 13 do Book e anatomias de skeleton, empty, falha parcial e erro documental.
• 2.1 — regras gerais anteriores, preservadas no histórico Git.