# Radio

Chooses exactly one option from a short list shown in full.

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

## When to use it

* Two to five options the reader compares before choosing.
* Options that need a sentence or a description each.
* A choice inside a form that applies on submit.

## When not to use it

* More than five options or little room: use Select.
* Two to five one word values that apply at once: use SegmentedControl.
* Any number of choices: use Checkbox.
* One on or off setting: use Checkbox or Switch.

## Rules

* Two to five visible options, one chosen from the start.
* A long list, such as a country of origin, is a Select or a Combobox.
* One setting that is on or off is one Checkbox or Switch, not two radio buttons for Yes and No.

## Anatomy

* Circle: 16 px (--radius-full)
* Edge at rest: 1 px inset, rgba(13, 18, 40, 0.55) in light, rgba(255, 255, 255, 0.2) in dark, as on the checkbox
* Fill at rest: #ffffff in light, --surface-control in dark, as on the checkbox
* Fill chosen (--brand-blue)
* Dot: 6 px, centered (--on-brand)
* Label: 14 px on 20 px, weight 400 (--text)
* Description: 13 px on 18 px, directly under the label (--text-muted)
* Gap circle to label: 8 px (--space-2)
* Space between options: 8 px with a fine pointer, 0 with a coarse pointer, where rows are 44 px (--space-2)
* Row layout: two or three short options, each as wide as the longest, 24 px apart, stacked below 640 px (--space-6)
* Group label: a field label on a legend
* Focus ring: 2 px, offset 2 px (--focus-ring)

## States

* rest: the flat circle inside its 1 px edge
* focus visible: ring outside the circle (--focus-ring)
* chosen: brand fill with a white dot (--brand-blue, --on-brand)
* disabled: circle and dot at half strength, label in muted ink (--text-muted)
* invalid: error edge, with the message in the error line of the group (--error, --error-ink)

## Keyboard

* Tab: Enters the group at the chosen option, or the first when none is chosen
* Arrow keys: Move to the next or previous option and choose it, wrapping at the ends
* Space: Chooses the focused option when none is chosen
* Shift+Tab: Leaves the group

## Accessibility

* Native radio inputs sharing a name, inside a fieldset with a legend.
* Each option is a label element.
* The group is one Tab stop.
* Screen readers announce the legend, the option, its position and its state.

## Content

* Fragments in sentence case, no full stop.
* Long labels wrap and are not truncated.
* Descriptions are sentences with a full stop, on every option or on none.
* The group label ends without a colon.
* The safe, usual option comes first and starts chosen.

## Tokens

* --surface-control
* --text-muted
* --text
* --brand-blue
* --on-brand
* --error
* --radius-full
* --space-2
* --space-6
* --focus-ring