Ux Iconography

Iconography Skill

How this skill behaves (read first)

This is a generative foundation skill. Icons are where an AI assistant ships ambiguity: Claude adds icon-only buttons with no labels, reaches for novel or decorative glyphs instead of the metaphor users already know, mixes styles (some outlined, some filled, different stroke weights), and uses different icons for the same action across a screen. An icon that makes the user stop and decode it has failed — its whole job is faster recognition.

So this skill gates:

1. Establish context — platform/library, whether icons earn their place here, and the design-system maturity (these set the style, the label policy, and the source).
2. Apply the always-true core — universal metaphors, one consistent style, labels where meaning isn't obvious, legibility at size, and accessible labels.
3. Surface the context-dependent decisions (icon style, system library vs custom, labels, state variants, rendering mode, containers) with trade-offs; let the user choose.

Then it hands off to ux-accessibility-audit (labels, contrast, touch targets), ux-aesthetics-audit (style consistency, overdesign), and ux-microcopy-audit (the icon labels themselves), plus ux-mobile-responsiveness-audit when touch targets matter.

Scope & composition (per docs/orchestration-policy.md §9): this skill owns icon choice, style, and usage. Peers that own a sub-part (defer — each handles its sub-part if reached): ux-buttons owns button label wording and button anatomy. Inherit under a design system (only build from scratch): ux-typography owns the type scale and ux-layout-spacing-grids owns the spacing/grid the icons sit on — take both from the system's tokens when one exists. The full evaluative review defers to the audits above.

---

Step 0 — Establish context before choosing icons

Ask if not known; state the assumption if proceeding without an answer:

• Platform & library — iOS/macOS lean on SF Symbols; Android on Material symbols; web may use an open set or a custom library. The platform sets default metaphors, rendering, and weights.
• Do icons earn their place here? Icons help with frequent or quick-access actions and scanning. If an icon doesn't simplify the journey, omit it — clutter dilutes the icons that matter. One icon, one action.
• Design-system maturity — a one-off screen needs the right glyphs and labels; a system needs naming, tagging, component structure, and tokens so the set stays consistent and findable.

---

The always-apply core (true for almost every icon)

Make it understood

• Use universal, recognized metaphors — clarity over novelty. Magnifying glass for search, arrows for navigation, gear for settings. A clever substitute (binoculars for search) just makes users stop and think.
• ❌ A bespoke glyph for "search." ✅ The magnifying glass everyone already reads as search.
• Label when meaning isn't obvious. Unique/ambiguous icons need a short text label (1–3 words, action words like "Search," "Share"). Universal icons can sometimes stand alone — but pairing icon + label is the safe default in dense or first-use contexts.
• **Always provide an accessible label for icon-only controls.** If there's no visible text, the control needs an accessible name so screen readers can announce its purpose. (If a visible label exists, that serves as the accessible text — don't double up.)
• One action, one icon — and don't conflict. Use the same icon for the same action everywhere; never two icons for one concept. Be aware metaphors carry different meanings across products (heart vs. star vs. thumbs-up; heart = "like" vs. "love" vs. "save") and keep your usage unambiguous.

Make it legible and consistent

• Keep icons simple. Reduce to the essential shape; fine detail blurs or disappears at small sizes. Add detail only where the display size genuinely supports it.
• One consistent style across the set. Match stroke weight, corner radius, geometry, and color treatment. Mixing outlined and filled (or sharp and rounded) at random breaks the visual language. Pick a single primary style.
• Balance optically, not just mathematically. Equal frame size ≠ equal visual weight; a dense glyph looks heavier than a sparse one at the same dimensions. Adjust within the frame (and use consistent containers/padding) so icons feel equal.
• Design per size; don't mechanically scale. Stroke scales with the frame (e.g. 16px→~1px, 24px→~1.5px); small sizes need simpler geometry. Use SVG so icons stay crisp across densities.

Make it usable

• Adequate touch targets. The tappable area should exceed the glyph — at least 44×44pt (iOS) / 48×48dp (Android) — with padding so neighboring icons aren't mis-tapped.
• Consistent, purposeful color. A limited palette: one standout color for active/important icons, a muted/neutral for the rest; semantic colors where they carry meaning (red = destructive, etc.). Don't let colored icons distract from content.

---

