feat(ux): incorporar diretrizes de despoluicao visual e hierarquia do Refactoring UI e referenciar livro no Paiol

skills/auditar-ux-heuristicas/SKILL.md

@@ -42,6 +42,23 @@ Para a aplicação como um todo e entre telas conectadas:
 - [ ] **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?
 
+### 2.6. Auditoria de Despoluição Visual e Hierarquia (*Refactoring UI*)
+
+Verificar conformidade com `rules/refactoring-ui-hierarquia-despoluicao`:
+- [ ] **Pirâmide de Ações (1 Primária por Vista):** Existe apenas 1 botão sólido (`color="primary" variant="flat"`) por contexto, com secundárias em `outlined`/`tonal` e destrutivas discretas (`variant="text"` ou em `v-menu`, reservando vermelho sólido apenas para o modal de confirmação)?
+- [ ] **Zero *Card-ception* e Menos Bordas:** Os componentes evitam `v-card` com borda dentro de `v-card` e excesso de `<v-divider>`, separando grupos por contraste de superfície (`#FFFFFF` sobre `#F2F3EE`) ou espaçamento (`24px–32px`)?
+- [ ] **Rótulos como Último Recurso:** Dados autoexplicativos (CNPJ, e-mail, datas, status) ou frases combinadas evitam pilhas repetitivas de `Rótulo: Valor` com mesmo peso visual?
+- [ ] **Tabelas Enxutas (Colunas Combinadas):** Tabelas evitam 8+ colunas estreitas agrupando dados relacionados na mesma célula em 2 linhas (Título escuro `600` + subtítulo neutro `12px`) e alinham números à direita com `tabular-nums`?
+- [ ] **Lei da Proximidade e Largura Ideal:** O espaço externo entre grupos/campos (`16px–32px`) é maior que o espaço interno (`4px–8px`), e formulários simples respeitam `max-width: 640px–800px`?
+- [ ] **Estados Vazios Despoluídos:** Quando não há registros criados na base, filtros secundários e paginação são ocultados em favor apenas do *Empty State* orientador com CTA?
+
+```sh
+# Detectar excesso de divisores e possíveis cards aninhados
+rg "<v-divider" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
+# Detectar botões destrutivos vermelhos sólidos fora de modais de confirmação
+rg 'color="error"|<v-btn[^>]*error' --include='*.vue' <modulo>-front/src/ -n
+```
+
 ### 3. Acessibilidade Básica
 
 ```sh
@@ -72,6 +89,8 @@ rg "<v-btn\|<button" --include='*.vue' <modulo>-front/src/ -n | grep -v "aria-la
 
 ## Referências
 
+- Rule: `global/rules/refactoring-ui-hierarquia-despoluicao`
+- Livro *Refactoring UI* (Paiol): `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
 - Skill: `skills/ux-fluxo-funcional/SKILL.md`
 - Skill: `skills/ux/SKILL.md`
 - Rule: `global/rules/diagnostico-antes-correcao`

skills/diagnosticar-saude-frontend/SKILL.md

@@ -73,6 +73,19 @@ rg "Error:|Exception:|null|undefined|NaN" --include='*.vue' <modulo>-front/src/
 rg "snackbar\|toast\|notify\|mensagem\|alerta" --include='*.vue' --include='*.ts' <modulo>-front/src/ -n
 ```
 
+### 5.5. Verificar Poluição Visual e Hierarquia (*Refactoring UI*)
+
+```sh
+# Detectar excesso de linhas divisórias (<v-divider>) poluindo componentes
+rg "<v-divider" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
+
+# Detectar múltiplos botões sólidos ou destrutivos concorrentes na mesma tela
+rg 'variant="flat"|variant="elevated"|color="error"' --include='*.vue' <modulo>-front/src/ -n
+
+# Detectar ícones Lucide superdimensionados a seco (> 28px sem container)
+rg ':size="(3[2-9]|[4-9][0-9])"' --include='*.vue' <modulo>-front/src/ -n
+```
+
 ### 6. Gerar Relatório
 
 ```markdown
@@ -104,5 +117,7 @@ rg "snackbar\|toast\|notify\|mensagem\|alerta" --include='*.vue' --include='*.ts
 ## Referências
 
 - Rule: `global/rules/diagnostico-antes-correcao`
+- Rule: `global/rules/refactoring-ui-hierarquia-despoluicao`
+- Livro *Refactoring UI* (Paiol): `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
 - Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
 - Rule: `global/rules/estrutura-vue` (via front)

skills/plano.executar/SKILL.md

@@ -53,8 +53,8 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui
 | Especialista | Papel & Escopo de Atuação | Principais Responsabilidades |
 | :--- | :--- | :--- |
 | **`@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 & 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. |
