Iconography

---
model_tier: inherit
name: iconography
description: "Resolve an icon request to a concrete Iconify name and emit the embedding for the project's stack. Use when adding icons, picking an icon set, or wiring Lucide/Heroicons/Phosphor/Tabler."
domain: product
personas: []
workspaces:
  - engineering
packs:
  - frontend-design
trust:
  level: professional
install:
  removable: true
scope:
  write: []
  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
execution:
  type: manual
---

# iconography

> Resolve an icon request to a verified Iconify name (`set:name`) and emit the
> correct embedding for the project's stack — CSS class, inline SVG, or
> framework component — while keeping icon-set usage consistent across the UI.

## When to use

- Adding any icon to a component or page.
- Picking an icon set for a new project or feature area.
- Wiring Lucide, Heroicons, Phosphor, or Tabler into a stack (React, Blade, Tailwind).
- Auditing inconsistent icon usage across a UI surface.

## Procedure

1. **Identify the icon need** — what does the icon communicate? Name the semantic
   intent (e.g., "download action", "warning state", "user profile") rather than
   visual description alone.
2. **Pick the icon set** per stack and brand context. Default open sets:
   **Lucide** (clean, Tailwind-native), **Heroicons** (Tailwind/React first-party),
   **Phosphor** (multi-weight, flexible), **Tabler** (comprehensive, stroke-based).
   Brand/provider marks use **lobe-icons** (`lobe-icons:openai-color`, etc.).
   Stack consumers: `react-shadcn-ui` → Lucide; `blade-ui` → Heroicons or Lucide;
   `tailwind-engineer` → any web-font-friendly set.
3. **Resolve to a concrete Iconify name** in `set:name` format, e.g.
   `lucide:arrow-right`, `heroicons:user-solid`, `ph:warning-bold`,
   `tabler:download`. Verify the name exists on
   [iconify.design](https://iconify.design) before emitting.
4. **Emit the embedding** matched to the stack:
   - **CSS class (web-font path)** — `<span class="iconify" data-icon="lucide:arrow-right"></span>` plus the Iconify CDN or build-time bundle.
   - **Inline SVG** — fetch the SVG from the Iconify API (`https://api.iconify.design/{set}/{name}.svg`) and embed directly.
   - **Framework component** — `<Icon icon="lucide:arrow-right" />` via `@iconify/react`, `@iconify/vue`, or the stack's Iconify wrapper.
5. **Verify** — check the resolved name on `iconify.design/icon/{set}:{name}`;
   confirm the icon renders as expected before shipping.

## Iconography floor (design fidelity)

Before resolving any new icon, honour the project's existing icon system — the
Inspect stage of the
[design-artifact lifecycle](../../../docs/contracts/design-artifact-lifecycle.md).

- **Inspect first.** Detect the icon set already in use (imports, existing
  `set:name` usages, brand assets) before picking one. A new icon matches the
  incumbent set's **stroke weight, fill style, corner radius, size, and
  metaphor** — do not introduce a second visual language (see
  [`icon-consistency`](../../rules/icon-consistency.md)).
- **No emoji-as-icon in serious UI.** An emoji is not an icon — never substitute
  `⚙️`/`🔔`/`✅` for a real icon in a product/admin/marketing surface (functional
  CLI/status markers are a different context, out of scope here).
- **No hand-rolled icons when a set exists.** If the project has an icon library
  or brand mark, use it — do not hand-author a one-off SVG that drifts from the
  system. Hand-rolling is for a genuinely missing glyph, and then it matches the
  set's grid + stroke.
- **Flag substitutions when the exact asset is absent.** When the needed icon or
  brand mark does not exist in the set, pick the nearest and **state the
  substitution** ("no exact 'sync' glyph in Heroicons; used `arrow-path`") rather
  than silently approximating or inventing. (fixtures: `daf-emoji-as-icon`,
  `daf-fake-svg-logo`.)

## Output format

1. **Iconify name** — `set:name` string, e.g. `lucide:arrow-right`.
2. **Embedding snippet** — the ready-to-paste code for the project's stack
   (CSS class, inline SVG, or component import + usage).
3. **Set/consistency note** — which set was chosen, why, and whether it matches
   the icons already in use in this codebase.

## Gotcha

- **Mixing icon sets in one UI looks inconsistent.** Lucide and Heroicons have
  different stroke weights and visual rhythm; mixing them without a deliberate
  brand reason produces a jarring result. Audit the existing set before
  introducing a second one.
- **Nonexistent Iconify names 404 silently.** A name like `lucide:arrowRight`
  (camelCase) or `heroicons:user` (missing `-solid`/`-outline` suffix) resolves
  to nothing at render time — the slot is empty with no error. Always verify on
  `iconify.design` before committing the snippet.

## Do NOT

- Do NOT mix multiple icon sets in the same UI surface without an explicit brand
  reason and a note in the set/consistency output.
- Do NOT inline hundreds of raw SVGs when a CSS-class web-font set is available —
  the bundle cost is orders of magnitude higher than a single Iconify CDN include.
- Do NOT invent Iconify names — every name must be verified to exist in the
  Iconify registry; a plausible-sounding name that doesn't exist renders as
  nothing.

## See also

- [`design-canon.md`](../../../docs/guidelines/design-canon.md) § Icon systems — prefer a named system's icon set (Material Symbols / SF Symbols / Fluent / Carbon) when that system is in play.
- [`design-tokens`](../design-tokens/SKILL.md) — token system the icon color/size variables should reference.
- [`typography-system`](../typography-system/SKILL.md) — sibling visual-consistency skill.
- [`fe-design`](../fe-design/SKILL.md) — broader frontend design discipline.
- [`icon-consistency`](../../rules/icon-consistency.md) — enforced rule for set discipline across the project.
- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — icon-relevant slop tells: V5 (hand-drawn SVG mixed with crisp icon-system icons) and T3 (small rounded-square icon tile above every feature heading — the universal AI feature-card template).