.agent/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 do módulo (definido em memorias-ia/modulo.yml), 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 do ecossistema é especialista no domínio de negócio do módulo (cujo escopo, propósito e público-alvo devem ser consultados obrigatoriamente em memorias-ia/modulo.yml nos campos modulo-descricao e modulo-tipo) — mas não tem obrigação de entender engenharia de software ou banco de dados.

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 ativo à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 Razão Social da Organização"

// ✅ CORRETO — linguagem do domínio + Sentence case (M3)
"Informe a razão social da organização"
"Selecione a categoria da solicitação"
"A data de conclusão deve ser posterior à data de início"
"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 título 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 contexto do domínio e orienta
// Título (sem ponto final): "Nenhuma etapa cadastrada neste cronograma"
// Apoio: "Para iniciar o acompanhamento de prazos, adicione a primeira etapa."
// Botão CTA: "Adicionar etapa"

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 etapa do cronograma?",
  corpo: "Os prazos e os documentos vinculados a esta etapa serão removidos permanentemente.",
  botoes: ["Cancelar", "Excluir etapa"]
}

{
  titulo: "Arquivar solicitação?",
  corpo: "Esta solicitação sairá das listagens ativas, mas poderá ser consultada no histórico.",
  botoes: ["Cancelar", "Arquivar solicitação"]
}

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 Solicitante:"

// ✅ CORRETO — específico do domínio, Sentence case e sem pontuação final
label: "Razão social do solicitante"
placeholder: "Ex.: Organização Vale Verde Ltda."

label: "Valor estimado do contrato (R$)"
placeholder: "Ex.: 15.000,00"

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 zCadastro = z.object({
  nome: z.string().min(1),
  valor: z.number().positive(),
})

// ✅ CORRETO — mensagens customizadas em linguagem do domínio
const zCadastro = z.object({
  nome: z.string().min(1, "Informe a razão social da organização"),
  valor: z.number({ invalid_type_error: "Informe um valor numérico válido" })
    .positive("O valor 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, CEP, UF, PDF, API).
   • 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 solicitação", "Salvar alterações", "Dados do responsável").
   • Proibido usar Title Case anglófono ("Salvar Alterações", "Dados Do Responsável") 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 concluir a solicitação, anexe o documento comprobatório"
   • ❌ "Anexe o documento comprobatório para concluir a solicitação"
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 ("Minhas solicitações") e 2ª pessoa ("Gerencie suas solicitações") 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 pendências encontradas", "Até 10 MB", "Há 2 dias"), nunca por extenso ("três pendências").
   • 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 ou de outro domínio 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/identidade-modulo (memorias-ia/modulo.yml)
• 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)