@salesforce/afv-skills 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/applying-slds/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: applying-slds
+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 `validating-slds` 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.
+
+## What is SLDS?
+
+| Artifact | Count | Description |
+|----------|-------|-------------|
+| **Lightning Base Components** | ~70 | Pre-built LWC components (LWC only) |
+| **SLDS Blueprints** | 85 | CSS/HTML patterns for any framework |
+| **Styling Hooks** | 523 | CSS custom properties (`--slds-g-*`) for theming |
+| **Utility Classes** | 1,147 | Rapid styling classes for spacing, layout, visibility |
+| **Icons** | 1,732 | SVG icons across 5 categories |
+
+---
+
+## Scope
+
+**This skill covers:**
+- Which blueprint to use for a given UI pattern
+- 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):**
+- **Design decisions** -- visual hierarchy, composition, interaction patterns
+- **LWC mechanics** -- component structure, @wire, @api, lifecycle, events (not yet available)
+- **Full accessibility** -- WCAG conformance, ARIA patterns, keyboard navigation, focus management, contrast ratios (not yet available)
+
+---
+
+## Component Selection Hierarchy
+
+Always follow this order:
+
+```
+1. Lightning Base Components (LWC only)    ← Check first
+2. SLDS Blueprints (any framework)         ← Use exact SLDS classes
+3. Custom with Styling Hooks               ← Use var(--slds-g-*)
+4. Custom CSS (last resort)                ← Still use hooks for values
+```
+
+If building in LWC, check for an LBC first: [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components)
+
+If no LBC exists (or not using LWC), select an SLDS Blueprint. See [references/component-selection.md](references/component-selection.md).
+
+---
+
+## Core Rules
+
+### Do
+
+- Follow the selection hierarchy: LBC > Blueprint > Hooks > Custom CSS
+- 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)
+
+---
+
+## Hook Naming Traps
+
+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 `metadata/hooks-index.json` before using it.
+
+### Trap 1: Font size hooks are NOT numbered
+
+| Wrong (does not exist) | Correct | Notes |
+|------------------------|---------|-------|
+| `--slds-g-font-size-3` | `--slds-g-font-scale-1` | Font sizes use `font-scale-*`, not `font-size-*` |
+| `--slds-g-font-size-4` | `--slds-g-font-scale-2` | Only `--slds-g-font-size-base` exists (base size) |
+| `--slds-g-font-size-8` | `--slds-g-font-scale-6` | Scale goes: neg-4 through 10 |
+
+**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-on-accent` | `--slds-g-color-on-accent-1` | Pick 1/2/3 by emphasis level |
+| `--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 |
+|----------|---------------------|-----------------|
+| Styling hook (`--slds-g-*`) | `node scripts/search-hooks.cjs --prefix "<hook-name>"` | `metadata/hooks-index.json` |
+| Utility class (`slds-*`) | `node scripts/search-utilities.cjs --search "<class-name>"` | `metadata/utilities-index.json` |
+| Blueprint / CSS class | `node scripts/search-blueprints.cjs --search "<pattern>"` then read the YAML | `metadata/blueprints/components/*.yaml` |
+| Icon | `node scripts/search-icons.cjs --query "<description>"` | `metadata/icon-metadata.json` |
+
+If the search returns no match: **do not use the artifact.** Find an alternative from the search results or build custom with verified hooks.
+
+---
+
+## Naming Conventions
+
+Use a consistent prefix for custom classes to avoid collision with SLDS:
+
+| Pattern | Use Case | Example |
+|---------|----------|---------|
+| `my-*` | General custom styling | `my-card-header` |
+| `c-*` | LWC component-specific | `c-accountList-row` |
+| `[namespace]-*` | Package/app namespace | `acme-dashboard-widget` |
+
+**Avoid:** generic names (`container`, `wrapper`), SLDS-like names (`custom-slds-button`), BEM on SLDS classes (`slds-card__custom-header`).
+
+Custom hook namespacing:
+```css
+:root {
+  --my-app-primary: var(--slds-g-color-accent-1);
+  --my-app-card-padding: var(--slds-g-spacing-4);
+}
+```
+
+---
+
+## Knowledge Map
+
+This skill bundles comprehensive SLDS knowledge. Read files as needed -- don't read everything upfront.
+
+### Decision Guides (start here for each task)
+
+| File | Read when |
+|------|-----------|
+| [references/component-selection.md](references/component-selection.md) | Choosing a component or blueprint |
+| [references/styling-decision-guide.md](references/styling-decision-guide.md) | Applying colors, spacing, typography, shadows |
+| [references/icons-decision-guide.md](references/icons-decision-guide.md) | Selecting or implementing an icon |
+| [references/utilities-quick-ref.md](references/utilities-quick-ref.md) | Using utility classes for layout/spacing |
+
+### Search Scripts (find specific artifacts)
+
+| Script | What it searches | Example |
+|--------|-----------------|---------|
+| `scripts/search-blueprints.cjs` | 85 blueprint YAMLs | `--search "dialog"` |
+| `scripts/search-hooks.cjs` | 523 styling hooks | `--prefix "--slds-g-color-accent-"` |
+| `scripts/search-icons.cjs` | 1,732 icons with synonyms | `--query "save button"` |
+| `scripts/search-utilities.cjs` | 1,147 utility classes | `--category "grid"` |
+
+### Deep-Dive Guidance (read for detailed rules)
+
+| Folder | Content | Index |
+|--------|---------|-------|
+| `guidance/overviews/` | Foundational concepts (color, spacing, typography, etc.) | [guidance/README.md](guidance/README.md) |
+| `guidance/styling-hooks/` | Hook categories with detailed usage | [guidance/README.md](guidance/README.md) |
+| `guidance/utilities/` | 27 utility class categories | [guidance/README.md](guidance/README.md) |
+| `guidance/slds-development-guide.md` | Full SLDS development guide | -- |
+
+### Raw Metadata (structured data for lookup)
+
+> **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.
+
+| File | Content | Lines |
+|------|---------|-------|
+| `metadata/blueprints/components/*.yaml` | 85 blueprint specs (classes, variants, a11y, HTML) | ~50-200 each |
+| `metadata/hooks-index.json` | 523 hooks with values and CSS properties | ~6,300 |
+| `metadata/icon-metadata.json` | 1,732 icons with synonyms for search | ~38,500 |
+| `metadata/utilities-index.json` | 1,147 utility classes with CSS rules | ~6,900 |
+
+---
+
+## Authoring Workflow
+
+### Phase 1: Understand the Need
+
+Identify:
+- What UI pattern is needed? (form, table, modal, card, etc.)
+- What framework? (LWC, React, Vue, Angular, vanilla)
+- What data will it display?
+- What states does it need? (loading, empty, error, success)
+
+### Phase 2: Select the Artifact
+
+1. **If LWC**: Check the [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for an LBC
+2. **Search blueprints**: `node scripts/search-blueprints.cjs --search "<pattern>"`
+3. **Read the blueprint YAML**: `metadata/blueprints/components/<name>.yaml` for exact classes, modifiers, states, and accessibility requirements
+4. **No match?** Build custom with hooks (see Phase 3)
+
+Details: [references/component-selection.md](references/component-selection.md)
+
+### Phase 3: Apply Styling
+
+1. **Read**: [references/styling-decision-guide.md](references/styling-decision-guide.md)
+2. **Colors**: Classify role (surface, accent, feedback, border) then pick hook
+3. **Spacing**: Use utility classes (`slds-p-*`, `slds-m-*`) or hooks (`--slds-g-spacing-*`)
+4. **Layout**: Use grid utilities (`slds-grid`, `slds-col`, `slds-size_*`)
+5. **Custom CSS**: Use `var(--slds-g-*, fallback)`, custom class prefixes only
+
+### Phase 4: Add Icons
+
+1. **Read**: [references/icons-decision-guide.md](references/icons-decision-guide.md)
+2. **Search**: `node scripts/search-icons.cjs --query "<description>"`
+3. **In LWC**: Use `<lightning-icon>` with `alternative-text`
+4. **In non-LWC**: Use SVG with `slds-icon` classes and `slds-assistive-text`
+
+### Phase 5: Validate (Mandatory — Do Not Skip)
+
+**Step 1: Run the SLDS linter.** This is required. Zero violations is the target.
+
+```bash
+npx @salesforce-ux/slds-linter@latest lint <component-path>
+```
+
+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 `metadata/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 `validating-slds` 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) */
+background: var(--slds-g-color-surface-1, #ffffff);
+color: var(--slds-g-color-on-surface-2, #181818);
+
+/* Standard padding */
+padding: var(--slds-g-spacing-4, 1rem);
+
+/* Card-like container */
+border-radius: var(--slds-g-radius-border-2, 0.25rem);
+box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1));
+
+/* Accent for primary actions */
+background: var(--slds-g-color-accent-1, #0176d3);
+color: var(--slds-g-color-on-accent-1, #ffffff);
+
+/* Typography -- use font-scale-*, NOT font-size-* (only font-size-base exists) */
+font-size: var(--slds-g-font-scale-2, 0.875rem);
+```
+
+### Common Utility Patterns
+
+```html
+<!-- Responsive grid -->
+<div class="slds-grid slds-wrap slds-gutters">
+  <div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2">...</div>
+</div>
+
+<!-- Spacing -->
+<div class="slds-p-around_medium slds-m-bottom_small">...</div>
+
+<!-- Truncation -->
+<p class="slds-truncate" title="Full text here">Full text here</p>
+```
+
+---
+
+## Examples
+
+See [examples.md](examples.md) for worked examples demonstrating the full workflow from intent to SLDS artifact selection.
+
+## Validation
+
+See [checklists.md](checklists.md) for validation checklists aligned with the validating-slds skill.
+
+## Resources
+
+| Resource | URL |
+|----------|-----|
+| SLDS Website | https://www.lightningdesignsystem.com/ |
+| Lightning Component Library | https://developer.salesforce.com/docs/component-library/overview/components |
+| SLDS Linter | https://developer.salesforce.com/docs/platform/slds-linter/guide |
+| Styling Hooks Reference | https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks |

package/skills/applying-slds/checklists.md

@@ -0,0 +1,83 @@
+# Validation Checklists
+
+Run through these checks before finalizing any SLDS-authored component. Check IDs align with the validating-slds skill's quality-checks.md.
+
+
+## Theming & Styling (T-series)
+
+Code produced by this skill should score high on T-series checks.
+
+| Check | What to verify | Audit ID |
+|-------|---------------|----------|
+| **Hook fallbacks** | Every `var(--slds-g-*)` has a fallback value | T002 |
+| **Surface pairing** | `surface-*` bg paired with `on-surface-*` text | T010 |
+| **Container pairing** | `surface-container-*` bg paired with `on-surface-*` text | T011 |
+| **Accent pairing** | `accent-*` bg paired with `on-accent-*` text | T012 |
+| **Feedback pairing** | Feedback colors paired with correct text hooks | T013 |
+| **Spacing hooks** | Spacing uses `var(--slds-g-spacing-*)` or utility classes | T020 |
+| **No magic pixels** | No arbitrary `px` values for spacing | T021 |
+| **Font family hooks** | `font-family` uses `var(--slds-g-font-family-*)` | T030 |
+| **Font size hooks** | `font-size` uses `var(--slds-g-font-scale-*)` or `var(--slds-g-font-size-base)` -- NOT `var(--slds-g-font-size-N)` | T031 |
+| **Font weight hooks** | `font-weight` uses `var(--slds-g-font-weight-*)` | T032 |
+| **Shadow hooks** | Shadows use `var(--slds-g-shadow-*)` | T040 |
+| **Border radius hooks** | Border radius uses `var(--slds-g-radius-*)` | T041 |
+| **Color hooks numbered** | Every `--slds-g-color-*` hook ends in a number (no bare `on-surface`, `on-accent`, etc.) | T050 |
+| **No invented hooks** | Every hook referenced actually exists in `metadata/hooks-index.json` | T051 |
+| **No hardcoded colors** | No hex, rgb, or named colors (linter also catches this) | linter |
+| **No class overrides** | No `.slds-*` class overrides (linter also catches this) | linter |
+| **No deprecated tokens** | No `--lwc-*` tokens (linter also catches this) | linter |
+
+---
+
+## Code Quality (Q-series)
+
+| Check | What to verify | Audit ID |
+|-------|---------------|----------|
+| **No !important** | No `!important` declarations | Q001 |
+| **No inline styles** | No `style="..."` in HTML | Q002 |
+| **Custom class prefix** | Custom classes use `my-*`, `c-*`, or namespace prefix | Q010 |
+| **No dynamic SLDS class manipulation** | Avoid `.classList.add/remove/toggle('slds-*')` patterns in JS | Q012 |
+| **No magic numbers** | All numeric values have clear purpose | Q020 |
+
+---
+
+## Component Usage (C-series)
+
+| Check | What to verify | Audit ID |
+|-------|---------------|----------|
+| **LBC inputs** (LWC) | Use `<lightning-input>` not `<input>` | C001 |
+| **LBC buttons** (LWC) | Use `<lightning-button>` not `<button>` | C002 |
+| **LBC icons** (LWC) | Use `<lightning-icon>` not custom SVG | C003 |
+| **Blueprint structure** | Cards use `slds-card`, modals use `slds-modal`, etc. | C010-C013 |
+
+---
+
+## Accessibility Reminders (A-series)
+
+Deep accessibility is owned by the **accessibility skill**. These are minimal reminders to nudge agents.
+
+| Check | What to verify | Audit ID |
+|-------|---------------|----------|
+| **Icon alt text** | All `<lightning-icon>` have `alternative-text` (empty string for decorative) | A004 |
+| **Image alt text** | All `<img>` have `alt` attribute | A005 |
+| **Color not sole indicator** | Status uses icon or text too, not just color | A030 |
+| **No outline:none** | Don't remove focus outline without replacement | A021 |
+
+For full WCAG compliance, apply the accessibility skill after authoring.
+
+---
+
+## Quick Validation Script
+
+Run the SLDS linter to catch the most common issues automatically:
+
+```bash
+npx @salesforce-ux/slds-linter@latest lint .
+```
+
+The linter catches:
+- `slds/class-override` -- overriding SLDS classes
+- `slds/lwc-token-to-slds-hook` -- deprecated tokens
+- `slds/no-hardcoded-values` -- hardcoded colors/spacing
+
+Everything above the linter line must be checked manually or by the auditing skill.

package/skills/applying-slds/examples.md

@@ -0,0 +1,283 @@
+# Examples
+
+Worked examples showing the SLDS authoring workflow: from intent to artifact selection.
+
+Each example follows the 5-phase workflow from SKILL.md and shows which files were consulted and why.
+
+
+## Example 1: Build a Confirmation Dialog
+
+### Phase 1: Understand the Need
+
+- **Pattern:** Confirmation dialog before a destructive action
+- **Framework:** LWC
+- **States:** Open, confirming (loading), closed
+
+### Phase 2: Select the Artifact
+
+**Check LBC:** `LightningModal` exists in the [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components). Use it.
+
+**Also search blueprints** (for class reference):
+
+```bash
+node scripts/search-blueprints.cjs --search "modal"
+# Found: Modals (category: Overlay, root: slds-modal)
+```
+
+**Read blueprint YAML** for class details: `metadata/blueprints/components/modals.yaml`
+
+Key takeaway: `LightningModal` handles the `slds-modal`, `slds-backdrop`, and ARIA attributes automatically. No need to apply blueprint classes manually in LWC.
+
+### Phase 3: Apply Styling
+
+**Read:** `references/styling-decision-guide.md`
+
+The destructive action button needs error color to signal danger:
+
+```bash
+node scripts/search-hooks.cjs --prefix "--slds-g-color-error-"
+# Found: --slds-g-color-error-1 (#ea001e), --slds-g-color-on-error-1 (#ffffff)
+```
+
+**Result:** Use `variant="destructive"` on `lightning-button` inside the modal footer. The LBC handles the correct SLDS color hooks internally.
+
+For the modal body spacing, use utility classes:
+
+```html
+<div class="slds-p-around_medium slds-text-align_center">
+  <p>Are you sure you want to delete this record?</p>
+</div>
+```
+
+### Phase 4: Add Icons
+
+**Search:** `node scripts/search-icons.cjs --query "warning"`
+
+```
+Found: utility:warning (score: 100, match: exact)
+```
+
+```html
+<lightning-icon
+    icon-name="utility:warning"
+    alternative-text="Warning"
+    variant="error"
+    size="small"
+    class="slds-m-right_x-small">
+</lightning-icon>
+```
+
+### Phase 5: Validate (checklists.md)
+
+- No hardcoded colors (using LBC variants + hooks)
+- Icon has `alternative-text`
+- Spacing uses utility classes (`slds-p-around_medium`, `slds-m-right_x-small`)
+- No `.slds-*` overrides
+
+---
+
+## Example 2: Styled Card with Status Badge (Non-LWC)
+
+### Phase 1: Understand the Need
+
+- **Pattern:** A card showing a record with a colored status badge
+- **Framework:** React (not LWC -- no LBCs available)
+- **States:** Active, inactive, pending
+
+### Phase 2: Select the Artifact
+
+**LBC check:** Not applicable (React).
+
+**Search blueprints:**
+
+```bash
+node scripts/search-blueprints.cjs --search "card"
+# Found: Cards (category: Layout, root: slds-card)
+
+node scripts/search-blueprints.cjs --search "badge"
+# Found: Badges (category: Feedback, root: slds-badge)
+```
+
+**Read YAMLs:**
+- `metadata/blueprints/components/cards.yaml` -- classes: `slds-card`, `slds-card__header`, `slds-card__body`, `slds-card__footer`
+- `metadata/blueprints/components/badges.yaml` -- classes: `slds-badge`, modifiers: `slds-badge_lightest`, `slds-badge_inverse`
+
+### Phase 3: Apply Styling
+
+**Read:** `references/styling-decision-guide.md`
+
+Card background and text use surface hooks. The status is conveyed by badge text plus a custom status accent on the card, rather than invented badge modifiers.
+
+```html
+<article class="slds-card my-status-card">
+  <div class="slds-card__header slds-grid">
+    <header class="slds-media slds-media_center slds-has-flexi-truncate">
+      <div class="slds-media__body">
+        <h2 class="slds-card__header-title slds-truncate">Account Name</h2>
+      </div>
+      <div class="slds-no-flex">
+        <span class="slds-badge slds-badge_lightest">Active</span>
+      </div>
+    </header>
+  </div>
+  <div class="slds-card__body slds-card__body_inner">
+    <p>Record details here</p>
+  </div>
+</article>
+```
+
+Custom styling for a subtle card border:
+
+```css
+.my-status-card {
+  border-left: 3px solid var(--slds-g-color-accent-1, #0176d3);
+}
+```
+
+Note: custom class uses `my-*` prefix, hook with fallback, no `.slds-*` overrides.
+
+### Phase 4: Add Icons
+
+**Search for a standard object icon:**
+
+```bash
+node scripts/search-icons.cjs --query "account" --category "standard"
+# Found: standard:account (score: 100, match: exact)
+```
+
+In React (non-LWC), use the SVG blueprint pattern:
+
+```html
+<span class="slds-icon_container slds-icon-standard-account" title="Account">
+  <svg class="slds-icon slds-icon_small" aria-hidden="true">
+    <use xlinkHref="/assets/icons/standard-sprite/svg/symbols.svg#account"></use>
+  </svg>
+  <span class="slds-assistive-text">Account</span>
+</span>
+```
+
+### Phase 5: Validate
+
+- Card uses exact blueprint classes (`slds-card`, `slds-card__header`, etc.)
+- Badge uses a real blueprint modifier (`slds-badge_lightest`), not an invented status variant
+- Custom border uses `my-*` prefix and hook with fallback
+- Icon uses `slds-assistive-text` for accessibility
+- No hardcoded colors
+
+---
+
+## Example 3: Responsive Data Layout with Hooks
+
+### Phase 1: Understand the Need
+
+- **Pattern:** A responsive grid of metric cards
+- **Framework:** LWC
+- **States:** Loading (spinner), populated, empty (illustration)
+
+### Phase 2: Select the Artifact
+
+**LBC:** `lightning-card` for each metric card. `lightning-spinner` for loading.
+
+**Search for empty state:**
+
+```bash
+node scripts/search-blueprints.cjs --search "illustration"
+# Found: Illustration (category: Media, root: slds-illustration)
+```
+
+### Phase 3: Apply Styling
+
+**Verify grid and spacing utilities** before using them:
+
+```bash
+node scripts/search-utilities.cjs --search "slds-grid"
+# Found: slds-grid (category: grid, css: display: flex)
+
+node scripts/search-utilities.cjs --search "slds-text-heading_large"
+# Found: slds-text-heading_large (category: typography)
+
+node scripts/search-utilities.cjs --search "slds-text-body_small"
+# Found: slds-text-body_small (category: typography)
+```
+
+**Grid layout** uses utility classes (see `references/utilities-quick-ref.md`):
+
+```html
+<div class="slds-grid slds-wrap slds-gutters">
+  <template for:each={metrics} for:item="metric">
+    <div key={metric.id} class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2 slds-large-size_1-of-3">
+      <lightning-card title={metric.label}>
+        <div class="slds-p-horizontal_small">
+          <p class="slds-text-heading_large">{metric.value}</p>
+          <p class="slds-text-body_small slds-text-color_weak">{metric.subtitle}</p>
+        </div>
+      </lightning-card>
+    </div>
+  </template>
+</div>
+```
+
+**Custom metric styling** with hooks:
+
+```css
+.my-metric-value {
+  font-size: var(--slds-g-font-scale-6, 2rem);
+  font-weight: var(--slds-g-font-weight-7, 700);
+  color: var(--slds-g-color-on-surface-3, #181818);
+}
+
+.my-metric-trend-up {
+  color: var(--slds-g-color-success-1, #2e844a);
+}
+
+.my-metric-trend-down {
+  color: var(--slds-g-color-error-1, #ea001e);
+}
+```
+
+Note: trend colors use semantic feedback hooks (success/error), not hardcoded green/red.
+
+**Empty state** uses the SLDS illustration blueprint:
+
+```html
+<template if:false={hasData}>
+  <div class="slds-illustration slds-illustration_small">
+    <img src="/img/chatter/Desert.svg" class="slds-illustration__svg" alt="" />
+    <div class="slds-text-longform">
+      <h3 class="slds-text-heading_medium">No metrics available</h3>
+      <p class="slds-text-body_regular">Check back when data is loaded.</p>
+    </div>
+  </div>
+</template>
+```
+
+### Phase 4: Add Icons
+
+Trend indicators need icons:
+
+```bash
+node scripts/search-icons.cjs --query "arrow up"
+# Found: utility:arrowup (score: 100)
+
+node scripts/search-icons.cjs --query "arrow down"
+# Found: utility:arrowdown (score: 100)
+```
+
+```html
+<lightning-icon
+    icon-name={metric.trendIcon}
+    alternative-text={metric.trendLabel}
+    size="xx-small"
+    class="slds-m-left_xx-small">
+</lightning-icon>
+```
+
+### Phase 5: Validate
+
+- Grid uses `slds-grid` + `slds-col` + responsive `slds-*-size_*` classes
+- Spacing uses utilities (`slds-p-horizontal_small`, `slds-m-left_xx-small`)
+- Typography uses utilities (`slds-text-heading_large`, `slds-text-body_small`)
+- Custom CSS uses `my-*` prefix and hooks with fallbacks
+- Trend colors use semantic hooks (success/error), not hardcoded values
+- Empty state uses SLDS illustration blueprint
+- Icons have `alternative-text`