When to use
- Toolbars
- Status cues
- Navigation affordances
- Compact repeated actions
Icon
Icons support recognition, affordance, and compact scanning in product UI. Use them to clarify a control or state, not to decorate empty space.
Guidance for adoption
Start here before choosing examples or props. These notes explain where Icon helps, where another pattern is better, and what should stay true in product work.
When not to use
- Replacing essential text without labels
- Decorative filler
- Ambiguous domain concepts
Accessibility expectations
- Hide decorative icons from assistive technology.
- Provide accessible names for icon-only controls.
- Keep icon hit targets large enough for touch.
Content guidance
- Pair unfamiliar, high-risk, or domain-specific icons with visible text so people do not have to guess.
- For icon-only controls, write the accessible name as the action, such as "Open settings".
- Use the same icon for the same concept across pages so recognition builds over time.
- Do not rely on color alone for status; pair the icon with text, a badge, or a clear label.
Implementation notes
- Use lucide-react where a known symbol exists; avoid custom SVGs unless the system lacks a suitable icon.
- Set aria-hidden="true" on decorative icons that sit next to visible text.
- Give icon-only buttons an aria-label on the button, not on the icon itself.
- Use the documented size conventions and keep stroke width consistent with nearby UI.
Import
import { Download } from 'lucide-react';Use lucide-react icons directly. Size with the size prop and mark decorative icons with aria-hidden.
Usage patterns
Icons work best when their role is explicit. Use the same symbol for the same purpose across pages, flows, documentation, and generated examples.
Use an icon to speed recognition while text still carries the meaning.
Reserve for familiar, repeated controls and provide an accessible name.
Approved
Pair the symbol with text so meaning does not depend on color alone.
Use compact direction icons to reinforce movement and hierarchy.
Use recognizable icons for dense, repeated tools with stable labels.
Keep supporting icons quiet and close to the text they explain.
Anatomy
A useful icon connects the symbol, text, semantic state, and interaction target. The visual mark is only one part of the component contract.
- Recognizable symbol
- Semantic color
- Accessible name when needed
- Visible label or nearby text
- Touch-safe target
- Consistent size and stroke
Usage rules
Use icons to support text
Icons should make familiar actions easier to scan. Text should still name the action, status, or destination.
Do not make users decode icons
If the symbol is unfamiliar, domain-specific, or high risk, use visible text and supporting copy instead.
Use the system icon family
Use Lucide icons with consistent sizing, stroke, and color inheritance across product surfaces.
Do not add decorative filler
Avoid icons that exist only to fill space. Every meaningful icon should clarify a control, state, or piece of content.
Known limitations
What Icon does not do yet, and what consumers need to compose themselves.
- No wrapper component. The system delegates to lucide-react directly, so there is no central place to enforce size tokens, stroke width, or aria-hidden/aria-label defaults; each consumer follows the documented conventions by hand.
- No curated subset. Any of the lucide icons can be imported, and the system does not restrict or alias the approved set, so drift is enforced only by code review.
Agent guidance
Agents should choose icons from the approved library, attach accessible names to icon-only controls, and avoid inventing decorative SVGs for product UI.
Generation rules
- Use lucide icons where a known symbol exists.
- Pair unfamiliar icons with visible text or a tooltip.
- Do not create custom SVG icons unless the system lacks an appropriate symbol.
- Set aria-hidden="true" on decorative icons that sit next to a visible text label; otherwise screen readers announce the icon name and the label twice.
- For icon-only controls, give the wrapping button an aria-label that describes the action ("Close panel"), not the symbol ("X icon"). An unlabeled icon button has no accessible name.
- Set size with the existing 16, 20, or 24 px conventions via the size prop on lucide; do not pass arbitrary pixel widths. Stroke width stays at the default 1.5 unless the system documents otherwise.
- Do not rely on icon color alone to communicate status. Pair the icon with a visible word or badge; color-only states match the color-only-state anti-pattern.
Baseline example
<button type="button" aria-label="Download report">
<Download size={20} aria-hidden="true" />
</button>
<button type="button">
<Download size={20} aria-hidden="true" />
Download report
</button>If an icon does not have a clear, common meaning, agents should use text first and skip the icon unless a documented product pattern requires it.
Decision standard
Icons support recognition; text carries meaning. Use an icon when it improves scanning, strengthens an affordance, or identifies a status without making the user guess.