@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/applying-slds/references/component-selection.md

@@ -0,0 +1,112 @@
+# Component & Blueprint Selection
+
+How to find the right SLDS artifact for a UI pattern.
+
+---
+
+## Decision Flow
+
+```
+What framework?
+├─ LWC → Check Lightning Base Component (LBC) first
+│   ├─ LBC exists → Use it. Done.
+│   └─ No LBC → Fall through to SLDS Blueprint
+├─ React / Vue / Angular / vanilla → Skip LBC, go to SLDS Blueprint
+└─ Any framework → No blueprint match? → Build custom with styling hooks
+```
+
+## Step 1: Check for LBC (LWC only)
+
+Lightning Base Components are pre-built, accessible, themed LWC components.
+
+**Always check first:** [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components)
+
+Common LBCs and their use cases:
+
+| Component | Use Case |
+|-----------|----------|
+| `lightning-button` | All button actions |
+| `lightning-input` | Text, email, number, date inputs |
+| `lightning-combobox` | Dropdown selection |
+| `lightning-datatable` | Tabular data with sorting/selection |
+| `lightning-card` | Content containers |
+| `lightning-modal` | Dialog overlays |
+| `lightning-icon` | SLDS icons |
+| `lightning-layout` | Responsive grid layout |
+
+If an LBC exists, use it. Do not build a custom version from blueprint markup.
+
+## Step 2: Search SLDS Blueprints
+
+Blueprints are HTML/CSS patterns that work in any framework. Use when no LBC exists or when not building in LWC.
+
+### How to search
+
+```bash
+# Keyword search
+node scripts/search-blueprints.cjs --search "dialog"
+
+# Browse by category
+node scripts/search-blueprints.cjs --category "Overlay"
+
+# Get full details for a specific blueprint
+node scripts/search-blueprints.cjs --name "modals"
+```
+
+### Blueprint categories
+
+| Category | Examples |
+|----------|----------|
+| Layout | Cards, Tiles, Page Headers |
+| Forms | Input, Select, Combobox, Checkbox, Radio, Textarea |
+| Navigation | Tabs, Vertical Navigation, Breadcrumbs, Path |
+| Data Display | Data Tables, Trees, Activity Timeline |
+| Feedback | Alert, Toast, Scoped Notifications, Spinners |
+| Overlay | Modals, Popovers, Tooltips, Prompt |
+| Media | Avatar, Carousel, Files, Illustration |
+| Actions | Buttons, Button Groups, Button Icons, Menus |
+
+### How to read a blueprint YAML
+
+Each file in `metadata/blueprints/components/{name}.yaml` contains:
+
+```yaml
+name: "Modals"
+description: "Dialog overlays..."
+category: "Overlay"
+slds_classes:
+  root: "slds-modal"            # The BEM root class to apply
+  elements:                     # Child element classes
+    - class: "slds-modal__header"
+      purpose: "Contains title and close action"
+  modifiers:                    # Size/style variants
+    - class: "slds-modal_large"
+      usage: "For complex forms or detailed content"
+  states:                       # State classes
+    - class: "slds-fade-in-open"
+accessibility:                  # Required ARIA attributes
+  roles: ["dialog"]
+  attributes: ["aria-modal", "aria-labelledby"]
+example_html: "..."             # Reference markup
+```
+
+Use the `root` class, add `elements` for structure, `modifiers` for variants, and follow `accessibility` requirements.
+
+## Step 3: Custom with Styling Hooks
+
+If no LBC or blueprint matches your need, build custom markup with SLDS styling hooks.
+
+See [styling-decision-guide.md](styling-decision-guide.md) for how to apply hooks correctly.
+
+Rules for custom components:
+- Use custom class prefixes (`my-*`, `c-*`) -- never override `slds-*` classes
+- Use `var(--slds-g-*, fallback)` for all themeable values
+- Follow the blueprint naming pattern (BEM-like) for consistency
+
+---
+
+## Deep Reference
+
+- Full blueprint details: `guidance/blueprints-index.md`
+- All blueprint YAMLs: `metadata/blueprints/components/`
+- LBC documentation: [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components)

