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

2026-10-24 14:32:52 -03:00 · 2026-10-24 14:32:52 -03:00 · 5b122a4abd
commit 5b122a4abd
parent ddb6d18f90 1a8adfc2dc
30 changed files with 961 additions and 99 deletions
--- a/agents/front/agent.json
+++ b/agents/front/agent.json
--- a/agents/front/agent.md
+++ b/agents/front/agent.md
@ -47,7 +47,8 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 8. Implementar fluxos de navegação e estados de interface
 9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
 10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
-11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (ver `rules/testes-interface-agent-browser.md`)
+11. **Garantir Despoluição Visual e Hierarquia (*Refactoring UI*)** — construir telas limpas, sem excesso de bordas/divisores ou *cards* aninhados (*Card-ception*), com pirâmide de ações estrita (apenas 1 botão primário sólido por vista e botões destrutivos discretos fora do modal de confirmação), consolidação de colunas correlatas em tabelas (2 linhas por célula) e espaçamento regido pela Lei da Proximidade (ver `rules/refactoring-ui-hierarquia-despoluicao.md` e `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`)
+12. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (ver `rules/testes-interface-agent-browser.md`)

 ## Restrições

@ -60,6 +61,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 - Mensagens visíveis ao usuário devem estar em linguagem do domínio, sem jargões técnicos
 - Schemas Zod importados de `*-comuns` — nunca redefinidos no front
 - NUNCA usar strings literais quando existirem enums no `*-comuns` (usar obrigatoriamente os enums/zEnums da respectiva aplicação para status, filtros, tipos, categorias e opções de UI)
+- NUNCA aninhar `v-card` com borda dentro de `v-card` (*Card-ception*), abusar de `<v-divider>` ou colocar múltiplos botões sólidos coloridos (`primary`, `success`, `error`) competindo na mesma seção (ver `rules/refactoring-ui-hierarquia-despoluicao.md`)
 - Ajuda de interface deve ser **obrigatoriamente** no formato Markdown co-localizado (`modalX.ajuda.md`)

 ## Colaborações
@ -87,7 +89,8 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 - [ ] `defineComponent` com `setup()` real?
 - [ ] Schemas importados de `*-comuns`?
 - [ ] Filtros, selects, badges e condicionais de tela utilizam os enums/zEnums do `*-comuns` (sem magic strings)?
- [ ] Estados de loading, erro e vazio implementados?
+- [ ] Estados de loading, erro e vazio implementados (ocultando filtros/paginação inúteis quando a base estiver vazia)?
+- [ ] Hierarquia visual e despoluição aplicadas (`refactoring-ui-hierarquia-despoluicao`: 1 único CTA sólido por vista, ações destrutivas discretas fora do modal, zero *Card-ception*, tabelas com colunas combinadas em 2 linhas e alinhamento numérico à direita com `tabular-nums`)?
 - [ ] Modal ou tela com ajuda possui arquivo co-localizado `{componente}.ajuda.md` (ex: `modalX.ajuda.md`)?
 - [ ] Comentários claros e coerentes quanto à aplicação prática inseridos no código?
 - [ ] Build passa (`tsc --noEmit` + `biome check`)?
--- a/agents/front/persona
+++ b/agents/front/persona
@ -47,7 +47,8 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 8. Implementar fluxos de navegação e estados de interface
 9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
 10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
-11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (ver `rules/testes-interface-agent-browser.md`)
+11. **Garantir Despoluição Visual e Hierarquia (*Refactoring UI*)** — construir telas limpas, sem excesso de bordas/divisores ou *cards* aninhados (*Card-ception*), com pirâmide de ações estrita (apenas 1 botão primário sólido por vista e botões destrutivos discretos fora do modal de confirmação), consolidação de colunas correlatas em tabelas (2 linhas por célula) e espaçamento regido pela Lei da Proximidade (ver `rules/refactoring-ui-hierarquia-despoluicao.md` e `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`)
+12. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (ver `rules/testes-interface-agent-browser.md`)

 ## Restrições

