description: "Apply 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\"."
metadata:
version: "1.0"
---
# Applying SLDS
The **Salesforce Lightning Design System (SLDS)** is a CSS framework with thousands of artifacts. This skill teaches agents how to find and correctly use them.
> **Version:** This skill targets **SLDS v2**. Legacy `--lwc-*` tokens and `slds-*--modifier` syntax are deprecated.
>
> **Audit scope:** The companion `design-systems-slds-validate` skill analyzer only scans `.css`, `.html`, and `.js` files. Use it directly for LWC and similar HTML/CSS/JS components; treat it as a partial signal for JSX/TSX or other framework-specific template formats and supplement with manual review.
- How to style with hooks (color, spacing, typography, shadows, borders)
- Which utility classes to use for layout, spacing, visibility
- Which icon to use and from which category
- SLDS naming conventions, class structure, hook syntax
**This skill includes basic accessibility reminders** (icon alt text, focus outlines, color-not-sole-indicator) in the validation checklists. Full WCAG compliance requires a dedicated accessibility review.
**This skill does NOT cover (use companion skills):**
- Use `var(--slds-g-*, fallback)` for all themeable values
- Create custom classes (`my-*`, `c-*`) instead of overriding `.slds-*`
- **Verify every hook, class, and utility exists before using it** — run the search scripts; never assume an artifact exists based on naming patterns (see [Verify Before You Use](#verify-before-you-use))
- Pair surface colors with on-surface colors for text
- Provide `alternative-text` on every `<lightning-icon>`
### Don't
- Hard-code colors, spacing, or typography values
- Override `.slds-*` classes directly
- Use deprecated `--lwc-*` tokens as primary values
- Use `--slds-s-*` (shared) hooks -- they are private/internal
- Reassign hook values -- only reference them with `var()`
- Use color alone to convey meaning
- Invent hook names by interpolating patterns from other families (see Naming Traps below)
SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming `{prefix}-{number}` works universally. **Always verify a hook exists** via the bundled `search-hooks.cjs` script or `assets/hooks-index.json` before using it.
**Rule:** For font sizes, use `--slds-g-font-size-base` (the one base size) or `--slds-g-font-scale-*` (the numbered scale). Never `--slds-g-font-size-N`.
### Trap 2: Color hooks always require a number
| Wrong (does not exist) | Correct | Notes |
|------------------------|---------|-------|
| `--slds-g-color-on-surface` | `--slds-g-color-on-surface-2` | All color hooks need a number |
| `--slds-g-color-surface` | `--slds-g-color-surface-1` | No unnumbered base form |
**Rule:** Every `--slds-g-color-*` hook ends in a number. Pick by emphasis: `-1` (low), `-2` (medium), `-3` (high).
### Trap 3: Not all values have hook equivalents
Some CSS values (e.g., `min-width: 7rem` for label alignment) have no SLDS hook. This is acceptable:
```css
.c-field-label {
/* No SLDS hook exists for this width; intentional custom value */
min-width: 7rem;
}
```
**Rule:** When no hook exists, use the value directly with a comment explaining it's intentional. Prefer SLDS grid utilities (`slds-size_*`) as alternatives to hardcoded widths where possible.
---
## Verify Before You Use
> **Rule:** Never include an SLDS hook, utility class, blueprint class, or icon in generated code without first confirming it exists in the metadata. Guessing based on naming patterns is the primary source of invented artifacts.
Run the appropriate search command **before** emitting any SLDS artifact:
| Artifact | Verification command | Source of truth |
> **Do not read metadata JSON files directly** — they are too large for agent context (hooks-index.json is 6,000+ lines; icon-metadata.json is 38,000+ lines). Use the search scripts above to query them.
The linter catches hardcoded values, class overrides, and deprecated tokens. **Fix all violations before proceeding.** Do not rationalize violations as acceptable.
**Step 2: Verify no invented hooks.** Confirm every `--slds-g-*` hook in the output exists in `assets/hooks-index.json`. Cross-reference against the T051 check in [checklists.md](checklists.md).
**Step 3: Run through [checklists.md](checklists.md)** for the checks the linter cannot automate:
- All `var(--slds-g-*)` have fallback values (T002)
- Surface/accent/feedback color hooks are properly paired (T010–T013)
- Spacing uses hooks or utility classes — no magic `px` values (T020–T021)
- Font sizes use `--slds-g-font-scale-*`, not `--slds-g-font-size-N` (T031)
- All icons have accessibility text (A004)
- Custom classes use `my-*` or `c-*` prefix (Q010)
**Step 4 (optional): Run the full quality audit** using the `design-systems-slds-validate` skill for a scored report before code review or deployment. Use it directly for LWC / HTML-CSS-JS components; for JSX/TSX outputs, treat the result as partial coverage only. Target a B grade (≥80) or higher before marking work complete.
---
## Quick Reference
### Common Hook Patterns
```css
/* Surface + text pairing (always use numbered variants) */
