2026-09-28 22:18:39 -03:00

3.8 KiB

Raw Blame History

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	global	glob	*/.vue, */.ts, */.tsx	2026-09-28

Regra: Mensagens Orientadas ao Domínio

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.

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.

Regra

1. Erros de validação devem indicar O QUE preencher, não O QUE falhou

// ❌ ERRADO — linguagem técnica
"Campo obrigatório"
"Erro de validação"
"Formato inválido"
"Payload inválido"

// ✅ 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"
"Informe o CNPJ no formato 00.000.000/0000-00"

2. Erros de sistema devem ser traduzidos para o usuário

// ❌ ERRADO — erro técnico exposto
"Erro 500: Internal Server Error"
"Timeout na requisição"
"Network Error"
"ECONNREFUSED"

// ✅ CORRETO — mensagem humanizada
"Não foi possível salvar. Tente novamente em instantes."
"A operação demorou mais que o esperado. Tente novamente."
"Sem conexão com o servidor. Verifique sua internet."

3. Estados vazios devem explicar o contexto

Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário:

// ❌ ERRADO — genérico
"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."

4. Confirmações devem descrever a consequência

// ❌ ERRADO — genérico
"Tem certeza que deseja excluir?"
"Confirmar operação?"

// ✅ 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."

5. Labels e placeholders devem usar vocabulário do domínio

// ❌ ERRADO — genérico
label: "Nome"
placeholder: "Digite aqui"

// ✅ CORRETO — específico do domínio
label: "Razão Social do Empreendedor"
placeholder: "Ex: Mineração Vale Verde Ltda."

label: "Área Total do Empreendimento"
placeholder: "Em hectares (ex: 150,5)"

6. Schemas Zod devem ter mensagens de domínio

// ❌ ERRADO — mensagens padrão do Zod
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"
})

// ✅ CORRETO — mensagens customizadas
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" })
    .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"),
})

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.

Referências

Rule: global/rules/zod-validacao-padrao (schemas com mensagens customizadas)
Workflow: global/workflows/ux (design de interface)

3.8 KiB Raw Blame History