# O texto da interface

A peça certa com o texto errado é uma tela errada. Este arquivo diz **o que
escrever dentro** dos componentes, e é a parte do trabalho que nenhuma guarda
mede: `tsc`, contraste, `check:classes` e os testes passam inteiros sobre uma
mensagem que não ajuda ninguém.

## Conteúdo

- As três frases que toda tela escreve
- O botão diz o que vai acontecer
- O par de botões nunca repete a mesma palavra com dois sentidos
- A mensagem de erro nomeia quem falhou e o que fazer
- O vazio é uma porta, não um aviso
- Rótulo, dica e placeholder
- Link e lista começam pela palavra que informa
- Preço e parcela
- Forma: pessoa, tempo e tamanho
- O texto que a peça escreve sozinha mora em `labels`

## As três frases que toda tela escreve

Toda listagem, todo gráfico e todo formulário escrevem estas três, e são elas
que a pessoa lê nos piores dias:

| Momento | Quem escreve | O que a frase precisa ter |
|---|---|---|
| Deu erro | `errorTitle` + `errorMessage` | o que falhou, quem falhou, e o que fazer agora |
| Não há nada | `empty` (título + descrição) | por que está vazio, e o caminho para deixar de estar |
| Vai sem volta | título + descrição do `AlertDialog` | o efeito, quem é avisado, e que não se desfaz |

## O botão diz o que vai acontecer

O rótulo é um **verbo com o objeto**, não uma categoria. A pessoa decide olhando
o botão, e "Confirmar" não diz o que ela está confirmando.

| Em vez de | Escreva |
|---|---|
| Confirmar | Emitir nota |
| Salvar | Salvar rascunho |
| OK | Entendi |
| Enviar | Enviar para a prefeitura |
| Sim | Cancelar nota |

Quando a ação não tem volta, o verbo carrega isso: "Cancelar nota" e não
"Continuar".

## O par de botões nunca repete a mesma palavra com dois sentidos

É o defeito de texto mais caro que existe, e ele aparece exatamente onde dói:
na caixa que confirma uma ação sem volta.

```tsx
<AlertDialogTitle>Cancelar a nota 4813?</AlertDialogTitle>
<AlertDialogDescription>
  A prefeitura recebe o cancelamento e o cliente é avisado. Não dá para desfazer.
</AlertDialogDescription>
<AlertDialogFooter>
  <AlertDialogClose render={<Button variant="secondary" />}>Manter nota</AlertDialogClose>
  <AlertDialogClose render={<Button variant="danger" />}>Cancelar nota</AlertDialogClose>
</AlertDialogFooter>
```

O botão de escape diz **"Manter nota"**. Se dissesse "Cancelar", a palavra
significaria duas coisas opostas dentro da mesma caixa — abortar a operação e
cancelar a nota — e a pessoa teria que adivinhar qual, numa ação que avisa a
prefeitura e não tem volta.

A regra sai daí: **o escape nomeia o estado que fica**, não a desistência.
"Manter nota", "Continuar editando", "Ficar aqui". Nunca "Cancelar" ao lado de
uma ação que também se chama cancelar.

No `Popconfirm`, e no `AlertDialog` do pacote nativo, o par se escreve em
`labels`, com as mesmas chaves nos dois:
`labels={{ confirm: "Cancelar nota", cancel: "Manter nota" }}`. O `confirm` é
obrigatório nas duas peças, sem padrão: a peça não sabe a ação, e um
"Confirmar" de fábrica é exatamente o rótulo que esta página proíbe. Sem
`cancel`, o escape é "Cancelar", e vira "Voltar" quando o `confirm` já começa
com "Cancelar" - mas o melhor escape é o que nomeia o estado que fica.

O título é uma **pergunta que nomeia o objeto**: "Cancelar a nota 4813?", e não
"Tem certeza?". Um número no título é o que permite descobrir que se clicou na
linha errada.

## A mensagem de erro nomeia quem falhou e o que fazer

Duas frases, e cada uma tem um trabalho. É o padrão que o catálogo inteiro já
usa, e ele não se negocia por pressa:

```tsx
<DataTable
  isError={query.isError}
  errorTitle="Não foi possível carregar as notas"
  errorMessage="A prefeitura não respondeu. Tente de novo em alguns minutos."
  onRetry={query.refetch}
  labels={{ retry: "Tentar de novo" }}
/>
```

- **`errorTitle`** diz o que falhou, nomeando o objeto: "as notas", "o
  faturamento", "a agenda". Nunca "Erro" nem "Algo deu errado".
- **`errorMessage`** diz **quem** falhou e **o que fazer**: "A prefeitura não
  respondeu", "A consulta expirou", seguido de "Tente de novo em alguns
  minutos". Quem falhou é o que decide se a pessoa espera, corrige ou liga para
  alguém.
