Gerador de Estados de Feedback de UX

Quando Usar

Use esta habilidade quando precisar adicionar estados de feedback apropriados para o usuário (carregando, sucesso, erro, vazio) a um componente ou página.

Quando NÃO Usar

• Apenas para as palavras dentro de um estado → use /ss-copy
• Para problemas de acessibilidade em estados existentes → use /ss-a11y
• Para criação de componentes totalmente novos → use /ss-component
• Para configuração de analytics ou registro de erros — apenas apresentação de UI

Alvo: $ARGUMENTS

Instruções

1. Leia o arquivo alvo e identifique todas as áreas dependentes de dados.

2. Leia a referência da linguagem de design:

   • Seções DESIGN-LANGUAGE.md sobre Estados de Carregamento (Esqueleto), Estados Vazios, Estados de Erro

3. Para cada área dependente de dados, implemente TODOS os 4 estados:

Estado 1: Carregando (Esqueleto)

// Skeleton must match the final layout shape
<div className="bg-card rounded-2xl p-6 shadow-[var(--shadow-card)]">
  <div className="flex items-center gap-2 mb-3">
    <div className="size-7 bg-surface-muted rounded-lg animate-pulse" />
    <div className="h-3 w-16 bg-surface-muted rounded animate-pulse" />
  </div>
  <div className="h-9 w-24 bg-surface-muted rounded-lg animate-pulse mb-3" />
  <div className="h-3 w-12 bg-surface-muted rounded animate-pulse" />
</div>

Regras:

• Exiba o esqueleto por no mínimo 300ms (evite flash)
• Atrasar a exibição do esqueleto em 300ms (cargas rápidas pulam o esqueleto completamente)
• Use animate-pulse (ciclo de 1,5s)
• Combine as formas do esqueleto com as dimensões do conteúdo real
• Nunca use spinners dentro de cards

Estado 2: Vazio (Sem Dados)

<EmptyState
  icon={PackageIcon}
  title="No activity yet"
  description="Create your first project to get started."
  action={<Button>Create Project</Button>}
/>

Regras:

• Alinhado ao centro no card
• Ícone: 32px, text-text-tertiary
• Título: 14px, text-text-secondary
• Sempre sugira uma próxima ação
• Valores zero são exibidos como "0" (não oculte ou use traço)

Estado 3: Erro (Falha ao Carregar)

<div className="flex flex-col items-center justify-center py-8 text-center">
  <AlertCircle className="size-8 text-destructive mb-3" />
  <p className="text-[14px] text-text-secondary mb-4">Couldn't load the data</p>
  <Button variant="brandGhost" size="sm" onClick={retry}>Try again</Button>
</div>

Regras:

• Falha parcial: apenas o card afetado exibe erro, o restante carrega normalmente
• Falha na página inteira: EmptyState em tela cheia com opção de tentar novamente
• Mensagem de erro: linguagem clara, culpe o sistema
• Sempre forneça um botão para tentar novamente

Estado 4: Sucesso (Feedback de Ação)

// Toast notification for action confirmations
toast("Changes saved")

// With undo for destructive actions
toast("Item deleted", { action: { label: "Undo", onClick: handleUndo } })

Regras:

• Toast de informação: exibição de 3s
• Toast de ação (com desfazer): exibição de 5s
• Posição do toast: acima do BottomNav
• Um toast por vez (novo substitui o antigo)

4. Padrão de implementação:

function DataCard({ data, isLoading, error }) {
  if (isLoading) return <DataCardSkeleton />
  if (error) return <DataCardError onRetry={refetch} />
  if (!data || data.length === 0) return <DataCardEmpty />
  return <DataCardContent data={data} />
}

5. Verifique prefers-reduced-motion — desabilite animate-pulse quando o movimento reduzido for preferido.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente à sua origem anterior e ao contexto do projeto local.
• Verifique comandos, código gerado, dependências, credenciais e comportamento de serviços externos antes de aplicar alterações.
• Não trate exemplos como substitutos para testes específicos do ambiente, revisão de segurança ou aprovação do usuário para ações destrutivas ou custosas.