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

18 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-26

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 7 Pilares da Usabilidade Funcional

Pilar 1 — Navegação no Menu Lateral Ordenada pela Jornada Operacional

O menu de navegação das páginas do módulo deve residir exclusivamente no componente de menu lateral de navegação (ex.: MenuLateral.vue / Sidebar), ordenado pela sequência lógica de trabalho do domínio:

  1. Ordem da Tarefa (Task-Order Navigation no Menu Lateral): A navegação lateral 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. Proibição de Menu Duplicado no Cabeçalho Superior: O cabeçalho superior (v-app-bar / Navbar) deve conter apenas o botão de acionamento do menu lateral, a identidade do módulo e o menu de usuário/notificações — nunca duplicar botões de navegação de páginas na barra superior.

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, Orçamento de Viewport e Anti-Aperto Visual (Progressive Disclosure)

Evitar empilhar listas mestras, formulários, barras de ferramentas e múltiplas abas analíticas na mesma dobra de tela. Pelo menos 70%–75% da área da janela (1366x768) deve pertencer ao conteúdo principal.

  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. Prevenção de Colisão de Painéis Laterais (Sidebar Mutual Exclusion):
    • Proibido manter abertos simultaneamente o Menu Lateral de Navegação (256px) e uma Gaveta Inspetora de Detalhes (400px–440px) quando isso espremer a área central.
    • Ao abrir o Painel Inspetor (Master-Detail) ou alternar para visões horizontais largas (Cronograma Gantt), o menu lateral esquerdo deve recolher automaticamente (auto-collapse).
  3. Teto de 2 Faixas no Topo e Criadores Sob Demanda:
    • Proibido empilhar 4 a 6 barras horizontais antes do conteúdo (Topbar + Header + Ações/KPIs + Abas/Filtros + Form Inline de Criação + Barra de Situação).
    • Consolidar o cabeçalho da visão em no máximo 2 faixas horizontais e abrir formulários de criação rápida (+ Nova Tarefa) sob demanda ao clicar no botão de ação, recolhendo-os após criar ou cancelar.
  4. Revelação Progressiva Intra-Painel (Inspetor em Acordeão e Zero Card Redundante):
    • Gavetas e painéis de detalhe (Side Sheets / Inspectors) nunca devem exibir um "Card de Resumo" que repete os dados já visíveis no item selecionado e nos campos abaixo, nem abrir 5+ seções ao mesmo tempo.
    • Manter abertas por padrão apenas as seções de Identificação/Prazo e Entrega, e usar acordeões colapsáveis com resumo no título (Recursos (2 • R$ 1.200,00), Pré-requisitos (1/1), Responsáveis (1)) para seções secundárias 1:N.
  5. Orçamento de Densidade por Linha (Teto de 3 Indicadores em Repouso):
    • Cada linha de árvore/lista ou card Kanban em repouso deve exibir no máximo 3 indicadores além do título (ex.: Checkbox/Ícone + Prazo ou Progresso + Bloqueio/Alerta), ocultando ações secundárias (+ Sub, Editar) até o :hover / :focus-within.
  6. 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).

Pilar 7 — Organização de Telas, Modais (Dialogs) e Painéis Laterais (Side Sheets) — Material Design 3

