forcedotcom/sf-skills / skills/design-systems-slds-apply
design-systems-slds-apply
UnverifiedApply SLDS-compliant UI using the correct blueprints, styling hooks, utility classes, and icons. Use when building any UI that needs SLDS, choosing between Lightning Base Components and SLDS Blueprints, applying styling hooks for theming, using utility classes for layout and spacing, or selecting icons. Triggers include "build a modal", "create a form", "data table", "SLDS styling", "style with hooks", "add an icon".
references/icons-decision-guide.md
View on GitHub# Icons Decision Guide
How to select and use SLDS icons correctly.
---
## Icon Categories
SLDS provides 1,732 icons across 5 categories. Pick the right category first:
| Category | Purpose | Size | Example |
|----------|---------|------|---------|
| **utility** | UI affordances: actions, navigation, status indicators | 16-24px | `utility:search`, `utility:close`, `utility:save` |
| **standard** | Object/entity representations | 48px | `standard:account`, `standard:contact`, `standard:opportunity` |
| **action** | Actions on objects, typically in button icons | 24px | `action:new_task`, `action:edit`, `action:delete` |
| **custom** | Custom object representations (custom1-custom113) | 48px | `custom:custom1`, `custom:custom42` |
| **doctype** | File type representations | 48px | `doctype:pdf`, `doctype:excel`, `doctype:word` |
### Category Decision Tree
```text
What does the icon represent?
├─ A UI control or indicator? → utility
├─ A Salesforce object or entity? → standard
├─ An action the user can take? → action
├─ A custom object? → custom
└─ A file type? → doctype
```
---
## How to Search
```bash
# Semantic search with synonym matching
node scripts/search-icons.cjs --query "save button"
# Filter by category
node scripts/search-icons.cjs --query "user" --category "standard"
# List all categories
node scripts/search-icons.cjs --list-categories
```
The search engine matches against icon names, synonyms, and descriptions. Multi-word queries match across all fields with relevance scoring.
---
## Usage in LWC
Use `<lightning-icon>` for display and `<lightning-button-icon>` for interactive icons:
```html
<!-- Display icon -->
<lightning-icon
icon-name="utility:search"
alternative-text="Search"
size="small">
</lightning-icon>
<!-- Interactive icon button -->
<lightning-button-icon
icon-name="utility:close"
alternative-text="Close dialog"
title="Close"
onclick={handleClose}>
</lightning-button-icon>
```
### Size options
| Size | Use for |
|------|---------|
| `xx-small` | Inline with text |
| `x-small` | Dense layouts |
| `small` | Default for utility icons |
| `medium` | Default for standard/custom icons |
| `large` | Hero/feature icons |
---
## Usage in Non-LWC (Blueprint Markup)
Use SVG with SLDS icon classes:
```html
<span class="slds-icon_container slds-icon-utility-search" title="Search">
<svg class="slds-icon slds-icon_small" aria-hidden="true">
<use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
</svg>
<span class="slds-assistive-text">Search</span>
</span>
```
Key classes:
- `slds-icon_container` -- wrapper with background color
- `slds-icon` -- the SVG element
- `slds-icon_small` / `slds-icon_large` -- sizing
- `slds-icon-utility-*` / `slds-icon-standard-*` -- category-specific containers
---
## Accessibility Rules
**Every icon must have an accessibility story.**
| Scenario | LWC | Non-LWC |
|----------|-----|---------|
| **Meaningful icon** (conveys information) | `alternative-text="Description"` | `<span class="slds-assistive-text">Description</span>` |
| **Decorative icon** (next to text label) | `alternative-text=""` | `aria-hidden="true"` on SVG |
| **Interactive icon** (button) | `alternative-text="Action"` + `title="Tooltip"` | `aria-label="Action"` on button |
**Rules:**
- Never leave `alternative-text` undefined on `<lightning-icon>` -- set it to empty string `""` if decorative
- `title` provides a visible tooltip; `alternative-text` provides screen reader text
- Icon-only buttons always need `alternative-text` describing the action, not the icon
---
## Deep Reference
- Icon implementation guidance: `references/icons-guidance.md`
- Icons overview: `references/overviews/icons.md`
- Full icon metadata (1,732 icons with synonyms): `assets/icon-metadata.json`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |