@salesforce/afv-skills 1.13.0 → 1.15.0

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`

package/skills/applying-slds/guidance/README.md

@@ -0,0 +1,83 @@
+# Bundled Guidance Index
+
+Source: `packages/guidance/` -- SLDS domain knowledge for deep reference.
+
+Read these files when the workflow phases in SKILL.md point you here. The Knowledge Map in SKILL.md tells you which file to read for each task.
+
+---
+
+## Root Files
+
+| File | Read When | Description |
+|------|-----------|-------------|
+| `slds-development-guide.md` | Need comprehensive SLDS development patterns | Full development guide -- component hierarchy, framework patterns, code generation rules. SKILL.md has the core; this is the deep reference. |
+| `blueprints-index.md` | Selecting a blueprint component | All SLDS blueprints mapped to categories and LBC equivalents |
+| `icons-guidance.md` | Implementing icons | Icon implementation patterns, categories, accessibility |
+
+## Overviews (`overviews/`)
+
+Foundational concepts for each SLDS domain. Read when you need to understand the rules behind a domain before using specific hooks or utilities.
+
+| File | Read When | Description |
+|------|-----------|-------------|
+| `color.md` | Making any color decision | 85-5-10 density rule, color role taxonomy, hook selection hierarchy, numerical color system |
+| `spacing.md` | Setting spacing or sizing | 4-point spacing grid, semantic sizing scale, spacing-to-hook mappings |
+| `typography.md` | Setting fonts, sizes, weights | Typography scale, heading hierarchy, font family hooks |
+| `shadows.md` | Adding elevation or depth | Shadow levels, elevation system, when to use which shadow |
+| `borders.md` | Adding borders or dividers | SLDS 2 minimal-border philosophy, border hooks and utility classes |
+| `display-density.md` | Supporting comfy/compact modes | Display density utility patterns, density-responsive components |
+| `illustrations.md` | Showing empty/error/info states | SLDS illustration markup, when to use which illustration |
+| `icons.md` | Understanding icon system | Icon categories overview, sprite structure, sizing conventions |
+| `utilities.md` | Understanding utility class system | Utility class philosophy, naming patterns, when to use utilities vs. hooks |
+
+## Styling Hooks (`styling-hooks/`)
+
+CSS custom property guidance. Read when applying `--slds-g-*`, `--slds-s-*`, or `--slds-c-*` hooks.
+
+| File | Read When | Description |
+|------|-----------|-------------|
+| `index.md` | Starting any styling hooks work | Entry point: three-tier hierarchy (global/shared/component), core categories, decision trees |
+| `color/index.md` | Working with color hooks | Color hook organization, palettes, selection hierarchy |
+| `color/system-hooks.md` | Need system-level color hooks | Low-level palette hooks (`--slds-g-color-palette-*`) |
+| `color/expressive-palette-hooks.md` | Need expressive/brand colors | Expressive palette hooks for brand-aligned color usage |
+| `color/semantic/accent-hooks.md` | Need accent/brand colors | `--slds-g-color-accent-*` hooks for interactive and brand elements |
+| `color/semantic/feedback-hooks.md` | Need success/warning/error colors | `--slds-g-color-error-*`, `--slds-g-color-success-*`, `--slds-g-color-warning-*` |
+| `color/semantic/surface-hooks.md` | Need surface/background colors | `--slds-g-color-surface-*` and `--slds-g-color-on-surface-*` for surfaces and text |
+| `typography.md` | Setting typography with hooks | Typography hooks: font-family, font-size, font-weight, line-height |
+| `spacing.md` | Setting spacing/sizing with hooks | Spacing hooks: `--slds-g-spacing-*`, sizing hooks |
+| `borders.md` | Setting borders with hooks | Border hooks: width, color, radius |
+| `shadows.md` | Setting shadows with hooks | Shadow hooks: `--slds-g-shadow-*` levels |
+
+## Utilities (`utilities/`)
+
+Individual utility class categories. Read when you need specific classes for a layout or styling task.
+
+| File | Read When | Description |
+|------|-----------|-------------|
+| `index.md` | Need utility class overview | All 26 categories with class counts and common patterns |
+| `grid.md` | Building grid layouts | `slds-grid`, `slds-col`, `slds-size_*`, responsive sizing |
+| `margin.md` | Adding margin | `slds-m-*` margin utilities by direction and size |
+| `padding.md` | Adding padding | `slds-p-*` padding utilities by direction and size |
+| `sizing.md` | Setting widths | `slds-size_*` fractional and absolute width utilities |
+| `layout.md` | Page-level layout | Page layout containers and regions |
+| `alignment.md` | Aligning content | Flex alignment, text alignment, vertical centering |
+| `borders.md` | Adding border utilities | Border direction, radius, and removal utilities |
+| `box.md` | Box model utilities | Box-sizing, overflow, display utilities |
+| `color.md` | Color utility classes | Text and background color utilities |
+| `dark-mode.md` | Dark mode support | Dark mode utility classes and patterns |
+| `description-list.md` | Description lists | `dl`/`dt`/`dd` styling utilities |
+| `floats.md` | Float layout | Float and clearfix utilities |
+| `horizontal-list.md` | Horizontal lists | Inline list layout utilities |
+| `hyphenation.md` | Word breaking | Hyphenation and word-break utilities |
+| `interactions.md` | Pointer/cursor styles | Interaction and cursor utilities |
+| `line-clamp.md` | Text line limiting | Line clamping utilities |
+| `media-object.md` | Media object pattern | Figure + body layout utilities |
+| `name-value-list.md` | Name-value pairs | Key-value display utilities |
+| `position.md` | Positioning | Position, z-index, and sticky utilities |
+| `print.md` | Print styles | Print-specific visibility and layout |
+| `scrollable.md` | Scroll containers | Scrollable area utilities |
+| `themes.md` | Theme containers | Theme override container utilities |
+| `truncate.md` | Text truncation | Ellipsis and text truncation |
+| `typography.md` | Text styling | Font size, weight, alignment utilities |
+| `vertical-list.md` | Vertical lists | Stacked list layout utilities |
+| `visibility.md` | Show/hide elements | Responsive and state visibility utilities |

package/skills/applying-slds/guidance/blueprints-index.md

@@ -0,0 +1,213 @@
+---
+id: slds.guidance.blueprints
+title: SLDS Blueprints Index
+description: Complete index of SLDS blueprints by category with Lightning component mapping
+summary: "Index of SLDS blueprints across 9 categories (Actions, Input, Layout, Navigation, Display, Data, Feedback, Overlay, Complex Components). Covers when to use blueprints vs Lightning Base Components."
+
+artifact_type: index
+domain: blueprints
+topic: blueprints
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, learn]
+
+refs:
+  - slds.guidance.development
+  - slds.guidance.design
+  - slds.guidance.icons
+
+tags: [blueprints, components, html, css, implementation]
+keywords: [SLDS blueprints, component implementation, HTML structure, CSS classes, Lightning components, custom components]
+---
+
+# SLDS Blueprints Index
+
+## Overview
+
+Blueprints provide HTML structure, CSS classes, ARIA requirements, and code examples for each SLDS component. Each blueprint includes:
+
+- **HTML structure**: Element hierarchy and required markup
+- **CSS classes**: Root, element, modifier, size, and state classes
+- **Styling hooks**: CSS custom properties for theming
+- **Accessibility**: ARIA attributes, keyboard patterns, screen reader guidance
+- **Code examples**: Usage examples for variants
+- **Lightning component mapping**: Corresponding LWC when available
+
+**Use blueprints** when building custom HTML/CSS, targeting non-Salesforce platforms, or when no Lightning Base Component exists.
+
+**Use Lightning Base Components** when working within Salesforce (LWC, Aura, Visualforce) — they handle accessibility, events, and framework integration automatically.
+
+---
+
+## Blueprints by Category
+
+### Actions
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Buttons** | Action triggers with text labels | `lightning-button` |
+| **Button Icons** | Icon-only action triggers | `lightning-button-icon` |
+| **Button Groups** | Related buttons in a row | `lightning-button-group` |
+| **Docked Utility Bar** | Persistent bottom utility panel | N/A |
+
+---
+
+### Input
+
+Form controls for user input and data entry.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Checkbox** | Binary selection control | `lightning-checkbox` |
+| **Checkbox Button** | Checkbox styled as a button | `lightning-checkbox-button` |
+| **Checkbox Button Group** | Set of checkbox buttons in a fieldset | `lightning-checkbox-group` |
+| **Checkbox Toggle** | Toggle-style checkbox | `lightning-input` (type="checkbox-button") |
+| **Combobox** | Text input with dropdown list | `lightning-combobox` |
+| **Counter** | Number input with increment/decrement controls | N/A |
+| **Datepickers** | Calendar date selection | `lightning-input` (type="date") |
+| **Datetime Picker** | Combined date and time selection | `lightning-input` (type="datetime") |
+| **Dueling Picklist** | Multi-select with two lists | `lightning-dual-listbox` |
+| **Expression** | Formula builder interface | N/A |
+| **File Selector** | File upload with drag-and-drop | `lightning-file-upload` |
+| **Form Element** | Wrapper for form inputs | N/A |
+| **Input** | Text/number input | `lightning-input` |
+| **Lookups** | Search and select from a dataset | `lightning-record-picker` |
+| **Picklist** | Dropdown from predefined options | `lightning-combobox` |
+| **Radio Group** | Single selection from exclusive options | `lightning-radio-group` |
+| **Radio Button Group** | Radio buttons in a styled group | `lightning-radio-group` |
+| **Rich Text Editor** | Text editor with formatting toolbar | `lightning-input-rich-text` |
+| **Select** | Native dropdown selection | `lightning-combobox` |
+| **Slider** | Numeric range input via draggable handle | `lightning-slider` |
+| **Textarea** | Multi-line text input | `lightning-textarea` |
+| **Timepicker** | Time selection interface | `lightning-input` (type="time") |
+| **Visual Picker** | Visual tile-based selection | `lightning-radio-group` (with tiles) |
+
+---
+
+### Layout
+
+Components for organizing and structuring content.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Accordion** | Collapsible stacked sections | `lightning-accordion` |
+| **Brand Band** | Visual header with branding | N/A |
+| **Builder Header** | Header for app builder interfaces | N/A |
+| **Cards** | Container with header/body/footer | `lightning-card` |
+| **Carousel** | Slideshow with navigation controls | `lightning-carousel` |
+| **Docked Form Footer** | Fixed bottom footer for form actions | N/A |
+| **Expandable Section** | Collapsible content block | N/A |
+| **Page Headers** | Page title, metadata, and actions | `lightning-record-view-form` |
+| **Panels** | Structured side or overlay container | N/A |
+| **Split View** | Resizable two-pane layout | N/A |
+| **Summary Detail** | Collapsible key-value layout | N/A |
+| **Tiles** | Card-like grid content items | `lightning-tile` |
+
+---
+
+### Navigation
+
+Components for navigation and wayfinding.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **App Launcher** | Grid for app discovery | N/A |
+| **Breadcrumbs** | Hierarchical location trail | `lightning-breadcrumbs` |
+| **Dynamic Menu** | Contextual menu in popover | N/A |
+| **Global Header** | Primary application header | N/A |
+| **Global Navigation** | Main navigation bar | `lightning-navigation` |
+| **Menus** | Contextual action lists | `lightning-menu-item` |
+| **Path** | Linear process stage indicator | `lightning-path` |
+| **Scoped Tabs** | Tabs scoped to a context | `lightning-tabset` |
+| **Tabs** | Switchable content panels | `lightning-tabset` |
+| **Trees** | Hierarchical list | `lightning-tree` |
+| **Vertical Navigation** | Vertical nav menu | `lightning-vertical-navigation` |
+| **Vertical Tabs** | Vertical tab interface | `lightning-vertical-navigation` |
+
+---
+
+### Display
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Activity Timeline** | Chronological event list | `lightning-activity-timeline` |
+| **Avatar** | User or entity image placeholder | `lightning-avatar` |
+| **Avatar Group** | Stacked avatar collection | N/A |
+| **Badges** | Small status label | `lightning-badge` |
+| **Dynamic Icons** | Animated contextual icons | N/A |
+| **Files** | File attachment card | N/A |
+| **Icons** | SVG icons from SLDS sprite | `lightning-icon` |
+| **Illustration** | Empty/error state graphic | N/A |
+| **Pills** | Removable tag or filter token | `lightning-pill` |
+
+---
+
+### Data
+
+Components for displaying structured data.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Data Tables** | Sortable tabular data | `lightning-datatable` |
+| **Tree Grid** | Hierarchical data table | `lightning-tree-grid` |
+
+---
+
+### Feedback
+
+Components for communicating status and feedback.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Alert** | Page-level status banner | N/A |
+| **Notifications** | System notification messages | N/A |
+| **Progress Bar** | Linear completion indicator | `lightning-progress-bar` |
+| **Progress Indicator** | Multi-step process tracker | `lightning-progress-indicator` |
+| **Progress Ring** | Circular progress indicator | `lightning-progress-ring` |
+| **Scoped Notifications** | Notification scoped to a container | N/A |
+| **Spinners** | Loading state indicator | `lightning-spinner` |
+| **Toast** | Temporary notification message | N/A |
+| **Trial Bar** | Trial status and call-to-action bar | N/A |
+
+---
+
+### Overlay
+
+Components that appear above the main interface.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Docked Composer** | Bottom-docked content creation panel | N/A |
+| **Modals** | Blocking dialog overlay | N/A |
+| **Popovers** | Contextual overlay anchored to trigger | N/A |
+| **Prompt** | Confirmation or input dialog | N/A |
+| **Tooltips** | Hover-triggered label | N/A |
+| **Welcome Mat** | Onboarding introduction overlay | N/A |
+
+---
+
+### Complex Components
+
+Advanced components with rich functionality.
+
+| Blueprint | Description | Lightning Component |
+|-----------|-------------|---------------------|
+| **Chat** | Chronological chat message display | N/A |
+| **Color Picker** | Color selection with hex/swatch input | N/A |
+| **Drop Zone** | Drag-and-drop target area | N/A |
+| **Feeds** | Chronological activity feed | N/A |
+| **List Builder** | Drag-and-drop list ordering | N/A |
+| **Map** | Interactive map display | `lightning-map` |
+| **Publishers** | Content creation panel | N/A |
+| **Setup Assistant** | Guided onboarding checklist | N/A |
+
+---
+
+## Framework Notes
+
+- **LWC / Aura**: Prefer the mapped Lightning component when listed — it handles accessibility and events.
+- **React / Vue / Angular / plain HTML**: Use the blueprint HTML structure and CSS classes directly.
+- **Customization**: Apply styling hooks (CSS custom properties) to theme components without overriding base styles.