package/skills/applying-slds/references/icons-decision-guide.md

@@ -0,0 +1,124 @@
+# 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`

package/skills/applying-slds/references/styling-decision-guide.md

@@ -0,0 +1,228 @@
+# Styling Decision Guide
+
+How to apply SLDS styling correctly using hooks, utilities, and custom CSS.
+
+---
+
+## Styling Hook Hierarchy
+
+SLDS hooks follow a three-tier naming system:
+
+| Tier | Prefix | Use |
+|------|--------|-----|
+| **Global Semantic** | `--slds-g-*` | System-wide. Use these by default. |
+| **Shared** | `--slds-s-*` | Private/internal. **DO NOT USE.** Reserved for Salesforce. |
+| **Component** | `--slds-c-*` | Scoped to specific LBCs. Use to customize LBC appearance. |
+
+**Rule: Always use `--slds-g-*` hooks unless `--slds-c-*` hooks exist for your specific LBC.**
+
+### Discovering `--slds-c-*` Hooks
+
+Component hooks are scoped to specific Lightning Base Components. To find available hooks for an LBC:
+
+1. **Inspect the LBC docs**: Check the component's [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components) page — look for "Styling Hooks" or "Custom Properties" sections
+2. **Browser DevTools**: Render the LBC, inspect the element, and look for `--slds-c-*` properties in the computed styles
+3. **Known patterns**: Component hooks follow `--slds-c-{component}-{property}-{state}` naming, e.g., `--slds-c-button-success-shadow-hover`
+
+There is no centralized metadata file for `--slds-c-*` hooks — they are documented per-component. Some examples exist in `guidance/overviews/shadows.md` and `guidance/styling-hooks/index.md`.
+
+---
+
+## Hook Syntax
+
+Always use `var()` with a fallback value:
+
+```css
+.my-card {
+  background: var(--slds-g-color-surface-1, #ffffff);
+  padding: var(--slds-g-spacing-4, 1rem);
+  border-radius: var(--slds-g-radius-border-2, 0.25rem);
+}
+```
+
+**Never reassign hook values.** Salesforce controls them and can change them.
+
+### Choosing Fallback Values
+
+The fallback in `var(--slds-g-*, fallback)` is used when the hook isn't loaded (e.g., outside Lightning Experience, in static HTML previews, or during SSR). Use the **light-mode default** value:
+
+1. **Look up the value in `metadata/hooks-index.json`** — each hook has a `value` field showing its resolved default
+2. **Use the search script**: `node scripts/search-hooks.cjs --prefix "--slds-g-color-surface-"` shows values
+3. **Common defaults**: `#ffffff` for surfaces, `#181818` for text, `1rem` for spacing-4, `0.25rem` for radius-border-2
+
+Always use the light-mode default. Dark-mode values are applied automatically when the hook is active — the fallback only matters when hooks aren't loaded at all.
+
+---
+
+## Color: The 85-5-10 Rule
+
+All SLDS UIs should maintain this approximate color distribution:
+
+| % | Role | What to use |
+|---|------|-------------|
+| **85%** | Foundation | Surfaces, backgrounds, containers. Neutral colors: whites, grays. Hooks: `--slds-g-color-surface-*` |
+| **5%** | Accents | Primary actions, selected states, key CTAs. Hooks: `--slds-g-color-accent-*` |
+| **10%** | Expressive | Data viz, custom branding. Use sparingly. Hooks: `--slds-g-color-palette-*` |
+
+### Color Role Selection
+
+Before picking a hook, classify what the color is for:
+
+| Role | Hook prefix | Examples |
+|------|-------------|----------|
+| Surface (backgrounds) | `--slds-g-color-surface-*` | Page bg, modal bg, top-level panels |
+| Surface container (nested surfaces) | `--slds-g-color-surface-container-*` | Card bg, embedded panels, list items |
+| On-surface (text on surfaces) | `--slds-g-color-on-surface-*` | Body text, headings, icons |
+| Accent (emphasis) | `--slds-g-color-accent-*` | Primary emphasis, selected state text/icons |
+| Accent container (accent backgrounds) | `--slds-g-color-accent-container-*` | Buttons, selected tabs, emphasized controls |
+| Border | `--slds-g-color-border-*` | Dividers, card borders |
+| Error | `--slds-g-color-error-*` | Validation errors |
+| Success | `--slds-g-color-success-*` | Confirmation states |
+| Warning | `--slds-g-color-warning-*` | Caution messages |
+
+**Always pair surfaces with on-surfaces.** Example: `surface-1` background + `on-surface-2` text.
+
+**CRITICAL:** All color hooks require a numbered variant. There is no unnumbered base form (e.g., `--slds-g-color-on-surface` does not exist -- use `on-surface-1`, `-2`, or `-3`):
+
+| Variant | Emphasis | Use for |
+|---------|----------|---------|
+| `-1` | Low | Captions, placeholder text, de-emphasized content |
+| `-2` | Medium | Body text, labels, standard content |
+| `-3` | High | Page titles, headings, primary emphasis |
+
+### How to search hooks
+
+```bash
+# By prefix
+node scripts/search-hooks.cjs --prefix "--slds-g-color-surface-"
+
+# By category
+node scripts/search-hooks.cjs --category "color"
+
+# By CSS property
+node scripts/search-hooks.cjs --property "background-color"
+
+# Find hook for a hardcoded value
+node scripts/search-hooks.cjs --value "#0176d3"
+```
+
+---
+
+## Spacing: 4-Point Grid
+
+SLDS uses a numbered scale, not named sizes:
+
+| Hook | Value | Pixels | Use for |
+|------|-------|--------|---------|
+| `--slds-g-spacing-1` | 0.25rem | 4px | Tight inline spacing |
+| `--slds-g-spacing-2` | 0.5rem | 8px | Between related items |
+| `--slds-g-spacing-3` | 0.75rem | 12px | Small gaps |
+| `--slds-g-spacing-4` | 1rem | 16px | Standard padding/margin |
+| `--slds-g-spacing-5` | 1.5rem | 24px | Section gaps |
+| `--slds-g-spacing-6` | 2rem | 32px | Between sections |
+| `--slds-g-spacing-8` | 3rem | 48px | Large separations |
+| `--slds-g-spacing-12` | 5rem | 80px | Page-level spacing |
+
+---
+
+## Typography Hooks (Naming Exception)
+
+Typography hooks break from the `{prefix}-{number}` pattern used by spacing and color:
+
+| Hook | Pattern | Use |
+|------|---------|-----|
+| `--slds-g-font-size-base` | Single value | Base application font size (13px / 0.8125rem) |
+| `--slds-g-font-scale-*` | Numbered scale | All other sizes: `font-scale-1` (14px) through `font-scale-10` |
+| `--slds-g-font-scale-neg-*` | Negative scale | Smaller sizes: `font-scale-neg-1` through `neg-4` |
+| `--slds-g-font-scale-var-*` | Density-aware | Adapts to compact/comfy display density settings |
+
+**Common mappings:**
+
+| Size | Hook | Approximate value |
+|------|------|-------------------|
+| Small body text | `--slds-g-font-scale-neg-1` | 12px |
+| Default body | `--slds-g-font-size-base` | 13px |
+| Larger body | `--slds-g-font-scale-1` | 14px |
+| Subheading | `--slds-g-font-scale-2` | 16px |
+| Heading | `--slds-g-font-scale-4` | 20px |
+| Page title | `--slds-g-font-scale-6` | 28px |
+| Display | `--slds-g-font-scale-8` | 40px |
+
+**CRITICAL:** `--slds-g-font-size-3`, `--slds-g-font-size-4`, etc. do NOT exist. Only `--slds-g-font-size-base` is valid. For numbered sizes, use `--slds-g-font-scale-*`.
+
+---
+
+## When Hooks Don't Exist
+
+Not all CSS properties have styling hooks. Not all values have hook equivalents either (e.g., `min-width: 7rem` for label alignment). Use this decision tree:
+
+```
+Does a hook exist for this property?
+├─ YES → Use it: var(--slds-g-*, fallback)
+├─ NO → Is there a utility class?
+│       ├─ YES → Use the utility class
+│       └─ NO → Use minimal custom CSS with:
+│               1. Custom class prefix (my-*, c-*)
+│               2. Use hooks for related values (e.g., hook colors in gradients)
+│               3. Document why no hook/utility exists
+```
+
+**Properties without hooks (use custom CSS):**
+- `transform`, `transition` (use `--slds-g-duration-*` for timing only)
+- `z-index` (use SLDS utility classes when possible)
+- `cursor`, `overflow`
+- Complex gradients (use hook colors within gradient syntax)
+
+**Values without hook equivalents (acceptable hardcoding):**
+
+Some dimension values have no SLDS hook (e.g., `min-width: 7rem` for label alignment, `max-height: 20rem` for scrollable panels). This is acceptable when:
+1. No SLDS sizing hook or utility class covers the value
+2. A comment explains the value is intentional
+3. SLDS grid utilities (`slds-size_*`) were considered as alternatives
+
+```css
+.c-field-label {
+  /* No SLDS hook exists for this width; intentional for label alignment */
+  min-width: 7rem;
+}
+```
+
+**Example -- gradient with hook colors:**
+```css
+.my-gradient-bg {
+  background: linear-gradient(
+    to bottom,
+    var(--slds-g-color-surface-1, #ffffff),
+    var(--slds-g-color-surface-2, #f3f3f3)
+  );
+}
+```
+
+---
+
+## Hook vs. Utility vs. Custom CSS
+
+| Need | First choice | Fallback |
+|------|-------------|----------|
+| Color (bg, text, border) | Hook: `var(--slds-g-color-*)` | -- |
+| Spacing (margin, padding) | Utility: `slds-m-*`, `slds-p-*` | Hook: `var(--slds-g-spacing-*)` |
+| Layout (grid, columns) | Utility: `slds-grid`, `slds-col` | -- |
+| Typography (size) | Hook: `var(--slds-g-font-scale-*)` or `var(--slds-g-font-size-base)` | Utility: `slds-text-*` |
+| Typography (weight) | Hook: `var(--slds-g-font-weight-*)` | -- |
+| Visibility (show/hide) | Utility: `slds-hide`, `slds-show` | -- |
+| Borders (width, radius) | Hook: `var(--slds-g-radius-*)` | Utility: `slds-border-*` |
+| Shadows | Hook: `var(--slds-g-shadow-*)` | -- |
+| Anything else | Custom CSS with custom class prefix | Use hook values where possible |
+
+---
+
+## Deep Reference
+
+- Styling hooks index: `guidance/styling-hooks/index.md`
+- Color hooks deep dive: `guidance/styling-hooks/color/`
+- Color overview (85-5-10 rule): `guidance/overviews/color.md`
+- Spacing overview: `guidance/overviews/spacing.md`
+- Typography hooks: `guidance/styling-hooks/typography.md`
+- Borders overview: `guidance/overviews/borders.md`
+- Shadows overview: `guidance/overviews/shadows.md`
+- All 523 hooks searchable: `metadata/hooks-index.json`

