--- name: ux-fluxo-funcional description: > Arquitetura de Informação, Jornada Operacional Guiada, Revelação Progressiva (Progressive Disclosure) e Contraste Funcional em aplicações -front. Transforma telas isoladas em um fluxo contínuo, autoexplicativo e sem sobrecarga cognitiva. scope: global updatedAt: "2026-10-26" --- # Skill: UX de Fluxo Funcional e Jornada Guiada (`ux-fluxo-funcional`) ## Objetivo Garantir que qualquer aplicação `-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 `` 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 `` 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 ``, `` ou `` 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 `-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 _ --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`)