@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/applying-slds/guidance/utilities/typography.md

@@ -0,0 +1,166 @@
+---
+id: slds.guidance.utilities.typography
+title: Typography Utilities
+description: SLDS text styling and typography utility classes
+summary: "Utilities for text styling. Headings, body text, alignment, colors, and special formatting. Link utilities are documented in [Interactions](ref:slds.guidance.utilities.interactions)."
+
+artifact_type: reference
+domain: utilities
+topic: typography
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.utilities.interactions
+  - slds.guidance.hooks.typography
+
+tags: [utilities, typography, text, headings, alignment]
+keywords: [slds-text-heading, slds-text-body, slds-text-color, slds-text-align]
+---
+
+# Typography - Text Styling
+
+Text styling, headings, alignment, and colors.
+
+## Core Classes
+
+### Heading Sizes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-heading_large` | Large heading (28px, line-height 1.25) |
+| `slds-text-heading_medium` | Medium heading (20px, line-height 1.25) |
+| `slds-text-heading_small` | Small heading (16px, line-height 1.25) |
+
+### Title Styles
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-title` | Standard title (12px, line-height 1.25) |
+| `slds-text-title_caps` | Uppercase title (12px, weight 400, letter-spacing 0.0625rem) |
+| `slds-text-title_bold` | Bold title (12px, weight 700) |
+
+### Body Text
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-body_regular` | Regular body text (13px) |
+| `slds-text-body_small` | Small body text (12px) |
+
+### Text Alignment
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-align_left` | Aligns text to start |
+| `slds-text-align_center` | Centers text |
+| `slds-text-align_right` | Aligns text to end |
+
+### Text Colors
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-color_default` | Default text color |
+| `slds-text-color_weak` | De-emphasized text color |
+| `slds-text-color_error` | Error state text (red) |
+| `slds-text-color_destructive` | Destructive action text (red) |
+| `slds-text-color_success` | Success state text (green) |
+| `slds-text-color_inverse` | Light text on dark background |
+| `slds-text-color_inverse-weak` | De-emphasized inverse text |
+
+### Special Formatting
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-longform` | Applies default spacing to content blocks |
+| `slds-text-font_monospace` | Applies monospace font family |
+| `slds-line-height_reset` | Resets line-height to 1 |
+
+## Common Patterns
+
+### Page Header
+```html
+<!-- Main page title with subtitle -->
+<div class="slds-page-header">
+  <h1 class="slds-text-heading_large">
+    <!-- 28px heading -->
+    Account Details
+  </h1>
+  <p class="slds-text-body_regular slds-text-color_weak">
+    <!-- 13px de-emphasized text -->
+    View and manage account information
+  </p>
+</div>
+```
+
+### Section Headers
+```html
+<!-- Section with title caps -->
+<section class="slds-m-top_large">
+  <h2 class="slds-text-title_caps slds-m-bottom_small">
+    <!-- 12px uppercase title -->
+    CONTACT INFORMATION
+  </h2>
+  <div class="slds-text-body_regular">
+    <!-- Content -->
+  </div>
+</section>
+```
+
+### Status Messages
+```html
+<!-- Success message -->
+<div class="slds-text-color_success slds-text-align_center">
+  <!-- Green centered text -->
+  Record saved successfully
+</div>
+
+<!-- Error message -->
+<div class="slds-text-color_error slds-m-top_small">
+  <!-- Red error text -->
+  Required field missing
+</div>
+```
+
+### Long-Form Content
+```html
+<!-- Article with automatic spacing -->
+<article class="slds-text-longform">
+  <!-- Automatic margins for h1, h2, h3, p, ul, ol -->
+  <h1>Article Title</h1>
+  <p>First paragraph with automatic bottom margin.</p>
+  <ul>
+    <!-- Disc bullets with proper indentation -->
+    <li>First item</li>
+    <li>Second item</li>
+  </ul>
+</article>
+```
+
+### Code Display
+```html
+<!-- Monospace text for code -->
+<code class="slds-text-font_monospace slds-text-body_small">
+  <!-- 12px monospace font -->
+  SELECT Id, Name FROM Account
+</code>
+```
+
+## Best Practices
+
+✅ Use semantic HTML elements (h1-h6) with text utility classes
+✅ Apply `slds-text-heading_*` classes to maintain consistent sizing
+✅ Use `slds-text-color_weak` for secondary information
+✅ Apply `slds-text-title_caps` for section labels and tabs
+✅ Use `slds-text-longform` for user-generated content areas
+✅ Combine text utilities with spacing utilities for proper layout
+
+❌ Avoid using heading classes on non-heading elements for sizing
+❌ Never use color utilities as the only indicator of state
+❌ Avoid mixing multiple text size classes on the same element
+❌ Never override line-height unless using `slds-line-height_reset`

package/skills/applying-slds/guidance/utilities/vertical-list.md

@@ -0,0 +1,166 @@
+---
+id: slds.guidance.utilities.vertical-list
+title: Vertical-list Utilities
+description: SLDS vertical list utility classes for list formatting and spacing
+summary: "Utilities for vertical lists including dividers, cards, spacing, link blocks, and list styles (dotted, ordered)."
+
+artifact_type: reference
+domain: utilities
+topic: vertical-list
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+
+tags: [utilities, lists, vertical-list, dividers]
+keywords: [slds-list, slds-has-dividers, vertical spacing, list formatting]
+---
+
+# Vertical List - Formatting & Spacing
+
+Creating and styling vertical lists with consistent spacing, dividers, and interactive states.
+
+## Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-list_vertical` | Base vertical list container |
+| `slds-list__item` | Individual list item |
+| `slds-item` | Generic item (alternative to `slds-list__item`) |
+| `slds-is-selected` | Marks selected state with accent border |
+| `slds-is-nested` | Indents nested lists by 16px |
+
+## List Styles
+
+| Class | Purpose |
+|-------|---------|
+| `slds-list_dotted` | Unordered list with disc bullets |
+| `slds-list_ordered` | Ordered list with decimal numbers |
+
+## Spacing Variants
+
+| Class | Spacing Between Items |
+|-------|----------------------|
+| `slds-list_vertical-space` | 8px (`x-small`) |
+| `slds-list_vertical-space-medium` | 16px (`medium`) |
+
+## Divider Classes
+
+### Line Dividers
+| Class | Purpose |
+|-------|---------|
+| `slds-has-dividers` | Bottom border on items with hover states |
+| `slds-has-dividers_top` | Top border on each item |
+| `slds-has-dividers_bottom` | Bottom border on each item |
+| `slds-has-dividers_top-space` | Top border with 8px padding |
+| `slds-has-dividers_bottom-space` | Bottom border with 8px padding |
+
+### Card Dividers
+| Class | Purpose |
+|-------|---------|
+| `slds-has-cards` | Bordered cards with rounded corners |
+| `slds-has-cards_space` | Bordered cards with 12px padding |
+| `slds-has-dividers_around` | Full border around each item |
+| `slds-has-dividers_around-space` | Full border with 12px padding |
+
+### Single Dividers
+| Class | Purpose |
+|-------|---------|
+| `slds-has-divider` | Single top divider (8px margin + padding) |
+| `slds-has-divider_top` | Top border only |
+| `slds-has-divider_bottom` | Bottom border only |
+| `slds-has-divider_top-space` | Top border with padding |
+| `slds-has-divider_bottom-space` | Bottom border with padding |
+| `slds-has-divider_right` | Right border only |
+| `slds-has-divider_left` | Left border only |
+
+## Link Blocks
+
+| Class | Purpose |
+|-------|---------|
+| `slds-has-block-links` | Makes links display block |
+| `slds-has-block-links_space` | Block links with 12px padding |
+| `slds-has-inline-block-links` | Makes links display inline-block |
+| `slds-has-inline-block-links_space` | Inline-block links with 12px padding |
+
+## Interactive States
+
+| Class | Purpose |
+|-------|---------|
+| `slds-has-list-interactions` | Enables hover and active states |
+
+## Common Patterns
+
+```html
+<!-- Basic vertical list with dividers -->
+<ul class="slds-list_vertical slds-has-dividers">
+  <li class="slds-list__item">Item 1</li>
+  <li class="slds-list__item">Item 2</li>
+  <li class="slds-list__item slds-is-selected">Selected Item</li>
+</ul>
+
+<!-- Card-style list with spacing -->
+<ul class="slds-has-cards_space">
+  <li class="slds-list__item">
+    <!-- Each item appears as a card with padding -->
+    <h3>Card Title</h3>
+    <p>Card content with 12px padding</p>
+  </li>
+  <li class="slds-list__item">
+    <h3>Another Card</h3>
+    <p>Automatically spaced 8px apart</p>
+  </li>
+</ul>
+
+<!-- List with block links -->
+<ul class="slds-has-block-links_space">
+  <li class="slds-list__item">
+    <a href="/page1">
+      <!-- Entire area is clickable with padding -->
+      <h3>Link Title</h3>
+      <p>Description text</p>
+    </a>
+  </li>
+  <li class="slds-list__item">
+    <a href="/page2">Another clickable item</a>
+  </li>
+</ul>
+
+<!-- Nested list with bullets -->
+<ul class="slds-list_dotted">
+  <li>Parent item</li>
+  <li>
+    Another parent
+    <ul class="slds-list_dotted slds-is-nested">
+      <li>Nested child 1</li>
+      <li>Nested child 2</li>
+    </ul>
+  </li>
+</ul>
+
+<!-- Interactive list with hover states -->
+<ul class="slds-list_vertical slds-has-dividers slds-has-list-interactions">
+  <li class="slds-list__item">Hover for gray background</li>
+  <li class="slds-list__item">Click for active state</li>
+</ul>
+```
+
+## Best Practices
+
+✅ Use `slds-list_vertical` with `slds-has-dividers` for navigation menus
+✅ Apply `slds-has-cards_space` for distinct content sections
+✅ Use `slds-has-block-links_space` for clickable list items
+✅ Add `slds-is-selected` to indicate current selection
+✅ Combine `slds-list_dotted` or `slds-list_ordered` for structured content
+✅ Use `slds-is-nested` for hierarchical lists
+
+❌ Mix card styles with line dividers on the same list
+❌ Apply multiple divider types to the same element
+❌ Use `slds-list__item` and `slds-item` interchangeably in the same list
+❌ Nest lists more than 3 levels deep

