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
|
|
@ -1,120 +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
|
||||
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-09-28"
|
||||
updatedAt: "2026-10-26"
|
||||
---
|
||||
|
||||
# Regra: Mensagens Orientadas ao Domínio
|
||||
# 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 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**.
|
||||
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 visível na interface — erro, validação, confirmação, tooltip, empty state, ajuda — deve ser escrita na linguagem do domínio do módulo.
|
||||
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
|
||||
"Campo obrigatório"
|
||||
// ❌ 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
|
||||
"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"
|
||||
// ✅ 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 para o usuário
|
||||
### 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"
|
||||
"Network Error / ECONNREFUSED"
|
||||
|
||||
// ✅ CORRETO — mensagem humanizada
|
||||
"Não foi possível salvar. Tente novamente em instantes."
|
||||
// ✅ 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."
|
||||
"Sem conexão com o servidor. Verifique sua internet e tente novamente."
|
||||
```
|
||||
|
||||
### 3. Estados vazios devem explicar o contexto
|
||||
### 3. Estados vazios (*empty states*) devem explicar o contexto e orientar a ação
|
||||
|
||||
Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário:
|
||||
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
|
||||
"Nenhum registro encontrado"
|
||||
// ❌ ERRADO — genérico e sem saída
|
||||
"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."
|
||||
// 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. Confirmações devem descrever a consequência
|
||||
### 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
|
||||
"Tem certeza que deseja excluir?"
|
||||
"Confirmar operação?"
|
||||
// ❌ 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 — 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."
|
||||
// ✅ 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
|
||||
### 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
|
||||
label: "Nome"
|
||||
placeholder: "Digite aqui"
|
||||
// ❌ 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
|
||||
label: "Razão Social do Empreendedor"
|
||||
placeholder: "Ex: Mineração Vale Verde Ltda."
|
||||
// ✅ 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"
|
||||
placeholder: "Em hectares (ex: 150,5)"
|
||||
label: "Área total do empreendimento (ha)"
|
||||
placeholder: "Ex.: 150,5"
|
||||
```
|
||||
|
||||
### 6. Schemas Zod devem ter mensagens de domínio
|
||||
### 6. Schemas Zod devem ter mensagens de domínio em *Sentence case*
|
||||
|
||||
```typescript
|
||||
// ❌ ERRADO — mensagens padrão do Zod
|
||||
// ❌ ERRADO — mensagens padrão do Zod em inglês ou técnicas
|
||||
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"
|
||||
nome: z.string().min(1),
|
||||
area: z.number().positive(),
|
||||
})
|
||||
|
||||
// ✅ CORRETO — mensagens customizadas
|
||||
// ✅ CORRETO — mensagens customizadas em linguagem do domínio
|
||||
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" })
|
||||
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 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.
|
||||
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)
|
||||
- Workflow: `global/workflows/ux` (design de interface)
|
||||
- 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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue