Label, Description e FieldError

Todo campo do Admin leva três textos de apoio. O Label dá o nome visível e acessível, a Description explica o formato ou onde o dado aparece, e o FieldError diz como corrigir. Dentro de um TextField eles se ligam ao campo sozinhos: nada de htmlFor ou aria-describedby à mão.

import { Description, FieldError, Label } from "@rastreio-x/ui";

Padrão

O Label fica sempre visível, acima do campo, em Title Case curto. Ele nomeia o campo; o placeholder só dá um exemplo.

Obrigatório

isRequired no TextField acende o indicador no Label e expõe aria-required ao campo. Marque os obrigatórios, não os opcionais, quando a maioria do formulário for obrigatória.

Estados

isInvalid e isDisabled do campo chegam ao Label, que muda de aparência. Estado nunca é só cor: acompanhe o inválido com um FieldError.

Descrição

A Description fica abaixo do campo e responde "o que eu coloco aqui?" ou "onde isso aparece?". Ela entra em aria-describedby, então o leitor de tela a lê depois do rótulo.

Erro de campo

O FieldError aparece quando o campo está inválido. Troque a Description pelo erro em vez de empilhar os dois, para o campo não crescer sem controle. A mensagem diz o que fazer.

Sem rótulo visível

Quando o contexto já nomeia o campo (a busca de uma barra de filtros, por exemplo), omita o Label e passe aria-label. Não troque o rótulo por placeholder.

Em um formulário do Admin

Os três juntos, como no formulário da Marca: rótulo em todo campo, descrição para o que não é óbvio e erro só depois que há algo a corrigir.

Anatomia

TextField
├── Label          nome do campo (sempre visível)
├── Input          o campo (ou TextArea, InputGroup)
├── Description    ajuda, abaixo do campo
└── FieldError     erro, no lugar da descrição

• Label usa <label> nativo e é ligado ao campo pelo TextField.
• Description e FieldError são ligados por aria-describedby.
• O FieldError do React Aria só renderiza quando o campo está inválido; com isInvalid controlado, renderize-o condicionalmente, como nos exemplos.

Propriedades

Rótulo (Label):

Descrição (Description):

Erro (FieldError):

Animações

Os três textos não animam. O FieldError ganha só uma transição curta de cor do HeroUI; com prefers-reduced-motion, a folha global da fachada a reduz a 0,01 ms. Nenhuma mensagem desliza ou pisca: o erro aparece e pronto.

Acessibilidade

• O Label é um <label> nativo: clicar nele foca o campo, e o texto é o nome acessível.
• Description e FieldError entram em aria-describedby do campo e são lidos depois do rótulo.
• O erro é anunciado quando surge, porque o campo passa a aria-invalid="true".
• O texto do erro usa o token de perigo com contraste mínimo de 4,5:1. O indicador de obrigatório nunca é o único sinal: o campo também expõe aria-required.
• Rótulo visível sempre que possível. Sem ele, aria-label no campo.

Boas práticas

• Escreva o Label como substantivo (Nome da Loja), não como pergunta ou frase.
• A Description explica; o FieldError instrui. Não repita a mesma frase nos dois.
• Valide ao sair do campo ou ao enviar, nunca a cada tecla.
• Troque a descrição pelo erro, não empilhe os dois.

Relacionados

• TextField o contêiner que liga os três ao campo.
• Input o campo de uma linha.
• TextArea o campo de várias linhas.
• InputGroup campo com prefixo e sufixo.