.agent/global/rules/mensagens-usuario.md

type	name	description	scope	trigger	globs	updatedAt
rule	mensagens-usuario	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	global	glob	**/*.vue, **/*.ts, **/*.tsx	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):

// ❌ 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:

// ❌ 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:

// ❌ 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].

// ❌ 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:

// ❌ 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

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