Skip to main content
skill CX Codex

icon-design · oakoss — Claude Code skill: what it does, how to install

icon-design matches UI concepts to semantically correct icons from Lucide, Heroicons, or Phosphor with safe tree-shaking import habits.

MIT 187 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill icon-design -a claude-code
Open on GitHub

What icon-design does

This skill guides the AI to pick semantically sound iconography for UI components like navigation bars, grids, and contact blocks. It maps specific concepts to ready-to-use component names across Lucide, Heroicons, and Phosphor, stopping unwanted emoji from landing in production code.

It enforces design standards across your layout: sticking strictly to outline or solid styles within a single block, passing colors via currentColor instead of hardcoded hex values, and standardizing sizes from w-4 h-4 up to w-10 h-10. Button-only icons are required to include aria-label attributes.

Wildcard imports like import * as Icons destroy bundle tree-shaking, which is why the skill insists on direct named imports. Lucide (lucide-react) serves as the default recommended library.

What it helps with

  • map UI concepts to proper icon component names
  • prevent emoji usage in website components
  • preserve tree-shaking with explicit named imports
  • enforce accessibility attributes for icon buttons

Example prompts for the agent

  • Pick appropriate Lucide icons for our feature cards
  • Audit icon imports in the header to ensure proper tree-shaking
  • Replace emoji with accessible Heroicons in the contact section

How to install icon-design

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill icon-design -a claude-code

2Manually: put the files in place

~/.claude/skills/icon-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/icon-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about icon-design

How to install icon-design in Claude Code?

Run npx skills add oakoss/agent-skills --skill icon-design -a claude-code. The skill file will be placed in ~/.claude/skills/icon-design/SKILL.md.

What does icon-design do?

It guides code assistants in picking matching icon components across major libraries while applying accessibility attributes and bundling best practices.

Which icon library is suggested by default?

Lucide is the default recommendation because it offers over 1,600 icons, solid React tooling, and dynamic loading via lucide-react/dynamic.

Source text

SKILL.md · MIT
---
name: icon-design
description: |
  Select semantically appropriate icons for websites using Lucide, Heroicons, or Phosphor. Covers concept-to-icon mapping, React/HTML templates, and tree-shaking patterns.

  Use when: building feature sections, service grids, contact info, navigation, or any UI needing icons. Prevents emoji usage, ensures consistency.
license: MIT
metadata:
  author: oakoss
  version: '1.1'
---

# Icon Design

Select the right icon for the job. Maps concepts to icons across three modern libraries, provides ready-to-use templates, and prevents common mistakes like broken tree-shaking and inconsistent styles.

## Quick Reference

| Concept        | Lucide          | Heroicons                | Phosphor          |
| -------------- | --------------- | ------------------------ | ----------------- |
| Award/Quality  | `Trophy`        | `trophy`                 | `Trophy`          |
| Price/Value    | `Tag`           | `tag`                    | `Tag`             |
| Location       | `MapPin`        | `map-pin`                | `MapPin`          |
| Expertise      | `GraduationCap` | `academic-cap`           | `GraduationCap`   |
| Support        | `MessageCircle` | `chat-bubble-left-right` | `ChatCircle`      |
| Security       | `Shield`        | `shield-check`           | `Shield`          |
| Speed          | `Zap`           | `bolt`                   | `Lightning`       |
| Phone          | `Phone`         | `phone`                  | `Phone`           |
| Email          | `Mail`          | `envelope`               | `Envelope`        |
| User/Profile   | `User`          | `user`                   | `User`            |
| Team           | `Users`         | `user-group`             | `Users`           |
| Settings       | `Settings`      | `cog-6-tooth`            | `Gear`            |
| Home           | `Home`          | `home`                   | `House`           |
| Search         | `Search`        | `magnifying-glass`       | `MagnifyingGlass` |
| Check/Success  | `Check`         | `check`                  | `Check`           |
| Close/Cancel   | `X`             | `x-mark`                 | `X`               |
| Menu           | `Menu`          | `bars-3`                 | `List`            |
| Calendar       | `Calendar`      | `calendar`               | `Calendar`        |
| Clock/Time     | `Clock`         | `clock`                  | `Clock`           |
| Heart/Favorite | `Heart`         | `heart`                  | `Heart`           |

## Library Selection

| Library       | Best For                         | Package                 |
| ------------- | -------------------------------- | ----------------------- |
| **Lucide**    | General use, React projects      | `lucide-react`          |
| **Heroicons** | Tailwind projects, minimal style | `@heroicons/react`      |
| **Phosphor**  | Weight variations needed         | `@phosphor-icons/react` |

