coastdigitalgroup/coastai-skills

Sistema de Estados Interativos

Propósito

O skill Sistema de Estados Interativos fornece um framework para definir como os componentes de UI respondem à entrada do usuário. Ele garante que cada elemento interativo (botões, links, campos de entrada, cards) tenha um feedback visual claro, consistente e acessível em todos os modos de interação (mouse, teclado, toque). Este sistema remove ambiguidades para desenvolvedores e garante uma sensação responsiva e de alta qualidade para o usuário final.

Casos de Uso

• Definir o comportamento de componentes para um sistema de design ou biblioteca de UI.
• Auditar um site existente em busca de interações "mortas" ou sem resposta.
• Garantir conformidade com WCAG 2.2 para indicadores de foco, tamanho de alvo e affordances interativos.
• Padronizar padrões de feedback (por exemplo, todas as ações destrutivas se comportam da mesma forma).

Quando NÃO Usar

• Conteúdo Estático: Elementos puramente informativos que não possuem interação de clique, toque ou teclado.
• Design de Movimento Experimental: Onde o objetivo é uma animação complexa e não padrão, em vez de feedback funcional de estado.
• Padrões Padrão do Navegador: Se o projeto depende estritamente de elementos nativos do navegador sem estilo (embora isso seja raro para designs de sites profissionais).

Entradas

1. Inventário de Componentes: Uma lista de todos os elementos interativos no design.
2. Sistema de Cores da Marca: Escalas de cores primárias, secundárias e semânticas existentes.
3. Meta de Acessibilidade: (por exemplo, WCAG Nível AA) que dita as taxas de contraste para os estados.

Saídas

1. Matriz de Estados: Um mapa abrangente mostrando os estados Default, Hover, Focus, Active e Disabled para cada componente.
2. Diretrizes de Interação: Regras para transições, tempo (ms) e funções de easing.
3. Especificação de Acessibilidade: Definições explícitas para anéis de foco e dicas visuais exclusivas para teclado.

Fluxo de Trabalho

1. Identificar Elementos Interativos

Categorize os elementos por seu tipo de interação:

• Ações: Botões, links, itens de menu.
• Entradas: Campos de texto, checkboxes, botões de rádio, selects.
• Contêineres: Cards clicáveis, cabeçalhos de acordeão, abas.

2. Definir a Paleta de Estados

Determine como as variáveis visuais mudam por estado:

• Hover (Mouse): Pequena mudança na cor de fundo, borda ou elevação (sombra).
• Focus (Teclado): Um anel ou contorno de alto contraste. Deve ser distinto do estado Hover.
• Active/Pressionado: "Compressão" visual (por exemplo, escurecimento leve ou redução de escala) para indicar um clique/toque bem-sucedido.
• Disabled: Opacidade reduzida e remoção de dicas interativas (o cursor muda).
• Visited (Links): Uma cor distinta para links navegados (crítico para sites com muito conteúdo).

3. Estabelecer Lógica de Foco

Projete um "Estilo de Foco Global" que garanta que os usuários de teclado sempre saibam onde estão.

• Regra: O indicador de foco deve ter uma taxa de contraste de pelo menos 3:1 contra o fundo E contra o estado sem foco do componente.
• Regra (WCAG 2.2 SC 2.4.11): O indicador de foco nunca deve ser totalmente ocultado por outro conteúdo (por exemplo, um cabeçalho fixo cobrindo um elemento focado durante a rolagem). Pelo menos parte do indicador deve permanecer sempre visível.

4. Otimizar para Toque (Mobile)

Como os estados de hover não existem em dispositivos de toque:

• Garanta que os estados active forneçam feedback imediato.
• Verifique se os alvos de toque atendem ao WCAG 2.2 SC 2.5.8 (mínimo 24x24px) e prefira 44x44px quando o layout permitir um alcance confortável do polegar.
• Remova informações dependentes de hover (use tooltips ao tocar ou rótulos persistentes).

5. Documentar Transições

Defina como a mudança ocorre:

• Duração: 150ms a 250ms é padrão para mudanças de estado.
• Easing: ease-in-out ou cubic-bezier(0.4, 0, 0.2, 1).

Regras de Decisão

• Persistência de Estado: Os indicadores de foco devem permanecer visíveis enquanto o elemento tiver o foco.
• Affordance Primeiro: Elementos interativos devem parecer "clicáveis" em seu estado padrão (por exemplo, botões devem ter mais peso visual do que tags não clicáveis).
• Sem Estados Apenas com Cor: Não dependa apenas da cor para indicar um estado (por exemplo, um estado de erro deve incluir um ícone ou mudança na espessura da borda).
• Feedback Imediato: As respostas interativas devem parecer instantâneas (tempo de início <100ms).

Restrições

• Acessibilidade: Indicadores de foco não podem ser "ocultados" via CSS outline: none sem fornecer uma alternativa robusta.
• Responsividade: Os estados devem funcionar em telas pequenas sem depender de hover do mouse.
• Desempenho: Evite box-shadows pesados ou filtros complexos em estados que disparam com frequência (como hover) para evitar travamento de layout.

Padrões Comuns de Falha

• O "Foco Invisível": Remover o anel de foco padrão do navegador e não substituí-lo, tornando o site inutilizável para usuários de teclado.
• Lógica Apenas com Hover: Colocar informações ou ações críticas dentro de um estado de hover, tornando-as inacessíveis no mobile.
• Estados Ativos Vaguitos: Botões que não mudam quando clicados, fazendo com que os usuários cliquem várias vezes.
• Estados Desabilitados Confusos: Elementos que parecem desabilitados, mas são clicáveis, ou vice-versa.

Critérios de Validação

• Cada elemento interativo tem estados Hover, Focus e Active definidos.
• Os indicadores de foco atendem ao requisito de contraste de 3:1 e nunca são totalmente obscurecidos por outro conteúdo (WCAG 2.2 SC 2.4.11).
• Os alvos de toque atendem a pelo menos 24x24px (WCAG 2.2 SC 2.5.8), preferencialmente 44x44px.
• Nenhuma informação crítica está oculta atrás de uma interação apenas com hover.
• Os estados desabilitados são visualmente distintos e possuem pointer-events: none (ou lógica equivalente).
• O sistema inclui uma diretriz clara de transição/animação para os estados.