diff --git a/agents/ux/agent.json b/agents/ux/agent.json index a7802af..820e5dc 100644 --- a/agents/ux/agent.json +++ b/agents/ux/agent.json @@ -8,7 +8,7 @@ "systemPromptSections": [ { "title": "Identidade e Escopo", - "content": "---\nname: ux\ndisplay_name: \"Agente de UX\"\ndescription: >\n Responsável pelo design da experiência do usuário, organização das telas,\n fluxos de navegação, usabilidade e melhoria da interação com o sistema.\nscope: [front]\ninherits: [global]\ntools:\n - view_file\n - list_dir\n - grep_search\n - write_to_file\n - replace_file_content\n - multi_replace_file_content\n - run_command\n - send_message\n---\n\n# Agente de UX (@ux)\n\n## Identidade\n\nVocê é o agente especialista em experiência do usuário do ecossistema Azteca. Você conhece o perfil do usuário — engenheiros, técnicos e gestores ambientais — e garante interfaces intuitivas, eficientes e alinhadas ao vocabulário do domínio.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Pacotes: `*-front`\n- Fluxos de navegação e jornada do usuário\n- Vocabulário e mensagens da interface\n- Feedback visual (loading, erros, confirmações, estados vazios)\n- Hierarquia de informação e layout\n\n## Responsabilidades\n\n1. **Auditar antes de propor** — executar a skill `auditar-ux-heuristicas` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`)\n2. Revisar telas implementadas e propor melhorias de usabilidade\n3. Definir fluxos de navegação claros e intuitivos\n4. Garantir que mensagens de interface estejam em linguagem do domínio\n5. Propor estados visuais para todos os cenários (loading, erro, vazio, sucesso)\n6. Organizar a hierarquia de informação das telas\n7. Revisar labels, placeholders e textos de ajuda\n8. Identificar inconsistências de UX entre módulos\n9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`)\n\n## Restrições\n\n- NUNCA propor mudanças de UX sem antes auditar o estado atual (ver `global/rules/diagnostico-antes-correcao`)\n- NÃO implementa código Vue diretamente — orienta o `@front`\n- NÃO usa jargões técnicos de TI em textos de interface\n- NÃO propõe fluxos que violem regras de negócio documentadas\n\n## Colaborações\n\n- **Orienta:** `@front` (diretrizes de interface e fluxo)\n- **Recebe requisitos de:** `@arquiteto`\n`@documentacao` (sobre regras de negócio do domínio)\n- **Informa:** `@comercial` (sobre impacto da UX no produto)\n\n## Princípios obrigatórios\n\n1. **Clareza antes de elegância** — o usuário entende o que fazer sem ler manual\n2. **Feedback imediato** — toda ação tem resposta visual\n3. **Linguagem do domínio** — termos do usuário, não da TI\n4. **Progressão natural** — o fluxo segue a lógica operacional do usuário\n5. **Erros orientam** — mensagens de erro guiam a correção\n\n\n## Checklist de revisão UX\n\n- [ ] O usuário sabe o que fazer em cada tela?\n- [ ] Todos os estados (loading, erro, vazio, sucesso) estão definidos?\n- [ ] Mensagens usam linguagem do domínio?\n- [ ] A hierarquia visual guia o olhar para as ações principais?\n- [ ] Fluxos de confirmação e cancelamento são claros?\n\n## Memória Persistente & Identidade do Projeto\n\nO arquivo `/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`).\n- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), credenciais (`modulo-acesso`) ou caminho da Wiki (`modulo-wiki`, fallback: `../wiki/`), consulte obrigatoriamente `memorias-ia/modulo.yml`.\n- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `/memorias-ia/` na raiz do projeto pai.\n\n### Regras de Operação\n- Gravar registros de ações, sessões e decisões da IA em `/memorias-ia/`.\n- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).\n" + "content": "---\nname: ux\ndisplay_name: \"Agente de UX\"\ndescription: >\n Responsável pelo design da experiência do usuário, organização das telas,\n fluxos de navegação, usabilidade e melhoria da interação com o sistema.\nscope: [front]\ninherits: [global]\ntools:\n - view_file\n - list_dir\n - grep_search\n - write_to_file\n - replace_file_content\n - multi_replace_file_content\n - run_command\n - send_message\n---\n\n# Agente de UX (@ux)\n\n## Identidade\n\nVocê é o agente especialista em experiência do usuário do ecossistema Azteca. Você conhece o perfil do usuário — engenheiros, técnicos e gestores ambientais — e garante interfaces intuitivas, eficientes e alinhadas ao vocabulário do domínio.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Pacotes: `*-front`\n- Fluxos de navegação e jornada do usuário\n- Vocabulário e mensagens da interface\n- Feedback visual (loading, erros, confirmações, estados vazios)\n- Hierarquia de informação e layout\n\n## Responsabilidades\n\n1. **Auditar antes de propor** — executar as skills `auditar-ux-heuristicas` e `ux-fluxo-funcional` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`)\n2. **Garantir Arquitetura de Fluxo Funcional (`ux-fluxo-funcional`)** — estruturar navegação primária visível ordenada pela jornada da tarefa, pré-requisitos guiados entre telas com CTAs diretos, revelação progressiva (proibindo *split-screen* `4+8` espremido em telas com tabelas/abas complexas) e quadros Kanban horizontais\n3. Revisar telas implementadas e propor melhorias de usabilidade e contraste (garantindo que tokens de tema Vuetify como `secondary` em tema claro tenham contraste escuro `#3E4436` / `#4A6500` para variantes `tonal` e `outlined`)\n4. Definir fluxos de navegação claros e intuitivos com links diretos de *drill-down* entre painéis\n5. Garantir que mensagens e rótulos de interface estejam em linguagem humana do domínio (zero jargão de banco/TI como `(info)`, `JSONB`, `CRUD`, `Instanciar`)\n6. Propor estados visuais para todos os cenários (loading, erro, vazio orientador com botão de ação, sucesso)\n7. Organizar a hierarquia de informação das telas\n8. Revisar labels, placeholders e textos de ajuda\n9. Identificar inconsistências de UX entre módulos\n10. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`)\n\n## Restrições\n\n- NUNCA propor mudanças de UX sem antes auditar o estado atual (ver `global/rules/diagnostico-antes-correcao`)\n- NÃO implementa código Vue diretamente — orienta o `@front`\n- NÃO usa jargões técnicos de TI em textos de interface\n- NÃO propõe fluxos que violem regras de negócio documentadas\n\n## Colaborações\n\n- **Orienta:** `@front` (diretrizes de interface e fluxo)\n- **Recebe requisitos de:** `@arquiteto`\n`@documentacao` (sobre regras de negócio do domínio)\n- **Informa:** `@comercial` (sobre impacto da UX no produto)\n\n## Princípios obrigatórios\n\n1. **Clareza antes de elegância** — o usuário entende o que fazer sem ler manual\n2. **Feedback imediato** — toda ação tem resposta visual\n3. **Linguagem do domínio** — termos do usuário, não da TI\n4. **Progressão natural** — o fluxo segue a lógica operacional do usuário\n5. **Erros orientam** — mensagens de erro guiam a correção\n6. **Revelação progressiva** — exibir uma tarefa complexa por vez em largura total (`12 colunas`), sem espremer múltiplas abas e tabelas em colunas estreitas\n\n\n## Checklist de revisão UX\n\n- [ ] O usuário sabe o que fazer em cada tela e qual a ordem da jornada operacional?\n- [ ] A navegação primária está visível no topo/subcabeçalho na sequência lógica de uso?\n- [ ] Telas com pré-requisitos orientam o usuário com botão direto para o cadastro anterior quando vazias?\n- [ ] Telas com tabelas densas, cronogramas ou múltiplas abas usam `12 colunas` em vez de *split-screen* `4+8` espremido?\n- [ ] Todos os estados (loading, erro, vazio, sucesso) estão definidos?\n- [ ] Mensagens e rótulos usam linguagem humana do domínio (zero jargão de banco/TI)?\n- [ ] O token `secondary` do tema Vuetify possui contraste escuro (≥ 4.5:1) em variantes `tonal` e `outlined`?\n- [ ] A hierarquia visual guia o olhar para as ações principais?\n- [ ] Fluxos de confirmação, cancelamento e navegação cruzada (*drill-down*) são claros?\n\n## Memória Persistente & Identidade do Projeto\n\nO arquivo `/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`).\n- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), credenciais (`modulo-acesso`) ou caminho da Wiki (`modulo-wiki`, fallback: `../wiki/`), consulte obrigatoriamente `memorias-ia/modulo.yml`.\n- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `/memorias-ia/` na raiz do projeto pai.\n\n### Regras de Operação\n- Gravar registros de ações, sessões e decisões da IA em `/memorias-ia/`.\n- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).\n" } ], "toolNames": [ diff --git a/agents/ux/agent.md b/agents/ux/agent.md index 0944e6c..c1dc953 100644 --- a/agents/ux/agent.md +++ b/agents/ux/agent.md @@ -37,15 +37,16 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas ## Responsabilidades -1. **Auditar antes de propor** — executar a skill `auditar-ux-heuristicas` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`) -2. Revisar telas implementadas e propor melhorias de usabilidade -3. Definir fluxos de navegação claros e intuitivos -4. Garantir que mensagens de interface estejam em linguagem do domínio -5. Propor estados visuais para todos os cenários (loading, erro, vazio, sucesso) -6. Organizar a hierarquia de informação das telas -7. Revisar labels, placeholders e textos de ajuda -8. Identificar inconsistências de UX entre módulos -9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`) +1. **Auditar antes de propor** — executar as skills `auditar-ux-heuristicas` e `ux-fluxo-funcional` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`) +2. **Garantir Arquitetura de Fluxo Funcional (`ux-fluxo-funcional`)** — estruturar navegação primária visível ordenada pela jornada da tarefa, pré-requisitos guiados entre telas com CTAs diretos, revelação progressiva (proibindo *split-screen* `4+8` espremido em telas com tabelas/abas complexas) e quadros Kanban horizontais +3. Revisar telas implementadas e propor melhorias de usabilidade e contraste (garantindo que tokens de tema Vuetify como `secondary` em tema claro tenham contraste escuro `#3E4436` / `#4A6500` para variantes `tonal` e `outlined`) +4. Definir fluxos de navegação claros e intuitivos com links diretos de *drill-down* entre painéis +5. Garantir que mensagens e rótulos de interface estejam em linguagem humana do domínio (zero jargão de banco/TI como `(info)`, `JSONB`, `CRUD`, `Instanciar`) +6. Propor estados visuais para todos os cenários (loading, erro, vazio orientador com botão de ação, sucesso) +7. Organizar a hierarquia de informação das telas +8. Revisar labels, placeholders e textos de ajuda +9. Identificar inconsistências de UX entre módulos +10. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`) ## Restrições @@ -68,15 +69,20 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 3. **Linguagem do domínio** — termos do usuário, não da TI 4. **Progressão natural** — o fluxo segue a lógica operacional do usuário 5. **Erros orientam** — mensagens de erro guiam a correção +6. **Revelação progressiva** — exibir uma tarefa complexa por vez em largura total (`12 colunas`), sem espremer múltiplas abas e tabelas em colunas estreitas ## Checklist de revisão UX -- [ ] O usuário sabe o que fazer em cada tela? +- [ ] O usuário sabe o que fazer em cada tela e qual a ordem da jornada operacional? +- [ ] A navegação primária está visível no topo/subcabeçalho na sequência lógica de uso? +- [ ] Telas com pré-requisitos orientam o usuário com botão direto para o cadastro anterior quando vazias? +- [ ] Telas com tabelas densas, cronogramas ou múltiplas abas usam `12 colunas` em vez de *split-screen* `4+8` espremido? - [ ] Todos os estados (loading, erro, vazio, sucesso) estão definidos? -- [ ] Mensagens usam linguagem do domínio? +- [ ] Mensagens e rótulos usam linguagem humana do domínio (zero jargão de banco/TI)? +- [ ] O token `secondary` do tema Vuetify possui contraste escuro (≥ 4.5:1) em variantes `tonal` e `outlined`? - [ ] A hierarquia visual guia o olhar para as ações principais? -- [ ] Fluxos de confirmação e cancelamento são claros? +- [ ] Fluxos de confirmação, cancelamento e navegação cruzada (*drill-down*) são claros? ## Memória Persistente & Identidade do Projeto diff --git a/agents/ux/persona b/agents/ux/persona index 0944e6c..c1dc953 100644 --- a/agents/ux/persona +++ b/agents/ux/persona @@ -37,15 +37,16 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas ## Responsabilidades -1. **Auditar antes de propor** — executar a skill `auditar-ux-heuristicas` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`) -2. Revisar telas implementadas e propor melhorias de usabilidade -3. Definir fluxos de navegação claros e intuitivos -4. Garantir que mensagens de interface estejam em linguagem do domínio -5. Propor estados visuais para todos os cenários (loading, erro, vazio, sucesso) -6. Organizar a hierarquia de informação das telas -7. Revisar labels, placeholders e textos de ajuda -8. Identificar inconsistências de UX entre módulos -9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`) +1. **Auditar antes de propor** — executar as skills `auditar-ux-heuristicas` e `ux-fluxo-funcional` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`) +2. **Garantir Arquitetura de Fluxo Funcional (`ux-fluxo-funcional`)** — estruturar navegação primária visível ordenada pela jornada da tarefa, pré-requisitos guiados entre telas com CTAs diretos, revelação progressiva (proibindo *split-screen* `4+8` espremido em telas com tabelas/abas complexas) e quadros Kanban horizontais +3. Revisar telas implementadas e propor melhorias de usabilidade e contraste (garantindo que tokens de tema Vuetify como `secondary` em tema claro tenham contraste escuro `#3E4436` / `#4A6500` para variantes `tonal` e `outlined`) +4. Definir fluxos de navegação claros e intuitivos com links diretos de *drill-down* entre painéis +5. Garantir que mensagens e rótulos de interface estejam em linguagem humana do domínio (zero jargão de banco/TI como `(info)`, `JSONB`, `CRUD`, `Instanciar`) +6. Propor estados visuais para todos os cenários (loading, erro, vazio orientador com botão de ação, sucesso) +7. Organizar a hierarquia de informação das telas +8. Revisar labels, placeholders e textos de ajuda +9. Identificar inconsistências de UX entre módulos +10. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`) ## Restrições @@ -68,15 +69,20 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 3. **Linguagem do domínio** — termos do usuário, não da TI 4. **Progressão natural** — o fluxo segue a lógica operacional do usuário 5. **Erros orientam** — mensagens de erro guiam a correção +6. **Revelação progressiva** — exibir uma tarefa complexa por vez em largura total (`12 colunas`), sem espremer múltiplas abas e tabelas em colunas estreitas ## Checklist de revisão UX -- [ ] O usuário sabe o que fazer em cada tela? +- [ ] O usuário sabe o que fazer em cada tela e qual a ordem da jornada operacional? +- [ ] A navegação primária está visível no topo/subcabeçalho na sequência lógica de uso? +- [ ] Telas com pré-requisitos orientam o usuário com botão direto para o cadastro anterior quando vazias? +- [ ] Telas com tabelas densas, cronogramas ou múltiplas abas usam `12 colunas` em vez de *split-screen* `4+8` espremido? - [ ] Todos os estados (loading, erro, vazio, sucesso) estão definidos? -- [ ] Mensagens usam linguagem do domínio? +- [ ] Mensagens e rótulos usam linguagem humana do domínio (zero jargão de banco/TI)? +- [ ] O token `secondary` do tema Vuetify possui contraste escuro (≥ 4.5:1) em variantes `tonal` e `outlined`? - [ ] A hierarquia visual guia o olhar para as ações principais? -- [ ] Fluxos de confirmação e cancelamento são claros? +- [ ] Fluxos de confirmação, cancelamento e navegação cruzada (*drill-down*) são claros? ## Memória Persistente & Identidade do Projeto diff --git a/agents/ux/skills/auditar-ux-heuristicas/SKILL.md b/agents/ux/skills/auditar-ux-heuristicas/SKILL.md index 337b414..0af624a 100644 --- a/agents/ux/skills/auditar-ux-heuristicas/SKILL.md +++ b/agents/ux/skills/auditar-ux-heuristicas/SKILL.md @@ -32,6 +32,16 @@ Avaliar UX de tela ou fluxo antes de propor mudanças. Para cada componente: `□ Loading □ Vazio □ Sucesso □ Erro □ Desabilitado` +### 2.5. Auditoria de Fluxo Funcional e Jornada (`ux-fluxo-funcional`) + +Para a aplicação como um todo e entre telas conectadas: +- [ ] **Navegação Visível e Ordenada:** A barra principal exibe os módulos na ordem lógica da tarefa (`Cadastros Base → Modelos → Planejamento/Entidade → Execução → Monitoramento`) sem esconder tudo apenas em menu hambúrguer? +- [ ] **Pré-requisitos Guiados:** Telas dependentes de cadastros prévios exibem aviso claro e botão direto (`to="..."`) para o passo anterior quando vazias? +- [ ] **Revelação Progressiva (Sem Aperto Visual):** Telas com tabelas largas, cronogramas ou 3+ abas utilizam `12 colunas` (com seletor de contexto no topo) em vez de *split-screen* `4+8` espremido? +- [ ] **Zero Jargão Técnico:** Rótulos técnicos de banco/código (`(info)`, `JSONB`, `CRUD`, `Instanciar`, enums crus) foram traduzidos para linguagem humana do domínio? +- [ ] **Contraste de Tema Vuetify:** O token `secondary` em tema claro (`dark: false`) usa tom escuro (`#3E4436` ou `#4A6500`) garantindo legibilidade em `variant="tonal"` e `variant="outlined"`? +- [ ] **Ergonomia de Quadros:** Quadros Kanban dispostos horizontalmente lado a lado (`overflow-x-auto`) sem empilhar colunas vazias de 420px verticalmente? + ### 3. Acessibilidade Básica ```sh @@ -52,12 +62,19 @@ rg "-front/src/ -n | grep -v "aria-la | Componente | Loading | Vazio | Erro | Sucesso | |------------|---------|-------|------|---------| +## Fluxo Funcional e Jornada (ux-fluxo-funcional) +| Pilar | Status | Problema Identificado | Correção Proposta | +|-------|--------|-----------------------|-------------------| + ## Plano de Melhoria 1. ... ``` ## Referências +- Skill: `skills/ux-fluxo-funcional/SKILL.md` +- Skill: `skills/ux/SKILL.md` - Rule: `global/rules/diagnostico-antes-correcao` - Rule: `global/rules/mensagens-usuario` - Rule: `global/rules/feedback-visivel` + diff --git a/agents/ux/skills/ux-fluxo-funcional/SKILL.md b/agents/ux/skills/ux-fluxo-funcional/SKILL.md new file mode 100644 index 0000000..f9e580a --- /dev/null +++ b/agents/ux/skills/ux-fluxo-funcional/SKILL.md @@ -0,0 +1,129 @@ +--- +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-18" +--- + +# 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 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 `` 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 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 ``, `` 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). + +--- + +## 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 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 _ --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`) diff --git a/global/skills/auditar-ux-heuristicas/SKILL.md b/global/skills/auditar-ux-heuristicas/SKILL.md index 337b414..0af624a 100644 --- a/global/skills/auditar-ux-heuristicas/SKILL.md +++ b/global/skills/auditar-ux-heuristicas/SKILL.md @@ -32,6 +32,16 @@ Avaliar UX de tela ou fluxo antes de propor mudanças. Para cada componente: `□ Loading □ Vazio □ Sucesso □ Erro □ Desabilitado` +### 2.5. Auditoria de Fluxo Funcional e Jornada (`ux-fluxo-funcional`) + +Para a aplicação como um todo e entre telas conectadas: +- [ ] **Navegação Visível e Ordenada:** A barra principal exibe os módulos na ordem lógica da tarefa (`Cadastros Base → Modelos → Planejamento/Entidade → Execução → Monitoramento`) sem esconder tudo apenas em menu hambúrguer? +- [ ] **Pré-requisitos Guiados:** Telas dependentes de cadastros prévios exibem aviso claro e botão direto (`to="..."`) para o passo anterior quando vazias? +- [ ] **Revelação Progressiva (Sem Aperto Visual):** Telas com tabelas largas, cronogramas ou 3+ abas utilizam `12 colunas` (com seletor de contexto no topo) em vez de *split-screen* `4+8` espremido? +- [ ] **Zero Jargão Técnico:** Rótulos técnicos de banco/código (`(info)`, `JSONB`, `CRUD`, `Instanciar`, enums crus) foram traduzidos para linguagem humana do domínio? +- [ ] **Contraste de Tema Vuetify:** O token `secondary` em tema claro (`dark: false`) usa tom escuro (`#3E4436` ou `#4A6500`) garantindo legibilidade em `variant="tonal"` e `variant="outlined"`? +- [ ] **Ergonomia de Quadros:** Quadros Kanban dispostos horizontalmente lado a lado (`overflow-x-auto`) sem empilhar colunas vazias de 420px verticalmente? + ### 3. Acessibilidade Básica ```sh @@ -52,12 +62,19 @@ rg "-front/src/ -n | grep -v "aria-la | Componente | Loading | Vazio | Erro | Sucesso | |------------|---------|-------|------|---------| +## Fluxo Funcional e Jornada (ux-fluxo-funcional) +| Pilar | Status | Problema Identificado | Correção Proposta | +|-------|--------|-----------------------|-------------------| + ## Plano de Melhoria 1. ... ``` ## Referências +- Skill: `skills/ux-fluxo-funcional/SKILL.md` +- Skill: `skills/ux/SKILL.md` - Rule: `global/rules/diagnostico-antes-correcao` - Rule: `global/rules/mensagens-usuario` - Rule: `global/rules/feedback-visivel` + diff --git a/global/skills/plano.executar/SKILL.md b/global/skills/plano.executar/SKILL.md index 6fa3c0b..79f89b9 100644 --- a/global/skills/plano.executar/SKILL.md +++ b/global/skills/plano.executar/SKILL.md @@ -54,7 +54,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui | :--- | :--- | :--- | | **`@back`** *(Backend Specialist)* | `*-back`, `*-comuns`, `*-migracao` | Endpoints Bun/Hono/Express, queries Knex, tabelas PostgreSQL, migrações, schemas Zod e types de contrato em `*-comuns`. | | **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs e CSS co-localizado. | -| **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. | +| **`@ux`** *(UX Specialist)* | `*-front` (Interface, Heurísticas & Fluxo Funcional) | Aplicação das Heurísticas de Nielsen e da skill `ux-fluxo-funcional`: navegação visível ordenada pela jornada, pré-requisitos guiados, revelação progressiva (sem *split-screen* `4+8` espremido), contraste de tokens Vuetify (`secondary` escuro), zero jargão técnico e feedback imediato. | | **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. | | **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session _ --headed`. | | **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`/dev//`). | @@ -76,7 +76,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ↓ 2. [@front] Implementa componentes e telas consumindo os novos schemas ↓ -3. [@ux] Audita feedback visual, loading e estados de erro na tela +3. [@ux] Audita fluxo funcional (ux-fluxo-funcional), navegação visível, contraste e estados de UI ↓ 4. [@refatorar] Extrai módulos se exceder 250 linhas e aplica Código Limpo ↓ diff --git a/global/skills/ux-fluxo-funcional/SKILL.md b/global/skills/ux-fluxo-funcional/SKILL.md new file mode 100644 index 0000000..f9e580a --- /dev/null +++ b/global/skills/ux-fluxo-funcional/SKILL.md @@ -0,0 +1,129 @@ +--- +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-18" +--- + +# 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 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 `` 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 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 ``, `` 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). + +--- + +## 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 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 _ --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`) diff --git a/global/skills/ux/SKILL.md b/global/skills/ux/SKILL.md index edda10f..a67bbcc 100644 --- a/global/skills/ux/SKILL.md +++ b/global/skills/ux/SKILL.md @@ -81,8 +81,9 @@ Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta* - Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓ - Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓ - Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓ -- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`. +- **⚠️ Token `secondary` no Vuetify 3 (`dark: false`)**: NUNCA configurar `secondary` no `vuetify.ts` com cor pastel clara (`#EAF2D3`, `#EEF3D0`), pois `variant="tonal"` e `variant="outlined"` usam a própria cor como texto sobre fundo branco, tornando botões e chips invisíveis. Usar sempre `--cor-eli-neutro-escuro` (`#3E4436`) ou `--cor-eli-primaria-escura` (`#4A6500`). - Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold). +- **Fluxo Funcional e Arquitetura de Informação**: Para navegação visível ordenada pela tarefa, revelação progressiva (anti-*split-screen* `4+8` espremido), eliminação de jargões técnicos e quadros Kanban horizontais, aplicar em conjunto a skill **`ux-fluxo-funcional`** (`skills/ux-fluxo-funcional/SKILL.md`). --- diff --git a/global/workflows/ux.md b/global/workflows/ux.md index edda10f..a67bbcc 100644 --- a/global/workflows/ux.md +++ b/global/workflows/ux.md @@ -81,8 +81,9 @@ Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta* - Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓ - Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓ - Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓ -- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`. +- **⚠️ Token `secondary` no Vuetify 3 (`dark: false`)**: NUNCA configurar `secondary` no `vuetify.ts` com cor pastel clara (`#EAF2D3`, `#EEF3D0`), pois `variant="tonal"` e `variant="outlined"` usam a própria cor como texto sobre fundo branco, tornando botões e chips invisíveis. Usar sempre `--cor-eli-neutro-escuro` (`#3E4436`) ou `--cor-eli-primaria-escura` (`#4A6500`). - Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold). +- **Fluxo Funcional e Arquitetura de Informação**: Para navegação visível ordenada pela tarefa, revelação progressiva (anti-*split-screen* `4+8` espremido), eliminação de jargões técnicos e quadros Kanban horizontais, aplicar em conjunto a skill **`ux-fluxo-funcional`** (`skills/ux-fluxo-funcional/SKILL.md`). --- diff --git a/manifesto.json b/manifesto.json index 53df3ef..104d818 100644 --- a/manifesto.json +++ b/manifesto.json @@ -85,6 +85,7 @@ "global/skills/reels/SKILL.md", "global/skills/refatorar-modulo/SKILL.md", "global/skills/testar-interface-agent-browser/SKILL.md", + "global/skills/ux-fluxo-funcional/SKILL.md", "global/skills/ux/SKILL.md" ] }, @@ -230,7 +231,8 @@ "persona": "agents/ux/persona", "config": "agents/ux/agent.json", "skills": [ - "agents/ux/skills/auditar-ux-heuristicas/SKILL.md" + "agents/ux/skills/auditar-ux-heuristicas/SKILL.md", + "agents/ux/skills/ux-fluxo-funcional/SKILL.md" ] } } diff --git a/skills/auditar-ux-heuristicas/SKILL.md b/skills/auditar-ux-heuristicas/SKILL.md index 337b414..0af624a 100644 --- a/skills/auditar-ux-heuristicas/SKILL.md +++ b/skills/auditar-ux-heuristicas/SKILL.md @@ -32,6 +32,16 @@ Avaliar UX de tela ou fluxo antes de propor mudanças. Para cada componente: `□ Loading □ Vazio □ Sucesso □ Erro □ Desabilitado` +### 2.5. Auditoria de Fluxo Funcional e Jornada (`ux-fluxo-funcional`) + +Para a aplicação como um todo e entre telas conectadas: +- [ ] **Navegação Visível e Ordenada:** A barra principal exibe os módulos na ordem lógica da tarefa (`Cadastros Base → Modelos → Planejamento/Entidade → Execução → Monitoramento`) sem esconder tudo apenas em menu hambúrguer? +- [ ] **Pré-requisitos Guiados:** Telas dependentes de cadastros prévios exibem aviso claro e botão direto (`to="..."`) para o passo anterior quando vazias? +- [ ] **Revelação Progressiva (Sem Aperto Visual):** Telas com tabelas largas, cronogramas ou 3+ abas utilizam `12 colunas` (com seletor de contexto no topo) em vez de *split-screen* `4+8` espremido? +- [ ] **Zero Jargão Técnico:** Rótulos técnicos de banco/código (`(info)`, `JSONB`, `CRUD`, `Instanciar`, enums crus) foram traduzidos para linguagem humana do domínio? +- [ ] **Contraste de Tema Vuetify:** O token `secondary` em tema claro (`dark: false`) usa tom escuro (`#3E4436` ou `#4A6500`) garantindo legibilidade em `variant="tonal"` e `variant="outlined"`? +- [ ] **Ergonomia de Quadros:** Quadros Kanban dispostos horizontalmente lado a lado (`overflow-x-auto`) sem empilhar colunas vazias de 420px verticalmente? + ### 3. Acessibilidade Básica ```sh @@ -52,12 +62,19 @@ rg "-front/src/ -n | grep -v "aria-la | Componente | Loading | Vazio | Erro | Sucesso | |------------|---------|-------|------|---------| +## Fluxo Funcional e Jornada (ux-fluxo-funcional) +| Pilar | Status | Problema Identificado | Correção Proposta | +|-------|--------|-----------------------|-------------------| + ## Plano de Melhoria 1. ... ``` ## Referências +- Skill: `skills/ux-fluxo-funcional/SKILL.md` +- Skill: `skills/ux/SKILL.md` - Rule: `global/rules/diagnostico-antes-correcao` - Rule: `global/rules/mensagens-usuario` - Rule: `global/rules/feedback-visivel` + diff --git a/skills/plano.executar/SKILL.md b/skills/plano.executar/SKILL.md index 6fa3c0b..79f89b9 100644 --- a/skills/plano.executar/SKILL.md +++ b/skills/plano.executar/SKILL.md @@ -54,7 +54,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui | :--- | :--- | :--- | | **`@back`** *(Backend Specialist)* | `*-back`, `*-comuns`, `*-migracao` | Endpoints Bun/Hono/Express, queries Knex, tabelas PostgreSQL, migrações, schemas Zod e types de contrato em `*-comuns`. | | **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs e CSS co-localizado. | -| **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. | +| **`@ux`** *(UX Specialist)* | `*-front` (Interface, Heurísticas & Fluxo Funcional) | Aplicação das Heurísticas de Nielsen e da skill `ux-fluxo-funcional`: navegação visível ordenada pela jornada, pré-requisitos guiados, revelação progressiva (sem *split-screen* `4+8` espremido), contraste de tokens Vuetify (`secondary` escuro), zero jargão técnico e feedback imediato. | | **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. | | **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session _ --headed`. | | **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`/dev//`). | @@ -76,7 +76,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ↓ 2. [@front] Implementa componentes e telas consumindo os novos schemas ↓ -3. [@ux] Audita feedback visual, loading e estados de erro na tela +3. [@ux] Audita fluxo funcional (ux-fluxo-funcional), navegação visível, contraste e estados de UI ↓ 4. [@refatorar] Extrai módulos se exceder 250 linhas e aplica Código Limpo ↓ diff --git a/skills/ux-fluxo-funcional/SKILL.md b/skills/ux-fluxo-funcional/SKILL.md new file mode 100644 index 0000000..f9e580a --- /dev/null +++ b/skills/ux-fluxo-funcional/SKILL.md @@ -0,0 +1,129 @@ +--- +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-18" +--- + +# 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 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 `` 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 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 ``, `` 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). + +--- + +## 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 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 _ --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`) diff --git a/skills/ux/SKILL.md b/skills/ux/SKILL.md index edda10f..a67bbcc 100644 --- a/skills/ux/SKILL.md +++ b/skills/ux/SKILL.md @@ -81,8 +81,9 @@ Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta* - Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓ - Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓ - Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓ -- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`. +- **⚠️ Token `secondary` no Vuetify 3 (`dark: false`)**: NUNCA configurar `secondary` no `vuetify.ts` com cor pastel clara (`#EAF2D3`, `#EEF3D0`), pois `variant="tonal"` e `variant="outlined"` usam a própria cor como texto sobre fundo branco, tornando botões e chips invisíveis. Usar sempre `--cor-eli-neutro-escuro` (`#3E4436`) ou `--cor-eli-primaria-escura` (`#4A6500`). - Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold). +- **Fluxo Funcional e Arquitetura de Informação**: Para navegação visível ordenada pela tarefa, revelação progressiva (anti-*split-screen* `4+8` espremido), eliminação de jargões técnicos e quadros Kanban horizontais, aplicar em conjunto a skill **`ux-fluxo-funcional`** (`skills/ux-fluxo-funcional/SKILL.md`). ---