- **`onRetry`** existe quando repetir resolve. Erro que não tem saída não ganha
  botão, ganha o caminho: quem procurar, ou onde olhar.

Nunca escreva código de erro, `stack` ou nome de endpoint na tela. Isso é para o
log.

**Erro de campo é diferente de erro de tela**: o do campo diz o formato aceito
("Use o formato 00.000.000/0000-00"), e não "Valor inválido". Inválido a pessoa
já sabia; o que ela não sabe é o que serve.

## O vazio é uma porta, não um aviso

O mesmo componente tem dois textos diferentes, e trocá-los é o erro comum:

| Situação | Título | Descrição |
|---|---|---|
| Nunca houve nada | "Nenhuma nota" | "Emita a primeira para ela aparecer." |
| O filtro não achou | "Nenhuma nota no período" | mude o filtro, e diga qual |
| A busca não achou | "Nenhum cliente com esse nome" | — |

O primeiro caso é a primeira vez da pessoa no produto, e ele merece a **ação**
junto:

```tsx
<EmptyState
  title="Nenhuma nota"
  description="Emita a primeira para ela aparecer."
  action={<Button>Emitir nota</Button>}
/>
```

O segundo e o terceiro **não** levam ação de criar: quem filtrou quer o filtro
de volta, não um cadastro. E o texto nomeia o recorte que não achou — "no
período", "com esse nome" —, porque é ele que a pessoa vai mexer.

