Icon

Usage

Overview

Icon renders one generated glyph as an inline SVG. Import the glyph from @prepared911/ui/icons/<kebab-name> (or by name from @prepared911/ui/icons) and pass it to glyph. Size is an IconSize token; paint is currentColor, steered by the optional foreground prop or by the surrounding text color when foreground is Foreground.Inherit (the default). Use icons for inline clarification next to labels, list leads, and status rows; everywhere dispatch surfaces need quick visual scanning without becoming clickable targets on their own.

When to use

Inline with Text where the icon reinforces meaning already present in words (status + label, category + title).
List and table cells where density allows a small lead icon with text.
Map and timeline adornments where touch targets are handled by a parent hit area.

When not to use

Sole control for an action; use Icon button with an accessible name on the control and focusability.
Custom SVG outside the approved glyph set; work with design to add or map a glyph through the icon pipeline.
Replacing entire sentences; icons supplement text, especially for critical operations.

Color and semantics

Set foreground to a member of Text's Foreground enum when the icon should paint a token directly (Storybook ForegroundMatrix). Members with an icon rung (Default, Subtle, Muted, Disabled, OnAccent, Transient*) bind --color-icon-*; Link, Accent, AccentStrong, and the status members bind the same foreground tokens as Text. With Foreground.Inherit, set color on a wrapping Text run instead (Storybook InContext under Composition).

Outlined and filled pairs

A state that swaps an outline for a fill uses two glyphs, not a style prop: hand-alt-outlined while off and hand-alt-filled while on (ControlIsland's raise hand). Pass each to glyph from its own subpath. For success status marks, pair the stroked check-circle glyphs with circle-check-filled (circleCheckFilled from @prepared911/ui/icons/circle-check-filled): a solid disc with the check knocked out, authored in the design file as circle-check-filled until the hosted manifest publishes it. Use foreground={Foreground.Success} (or success-coloured text with Foreground.Inherit).

Anatomy

One root svg sized by IconSize classes (--icon-xs through --icon-lg). Lucide-sourced glyphs stroke currentColor; filled fallbacks fill currentColor. The glyph aligns with adjacent text baselines as an inline icon.

Content guidelines

Omit label for decorative icons beside visible text; pass label only when the icon is the sole carrier of meaning at that point in the tree.
Match size to the adjacent text step: dense tables use IconSize.Small or ExtraSmall; page headers may use Medium or Large.

Behavior and states

rotation applies quarter-turn steps via IconRotation (Storybook Rotation).
spin turns the glyph continuously for loading affordances owned by a control; it stops under reduced motion (Storybook Spin).
Non-interactive icons do not receive focus; wrap with Interactable or Button when clicking is required.

Best practices

Do pair icons with visible text in high-stakes flows (911, QA decisions).
Do reuse glyphs consistently: same concept, same import across modules.
Don't rely on color alone; combine icon shape, text, and position.
Don't crowd multiple icons in a single table cell without hierarchy.

Accessibility

See the dedicated accessibility page. Storybook LabelledVsDecorative shows decorative versus named icons.

Icon button for actionable icon-only controls.
Icon toggle for on/off toolbars.
Engineering ui-components for import patterns and the glyph finder in Storybook.

Grid / Accessibility

Icon / API and Development

On this page

Outlined and filled pairs

Icon

Usage

Overview

When to use

Inline with Text where the icon reinforces meaning already present in words (status + label, category + title).
List and table cells where density allows a small lead icon with text.
Map and timeline adornments where touch targets are handled by a parent hit area.

When not to use

Sole control for an action; use Icon button with an accessible name on the control and focusability.
Custom SVG outside the approved glyph set; work with design to add or map a glyph through the icon pipeline.
Replacing entire sentences; icons supplement text, especially for critical operations.

Color and semantics

Outlined and filled pairs

Anatomy

Content guidelines

Omit label for decorative icons beside visible text; pass label only when the icon is the sole carrier of meaning at that point in the tree.
Match size to the adjacent text step: dense tables use IconSize.Small or ExtraSmall; page headers may use Medium or Large.

Behavior and states

rotation applies quarter-turn steps via IconRotation (Storybook Rotation).
spin turns the glyph continuously for loading affordances owned by a control; it stops under reduced motion (Storybook Spin).
Non-interactive icons do not receive focus; wrap with Interactable or Button when clicking is required.

Best practices

Do pair icons with visible text in high-stakes flows (911, QA decisions).
Do reuse glyphs consistently: same concept, same import across modules.
Don't rely on color alone; combine icon shape, text, and position.
Don't crowd multiple icons in a single table cell without hierarchy.

Accessibility

See the dedicated accessibility page. Storybook LabelledVsDecorative shows decorative versus named icons.

Icon button for actionable icon-only controls.
Icon toggle for on/off toolbars.
Engineering ui-components for import patterns and the glyph finder in Storybook.

Grid / Accessibility

Icon / API and Development

On this page

Outlined and filled pairs