--- 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 (`

Documentos exigidos

` e nunca `

Documentos exigidos:

`). - **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)