package/skills/applying-slds/guidance/utilities/visibility.md

@@ -0,0 +1,228 @@
+---
+id: slds.guidance.utilities.visibility
+title: Visibility Utilities
+description: SLDS show/hide and responsive display utility classes
+summary: "Utilities for controlling element visibility including basic show/hide, responsive breakpoints, screen reader support, and collapsed/expanded states."
+
+artifact_type: reference
+domain: utilities
+topic: visibility
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+
+tags: [utilities, visibility, responsive, accessibility]
+keywords: [slds-show, slds-hide, slds-assistive-text, responsive visibility, screen reader]
+---
+
+# Visibility - Show/Hide Elements
+
+Controlling element visibility and responsive display.
+
+## Basic Visibility
+
+| Class | Effect |
+|-------|--------|
+| `slds-show` | Display block |
+| `slds-hide` | Display none (!important, hidden from screen readers) |
+| `slds-hidden` | Visibility hidden (!important, maintains space) |
+| `slds-visible` | Visibility visible |
+| `slds-is-visually-empty` | Removes element from layout flow |
+
+**Display Variants**:
+- `slds-show_inline` - Display inline
+- `slds-show_inline-block` - Display inline-block
+
+## Screen Reader Support
+
+| Class | Purpose |
+|-------|---------|
+| `slds-assistive-text` | Visually hidden but readable by screen readers |
+| `slds-assistive-text_focus` | Becomes visible when focused (for skip links) |
+
+```html
+<!-- Icon with screen reader label -->
+<button class="slds-button slds-button_icon">
+  <svg class="slds-icon">...</svg>
+  <span class="slds-assistive-text">Edit Record</span>
+</button>
+
+<!-- Skip navigation link -->
+<a href="#main" class="slds-assistive-text slds-assistive-text_focus">
+  Skip to main content
+</a>
+```
+
+## Collapsed/Expanded States
+
+| Class | Effect |
+|-------|--------|
+| `slds-is-collapsed` | Height: 0, overflow: hidden |
+| `slds-is-expanded` | Height: auto, overflow: visible |
+
+```html
+<!-- Collapsible section -->
+<div class="slds-section">
+  <button aria-expanded="false" aria-controls="section-content">
+    Toggle Section
+  </button>
+  <div id="section-content" class="slds-is-collapsed">
+    <!-- Content hidden by default -->
+    Collapsible content here
+  </div>
+</div>
+```
+
+## Transition Visibility
+
+| Class | Effect |
+|-------|--------|
+| `slds-transition-hide` | Opacity: 0 |
+| `slds-transition-show` | Opacity: 1 |
+
+Add CSS transitions for smooth animations:
+```css
+.slds-transition-hide,
+.slds-transition-show {
+  transition: opacity 0.3s ease;
+}
+```
+
+## Responsive Visibility
+
+**Breakpoints**:
+- `x-small`: 320px
+- `small`: 480px
+- `medium`: 768px
+- `large`: 1024px
+- `x-large`: 1280px
+
+### Show Classes (Hidden Below, Visible At/Above)
+
+| Class | Visible From |
+|-------|--------------|
+| `slds-x-small-show` | 320px+ |
+| `slds-small-show` | 480px+ |
+| `slds-medium-show` | 768px+ |
+| `slds-large-show` | 1024px+ |
+
+**Display Variants**:
+- `slds-x-small-show_inline-block`
+- `slds-x-small-show_inline`
+- `slds-small-show_inline-block`
+- `slds-small-show_inline`
+- `slds-medium-show_inline-block`
+- `slds-medium-show_inline`
+- `slds-large-show_inline-block`
+- `slds-large-show_inline`
+
+### Show Only Classes (Visible Only Within Range)
+
+| Class | Visible Range |
+|-------|---------------|
+| `slds-x-small-show-only` | 320px - 479px |
+| `slds-small-show-only` | 480px - 767px |
+| `slds-medium-show-only` | 768px - 1023px |
+
+**Display Variants**:
+- `slds-x-small-show-only_inline-block`
+- `slds-x-small-show-only_inline`
+- `slds-small-show-only_inline-block`
+- `slds-small-show-only_inline`
+- `slds-medium-show-only_inline-block`
+- `slds-medium-show-only_inline`
+
+### Hide Classes
+
+| Class | Hidden At/Above | Visible Below |
+|-------|-----------------|---------------|
+| `slds-hide_x-small` | 320px+ | < 320px |
+| `slds-hide_small` | 480px+ | < 480px |
+| `slds-hide_medium` | 768px+ | < 768px |
+| `slds-hide_large` | 1024px+ | < 1024px |
+| `slds-hide_x-large` | 1280px+ | < 1280px |
+
+### Max Hide Classes (Hidden Below Breakpoint)
+
+| Class | Hidden Below |
+|-------|--------------|
+| `slds-max-x-small-hide` | < 480px |
+| `slds-max-small-hide` | < 768px |
+| `slds-max-medium-hide` | < 1024px |
+
+### Inverse Show Classes (Hidden At/Above)
+
+| Class | Visible Below | Hidden At/Above |
+|-------|---------------|-----------------|
+| `slds-show_x-small` | < 320px | 320px+ |
+| `slds-show_small` | < 480px | 480px+ |
+| `slds-show_medium` | < 768px | 768px+ |
+| `slds-show_large` | < 1024px | 1024px+ |
+| `slds-show_x-large` | < 1280px | 1280px+ |
+
+## Common Patterns
+
+```html
+<!-- Mobile menu / Desktop nav -->
+<button class="slds-button slds-hide_medium">
+  <!-- Visible on mobile, hidden 768px+ -->
+  <svg class="slds-icon">...</svg>
+  <span class="slds-assistive-text">Open Menu</span>
+</button>
+
+<nav class="slds-medium-show">
+  <!-- Hidden below 768px, visible 768px+ -->
+  <ul class="slds-list_horizontal">...</ul>
+</nav>
+
+<!-- Responsive table/card view -->
+<div class="slds-max-small-hide">
+  <!-- Table hidden below 768px -->
+  <table class="slds-table">...</table>
+</div>
+
+<div class="slds-small-show-only">
+  <!-- Cards shown only 480px-767px -->
+  <div class="slds-card">...</div>
+</div>
+
+<!-- Progressive disclosure -->
+<div class="slds-small-show">
+  <!-- Additional details shown 480px+ -->
+  Extended information for larger screens
+</div>
+
+<!-- Accessible expandable section -->
+<section class="slds-section slds-is-open">
+  <h2>
+    <button aria-expanded="true" aria-controls="content-id">
+      Section Title
+    </button>
+  </h2>
+  <div id="content-id" class="slds-is-expanded">
+    Section content
+  </div>
+</section>
+```
+
+## Best Practices
+
+✅ Use `slds-assistive-text` for all icon-only buttons
+✅ Use `slds-hide` with `!important` to ensure hiding
+✅ Test responsive classes at each breakpoint
+✅ Pair `aria-expanded` with `slds-is-collapsed/expanded`
+✅ Use `slds-assistive-text_focus` for skip links
+✅ Apply mobile-first approach: hide by default, show at breakpoints
+
+❌ Combine `slds-hide` and `slds-show` on the same element
+❌ Use `slds-hidden` and `slds-visible` together
+❌ Hide essential content from screen readers
+❌ Use visibility classes for layout (use Grid or Flexbox instead)
+❌ Rely only on `display: none` for animations (use transitions)

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

