publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/global/skills/ux-fluxo-funcional/SKILL.md

9.6 KiB
Raw Blame History

name description scope updatedAt
ux-fluxo-funcional Arquitetura de Informação, Jornada Operacional Guiada, Revelação Progressiva (Progressive Disclosure) e Contraste Funcional em aplicações <modulo>-front. Transforma telas isoladas em um fluxo contínuo, autoexplicativo e sem sobrecarga cognitiva. global 2026-10-18

Skill: UX de Fluxo Funcional e Jornada Guiada (ux-fluxo-funcional)

Objetivo

Garantir que qualquer aplicação <modulo>-front do ecossistema (identificada via memorias-ia/modulo.yml) opere como um fluxo funcional contínuo e autoexplicativo, evitando que a execução sequencial de features resulte em telas isoladas, navegação oculta, excesso de informação simultânea (split-screen espremido), jargões técnicos de banco de dados ou botões invisíveis por falha de contraste no tema.

Os 6 Pilares da Usabilidade Funcional

Pilar 1 — Navegação Primária Visível e Ordenada pela Jornada Operacional

O usuário corporativo não deve adivinhar onde clicar nem abrir um menu hambúrguer oculto a cada troca de tela para descobrir como o sistema funciona.

  1. Ordem da Tarefa (Task-Order Navigation): A navegação principal do módulo deve refletir a sequência lógica de trabalho do domínio:
    • 1. Cadastros Base / Pré-requisitos (ex.: catálogos, recursos, equipes, parâmetros iniciais)
    • 2. Modelos / Configuração (ex.: templates, padrões reutilizáveis)
    • 3. Entidade Principal / Planejamento (ex.: registros centrais do módulo, cronogramas, estruturação)
    • 4. Execução Operacional (ex.: quadros de trabalho, filas de atendimento, operação diária)
    • 5. Monitoramento / Indicadores (ex.: dashboards executivos, relatórios consolidados)
  2. Barra de Navegação Visível no Topo ou Subcabeçalho: Além do menu lateral retrátil (v-navigation-drawer), manter uma barra de navegação primária visível no v-app-bar (ou barra horizontal de etapas) com destaque claro da rota ativa.

Pilar 2 — Fluxo Guiado e Desacoplamento de Pré-requisitos (Zero Becos Sem Saída)

Quando uma tela ou ação exige registros previamente cadastrados em outra tela, a interface nunca deve exibir apenas um <v-select> vazio ou um erro genérico de validação.

  1. Empty States Orientadores com CTA Direto: Todo estado vazio deve explicar por que não há itens e oferecer um botão de ação imediata (to="..." ou abertura de modal) para o passo anterior ou para a criação do primeiro registro.
  2. Avisos de Pré-requisito com Atalho: Se um formulário requer um cadastro base ainda inexistente, exibir um <v-alert type="info" variant="tonal"> explicando o pré-requisito com um botão direto para a tela correspondente.
  3. Continuidade Pós-Ação: Após concluir um cadastro estruturante (ex.: aplicar um modelo ou criar um registro principal), oferecer atalho claro para o próximo passo natural da jornada (ex.: "Ir para o Quadro de Execução" ou "Detalhar Etapas").

Pilar 3 — Revelação Progressiva e Anti-Aperto Visual (Progressive Disclosure)

Evitar empilhar listas mestras, formulários e múltiplas abas analíticas na mesma dobra de tela.

  1. Proibição de Split-Screen Estreito (4 + 8 colunas) para Conteúdo Complexo:
    • Nunca dividir a tela em v-col md="4" (lista lateral fixa) + v-col md="8" (detalhe) quando o painel de detalhe possuir tabelas de múltiplas colunas, cronogramas, árvores hierárquicas ou 3+ abas.
    • Padrão Recomendado: Utilizar um Seletor Rápido de Contexto no Topo (v-select / v-autocomplete em card compacto + botão de listagem/troca) e dedicar 100% da largura (12 colunas) para a área de trabalho ativa.
  2. Agrupamento de Ações Secundárias:
    • Limitar cada cabeçalho de seção ou linha de tabela a 1 ação primária visível + até 2 ações frequentes.
    • Agrupar ações secundárias ou administrativas (ex.: exportar, clonar, histórico, arquivar, excluir) em menu contextual (v-menu) ou modal específico.

Pilar 4 — Linguagem Humana do Domínio (Zero Jargão de Banco ou Engenharia)

O usuário final é especialista no negócio (gestor, técnico, analista, operador), não em engenharia de software ou modelagem de banco de dados.

❌ Proibido na Interface (Jargão Técnico) ✅ Obrigatório na Interface (Linguagem Humana)
Dados extras (info), Metadados JSONB, Payload Campos com rótulos reais do negócio ou seção Informações Complementares
Instanciar Template, Hidratar Entidade, Seed Criar a partir de Modelo, Aplicar Modelo Padrão
CRUD de ..., Listagem de Entidades Nome direto da área (ex.: Equipes e Pessoas, Modelos de Trabalho)
Siglas técnicas puras sem contexto (WBS, EVM, FK, UUID) Termos compreensíveis (Estrutura de Etapas, Desempenho e Prazos, Código)
Valores brutos de enum (EM_ANDAMENTO, concluido_atraso) Rótulos formatados com acentuação e semântica visual (Em Andamento, Concluído com Atraso)

