Controls

Button

A button runs one action named as a verb: Get feedback, Save draft, Rerun feedback. Anatomy: a 500 weight label, an optional leading icon slot, an inset of 12, 16, or 20px on the 32, 40, or 44px ladder, and a 4px radius. Never a pill, never a shadow, never yellow.

States. Rest, hover, press, focus with the shared ring, disabled, and loading. Disabled flattens any variant to an ink-200 fill with an ink-400 label. Loading keeps the label and its width, swaps a 16px linear spinner into the icon slot, and ignores clicks until it resolves. Sizes follow the sizing ladder: 32, 40, and 44px with 12, 16, and 20px insets and a 44px effective target.

Accessibility. A button is a button element. Keep the label in the DOM while loading and set aria-busy, so the accessible name never disappears mid action. Danger belongs only in destructive rows and confirm dialogs.

Icon button

An icon button is a square button for one compact utility act whose glyph is unambiguous: dismiss, copy, rerun. It takes the secondary or quiet appearance, never primary, and its only accessible name is a required aria-label.

States. The same line as the button: rest, hover, press, focus, disabled.

Accessibility. The aria-label names the action, not the glyph: Rerun feedback, not circular arrow. At 32px the effective target still reaches 44px through surrounding space.

Text input

A text input takes a single line. Anatomy: a 40px box (44 on touch) with a border-strong boundary, 4px radius, body-md value text, and an ink-400 placeholder that shows an example, never the instruction.

States. Rest, focus, error, and disabled, as staged above. Focus adds the ring and nothing else: darkening the boundary as well would double stroke the box.

Accessibility. Every input pairs with a visible label from the field pattern below; the placeholder vanishes at the first character, so it never carries requirements.

Textarea

A textarea is the same contract with room to write. Long writing surfaces get a 20 by 24px inset and grow with their content; the surrounding scroll owner absorbs the length, never the page.

States. The text input line applies; only the inset and the free height differ.

Accessibility. Keep growth visual: once the scroll owner's limit is reached the textarea scrolls internally rather than pushing the actions below it out of reach.

Select

A select is a custom control in input clothing: a 40px border-strong trigger with a 16px ink-600 chevron, opening a listbox built on the menu overlay surface. The native element remains only where the platform demands it; email renders no controls at all.

States. Rest, focus, error, and disabled follow the text input on the trigger; the chevron never changes. Open adds the listbox on the overlay recipe while the trigger keeps focus and its ring.

Accessibility. The trigger takes role="combobox" with aria-expanded; the list is a listbox of option rows carrying aria-selected. Focus stays on the trigger while the list is open and returns to it on close; the keyboard line above is part of the contract, not an enhancement.

Field

Field wraps any control so it explains itself: a 13/500 label first, the control, then helper or error in body-sm. Required is the written word beside the label; an asterisk alone explains nothing.

States. Helper and error share one slot below the control; error replaces helper instead of stacking under it.

Accessibility. Point the control at its helper or error with aria-describedby and set aria-invalid on error, so the message reads with the label instead of getting lost below.

Checkbox and radio

A checkbox answers one independent yes or no; radios choose one of a visible few. Anatomy: a 20px box at 4px radius or a full round circle, border-strong when empty, ink-900 with a paper glyph when chosen, and a label completing the 44px row.

States. Empty, checked, focus, and disabled, which mutes the mark to ink-200 with an ink-400 label. Checking animates: the check draws in and the radio dot fades and settles over duration.sm; see selection motion below.

Accessibility. Keep the native input inside the label element: the row toggles from anywhere and the platform announces the state without extra wiring.

Switch

A switch flips a setting that applies the moment it moves; nothing waits for a save. Anatomy: a 40 by 24 full round track with a 20px paper thumb, ink-200 when off, ink-900 when on. The label states what turning it on does.

States. Off, on, focus, and disabled, muted like the checkbox. The thumb slides its 16px over duration.sm on ease.out while the track crossfades between ink-200 and ink-900.

Accessibility. A native checkbox with role="switch" works; position and fill carry the state together, so on and off never differ by color alone.

Selection motion

Checking is drawn, not swapped: the check strokes in, the radio dot settles, the switch thumb slides. All three run live below; click a row or toggle it with the keyboard to play the change.

Motion. The three marks share one family from the motion page recipes: color changes ride the hover timing, the draw and settle run duration.sm with ease.out, and nothing bounces or overshoots. Reduced motion collapses all three to instant flips through the global rule, so every state stays legible in the resting frame.

Anatomy: a bg-subtle track with a 2px inner inset, 32px items, the active item lifted to a white fill with a hairline and ink-900 text, inactive items in ink-600. Two segments are the norm; three is the ceiling.

States. Active, inactive, inactive hover, and focus. On change the white active pill slides to the chosen segment, transform only, over duration.sm with ease.out; reduced motion snaps it into place.

Accessibility. Expose it as tabs: a tablist with aria-selected and arrow key movement, because segments switch views in place.

1. One primary action per view. One Midnight fill; supporting acts are secondary, quiet, or links.
2. Height follows density, never importance. The 32/40/44 ladder is regional; primary does not mean taller.
3. Labels are visible. A placeholder is an example, never the label or the instruction.
4. One focus signal. The 2px brand-700 ring at 2px offset serves every control, and nothing else changes at focus.
5. Destructive is a variant, not a color accident. Danger buttons live in destructive rows and confirm dialogs and stay white until hover.
6. Loading never collapses width. The label holds its box while a 16px spinner takes the icon slot.
7. Every control reaches 44px effectively. Visuals may be 20 or 32px; targets and rows may not.
8. Segments and switches act instantly. A segmented control never submits; a switch never waits for a save.