@ -60,6 +61,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 - Mensagens visíveis ao usuário devem estar em linguagem do domínio, sem jargões técnicos
 - Schemas Zod importados de `*-comuns` — nunca redefinidos no front
 - NUNCA usar strings literais quando existirem enums no `*-comuns` (usar obrigatoriamente os enums/zEnums da respectiva aplicação para status, filtros, tipos, categorias e opções de UI)
+- NUNCA aninhar `v-card` com borda dentro de `v-card` (*Card-ception*), abusar de `<v-divider>` ou colocar múltiplos botões sólidos coloridos (`primary`, `success`, `error`) competindo na mesma seção (ver `rules/refactoring-ui-hierarquia-despoluicao.md`)
 - Ajuda de interface deve ser **obrigatoriamente** no formato Markdown co-localizado (`modalX.ajuda.md`)

 ## Colaborações
@ -87,7 +89,8 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 - [ ] `defineComponent` com `setup()` real?
 - [ ] Schemas importados de `*-comuns`?
 - [ ] Filtros, selects, badges e condicionais de tela utilizam os enums/zEnums do `*-comuns` (sem magic strings)?
- [ ] Estados de loading, erro e vazio implementados?
+- [ ] Estados de loading, erro e vazio implementados (ocultando filtros/paginação inúteis quando a base estiver vazia)?
+- [ ] Hierarquia visual e despoluição aplicadas (`refactoring-ui-hierarquia-despoluicao`: 1 único CTA sólido por vista, ações destrutivas discretas fora do modal, zero *Card-ception*, tabelas com colunas combinadas em 2 linhas e alinhamento numérico à direita com `tabular-nums`)?
 - [ ] Modal ou tela com ajuda possui arquivo co-localizado `{componente}.ajuda.md` (ex: `modalX.ajuda.md`)?
 - [ ] Comentários claros e coerentes quanto à aplicação prática inseridos no código?
 - [ ] Build passa (`tsc --noEmit` + `biome check`)?
