Setup

On first use, read setup.md silently and start naturally. Never mention setup files to the user.

When to Use

User needs icons in a web project. Agent handles icon selection, installation method, and framework-specific syntax.

Architecture

No persistent storage needed. Icon preferences tracked in user's main memory if requested.

Quick Reference

Core Rules

1. Determine Installation Method First

Ask or infer the project setup before suggesting icons:

2. Use Correct Syntax Per Method

CDN Kit (easiest):

<script src="https://kit.fontawesome.com/YOUR_KIT_ID.js" crossorigin="anonymous"></script>
<i class="fa-solid fa-house"></i>

npm (fontawesome-free):

npm install @fortawesome/fontawesome-free

import '@fortawesome/fontawesome-free/css/all.min.css';

<i class="fa-solid fa-user"></i>

React:

npm install @fortawesome/react-fontawesome @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faHouse } from '@fortawesome/free-solid-svg-icons';

<FontAwesomeIcon icon={faHouse} />

3. Know the Icon Styles

4. Icon Search Strategy

When user asks for an icon:

1. Suggest semantic name first (e.g., fa-envelope for email)
2. Provide 2-3 alternatives if ambiguous
3. Specify style availability (free vs pro)

Common mappings:

5. Sizing and Styling

Size classes:

<i class="fa-solid fa-house fa-xs"></i>   <!-- 0.75em -->
<i class="fa-solid fa-house fa-sm"></i>   <!-- 0.875em -->
<i class="fa-solid fa-house fa-lg"></i>   <!-- 1.25em -->
<i class="fa-solid fa-house fa-xl"></i>   <!-- 1.5em -->
<i class="fa-solid fa-house fa-2xl"></i>  <!-- 2em -->

Fixed width (for alignment in lists):

<i class="fa-solid fa-house fa-fw"></i>

Animation:

<i class="fa-solid fa-spinner fa-spin"></i>
<i class="fa-solid fa-heart fa-beat"></i>
<i class="fa-solid fa-bell fa-shake"></i>

Rotation:

<i class="fa-solid fa-arrow-right fa-rotate-90"></i>
<i class="fa-solid fa-arrow-right fa-rotate-180"></i>
<i class="fa-solid fa-arrow-right fa-flip-horizontal"></i>

6. Accessibility

Always provide accessible labels:

<!-- Decorative (hidden from screen readers) -->
<i class="fa-solid fa-house" aria-hidden="true"></i>

<!-- Meaningful (needs label) -->
<i class="fa-solid fa-trash" aria-label="Delete item"></i>

<!-- With visible text (icon is decorative) -->
<button>
  <i class="fa-solid fa-save" aria-hidden="true"></i>
  Save
</button>

7. Version Differences

v6 (current):

• Use fa-solid, fa-regular, fa-brands
• Icon names like fa-house, fa-magnifying-glass

v5 (legacy):

• Use fas, far, fab
• Some icon names changed (e.g., fa-home → fa-house)

If working with existing v5 code, don't force upgrade unless asked.

Common Traps

• Using Pro icons in free tier → icons don't render, no error
• Wrong prefix (fa-solid vs fas) → depends on version, check project
• Missing CSS import with npm → icons show as squares
• Using v5 names in v6 → some work, some don't (e.g., fa-home deprecated)
• Not setting aria-hidden on decorative icons → screen reader noise

External Endpoints

No user data is sent. Icons loaded from public CDN.

Security & Privacy

Data that leaves your machine:

• HTTP request to Font Awesome CDN (if using CDN method)

Data that stays local:

• All icon choices and code

This skill does NOT:

• Track icon usage
• Send analytics
• Require authentication for free tier

Related Skills

Install with clawhub install <slug> if user confirms:

• react — React development patterns
• html — HTML best practices
• css — CSS styling patterns

Feedback

• If useful: clawhub star font-awesome
• Stay updated: clawhub sync