Form Field

Wrapper composite que junta label, controle (Input/Select/Textarea), required indicator, helper text e error message. É onde a acessibilidade de form se materializa: associação correta de label↔controle, aria-describedby pra helper, aria-invalid em estado de erro.Composite wrapper that pairs label, control (Input/Select/Textarea), required indicator, helper text, and error message. This is where form accessibility lives: correct label↔control association, aria-describedby for helpers, aria-invalid on error.

Quando usarWhen to use

Use Form Field quandoUse Form Field when

Qualquer controle de formulário precisar de label visível, helper text ou validação. Sempre que houver Input, Select ou Textarea com contexto adicional, eles devem estar dentro de um Form Field — é o que conecta os pedaços de forma acessível.Any form control needs a visible label, helper text, or validation. Whenever you have an Input, Select, or Textarea with additional context, they should live inside a Form Field — it connects the pieces accessibly.

Não use Form Field quandoDon't use Form Field when

O controle não precisa de label visível (ex: search input no header com ícone, com aria-label direto no controle). Mesmo assim, considere usar Form Field com --no-label pra manter consistência de espaçamento.The control doesn't need a visible label (e.g., search input in header with icon, using aria-label directly). Even so, consider Form Field with --no-label to keep spacing consistent.

AnatomiaAnatomy

Email address

We'll never share your email. 1 2 3 4 5

1 Label (.ds-field__label) — texto descritivo, com for= apontando pro id do controle.
2 Required indicator (.ds-field__required) — asterisco visual, aria-hidden="true" (a obrigatoriedade vem do aria-required no controle).
3 Controle — Input/Select/Textarea/Checkbox group, com id matching o label e aria-describedby apontando pro helper.
4 Helper text (.ds-field__helper) — orientação ou contexto adicional, com id referenciado pelo aria-describedby do controle.
5 Error message (.ds-field__error) — mensagem de validação, aparece apenas em .ds-field--error com role="alert". 1 Label (.ds-field__label) — descriptive text with for= pointing to the control's id.
2 Required indicator (.ds-field__required) — visual asterisk, aria-hidden="true" (required state comes from aria-required on the control).
3 Control — Input/Select/Textarea/Checkbox group, with matching id and aria-describedby pointing to the helper.
4 Helper text (.ds-field__helper) — guidance or additional context, with id referenced by control's aria-describedby.
5 Error message (.ds-field__error) — validation message, shown only in .ds-field--error with role="alert".

Encapsulando controlesWrapping form controls

Form Field é agnóstico ao tipo de controle. Funciona com Input, Textarea e Select via label[for]. Pra grupos (Checkbox/Radio), use <fieldset> + <legend> em vez de label/for individual — semantica de grupo é diferente da semantica 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.

Full name

As shown on your ID.

Notes

Up to 500 characters.

Country

Used for shipping calculations.

Notification preferences

Email SMS Push notifications

Choose how we contact you.

Plan

Monthly — $9 Annual — $90 Lifetime — $300

You can change this anytime.

Note: 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 pro id do error. role="alert" no error garante anúncio imediato pra 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.

Email address

Please enter a valid email address.

<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>

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.

ClassesClasses

Class	UsoUsage
`ds-field`	Wrapper. Stack vertical com gap consistente.Wrapper. Vertical stack with consistent gap.
`ds-field__label-row`	Linha do label + required (horizontal).Label + required row (horizontal).
`ds-field__label`	Texto do label (14px medium).Label text (14px medium).
`ds-field__required`	Asterisco visual (decorativo, `aria-hidden`).Visual asterisk (decorative, `aria-hidden`).
`ds-field__helper`	Helper text (12px secundário).Helper text (12px secondary).
`ds-field__error`	Mensagem de erro. Visível apenas em `--error`.Error message. Visible only with `--error`.
`ds-field--error`	Modificador: estado de erro. Mostra error message, tinge label.Modifier: error state. Shows error message, tints label.
`ds-field--no-label`	Modificador: esconde label-row. Usar com `aria-label` no controle.Modifier: hides label-row. Pair with `aria-label` on control.
`ds-field--no-helper`	Modificador: esconde helper.Modifier: hides helper.