afv-library/skills/design-systems-slds-apply/references/icons-guidance.md

id	title	description	summary	artifact_type	domain	topic	content_format	complexity	audience	tasks	refs	tags	keywords
slds.guidance.icons	SLDS Icons Guidance	Icon selection and implementation guidance for coding agents	Icon implementation guide covering the sprite:symbol naming model, category decision guide (action, utility, standard, custom, doctype), implementation patterns for Lightning and SLDS markup, and accessibility requirements.	guide	icons	icons	structured	intermediate	implementer	choose implement	slds.guidance.development slds.guidance.design slds.guidance.blueprints	icons sprites svg utility-icons action-icons standard-icons	icon sprites utility icons action icons standard icons custom icons doctype icons icon accessibility SVG icons

SLDS Icons Guidance

Overview

SLDS icons are a curated set of reusable SVG symbols grouped into sprite categories. They're used to add quick, consistent visual meaning to UI elements (buttons, navigation, record headers, status indicators, file types, and more).

This guidance covers:

• Category guidance for picking the right sprite
• Implementation patterns (Lightning + SLDS markup)
• Accessibility requirements for icons in UI

---

Icon Naming Model (Critical)

An icon is referenced as:

• sprite:symbol (example: utility:search, action:save, standard:account)

Where:

• sprite = category (action, utility, standard, custom, doctype)
• symbol = the icon name within that sprite

---

Category Decision Guide (What to Use When)

Action Icons (action:*)

• Use for: verbs / user actions (save, delete, edit, add, close)
• Common placements: buttons, menus, toolbars, row actions
• Rule of thumb: if the UI text could start with "Do …", use action:

Utility Icons (utility:*)

• Use for: general interface affordances and controls (search, settings, filter, chevrons)
• Common placements: nav, search fields, utility panels, small inline UI hints
• Rule of thumb: if it's a UI control concept (not a business object), use utility:

Standard Icons (standard:*)

• Use for: Salesforce objects/entities (Account, Contact, Case, Opportunity)
• Common placements: record headers, object pickers, list tiles
• Rule of thumb: if the icon represents "what this thing is" (a noun/object), use standard:

Custom Icons (custom:*)

• Use for: generic shapes/symbols, often for custom objects when no standard icon fits
• Common placements: custom object tiles, app launcher tiles, branded placeholders
• Rule of thumb: use custom: when standard: is not appropriate and you still want a "record/object style" icon

Doctype Icons (doctype:*)

• Use for: file types (pdf, image, spreadsheet, etc.)
• Common placements: attachments, file lists, previews
• Rule of thumb: if you're representing a file format, use doctype:

---

How to Search Icons

Effective query patterns:

• Intent-first: "save", "delete", "filter", "settings", "add user"
• Object-first: "account", "contact", "case"
• UI affordance: "chevron right", "close x", "search magnifier"

Optional filters:

• Restrict to a sprite category (action / utility / standard / custom / doctype)
• Limit results to keep responses tight

Searchable Metadata Fields

Each icon entry in the JSON metadata supports these lookup strategies:

• Exact match: category + icon name (mapped to sprite:symbol at runtime, e.g. utility:chevronright)
• Discovery: synonyms (best for intent searches — e.g. "next" finds chevronright)
• Styling: className (computed as slds-icon-{category}-{name} for SLDS <svg> containers)
• Context: description (matches long-form queries about icon purpose)
• RTL: directionality.hasRtl (rare, but important for directional glyphs)

---

Implementation Patterns

Lightning Web Components (preferred inside Salesforce)

Icon only:

<lightning-icon
  icon-name="utility:search"
  alternative-text="Search"
  title="Search"
  size="x-small">
</lightning-icon>

Icon button:

<lightning-button-icon
  icon-name="action:save"
  alternative-text="Save"
  title="Save"
  onclick={handleSave}>
</lightning-button-icon>

SLDS (raw HTML/SVG usage)

If you're implementing outside Lightning components, use the className from the JSON (example: slds-icon-utility-search) with the appropriate SLDS blueprint patterns for icon containers.

---

Sizes

When rendering icons in Lightning Web Components, prefer the built-in size tokens on lightning-icon / lightning-button-icon instead of custom CSS.

Size token	Typical use
xx-small	Inline with dense UI or text-adjacent glyphs
x-small	Compact layouts / tight controls
small	Default for most utility UI icons
medium	Default for object/record representation icons
large	Featured / hero contexts (use sparingly)

---

Accessibility Requirements (Do Not Skip)

When the icon communicates meaning

• Provide text for assistive tech:
  • LWC: alternative-text (required), title (recommended)
  • HTML/SVG: ensure an accessible name via text, aria-label, or title as appropriate

When the icon is purely decorative

• Hide it from assistive tech (don't create "noise"):
  • LWC: use an empty alternative-text="" only if the containing control already has an accessible label
  • HTML/SVG: aria-hidden="true" on the decorative icon element

Don't rely on icons alone

If the icon represents status (success/error/warning), ensure there's text and/or non-color cues in addition to the icon.

---

Icon Metadata Structure

All 1,732 icons are stored in a single icon-metadata.json file, keyed by icon name. Each entry includes:

• displayName — the icon identifier (e.g. chevronright, add_contact)
• category — sprite category: action, utility, standard, custom, doctype
• synonyms — search terms for discovery (e.g. ["next", "forward", "arrow", "chevron"])
• description — what the icon represents
• directionality — type (common or directional) and hasRtl flag