feat(ux): incorporar diretrizes de despoluicao visual e hierarquia do Refactoring UI e referenciar livro no Paiol
This commit is contained in:
commit
5b122a4abd
30 changed files with 961 additions and 99 deletions
Binary file not shown.
File diff suppressed because one or more lines are too long
|
|
@ -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`)?
|
||||
|
|
|
|||
|
|
@ -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`)?
|
||||
|
|
|
|||
166
agents/front/rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
166
agents/front/rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
|
|
@ -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`
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -38,15 +38,16 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
|||
## Responsabilidades
|
||||
|
||||
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 <modulo-id>_<contexto?>`)** 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`)
|
||||
2. **Garantir Arquitetura de Fluxo Funcional (`ux-fluxo-funcional`)** — estruturar navegação principal concentrada exclusivamente no `MenuLateral.vue` 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. **Aplicar Despoluição Visual e Hierarquia (*Refactoring UI*)** — exigir conformidade com `rules/refactoring-ui-hierarquia-despoluicao.md` (consulta completa em `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`): pirâmide de ações (apenas 1 ação primária sólida por vista; ações destrutivas discretas na listagem e botão vermelho sólido exclusivo para o modal de confirmação), eliminação de bordas excessivas e *Card-ception*, rótulos como último recurso, consolidação de colunas correlatas em tabelas (2 linhas por célula) e Lei da Proximidade nos espaçamentos
|
||||
4. 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`)
|
||||
5. Definir fluxos de navegação claros e intuitivos com links diretos de *drill-down* entre painéis
|
||||
6. 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`)
|
||||
7. Propor estados visuais para todos os cenários (loading, erro, vazio orientador com botão de ação e ocultação de filtros inúteis, sucesso)
|
||||
8. Organizar a hierarquia de informação das telas (3 níveis de cor de texto, 2 faixas de peso `400/500` e `600/700`, títulos contidos `16px–20px`)
|
||||
9. Revisar labels, placeholders e textos de ajuda
|
||||
10. Identificar inconsistências de UX entre módulos
|
||||
11. 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 <modulo-id>_<contexto?>`)** 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
|
||||
|
||||
|
|
@ -70,18 +71,21 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
|||
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
|
||||
7. **Despoluição visual (*Refactoring UI*)** — separar grupos por contraste de superfície ou espaçamento (sem *Card-ception* nem excesso de `<v-divider>`), enfatizar des-enfatizando elementos secundários, consolidar colunas em tabelas e respeitar a pirâmide de ações
|
||||
|
||||
|
||||
## Checklist de revisão UX
|
||||
|
||||
- [ ] 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?
|
||||
- [ ] A navegação principal está concentrada exclusivamente no `MenuLateral.vue` (sem duplicar links na `CabecalhoPrincipal.vue`) 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?
|
||||
- [ ] Todos os estados (loading, erro, vazio sem filtros inúteis, sucesso) estão definidos?
|
||||
- [ ] 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?
|
||||
- [ ] A pirâmide de ações é respeitada (apenas 1 botão primário sólido por vista; botões destrutivos discretos fora do modal de confirmação)?
|
||||
- [ ] A tela está livre de *Card-ception* (zero `v-card` com borda dentro de `v-card`), excesso de `<v-divider>` e pilhas redundantes de `Rótulo: Valor`?
|
||||
- [ ] Tabelas consolidam dados correlatos em células de 2 linhas (evitando 8+ colunas estreitas) e alinham números à direita com `tabular-nums`?
|
||||
- [ ] Fluxos de confirmação, cancelamento e navegação cruzada (*drill-down*) são claros?
|
||||
|
||||
## Memória Persistente & Identidade do Projeto
|
||||
|
|
|
|||
|
|
@ -38,15 +38,16 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
|||
## Responsabilidades
|
||||
|
||||
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 <modulo-id>_<contexto?>`)** 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`)
|
||||
2. **Garantir Arquitetura de Fluxo Funcional (`ux-fluxo-funcional`)** — estruturar navegação principal concentrada exclusivamente no `MenuLateral.vue` 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. **Aplicar Despoluição Visual e Hierarquia (*Refactoring UI*)** — exigir conformidade com `rules/refactoring-ui-hierarquia-despoluicao.md` (consulta completa em `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`): pirâmide de ações (apenas 1 ação primária sólida por vista; ações destrutivas discretas na listagem e botão vermelho sólido exclusivo para o modal de confirmação), eliminação de bordas excessivas e *Card-ception*, rótulos como último recurso, consolidação de colunas correlatas em tabelas (2 linhas por célula) e Lei da Proximidade nos espaçamentos
|
||||
4. 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`)
|
||||
5. Definir fluxos de navegação claros e intuitivos com links diretos de *drill-down* entre painéis
|
||||
6. 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`)
|
||||
7. Propor estados visuais para todos os cenários (loading, erro, vazio orientador com botão de ação e ocultação de filtros inúteis, sucesso)
|
||||
8. Organizar a hierarquia de informação das telas (3 níveis de cor de texto, 2 faixas de peso `400/500` e `600/700`, títulos contidos `16px–20px`)
|
||||
9. Revisar labels, placeholders e textos de ajuda
|
||||
10. Identificar inconsistências de UX entre módulos
|
||||
11. 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 <modulo-id>_<contexto?>`)** 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
|
||||
|
||||
|
|
@ -70,18 +71,21 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
|
|||
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
|
||||
7. **Despoluição visual (*Refactoring UI*)** — separar grupos por contraste de superfície ou espaçamento (sem *Card-ception* nem excesso de `<v-divider>`), enfatizar des-enfatizando elementos secundários, consolidar colunas em tabelas e respeitar a pirâmide de ações
|
||||
|
||||
|
||||
## Checklist de revisão UX
|
||||
|
||||
- [ ] 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?
|
||||
- [ ] A navegação principal está concentrada exclusivamente no `MenuLateral.vue` (sem duplicar links na `CabecalhoPrincipal.vue`) 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?
|
||||
- [ ] Todos os estados (loading, erro, vazio sem filtros inúteis, sucesso) estão definidos?
|
||||
- [ ] 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?
|
||||
- [ ] A pirâmide de ações é respeitada (apenas 1 botão primário sólido por vista; botões destrutivos discretos fora do modal de confirmação)?
|
||||
- [ ] A tela está livre de *Card-ception* (zero `v-card` com borda dentro de `v-card`), excesso de `<v-divider>` e pilhas redundantes de `Rótulo: Valor`?
|
||||
- [ ] Tabelas consolidam dados correlatos em células de 2 linhas (evitando 8+ colunas estreitas) e alinham números à direita com `tabular-nums`?
|
||||
- [ ] Fluxos de confirmação, cancelamento e navegação cruzada (*drill-down*) são claros?
|
||||
|
||||
## Memória Persistente & Identidade do Projeto
|
||||
|
|
|
|||
166
agents/ux/rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
166
agents/ux/rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
|
|
@ -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`
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -18,17 +18,17 @@ Garantir que qualquer aplicação `<modulo>-front` do ecossistema (identificada
|
|||
|
||||
## Os 6 Pilares da Usabilidade Funcional
|
||||
|
||||
### Pilar 1 — Navegação Primária Visível e Ordenada pela Jornada Operacional
|
||||
### Pilar 1 — Navegação no Menu Lateral 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.
|
||||
O menu de navegação das páginas do módulo deve residir **exclusivamente no menu lateral (`MenuLateral.vue`)**, ordenado pela sequência lógica de trabalho do domínio:
|
||||
|
||||
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. **Ordem da Tarefa (Task-Order Navigation no `MenuLateral.vue`):** A navegação lateral do módulo deve refletir a sequência lógica de trabalho do domínio:
|
||||
- `1. Cadastros Base / Pré-requisitos` (ex.: catálogos, recursos, equipes, parâmetros iniciais)
|
||||
- `2. Modelos / Configuração` (ex.: templates, padrões reutilizáveis)
|
||||
- `3. Entidade Principal / Planejamento` (ex.: registros centrais do módulo, cronogramas, estruturação)
|
||||
- `4. Execução Operacional` (ex.: quadros de trabalho, filas de atendimento, operação diária)
|
||||
- `5. Monitoramento / Indicadores` (ex.: dashboards executivos, relatórios consolidados)
|
||||
2. **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.
|
||||
2. **Proibição de Menu Duplicado no Cabeçalho (`CabecalhoPrincipal.vue`):** O `v-app-bar` superior deve conter apenas o botão de acionamento do menu lateral, a identidade do módulo e o menu de usuário/notificações — **nunca** duplicar botões de navegação de páginas na barra superior.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -98,7 +98,7 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
|
|||
2. **Auditar a Jornada Completa:** Inspecionar `App.vue`, `router/index.ts`, `plugins/vuetify.ts` e as views de `<modulo>-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`.
|
||||
- Concentrar a navegação principal exclusivamente em `MenuLateral.vue` (sem duplicar links na `CabecalhoPrincipal.vue`) e ordenada pela jornada operacional.
|
||||
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.
|
||||
|
|
@ -110,7 +110,7 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
|
|||
|
||||
## 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?
|
||||
- [ ] A navegação principal está concentrada exclusivamente no `MenuLateral.vue` (sem menu horizontal duplicado no cabeçalho) 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?
|
||||
|
|
@ -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`)
|
||||
|
|
|
|||
|
|
@ -17,10 +17,11 @@ Usado nos módulos voltados a empresas privadas e gestão corporativa.
|
|||
|
||||
### Características
|
||||
|
||||
- **Framework UI:** Vuetify (Vue 3) / `eli-vue`
|
||||
- **Cores:** paleta própria definida no tema Vuetify do projeto
|
||||
- **Tipografia:** controlada pelo tema Vuetify
|
||||
- **Componentes:** componentes Vuetify (`v-btn`, `v-card`, `v-data-table`, etc.)
|
||||
- **Framework UI:** Vuetify (Vue 3) / `eli-vue` ou Tailwind CSS v4 (módulos verdes e-Licencie `#688c00`)
|
||||
- **Cores:** paleta própria definida no tema do projeto (`#688c00` verde floresta e-Licencie)
|
||||
- **Tipografia Obrigatória:** **`Google Sans`** (Variable Font 100–900 carregada via `@font-face` do MinIO Paiol: `https://paiol.idz.one/estaticos/GoogleSans/GoogleSans-VariableFont_GRAD,opsz,wght.ttf` e `GoogleSans-Italic-VariableFont_GRAD,opsz,wght.ttf`). Proibido uso de fontes genéricas ou `font-mono` em badges/valores (usar `tabular-nums` com `Google Sans`).
|
||||
- **Iconografia Obrigatória:** **`@lucide/vue`** exclusivamente. É proibido usar `lucide-vue-next`, `@mdi/font`, SVGs inline ou caracteres Unicode/ASCII (`└`, `➔`) como ícones visuais.
|
||||
- **Componentes:** componentes Vuetify (`v-btn`, `v-card`, `v-data-table`, etc.) ou componentes modulares Vue 3
|
||||
- **Estilo visual:** moderno, tech, voltado a usabilidade corporativa
|
||||
|
||||
### Quando aplicar
|
||||
|
|
@ -184,6 +185,8 @@ import { eBetha } from "p-ambiente";
|
|||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- Betha Design System: https://design.plataforma.betha.cloud/doc/index.html
|
||||
- Framework Design CDN: https://cdn.betha.cloud/base/g4/design/4.0.0/
|
||||
- Rule: `refactoring-ui-hierarquia-despoluicao` (despoluição visual, hierarquia e espaçamento)
|
||||
- Livro *Refactoring UI* (Steve Schoger & Adam Wathan): `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
|
||||
- Rule: `css-global-betha` (variáveis --bth-*)
|
||||
- Rule: `theme-provider-mui-betha` (arquitetura ThemeProvider)
|
||||
- Rule: `modal-dialog-padrao-betha` (estrutura de modais)
|
||||
|
|
|
|||
|
|
@ -40,6 +40,9 @@ Em **toda execução de prompt**, o agente DEVE observar rigorosamente os três
|
|||
7. Flexibilidade e eficiência de uso (fluxos fluidos, ações diretas).
|
||||
8. Estética e design minimalista (interface limpa, sem ruído).
|
||||
9. Diagnóstico e recuperação de erros (mensagens claras e orientadoras).
|
||||
- **Hierarquia Visual e Despoluição de UI (*Refactoring UI* — Steve Schoger & Adam Wathan)**:
|
||||
- Aplicar obrigatoriamente a regra `global/rules/refactoring-ui-hierarquia-despoluicao` (pirâmide de ações com apenas 1 primária sólida por vista, eliminação de bordas e *cards* aninhados, consolidação de colunas em tabelas, Lei da Proximidade no espaçamento e rótulos como último recurso).
|
||||
- Obra completa de referência para consulta: `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
|
||||
- **Acessibilidade & Clareza Cognitiva**: Respeitar padrões de acessibilidade (WCAG) e garantir interface responsiva com feedbacks compreensíveis.
|
||||
|
||||
## Processo de Execução em 3 Etapas
|
||||
|
|
|
|||
166
global/rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
166
global/rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
|
|
@ -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`
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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>/`). |
|
||||
|
|
|
|||
|
|
@ -18,17 +18,17 @@ Garantir que qualquer aplicação `<modulo>-front` do ecossistema (identificada
|
|||
|
||||
## Os 6 Pilares da Usabilidade Funcional
|
||||
|
||||
### Pilar 1 — Navegação Primária Visível e Ordenada pela Jornada Operacional
|
||||
### Pilar 1 — Navegação no Menu Lateral 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.
|
||||
O menu de navegação das páginas do módulo deve residir **exclusivamente no menu lateral (`MenuLateral.vue`)**, ordenado pela sequência lógica de trabalho do domínio:
|
||||
|
||||
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. **Ordem da Tarefa (Task-Order Navigation no `MenuLateral.vue`):** A navegação lateral do módulo deve refletir a sequência lógica de trabalho do domínio:
|
||||
- `1. Cadastros Base / Pré-requisitos` (ex.: catálogos, recursos, equipes, parâmetros iniciais)
|
||||
- `2. Modelos / Configuração` (ex.: templates, padrões reutilizáveis)
|
||||
- `3. Entidade Principal / Planejamento` (ex.: registros centrais do módulo, cronogramas, estruturação)
|
||||
- `4. Execução Operacional` (ex.: quadros de trabalho, filas de atendimento, operação diária)
|
||||
- `5. Monitoramento / Indicadores` (ex.: dashboards executivos, relatórios consolidados)
|
||||
2. **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.
|
||||
2. **Proibição de Menu Duplicado no Cabeçalho (`CabecalhoPrincipal.vue`):** O `v-app-bar` superior deve conter apenas o botão de acionamento do menu lateral, a identidade do módulo e o menu de usuário/notificações — **nunca** duplicar botões de navegação de páginas na barra superior.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -98,7 +98,7 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
|
|||
2. **Auditar a Jornada Completa:** Inspecionar `App.vue`, `router/index.ts`, `plugins/vuetify.ts` e as views de `<modulo>-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`.
|
||||
- Concentrar a navegação principal exclusivamente em `MenuLateral.vue` (sem duplicar links na `CabecalhoPrincipal.vue`) e ordenada pela jornada operacional.
|
||||
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.
|
||||
|
|
@ -110,7 +110,7 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
|
|||
|
||||
## 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?
|
||||
- [ ] A navegação principal está concentrada exclusivamente no `MenuLateral.vue` (sem menu horizontal duplicado no cabeçalho) 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?
|
||||
|
|
@ -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`)
|
||||
|
|
|
|||
|
|
@ -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,18 +144,22 @@ 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?
|
||||
|
||||
#### Tipografia
|
||||
#### Tipografia — Google Sans (obrigatório)
|
||||
|
||||
- [ ] Tamanhos de fonte seguem a escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading)?
|
||||
- [ ] Textos longos usam `line-height: 1.5` para legibilidade?
|
||||
- [ ] Labels de formulário são visualmente distintos do conteúdo preenchido?
|
||||
- [ ] 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`.
|
||||
- [ ] 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
|
||||
|
||||
|
|
@ -169,9 +185,7 @@ Ao implementar melhorias, seguir os padrões do ecossistema:
|
|||
Todos os ícones do projeto devem vir exclusivamente da biblioteca **`@lucide/vue`** (dependência já instalada no `package.json`).
|
||||
|
||||
**Proibido**:
|
||||
- SVG inline manual (hardcoded no template)
|
||||
- Ícones de `@mdi/font` ou Material Design Icons em componentes do projeto
|
||||
- Bibliotecas alternativas (Font Awesome, Heroicons, etc.)
|
||||
- `lucide-vue-next`, `@mdi/font`, Font Awesome, Heroicons, SVGs inline manuais ou caracteres ASCII/Unicode (`└`, `➔`) como ícones.
|
||||
|
||||
**Como usar**:
|
||||
|
||||
|
|
@ -240,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 |
|
||||
|
|
@ -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,18 +144,22 @@ 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?
|
||||
|
||||
#### Tipografia
|
||||
#### Tipografia — Google Sans (obrigatório)
|
||||
|
||||
- [ ] Tamanhos de fonte seguem a escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading)?
|
||||
- [ ] Textos longos usam `line-height: 1.5` para legibilidade?
|
||||
- [ ] Labels de formulário são visualmente distintos do conteúdo preenchido?
|
||||
- [ ] 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`.
|
||||
- [ ] 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
|
||||
|
||||
|
|
@ -169,9 +185,7 @@ Ao implementar melhorias, seguir os padrões do ecossistema:
|
|||
Todos os ícones do projeto devem vir exclusivamente da biblioteca **`@lucide/vue`** (dependência já instalada no `package.json`).
|
||||
|
||||
**Proibido**:
|
||||
- SVG inline manual (hardcoded no template)
|
||||
- Ícones de `@mdi/font` ou Material Design Icons em componentes do projeto
|
||||
- Bibliotecas alternativas (Font Awesome, Heroicons, etc.)
|
||||
- `lucide-vue-next`, `@mdi/font`, Font Awesome, Heroicons, SVGs inline manuais ou caracteres ASCII/Unicode (`└`, `➔`) como ícones.
|
||||
|
||||
**Como usar**:
|
||||
|
||||
|
|
@ -240,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 |
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"versao": "3.3.0",
|
||||
"atualizadoEm": "2026-10-14",
|
||||
"versao": "3.4.0",
|
||||
"atualizadoEm": "2026-10-24",
|
||||
"projeto": "agnostico-submodulo",
|
||||
"identidade": "memorias-ia/modulo.yml",
|
||||
"artefatos": {
|
||||
|
|
@ -29,6 +29,7 @@
|
|||
"global/rules/mensagens-usuario.md",
|
||||
"global/rules/modal-dialog-padrao-betha.md",
|
||||
"global/rules/proibido-commit-ia.md",
|
||||
"global/rules/refactoring-ui-hierarquia-despoluicao.md",
|
||||
"global/rules/refatoracao-segura.md",
|
||||
"global/rules/regras-negocio-md.md",
|
||||
"global/rules/solid-compliance.md",
|
||||
|
|
@ -184,7 +185,8 @@
|
|||
"persona": "agents/front/persona",
|
||||
"config": "agents/front/agent.json",
|
||||
"rules": [
|
||||
"agents/front/rules/estrutura-vue.md"
|
||||
"agents/front/rules/estrutura-vue.md",
|
||||
"agents/front/rules/refactoring-ui-hierarquia-despoluicao.md"
|
||||
],
|
||||
"workflows": [
|
||||
"agents/front/workflows/adicionar-ajuda.md",
|
||||
|
|
@ -230,6 +232,9 @@
|
|||
"ux": {
|
||||
"persona": "agents/ux/persona",
|
||||
"config": "agents/ux/agent.json",
|
||||
"rules": [
|
||||
"agents/ux/rules/refactoring-ui-hierarquia-despoluicao.md"
|
||||
],
|
||||
"skills": [
|
||||
"agents/ux/skills/auditar-ux-heuristicas/SKILL.md",
|
||||
"agents/ux/skills/ux-fluxo-funcional/SKILL.md"
|
||||
|
|
|
|||
|
|
@ -185,6 +185,8 @@ import { eBetha } from "p-ambiente";
|
|||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- Betha Design System: https://design.plataforma.betha.cloud/doc/index.html
|
||||
- Framework Design CDN: https://cdn.betha.cloud/base/g4/design/4.0.0/
|
||||
- Rule: `refactoring-ui-hierarquia-despoluicao` (despoluição visual, hierarquia e espaçamento)
|
||||
- Livro *Refactoring UI* (Steve Schoger & Adam Wathan): `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
|
||||
- Rule: `css-global-betha` (variáveis --bth-*)
|
||||
- Rule: `theme-provider-mui-betha` (arquitetura ThemeProvider)
|
||||
- Rule: `modal-dialog-padrao-betha` (estrutura de modais)
|
||||
|
|
|
|||
|
|
@ -40,6 +40,9 @@ Em **toda execução de prompt**, o agente DEVE observar rigorosamente os três
|
|||
7. Flexibilidade e eficiência de uso (fluxos fluidos, ações diretas).
|
||||
8. Estética e design minimalista (interface limpa, sem ruído).
|
||||
9. Diagnóstico e recuperação de erros (mensagens claras e orientadoras).
|
||||
- **Hierarquia Visual e Despoluição de UI (*Refactoring UI* — Steve Schoger & Adam Wathan)**:
|
||||
- Aplicar obrigatoriamente a regra `global/rules/refactoring-ui-hierarquia-despoluicao` (pirâmide de ações com apenas 1 primária sólida por vista, eliminação de bordas e *cards* aninhados, consolidação de colunas em tabelas, Lei da Proximidade no espaçamento e rótulos como último recurso).
|
||||
- Obra completa de referência para consulta: `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
|
||||
- **Acessibilidade & Clareza Cognitiva**: Respeitar padrões de acessibilidade (WCAG) e garantir interface responsiva com feedbacks compreensíveis.
|
||||
|
||||
## Processo de Execução em 3 Etapas
|
||||
|
|
|
|||
166
rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
166
rules/refactoring-ui-hierarquia-despoluicao.md
Normal file
|
|
@ -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`
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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>/`). |
|
||||
|
|
|
|||
|
|
@ -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`)
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
Loading…
Add table
Add a link
Reference in a new issue