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).

Approved custom glyphs

Components and product code import Lucide-sourced glyphs, plus a short approved list. Authored glyphs (glyphs/custom-glyphs.json, refreshed with pnpm icons:generate) include ai-sparkle (the AI mark) and the raise hand pair (hand-alt-outlined, hand-alt-filled).

Figma-owned fallbacks that remotes and apps may import when Lucide has no equivalent are listed in APPROVED_FIGMA_CUSTOM_GLYPHS in packages/ui/tests/icons-lucide-only.test.ts: bwcicon (the body-worn camera mark on the map's device badge), call-end (end-call handset), and dial-pad (the dial-pad toggle; do not use grip-horizontal, which is the window drag grip). Their geometry stays in the manifest snapshot (pnpm icons:sync / icons:export), not in custom-glyphs.json.

All approved glyphs render through Icon. A glyph outside the Lucide-sourced or approved sets fails the Lucide-only test, which scans remotes and apps.

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

Approved custom glyphs

Icon

Usage

Overview

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

Outlined and filled pairs

Approved custom glyphs

All approved glyphs render through Icon. A glyph outside the Lucide-sourced or approved sets fails the Lucide-only test, which scans remotes and apps.

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

Approved custom glyphs