O desenho não segue essa divisão, e sim o tamanho do vazio: o que ocupa a
página ou a seção leva `illustration` nos três casos (`EmptyList` no primeiro,
`NoResults` no filtro e na busca; em produto da RivoCode, o Bacalhau em
`pose="emptyBox"` e `pose="shrug"`), e o vazio pequeno, numa coluna ou num
cartão estreito, leva `icon`. Quando usar cada um, e como pintar sem cor
literal, está em [design.md](design.md#ícone-ou-ilustração-no-estado-vazio).

## Rótulo, dica e placeholder

Todo campo tem os três, cada um com um trabalho.

- **Rótulo** nomeia o campo e fica sempre visível. Não é frase, não tem dois
  pontos: "CNPJ do cliente", não "Digite o CNPJ do cliente:".
- **Placeholder** mostra o **formato** ou um **exemplo real**, e nunca é rótulo.
  Ele some ao digitar, tem contraste baixo de propósito, e vários leitores de
  tela não o anunciam: usado como rótulo, o campo fica sem nome assim que a
  pessoa começa a escrever.
- **Dica** (`description`) explica a consequência, não repete o rótulo. "Ela
  aparece no corpo da nota" vale; "Informe a descrição" não vale nada.
- **Texto acessível de ícone** diz a ação, não o desenho: `IconButton` com
  `label="Excluir a nota 4813"`, nunca "Lixeira".

**Obrigatório e opcional: marque a minoria.** Cadastro, emissão e checkout,
onde quase tudo é obrigatório, marcam só o opcional, com
`<FieldLabel necessity="optional">` (ou `necessity` no `FormField`), que
escreve "(opcional)" em texto. É o padrão da casa quando há dúvida, porque
texto escrito não depende de legenda nem de cor. Filtro e preferência, onde
quase tudo é opcional, marcam só o obrigatório, com `necessity="required"` e
`required` no controle: o asterisco é escondido do leitor de tela, que ouve o
`required`. Nunca os dois no mesmo formulário, nunca "(obrigatório)" escrito à
mão, e nunca nenhum quando há dos dois tipos. No nativo o nome é o mesmo, e o
asterisco se fala "obrigatório".

O placeholder sai do dado:

| Campo | Placeholder | Quem escreve |
|---|---|---|
| CPF | `000.000.000-00` | o `MaskedInput mask="cpf"` |
| CNPJ | `00.000.000/0000-00` | o `MaskedInput mask="cnpj"` |
| CPF ou CNPJ | `000.000.000-00` | o `MaskedInput mask="cpfCnpj"` |
| Telefone | `(00) 00000-0000` | o `MaskedInput mask="telefone"` |
| Placa | `ABC1D23` | o `MaskedInput mask="placa"` |
| Cartão | `0000 0000 0000 0000` | o `MaskedInput mask="cartao"` |
| CEP | `00000-000` | o `PostalCodeField`, e o `MaskedInput mask="cep"` |
| Molde escrito à mão | um exemplo, `Ex.: SP-0412` | você |
| Data | `dd/mm/aaaa` | o `DatePicker` |
| Hora | `hh:mm` | o `TimeField` |
| Dinheiro | `0,00` | o `CurrencyInput` |
| E-mail | `nome@empresa.com.br` | você |
| Nome, razão social, cidade, descrição | `Ex.: Clínica São Lucas Ltda.` | você, com um valor que a pessoa reconheceria |
| Busca | `Buscar por número ou cliente` | você: o `SearchInput` nasce com "Buscar", e o seu diz por onde ela procura |
| Seletor sem escolha | `Selecione o status` | o `Select`, o `Combobox` e o `TreeSelect` nascem com "Selecione"; o seu diz o que se escolhe |
| Senha, código de verificação | nenhum | não há formato a mostrar |

Três formas de errar, e todas ocupam o lugar do exemplo sem dizer nada novo:

| Em vez de | Escreva |
|---|---|
| `placeholder="Digite o nome do cliente"` | `placeholder="Ex.: Clínica São Lucas Ltda."` |
| `placeholder="E-mail"`, sob o rótulo "E-mail do cliente" | `placeholder="nome@empresa.com.br"` |
| `placeholder="CNPJ"`, sem rótulo nenhum | rótulo "CNPJ do cliente" e `placeholder="00.000.000/0000-00"` |

```tsx
<FormField name="email" label="E-mail do cliente" description="O PDF da nota vai para este endereço.">
  {(field) => <Input {...field} type="email" autoComplete="email" placeholder="nome@empresa.com.br" />}
</FormField>
```

## Link e lista começam pela palavra que informa

Quem passa o olho lê as duas primeiras palavras de cada linha. Comece por elas.

- **O link diz para onde vai**: "Ver a nota 4813", "Política de trocas", e
  nunca "clique aqui" nem um "Saiba mais" que só faz sentido com o cartão em
  volta. O leitor de tela lista os links soltos, e três "Saiba mais" seguidos
  não dizem nada (WCAG 2.4.4).
- **O item de lista começa pelo assunto**: "Nota 4816 emitida para a Clínica
  São Lucas", e não "Foi emitida com sucesso a nota…".
- **A notificação começa pelo que mudou**: "Pagamento de R$ 1.284,90
  recebido", e não "Você tem uma nova atualização".

## Preço e parcela

O preço se escreve pelo total à vista, e a parcela nunca vem sozinha: "ou 12x
de R$ 119,90 sem juros", e com juros também a taxa e o total a prazo. A forma
inteira, com a regra que a pede, está em [comercio.md](comercio.md).

## Forma: pessoa, tempo e tamanho

- **Fale com a pessoa, na segunda pessoa**: "Você ainda não emitiu nenhuma
  nota". O sistema não fala de si: nada de "Estamos processando".
- **Presente, e voz ativa.** "A prefeitura não respondeu", não "Não foi possível
  que a resposta fosse obtida".
- **Sem culpa e sem susto.** Não diga que a pessoa errou; diga o que serve.
  Ponto de exclamação não pertence a nenhuma mensagem de sistema.
- **Frase curta e sem jargão nosso.** "A consulta expirou", não "timeout no
  gateway".
- **PT-BR na tela, código em inglês.** Termo do ecossistema não se traduz: é
  "agents", não "agentes".
- **Sem travessão na prosa da tela.** Duas frases curtas cabem melhor num alerta
  do que uma longa com aposto.

## O texto que a peça escreve sozinha mora em `labels`

O nome de um botão que a peça desenha, o que o leitor de tela ouve, uma frase
fixa como "da etapa anterior": tudo isso se troca por um objeto só, `labels`,
nos dois pacotes e com as mesmas chaves. Passe só as chaves que mudam.

```tsx
<QueryBoundary data={data} isError={isError} onRetry={refetch} labels={{ retry: "Carregar de novo" }}>
  {(invoices) => <InvoiceList invoices={invoices} />}
</QueryBoundary>
```

Não há prop solta terminada em `Label` para texto de interface. O que continua
prop é conteúdo: o `label` que dá nome ao campo, o `title` e o `errorTitle` do
aviso, o `placeholder`.

Data tem duas metades. O nome do mês, do dia da semana e a hora saem do
`locale` (tag BCP 47, `"en-US"`), no `EventCalendar` e no `Gantt`, e o
`DatePicker` e o `DateRangePicker` do web recebem o `locale` do calendário. As
palavras fixas em volta ("Hoje", "+2 mais", "Dia inteiro", "das 9h às 10h",
"12 a 18") são `labels`. No nativo não há `locale`: o `Calendar`, o
`DatePicker` e o `DateRangePicker` trocam os nomes do mês e as iniciais por
`labels.caption` e `labels.weekdays`.

```tsx
<EventCalendar
  events={events}
  locale="en-US"
  labels={{ today: "Today", week: "Week", events: (count) => `${count} events` }}
/>
```
