coastdigitalgroup/coastai-skills

Sistema de Etapas e Progresso

Propósito

O skill Sistema de Etapas e Progresso fornece uma metodologia para projetar e documentar como os usuários se movem por processos de múltiplas etapas ou aguardam tarefas em segundo plano. Ele garante que fluxos de trabalho complexos (como checkouts ou onboarding) sejam divididos em partes gerenciáveis, reduzindo a carga cognitiva ao comunicar onde o usuário está, o que foi concluído e o que resta fazer.

Casos de Uso

• Checkouts de E-commerce: Guiando os usuários por frete, pagamento e revisão.
• Formulários de Múltiplas Etapas: Dividindo tarefas longas de entrada de dados em seções lógicas.
• Onboarding de Usuários: Visualizando o processo de configuração de uma nova conta.
• Estados de Carregamento/Upload: Comunicando o status de operações de longa duração.
• Trilhas de Aprendizado: Mostrando o progresso em um curso ou currículo.

Quando NÃO Usar

• Tarefas de Tela Única: Se uma tarefa pode ser concluída em uma única vista sem alternância de contexto, um sistema de progresso adiciona ruído desnecessário.
• Feeds Infinitos: Rolagem de conteúdo onde não há um "fim" definido para o progresso.
• Interações Críticas de Alta Velocidade: Onde o atraso de mostrar indicadores de progresso prejudicaria uma tarefa sensível ao tempo (por exemplo, interface de jogos em tempo real).

Entradas

1. Inventário de Etapas: Uma lista dos estágios discretos necessários para concluir a tarefa.
2. Tipo de Tarefa: É uma sequência orientada pelo usuário (Steppers) ou um processo orientado pelo sistema (Barras de Progresso)?
3. Linearidade: As etapas devem ser concluídas em ordem, ou o usuário pode pular entre elas?
4. Restrições de Conteúdo: Rótulos, descrições e ícones para cada etapa.

Saídas

1. Estrutura de Progresso: Uma definição do tipo de componente (Horizontal, Vertical ou Circular).
2. Matriz de Estados: Especificações visuais para os estados Pendente, Ativo, Concluído e Erro.
3. Estratégia Responsiva: Como o indicador se adapta a viewports móveis (por exemplo, esconder rótulos, mudar para numérico).
4. Especificações de Acessibilidade: Funções ARIA, regiões ativas e regras de interação por teclado.

Fluxo de Trabalho

1. Categorizar o Tipo de Progresso

Determine o padrão visual mais apropriado:

• Stepper Horizontal: Melhor para processos lineares com 3–5 etapas em desktop.
• Stepper Vertical: Melhor para processos não lineares, etapas com comprimentos de conteúdo variados ou fluxos mobile-first.
• Barra de Progresso Contínua: Melhor para tarefas orientadas pelo sistema (uploads, carregamento) ou processos com um alto número de micro-etapas.
• Círculo de Progresso: Melhor para widgets de dashboard ou quando o espaço é extremamente limitado.

2. Definir Hierarquia e Rótulos das Etapas

• Rótulo Principal: Nome conciso da etapa (por exemplo, "Frete").
• Rótulo Secundário (Opcional): Descrição curta ou status (por exemplo, "Em Andamento").
• Indicador Visual: Números (para ordem), Ícones (para contexto) ou Pontos (para design minimalista).

3. Estabelecer Visualização de Estados

Defina distinções visuais claras para cada estado:

• Pendente: Baixo contraste, geralmente acinzentado.
• Ativo: Alto contraste, frequentemente usando a cor primária da marca ou um efeito de "brilho".
• Concluído: Use um ícone de "check" e uma cor distinta (geralmente verde ou uma versão mais suave da cor ativa).
• Erro: Use um ícone de "aviso" e uma cor de erro semântica (vermelho).

4. Projetar para Movimento e Feedback

• Transições: Use animações sutis ao mover entre etapas para reforçar a progressão.
• Clicabilidade: Determine se os usuários podem clicar em etapas anteriores para voltar.
• Validação: Visualize que uma etapa é válida/complete antes de permitir a progressão.

5. Planejar Adaptações Responsivas

Indicadores de múltiplas etapas são notórios por quebrar em dispositivos móveis:

• Redução de Rótulos: Em dispositivos móveis, oculte os rótulos de texto e mostre apenas números ou ícones.
• Transição para "Etapa X de Y": Substitua a barra visual completa por um resumo textual ou numérico simples.
• Mudança Vertical: Converta barras horizontais em listas verticais em telas pequenas.

Regras de Decisão

• A Regra das 5 Etapas: Se um stepper horizontal tiver mais de 5 etapas, mude para um stepper vertical ou um indicador de texto simples "Etapa X de Y" para evitar poluição visual.
• Ícone vs. Número: Use números se a ordem da sequência for crítica; use ícones apenas se eles fornecerem valor semântico imediato (por exemplo, um ícone de "Cartão de Crédito" para pagamento).
• Linearidade: Se os usuários devem concluir as etapas em ordem, desabilite cliques em etapas "futuras". Se for uma configuração flexível, permita pular.
• Preservação de Contexto: Sempre mostre os rótulos da etapa atual, anterior e próxima. Outras podem ser truncadas se necessário.

Restrições

• Acessibilidade:
  • Use role="progressbar" com aria-valuenow, aria-valuemin, aria-valuemax e um aria-valuetext legível por humanos (por exemplo, "Etapa 2 de 4: Pagamento") para barras contínuas.
  • Use aria-current="step" para identificar a etapa ativa em uma sequência.
  • Garanta que as taxas de contraste para etapas ativas vs. inativas atendam ao WCAG AA (4.5:1).
  • Se as etapas forem clicáveis, seus alvos devem atender ao WCAG 2.2 SC 2.5.8 (mínimo 24x24px, preferencialmente 44px) e expor estados :focus-visible visíveis.
• Hierarquia: O indicador de progresso deve ser um guia, não o foco principal. Geralmente fica no topo (horizontal) ou à esquerda (vertical) do conteúdo.
• Responsividade: Não deve causar overflow horizontal.

Padrões Comuns de Falha

• O "Progresso Misterioso": Mostrar uma barra sem rótulo ou porcentagem, deixando o usuário se perguntando "quanto tempo falta?"
• Estados Inacessíveis: Usar apenas cor (por exemplo, verde vs. cinza) para indicar conclusão sem ícones ou texto.
• Horizontais Lotados: Forçar muitas etapas em um layout horizontal, causando texto sobreposto ou alvos de toque minúsculos em dispositivos móveis.
• Falta de Persistência: Ocultar o indicador de progresso em algumas páginas de um fluxo de múltiplas etapas, fazendo com que os usuários percam o senso de localização.

Critérios de Validação

• A etapa atual é claramente distinguida das etapas concluídas e futuras.
• As etapas concluídas usam um indicador não baseado em cor (como uma marca de seleção).
• A visualização móvel é funcional e não causa overflow ou poluição visual.
• As funções ARIA e aria-current estão aplicadas corretamente.
• O sistema lida com estados de "Erro" para etapas individuais.
• O indicador está posicionado de forma consistente em todas as etapas do fluxo.