Form Field

Quando usarWhen to use

AnatomiaAnatomy

Encapsulando controlesWrapping form controls

Form Field é agnóstico ao tipo de controle. Funciona com Input, Textarea e Select via label[for]. Para grupos (Checkbox/Radio), use <fieldset> + <legend> em vez de label/for individual — a semântica de grupo é diferente da semântica de controle único.Form Field is control-agnostic. Works with Input, Textarea, and Select via label[for]. For groups (Checkbox/Radio), use <fieldset> + <legend> instead of individual label/for — group semantics differ from single-control semantics.

Nota: para grupos, aria-describedby vai no container do grupo; <legend> substitui <label>. O wrapper <fieldset class="ds-field"> herda o gap vertical igual ao Input.Note: for groups, aria-describedby goes on the group container; <legend> replaces <label>. The <fieldset class="ds-field"> wrapper inherits the same vertical gap as Input.

Error stateError state

Adicione .ds-field--error no wrapper, aria-invalid="true" + aria-describedby no controle apontando para o id do error. role="alert" no error garante anúncio imediato para screen readers.Add .ds-field--error on the wrapper, aria-invalid="true" + aria-describedby on the control pointing to the error's id. role="alert" on the error ensures immediate screen reader announcement.

<div class="ds-field ds-field--error">
  <div class="ds-field__label-row">
    <label class="ds-field__label" for="email">Email address</label>
    <span class="ds-field__required" aria-hidden="true">*</span>
  </div>
  <div class="ds-input ds-input--error">
    <input type="email" id="email" class="ds-input__field"
           value="not-an-email"
           aria-required="true"
           aria-invalid="true"
           aria-describedby="email-error">
  </div>
  <span class="ds-field__error" id="email-error" role="alert">
    Please enter a valid email address.
  </span>
</div>

Boas práticasBest practices

Checklist de acessibilidadeAccessibility checklist

• label com for= matching o id do controle (WCAG 1.3.1, 3.3.2).label with for= matching the control's id (WCAG 1.3.1, 3.3.2).
• Required: aria-required="true" no controle. Asterisco visual com aria-hidden="true".Required: aria-required="true" on the control. Visual asterisk with aria-hidden="true".
• Helper text: aria-describedby no controle apontando pro id do helper.Helper text: aria-describedby on the control pointing to helper's id.
• Error: aria-invalid="true" no controle, aria-describedby apontando pro id do error, e role="alert" no error pra anúncio imediato.Error: aria-invalid="true" on the control, aria-describedby pointing to error's id, and role="alert" on the error for immediate announcement.
• Sem label visível: use aria-label direto no controle E aplique .ds-field--no-label pra esconder a row.No visible label: use aria-label on the control directly AND apply .ds-field--no-label to hide the row.
• Grupos (Checkbox/Radio): use <fieldset> + <legend> em vez de label/for individual.Groups (Checkbox/Radio): use <fieldset> + <legend> instead of individual label/for.

Mapeamento de tokensToken mapping

Esses tokens existem como contrato CSS-only do Form Field. Eles aliasam Semantic quando o valor já é uma decisão reutilizável e não criam um componente visual Form Field no Figma, conforme ADR-017.These tokens exist as the CSS-only Form Field contract. They alias Semantic when the value is already reusable and do not create a visual Form Field component in Figma, per ADR-017.

Classes CSSCSS classes

RelacionadosRelated