```
✅ **GOOD: Uploading custom SVGs to your Kit and using `fa-kit` prefix**
```html
```
## 2. Common Patterns and Anti-patterns
### 2.1 Icon Styles
Always specify the icon style (e.g., `fa-solid`, `fa-regular`, `fa-brands`). Consistency in style is crucial for a unified UI.
❌ **BAD: Omitting style, relying on default (which can change or be ambiguous)**
```html
```
✅ **GOOD: Explicitly defining the style**
```html
```
### 2.2 Sizing Icons
Utilize Font Awesome's sizing utilities to maintain consistent vertical alignment and scale. Avoid custom CSS `font-size` overrides unless absolutely necessary for unique cases.
#### 2.2.1 Relative Sizing (for UI elements)
Use `fa-xs` to `fa-2xl` when icons need to align with text or other UI components. These classes adjust size while preserving vertical alignment.
❌ **BAD: Custom CSS `font-size` for inline icons**
```html
My coffee
``` ✅ **GOOD: Relative sizing classes for text alignment** ```htmlMy coffee
``` #### 2.2.2 Literal Sizing (for standalone icons) Use `fa-1x` to `fa-10x` for larger, standalone icons where precise text alignment is not the primary concern. ❌ **BAD: Scaling large icons with `em` units that might break alignment** ```html
```
✅ **GOOD: Literal sizing classes for large, independent icons**
```html
```
## 3. Performance Considerations
### 3.1 Kit Configuration
**Always configure your Kit to load only the icon subsets you actually use.** This significantly reduces download size and improves page load times. Regularly review and prune unused icon styles or categories.
❌ **BAD: Using a Kit with all icon styles enabled by default**
(This is a configuration anti-pattern, not directly code-related, but impacts code performance.)
✅ **GOOD: Customizing Kit to include only `Solid` and `Brands` if those are the only styles used.**
(Action: Visit fontawesome.com/kits, configure your kit.)
### 3.2 Self-Hosting (Advanced)
Only consider self-hosting Font Awesome if you have strict performance requirements, advanced caching strategies, and full control over your asset delivery. For most projects, Kit-based CDN is superior.
❌ **BAD: Self-hosting without a clear performance benefit or maintenance plan**
(Increased complexity, manual updates, potential for outdated versions.)
✅ **GOOD: Kit-based CDN for most projects; self-hosting only with justification and expertise.**
(Action: Stick to Kit unless a performance audit explicitly demands self-hosting and your team has the resources.)
## 4. Common Pitfalls and Gotchas
### 4.1 Missing Kit Script
Icons won't render if the Kit script is missing or incorrectly placed. Always verify its presence in the ``.
❌ **BAD: Icons showing as squares or empty space**
```html
```
✅ **GOOD: Verify script is loaded and accessible**
(Action: Check browser console for network errors related to the Kit script, ensure correct URL.)
### 4.2 Incorrect Class Names
Typos in icon names or style prefixes are common. Use the Font Awesome search tool to confirm exact class names.
❌ **BAD: Typo in icon name**
```html
```
✅ **GOOD: Double-checking icon names**
```html
```
### 4.3 SVG Upload Guidelines
When uploading custom SVGs to a Kit, adhere strictly to Font Awesome's guidelines to prevent rendering issues.
* **`viewBox`**: Must have explicit `width` and `height`.
* **Paths**: Single `
Welcome to our site!
``` ### 5.2 Semantic Icons If an icon conveys meaning (e.g., a "next page" arrow, a "message" icon in a button), provide an accessible text alternative. Use the `title` attribute, and Font Awesome's auto-accessibility will convert it into a screen-reader-only span. ❌ **BAD: Semantic icon without any accessible label** ```html ``` ✅ **GOOD: Semantic icon with a descriptive `title` attribute** ```html ``` ### 5.3 Manual Accessibility (Fallback) If Auto-Accessibility is unavailable (e.g., self-hosting older versions, specific framework integrations), you must manually apply `aria-hidden="true"` for decorative icons or an `sr-only` span for semantic ones. ❌ **BAD: Assuming auto-accessibility is always active** (Always verify your setup or explicitly add attributes.) ✅ **GOOD: Understanding when manual intervention is needed** ```html Notifications ``` ## 6. Theming Font Awesome icons inherit `font-size` and `color` from their parent elements. Leverage this for consistent theming. ❌ **BAD: Applying inline styles or overly specific CSS to individual icons** ```html ``` ✅ **GOOD: Styling icons via parent elements or utility classes** ```css /* In your CSS */ .primary-button .fa-icon { color: var(--color-primary); } .large-heading .fa-icon { font-size: 1.2em; /* Scales relative to heading */ } ``` ```html