.agent/rules/mensagens-usuario.md

---
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)