# Field

Wraps one form control with its label, hint and message, and connects them for assistive technology.

* Kind: component
* Page: https://design.werklist.com/components/field
* Version: 2.1.2

## When to use it

* Around each text field, text area, select, combobox, date field and time field in a form
* Around radio buttons or checkboxes that answer one question, as a fieldset with a legend

## When not to use it

* A search field in a toolbar: it has no visible label, and its placeholder gives its name
* A label beside the control: the label always sits above it

## Rules

* Check a format when the person leaves the field, and only when it holds a value
* Check required answers when the form is sent, and show every error at once
* Once an error shows, check again on each key so it clears at once
* Check an answer that depends on the server while the person types. The hint reads Checking until the answer comes back
* The form uses its own messages, never the browser's

## Anatomy

* Label: 13 px on 18 px, weight 500 (--text)
* Required word: (required) after the label, 13 px on 18 px, weight 400, hidden from screen readers (--text-muted)
* Count: 11 px on 16 px, aligned figures, at the end of the label row, written 412/500 and read as 412 of 500 characters (--text-muted)
* Label to control: 6 px
* Control: described on the page of each control
* Control to message: 4 px (--space-1)
* Hint: 12 px on 16 px, weight 400 (--text-muted)
* Error: 12 px on 16 px, no icon (--error)
* Warning: 12 px on 16 px, no icon (--warning-ink)
* Between fields: 16 px (--space-4)
* Between groups: 32 px (--space-8)
* Form column: at most 768 px

## States

* Required: (required) follows the label, and the control carries aria-required="true" (--text-muted)
* Error: The error replaces the hint, the control takes a 2 px edge in the error colour and aria-invalid="true", and the form is not sent (--error)
* Warning: The warning replaces the hint, and the form can be sent (--warning-ink)
* Read only: No fill, no ring and no side padding, with the value in full ink. It takes focus and is sent with the form (--text)
* Disabled: The control fades to 50 percent, Tab skips it and it is not sent. The label and the hint keep their ink, and the hint says what turns it on

## Keyboard

* Tab: Moves to the next control in the order the form shows them

## Accessibility

* A label element whose for attribute points at the control's id
* aria-describedby lists the message while one shows, otherwise the hint, and the count where there is one
* aria-invalid="true" while an error shows
* aria-required="true" on a required control. The visible word is hidden from screen readers so it is not read twice
* A message carries no role="alert". It is read when the control takes focus
* After a failed submit, focus moves as the Forms pattern describes, at /patterns/forms
* A field you type in shows focus with a blue ring and a halo. A combobox is a button that opens a list and shows focus as a button does, with a blue outline outside its edge
* A fieldset and a legend for controls that answer one question together
* Labels wrap and are not cut short

## Content

* Label: a noun phrase in sentence case with no colon and no full stop, such as Date of birth
* Hint: one sentence about the answer, ending with a full stop
* Error: the fix, in the words of the label, ending with a full stop, such as Enter the passport number. It never blames the person
* Placeholder: an example of the format only, never the label
* When every field is required: one sentence above the form, All fields are required, and no marks

## Tokens

* --text
* --text-muted
* --error
* --warning-ink
* --space-1
* --space-4
* --space-8