feat(ux): incorporar diretrizes M3 de UX writing e organizacao de telas, modais e paineis
This commit is contained in:
parent
4818887cb3
commit
b540fd97c0
21 changed files with 709 additions and 193 deletions
183
agents/ux/rules/mensagens-usuario.md
Normal file
183
agents/ux/rules/mensagens-usuario.md
Normal file
|
|
@ -0,0 +1,183 @@
|
|||
---
|
||||
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, seguindo as boas práticas de UX Writing do Material Design 3
|
||||
scope: global
|
||||
trigger: glob
|
||||
globs: "**/*.vue, **/*.ts, **/*.tsx"
|
||||
updatedAt: "2026-10-26"
|
||||
---
|
||||
|
||||
# Regra: Mensagens Orientadas ao Domínio e UX Writing (Material Design 3)
|
||||
|
||||
## Contexto
|
||||
|
||||
O usuário final dos módulos SaaS é profissional de **engenharia, ciência, administração pública ou gestão ambiental**. Ele entende de legislação, processos técnicos e operação — mas **não tem obrigação de entender tecnologia**.
|
||||
|
||||
Toda mensagem e microcopy visível na interface — títulos de telas, cabeçalhos de seções, modais, painéis laterais, erros, validações, confirmações, tooltips, estados vazios e botões — deve unir a **linguagem do domínio do módulo** às **boas práticas de UX Writing do Material Design 3** (`https://m3.material.io/foundations/writing/best-practices`).
|
||||
|
||||
---
|
||||
|
||||
## Regra
|
||||
|
||||
### 1. Erros de validação devem indicar O QUE preencher, não O QUE falhou
|
||||
|
||||
Usar voz ativa, tom neutro (sem culpar o usuário e sem pontos de exclamação `!`) e capitalização estilo de frase (*Sentence case*):
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — linguagem técnica ou Title Case artificial
|
||||
"Campo obrigatório!"
|
||||
"Erro de validação"
|
||||
"Formato inválido"
|
||||
"Payload inválido"
|
||||
"Informe a Área do Empreendimento"
|
||||
|
||||
// ✅ CORRETO — linguagem do domínio + Sentence case (M3)
|
||||
"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 de hoje"
|
||||
"Informe o CNPJ no formato 00.000.000/0000-00"
|
||||
```
|
||||
|
||||
### 2. Erros de sistema devem ser traduzidos e orientar o próximo passo
|
||||
|
||||
Explicar o que ocorreu de forma direta e como o usuário pode prosseguir, sem expor códigos HTTP, *stack traces* ou termos de infraestrutura:
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — erro técnico exposto
|
||||
"Erro 500: Internal Server Error"
|
||||
"Timeout na requisição"
|
||||
"Network Error / ECONNREFUSED"
|
||||
|
||||
// ✅ CORRETO — mensagem humanizada com orientação prática
|
||||
"Não foi possível salvar as alterações. Tente novamente em instantes."
|
||||
"A operação demorou mais que o esperado. Tente novamente."
|
||||
"Sem conexão com o servidor. Verifique sua internet e tente novamente."
|
||||
```
|
||||
|
||||
### 3. Estados vazios (*empty states*) devem explicar o contexto e orientar a ação
|
||||
|
||||
Quando uma lista, tabela ou painel está vazio, o texto principal não usa ponto final e o texto de apoio orienta o próximo passo:
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico e sem saída
|
||||
"Nenhum registro encontrado."
|
||||
"Lista vazia"
|
||||
|
||||
// ✅ CORRETO — explica o domínio e orienta
|
||||
// Título (sem ponto final): "Nenhuma condicionante cadastrada"
|
||||
// Apoio: "Para iniciar o controle de prazos, adicione a primeira condicionante desta licença."
|
||||
// Botão CTA: "Adicionar condicionante"
|
||||
```
|
||||
|
||||
### 4. Diálogos de confirmação devem explicar a consequência e usar botões específicos (M3)
|
||||
|
||||
Todo modal de confirmação/decisão crítica (`v-dialog`) deve obedecer à **Anatomia Tripla de Diálogo do Material Design 3**:
|
||||
|
||||
1. **Título com pergunta direta (`Verbo + objeto?`, sem repetir no corpo):** Iniciar com o verbo da ação em *Sentence case* terminado em interrogação.
|
||||
2. **Corpo com a consequência neutra e reversibilidade:** Explicar exatamente o que acontecerá se o usuário prosseguir, sem tom alarmista (`"Atenção!"`) e sem repetir a pergunta do título.
|
||||
3. **Botões de ação explícitos (`1 a 3 palavras`):** O botão confirmatório deve repetir o **verbo específico da ação**. É **proibido** usar pares ambíguos como `[Sim] / [Não]`, `[OK] / [Cancelar]` ou apenas `[Confirmar]`.
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico, alarmista e com botões ambíguos
|
||||
{
|
||||
titulo: "Atenção! Confirmar Operação?",
|
||||
corpo: "Tem certeza que deseja excluir este registro?",
|
||||
botoes: ["Não", "Sim"] // ou ["Cancelar", "OK"]
|
||||
}
|
||||
|
||||
// ✅ CORRETO — Anatomia M3 (Pergunta específica + Consequência + Verbo no botão)
|
||||
{
|
||||
titulo: "Excluir condicionante?",
|
||||
corpo: "O prazo de cumprimento e os documentos vinculados serão removidos permanentemente.",
|
||||
botoes: ["Cancelar", "Excluir condicionante"]
|
||||
}
|
||||
|
||||
{
|
||||
titulo: "Arquivar licença?",
|
||||
corpo: "Esta licença sairá das listagens ativas, mas poderá ser consultada no histórico.",
|
||||
botoes: ["Cancelar", "Arquivar licença"]
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Labels e placeholders devem usar vocabulário do domínio e *Sentence case*
|
||||
|
||||
Nunca finalizar `label` com dois-pontos (`:`) nem usar ponto final (`.`) em `label` ou `placeholder`:
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — genérico, com dois-pontos ou Title Case em todas as palavras
|
||||
label: "Nome:"
|
||||
placeholder: "Digite aqui."
|
||||
label: "Razão Social Do Empreendedor:"
|
||||
|
||||
// ✅ CORRETO — específico do domínio, Sentence case e sem pontuação final
|
||||
label: "Razão social do empreendedor"
|
||||
placeholder: "Ex.: Mineração Vale Verde Ltda."
|
||||
|
||||
label: "Área total do empreendimento (ha)"
|
||||
placeholder: "Ex.: 150,5"
|
||||
```
|
||||
|
||||
### 6. Schemas Zod devem ter mensagens de domínio em *Sentence case*
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — mensagens padrão do Zod em inglês ou técnicas
|
||||
const zEmpreendimento = z.object({
|
||||
nome: z.string().min(1),
|
||||
area: z.number().positive(),
|
||||
})
|
||||
|
||||
// ✅ CORRETO — mensagens customizadas em linguagem do domínio
|
||||
const zEmpreendimento = z.object({
|
||||
nome: z.string().min(1, "Informe a razão social do empreendimento"),
|
||||
area: z.number({ invalid_type_error: "Informe um valor numérico para a área" })
|
||||
.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"),
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Princípios de UX Writing e Escaneabilidade — Material Design 3
|
||||
|
||||
Toda escrita em componentes Vue (`*-front`) deve aplicar os 7 princípios do guia `m3.material.io/foundations/writing/best-practices`:
|
||||
|
||||
1. **Capitalização estilo de frase (*Sentence case*):**
|
||||
- Usar maiúscula **apenas na primeira letra da primeira palavra** e em **nomes próprios ou siglas oficiais** (`CNPJ`, `CPF`, `IBAMA`, `LP`, `LI`, `LO`, `ART`, `MTR`, `UF`).
|
||||
- Aplica-se a: títulos de páginas, cabeçalhos de cards/seções, títulos de modais e painéis laterais, labels de inputs, abas (`v-tab`), itens de menu e botões (`"Nova licença"`, `"Salvar alterações"`, `"Dados do empreendimento"`).
|
||||
- **Proibido** usar *Title Case* anglófono (`"Salvar Alterações"`, `"Dados Do Empreendimento"`) ou `ALL CAPS` em botões e títulos.
|
||||
2. **Começar pelo objetivo (*Begin with the objective*):**
|
||||
- Quando uma frase orientativa descreve uma meta e a ação necessária para atingi-la, **iniciar a frase pelo objetivo** para facilitar o escaneamento rápido:
|
||||
- ✅ `"Para emitir a licença, anexe o parecer técnico conclusivo"`
|
||||
- ❌ `"Anexe o parecer técnico conclusivo para emitir a licença"`
|
||||
3. **Pontuação enxuta para escaneabilidade (*Skip unnecessary punctuation*):**
|
||||
- **Omitir ponto final (`.`)** em: rótulos (`label`), botões, títulos e subtítulos, cabeçalhos de seção, tooltips curtos de 1 frase, toasts/snackbars de 1 frase e itens de lista (*bullet points*) de frase única.
|
||||
- **Proibir dois-pontos (`:`)** ao final de títulos, cabeçalhos de seção/lista e labels de campos (`<h3>Documentos exigidos</h3>` e nunca `<h3>Documentos exigidos:</h3>`).
|
||||
- **Usar ponto final** apenas quando o texto tiver **2 ou mais frases** ou quando a frase for acompanhada de um link.
|
||||
4. **Tempo presente, voz ativa e tom neutro:**
|
||||
- Escrever no **tempo presente** e na **voz ativa** (`"Salvando alterações..."` em vez de `"As alterações estão sendo salvas"`; `"O arquivo excede 10 MB"` em vez de `"O limite de 10 MB foi excedido pelo arquivo"`).
|
||||
- **Proibido** usar pontos de exclamação (`!`) ou palavras alarmistas (`"Atenção!"`, `"Erro fatal!"`, `"Cuidado!"`) em mensagens de erro ou aviso.
|
||||
5. **Consistência de pessoa verbal (2ª pessoa):**
|
||||
- Dirigir-se diretamente ao usuário em 2ª pessoa (`"você"`, `"seu/sua"`).
|
||||
- **Nunca misturar** 1ª pessoa (`"Meus processos"`) e 2ª pessoa (`"Gerencie seus processos"`) na mesma tela ou fluxo.
|
||||
6. **Algarismos para números e zero abreviações truncadas (*Use numerals & Avoid abbreviations*):**
|
||||
- Escrever números, limites e contadores **sempre como algarismos** (`"3 condicionantes pendentes"`, `"Até 10 MB"`, `"Há 2 dias"`), nunca por extenso (`"três condicionantes"`).
|
||||
- **Proibido** usar abreviações truncadas na interface (`"Qtd."`, `"Obs."`, `"Cad."`, `"End."`, `"Dt."`, `"Máx."`, `"Mín."`, `"Tel."`). Escrever a palavra por extenso (`"Quantidade"`, `"Observações"`, `"Cadastro"`, `"Endereço"`, `"Data"`, `"Máximo"`).
|
||||
7. **Acessibilidade textual (*Alt text & Anti-truncamento cego*):**
|
||||
- Textos alternativos (`alt`) devem ser concisos (até **125 caracteres**) e descrever a função/conteúdo sem iniciar por `"Imagem de..."` ou `"Ícone de..."`. Imagens decorativas devem usar `alt=""`.
|
||||
- **Nunca truncar texto essencial** (`text-truncate` / `ellipsis`) sem oferecer forma acessível de leitura integral (tooltip no foco/hover ou expansão em clique).
|
||||
|
||||
---
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem esta regra, o agente gera interfaces com textos prolixos, capitalização inconsistente (*Title Case* misturado com *Sentence case*), botões de confirmação ambíguos (`Sim/OK`), abreviações amadoras (`Qtd.`, `Obs.`) e mensagens técnicas que confundem o usuário final.
|
||||
|
||||
## Referências
|
||||
|
||||
- Material Design 3 — Writing Best Practices: `https://m3.material.io/foundations/writing/best-practices`
|
||||
- Rule: `global/rules/zod-validacao-padrao` (schemas com mensagens customizadas)
|
||||
- Rule: `global/rules/refactoring-ui-hierarquia-despoluicao` (hierarquia visual e despoluição)
|
||||
- Skill: `skills/ux-fluxo-funcional/SKILL.md` (jornada e organização de telas, modais e painéis)
|
||||
- Workflow: `global/workflows/ux` (revisão de UX)
|
||||
|
|
@ -96,9 +96,9 @@ Toda construção ou refatoração em pacotes `*-front` (`@front`, `@ux`, `@land
|
|||
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).
|
||||
|
||||
### 7. Ergonomia Cognitiva, Orçamento de Viewport e Densidade Visual (Leis de Sweller, Hick e Miller)
|
||||
### 7. Ergonomia Cognitiva, Orçamento de Viewport e Organização de Telas, Modais e Painéis (Leis de Sweller, Hick, Miller e Material Design 3)
|
||||
|
||||
Mesmo respeitando pesos tipográficos e ausência de bordas, uma tela continuará **carregada e cansativa** se desperdiçar espaço de tela com múltiplas barras fixas, colidir painéis laterais ou pendurar dezenas de pílulas coloridas em cada linha. Todo frontend deve obedecer a 4 limites quantitativos de ergonomia espacial:
|
||||
Mesmo respeitando pesos tipográficos e ausência de bordas, uma tela continuará **carregada e cansativa** se desperdiçar espaço de tela com múltiplas barras fixas, colidir painéis laterais ou pendurar dezenas de pílulas coloridas em cada linha. Todo frontend deve obedecer a 5 limites quantitativos de ergonomia espacial:
|
||||
|
||||
1. **Orçamento de Viewport (Regra 75/25) e Teto de 2 Faixas no Topo:**
|
||||
- Em uma tela desktop padrão (`1366x768` ou `1440x900`), no mínimo **70%–75% da área da janela** deve pertencer ao **canvas principal de trabalho** (lista, árvore, tabela, Gantt, Kanban).
|
||||
|
|
@ -114,7 +114,11 @@ Mesmo respeitando pesos tipográficos e ausência de bordas, uma tela continuar
|
|||
- Ações secundárias de linha (ex.: `+ Sub`, `Editar`, `Excluir`) devem ficar ocultas ou discretas em repouso, revelando-se em `:hover` ou `:focus-within` (`opacity-0 group-hover:opacity-100`).
|
||||
4. **Revelação Progressiva Intra-Painel (*Inspetor em Acordeão & Zero Card de Resumo Redundante*):**
|
||||
- Painéis inspetores (`Drawer` / `Aside`) **nunca** devem iniciar com um "Card de Resumo" que duplica os mesmos dados já visíveis na linha selecionada e nos blocos editáveis imediatamente abaixo.
|
||||
- No máximo **2 seções primárias** (*Identificação/Prazo* e *Entrega*) devem iniciar abertas. Seções relacionais secundárias (*Pré-requisitos/Dependências*, *Recursos e Custos*, *Responsáveis*) devem utilizar **seções colapsáveis (Acordeão)** exibindo o resumo no próprio cabeçalho (ex.: `Recursos e Custos (2 • R$ 2.424,00)`) e abrindo a lista/formulário apenas quando expandidas pelo usuário.
|
||||
- No máximo **2 seções primárias** (*Identificação/Prazo* e *Entrega*) devem iniciar abertas. Seções relacionais secundárias (*Pré-requisitos/Dependências*, *Recursos e Custos*, *Responsáveis*) devem utilizar **seções colapsáveis (Acordeão)** exibindo o resumo no próprio cabeçalho (ex.: `Recursos e custos (2 • R$ 2.424,00)`) e abrindo a lista/formulário apenas quando expandidas pelo usuário.
|
||||
5. **Matriz de Superfícies, *Chunking* de Telas e Regiões Fixas em Modais/Painéis (Material Design 3):**
|
||||
- **Agrupamento temático em telas (*Chunking*):** Dividir formulários longos em blocos lógicos de no máximo **4 a 6 campos** encabeçados por título curto em *Sentence case* (`16px–20px`, peso `600`, sem `:` e sem `.`).
|
||||
- **Modais Básicos (*Basic Dialogs*, `400px–560px`):** Usar com parcimônia, apenas para confirmações críticas/destrutivas ou decisões rápidas (até 3–4 campos). **Proibido** usar modal para feedback passivo de sucesso (usar `v-snackbar`) ou formulários extensos de 6+ campos (usar *Side Sheet* ou Página).
|
||||
- **Regiões Fixas (*Pinned Header & Footer*):** Em modais (`v-dialog`) e painéis laterais (`Side Sheets`), o **Cabeçalho no topo** (com título em *Sentence case* e botão fechar `X` nos painéis) e a **Barra de Ações no rodapé** (`[Cancelar]` + `[Verbo específico]`, nunca `Sim/Não/OK`) devem permanecer **sempre fixos**, rolando apenas o corpo central caso necessário.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -142,18 +146,18 @@ Mesmo respeitando pesos tipográficos e ausência de bordas, uma tela continuar
|
|||
</v-card>
|
||||
```
|
||||
|
||||
### ✅ Correto — Hierarquia clara, menos bordas e pirâmide de ações (*Refactoring UI*)
|
||||
### ✅ Correto — Hierarquia clara, menos bordas, *Sentence case* e pirâmide de ações (*Refactoring UI* + M3)
|
||||
|
||||
```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>
|
||||
<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>
|
||||
<v-btn color="primary" variant="flat">Nova licença</v-btn>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
|
|
@ -180,6 +184,8 @@ Elimina o aspecto amador, sobrecarregado e confuso das interfaces geradas pela I
|
|||
## Referências
|
||||
|
||||
- Livro completo no Paiol: `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
|
||||
- Material Design 3 — Writing, Layout, Dialogs & Side Sheets: `https://m3.material.io/foundations/writing/best-practices`, `https://m3.material.io/components/dialogs/guidelines`, `https://m3.material.io/components/side-sheets/guidelines`
|
||||
- Rule: `global/rules/mensagens-usuario`
|
||||
- Rule: `global/rules/estilos-design-system`
|
||||
- Skill: `skills/ux/SKILL.md`
|
||||
- Skill: `skills/ux-fluxo-funcional/SKILL.md`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue