antigravity-tooltip

name: antigravity-tooltip description: "Use esta skill antes de escrever qualquer titulo ou descricao de TooltipGlobal na plataforma. Define a filosofia central (tooltip responde 'o que esse campo faz pela minha empresa', nunca como funciona internamente), as 5 regras invioláveis (sem ponto final, idioma do usuario, max 90 chars na descricao, titulo vs descricao, sem jargao), padroes por contexto (campo editavel, dependente, somente-leitura, coluna de tabela, botao), anti-padroes e exemplos aprovados do Workspace Gravity."

Skill: Escrita de Tooltips

Filosofia Central

A tooltip responde uma única pergunta do usuário:

"O que esse campo/dado faz pela minha empresa?"

Nunca como o sistema funciona internamente. O usuário não sabe — e não precisa saber — que existe uma API, um banco de dados ou qualquer lógica de programação.

As 5 Regras Invioláveis

1. Sem ponto final

O texto da descricao nunca termina com ponto.

❌ "Razão social da empresa."
✅ "Razão social da empresa"

2. Idioma do usuário, não do desenvolvedor

Nunca mencione implementação técnica.

❌ "Carregado via API do IBGE com base no estado selecionado"
✅ "A lista de cidades aparece após você escolher o estado"

❌ "Utilizado no backend para cálculos fiscais"
✅ "Aparece em notas fiscais e relatórios gerados pela plataforma"

❌ "Renderizado via ReactDOM.createPortal"
✅ — (isso nunca deveria estar em uma tooltip)

3. Máximo ~90 caracteres na descricao

Uma frase. Se precisar de mais, a tooltip está errada — o design do campo precisa melhorar.

4. titulo = nome do conceito, descricao = o que o usuário faz ou ganha

O titulo pode ser igual ao label do campo. A descricao é onde está o valor real.

// Correto
<TooltipGlobal
  titulo="CNPJ"
  descricao="Aparece em notas fiscais e documentos gerados na plataforma"
>

// Errado — descricao redundante com o titulo
<TooltipGlobal
  titulo="CNPJ"
  descricao="Campo de CNPJ da empresa"
>

5. Sem jargão técnico, sem siglas sem contexto

Use linguagem que um gerente administrativo entenderia.

❌ "Define o slug da organização no multi-organização router"
✅ "Endereço exclusivo da sua conta — não pode ser alterado após a criação"

❌ "Foreign key vinculada ao registro pai"
✅ "Workspace ao qual este usuário está vinculado"

Perguntas de Checagem

Antes de publicar uma tooltip, responda:

1. O que o usuário FAZ com esse campo? → ex: "digita a razão social", "seleciona um estado"

2. O que acontece com esse dado depois? → ex: "aparece nos relatórios", "define o contexto da sessão", "enviado nas notas fiscais"

3. Existe comportamento especial que o usuário não esperaria? → ex: "a lista muda quando você troca o estado", "não pode ser editado após salvar"

4. Esse campo depende de outro campo? → se sim, mencione a dependência de forma simples

Padrões por Tipo de Contexto

Campo de formulário editável

Responda: O que esse dado representa e onde ele aparece depois?

Campo dependente de outro campo

Responda: Qual a condição para esse campo funcionar?

✅ "A lista de cidades aparece após você escolher o estado"
✅ "Disponível somente para usuários do tipo Master"
✅ "Calculado com base no período de vigência do contrato"

Campo somente-leitura / metadado

Responda: O que esse valor significa para o negócio?

✅ "Endereço exclusivo da sua conta — não pode ser alterado"
✅ "Calculado desde a data de ativação da conta"
✅ "Definido automaticamente com base no plano contratado"

Coluna de tabela

Responda: O que esse valor representa no contexto das linhas da tabela?

✅ "Total de usuários com acesso ativo neste Workspace"
✅ "Indica se a empresa está operando normalmente ou com acesso bloqueado"
✅ "Data em que a empresa foi cadastrada no sistema"

Exceção — Lista de Pedidos (hierarquia pedido → item)

Na lista /pedido/pedidos/lista, não use só TooltipGlobal com titulo + descricao de 90 caracteres para explicar regras de edição. Use o componente dedicado TooltipRegrasColuna (pills + aviso amarelo opcional).

• Pills: texto curto, sem ponto final — mesma regra desta skill.
• Aviso amarelo (AvisoImpactoEdicao): pode ultrapassar 90 caracteres; frase completa sobre impacto em outras colunas.
• SSOT: LISTA-EDITAR-SALVAR-TECNICO.md §6 (técnico) e LISTA-EDITAR-SALVAR-REGRAS-NEGOCIO.md §0 (negócio).
• Código: servicos-global/produto/pedido/client/src/shared/TooltipRegrasColuna.tsx, pillsTooltipColunaLista.ts.

Botão ou ação destrutiva

Responda: O que acontece imediatamente ao clicar? Há consequência?

✅ "Todo acesso deste Workspace será bloqueado imediatamente"
✅ "Define esta empresa como contexto da sua sessão — afeta todos os dados exibidos"
✅ "As alterações serão descartadas e o formulário voltará ao estado original"

Anti-padrões — Nunca Use

❌ Implementação exposta:
   "via API", "via IBGE", "carregado do banco", "query no backend"

❌ Passivo e vago:
   "utilizado para X", "referente ao campo X", "campo obrigatório"

❌ Redundância com o label:
   label = "Status" → descricao = "Status da empresa" (inútil)

❌ Muito longo:
   Mais de 2 linhas quebra o card e ninguém lê

❌ Ponto final:
   toda frase na descricao termina sem ponto

❌ Inglês:
   A plataforma é PT-BR. Tooltips também.

❌ Tom técnico ou formal demais:
   "Mediante seleção do estado federativo correspondente..."
   Use: "Após escolher o estado"

Template para Novos Campos

Sempre que for adicionar TooltipGlobal a um novo campo, use este raciocínio:

Campo: [nome do campo]
Tipo: [editável | somente-leitura | coluna | botão | dependente]
O usuário faz o quê com isso? → [resposta]
O que acontece com o dado? → [resposta]
Tem comportamento especial? → [sim/não → qual]
---
titulo: [nome do conceito — geralmente igual ao label]
descricao: [frase curta, ativo, sem ponto, sem jargão, max 90 chars]

Exemplos Reais do Workspace Gravity

Organizacao.tsx

TabelaGlobal — workspaces

TabelaGlobal — Usuários