Skip to content

role button

Icon button draft v0.5.1

Triggers an action with an icon alone; its label is given to assistive technology.

An icon button performs an action, like a button, but shows only an icon: it saves room in toolbars, table rows and headers where the action is familiar enough to be recognized from its symbol. It has no visible text, so it always carries a label that assistive technology announces as its name. Like every button, it never navigates.

Decisions

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

Variant

  • Without a size, an icon button is medium (36 px), like the button (Button decision default-size-medium). The icon=only variant of the Figma prototype's Button set defaults to xsmall.

    Every component with sizes in the system defaults to medium (text field, select, search field, number field, textarea, dropdown, icon button), so controls placed together without a size get the same size step; the prototype's xsmall default is also the top-left variant of its Button set and may come from the set's layout rather than from a choice.

    default-size-medium · 2026-10-15 · v0.5.0

    icon-button.container.min-height.mediumicon-button.container.min-width.medium

  • The icon button always renders the same as the button of the same emphasis, intent, size and state, as the icon=only variant of the Button in the Figma prototype does: its square side is the button's height, its glyph is the button's icon (size, font and optical size), and its fills, borders and glyph colors are the button's fills, borders and label colors, through the icon role of the same name (global.icon.* aliases global.text.*). Corners, border width, focus ring and transitions are the button's too. A button decision on any of these applies to the icon button in the same change: pnpm validate fails when an icon button token differs from the button token at the same place.

    same-rendering-as-button · 2026-10-15 · v0.4.0

    icon-button.container.*icon-button.icon.*button.container.*button.label.color.*button.icon.*

Size

  • The square side is the button's height, space.24 / 28 / 36 / 44 from extra small to large, with the same 24 px floor at extra small so that every size meets WCAG 2.2 2.5.8 by its own size; the Figma prototype's icon=only square is 20 px at extra small. The glyph is the button's icon, size.2 / 3 / 4 / 4 (16 / 20 / 24 / 24 px), as in Figma, in Material Symbols Outlined (font.icon.*: fill off, weight 300, grade 0, optical size 20 at every size). The glyph sits centered in the square: Figma's padding (2 / 4 / 6 / 10 px) is the side minus the glyph, halved, and needs no token. Corners corner-radius.2xs / 2xs / xs / xs, border stroke-width.sm, transitions duration.fast and easing.standard, as before.

    sizes-from-button · 2026-10-15 · v0.4.0 · replaces figma-library-scales

    icon-button.container.min-height.*icon-button.container.min-width.*icon-button.icon.size.*icon-button.icon.*icon-button.container.border-radius.*space.*size.*font.icon.*

    WCAG 2.5.8 Target Size (Minimum) (AA)

Color

  • The icon button takes the button's color decisions of 0.19.0 and 0.20.0. Subtle and ghost neutral glyphs are global.icon.on-base.neutral.primary in every state and both modes (button decision neutral-label-primary); a ghost brand glyph at rest is global.icon.on-base.brand.default (ghost-brand-label-on-base); a ghost icon button takes the subtle border one step behind on hover and press, global.border.subtle.<family>.default / hover (ghost-border-one-step-behind), and the shared disabled fill and border when disabled (ghost-disabled-shared). Error glyphs keep the Figma library's error colors (error-label-figma-library).

    colors-from-button · 2026-10-15 · v0.4.0

    icon-button.icon.color.subtle.neutral.*icon-button.icon.color.ghost.*icon-button.container.border-color.ghost.*icon-button.container.background.ghost.disabledglobal.icon.on-base.neutral.primaryglobal.icon.on-base.brand.defaultglobal.border.subtle.*global.bg.state.disabled.defaultglobal.border.state.disabled.default

  • The icon button exists in every color mode of the system, light and dark, and takes the colors of the mode of its context. Every color aliases the Figma library's mapped roles as they are, in both modes: fills global.bg.<emphasis>.<family>.<state>, borders global.border.<emphasis>.<family>.<state>, glyph global.icon.on-<emphasis>.<family>, disabled global.*.state.disabled.default; a ghost icon button reads the subtle text and icon colors. Where the Figma library's error colors fall under WCAG 2.2 AA, the gap is kept and tracked, not corrected in the icon button.

    The Figma library as it is, errors and limitations included, is the starting point the system evolves from.

    figma-library-colors · 2026-10-02 · v0.3.0 · replaces color-modes

    icon-button.container.background.*icon-button.container.border-color.*icon-button.icon.color.*global.bg.*global.border.*global.icon.*

    WCAG 1.4.3 Contrast (Minimum) (AA)

Accessibility

Superseded (3)

  • Sizes, spacing, radii, borders, type, icons and motion come straight from the Figma library's scales and the design system's additions, with the same values as before and no semantic layer in between: icons are Material Symbols Outlined glyphs (font.icon.*: fill off, weight 300, grade 0, optical size 20) at size.2 / 2 / 3 / 4, extra small to large; minimum width and height space.24 / 32 / 40 / 48; corners corner-radius.2xs / 2xs / xs / xs; border stroke-width.sm; transitions duration.fast and easing.standard.

    figma-library-scales · 2026-10-02 · v0.3.0 · replaced by sizes-from-button

  • The icon button exists in every color mode of the system, light and dark, and takes the colors of the mode of its context. Its color decisions (emphasis, intent, state) are the same in every mode; only the semantic colors they alias change. Dark colors follow the prototype's dark mapping, with the error fill and border kept one step darker than the prototype, as in light mode.

    color-modes · 2026-10-01 · v0.2.0 · replaced by figma-library-colors

  • Icons are glyphs of Material Symbols, latest version, for every component: Outlined family with fill off, weight 300, grade 0 and optical size 20 px.

    icons-material-symbols · 2026-10-01 · v0.1.0 · replaced by figma-library-scales