@@ -0,0 +1,84 @@
+# SLDS Metadata
+
+Structured data for all SLDS artifacts. Use the search scripts in `../scripts/` or grep directly.
+
+Source: `packages/metadata/`
+
+---
+
+## Files
+
+### `blueprints/components/*.yaml` (85 files)
+
+One YAML file per SLDS blueprint component. Each contains:
+
+- `name`, `description`, `category`
+- `slds_classes.root` -- the BEM root class (e.g., `slds-modal`)
+- `slds_classes.elements[]` -- child element classes with purpose
+- `slds_classes.modifiers[]` -- variant modifier classes with usage guidance
+- `slds_classes.states[]` -- state classes (active, disabled, open, etc.)
+- `accessibility` -- required ARIA roles, attributes, keyboard interactions
+- `example_html` -- reference markup
+
+**Search**: `node ../scripts/search-blueprints.js --search "dialog"`
+
+**Direct grep**: `grep -rl "category: Overlay" blueprints/components/`
+
+### `hooks-index.json` (523 hooks)
+
+All SLDS styling hooks with computed values and CSS property mappings.
+
+Each hook entry:
+```json
+{
+  "token": "--slds-g-color-accent-1",
+  "category": "color",
+  "value": "#0176d3",
+  "properties": ["background-color", "color", "border-color", "fill"]
+}
+```
+
+Categories: color (325), font (57), spacing (48), shadow (44), sizing (27), duration (8), radius (6), ratio (5), fontFamily (3)
+
+**Search**: `node ../scripts/search-hooks.js --category "color"`
+
+**Direct grep**: `grep -i "accent" hooks-index.json`
+
+### `icon-metadata.json` (1,732 icons)
+
+All SLDS icons with synonyms for semantic search across 5 categories.
+
+Each icon entry:
+```json
+{
+  "displayName": "add_contact",
+  "category": "action",
+  "description": "Represents adding a new contact...",
+  "synonyms": ["add", "user", "contact", "create", "new", "person", "plus"]
+}
+```
+
+Categories: action, custom, doctype, standard, utility
+
+**Search**: `node ../scripts/search-icons.js --query "save button"`
+
+**Direct grep**: `grep -B1 -A5 '"save"' icon-metadata.json`
+
+### `utilities-index.json` (1,147 utilities)
+
+All SLDS utility classes organized by category with CSS rules.
+
+Each utility entry:
+```json
+{
+  "class": "slds-m-bottom_small",
+  "css": { "margin-bottom": "0.75rem" },
+  "category": "margin"
+}
+```
+
+27 categories: grid (80), margin (119), padding (120), sizing (613), color (48), text (24), and more.
+
+**Search**: `node ../scripts/search-utilities.js --category "grid"`
+
+**Direct grep**: `grep -i "slds-grid" utilities-index.json`