package/skills/applying-slds/references/utilities-quick-ref.md

@@ -0,0 +1,125 @@
+# Utilities Quick Reference
+
+SLDS utility classes for rapid styling. 1,147 classes across 27 categories.
+
+---
+
+## When to Use Utilities vs. Hooks
+
+| Need | Use utility class | Use hook |
+|------|------------------|----------|
+| Margin/padding | `slds-m-bottom_medium`, `slds-p-around_small` | `var(--slds-g-spacing-4)` in custom CSS |
+| Grid layout | `slds-grid`, `slds-col`, `slds-size_*` | -- |
+| Visibility | `slds-hide`, `slds-show_*` | -- |
+| Text styling | `slds-text-heading_medium` | `var(--slds-g-font-*)` |
+| Borders | `slds-border_bottom` | `var(--slds-g-color-border-*)` |
+| Colors | `slds-theme_*` | `var(--slds-g-color-*)` |
+
+**Prefer utility classes for layout and spacing in markup.** Use hooks in custom CSS for colors, typography values, and dynamic theming.
+
+---
+
+## Most-Used Categories
+
+### Grid (`slds-grid`, 80 classes)
+
+```html
+<div class="slds-grid slds-wrap slds-gutters">
+  <div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2 slds-large-size_1-of-3">
+    <!-- Column content -->
+  </div>
+</div>
+```
+
+Key classes:
+- `slds-grid` -- flex container
+- `slds-wrap` -- allow wrapping
+- `slds-gutters` -- column spacing
+- `slds-col` -- flex column
+- `slds-size_1-of-N` -- fractional width (1-of-1 through 1-of-12)
+- `slds-medium-size_*`, `slds-large-size_*` -- responsive breakpoints
+- `slds-grid_vertical` -- column direction
+- `slds-grid_align-center` -- center alignment
+
+### Margin (`slds-m-*`, 119 classes)
+
+Pattern: `slds-m-{direction}_{size}`
+
+| Direction | Class pattern |
+|-----------|--------------|
+| All | `slds-m-around_*` |
+| Top | `slds-m-top_*` |
+| Bottom | `slds-m-bottom_*` |
+| Left | `slds-m-left_*` |
+| Right | `slds-m-right_*` |
+| Vertical | `slds-m-vertical_*` |
+| Horizontal | `slds-m-horizontal_*` |
+
+Sizes: `none`, `xxx-small`, `xx-small`, `x-small`, `small`, `medium`, `large`, `x-large`, `xx-large`
+
+### Padding (`slds-p-*`, 120 classes)
+
+Same pattern as margin: `slds-p-{direction}_{size}`
+
+### Sizing (`slds-size_*`, 613 classes)
+
+Fractional widths for columns and elements:
+- `slds-size_1-of-2` -- 50%
+- `slds-size_1-of-3` -- 33.3%
+- `slds-size_2-of-3` -- 66.6%
+- `slds-size_1-of-4` -- 25%
+- `slds-size_full` -- 100%
+
+Responsive: `slds-small-size_*`, `slds-medium-size_*`, `slds-large-size_*`
+
+### Typography (`slds-text-*`, 24 classes)
+
+- `slds-text-heading_large` -- large heading
+- `slds-text-heading_medium` -- medium heading
+- `slds-text-heading_small` -- small heading
+- `slds-text-body_regular` -- body text
+- `slds-text-body_small` -- small body text
+- `slds-text-title` -- uppercase label
+- `slds-text-color_default` -- default text color
+- `slds-text-color_weak` -- secondary text color
+
+### Visibility
+
+- `slds-hide` -- hide element (`display: none`)
+- `slds-show` -- show element (`display: block`)
+- `slds-show_inline` -- show inline
+- `slds-hidden` -- hidden via `visibility: hidden`; occupies space and is not a screen-reader helper
+- `slds-assistive-text` -- screen-reader only text
+
+Use `slds-assistive-text`, not `slds-hidden`, when content should remain available to assistive technology.
+
+### Truncation
+
+- `slds-truncate` -- single-line truncation with ellipsis
+- `slds-line-clamp_*` -- multi-line truncation (2, 3, 4, 5 lines)
+
+---
+
+## How to Search
+
+```bash
+# Browse all categories
+node scripts/search-utilities.cjs --category "all"
+
+# Browse a specific category
+node scripts/search-utilities.cjs --category "grid"
+
+# Search by class name
+node scripts/search-utilities.cjs --search "slds-m-bottom"
+
+# Wildcard pattern
+node scripts/search-utilities.cjs --pattern "slds-p-around_*"
+```
+
+---
+
+## Deep Reference
+
+- Utility index: `guidance/utilities/index.md`
+- Individual category guides: `guidance/utilities/{category}.md`
+- Full metadata (1,147 classes): `metadata/utilities-index.json`