Desktop UI Icons

Icon Design & Selection (Desktop)

The hard rule

Never use Lucide icons. Not as a placeholder, not "just for now," not for one-off icons. Lucide (and by extension the identical Feather-icon-derived look) is the single most recognizable visual tell of an AI-assisted or shadcn-template app — trained eyes clock it instantly, and it undercuts everything else this skill family does. If Lucide is already in the codebase, treat every instance of it as a bug to fix, not a default to build on top of.

This rule is absolute regardless of how the request is framed — "just use lucide for now," "it's fine for an MVP," or "everyone uses it" are not exceptions.

What to use instead

In order of preference:

1. A small custom-drawn icon set matching the app's own brand geometry (e.g. if the brand motif is organic/rounded, draw icons with rounded joins and soft terminals; if it's geometric, draw them sharp). This is the strongest option for a product that wants to look intentional rather than assembled, and it's worth the time investment for a flagship app.
2. A single well-chosen library, used consistently and modified to fit — Phosphor Icons, Tabler Icons, Iconoir, or Remix Icon are all solid, less-overexposed alternatives to Lucide. Pick exactly one. Set a consistent stroke width across the whole app (don't mix a 1.5px-stroke icon next to a 2px-stroke icon). Adjust the corner radius of the library's icons if needed to match the app's own radius scale from foundations.
3. Never mix icon families. One icon from library A next to one from library B is worse than using an imperfect single library consistently — mismatched stroke weight, corner style, and optical size is immediately visible even to someone who couldn't name why it looks wrong.

Whichever route is chosen, lock it in a single place (a component/import wrapper, a theme resource, a sprite sheet) so nobody can casually reach for a different set six months later.

Selection logic — does this even need an icon?

Not every action needs an icon. Icons should:

• Represent something with a stable, widely-understood visual metaphor (trash = delete, gear = settings, magnifying glass = search). If the metaphor takes explanation, it's the wrong icon — or the action needs a text label instead.
• Be paired with a text label whenever the meaning isn't universal, or whenever the control is a primary/frequent action (icon-only is for toolbars and dense UI, not for a settings page's main actions).
• Never be invented purely to "fill visual space" next to a label — an icon that adds no information is decoration, and decoration without meaning is an anti-slop violation from desktop-ui-foundations.

Consistency rules

• One optical size per context. Toolbar icons should all render at the same apparent size even if their underlying viewboxes differ slightly — normalize this, don't eyeball it.
• One stroke weight app-wide, or one fill style if using filled icons — never mix stroke and filled icons in the same view unless the fill is deliberately reserved for an "active/selected" state (see the color-system skill for state-driven icon treatment).
• Grid-align the artwork. Icons drawn or exported off a consistent pixel grid (typically 24×24 for a 16–20px rendered icon) will look crisper and align better with text baselines than ones scaled arbitrarily.
• Avoid decorative gradient fills on icons. A gradient-filled icon is a fast way to read as generic-AI polish; solid color communicates state (active/inactive/error) more clearly anyway.

Sizing tokens

Match to the button sizing scale in desktop-ui-buttons-controls:

• 12–14px — inline with caption/label text
• 16px — the default for most UI icons (menu items, list rows, inline buttons)
• 20px — toolbar and header icons
• 24px+ — reserved for empty-state or feature-highlight icons, used sparingly

App icon / tray icon / installer icon

The app's own icon (dock/taskbar/tray) is not a UI icon — it's a small piece of brand identity and deserves its own attention, not a reused UI glyph blown up large. It should:

• Read clearly at the smallest size it'll actually appear (16×16 tray icon), not just at the large marketing size.
• Follow each platform's shape conventions (macOS's rounded-square-with-inset-artwork convention vs. Windows' more literal square) rather than shipping one flat asset everywhere.
• Tie visually to the in-app brand motif rather than being an unrelated generic mark.

See desktop-installer-design for how this same icon shows up through the install flow.

Accessibility & internationalization

• Icon-only controls (toolbar buttons, close/collapse glyphs) need an accessible name exposed to the platform's accessibility API, not just a visual tooltip — tooltips are invisible to screen readers and to anyone who never hovers. See desktop-ui-accessibility-i18n.
• Directional icons (back/forward, next/previous chevrons) should mirror in right-to-left layouts. Icons with no inherent direction (checkmark, play, star, trash) should not be flipped.

Review format