The context-dependent decisions (surface, don't auto-apply)

Present each with its trade-off and a recommendation tied to Step 0; let the user choose. Mixing styles, or labeling everything / nothing by reflex, is the failure mode.

| Decision | Apply when | Avoid / adapt when | Default recommendation | |---|---|---|---| | Icon style | Outlined for clean, text-heavy UIs; filled for stronger contrast in compact spaces; colored/duotone for playful brands | Mixing styles freely; colored icons that distract or fail at small/accessibility sizes | Pick one primary style (outlined or filled) and apply it across the set | | System library vs custom | SF Symbols/Material for platform-native consistency, auto weight/scale/alignment; custom only for unique concepts | Reinventing universal glyphs; custom icons that don't match the system's stroke/grid | Use the platform library first; add custom icons that match its characteristics | | Label or icon-only | Label unique/ambiguous icons and first-use contexts; icon-only acceptable for truly universal glyphs with an accessible name | Icon-only for unique actions (users guess); over-labeling universal toolbar icons in tight space | Pair icon + label when in doubt; always keep an accessible name | | Filled vs outlined for state | Use the variant to signal state — outlined = default, filled = selected/active (favorite, bookmark, visibility) | Switching variants for decoration rather than meaning | Reserve the filled/outlined switch for state; keep structure identical across variants | | Rendering mode (Apple) | Monochrome for flexibility; hierarchical for depth; palette/multicolor for semantic meaning | Multicolor where it muddies an interface control | Monochrome for interface elements; richer modes only for semantic/feature icons | | Container & grid | Containers/keylines for uniform alignment, touch-target size, and optical balance across a set | Letting every icon fill its frame edge-to-edge (uneven weight) | Use consistent frames + trim/padding; align to an icon grid | | Library structure (systems) | Naming (category/object/modifier), tags, flattened single-layer components, color tokens | Ad-hoc names and inconsistent layer structure (breaks swaps/overrides, spawns duplicates) | Group by purpose, name + tag consistently, keep identical component structure |

---

Validate the result (orchestration)

> Hand-offs name each lens by its installable skill name. Invoke one only if that skill is installed; if it isn't, this skill's own core already carries these rules — proceed without it rather than blocking.

After choosing or designing icons, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by docs/orchestration-policy.md, or route the whole thing through ux-design-review. Here, microcopy is Tier A (auto-run); accessibility, aesthetics, and mobile-responsiveness are Tier B (offered) — under an existing design system aesthetics is suppressed and accessibility narrows to usage; mobile-responsiveness applies only on mobile. If the user invoked this skill for one specific thing, respect that scope.

• ux-accessibility-audit (Tier B — offer; narrow under a design system) — do icon-only controls have accessible names, do icons meet contrast against their background, are touch targets large enough, is meaning ever carried by color/icon alone?
• ux-aesthetics-audit (Tier B — offer; suppress under a design system) — is the set one consistent style (stroke, geometry, color), optically balanced, and free of decorative overload?
• ux-microcopy-audit (Tier A) — are the icon labels short, clear, action-oriented, and consistent with the product's voice?
• ux-mobile-responsiveness-audit (Tier B — offer; applies only on mobile) (when targeting touch) — do touch targets and spacing hold up on small screens?

This skill defers button label copy and button anatomy to ux-buttons, and the spacing/grid icons sit within to ux-layout-spacing-grids. If the audits surface a conflict, resolve toward the purpose: an icon exists to make an action faster to recognize — if it's ambiguous, inconsistent, or unreadable, add a label, unify the style, or drop it.

---

Common do/don't patterns

| ❌ Don't | ✅ Do | |---|---| | Ship icon-only buttons for non-obvious actions | Pair with a label; always give an accessible name | | Invent a clever/novel metaphor | Use the universal glyph users already know | | Mix outlined + filled + different stroke weights | One consistent style across the whole set | | Use different icons for the same action | One action, one icon, everywhere | | Pack in fine detail | Keep it simple so it reads at small sizes | | Trust equal frame size for equal weight | Balance optically with containers/padding | | Mechanically scale one icon to all sizes | Design per size; scale stroke; use SVG | | Shrink the tap area to the glyph | ≥44pt / 48dp touch target with padding | | Switch filled/outlined for decoration | Use the variant to signal state (default vs active) | | Reinvent platform-standard icons | Start from SF Symbols / Material; match them for custom | | Ship icons unchecked | Hand off to accessibility + aesthetics + microcopy (+ mobile) |

---

Source lessons (Uxcel)

• How to Use Icons in UI Design
• Icons & Symbols Guidelines
• Iconography in Design Systems
• Icon Terminology

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Uxcel-Lab
• Source: Uxcel-Lab/product-skills
• License: MIT
• Homepage: https://uxcel.com

Install and usage instructions live in the source repository linked above.