.
This commit is contained in:
parent
1adf19b92d
commit
1388a121bc
65 changed files with 157 additions and 5166 deletions
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: jsdoc-padrao
|
||||
description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
|
||||
scope: global
|
||||
trigger: file_match
|
||||
globs:
|
||||
- "**/*.ts"
|
||||
- "**/*.tsx"
|
||||
- "**/*.vue"
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Regra: Documentação em Código
|
||||
|
||||
## 1. JSDoc — Princípios
|
||||
|
||||
- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa.
|
||||
- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários.
|
||||
|
||||
## 2. JSDoc obrigatório em funções compartilhadas
|
||||
|
||||
Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Busca detalhes da entidade e calcula privilégios aplicáveis.
|
||||
* Não utilizar em processamento em lote para evitar sobrecarga.
|
||||
*
|
||||
* @param tenantId - Identificador do tenant no sistema
|
||||
* @param entityId - ID do registro na base de dados
|
||||
* @returns Objeto consolidado ou `null` se não encontrado
|
||||
*/
|
||||
export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
|
||||
```
|
||||
|
||||
## 3. Casts temporários — justificativa obrigatória
|
||||
|
||||
Coerções agressivas requerem comentário explicando o porquê:
|
||||
|
||||
```typescript
|
||||
// Necessário: biblioteca externa não provê tipagem genérica na versão atual
|
||||
const dados = payload.raw as unknown as RespostaFormatada
|
||||
```
|
||||
|
||||
## 4. TODOs estruturados
|
||||
|
||||
Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
|
||||
|
||||
- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API`
|
||||
- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos`
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar.
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `.agent/rules/typescript-sem-any.global.md`
|
||||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: escrita-natural
|
||||
trigger: context_match
|
||||
description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica.
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
ativacao: >
|
||||
Aplicar quando o agente estiver produzindo textos comerciais, de marketing,
|
||||
orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo.
|
||||
NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio).
|
||||
---
|
||||
|
||||
# Regra: Escrita Estratégica e Natural
|
||||
|
||||
## 🎯 Objetivo
|
||||
|
||||
Produzir textos que:
|
||||
|
||||
- Mostrem domínio real do problema
|
||||
- Se destaquem entre propostas genéricas
|
||||
- Soem humanos, não institucionais
|
||||
- Convençam com clareza e impacto
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Princípios obrigatórios
|
||||
|
||||
### 1. Começar pelo problema real
|
||||
|
||||
Evitar introduções genéricas.
|
||||
|
||||
❌
|
||||
"O presente projeto tem como objetivo..."
|
||||
|
||||
✅
|
||||
"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios."
|
||||
|
||||
---
|
||||
|
||||
### 2. Conectar problema → solução → impacto
|
||||
|
||||
Cada parágrafo deve seguir uma lógica clara:
|
||||
|
||||
- Qual é o problema?
|
||||
- Como a solução resolve?
|
||||
- O que muda na prática?
|
||||
|
||||
✅ Exemplo:
|
||||
"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho."
|
||||
|
||||
---
|
||||
|
||||
### 3. Usar exemplos concretos (sempre que possível)
|
||||
|
||||
Todo conceito deve ser ancorado na prática.
|
||||
|
||||
❌
|
||||
"A solução permite coleta de dados estruturados."
|
||||
|
||||
✅
|
||||
"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet."
|
||||
|
||||
---
|
||||
|
||||
### 4. Escrever como quem vive o problema
|
||||
|
||||
O texto deve ter contexto real:
|
||||
|
||||
- campo
|
||||
- operação
|
||||
- prefeitura
|
||||
- equipe técnica
|
||||
|
||||
✅
|
||||
"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos."
|
||||
|
||||
---
|
||||
|
||||
### 5. Persuasão baseada em impacto real
|
||||
|
||||
Evitar adjetivos vazios.
|
||||
|
||||
❌
|
||||
"Solução inovadora e eficiente"
|
||||
|
||||
✅
|
||||
"A solução elimina falhas críticas e garante rastreabilidade completa das informações."
|
||||
|
||||
---
|
||||
|
||||
### 6. Linguagem natural (sem burocracia)
|
||||
|
||||
Preferir:
|
||||
|
||||
- "Com a solução..."
|
||||
- "Na prática..."
|
||||
- "Isso permite..."
|
||||
- "Como resultado..."
|
||||
|
||||
Evitar:
|
||||
|
||||
- "Dessa forma"
|
||||
- "Destarte"
|
||||
- "O presente projeto"
|
||||
|
||||
---
|
||||
|
||||
### 7. Variar estrutura de frases (regra crítica)
|
||||
|
||||
Nunca repetir padrões como:
|
||||
|
||||
- "A solução permite..."
|
||||
- "O sistema permite..."
|
||||
|
||||
Alternar com:
|
||||
|
||||
- "Na prática, o técnico..."
|
||||
- "Com isso..."
|
||||
- "Isso reduz..."
|
||||
- "Como resultado..."
|
||||
|
||||
---
|
||||
|
||||
### 8. Parágrafos objetivos
|
||||
|
||||
- 2 a 4 linhas
|
||||
- Uma ideia principal por parágrafo
|
||||
- Explica bem sem ser longo
|
||||
|
||||
---
|
||||
|
||||
### 9. Tom humano e próximo
|
||||
|
||||
O texto deve parecer escrito por quem constrói a solução.
|
||||
|
||||
✅
|
||||
"A solução resolve um problema real que impacta o dia a dia das equipes."
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Proibido
|
||||
|
||||
- Texto genérico que serve para qualquer projeto
|
||||
- Parágrafos longos sem exemplo
|
||||
- Repetição de estrutura
|
||||
- Uso de termos sem explicação prática
|
||||
- Linguagem excessivamente institucional
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Checklist final
|
||||
|
||||
Antes de finalizar:
|
||||
|
||||
- [ ] O problema está claro?
|
||||
- [ ] Existe exemplo prático?
|
||||
- [ ] O impacto está explícito?
|
||||
- [ ] O texto soa humano?
|
||||
- [ ] Há repetição de estrutura?
|
||||
- [ ] Parece algo real ou genérico?
|
||||
|
||||
---
|
||||
|
||||
## 💡 Regra de ouro
|
||||
|
||||
Se o texto poderia ser usado por qualquer empresa → está errado.
|
||||
|
||||
Se parece que vem de quem vive o problema → está certo.
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
type: workflow
|
||||
name: comercial
|
||||
description: Criar uma descrição comercial das funcionalidades e do sistema
|
||||
scope: global
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ updatedAt: "2026-06-01"
|
|||
|
||||
Este workflow gera uma descrição comercial de funcionalidades ou do sistema completo, escrita na pasta `./COMERCIAL/`. Cada módulo ou funcionalidade gera um arquivo separado com o padrão `./COMERCIAL/<nome-do-modulo>.md`.
|
||||
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ O arquivo `./COMERCIAL/<nome-do-modulo>.md` deve seguir esta estrutura:
|
|||
|
||||
## Referências
|
||||
|
||||
- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
|
||||
- Workflow: `.agent/workflows/orcamento.global.md` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
|
||||
- Workflow: `.agent/workflows/marketing.global.md` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
|
||||
- Workflow: `.agent/workflows/otimizar-codigos.global.md` (para documentação técnica, não comercial)
|
||||
- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação)
|
||||
- Workflow: `agents/ag-comercial/workflows/orcamento.md` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
|
||||
- Workflow: `agents/ag-comercial/workflows/marketing.md` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
|
||||
- Workflow: `global/workflows/otimizar-codigos.md` (para documentação técnica, não comercial)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
type: workflow
|
||||
name: marketing
|
||||
description: Criar peças de marketing digital para funcionalidades e módulos do sistema
|
||||
scope: global
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ updatedAt: "2026-06-01"
|
|||
|
||||
Este workflow gera peças de marketing digital prontas para uso em canais como LinkedIn, Instagram, WhatsApp e E-mail. O resultado é salvo na pasta `./COMERCIAL/` junto ao arquivo comercial do módulo correspondente, ou em arquivo separado `./COMERCIAL/<nome-do-modulo>-marketing.md`.
|
||||
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow.
|
||||
|
||||
O agente deve atuar como **especialista em marketing digital voltado para o setor do produto (venda entre empresas)**, aplicando técnicas comprovadas de texto persuasivo e engajamento.
|
||||
|
||||
|
|
@ -205,5 +205,5 @@ O resultado deve ser salvo em `./COMERCIAL/<nome-do-modulo>-marketing.md` ou adi
|
|||
|
||||
## Referências
|
||||
|
||||
- Workflow: `.agent/workflows/comercial.global.md` (gera os blocos A e B que alimentam o marketing)
|
||||
- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
|
||||
- Workflow: `agents/ag-comercial/workflows/comercial.md` (gera os blocos A e B que alimentam o marketing)
|
||||
- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
type: workflow
|
||||
name: orcamento
|
||||
description: Criar texto de orçamento pronto para copiar e colar em peças de orçamento/proposta
|
||||
scope: global
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ updatedAt: "2026-06-01"
|
|||
|
||||
Este workflow gera textos prontos para **copiar e colar dentro de documentos de orçamento e propostas comerciais**. O resultado é salvo na pasta `./COMERCIAL/` com o sufixo `-orcamento` (ex: `./COMERCIAL/<nome-do-modulo>-orcamento.md`).
|
||||
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -129,6 +129,6 @@ se aplicável, legislação ou norma relevante citada por extenso.]
|
|||
|
||||
## Referências
|
||||
|
||||
- Workflow: `.agent/workflows/comercial.global.md` (descrição comercial detalhada — Resumo e Detalhamento)
|
||||
- Workflow: `.agent/workflows/marketing.global.md` (peças de marketing digital)
|
||||
- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
|
||||
- Workflow: `agents/ag-comercial/workflows/comercial.md` (descrição comercial detalhada — Resumo e Detalhamento)
|
||||
- Workflow: `agents/ag-comercial/workflows/marketing.md` (peças de marketing digital)
|
||||
- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
type: workflow
|
||||
name: reels
|
||||
description: Criar cadeia de roteiros de Reels para divulgação de funcionalidades e módulos
|
||||
scope: global
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ updatedAt: "2026-06-01"
|
|||
|
||||
Este workflow gera **cadeias de roteiros de Reels** (vídeos curtos de 30 a 60 segundos) organizados por tema. Os roteiros são escritos em tom provocativo, informal e direto — prontos para gravar falando para a câmera ou com narração em off. O resultado é salvo em `./COMERCIAL/<nome-do-modulo>-reels.md`.
|
||||
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
|
||||
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -199,6 +199,6 @@ O arquivo `./COMERCIAL/<nome-do-modulo>-reels.md` deve seguir esta estrutura:
|
|||
|
||||
## Referências
|
||||
|
||||
- Workflow: `.agent/workflows/comercial.global.md` (descrição comercial detalhada — base de contexto)
|
||||
- Workflow: `.agent/workflows/marketing.global.md` (peças de marketing por canal)
|
||||
- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
|
||||
- Workflow: `agents/ag-comercial/workflows/comercial.md` (descrição comercial detalhada — base de contexto)
|
||||
- Workflow: `agents/ag-comercial/workflows/marketing.md` (peças de marketing por canal)
|
||||
- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação)
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ Você é o agente responsável pela infraestrutura, pipelines e ambientes do eco
|
|||
- Dockerfiles e `docker-compose.yml`
|
||||
- Scripts de CI/CD
|
||||
- Variáveis de ambiente e secrets
|
||||
- Scripts de distribuição do `.agent/`
|
||||
- Scripts de sincronização do `.agent/` (submodule + inherited)
|
||||
- Automações e tarefas agendadas de infraestrutura
|
||||
|
||||
## Responsabilidades
|
||||
|
|
|
|||
|
|
@ -1,46 +1,54 @@
|
|||
---
|
||||
type: workflow
|
||||
name: atualizar-agente
|
||||
description: Aplica atualizações globais para o agente de IA
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
description: Atualiza o submodule AGENT-IA e sincroniza artefatos herdados
|
||||
scope: local
|
||||
updatedAt: "2026-06-18"
|
||||
---
|
||||
|
||||
# Workflow: Atualizar Agente Global
|
||||
# Workflow: Atualizar Agente (Submodule)
|
||||
|
||||
## Objetivo
|
||||
|
||||
Baixar e aplicar a versão mais recente das rules, workflows e tools globais a partir do servidor central (`paiol.idz.one`).
|
||||
Atualizar o submodule `.agent/base/` para a versão mais recente do AGENT-IA e sincronizar os artefatos herdados no projeto.
|
||||
|
||||
## Passos
|
||||
|
||||
### 1. Baixar o script de atualização (se ainda não existir)
|
||||
### 1. Atualizar o submodule
|
||||
|
||||
```bash
|
||||
curl -fL# "https://paiol.idz.one/desenvolvimento/agent-ia/atualizar-agente-global.sh" -o .agent/atualizar-agente.global.sh
|
||||
chmod +x .agent/atualizar-agente.global.sh
|
||||
cd .agent/base
|
||||
git pull origin main
|
||||
cd ../..
|
||||
git add .agent/base
|
||||
```
|
||||
|
||||
### 2. Executar o script
|
||||
### 2. Executar o script de sincronização
|
||||
|
||||
// turbo
|
||||
|
||||
```bash
|
||||
sh .agent/atualizar-agente.global.sh
|
||||
sh .agent/atualizar-agente.sh
|
||||
```
|
||||
|
||||
O script possui auto-atualização: na primeira execução, ele baixa sua própria versão mais recente e re-executa automaticamente.
|
||||
O script sincroniza `.agent/inherited/` com os artefatos do `base/`, sem tocar em `local/`.
|
||||
|
||||
### 3. Verificar resultado
|
||||
|
||||
Confirmar que os arquivos foram atualizados sem duplicações:
|
||||
Confirmar que a estrutura está íntegra:
|
||||
|
||||
```bash
|
||||
find .agent/ -name "*.md" -o -name "*.sh" | sort
|
||||
echo "=== Herdados ===" && find .agent/inherited/ -name "*.md" | sort
|
||||
echo "=== Locais ===" && find .agent/local/ -name "*.md" | sort 2>/dev/null || echo "(vazio)"
|
||||
```
|
||||
|
||||
Resultado esperado: todos os arquivos `.md` devem ter o sufixo `.global` (exceto `tools.md`).
|
||||
|
||||
### 4. Revisar mudanças (quando aplicável)
|
||||
|
||||
Se houve alterações significativas nas rules ou workflows, executar `/aprimorar-IA` para validar consistência do sistema de conhecimento.
|
||||
Se houve alterações significativas nas rules ou workflows herdados, executar `/aprimorar-IA` para validar consistência do sistema de conhecimento.
|
||||
|
||||
### 5. Commitar a atualização
|
||||
|
||||
```bash
|
||||
git add .agent/base
|
||||
git commit -m "chore: atualizar agent-ia para versão mais recente"
|
||||
```
|
||||
|
|
@ -26,7 +26,7 @@ Você é o agente responsável por tornar o conhecimento do ecossistema Azteca a
|
|||
## Escopo de Atuação
|
||||
|
||||
- Todos os pacotes: `*-back`, `*-front`, `*-comuns`
|
||||
- Diretório `.agent/` (regras, workflows, skills, memória)
|
||||
- Diretório `.agent/` (base/ herdado + local/ extensões + memoria/)
|
||||
- Arquivos `.regras-negocio.md` co-localizados
|
||||
- JSDoc em funções compartilhadas
|
||||
- Guias de usuário e ajuda contextual nas telas
|
||||
|
|
|
|||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: escrita-natural
|
||||
trigger: context_match
|
||||
description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica.
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
ativacao: >
|
||||
Aplicar quando o agente estiver produzindo textos comerciais, de marketing,
|
||||
orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo.
|
||||
NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio).
|
||||
---
|
||||
|
||||
# Regra: Escrita Estratégica e Natural
|
||||
|
||||
## 🎯 Objetivo
|
||||
|
||||
Produzir textos que:
|
||||
|
||||
- Mostrem domínio real do problema
|
||||
- Se destaquem entre propostas genéricas
|
||||
- Soem humanos, não institucionais
|
||||
- Convençam com clareza e impacto
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Princípios obrigatórios
|
||||
|
||||
### 1. Começar pelo problema real
|
||||
|
||||
Evitar introduções genéricas.
|
||||
|
||||
❌
|
||||
"O presente projeto tem como objetivo..."
|
||||
|
||||
✅
|
||||
"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios."
|
||||
|
||||
---
|
||||
|
||||
### 2. Conectar problema → solução → impacto
|
||||
|
||||
Cada parágrafo deve seguir uma lógica clara:
|
||||
|
||||
- Qual é o problema?
|
||||
- Como a solução resolve?
|
||||
- O que muda na prática?
|
||||
|
||||
✅ Exemplo:
|
||||
"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho."
|
||||
|
||||
---
|
||||
|
||||
### 3. Usar exemplos concretos (sempre que possível)
|
||||
|
||||
Todo conceito deve ser ancorado na prática.
|
||||
|
||||
❌
|
||||
"A solução permite coleta de dados estruturados."
|
||||
|
||||
✅
|
||||
"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet."
|
||||
|
||||
---
|
||||
|
||||
### 4. Escrever como quem vive o problema
|
||||
|
||||
O texto deve ter contexto real:
|
||||
|
||||
- campo
|
||||
- operação
|
||||
- prefeitura
|
||||
- equipe técnica
|
||||
|
||||
✅
|
||||
"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos."
|
||||
|
||||
---
|
||||
|
||||
### 5. Persuasão baseada em impacto real
|
||||
|
||||
Evitar adjetivos vazios.
|
||||
|
||||
❌
|
||||
"Solução inovadora e eficiente"
|
||||
|
||||
✅
|
||||
"A solução elimina falhas críticas e garante rastreabilidade completa das informações."
|
||||
|
||||
---
|
||||
|
||||
### 6. Linguagem natural (sem burocracia)
|
||||
|
||||
Preferir:
|
||||
|
||||
- "Com a solução..."
|
||||
- "Na prática..."
|
||||
- "Isso permite..."
|
||||
- "Como resultado..."
|
||||
|
||||
Evitar:
|
||||
|
||||
- "Dessa forma"
|
||||
- "Destarte"
|
||||
- "O presente projeto"
|
||||
|
||||
---
|
||||
|
||||
### 7. Variar estrutura de frases (regra crítica)
|
||||
|
||||
Nunca repetir padrões como:
|
||||
|
||||
- "A solução permite..."
|
||||
- "O sistema permite..."
|
||||
|
||||
Alternar com:
|
||||
|
||||
- "Na prática, o técnico..."
|
||||
- "Com isso..."
|
||||
- "Isso reduz..."
|
||||
- "Como resultado..."
|
||||
|
||||
---
|
||||
|
||||
### 8. Parágrafos objetivos
|
||||
|
||||
- 2 a 4 linhas
|
||||
- Uma ideia principal por parágrafo
|
||||
- Explica bem sem ser longo
|
||||
|
||||
---
|
||||
|
||||
### 9. Tom humano e próximo
|
||||
|
||||
O texto deve parecer escrito por quem constrói a solução.
|
||||
|
||||
✅
|
||||
"A solução resolve um problema real que impacta o dia a dia das equipes."
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Proibido
|
||||
|
||||
- Texto genérico que serve para qualquer projeto
|
||||
- Parágrafos longos sem exemplo
|
||||
- Repetição de estrutura
|
||||
- Uso de termos sem explicação prática
|
||||
- Linguagem excessivamente institucional
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Checklist final
|
||||
|
||||
Antes de finalizar:
|
||||
|
||||
- [ ] O problema está claro?
|
||||
- [ ] Existe exemplo prático?
|
||||
- [ ] O impacto está explícito?
|
||||
- [ ] O texto soa humano?
|
||||
- [ ] Há repetição de estrutura?
|
||||
- [ ] Parece algo real ou genérico?
|
||||
|
||||
---
|
||||
|
||||
## 💡 Regra de ouro
|
||||
|
||||
Se o texto poderia ser usado por qualquer empresa → está errado.
|
||||
|
||||
Se parece que vem de quem vive o problema → está certo.
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: jsdoc-padrao
|
||||
description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
|
||||
scope: global
|
||||
trigger: file_match
|
||||
globs:
|
||||
- "**/*.ts"
|
||||
- "**/*.tsx"
|
||||
- "**/*.vue"
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Regra: Documentação em Código
|
||||
|
||||
## 1. JSDoc — Princípios
|
||||
|
||||
- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa.
|
||||
- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários.
|
||||
|
||||
## 2. JSDoc obrigatório em funções compartilhadas
|
||||
|
||||
Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Busca detalhes da entidade e calcula privilégios aplicáveis.
|
||||
* Não utilizar em processamento em lote para evitar sobrecarga.
|
||||
*
|
||||
* @param tenantId - Identificador do tenant no sistema
|
||||
* @param entityId - ID do registro na base de dados
|
||||
* @returns Objeto consolidado ou `null` se não encontrado
|
||||
*/
|
||||
export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
|
||||
```
|
||||
|
||||
## 3. Casts temporários — justificativa obrigatória
|
||||
|
||||
Coerções agressivas requerem comentário explicando o porquê:
|
||||
|
||||
```typescript
|
||||
// Necessário: biblioteca externa não provê tipagem genérica na versão atual
|
||||
const dados = payload.raw as unknown as RespostaFormatada
|
||||
```
|
||||
|
||||
## 4. TODOs estruturados
|
||||
|
||||
Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
|
||||
|
||||
- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API`
|
||||
- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos`
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar.
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `.agent/rules/typescript-sem-any.global.md`
|
||||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: escrita-natural
|
||||
trigger: context_match
|
||||
description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica.
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
ativacao: >
|
||||
Aplicar quando o agente estiver produzindo textos comerciais, de marketing,
|
||||
orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo.
|
||||
NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio).
|
||||
---
|
||||
|
||||
# Regra: Escrita Estratégica e Natural
|
||||
|
||||
## 🎯 Objetivo
|
||||
|
||||
Produzir textos que:
|
||||
|
||||
- Mostrem domínio real do problema
|
||||
- Se destaquem entre propostas genéricas
|
||||
- Soem humanos, não institucionais
|
||||
- Convençam com clareza e impacto
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Princípios obrigatórios
|
||||
|
||||
### 1. Começar pelo problema real
|
||||
|
||||
Evitar introduções genéricas.
|
||||
|
||||
❌
|
||||
"O presente projeto tem como objetivo..."
|
||||
|
||||
✅
|
||||
"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios."
|
||||
|
||||
---
|
||||
|
||||
### 2. Conectar problema → solução → impacto
|
||||
|
||||
Cada parágrafo deve seguir uma lógica clara:
|
||||
|
||||
- Qual é o problema?
|
||||
- Como a solução resolve?
|
||||
- O que muda na prática?
|
||||
|
||||
✅ Exemplo:
|
||||
"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho."
|
||||
|
||||
---
|
||||
|
||||
### 3. Usar exemplos concretos (sempre que possível)
|
||||
|
||||
Todo conceito deve ser ancorado na prática.
|
||||
|
||||
❌
|
||||
"A solução permite coleta de dados estruturados."
|
||||
|
||||
✅
|
||||
"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet."
|
||||
|
||||
---
|
||||
|
||||
### 4. Escrever como quem vive o problema
|
||||
|
||||
O texto deve ter contexto real:
|
||||
|
||||
- campo
|
||||
- operação
|
||||
- prefeitura
|
||||
- equipe técnica
|
||||
|
||||
✅
|
||||
"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos."
|
||||
|
||||
---
|
||||
|
||||
### 5. Persuasão baseada em impacto real
|
||||
|
||||
Evitar adjetivos vazios.
|
||||
|
||||
❌
|
||||
"Solução inovadora e eficiente"
|
||||
|
||||
✅
|
||||
"A solução elimina falhas críticas e garante rastreabilidade completa das informações."
|
||||
|
||||
---
|
||||
|
||||
### 6. Linguagem natural (sem burocracia)
|
||||
|
||||
Preferir:
|
||||
|
||||
- "Com a solução..."
|
||||
- "Na prática..."
|
||||
- "Isso permite..."
|
||||
- "Como resultado..."
|
||||
|
||||
Evitar:
|
||||
|
||||
- "Dessa forma"
|
||||
- "Destarte"
|
||||
- "O presente projeto"
|
||||
|
||||
---
|
||||
|
||||
### 7. Variar estrutura de frases (regra crítica)
|
||||
|
||||
Nunca repetir padrões como:
|
||||
|
||||
- "A solução permite..."
|
||||
- "O sistema permite..."
|
||||
|
||||
Alternar com:
|
||||
|
||||
- "Na prática, o técnico..."
|
||||
- "Com isso..."
|
||||
- "Isso reduz..."
|
||||
- "Como resultado..."
|
||||
|
||||
---
|
||||
|
||||
### 8. Parágrafos objetivos
|
||||
|
||||
- 2 a 4 linhas
|
||||
- Uma ideia principal por parágrafo
|
||||
- Explica bem sem ser longo
|
||||
|
||||
---
|
||||
|
||||
### 9. Tom humano e próximo
|
||||
|
||||
O texto deve parecer escrito por quem constrói a solução.
|
||||
|
||||
✅
|
||||
"A solução resolve um problema real que impacta o dia a dia das equipes."
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Proibido
|
||||
|
||||
- Texto genérico que serve para qualquer projeto
|
||||
- Parágrafos longos sem exemplo
|
||||
- Repetição de estrutura
|
||||
- Uso de termos sem explicação prática
|
||||
- Linguagem excessivamente institucional
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Checklist final
|
||||
|
||||
Antes de finalizar:
|
||||
|
||||
- [ ] O problema está claro?
|
||||
- [ ] Existe exemplo prático?
|
||||
- [ ] O impacto está explícito?
|
||||
- [ ] O texto soa humano?
|
||||
- [ ] Há repetição de estrutura?
|
||||
- [ ] Parece algo real ou genérico?
|
||||
|
||||
---
|
||||
|
||||
## 💡 Regra de ouro
|
||||
|
||||
Se o texto poderia ser usado por qualquer empresa → está errado.
|
||||
|
||||
Se parece que vem de quem vive o problema → está certo.
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
type: rule
|
||||
name: estrutura-vue
|
||||
description: Padrões obrigatórios de estrutura para componentes Vue 3 (defineComponent, setup, CSS, dispatch)
|
||||
scope: global
|
||||
scope: local
|
||||
trigger: file_match
|
||||
globs:
|
||||
- "**/*.vue"
|
||||
|
|
@ -82,5 +82,5 @@ Sem estes padrões, componentes perdem inferência de tipos, lógica fica inaudi
|
|||
|
||||
## Referências
|
||||
|
||||
- Rule: `.agent/rules/limite-linhas.global.md`
|
||||
- Rule: `.agent/rules/typescript-sem-any.global.md`
|
||||
- Rule: `global/rules/limite-linhas.md`
|
||||
- Rule: `global/rules/typescript-sem-any.md`
|
||||
|
|
|
|||
|
|
@ -1,123 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: mensagens-usuario
|
||||
description: Toda mensagem visível ao usuário final deve ser escrita em linguagem do domínio, sem termos técnicos de TI
|
||||
scope: global
|
||||
trigger: file_match
|
||||
globs:
|
||||
- "**/*.vue"
|
||||
- "**/*.ts"
|
||||
- "**/*.tsx"
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Regra: Mensagens Orientadas ao Domínio
|
||||
|
||||
## Contexto
|
||||
|
||||
O usuário final dos módulos SaaS é profissional de **engenharia, ciência ou gestão ambiental**. Ele entende de legislação, processos técnicos e ciência aplicada — mas **não tem obrigação de entender tecnologia**.
|
||||
|
||||
Toda mensagem visível na interface — erro, validação, confirmação, tooltip, empty state, ajuda — deve ser escrita na linguagem do domínio do módulo.
|
||||
|
||||
## Regra
|
||||
|
||||
### 1. Erros de validação devem indicar O QUE preencher, não O QUE falhou
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — linguagem técnica
|
||||
"Campo obrigatório"
|
||||
"Erro de validação"
|
||||
"Formato inválido"
|
||||
"Payload inválido"
|
||||
|
||||
// ✅ CORRETO — linguagem do domínio
|
||||
"Informe a Área do Empreendimento (em hectares)"
|
||||
"Selecione o Tipo de Licença: LP, LI ou LO"
|
||||
"A Data da Vistoria deve ser anterior à data atual"
|
||||
"Informe o CNPJ no formato 00.000.000/0000-00"
|
||||
```
|
||||
|
||||
### 2. Erros de sistema devem ser traduzidos para o usuário
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — erro técnico exposto
|
||||
"Erro 500: Internal Server Error"
|
||||
"Timeout na requisição"
|
||||
"Network Error"
|
||||
"ECONNREFUSED"
|
||||
|
||||
// ✅ CORRETO — mensagem humanizada
|
||||
"Não foi possível salvar. Tente novamente em instantes."
|
||||
"A operação demorou mais que o esperado. Tente novamente."
|
||||
"Sem conexão com o servidor. Verifique sua internet."
|
||||
```
|
||||
|
||||
### 3. Estados vazios devem explicar o contexto
|
||||
|
||||
Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário:
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico
|
||||
"Nenhum registro encontrado"
|
||||
"Lista vazia"
|
||||
|
||||
// ✅ CORRETO — explica o domínio e orienta
|
||||
"Nenhuma condicionante cadastrada para esta licença."
|
||||
"Nenhum relatório de monitoramento registrado neste período."
|
||||
"Nenhum empreendimento encontrado com os filtros aplicados. Tente ampliar a busca."
|
||||
```
|
||||
|
||||
### 4. Confirmações devem descrever a consequência
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico
|
||||
"Tem certeza que deseja excluir?"
|
||||
"Confirmar operação?"
|
||||
|
||||
// ✅ CORRETO — descreve o impacto
|
||||
"Excluir esta condicionante? O prazo de cumprimento e os documentos vinculados serão removidos."
|
||||
"Arquivar esta licença? Ela não aparecerá mais nas listagens ativas."
|
||||
```
|
||||
|
||||
### 5. Labels e placeholders devem usar vocabulário do domínio
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico
|
||||
label: "Nome"
|
||||
placeholder: "Digite aqui"
|
||||
|
||||
// ✅ CORRETO — específico do domínio
|
||||
label: "Razão Social do Empreendedor"
|
||||
placeholder: "Ex: Mineração Vale Verde Ltda."
|
||||
|
||||
label: "Área Total do Empreendimento"
|
||||
placeholder: "Em hectares (ex: 150,5)"
|
||||
```
|
||||
|
||||
### 6. Schemas Zod devem ter mensagens de domínio
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — mensagens padrão do Zod
|
||||
const zEmpreendimento = z.object({
|
||||
nome: z.string().min(1), // "String must contain at least 1 character(s)"
|
||||
area: z.number().positive(), // "Number must be greater than 0"
|
||||
})
|
||||
|
||||
// ✅ CORRETO — mensagens customizadas
|
||||
const zEmpreendimento = z.object({
|
||||
nome: z.string().min(1, "Informe o nome do empreendimento"),
|
||||
area: z.number({ invalid_type_error: "A área deve ser um número" })
|
||||
.positive("A área deve ser maior que zero"),
|
||||
cnpj: z.string().regex(/^\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}$/,
|
||||
"CNPJ inválido. Use o formato 00.000.000/0000-00"),
|
||||
})
|
||||
```
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem esta regra, o agente gera mensagens técnicas que confundem gestores ambientais, consultores e técnicos de campo — forçando a equipe de suporte a traduzir erros de sistema para o vocabulário do cliente.
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `.agent/rules/zod-validacao-padrao.global.md` (schemas com mensagens customizadas)
|
||||
- Workflow: `.agent/workflows/ux.global.md` (design de interface)
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
type: workflow
|
||||
name: adicionar-ajuda
|
||||
description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
|
||||
scope: global
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
type: workflow
|
||||
name: criar-fluxograma
|
||||
description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema
|
||||
scope: global
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
|
@ -185,5 +185,5 @@ Caso contrário, seguir os passos acima para criar a primeira implementação.
|
|||
|
||||
## Referências
|
||||
|
||||
- Workflow: `.agent/workflows/otimizar-codigos.global.md`
|
||||
- Skill: `.agent/skills/documentar-decisao-tecnica.global/SKILL.md` (para decisões que geram fluxogramas)
|
||||
- Workflow: `global/workflows/otimizar-codigos.md`
|
||||
- Skill: `global/skills/documentar-decisao-tecnica/SKILL.md` (para decisões que geram fluxogramas)
|
||||
|
|
|
|||
|
|
@ -1,257 +0,0 @@
|
|||
---
|
||||
type: workflow
|
||||
name: ux
|
||||
description: Revisar e otimizar UX de componentes e telas Vue (Frontend)
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Workflow: Revisão de UX
|
||||
|
||||
Guia de revisão e otimização de interfaces Vue 3 + Vuetify 3 no ecossistema Azteca — para usuários corporativos com baixa familiaridade tecnológica.
|
||||
|
||||
---
|
||||
|
||||
## Perfil do Usuário
|
||||
|
||||
O público-alvo das interfaces é corporativo e diversificado em experiência técnica:
|
||||
|
||||
- Gestores públicos e ambientais
|
||||
- Técnicos de campo
|
||||
- Consultores ambientais
|
||||
- Operadores administrativos
|
||||
|
||||
**Premissa central**: o usuário não tem familiaridade avançada com tecnologia. A interface precisa ser autoexplicativa, sem dependência de treinamento prévio.
|
||||
|
||||
---
|
||||
|
||||
## Paleta de Cores Institucional
|
||||
|
||||
Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta** (primária), **Âmbar terroso** (apoio/aviso), **Cinza musgo** (neutros). Semânticas independentes para garantir reconhecimento universal.
|
||||
|
||||
### Escala primária — Verde floresta
|
||||
|
||||
| Token | Hex | Stop | Uso |
|
||||
|---|---|---|---|
|
||||
| `--cor-eli-primaria-bg` | `#EEF3D0` | 50 | Fundo de cards destacados, linhas ativas, hover suave |
|
||||
| `--cor-eli-primaria-zebra` | `#F6F9E8` | 30 | Linha zebrada de tabelas (quase branco esverdeado) |
|
||||
| `--cor-eli-primaria-suave` | `#BFC99C` | — | **Cabeçalho de tabela** — sage/olive mudo, sem limão, texto escuro |
|
||||
| `--cor-eli-primaria-clara` | `#D4E290` | 100 | Badges, chips, seleção, fundo de hover em listas |
|
||||
| `--cor-eli-primaria-media` | `#ADCC44` | 200 | Tags, indicadores secundários |
|
||||
| `--cor-eli-primaria-acao` | `#8AAF00` | 400 | Ação secundária, ícones ativos |
|
||||
| `--cor-eli-primaria` | `#688C00` | 600 | **Botões principais, links ativos, destaques — CTA principal** |
|
||||
| `--cor-eli-primaria-escura` | `#4A6500` | 800 | Hover em botões, bordas ativas, títulos com ênfase |
|
||||
| `--cor-eli-primaria-texto` | `#2E3F00` | 900 | Texto escuro sobre fundos claros da paleta primária |
|
||||
|
||||
### Escala de apoio — Âmbar terroso
|
||||
|
||||
| Token | Hex | Stop | Uso |
|
||||
|---|---|---|---|
|
||||
| `--cor-eli-alerta-bg` | `#FAF3DF` | 50 | Fundo de banners de aviso |
|
||||
| `--cor-eli-alerta-clara` | `#F5DC8A` | 100 | Badges de atenção, chips de alerta |
|
||||
| `--cor-eli-alerta` | `#DDB847` | 200 | Ícones de aviso, bordas de alerta |
|
||||
| `--cor-eli-alerta-forte` | `#8C6A00` | 600 | Texto sobre fundo de alerta, status pendente |
|
||||
|
||||
### Escala neutra — Cinza musgo
|
||||
|
||||
| Token | Hex | Stop | Uso |
|
||||
|---|---|---|---|
|
||||
| `--cor-eli-fundo` | `#F2F3EE` | 50 | Background geral de páginas |
|
||||
| `--cor-eli-borda` | `#D5D8CC` | 100 | Bordas padrão de containers |
|
||||
| `--cor-eli-borda-forte` | `#B5BAA8` | 200 | Bordas de foco, divisores |
|
||||
| `--cor-eli-neutro` | `#5E6553` | 600 | Textos secundários, ícones inativos |
|
||||
| `--cor-eli-neutro-escuro` | `#3E4436` | 800 | Texto de label, cabeçalhos de tabela |
|
||||
| `--cor-eli-superficie` | `#FFFFFF` | — | Cards, modais, popovers |
|
||||
|
||||
### Cores semânticas
|
||||
|
||||
| Token | Hex | Uso |
|
||||
|---|---|---|
|
||||
| `--cor-eli-sucesso` | `#2e7d32` | Confirmações, status positivo |
|
||||
| `--cor-eli-sucesso-bg` | `#E8F5E9` | Fundo de mensagens de sucesso |
|
||||
| `--cor-eli-erro` | `#c62828` | Erros, ações destrutivas |
|
||||
| `--cor-eli-erro-bg` | `#FFEBEE` | Fundo de mensagens de erro |
|
||||
| `--cor-eli-info` | `#1565c0` | Informações auxiliares |
|
||||
| `--cor-eli-info-bg` | `#E3F2FD` | Fundo de banners informativos |
|
||||
|
||||
### Regras de contraste
|
||||
|
||||
- Texto sobre `--cor-eli-primaria` (`#688C00`) deve ser **branco** (`#ffffff`) — contraste 4.6:1 ✓
|
||||
- Texto sobre `--cor-eli-primaria-bg` (`#EEF3D0`) deve ser `--cor-eli-primaria-texto` (`#2E3F00`) — contraste 12:1 ✓
|
||||
- Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓
|
||||
- Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓
|
||||
- Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓
|
||||
- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`.
|
||||
- Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold).
|
||||
|
||||
---
|
||||
|
||||
## Passos
|
||||
|
||||
### 1. Identificar o escopo da revisão
|
||||
|
||||
Determinar qual componente, tela ou modal será revisado. Pode ser:
|
||||
|
||||
- Um componente isolado (ex: `EliTabela`, `EliCartao`)
|
||||
- Uma página completa (ex: `PaginaCadastro.vue`)
|
||||
- Um modal ou drawer (ex: `EliTabelaModalFiltroAvancado.vue`)
|
||||
- Uma interação específica (ex: fluxo de filtro, paginação, menu de ações)
|
||||
|
||||
### 2. Mapear o estado atual
|
||||
|
||||
Antes de alterar, entender o que já existe:
|
||||
|
||||
- Ler o template (`<template>`) para entender a estrutura visual
|
||||
- Ler o CSS/SCSS associado para mapear os tokens de design em uso
|
||||
- Identificar quais componentes Vuetify estão sendo utilizados (ex: `v-btn`, `v-dialog`, `v-select`)
|
||||
- Verificar se existem estilos inline que deveriam migrar para classes CSS
|
||||
|
||||
### 3. Avaliar contra os critérios de UX
|
||||
|
||||
Para cada elemento da interface, avaliar:
|
||||
|
||||
#### Clareza
|
||||
|
||||
- [ ] O propósito de cada elemento é óbvio sem instrução?
|
||||
- [ ] Labels e placeholders são descritivos? (ex: "Buscar por nome ou CPF" vs "Buscar")
|
||||
- [ ] Í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
|
||||
|
||||
- [ ] 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`?
|
||||
|
||||
#### Feedback e estados
|
||||
|
||||
- [ ] Botões têm estados claros de hover (`--cor-eli-primaria-escura`), focus e disabled (`--cor-eli-borda-forte`)?
|
||||
- [ ] Carregamentos exibem indicador visual (spinner, skeleton, barra de progresso)?
|
||||
- [ ] 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
|
||||
|
||||
- [ ] 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)
|
||||
- [ ] Em mobile, os elementos empilham verticalmente sem quebra visual?
|
||||
- [ ] Modais têm largura proporcional ao conteúdo?
|
||||
|
||||
#### Tipografia
|
||||
|
||||
- [ ] 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?
|
||||
|
||||
#### Acessibilidade básica
|
||||
|
||||
- [ ] Elementos interativos têm `aria-label` quando o texto visual não é suficiente?
|
||||
- [ ] Foco via teclado (`Tab`) segue uma ordem lógica?
|
||||
- [ ] Cores não são o único meio de comunicar estado (ex: ícone + cor para erro)?
|
||||
- [ ] Todo texto sobre cor primária ou escura usa branco (`#FFFFFF`)?
|
||||
- [ ] Todo texto sobre `--cor-eli-primaria-bg` usa `--cor-eli-primaria-texto` (`#2E3F00`)?
|
||||
|
||||
### 4. Aplicar padrões Vue/Vuetify do projeto
|
||||
|
||||
Ao implementar melhorias, seguir os padrões do ecossistema:
|
||||
|
||||
#### Componentes Vuetify
|
||||
|
||||
- Usar `v-btn` com variantes do tema (`color="primary"`) em vez de classes CSS manuais para botões
|
||||
- Usar `v-dialog` para modais, `v-menu` para popovers contextuais
|
||||
- Usar `v-text-field`, `v-select` etc. para inputs sempre que possível
|
||||
- Aproveitar props de Vuetify: `density`, `variant`, `rounded`, `elevation`
|
||||
|
||||
#### Iconografia — Lucide (obrigatório)
|
||||
|
||||
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.)
|
||||
|
||||
**Como usar**:
|
||||
|
||||
```vue
|
||||
<script lang="ts">
|
||||
import { Filter, Plus, X, Trash2, Eye } from "@lucide/vue"
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<!-- Uso direto como componente -->
|
||||
<Filter :size="18" :stroke-width="2" />
|
||||
|
||||
<!-- Dentro de botão -->
|
||||
<button>
|
||||
<Plus :size="15" :stroke-width="2.5" />
|
||||
Adicionar
|
||||
</button>
|
||||
</template>
|
||||
```
|
||||
|
||||
**Props úteis**: `:size` (número em px), `:stroke-width` (espessura do traço, padrão 2), `:color` (cor do ícone).
|
||||
|
||||
**Catálogo de referência**: https://lucide.dev/icons — buscar pelo nome do ícone em inglês.
|
||||
|
||||
> Os tokens CSS estão documentados nas tabelas da seção **Paleta de Cores Institucional** acima.
|
||||
> No código, usar `var(--token, #fallback)` — sempre com fallback hardcoded em componentes de biblioteca.
|
||||
|
||||
- Classes devem seguir BEM: `eli-componente__elemento--modificador`
|
||||
- Evitar `!important` — resolver especificidade via seletor mais específico
|
||||
- Usar `var(--cor-eli-primaria)` em vez de valores hex hardcoded no CSS dos componentes
|
||||
- Transições padrão: `transition: all 0.2s ease` para hover/focus
|
||||
|
||||
#### Composição de componentes
|
||||
|
||||
- Componentes filhos devem receber dados via `props` e emitir eventos via `$emit`
|
||||
- Evitar acessar o DOM diretamente; preferir `ref` do Vue
|
||||
- Não duplicar CSS entre componentes — extrair para classe utilitária ou CSS do componente pai
|
||||
|
||||
### 5. Implementar melhorias prioritárias
|
||||
|
||||
Ordenar as melhorias por impacto no usuário:
|
||||
|
||||
1. **Crítico**: elementos que causam confusão ou impedem o uso (falta de feedback, botão invisível, estado vazio sem orientação)
|
||||
2. **Alto**: melhorias que reduzem atrito (espaçamento, hierarquia de botões, responsividade)
|
||||
3. **Médio**: refinamentos visuais (transições, micro-animações, consistência de cores)
|
||||
4. **Baixo**: polish (sombras sutis, arredondamentos, tipografia refinada)
|
||||
|
||||
### 6. Validar resultado
|
||||
|
||||
Após implementar:
|
||||
|
||||
- [ ] A tela renderiza sem erros no console?
|
||||
- [ ] Os estados (vazio, carregando, erro, com dados) estão todos cobertos?
|
||||
- [ ] A paleta de cores está coerente com a base `#688C00`?
|
||||
- [ ] Todos os tokens usados estão definidos na escala primária, de apoio ou neutra?
|
||||
- [ ] Nenhuma cor está hardcoded no CSS do componente (usar `var(--token, #fallback)`)?
|
||||
- [ ] Tokens novos têm fallback hardcoded? (ex: `var(--cor-eli-primaria-suave, #BFC99C)`)?
|
||||
- [ ] Contraste de texto validado: branco sobre `--cor-eli-primaria` e `--cor-eli-primaria-escura`; `--cor-eli-neutro-escuro` sobre `--cor-eli-primaria-suave`?
|
||||
- [ ] Nenhuma ação ficou sem feedback visual?
|
||||
- [ ] O layout não quebra em larguras menores que 1024px?
|
||||
- [ ] Componentes Vuetify recebem props de tema (`color`, `variant`) em vez de override CSS?
|
||||
- [ ] Efeito zebra de tabelas tem fundo branco explícito nas linhas normais (para funcionar sobre qualquer fundo de página)?
|
||||
|
||||
---
|
||||
|
||||
## Anti-padrões a evitar
|
||||
|
||||
| ❌ 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` |
|
||||
| Modal com scroll interno extenso | Dividir em etapas ou usar drawer lateral |
|
||||
| Tabela com 15+ colunas visíveis | Usar o modal de colunas para esconder as menos usadas |
|
||||
| Placeholder como único label | Label fixo acima do campo + placeholder como exemplo |
|
||||
| Ações alinhadas à esquerda em linha de tabela | Ações à direita, próximas ao fim da linha visual |
|
||||
| Toast/snackbar sem ação de fechar | Sempre incluir botão de fechar ou auto-dismiss com tempo suficiente (5s+) |
|
||||
| Estilos inline em `<template>` | Migrar para `<style scoped>` com classe BEM |
|
||||
| Cor hex hardcoded no componente | Usar `var(--cor-eli-primaria)` e demais tokens com fallback |
|
||||
| Texto escuro (`#333`) sobre `--cor-eli-primaria` | Usar branco (`#FFFFFF`) para garantir contraste WCAG AA |
|
||||
| Amarelo/âmbar para sucesso | Âmbar é reservado para **aviso**; sucesso usa `--cor-eli-sucesso` (`#2E7D32`) |
|
||||
| Misturar stops da paleta fora dos tokens | Usar apenas os tokens definidos; nunca interpolar valores avulsos |
|
||||
| Usar `--cor-eli-media` ou `--cor-eli-acao` como fundo de cabeçalho | Usar `--cor-eli-primaria-suave` (`#BFC99C`) — verde mudo sem efeito limão |
|
||||
| `var(--token)` sem fallback em componente de biblioteca | Sempre declarar `var(--token, #valor)` — o projeto destino pode não ter o token atualizado |
|
||||
| Zebra de tabela sem fundo branco explícito nas linhas normais | Declarar `.eli-tabela__tr .eli-tabela__td { background: var(--cor-eli-superficie, #fff) }` antes da regra zebra |
|
||||
|
|
@ -61,6 +61,41 @@ Você é o agente responsável por garantir a qualidade e confiabilidade do ecos
|
|||
- Cenários escritos em linguagem do domínio (Gherkin-style quando aplicável)
|
||||
- Documenta o "o que" e o "por que" de cada cenário
|
||||
|
||||
## Contexto de Referência
|
||||
|
||||
Este repositório é consumido como **git submodule** em `.agent/base/` dentro de cada projeto filho. Os artefatos seguem a hierarquia:
|
||||
|
||||
```
|
||||
.agent/
|
||||
├── base/ ← submodule AGENT-IA (read-only, nunca editar)
|
||||
│ ├── global/ ← rules, workflows e skills herdados
|
||||
│ └── agents/ ← personas e artefatos de cada agente
|
||||
├── local/ ← extensões do projeto (rules, workflows, skills)
|
||||
├── inherited/ ← cópia sincronizada do base (git-ignored)
|
||||
└── memoria/ ← ADRs, diários, contexto do projeto
|
||||
```
|
||||
|
||||
### Onde encontrar artefatos
|
||||
|
||||
| Tipo | Caminho |
|
||||
|------|---------|
|
||||
| Rules globais (herdadas) | `.agent/base/global/rules/` |
|
||||
| Workflows globais (herdados) | `.agent/base/global/workflows/` |
|
||||
| Skills globais (herdadas) | `.agent/base/global/skills/` |
|
||||
| Personas dos agentes | `.agent/base/agents/*/persona.md` |
|
||||
| Rules locais do projeto | `.agent/local/rules/` |
|
||||
| Workflows locais do projeto | `.agent/local/workflows/` |
|
||||
| Skills locais do projeto | `.agent/local/skills/` |
|
||||
| Memória e ADRs | `.agent/memoria/` |
|
||||
|
||||
### Precedência
|
||||
|
||||
```
|
||||
local/ > inherited/ (base)
|
||||
```
|
||||
|
||||
Artefatos em `local/` sempre têm prioridade sobre os herdados de `base/`.
|
||||
|
||||
## Checklist de cobertura mínima
|
||||
|
||||
- [ ] Happy path (fluxo principal) coberto?
|
||||
|
|
|
|||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: escrita-natural
|
||||
trigger: context_match
|
||||
description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica.
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
ativacao: >
|
||||
Aplicar quando o agente estiver produzindo textos comerciais, de marketing,
|
||||
orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo.
|
||||
NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio).
|
||||
---
|
||||
|
||||
# Regra: Escrita Estratégica e Natural
|
||||
|
||||
## 🎯 Objetivo
|
||||
|
||||
Produzir textos que:
|
||||
|
||||
- Mostrem domínio real do problema
|
||||
- Se destaquem entre propostas genéricas
|
||||
- Soem humanos, não institucionais
|
||||
- Convençam com clareza e impacto
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Princípios obrigatórios
|
||||
|
||||
### 1. Começar pelo problema real
|
||||
|
||||
Evitar introduções genéricas.
|
||||
|
||||
❌
|
||||
"O presente projeto tem como objetivo..."
|
||||
|
||||
✅
|
||||
"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios."
|
||||
|
||||
---
|
||||
|
||||
### 2. Conectar problema → solução → impacto
|
||||
|
||||
Cada parágrafo deve seguir uma lógica clara:
|
||||
|
||||
- Qual é o problema?
|
||||
- Como a solução resolve?
|
||||
- O que muda na prática?
|
||||
|
||||
✅ Exemplo:
|
||||
"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho."
|
||||
|
||||
---
|
||||
|
||||
### 3. Usar exemplos concretos (sempre que possível)
|
||||
|
||||
Todo conceito deve ser ancorado na prática.
|
||||
|
||||
❌
|
||||
"A solução permite coleta de dados estruturados."
|
||||
|
||||
✅
|
||||
"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet."
|
||||
|
||||
---
|
||||
|
||||
### 4. Escrever como quem vive o problema
|
||||
|
||||
O texto deve ter contexto real:
|
||||
|
||||
- campo
|
||||
- operação
|
||||
- prefeitura
|
||||
- equipe técnica
|
||||
|
||||
✅
|
||||
"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos."
|
||||
|
||||
---
|
||||
|
||||
### 5. Persuasão baseada em impacto real
|
||||
|
||||
Evitar adjetivos vazios.
|
||||
|
||||
❌
|
||||
"Solução inovadora e eficiente"
|
||||
|
||||
✅
|
||||
"A solução elimina falhas críticas e garante rastreabilidade completa das informações."
|
||||
|
||||
---
|
||||
|
||||
### 6. Linguagem natural (sem burocracia)
|
||||
|
||||
Preferir:
|
||||
|
||||
- "Com a solução..."
|
||||
- "Na prática..."
|
||||
- "Isso permite..."
|
||||
- "Como resultado..."
|
||||
|
||||
Evitar:
|
||||
|
||||
- "Dessa forma"
|
||||
- "Destarte"
|
||||
- "O presente projeto"
|
||||
|
||||
---
|
||||
|
||||
### 7. Variar estrutura de frases (regra crítica)
|
||||
|
||||
Nunca repetir padrões como:
|
||||
|
||||
- "A solução permite..."
|
||||
- "O sistema permite..."
|
||||
|
||||
Alternar com:
|
||||
|
||||
- "Na prática, o técnico..."
|
||||
- "Com isso..."
|
||||
- "Isso reduz..."
|
||||
- "Como resultado..."
|
||||
|
||||
---
|
||||
|
||||
### 8. Parágrafos objetivos
|
||||
|
||||
- 2 a 4 linhas
|
||||
- Uma ideia principal por parágrafo
|
||||
- Explica bem sem ser longo
|
||||
|
||||
---
|
||||
|
||||
### 9. Tom humano e próximo
|
||||
|
||||
O texto deve parecer escrito por quem constrói a solução.
|
||||
|
||||
✅
|
||||
"A solução resolve um problema real que impacta o dia a dia das equipes."
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Proibido
|
||||
|
||||
- Texto genérico que serve para qualquer projeto
|
||||
- Parágrafos longos sem exemplo
|
||||
- Repetição de estrutura
|
||||
- Uso de termos sem explicação prática
|
||||
- Linguagem excessivamente institucional
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Checklist final
|
||||
|
||||
Antes de finalizar:
|
||||
|
||||
- [ ] O problema está claro?
|
||||
- [ ] Existe exemplo prático?
|
||||
- [ ] O impacto está explícito?
|
||||
- [ ] O texto soa humano?
|
||||
- [ ] Há repetição de estrutura?
|
||||
- [ ] Parece algo real ou genérico?
|
||||
|
||||
---
|
||||
|
||||
## 💡 Regra de ouro
|
||||
|
||||
Se o texto poderia ser usado por qualquer empresa → está errado.
|
||||
|
||||
Se parece que vem de quem vive o problema → está certo.
|
||||
|
|
@ -1,123 +0,0 @@
|
|||
---
|
||||
type: rule
|
||||
name: mensagens-usuario
|
||||
description: Toda mensagem visível ao usuário final deve ser escrita em linguagem do domínio, sem termos técnicos de TI
|
||||
scope: global
|
||||
trigger: file_match
|
||||
globs:
|
||||
- "**/*.vue"
|
||||
- "**/*.ts"
|
||||
- "**/*.tsx"
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Regra: Mensagens Orientadas ao Domínio
|
||||
|
||||
## Contexto
|
||||
|
||||
O usuário final dos módulos SaaS é profissional de **engenharia, ciência ou gestão ambiental**. Ele entende de legislação, processos técnicos e ciência aplicada — mas **não tem obrigação de entender tecnologia**.
|
||||
|
||||
Toda mensagem visível na interface — erro, validação, confirmação, tooltip, empty state, ajuda — deve ser escrita na linguagem do domínio do módulo.
|
||||
|
||||
## Regra
|
||||
|
||||
### 1. Erros de validação devem indicar O QUE preencher, não O QUE falhou
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — linguagem técnica
|
||||
"Campo obrigatório"
|
||||
"Erro de validação"
|
||||
"Formato inválido"
|
||||
"Payload inválido"
|
||||
|
||||
// ✅ CORRETO — linguagem do domínio
|
||||
"Informe a Área do Empreendimento (em hectares)"
|
||||
"Selecione o Tipo de Licença: LP, LI ou LO"
|
||||
"A Data da Vistoria deve ser anterior à data atual"
|
||||
"Informe o CNPJ no formato 00.000.000/0000-00"
|
||||
```
|
||||
|
||||
### 2. Erros de sistema devem ser traduzidos para o usuário
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — erro técnico exposto
|
||||
"Erro 500: Internal Server Error"
|
||||
"Timeout na requisição"
|
||||
"Network Error"
|
||||
"ECONNREFUSED"
|
||||
|
||||
// ✅ CORRETO — mensagem humanizada
|
||||
"Não foi possível salvar. Tente novamente em instantes."
|
||||
"A operação demorou mais que o esperado. Tente novamente."
|
||||
"Sem conexão com o servidor. Verifique sua internet."
|
||||
```
|
||||
|
||||
### 3. Estados vazios devem explicar o contexto
|
||||
|
||||
Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário:
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico
|
||||
"Nenhum registro encontrado"
|
||||
"Lista vazia"
|
||||
|
||||
// ✅ CORRETO — explica o domínio e orienta
|
||||
"Nenhuma condicionante cadastrada para esta licença."
|
||||
"Nenhum relatório de monitoramento registrado neste período."
|
||||
"Nenhum empreendimento encontrado com os filtros aplicados. Tente ampliar a busca."
|
||||
```
|
||||
|
||||
### 4. Confirmações devem descrever a consequência
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico
|
||||
"Tem certeza que deseja excluir?"
|
||||
"Confirmar operação?"
|
||||
|
||||
// ✅ CORRETO — descreve o impacto
|
||||
"Excluir esta condicionante? O prazo de cumprimento e os documentos vinculados serão removidos."
|
||||
"Arquivar esta licença? Ela não aparecerá mais nas listagens ativas."
|
||||
```
|
||||
|
||||
### 5. Labels e placeholders devem usar vocabulário do domínio
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico
|
||||
label: "Nome"
|
||||
placeholder: "Digite aqui"
|
||||
|
||||
// ✅ CORRETO — específico do domínio
|
||||
label: "Razão Social do Empreendedor"
|
||||
placeholder: "Ex: Mineração Vale Verde Ltda."
|
||||
|
||||
label: "Área Total do Empreendimento"
|
||||
placeholder: "Em hectares (ex: 150,5)"
|
||||
```
|
||||
|
||||
### 6. Schemas Zod devem ter mensagens de domínio
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — mensagens padrão do Zod
|
||||
const zEmpreendimento = z.object({
|
||||
nome: z.string().min(1), // "String must contain at least 1 character(s)"
|
||||
area: z.number().positive(), // "Number must be greater than 0"
|
||||
})
|
||||
|
||||
// ✅ CORRETO — mensagens customizadas
|
||||
const zEmpreendimento = z.object({
|
||||
nome: z.string().min(1, "Informe o nome do empreendimento"),
|
||||
area: z.number({ invalid_type_error: "A área deve ser um número" })
|
||||
.positive("A área deve ser maior que zero"),
|
||||
cnpj: z.string().regex(/^\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}$/,
|
||||
"CNPJ inválido. Use o formato 00.000.000/0000-00"),
|
||||
})
|
||||
```
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem esta regra, o agente gera mensagens técnicas que confundem gestores ambientais, consultores e técnicos de campo — forçando a equipe de suporte a traduzir erros de sistema para o vocabulário do cliente.
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `.agent/rules/zod-validacao-padrao.global.md` (schemas com mensagens customizadas)
|
||||
- Workflow: `.agent/workflows/ux.global.md` (design de interface)
|
||||
|
|
@ -1,257 +0,0 @@
|
|||
---
|
||||
type: workflow
|
||||
name: ux
|
||||
description: Revisar e otimizar UX de componentes e telas Vue (Frontend)
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Workflow: Revisão de UX
|
||||
|
||||
Guia de revisão e otimização de interfaces Vue 3 + Vuetify 3 no ecossistema Azteca — para usuários corporativos com baixa familiaridade tecnológica.
|
||||
|
||||
---
|
||||
|
||||
## Perfil do Usuário
|
||||
|
||||
O público-alvo das interfaces é corporativo e diversificado em experiência técnica:
|
||||
|
||||
- Gestores públicos e ambientais
|
||||
- Técnicos de campo
|
||||
- Consultores ambientais
|
||||
- Operadores administrativos
|
||||
|
||||
**Premissa central**: o usuário não tem familiaridade avançada com tecnologia. A interface precisa ser autoexplicativa, sem dependência de treinamento prévio.
|
||||
|
||||
---
|
||||
|
||||
## Paleta de Cores Institucional
|
||||
|
||||
Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta** (primária), **Âmbar terroso** (apoio/aviso), **Cinza musgo** (neutros). Semânticas independentes para garantir reconhecimento universal.
|
||||
|
||||
### Escala primária — Verde floresta
|
||||
|
||||
| Token | Hex | Stop | Uso |
|
||||
|---|---|---|---|
|
||||
| `--cor-eli-primaria-bg` | `#EEF3D0` | 50 | Fundo de cards destacados, linhas ativas, hover suave |
|
||||
| `--cor-eli-primaria-zebra` | `#F6F9E8` | 30 | Linha zebrada de tabelas (quase branco esverdeado) |
|
||||
| `--cor-eli-primaria-suave` | `#BFC99C` | — | **Cabeçalho de tabela** — sage/olive mudo, sem limão, texto escuro |
|
||||
| `--cor-eli-primaria-clara` | `#D4E290` | 100 | Badges, chips, seleção, fundo de hover em listas |
|
||||
| `--cor-eli-primaria-media` | `#ADCC44` | 200 | Tags, indicadores secundários |
|
||||
| `--cor-eli-primaria-acao` | `#8AAF00` | 400 | Ação secundária, ícones ativos |
|
||||
| `--cor-eli-primaria` | `#688C00` | 600 | **Botões principais, links ativos, destaques — CTA principal** |
|
||||
| `--cor-eli-primaria-escura` | `#4A6500` | 800 | Hover em botões, bordas ativas, títulos com ênfase |
|
||||
| `--cor-eli-primaria-texto` | `#2E3F00` | 900 | Texto escuro sobre fundos claros da paleta primária |
|
||||
|
||||
### Escala de apoio — Âmbar terroso
|
||||
|
||||
| Token | Hex | Stop | Uso |
|
||||
|---|---|---|---|
|
||||
| `--cor-eli-alerta-bg` | `#FAF3DF` | 50 | Fundo de banners de aviso |
|
||||
| `--cor-eli-alerta-clara` | `#F5DC8A` | 100 | Badges de atenção, chips de alerta |
|
||||
| `--cor-eli-alerta` | `#DDB847` | 200 | Ícones de aviso, bordas de alerta |
|
||||
| `--cor-eli-alerta-forte` | `#8C6A00` | 600 | Texto sobre fundo de alerta, status pendente |
|
||||
|
||||
### Escala neutra — Cinza musgo
|
||||
|
||||
| Token | Hex | Stop | Uso |
|
||||
|---|---|---|---|
|
||||
| `--cor-eli-fundo` | `#F2F3EE` | 50 | Background geral de páginas |
|
||||
| `--cor-eli-borda` | `#D5D8CC` | 100 | Bordas padrão de containers |
|
||||
| `--cor-eli-borda-forte` | `#B5BAA8` | 200 | Bordas de foco, divisores |
|
||||
| `--cor-eli-neutro` | `#5E6553` | 600 | Textos secundários, ícones inativos |
|
||||
| `--cor-eli-neutro-escuro` | `#3E4436` | 800 | Texto de label, cabeçalhos de tabela |
|
||||
| `--cor-eli-superficie` | `#FFFFFF` | — | Cards, modais, popovers |
|
||||
|
||||
### Cores semânticas
|
||||
|
||||
| Token | Hex | Uso |
|
||||
|---|---|---|
|
||||
| `--cor-eli-sucesso` | `#2e7d32` | Confirmações, status positivo |
|
||||
| `--cor-eli-sucesso-bg` | `#E8F5E9` | Fundo de mensagens de sucesso |
|
||||
| `--cor-eli-erro` | `#c62828` | Erros, ações destrutivas |
|
||||
| `--cor-eli-erro-bg` | `#FFEBEE` | Fundo de mensagens de erro |
|
||||
| `--cor-eli-info` | `#1565c0` | Informações auxiliares |
|
||||
| `--cor-eli-info-bg` | `#E3F2FD` | Fundo de banners informativos |
|
||||
|
||||
### Regras de contraste
|
||||
|
||||
- Texto sobre `--cor-eli-primaria` (`#688C00`) deve ser **branco** (`#ffffff`) — contraste 4.6:1 ✓
|
||||
- Texto sobre `--cor-eli-primaria-bg` (`#EEF3D0`) deve ser `--cor-eli-primaria-texto` (`#2E3F00`) — contraste 12:1 ✓
|
||||
- Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓
|
||||
- Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓
|
||||
- Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓
|
||||
- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`.
|
||||
- Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold).
|
||||
|
||||
---
|
||||
|
||||
## Passos
|
||||
|
||||
### 1. Identificar o escopo da revisão
|
||||
|
||||
Determinar qual componente, tela ou modal será revisado. Pode ser:
|
||||
|
||||
- Um componente isolado (ex: `EliTabela`, `EliCartao`)
|
||||
- Uma página completa (ex: `PaginaCadastro.vue`)
|
||||
- Um modal ou drawer (ex: `EliTabelaModalFiltroAvancado.vue`)
|
||||
- Uma interação específica (ex: fluxo de filtro, paginação, menu de ações)
|
||||
|
||||
### 2. Mapear o estado atual
|
||||
|
||||
Antes de alterar, entender o que já existe:
|
||||
|
||||
- Ler o template (`<template>`) para entender a estrutura visual
|
||||
- Ler o CSS/SCSS associado para mapear os tokens de design em uso
|
||||
- Identificar quais componentes Vuetify estão sendo utilizados (ex: `v-btn`, `v-dialog`, `v-select`)
|
||||
- Verificar se existem estilos inline que deveriam migrar para classes CSS
|
||||
|
||||
### 3. Avaliar contra os critérios de UX
|
||||
|
||||
Para cada elemento da interface, avaliar:
|
||||
|
||||
#### Clareza
|
||||
|
||||
- [ ] O propósito de cada elemento é óbvio sem instrução?
|
||||
- [ ] Labels e placeholders são descritivos? (ex: "Buscar por nome ou CPF" vs "Buscar")
|
||||
- [ ] Í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
|
||||
|
||||
- [ ] 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`?
|
||||
|
||||
#### Feedback e estados
|
||||
|
||||
- [ ] Botões têm estados claros de hover (`--cor-eli-primaria-escura`), focus e disabled (`--cor-eli-borda-forte`)?
|
||||
- [ ] Carregamentos exibem indicador visual (spinner, skeleton, barra de progresso)?
|
||||
- [ ] 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
|
||||
|
||||
- [ ] 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)
|
||||
- [ ] Em mobile, os elementos empilham verticalmente sem quebra visual?
|
||||
- [ ] Modais têm largura proporcional ao conteúdo?
|
||||
|
||||
#### Tipografia
|
||||
|
||||
- [ ] 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?
|
||||
|
||||
#### Acessibilidade básica
|
||||
|
||||
- [ ] Elementos interativos têm `aria-label` quando o texto visual não é suficiente?
|
||||
- [ ] Foco via teclado (`Tab`) segue uma ordem lógica?
|
||||
- [ ] Cores não são o único meio de comunicar estado (ex: ícone + cor para erro)?
|
||||
- [ ] Todo texto sobre cor primária ou escura usa branco (`#FFFFFF`)?
|
||||
- [ ] Todo texto sobre `--cor-eli-primaria-bg` usa `--cor-eli-primaria-texto` (`#2E3F00`)?
|
||||
|
||||
### 4. Aplicar padrões Vue/Vuetify do projeto
|
||||
|
||||
Ao implementar melhorias, seguir os padrões do ecossistema:
|
||||
|
||||
#### Componentes Vuetify
|
||||
|
||||
- Usar `v-btn` com variantes do tema (`color="primary"`) em vez de classes CSS manuais para botões
|
||||
- Usar `v-dialog` para modais, `v-menu` para popovers contextuais
|
||||
- Usar `v-text-field`, `v-select` etc. para inputs sempre que possível
|
||||
- Aproveitar props de Vuetify: `density`, `variant`, `rounded`, `elevation`
|
||||
|
||||
#### Iconografia — Lucide (obrigatório)
|
||||
|
||||
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.)
|
||||
|
||||
**Como usar**:
|
||||
|
||||
```vue
|
||||
<script lang="ts">
|
||||
import { Filter, Plus, X, Trash2, Eye } from "@lucide/vue"
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<!-- Uso direto como componente -->
|
||||
<Filter :size="18" :stroke-width="2" />
|
||||
|
||||
<!-- Dentro de botão -->
|
||||
<button>
|
||||
<Plus :size="15" :stroke-width="2.5" />
|
||||
Adicionar
|
||||
</button>
|
||||
</template>
|
||||
```
|
||||
|
||||
**Props úteis**: `:size` (número em px), `:stroke-width` (espessura do traço, padrão 2), `:color` (cor do ícone).
|
||||
|
||||
**Catálogo de referência**: https://lucide.dev/icons — buscar pelo nome do ícone em inglês.
|
||||
|
||||
> Os tokens CSS estão documentados nas tabelas da seção **Paleta de Cores Institucional** acima.
|
||||
> No código, usar `var(--token, #fallback)` — sempre com fallback hardcoded em componentes de biblioteca.
|
||||
|
||||
- Classes devem seguir BEM: `eli-componente__elemento--modificador`
|
||||
- Evitar `!important` — resolver especificidade via seletor mais específico
|
||||
- Usar `var(--cor-eli-primaria)` em vez de valores hex hardcoded no CSS dos componentes
|
||||
- Transições padrão: `transition: all 0.2s ease` para hover/focus
|
||||
|
||||
#### Composição de componentes
|
||||
|
||||
- Componentes filhos devem receber dados via `props` e emitir eventos via `$emit`
|
||||
- Evitar acessar o DOM diretamente; preferir `ref` do Vue
|
||||
- Não duplicar CSS entre componentes — extrair para classe utilitária ou CSS do componente pai
|
||||
|
||||
### 5. Implementar melhorias prioritárias
|
||||
|
||||
Ordenar as melhorias por impacto no usuário:
|
||||
|
||||
1. **Crítico**: elementos que causam confusão ou impedem o uso (falta de feedback, botão invisível, estado vazio sem orientação)
|
||||
2. **Alto**: melhorias que reduzem atrito (espaçamento, hierarquia de botões, responsividade)
|
||||
3. **Médio**: refinamentos visuais (transições, micro-animações, consistência de cores)
|
||||
4. **Baixo**: polish (sombras sutis, arredondamentos, tipografia refinada)
|
||||
|
||||
### 6. Validar resultado
|
||||
|
||||
Após implementar:
|
||||
|
||||
- [ ] A tela renderiza sem erros no console?
|
||||
- [ ] Os estados (vazio, carregando, erro, com dados) estão todos cobertos?
|
||||
- [ ] A paleta de cores está coerente com a base `#688C00`?
|
||||
- [ ] Todos os tokens usados estão definidos na escala primária, de apoio ou neutra?
|
||||
- [ ] Nenhuma cor está hardcoded no CSS do componente (usar `var(--token, #fallback)`)?
|
||||
- [ ] Tokens novos têm fallback hardcoded? (ex: `var(--cor-eli-primaria-suave, #BFC99C)`)?
|
||||
- [ ] Contraste de texto validado: branco sobre `--cor-eli-primaria` e `--cor-eli-primaria-escura`; `--cor-eli-neutro-escuro` sobre `--cor-eli-primaria-suave`?
|
||||
- [ ] Nenhuma ação ficou sem feedback visual?
|
||||
- [ ] O layout não quebra em larguras menores que 1024px?
|
||||
- [ ] Componentes Vuetify recebem props de tema (`color`, `variant`) em vez de override CSS?
|
||||
- [ ] Efeito zebra de tabelas tem fundo branco explícito nas linhas normais (para funcionar sobre qualquer fundo de página)?
|
||||
|
||||
---
|
||||
|
||||
## Anti-padrões a evitar
|
||||
|
||||
| ❌ 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` |
|
||||
| Modal com scroll interno extenso | Dividir em etapas ou usar drawer lateral |
|
||||
| Tabela com 15+ colunas visíveis | Usar o modal de colunas para esconder as menos usadas |
|
||||
| Placeholder como único label | Label fixo acima do campo + placeholder como exemplo |
|
||||
| Ações alinhadas à esquerda em linha de tabela | Ações à direita, próximas ao fim da linha visual |
|
||||
| Toast/snackbar sem ação de fechar | Sempre incluir botão de fechar ou auto-dismiss com tempo suficiente (5s+) |
|
||||
| Estilos inline em `<template>` | Migrar para `<style scoped>` com classe BEM |
|
||||
| Cor hex hardcoded no componente | Usar `var(--cor-eli-primaria)` e demais tokens com fallback |
|
||||
| Texto escuro (`#333`) sobre `--cor-eli-primaria` | Usar branco (`#FFFFFF`) para garantir contraste WCAG AA |
|
||||
| Amarelo/âmbar para sucesso | Âmbar é reservado para **aviso**; sucesso usa `--cor-eli-sucesso` (`#2E7D32`) |
|
||||
| Misturar stops da paleta fora dos tokens | Usar apenas os tokens definidos; nunca interpolar valores avulsos |
|
||||
| Usar `--cor-eli-media` ou `--cor-eli-acao` como fundo de cabeçalho | Usar `--cor-eli-primaria-suave` (`#BFC99C`) — verde mudo sem efeito limão |
|
||||
| `var(--token)` sem fallback em componente de biblioteca | Sempre declarar `var(--token, #valor)` — o projeto destino pode não ter o token atualizado |
|
||||
| Zebra de tabela sem fundo branco explícito nas linhas normais | Declarar `.eli-tabela__tr .eli-tabela__td { background: var(--cor-eli-superficie, #fff) }` antes da regra zebra |
|
||||
Loading…
Add table
Add a link
Reference in a new issue