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
npx skills add oakoss/agent-skills --skill icon-design -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/icon-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/icon-design/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill icon-design -a codex2Manually: put the files in place
.agents/skills/icon-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill icon-design -a cursor2Manually: put the files in place
.cursor/skills/icon-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/icon-design2Manually: put the files in place
.github/skills/icon-design/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill icon-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/icon-designManually: put the files in place
.devin/skills/icon-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill icon-design -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.