Icon
Icons communicate meaning through simple, recognizable symbols. They reinforce labels, indicate actions, and provide visual cues that reduce cognitive load.
Anatomy
- 1 Icon element — square, inherits color from
currentColorand size from parentline-height
Options
Decorative vs. meaningful
Most icons are decorative — they sit next to a visible text label and are hidden
from assistive technology with aria-hidden="true". When an icon is the only
content (no adjacent label), it must have an accessible name via aria-label.
Color
Icons inherit currentColor by default. Apply semantic color tokens through the
parent element or a utility class to change the icon color. Never hardcode hex
values on icons.
Size
Icon size is controlled by the parent's line-height. A parent with
line-height: 24px produces a 24×24 icon. No explicit width or height is
needed.
Table of options
| Property | Values | Default |
|---|---|---|
--icon-src | icon URL path | — |
| color | Inherited from currentColor | parent text color |
| size | Inherited from parent line-height | 1lh |
aria-hidden | true (decorative) / omitted (meaningful) | true |
aria-label | text (meaningful icons only) | — |
Behaviors
Color inheritance
The icon uses currentColor as its fill. Changing the parent's color property or applying a semantic token class changes the icon color automatically.
Size from line-height
The icon is always square and matches the inherited line-height of its parent. A 24px line-height produces a 24×24 icon. No explicit dimensions are needed.
Inline alignment
Icons use vertical-align: middle to sit on the text baseline. They align naturally next to text in buttons, labels, and links without extra positioning.
CSS mask rendering
The SVG is applied as a CSS mask-image, not as an inline SVG or <img>. This allows color control via currentColor and avoids DOM bloat from inline SVG markup.
Usage guidelines
Use icons to reinforce, not replace, labels
Do
Pair icons with visible text labels so the meaning is clear to all users.
Don't
Don't use a standalone icon without an accessible name — screen readers will skip it entirely.
Use semantic color tokens for icon color
Do
Use semantic tokens like --color-text-brand or --color-text-success to color icons.
Don't
Don't hardcode hex colors on icons — they won't adapt across brands and modes.
Mark decorative icons correctly
aria-hidden="true"
Do
Add aria-hidden="true" to decorative icons that sit next to a text label.
aria-label="Search"
Don't
Don't add an accessible name to a decorative icon — it creates duplicate announcements for screen reader users.
Content standards
Accessible names for meaningful icons
When an icon is the only interactive content (e.g. an icon-only button), provide
a concise aria-label that describes the action, not the icon shape.
aria-label="Close dialog"
Do
Describe the action the icon triggers.
aria-label="X icon"
Don't
Don't describe the visual shape — users need to know what it does, not what it looks like.
Icon file naming
Icon SVG files use kebab-case names that describe the concept, not the visual
form: checkmark.svg, arrow-right.svg, luggage-trolley.svg.
Keyboard interactions
Icons are not interactive on their own. Keyboard interactions are handled by the parent component (button, link, or other control) that contains the icon.
| Key | Interaction |
|---|---|
| Tab | Icons are not focusable. Focus moves to the parent interactive element. |
Accessibility
- Decorative icons must have
aria-hidden="true"to be skipped by screen readers. - Meaningful icons (icon-only buttons, status indicators) must have an
aria-labelon the icon or the parent element. - Icons inherit
currentColor— they automatically meet the same contrast ratio as the surrounding text. - Never use an icon as the sole means of conveying critical information (e.g. error state). Always pair with text or a semantic state.
- The CSS mask technique preserves the icon in Windows High Contrast Mode
because it uses
background-color: currentColor.
Theming
Icons adapt automatically across brands and color modes because they inherit
currentColor. Use the hero preview switches above to see it in action.
For the full theming architecture — brands, modes, and how tokens cascade — see Foundations: Theming.
Design checklist
currentColor and adapt across light and dark modes.