@salesforce/afv-skills 1.14.0 → 1.15.0

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.

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

@@ -0,0 +1,186 @@
+---
+id: slds.guidance.icons
+title: SLDS Icons Guidance
+description: Icon selection and implementation guidance for coding agents
+summary: "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."
+
+artifact_type: guide
+domain: icons
+topic: icons
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, implement]
+
+refs:
+  - slds.guidance.development
+  - slds.guidance.design
+  - slds.guidance.blueprints
+
+tags: [icons, sprites, svg, utility-icons, action-icons, standard-icons]
+keywords: [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:**
+
+```html
+<lightning-icon
+  icon-name="utility:search"
+  alternative-text="Search"
+  title="Search"
+  size="x-small">
+</lightning-icon>
+```
+
+**Icon button:**
+
+```html
+<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