Default recommendation: Lucide (1,600+ icons, excellent React integration, dynamic loading via `lucide-react/dynamic`).

## Selection Process

1. **Identify the concept** -- what does the label/title communicate?
2. **Check semantic mapping** -- see `references/semantic-mapping.md`
3. **Choose library** -- Lucide (default), Heroicons (Tailwind), Phosphor (weights)
4. **Apply template** -- see `references/icon-templates.md`
5. **Verify consistency** -- same style, same size within each section

## Icon Style Rules

| Rule              | Detail                                                                |
| ----------------- | --------------------------------------------------------------------- |
| No mixed styles   | Use all outline OR all solid in a section                             |
| No emoji          | Use proper icon components (tree-shakeable)                           |
| Use currentColor  | Icons inherit text color via `stroke="currentColor"`                  |
| Semantic colors   | Use `text-primary`, not `text-blue-500`                               |
| Consistent sizing | Inline `w-4 h-4`, cards `w-8 h-8`, hero `w-10 h-10`                   |
| Tree-shaking safe | Use explicit named imports and icon maps, never `import *`            |
| Accessibility     | Add `aria-hidden="true"` to decorative icons, `aria-label` to buttons |

## Common Mistakes

| Mistake                                                            | Correct Pattern                                                                  |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Importing all icons with `import * as Icons` breaking tree-shaking | Use explicit named imports and a static icon map                                 |
| Mixing outline and solid icon styles within the same section       | Pick one style per section and apply consistently                                |
| Using emoji instead of proper icon components                      | Always use tree-shakeable icon components from Lucide, Heroicons, or Phosphor    |
| Hardcoding color values like `text-blue-500` on icons              | Use semantic colors like `text-primary` so icons inherit theme changes           |
| Choosing icons by visual appeal rather than semantic meaning       | Map the concept first using the semantic mapping reference, then select the icon |
| Missing `aria-label` on icon-only buttons                          | Add `aria-label="Description"` to buttons containing only icons                  |
| Using old Heroicons import paths without size prefix               | Use `@heroicons/react/24/outline` with the size prefix                           |

## Delegation

- **Audit existing icon usage for consistency and tree-shaking issues**: Use `Explore` agent to scan imports and identify mixed styles or wildcard imports
- **Migrate icons from Font Awesome or Material to modern libraries**: Use `Task` agent with the migration guide reference
- **Plan icon system architecture for a design system**: Use `Plan` agent to select library, define sizing conventions, and establish semantic mappings

## References

- [semantic-mapping.md](references/semantic-mapping.md) -- Full concept-to-icon tables by category (quality, price, location, trade-specific, navigation, status)
- [icon-templates.md](references/icon-templates.md) -- React/HTML patterns with Tailwind (feature cards, buttons, inputs, navigation, status badges)
- [library-comparison.md](references/library-comparison.md) -- Lucide vs Heroicons vs Phosphor (features, bundle size, import patterns)
- [migration-guide.md](references/migration-guide.md) -- Font Awesome, Material Icons, Feather, and emoji to modern equivalents
- [accessibility.md](references/accessibility.md) -- Decorative vs meaningful icons, aria attributes, screen reader patterns

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

icon-design by other authors comes first.

From the same set106

The whole set →
ci-cd-architecture ci-cd-architecture is a Claude Code skill for planning CI/CD pipelines, comparing deployment platforms, and securing GitHub Actions. It supports preparing a project for production or changing its delivery setup. CX Codex +1 199installs openapi Guides the agent in writing OpenAPI 3.1 schemas and generating TypeScript clients. Ideal for REST API contract design and schema validation. CX Codex +1 197installs css-animation-patterns css-animation-patterns is a Claude Code skill for CSS animation work. It guides agents on composite properties, transitions, and newer motion APIs. CX Codex +1 196installs pnpm-workspace pnpm-workspace teaches coding agents to configure pnpm monorepos and version catalogs. Useful when managing multi-package repositories. CX Codex +1 195installs pdf-tools pdf-tools — a skill for Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI that covers the full PDF lifecycle: text and table extraction, generation, modification, form filling and encryption. CX Codex +1 186installs ssh-remote ssh-remote guides coding agents through OpenSSH setups, Ed25519 key pairs, port forwarding, and rsync transfers. CX Codex +1 183installs tanstack-hotkeys An agent skill for adding keyboard shortcuts to React with TanStack Hotkeys: single bindings, key sequences, user-recorded shortcuts. CX Codex +1 179installs technical-docs This skill helps write and maintain technical docs, create Mermaid diagrams, and compare documentation coverage with code. Use it for doc-as-code workflows and audits. CX Codex +1 177installs

Project sponsors

Companies that keep this analytics open