Skip to content
GitHub
Sections

Reference · Components and layout

Form field

This is a spec: descriptive guidance, not a checkable rule. It carries no forbidden and instead pair, and no jig check detector applies to it directly.

The spec

Anatomy, in this order:

  1. 1.
    <label> — always visible, stacked above the input (F-98)
  2. 2.
    Required or optional marker, in the label (F-97)
  3. 3.
    Hint text — above the input, below the label
  4. 4.
    Error message — also above the input, after the hint, role="alert"
  5. 5.
    Input

States: default, focus, filled, invalid, disabled, read-only.

Label

  • Above the input, never beside it. Left-placed labels force the eye to zig-zag; right-aligning them to fix that creates a jagged left edge that is harder to scan; and long labels wrap badly in the narrow column. Stacked above, the label and input are taken in with a single focus.
  • Close to its input — --spacing-label (4px), against --spacing-stack between fields. The label must be visibly closer to its own input than to anything else, or the pairing is ambiguous (D-25).
  • No instructional verbs. "Email", not "Enter your email" or "Type your email here". The input field already implies the verb.
  • No "my" or "your" (I-88).

Required and optional

Mark both. Marking only optional fields, with "all fields are required unless marked optional" at the top, fails because people scan past instructions — and marking both is an accessibility requirement for screen reader users anyway.

Marker
Required* with the convention stated at the top, or the word "required"
OptionalThe word "optional"

The word "required" is the safer of the two: no instruction needed anywhere, no assumption that the asterisk is understood. The asterisk is more concise and lets people scan the count of required fields at a glance. Either is fine; be consistent.

Never colour the asterisk red. Red means error.

You may leave required fields unmarked only when: the product has no optional fields anywhere; the form is short and familiar (login, newsletter signup); the form asks one question per screen with the reason explained; or testing has shown it is unnecessary.

Hints

Above the input, not below. Two reasons: a rule about a password's minimum length is useful before typing, not after failing; and the space below an input gets covered by autofill menus and on-screen keyboards, so a hint placed there may never be seen.

Do not hide a hint in a tooltip if it is needed to complete the field.

The error message goes above the input too, and for the second of those reasons. The space below a field is covered by autofill menus and on-screen keyboards at exactly the moment an error appears — so an error placed there is hidden from the person who most needs to see it. Putting the hint above and the error below would have taken half of one argument and ignored the other half.

Order between them: hint first, then error. The hint is standing guidance about the field; the error is a transient response to what was just typed, so it sits closest to the input it is about.

Placeholders

Not a label (F-36). Placeholders vanish on focus, make an empty field look pre-filled and skippable, and are light enough by design that they usually fail contrast.

Use one only as a format example — MM / YY — or in a single-field search box, and then at 4.5:1 with a real accessible label present.

Width

Match the width to the expected input. A four-character postcode gets a four-character field. Uniform full-width fields look tidy and lie about the input: width is the strongest hint people have about how much is wanted. Where length varies, size for the common case.

Conventional styling

Keep the iconic parts (E-52): a rectangle with the label above, a square with a tick for checkbox, a circle for radio. If you restyle — enlarging a radio's target area, say — keep the circle on the left of the label. Without it, nobody can tell whether one option or several can be chosen.

Other rules

  • Error text says what to do (F-37), signalled by border and text and aria-invalid — never colour alone (C-20).
  • type, inputmode, autocomplete, enterkeyhint set correctly (F-40).
  • Field borders clear 3:1 (02-tokens.md). Low-contrast borders are the single most common form defect, and they fail for a sighted user in sunlight as readily as for someone with low vision.
  • Never reformat or truncate a value while it is being typed.
Kind
Spec
Section
Components and layout

Read as plain text