Gallery

Form primitives in isolation. States via :hover, :focus, :disabled, and aria-invalid.

When to use each

Three decisions that compound in every form: how to lay out labels, which binary control to use, and how to give feedback.

Drift to avoid

Six named anti-patterns. The first three came directly from either the audit or shipping bugs we hit building this kitchen sink.

• Don't use flex for form row alignment

  Principle 2
  Flex with flex: 1 on all non-label children stretches fixed-width controls — switches and radios end up spanning the full row, and the thumb travel breaks. Use CSS Grid grid-template-columns: 140px 1fr instead; inputs fill the 1fr column via their own width: 100%, switches stay at their native size. We hit this exact bug when wiring the composition below.
• Don't use min-width on labels

  Principle 2
  min-width lets longer labels push controls rightward, creating jagged column alignment across rows. Use fixed width (or the grid equivalent) so the control column stays aligned regardless of label content.
• Don't use bare <input type="checkbox"> for single toggles

  Principle 4
  The audit found this in 25+ files. Single boolean toggle = .switch. Multi-select from a list = .checkbox. The two controls have different ARIA semantics and different user expectations; the wrong one feels off even when the user can't articulate why.
• Don't cram label-to-control gaps below --space-3

  Principle 5
  --space-1 (4px) and --space-2 (8px) read as cramped — fields blur together and the form feels frantic. --space-3 (12px) minimum between label and control. --space-4 (16px) between adjacent rows.
• Don't pair invalid state without an error message

  UX
  A red border with no explanation is hostile — the user knows something's wrong but not what. Always pair aria-invalid="true" with a .form-error message below the input, naming the rule that failed.
• Don't show error text above the input

  UX
  Errors belong below the input, where the eye lands after typing. Above-input errors get missed; below-input errors get read.

Composition — device configuration

A real settings form using everything above. Labels beside the input (grid), controls aligned across rows, switch at native width, slider with paired value, footer with one ghost + one primary.

• grid not flex 140px label column + 1fr control column — fixed-width controls (switch, radio) sit at their natural size, not stretched
• native widths Switch is 28px; slider has a paired value; textarea grows vertically — each control behaves like itself
• one primary Save = primary, Cancel = ghost. Footer reads left-to-right: exit, then commit
• space-3 between rows Generous gap; the form doesn't feel cramped at any width

Rich dropdown — when native select isn't enough

Native <select> can't show a color swatch next to an option or a description line below it. When you need either, compose a .form-dropdown-trigger (looks identical to .form-select) with a .popover hosting .form-dropdown-option rows. DH ships the CSS; you wire the open/close, keyboard nav, and ARIA.

• trigger = button A styled <button>, not a <select>. ARIA attributes (aria-haspopup, aria-expanded) come from the adopter's JS controller
• panel = .popover Reuse the existing floating-panel primitive — no new "dropdown panel" class
• option composition .form-dropdown-option takes an optional .option-swatch + required .option-label + optional .option-description. Drop the swatch when you don't need it; the grid collapses
• no JS shipped DH stays framework-agnostic — focus management, keyboard nav, click-outside, and placement are the adopter's call. Don't reach for a JS library before evaluating whether native <select> would suffice