mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-08 00:10:29 +08:00
119dc668d5
* feat: add SLDS applying and auditing quality skills Two new skills for SLDS v2 compliance: - applying-slds: guides artifact selection, styling hooks, utilities, icons - auditing-slds-quality: scored quality audit with linter + static analysis Made-with: Cursor * refactor: rename auditing-slds-quality skill to validating-slds Renames the skill directory and updates all references in applying-slds/SKILL.md and applying-slds/checklists.md. Made-with: Cursor * fix: improve accuracy and add manual review gate across SLDS skills Correct hook families, badge modifiers, and severity levels; add a manual review gate to validating-slds so automated grades alone cannot declare production readiness; make analyze-quality.cjs portable with explicit --hooks-index flag; remove dead parseYaml code; add version field to all three skill frontmatters. Made-with: Cursor * chore: retrigger CI Made-with: Cursor * fix: quote YAML descriptions and improve color hook disambiguation - Quote description frontmatter in all three skills for valid YAML (inner double quotes now escaped) - Strengthen Step 4 directive: MUST read color-hooks guide before choosing a hook — linter suggestions are unranked - Add surface vs surface-container disambiguation table - Add accent hook context table and state progression - Add standalone-component exception for surface classification - Add modal background example to examples.md - Remove redundant brand-button example (covered by new context table) Made-with: Cursor
125 lines
3.8 KiB
Markdown
125 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```
|
|
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: `guidance/icons-guidance.md`
|
|
- Icons overview: `guidance/overviews/icons.md`
|
|
- Full icon metadata (1,732 icons with synonyms): `metadata/icon-metadata.json`
|