+| **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs, CSS co-localizado e despoluição visual (`refactoring-ui-hierarquia-despoluicao`). |
+| **`@ux`** *(UX Specialist)* | `*-front` (Interface, Heurísticas, Fluxo Funcional & *Refactoring UI*) | Aplicação das Heurísticas de Nielsen, `ux-fluxo-funcional` e `refactoring-ui-hierarquia-despoluicao` (livro no Paiol: `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`): navegação exclusiva no `MenuLateral.vue` ordenada pela jornada, pré-requisitos guiados, revelação progressiva (`12 colunas`), pirâmide de ações (1 primária sólida; destrutivas discretas fora do modal), zero *Card-ception* / menos bordas, consolidação de colunas em tabelas, 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 <modulo>_<contexto?> --headed`. |
 | **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `<modulo-wiki>/` | 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 (`<modulo-wiki>/dev/<modulo-id>/`). |

skills/ux-fluxo-funcional/SKILL.md

@@ -122,6 +122,8 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
 
 ## Referências
 
+- 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`)

skills/ux/SKILL.md

@@ -84,6 +84,7 @@ Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta*
 - **⚠️ 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`).
+- **Despoluição Visual e Hierarquia (*Refactoring UI*)**: Aplicar obrigatoriamente a regra **`refactoring-ui-hierarquia-despoluicao`** (`rules/refactoring-ui-hierarquia-despoluicao.md`) e consultar o livro de referência em `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`.
 
 ---
 
@@ -118,12 +119,23 @@ Para cada elemento da interface, avaliar:
 - [ ] Ícones acompanham texto quando a ação não é universalmente reconhecível?
 - [ ] O estado vazio (empty state) orienta o usuário sobre o próximo passo?
 
-#### Hierarquia visual
+#### Hierarquia visual e Pirâmide de Ações (*Refactoring UI*)
 
-- [ ] O olho do usuário é guiado para a ação principal primeiro?
-- [ ] Ações primárias usam `--cor-eli-primaria` (`#688C00`) com destaque?
-- [ ] Ações secundárias são visuais mas não competem com a primária?
-- [ ] Ações destrutivas (Excluir, Limpar) usam `--cor-eli-erro` com variante `text` ou `outlined`?
+- [ ] O olho do usuário é guiado para a ação principal primeiro (apenas **1 ação primária sólida** `variant="flat"` por vista/seção)?
+- [ ] Ações primárias usam `--cor-eli-primaria` (`#688C00`) com destaque, secundárias usam `outlined`/`tonal` e terciárias usam `text`?
+- [ ] Ações destrutivas (Excluir, Limpar, Remover) na tela principal são discretas (`variant="text"` ou em `v-menu`), reservando o botão vermelho sólido exclusivamente para o **modal de confirmação**?
+- [ ] Rótulos óbvios foram omitidos ou combinados com o valor (`"12 condicionantes"`, CNPJ/e-mail pelo formato) em vez de pilhas repetitivas de `Rótulo: Valor`?
+- [ ] Em cards de indicadores/KPIs, o valor numérico é o protagonista (`20px–24px`, peso `600/700`) e o rótulo é secundário (`12px`, cor neutra)?
+- [ ] Títulos de seção (`h1`–`h3`) têm tamanho contido (`16px–20px`, peso `600`) sem roubar espaço do conteúdo?
+
+#### Despoluição de Containers e Tabelas (*Use Fewer Borders*)
+
+- [ ] A tela está livre de *Card-ception* (zero `v-card` com borda aninhado dentro de outro `v-card` com borda)?
+- [ ] A separação entre grupos prioriza contraste de superfície (`#FFFFFF` sobre `#F2F3EE`), sombra sutil ou espaçamento extra (`24px–32px`) em vez de linhas `<v-divider>` em tudo?
+- [ ] Tabelas consolidam dados relacionados em uma mesma célula de 2 linhas (ex.: *Razão Social* em negrito + *CNPJ • Cidade/UF* abaixo em `12px` neutro), evitando 8+ colunas estreitas?
+- [ ] Colunas numéricas e monetárias estão alinhadas à direita com `tabular-nums`?
+- [ ] Badges e chips usam contraste invertido (fundo pastel claro + texto escuro da mesma matiz) em vez de múltiplas pílulas saturadas escuras?
+- [ ] Quando a listagem está inicialmente vazia (zero registros), barras de filtros secundárias e paginação inúteis são ocultadas?
 
 #### Feedback e estados
 