--- a/agents/front/rules/refactoring-ui-hierarquia-despoluicao.md
+++ b/agents/front/rules/refactoring-ui-hierarquia-despoluicao.md
@ -0,0 +1,166 @@
+---
+type: rule
+name: refactoring-ui-hierarquia-despoluicao
+description: Diretrizes obrigatórias do livro Refactoring UI (Steve Schoger & Adam Wathan) para eliminar poluição visual, excesso de bordas, botões concorrentes e falta de hierarquia nos frontends.
+scope: global
+trigger: always_on
+priority: alta
+updatedAt: "2026-10-24"
+---
+
+# Regra: Despoluição Visual e Hierarquia de UI (*Refactoring UI*)
+
+## Contexto
+
+Interfaces geradas sem disciplina de hierarquia visual tendem a sair **carregadas, barulhentas e confusas**: cartões dentro de cartões com bordas e divisores em excesso (*Card-ception*), múltiplos botões coloridos sólidos competindo por atenção, dezenas de pares `Rótulo: Valor` com mesmo peso visual, tabelas espremidas com 10+ colunas e formulários esticados por toda a tela.
+
+Toda construção ou refatoração em pacotes `*-front` (`@front`, `@ux`, `@land`) **DEVE** obedecer aos 6 pilares práticos de **Steve Schoger & Adam Wathan (*Refactoring UI*)**.
+
+- **Obra de referência completa (consulta online no Paiol):** `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
+
+---
+
+## Regra
+
+### 1. Hierarquia Visual por Peso e Contraste (Cap. 2 — *Hierarquia é Tudo*)
+
+1. **3 Níveis de Cor de Texto e 2 Pesos de Fonte:**
+   - **Pesos permitidos:** `400`/`500` para texto normal e `600`/`700` para ênfase (títulos, valores principais, células-chave). **Proibido** usar peso `< 400` ou fonte `< 12px` para des-enfatizar texto (reduz legibilidade).
+   - **Cores de texto:** Primário escuro (`--cor-eli-primaria-texto` `#2E3F00` ou `#212529`), Secundário médio (`--cor-eli-neutro` `#5E6553` ou `#495057`) e Terciário discreto para metadados auxiliares.
+2. **Enfatizar Des-enfatizando (*Emphasize by de-emphasizing*):**
+   - Quando um elemento principal não se destaca, **não** aumente sua fonte ou saturação indefinidamente: reduza o contraste dos elementos que competem com ele (itens inativos, textos de apoio, barras laterais sem caixas pesadas).
+3. **Rótulos são o Último Recurso (*Labels are a last resort*):**
+   - **Proibido** empilhar listas ingênuas de `Rótulo: Valor` vindas do banco de dados com igual peso visual.
+   - Omitir o rótulo quando o formato ou contexto já identifica o dado (CNPJ, e-mail, telefone, status, moeda, data) ou combinar rótulo + valor em frase natural (`"12 condicionantes pendentes"`, `"150,5 ha de área total"`).
+   - Quando o rótulo for necessário (ex.: cards de indicadores/KPIs), o **valor é o protagonista** (`20px–24px`, peso `600/700`, cor escura) e o rótulo é secundário (`12px`, cor neutra suave).
+4. **Separar Hierarquia Visual da Semântica HTML:**
+   - Tags `<h1>`, `<h2>`, `<h3>` em telas de aplicação funcionam como rótulos de seção: devem ser contidas (`16px–20px`, peso `600`), nunca títulos gigantes que roubam espaço da área de trabalho.
+5. **Equilibrar Peso e Contraste em Ícones (`@lucide/vue`):**
+   - Ícones têm maior densidade superficial que texto. Ao acompanhar um rótulo, o ícone deve ter contraste suavizado (`color` neutra/secundária, `:size="16"` a `"18"`, `:stroke-width="1.75"` ou `"2"`) para não pesar mais que o texto.
+6. **Proibido Texto Cinza ou Branco Translúcido em Fundos Coloridos:**
+   - Sobre fundos coloridos, texto secundário nunca deve ser cinza puro nem branco com `opacity` reduzida: escolher tom da mesma matiz com luminosidade ajustada (ex.: `#2E3F00` sobre `#EEF3D0`).
+
+### 2. Pirâmide de Ações: A Semântica é Secundária (Cap. 2, p. 60)
+
+1. **Apenas 1 Ação Primária Verdadeira por Vista/Seção:**
+   - Somente a ação principal da tela recebe botão sólido de alto contraste (`color="primary" variant="flat"`).
+2. **Ações Secundárias e Terciárias:**
+   - **Secundárias** (ex.: *Filtrar, Exportar, Voltar*): usar `variant="outlined"` ou `variant="tonal"` com cor neutra/secundária escura (`#3E4436` / `#495057`).
+   - **Terciárias** (ex.: *Cancelar, Limpar, Ver mais*): usar estilo discreto (`variant="text"`).
+3. **Ações Destrutivas Discretas Fora do Modal:**
+   - Ser uma ação destrutiva (*Excluir, Remover, Arquivar*) **NÃO** significa que o botão deva ser vermelho sólido e chamativo na página principal ou em cada linha da tabela.
+   - Na tela principal/listagem, ações destrutivas devem usar tratamento secundário/terciário discreto (`variant="text"` neutro com hover em `--cor-eli-erro`, ou agrupadas em `v-menu`). O botão vermelho sólido (`color="error" variant="flat"`) deve existir **exclusivamente dentro do modal de confirmação**.
+
+### 3. Anti-Ruído: Use Menos Bordas e Zero *Card-ception* (Cap. 7, p. 238)
+
+1. **Proibido Aninhar Cartões com Borda (*Card-ception*):**
+   - **NUNCA** colocar `v-card` com borda (`variant="outlined"` ou `border`) dentro de outro `v-card` com borda, nem inserir `<v-divider>` a cada par de linhas.
+2. **3 Alternativas Obrigatórias ao Excesso de Bordas:**
+   - **Contraste de superfície:** posicionar o card branco (`--cor-eli-superficie` `#FFFFFF`) diretamente sobre o fundo neutro da página (`--cor-eli-fundo` `#F2F3EE` ou `#EBEDF0`), dispensando bordas pesadas.
+   - **Sombra sutil de elevação:** usar `box-shadow` leve para delinear o container sem linha dura.
+   - **Espaçamento extra:** aumentar a distância entre grupos (`24px–32px`) em vez de desenhar linhas divisórias (`<v-divider>`).
+
+### 4. Espaço em Branco, Proximidade e Largura Ideal (Cap. 3, p. 66–99)
+
+1. **Começar com Espaço em Branco Generoso:**
+   - O respiro visual (`pa-6`, `ga-6`) é o padrão; compactar apenas deliberadamente em tabelas operacionais densas.
+2. **Evitar Espaçamento Ambíguo (Lei da Proximidade):**
+   - Deve haver **sempre mais espaço ao redor de um grupo do que dentro dele**:
+     - Entre label e input: `4px–6px`
+     - Entre um campo e o próximo campo: `16px–20px`
+     - Entre seções distintas de um formulário/tela: `32px–40px`
+3. **Não Preencher a Tela Inteira sem Necessidade:**
+   - Formulários simples, cartões de leitura ou configurações não devem ser esticados em `100%` da largura (`1360px+`). Limitar à largura ideal (`max-width: 640px–800px`) ou usar layout em 2 colunas assimétricas (título e texto explicativo da seção à esquerda em `4 cols` + card de campos à direita em `8 cols`).
+4. **Larguras Fixas Onde Necessário:**
+   - Não usar colunas fluidas percentuais para elementos que exigem largura fixa otimizada (menus laterais, colunas de ações, avatares, badges de status).
+
+### 5. Tabelas Escaneáveis e Tipografia Refinada (Caps. 4 e 7, p. 102–135, 242)
+
+1. **Combinar Colunas Relacionadas em Tabelas:**
+   - **Proibido** criar tabelas espremidas com 8–15 colunas onde cada campo vira uma coluna isolada.
+   - Combinar dados correlatos em uma única célula com hierarquia de 2 linhas (ex.: Linha 1 em `14px` peso `600` escuro com *Razão Social*; Linha 2 em `12px` peso `400` neutro com *CNPJ • Município/UF*).
+2. **Alinhamento e Ritmo Tipográfico:**
+   - Textos alinhados à esquerda; números, quantidades e valores monetários alinhados à **direita** com `font-variant-numeric: tabular-nums`.
+   - Comprimento de linha de parágrafos e textos de ajuda limitado a `45ch–75ch`.
+   - `line-height` inversamente proporcional ao tamanho da fonte: `1.15–1.25` para títulos grandes/números de KPI e `1.5` para corpo de texto.
+   - Alinhar pela linha de base (`align-baseline`) ao misturar tamanhos de fonte na mesma linha (ex.: título + subtítulo/contador).
+   - Textos em `UPPERCASE` (cabeçalhos de tabela, siglas, badges) devem ter tamanho reduzido (`11px–12px`), peso `600` e `letter-spacing: 0.05em`.
+
+### 6. Contraste Invertido, Ícones e Estados Vazios (Caps. 5, 6 e 7)
+
+1. **Contraste Invertido em Badges e Alertas (p. 162):**
+   - Evitar múltiplos chips/badges com fundo escuro saturado que competem com o botão primário. Usar **fundo claro suave (`stop 50/100`) + texto escuro da mesma matiz (`stop 800/900`)**. Nunca confiar apenas na cor (combinar com ícone ou rótulo explícito).
+2. **Tamanho Pretendido de Ícones e Bordas de Acento (p. 208, 224):**
+   - **Proibido** ampliar ícones de `16–24px` para `48px–64px` a seco (ficam grosseiros). Para destaque em *empty states* ou cabeçalhos de cards, manter o ícone em `20px–24px` dentro de um container arredondado (`40px–48px`) com fundo suave (`--cor-eli-primaria-bg`).
+   - Usar bordas de acento (`border-top` ou `border-left: 3px solid var(--cor-eli-primaria)`) em cards de resumo ou alertas para dar acabamento sem ruído.
+3. **Estados Vazios Despoluídos (p. 234):**
+   - Quando uma coleção estiver inicialmente vazia (zero registros criados), **ocultar barras de filtros secundárias, abas vazias e paginação**, exibindo somente o *Empty State* orientador com o botão de ação primária (CTA).
+
+---
+
+## Exemplos
+
+### ❌ Incorreto — Tela carregada (*Card-ception*, botões brigando e rótulos redundantes)
+
+```vue
+<v-card variant="outlined" class="pa-2">
+  <h1 class="text-h3">Listagem de Licenças</h1>
+  <v-divider class="my-2" />
+  <v-card variant="outlined" class="pa-2 mb-2">
+    <div><strong>Razão Social:</strong> Mineração Vale Verde</div>
+    <v-divider class="my-1" />
+    <div><strong>CNPJ:</strong> 12.345.678/0001-90</div>
+    <v-divider class="my-1" />
+    <div><strong>Status:</strong> Vigente</div>
+    <div class="d-flex ga-2 mt-2">
+      <v-btn color="primary" variant="flat">Editar</v-btn>
+      <v-btn color="success" variant="flat">Renovar</v-btn>
+      <v-btn color="warning" variant="flat">Exportar</v-btn>
+      <v-btn color="error" variant="flat">Excluir</v-btn>
+    </div>
+  </v-card>
+</v-card>
+```
+
+### ✅ Correto — Hierarquia clara, menos bordas e pirâmide de ações (*Refactoring UI*)
+
+```vue
+<section class="pa-6">
+  <header class="d-flex align-baseline justify-space-between mb-6">
+    <div>
+      <h1 class="text-h6 font-weight-semibold">Licenças Ambientais</h1>
+      <p class="text-body-2 text-medium-emphasis">12 licenças vigentes no período</p>
+    </div>
+    <div class="d-flex align-center ga-3">
+      <v-btn color="secondary" variant="outlined">Exportar</v-btn>
+      <v-btn color="primary" variant="flat">Nova Licença</v-btn>
+    </div>
+  </header>
+
+  <v-card flat class="pa-5 bg-surface rounded-lg">
+    <div class="d-flex align-center justify-space-between">
+      <div>
+        <div class="text-subtitle-1 font-weight-semibold">Mineração Vale Verde Ltda.</div>
+        <div class="text-caption text-medium-emphasis">12.345.678/0001-90 • Criciúma/SC</div>
+      </div>
+      <div class="d-flex align-center ga-2">
+        <v-btn color="secondary" variant="tonal" size="small">Renovar</v-btn>
+        <v-btn variant="text" size="small">Editar</v-btn>
+        <v-btn variant="text" color="error" size="small">Excluir</v-btn>
+      </div>
+    </div>
+  </v-card>
+</section>
+```
+
+## Impacto
+
+Elimina o aspecto amador, sobrecarregado e confuso das interfaces geradas pela IA, garantindo telas limpas, escaneáveis e com hierarquia visual profissional em todo o ecossistema.
+
+## Referências
+
+- Livro completo no Paiol: `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
+- Rule: `global/rules/estilos-design-system`
+- Skill: `skills/ux/SKILL.md`
+- Skill: `skills/ux-fluxo-funcional/SKILL.md`
+- Skill: `skills/auditar-ux-heuristicas/SKILL.md`
--- a/agents/front/skills/diagnosticar-saude-frontend/SKILL.md
+++ b/agents/front/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)