Conforme as diretrizes de Layout (Panes e Canonical Layouts), Dialogs e Side Sheets do Material Design 3 (https://m3.material.io/foundations/layout/understanding-layout/panes, https://m3.material.io/components/dialogs/guidelines e https://m3.material.io/components/side-sheets/guidelines):

  1. Matriz de Escolha de Superfície (Quando usar cada container):
    • Tela Principal / Single-Pane (12 colunas): Fluxos primários densos (tabelas amplas, múltiplas abas, cronogramas, formulários estruturantes).
    • Painel Lateral Coplanar (Standard Side Sheet, 360px–420px, sem scrim): Inspeção contextual de item selecionado na lista/árvore (Supporting Pane / Master-Detail leve) ou filtros avançados ao vivo, onde o usuário precisa comparar ou alternar itens na área principal simultaneamente. Recolhe automaticamente o menu lateral esquerdo.
    • Painel Lateral Modal (Modal Side Sheet, v-navigation-drawer temporary location="right", 400px–560px, com scrim): Formulários secundários de média complexidade (5 a 8 campos), histórico detalhado ou fluxos auxiliares que exigem foco exclusivo sem perder o contexto espacial da página ao fundo.
    • Modal Básico (Basic Dialog, v-dialog, max-width: 400px–560px): Modais são interruptivos por natureza e devem ser usados com parcimônia, exclusivamente para:
      1. Confirmações críticas ou destrutivas que exigem decisão imediata;
      2. Decisões rápidas ou criação enxuta (até 3 a 4 campos simples que não dependem de leitura da tela de fundo).
    • Modal de Tela Cheia (Full-Screen Dialog, v-dialog fullscreen): Tarefas modais complexas ou multi-etapas com barra superior fixa contendo Fechar (X) à esquerda, título em Sentence case e ação primária (Salvar) à direita.
    • Snackbar / Toast (v-snackbar): Feedback passivo de sucesso ou aviso curto de 1 frase. Proibido abrir um v-dialog apenas para exibir "Salvo com sucesso".
  2. Organização de Telas e Chunking Escaneável (Make Content Scannable):
    • Dividir telas e formulários longos em seções temáticas curtas (máximo de 4 a 6 campos relacionados por bloco) encabeçadas por título em Sentence case (16px–20px, peso 600, sem dois-pontos : e sem ponto final .).
    • Posicionar a informação mais importante no início do título/parágrafo (front-loading) e ocultar configurações raras ou detalhes técnicos sob demanda (Reveal details as needed).
  3. Anatomia e Regiões Fixas em Modais (M3 Dialog Anatomy & Pinned Regions):
    • Cabeçalho e Rodapé Fixos (Pinned Header & Footer): Evitar rolagem em Basic Dialogs; quando o conteúdo precisar rolar (ex.: lista de seleção), o Cabeçalho (v-card-title) no topo e a Barra de Ações (v-card-actions) no rodapé devem permanecer fixos e visíveis, rolando apenas o corpo central (v-card-text) com divisor sutil.
    • Título Específico + Consequência + Botão com Verbo: Título com pergunta direta ("Excluir etapa?"), corpo explicando a consequência sem repetir o título, e botões alinhados à direita ([Cancelar] + [Excluir etapa]), proibindo [Sim], [Não] ou [OK].
  4. Anatomia de Painéis Laterais (M3 Side Sheet Anatomy):
    • Header Fixo no Topo: Título conciso em Sentence case, botão explícito de fechar (X com aria-label="Fechar painel") à direita e, quando houver navegação multi-nível dentro do painel, botão de voltar (←) à esquerda do título.
    • Corpo em Seções e Acordeões: Até 2 seções primárias abertas; seções relacionais (1:N) em acordeões colapsáveis com resumo numérico no título.
    • Footer Fixo de Ações: Quando o painel exigir submissão manual, manter [Cancelar] e [Salvar alterações] fixos no rodapé do painel com divisor superior.

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 7 Pilares acima.
  3. Corrigir Tokens e Navegação Global:
    • Ajustar secondary em vuetify.ts caso esteja usando cor clara sem contraste.
    • Concentrar a navegação principal exclusivamente no componente de menu lateral (sem duplicar links na barra de cabeçalho superior) e ordenada pela jornada operacional.
  4. Desafogar Layouts, Organizar Modais/Painéis e Conectar Fluxos:
    • Substituir split-screens apertados (4+8) por seleção de contexto + área principal de 12 colunas.
    • Adequar modais e painéis à Matriz de Superfícies M3 (convertendo modais longos de 6+ campos em Side Sheets ou páginas, garantindo Pinned Header/Footer e botões com verbo específico).
    • 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) e salvar as evidências geradas em .evidencias/, conforme rules/testes-interface-agent-browser.md.

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

  • A navegação principal está concentrada exclusivamente no menu lateral (sem menu horizontal duplicado no cabeçalho superior) 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?
  • O cabeçalho operacional respeita o teto de 2 faixas horizontais (com criadores rápidos sob demanda) e recolhe o menu lateral automaticamente ao abrir o Inspetor de Detalhes?
  • Linhas de árvore/lista exibem no máximo 3 indicadores em repouso (sem "Natal de Badges") e o Inspetor usa seções colapsáveis (Acordeão) sem card de resumo duplicado?
  • A Matriz de Superfícies M3 é respeitada (Basic Dialog restrito a confirmações ou 3–4 campos com Header/Footer fixos; Side Sheet com botão fechar X e Footer fixo para formulários médios/inspeção; v-snackbar para avisos passivos)?
  • Formulários longos estão divididos em blocos temáticos de até 4–6 campos com títulos em Sentence case (sem : e sem .)?
  • Todos os rótulos técnicos de banco/código ((info), JSONB, Instanciar, enums crus) foram substituídos por linguagem natural do domínio em Sentence case?
  • 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

  • Material Design 3 — Writing Best Practices: https://m3.material.io/foundations/writing/best-practices
  • Material Design 3 — Layout, Dialogs & Side Sheets: https://m3.material.io/foundations/layout/understanding-layout/panes, https://m3.material.io/components/dialogs/guidelines, https://m3.material.io/components/side-sheets/guidelines
  • Rule: rules/mensagens-usuario.md (UX Writing M3 e linguagem do domínio)
  • Rule: rules/refactoring-ui-hierarquia-despoluicao.md (Hierarquia visual, pirâmide de ações, menos bordas e consolidação de tabelas — Refactoring UI)
  • Livro Refactoring UI (consulta online no Paiol): https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf
  • 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)