Pilar 5 — Contraste Garantido em Tokens de Tema Vuetify (secondary Escuro)

No Vuetify 3 em tema claro (dark: false), componentes com variant="tonal" e variant="outlined" utilizam a própria cor do token como cor do texto e do ícone sobre um fundo translúcido (12% de opacidade) ou branco (#FFFFFF).

  1. Proibição de Cores Pastéis Claras no Token secondary:
    • NUNCA definir secondary no vuetify.ts com cores claras/pastéis (ex.: #EAF2D3, #EEF3D0, #F5F5F5), pois qualquer <v-btn color="secondary" variant="tonal">, <v-btn color="secondary" variant="outlined"> ou <v-chip color="secondary"> ficará invisível (contraste ~1.1:1 sobre branco).
  2. Tokens Seguros para secondary em Tema Claro:
    • Estilo Floreta (Privado): Usar --cor-eli-neutro-escuro (#3E4436) ou --cor-eli-primaria-escura (#4A6500) — garantindo contraste WCAG AA ≥ 7:1 em variantes tonal e outlined, e texto branco legível em variante flat/elevated.
    • Estilo Betha (Governo): Usar #495057 ou #6c757d escuro com contraste validado.
    • Reservar cores pastéis claras (#EEF3D0) exclusivamente para variáveis CSS de fundo (--cor-eli-primaria-bg), nunca como token semântico de texto/botão do Vuetify.

Pilar 6 — Ergonomia de Quadros Operacionais e Navegação Cruzada

  1. Quadros Kanban Sempre Horizontais Lado a Lado:
    • Colunas de estágios (ex.: A Fazer, Em Andamento, Em Revisão, Concluído) devem ser exibidas lado a lado horizontalmente em desktop utilizando container flexível (d-flex flex-nowrap overflow-x-auto ga-4 pb-2) com largura mínima por coluna (min-width: 280px a 320px).
    • Proibido usar v-row/v-col que empilhe colunas de min-height: 420px verticalmente em resoluções intermediárias, gerando enormes caixas vazias que escondem os cartões abaixo da dobra.
  2. Navegação Cruzada (Drill-down Contextual):
    • Cards de resumo em Dashboards e tabelas de acompanhamento devem oferecer ação direta (clique ou botão) para abrir o registro correspondente no painel de detalhamento ou no quadro operacional já filtrado pelo item selecionado (query ou params de rota).

Protocolo Passo a Passo de Aplicação

  1. Ler Identidade do Módulo: Consultar memorias-ia/modulo.yml para identificar modulo-id, modulo-caminho, modulo-descricao e modulo-tipo.
  2. Auditar a Jornada Completa: Inspecionar App.vue, router/index.ts, plugins/vuetify.ts e as views de <modulo>-front/src/ verificando os 6 Pilares acima.
  3. Corrigir Tokens e Navegação Global:
    • Ajustar secondary em vuetify.ts caso esteja usando cor clara sem contraste.
    • Tornar a navegação principal visível e ordenada pela jornada operacional em App.vue.
  4. Desafogar Layouts e Conectar Fluxos:
    • Substituir split-screens apertados (4+8) por seleção de contexto + área principal de 12 colunas.
    • Inserir links de navegação cruzada e empty states guiados entre telas dependentes.
    • Garantir que quadros Kanban sejam horizontais e responsivos.
  5. Validar Visualmente com agent-browser:
    • Inspecionar o fluxo ponta a ponta em modo visível (agent-browser --session <modulo-id>_<contexto?> --headed) conforme rules/testes-interface-agent-browser.md.

Checklist Rápido de Conformidade (ux-fluxo-funcional)

  • A barra de navegação principal está visível e ordenada na sequência lógica de uso do módulo?
  • Todas as telas com pré-requisitos orientam o usuário e oferecem botão direto para a etapa anterior quando vazias?
  • Telas com abas densas ou tabelas largas usam 12 colunas em vez de split-screen 4+8 espremido?
  • Todos os rótulos técnicos de banco/código ((info), JSONB, Instanciar, enums crus) foram substituídos por linguagem natural do domínio?
  • O token secondary do tema Vuetify possui contraste escuro (≥ 4.5:1) em botões e chips variant="tonal" e variant="outlined"?
  • Quadros Kanban renderizam colunas lado a lado (overflow-x-auto) sem empilhar caixas vazias gigantes?
  • Existe navegação direta (drill-down) entre o Dashboard, a Visão de Detalhes e o Quadro Operacional?

Referências

  • Skill: skills/ux/SKILL.md (Paleta de cores, Lucide icons e padrões Vuetify)
  • Skill: skills/auditar-ux-heuristicas/SKILL.md (Heurísticas de Nielsen e estados de UI)
  • Skill: skills/testar-interface-agent-browser/SKILL.md (Validação visual E2E --headed)
  • Rule: rules/estilos-design-system.md (Design Systems Floreta e Betha)
  • Rule: rules/identidade-modulo.md (memorias-ia/modulo.yml)