Icons Skill

Use the Lucide icon library with local SVG files and the <x-icon> Web Component for consistent, accessible icons.

CRITICAL: When to Use This Skill

ALWAYS use the <x-icon> component. NEVER use inline SVGs.

Bad (Do NOT do this):

<!-- WRONG: Inline SVG -->
<button>
  <svg viewBox="0 0 24 24"><path d="M12 3v1m0 16v1..."/></svg>
</button>

Good (Do this instead):

<!-- CORRECT: x-icon component -->
<button>
  <x-icon name="sun" label="Light theme"></x-icon>
</button>

Why? The <x-icon> component:

• Ensures consistent sizing across the app
• Handles accessibility automatically
• Uses optimized, cached SVG loading
• Inherits color from CSS (no hardcoded colors)
• Works with any icon set (Lucide, custom, etc.)

Quick Start

<!-- Basic usage -->
<x-icon name="menu"></x-icon>
<x-icon name="arrow-right"></x-icon>
<x-icon name="check"></x-icon>

<!-- With size -->
<x-icon name="home" size="lg"></x-icon>

<!-- With accessible label (for functional icons) -->
<button>
  <x-icon name="x" label="Close"></x-icon>
</button>

<!-- Custom icon set -->
<x-icon name="logo" set="custom"></x-icon>

Directory Structure

.assets/
├── js/
│   └── components/
│       └── x-icon/          # Icon Web Component
│           ├── x-icon.js
│           └── x-icon-styles.js
└── icons/
    ├── lucide/              # Lucide icons (synced from npm)
    │   ├── index.json       # Icon manifest
    │   ├── menu.svg
    │   ├── x.svg
    │   └── ...              # ~1900 icons
    └── custom/              # Project-specific icons
        └── logo.svg

Setup

Run /scaffold-icons to set up icons in a project, or manually:

# 1. Install lucide-static
npm install lucide-static --save-dev

# 2. Sync icons
npm run icons:sync

# 3. Copy x-icon component
mkdir -p .assets/js/components/x-icon
cp .claude/skills/icons/templates/x-icon/*.js .assets/js/components/x-icon/

# 4. Include in HTML
<script type="module" src="/.assets/js/components/x-icon/x-icon.js"></script>

The <x-icon> Component

Attributes

Size Reference

Styling

Icons inherit currentColor for stroke color:

/* Change icon color */
.danger x-icon {
  color: var(--color-error);
}

/* Custom sizing */
x-icon.hero-icon {
  width: 4rem;
  height: 4rem;
}

Syncing Icons

Icons are sourced from the lucide-static npm package:

# Install package (one-time)
npm install lucide-static --save-dev

# Sync icons to .assets/icons/lucide/
npm run icons:sync

Run icons:sync after:

• Initial project setup
• Updating lucide-static version
• Fresh npm install

Accessibility

Decorative Icons (default)

Icons without a label are hidden from screen readers:

<!-- Decorative - hidden from screen readers -->
<button>
  <x-icon name="save"></x-icon>
  Save Document
</button>

Functional Icons

Add label for icon-only buttons or links:

<!-- Functional - announced to screen readers -->
<button aria-label="Close dialog">
  <x-icon name="x" label="Close"></x-icon>
</button>

Guidelines

Adding Custom Icons

1. Create SVG file in .assets/icons/custom/:

<!-- .assets/icons/custom/logo.svg -->
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <path d="M12 2L2 7l10 5 10-5-10-5z"/>
</svg>

2. Use with set="custom":

<x-icon name="logo" set="custom"></x-icon>

Custom Icon Requirements

• SVG format with viewBox attribute
• No fixed width/height (component handles sizing)
• Use currentColor for strokes/fills to inherit color
• Keep file size small (optimize with SVGO)

Replacing the Icon Set

To use a different icon library:

1. Remove lucide-static: npm uninstall lucide-static
2. Install alternative: npm install [other-library]
3. Update .claude/scripts/sync-icons.js source path
4. Run npm run icons:sync
5. Or manually copy SVGs to .assets/icons/[set-name]/

The <x-icon> component works with any SVG icon library.

Finding Icons

Browse available icons:

• Lucide: https://lucide.dev/icons
• Local manifest: .assets/icons/lucide/index.json

# Search for icons locally
grep -l "arrow" .assets/icons/lucide/*.svg | head -10

Common Icons

Checklist

When using icons:

• Icon name matches file in .assets/icons/[set]/
• Functional icons have label attribute
• Icon size appropriate for context
• Color inherits from parent (uses currentColor)
• Custom icons saved to .assets/icons/custom/

Related Skills

• xhtml-author - Write valid XHTML-strict HTML5 markup
• accessibility-checker - Ensure WCAG2AA accessibility compliance
• css-author - Modern CSS organization with native @import, @layer casca...
• performance - Write performance-friendly HTML pages