@@ -132,10 +144,11 @@ Para cada elemento da interface, avaliar:
 - [ ] Erros de formulário aparecem próximos ao campo com mensagem descritiva, usando `--cor-eli-erro` + `--cor-eli-erro-bg`?
 - [ ] Sucesso de operações tem confirmação visual (snackbar, toast, badge) com `--cor-eli-sucesso`?
 
-#### Densidade e espaçamento
+#### Densidade, espaçamento e Lei da Proximidade
 
-- [ ] O espaçamento segue múltiplos de 4px (4, 8, 12, 16, 24, 32)?
-- [ ] Em desktop, o espaço horizontal é bem aproveitado? (ex: grids de 2+ colunas para formulários largos)
+- [ ] O espaçamento começa generoso (`pa-6`, `ga-6`) e segue a escala do sistema (4, 8, 12, 16, 24, 32, 48)?
+- [ ] A **Lei da Proximidade** é respeitada (espaço entre campos `16px–20px` > espaço entre label e input `4px–6px`; espaço entre seções `32px+`)?
+- [ ] Formulários simples e cards de leitura respeitam sua largura ideal (`max-width: 640px–800px` ou layout `4+8` com título de seção à esquerda + inputs à direita) sem esticar inputs por `1400px`?
 - [ ] Em mobile, os elementos empilham verticalmente sem quebra visual?
 - [ ] Modais têm largura proporcional ao conteúdo?
 
@@ -143,7 +156,10 @@ Para cada elemento da interface, avaliar:
 
 - [ ] A fonte **`Google Sans`** (Variable Font 100–900 via `@font-face` de `https://paiol.idz.one/estaticos/GoogleSans/GoogleSans-VariableFont_GRAD,opsz,wght.ttf`) está aplicada em todo o sistema (`--font-sans` e `--eli-font-family`)?
 - [ ] Proibido `font-mono` em contadores, códigos e valores: usar `tabular-nums` com `Google Sans`.
-- [ ] Escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading); `line-height: 1.5` em textos longos.
+- [ ] Apenas 2 faixas de peso (`400/500` normal e `600/700` ênfase, nunca `< 400`) e 3 níveis de cor de texto (primário escuro, secundário médio, terciário suave)?
+- [ ] Escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading); `line-height: 1.5` em textos longos (`45ch–75ch`), `1.15–1.25` em títulos/KPIs e `letter-spacing: 0.05em` em textos `UPPERCASE`?
+- [ ] Tamanhos de fonte diferentes na mesma linha estão alinhados pela linha de base (`align-baseline`)?
+- [ ] Ícones de destaque em *empty states* ou cabeçalhos mantêm tamanho nativo (`20px–24px`) dentro de container arredondado (`40px–48px`) com fundo pastel suave, nunca inflados a seco para `48px+`?
 
 #### Acessibilidade básica
 
@@ -238,8 +254,12 @@ Após implementar:
 | ❌ Anti-padrão | ✅ Alternativa |
 |---|---|
 | Botão sem label de texto | Botão com ícone + texto, ou `aria-label` descritivo |
-| Cor vermelha para ação primária | Vermelho apenas para destrutivas; primária usa `--cor-eli-primaria` |
+| Cor vermelha sólida para botão Excluir na tabela | Usar `variant="text"` discreto na linha e vermelho sólido apenas no modal de confirmação |
+| Múltiplos botões sólidos (`primary`, `success`, `warning`) lado a lado | Pirâmide de ações: 1 primário `flat`, secundários `outlined`/`tonal` e terciários `text` |
+| *Card-ception* (`v-card` com borda dentro de `v-card` + `v-divider`) | Separar seções por contraste de superfície (`#FFFFFF` sobre `#F2F3EE`) ou espaçamento (`24px–32px`) |
+| Pilha de `Rótulo: Valor` com mesmo peso visual | Omitir rótulos óbvios pelo formato ou combinar em frase; destacar o dado e suavizar o rótulo |
 | Modal com scroll extenso | Dividir em etapas ou usar drawer lateral |
-| Tabela com 15+ colunas visíveis | Usar modal de colunas para ocultar secundárias |
+| Tabela com 10–15+ colunas estreitas | Consolidar colunas correlatas em célula de 2 linhas (Título + metadado secundário) |
+| Ícone inflado a seco (`48px–64px`) | Ícone `20px–24px` dentro de badge arredondado (`40px–48px`) com fundo pastel |
 | Estilos inline em template | Usar `<style scoped>` com tokens CSS e fallback |
 | Cor hex hardcoded | Usar `var(--cor-eli-primaria, #688C00)` com fallback |