Skip to content

role searchbox

Search field draft v0.1.0

Lets people type what they are looking for.

A search field collects a search term: a query for a whole site, a filter for a list. It is a Text field with a search glyph at its start, exposed to assistive technology as a search box, and whose clear control the platform provides. It has a visible label, which may be the only word next to it (Search), and an optional description; it has no error state: a search that finds nothing is reported by the results, not by the field.

Decisions

From decisions in packages/components/specs/components/search-field.spec.json, newest first. Every active decision is implemented by the spec, the tokens, the web implementation and the guidelines.

Color

  • The control follows the Text field's colors: a box on the default surface outlined in the accent neutral border color; hover tints it with the surface hover color and keeps the border; disabled takes the shared disabled colors. Value text is primary, the placeholder tertiary, the description secondary, the glyph the tertiary icon color.

    The Figma library maps no color to form controls. The accent neutral border is the lightest neutral border that keeps 3:1 against the surface in both modes (WCAG 1.4.11); the hover tint reuses the surface's own hover step.

    field-colors · 2026-10-03 · v0.1.0

    search-field.control.background.*search-field.control.border-color.*search-field.control.color.*search-field.icon.color.*

    WCAG 1.4.11 Non-text Contrast (AA)

Size

  • Three sizes from the Figma library's space and body scales: small (32 px high, 8 px inline padding, 14 px text), medium (40, 12, 16, the default) and large (48, 16, 20); the border is 0.6 px (stroke-width.sm) and the corners 4 px (corner-radius.xs) at every size; label, description and error message keep 14 px.

    sizes · 2026-10-03 · v0.1.0

    search-field.control.min-height.*search-field.control.padding-inline.*search-field.control.typography.*search-field.control.border-widthsearch-field.control.border-radius

Anatomy

  • A search glyph (the icon font) sits over the start edge of the control at 16, 20 or 24 px by size, 8 px from the edge; the control reserves 28, 36 or 40 px of start padding for it. It is hidden from assistive technology; the role says what the field is for.

    search-glyph · 2026-10-03 · v0.1.0

    search-field.icon.*search-field.control.padding-inline-start.*

    WCAG 1.1.1 Non-text Content (A)WAI-ARIA 1.2: aria-hidden

State