@salesforce/afv-skills 1.14.0 → 1.16.0

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

@@ -0,0 +1,89 @@
+---
+id: slds.guidance.utilities.interactions
+title: Interactions Utilities
+description: SLDS link reset, faux link, and focus state utility classes
+summary: "Utilities for link resets, faux links, and focus states. Enables custom link styling and accessible focus indicators."
+
+artifact_type: reference
+domain: utilities
+topic: interactions
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.utilities.typography
+
+tags: [utilities, interactions, links, focus, accessibility]
+keywords: [slds-text-link, slds-has-blur-focus, slds-text-link_reset, slds-text-link_faux]
+---
+
+# Interactions - Links & Focus States
+
+Managing link appearance, creating faux links, and implementing accessible focus states.
+
+## Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-text-link_reset` | Makes links and buttons appear as regular text |
+| `slds-text-link` | Restores link styling inside `slds-text-link_reset` |
+| `slds-text-link_faux` | Creates underline-on-hover for non-anchor elements |
+| `slds-type-focus` | Legacy alias for slds-text-link_faux |
+| `slds-has-blur-focus` | Adds accessible blurred outline on focus |
+| `slds-has-input-focus` | JavaScript-applied focus state for input containers |
+
+## Common Patterns
+
+```html
+<!-- Reset link to look like plain text -->
+<a href="/path" class="slds-text-link_reset">
+  This link looks like regular text
+</a>
+
+<!-- Reset with partial link styling restored -->
+<a href="/article" class="slds-text-link_reset">
+  This article discusses important topics
+  <span class="slds-text-link">Read more</span>
+</a>
+
+<!-- Faux link on heading + button combo -->
+<div class="slds-page-header__name">
+  <h1 class="slds-page-header__title slds-text-link_faux">
+    Account Name
+  </h1>
+  <button class="slds-button slds-button_icon slds-text-link_faux">
+    <svg class="slds-button__icon">...</svg>
+  </button>
+</div>
+
+<!-- Accessible blur focus on custom button -->
+<button class="slds-button slds-has-blur-focus">
+  Custom Action
+</button>
+
+<!-- Input container with JavaScript focus state -->
+<div class="slds-form-element__control" id="input-container">
+  <input class="slds-input"
+         onfocus="document.getElementById('input-container').classList.add('slds-has-input-focus')"
+         onblur="document.getElementById('input-container').classList.remove('slds-has-input-focus')" />
+</div>
+```
+
+## Best Practices
+
+✅ Use `slds-text-link_reset` to remove default link styling
+✅ Use `slds-text-link_faux` for non-anchor elements that need link behavior
+✅ Use `slds-has-blur-focus` for keyboard navigation accessibility
+✅ Apply `slds-has-input-focus` via JavaScript when input receives focus
+✅ Combine `slds-text-link_reset` with `slds-text-link` for partial link styling
+
+❌ Don't use `slds-text-link_faux` on actual anchor elements
+❌ Don't forget to handle both focus and blur events for `slds-has-input-focus`
+❌ Don't remove focus indicators without providing alternatives
+❌ Don't apply multiple interaction utilities to the same element

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

@@ -0,0 +1,109 @@
+---
+id: slds.guidance.utilities.layout
+title: Layout Utilities
+description: SLDS layout utility classes for global spacing and component connection
+summary: "Utilities for global spacing (has-buffer, has-full-bleed, magnet utilities). Provides consistent buffer margins, full-bleed layouts, and seamless card connections."
+
+artifact_type: reference
+domain: utilities
+topic: layout
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.hooks.spacing
+
+tags: [utilities, layout, spacing, magnet]
+keywords: [slds-has-buffer, slds-has-full-bleed, slds-has-magnet]
+---
+
+# Layout - Global Spacing & Component Connection
+
+Global spacing management and seamless component connections.
+
+## Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-has-buffer` | Applies consistent global margin using `--slds-g-spacing-3` token |
+| `slds-has-full-bleed` | Removes all margins to create full-bleed layouts |
+| `slds-has-bottom-magnet` | Removes bottom margin and border radius to connect with element below |
+| `slds-has-top-magnet` | Removes top margin and border radius to connect with element above |
+
+## Common Patterns
+
+### Standard Buffer Spacing
+```html
+<!-- Apply consistent spacing around cards -->
+<div class="slds-card slds-has-buffer">
+  <div class="slds-card__header">Card with buffer margin</div>
+  <div class="slds-card__body">Content has global spacing on all sides</div>
+</div>
+```
+
+### Full-Bleed Hero Section
+```html
+<!-- Remove margins for edge-to-edge layouts -->
+<div class="slds-page-header slds-has-full-bleed">
+  <div class="slds-page-header__row">
+    <div class="slds-page-header__col-title">Full-width header with no margins</div>
+  </div>
+</div>
+```
+
+### Connected Card Components
+```html
+<!-- Connect two cards vertically without gap -->
+<div class="slds-card slds-has-bottom-magnet">
+  <div class="slds-card__header">First Card</div>
+  <div class="slds-card__body">This card connects to the one below</div>
+</div>
+<div class="slds-card slds-has-top-magnet">
+  <div class="slds-card__header">Second Card</div>
+  <div class="slds-card__body">Appears seamlessly connected to card above</div>
+</div>
+```
+
+### Multiple Connected Components
+```html
+<!-- Chain multiple cards together -->
+<div class="slds-box slds-has-bottom-magnet">
+  <h2>Section Header</h2>
+</div>
+<div class="slds-card slds-has-top-magnet slds-has-bottom-magnet">
+  <div class="slds-card__body">Middle card connected on both sides</div>
+</div>
+<div class="slds-box slds-has-top-magnet">
+  <p>Footer content</p>
+</div>
+```
+
+### Combined Buffer and Magnet
+```html
+<!-- Use buffer with magnet for special layouts -->
+<div class="slds-card slds-has-buffer slds-has-bottom-magnet">
+  <div class="slds-card__body">Card with side margins but connected below</div>
+</div>
+<div class="slds-card slds-has-top-magnet slds-has-buffer">
+  <!-- Special case: removes bottom margin, border-radius, top border, and box-shadow -->
+  <div class="slds-card__body">Connected card with modified buffer behavior</div>
+</div>
+```
+
+## Best Practices
+
+✅ Use `slds-has-buffer` on cards and boxes for consistent component spacing
+✅ Apply magnet utilities to Cards, Page Headers, and Box components
+✅ Use `slds-has-bottom-magnet` on the top component and `slds-has-top-magnet` on the bottom component
+✅ Use `slds-has-full-bleed` for hero sections and full-width backgrounds
+
+❌ Avoid using magnet utilities on non-card-like elements
+❌ Do not mix magnet utilities with custom margin styles
+❌ Never apply `slds-has-full-bleed` to components that need spacing
+❌ Do not use magnet utilities when visual separation is needed

package/skills/applying-slds/guidance/utilities/line-clamp.md

@@ -0,0 +1,131 @@
+---
+id: slds.guidance.utilities.line-clamp
+title: Line-clamp Utilities
+description: SLDS line-clamp utility classes for multi-line text truncation
+summary: "Utilities for multi-line text truncation (2-7 lines). Provides controlled text overflow with ellipsis for readable content length management."
+
+artifact_type: reference
+domain: utilities
+topic: line-clamp
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.utilities.truncate
+
+tags: [utilities, line-clamp, truncation, text]
+keywords: [slds-line-clamp, text-truncation, ellipsis, multi-line]
+---
+
+# Line Clamp - Multi-line Text Truncation
+
+Controlled multi-line text truncation with ellipsis.
+
+## Line Limit Scale
+
+| Class | Lines | Use Case |
+|-------|-------|----------|
+| `slds-line-clamp` | 3 lines | Default truncation for card descriptions |
+| `slds-line-clamp_x-small` | 2 lines | Compact list items and previews |
+| `slds-line-clamp_small` | 3 lines | Standard card and tile descriptions |
+| `slds-line-clamp_medium` | 5 lines | Extended previews and summaries |
+| `slds-line-clamp_large` | 7 lines | Long-form content with controlled height |
+
+## Common Patterns
+
+### Card Description Truncation
+```html
+<!-- Standard 3-line truncation for card descriptions -->
+<div class="slds-card">
+  <div class="slds-card__body">
+    <p class="slds-line-clamp">
+      This is a long description that will be truncated after three lines
+      of text. Any content beyond the third line will be hidden with an
+      ellipsis to indicate more content is available.
+    </p>
+  </div>
+</div>
+```
+
+### Compact List Item Preview
+```html
+<!-- 2-line truncation for list items -->
+<ul class="slds-has-dividers_bottom">
+  <li class="slds-item">
+    <div class="slds-line-clamp_x-small">
+      Item description that displays only two lines before truncating
+      with ellipsis for space-efficient list layouts.
+    </div>
+  </li>
+</ul>
+```
+
+### Extended Article Summary
+```html
+<!-- 5-line truncation for article previews -->
+<article class="slds-box">
+  <h3 class="slds-text-heading_small">Article Title</h3>
+  <div class="slds-line-clamp_medium">
+    This article summary can display up to five lines of content before
+    truncation occurs. This provides enough context for readers to understand
+    the main points while maintaining consistent layout height across
+    multiple article cards in a grid or list view.
+  </div>
+</article>
+```
+
+### Long-form Content Preview
+```html
+<!-- 7-line truncation for detailed previews -->
+<div class="slds-panel">
+  <div class="slds-panel__body">
+    <div class="slds-line-clamp_large">
+      Extended content preview that allows up to seven lines of text
+      to be displayed. This is useful for detailed descriptions,
+      documentation excerpts, or any scenario where more context is
+      beneficial while still maintaining a maximum height constraint
+      for consistent layouts across different content lengths.
+    </div>
+  </div>
+</div>
+```
+
+### Responsive Text Truncation
+```html
+<!-- Different truncation levels for different contexts -->
+<div class="slds-grid slds-wrap">
+  <div class="slds-col slds-size_1-of-2">
+    <h4>Product Name</h4>
+    <p class="slds-line-clamp_x-small">
+      Brief product description limited to two lines
+    </p>
+  </div>
+  <div class="slds-col slds-size_1-of-2">
+    <h4>Product Details</h4>
+    <p class="slds-line-clamp_medium">
+      More detailed product information that can extend
+      up to five lines before being truncated
+    </p>
+  </div>
+</div>
+```
+
+## Best Practices
+
+✅ Apply line-clamp classes directly to text elements (`<p>`, `<div>`, `<span>`)
+✅ Use `slds-line-clamp_x-small` (2 lines) for compact layouts and list items
+✅ Use `slds-line-clamp` or `slds-line-clamp_small` (3 lines) for standard card descriptions
+✅ Use `slds-line-clamp_medium` (5 lines) for extended previews
+✅ Test truncation with actual content to ensure readability
+✅ Provide "Show More" functionality when truncated content needs full access
+
+❌ Do not apply to container elements with HTML children
+❌ Never use on elements containing interactive components
+❌ Do not rely on line-clamp for IE11 support (uses -webkit-line-clamp)
+❌ Avoid using with single-line truncation (use [Truncate Utilities](ref:slds.guidance.utilities.truncate) instead)

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

@@ -0,0 +1,155 @@
+---
+id: slds.guidance.utilities.margin
+title: Margin Utilities
+description: SLDS margin utility classes for external spacing
+summary: "Utilities for external spacing. Includes directional (top/right/bottom/left), aggregate (horizontal/vertical/around), and variable density classes. Base unit 4px with sizes from xxx-small (2px) to xx-large (48px)."
+
+artifact_type: reference
+domain: utilities
+topic: margin
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.utilities.padding
+  - slds.guidance.hooks.spacing
+
+tags: [utilities, margin, spacing, external-spacing]
+keywords: [slds-m, margin, external spacing, whitespace]
+---
+
+# Margin - External Spacing
+
+External spacing between elements. Base unit: **4px**.
+
+## Size Scale
+
+| Size | Class Suffix | Value | Pixels |
+|------|-------------|-------|--------|
+| None | `none` | 0 | 0px |
+| XXX Small | `xxx-small` | 0.125rem | 2px |
+| XX Small | `xx-small` | 0.25rem | 4px |
+| X Small | `x-small` | 0.5rem | 8px |
+| Small | `small` | 0.75rem | 12px |
+| Medium | `medium` | 1rem | 16px |
+| Large | `large` | 1.5rem | 24px |
+| X Large | `x-large` | 2rem | 32px |
+| XX Large | `xx-large` | 3rem | 48px |
+
+## Core Classes
+
+### Directional Margins
+
+| Class | Purpose |
+|-------|---------|
+| `slds-m-top_*` | Applies margin to the top edge |
+| `slds-m-right_*` | Applies margin to the right edge |
+| `slds-m-bottom_*` | Applies margin to the bottom edge |
+| `slds-m-left_*` | Applies margin to the left edge |
+
+### Aggregate Margins
+
+| Class | Purpose |
+|-------|---------|
+| `slds-m-horizontal_*` | Applies margin to left and right edges |
+| `slds-m-vertical_*` | Applies margin to top and bottom edges |
+| `slds-m-around_*` | Applies margin to all four edges |
+
+### Variable Density Classes
+
+| Class | Purpose | Comfy | Compact |
+|-------|---------|-------|---------|
+| `slds-var-m-top_*` | Variable density top margin | Full size | 50% size |
+| `slds-var-m-right_*` | Variable density right margin | Full size | 50% size |
+| `slds-var-m-bottom_*` | Variable density bottom margin | Full size | 50% size |
+| `slds-var-m-left_*` | Variable density left margin | Full size | 50% size |
+| `slds-var-m-horizontal_*` | Variable density horizontal margins | Full size | 50% size |
+| `slds-var-m-vertical_*` | Variable density vertical margins | Full size | 50% size |
+| `slds-var-m-around_*` | Variable density all sides | Full size | 50% size |
+
+## Common Patterns
+
+```html
+<!-- Card stack with consistent spacing -->
+<div class="slds-card slds-m-bottom_medium">
+  <!-- Card content -->
+</div>
+<div class="slds-card slds-m-bottom_medium">
+  <!-- Card content -->
+</div>
+<div class="slds-card">
+  <!-- Last card needs no bottom margin -->
+</div>
+
+<!-- Button group with horizontal spacing -->
+<div class="slds-button-group">
+  <button class="slds-button slds-button_neutral">Cancel</button>
+  <button class="slds-button slds-button_brand slds-m-left_small">Save</button>
+  <button class="slds-button slds-button_brand slds-m-left_small">Save & New</button>
+</div>
+
+<!-- Page sections with vertical rhythm -->
+<section class="slds-m-vertical_large">
+  <h2 class="slds-text-heading_medium slds-m-bottom_small">Section Title</h2>
+  <div class="slds-m-bottom_medium">
+    <!-- Section content -->
+  </div>
+</section>
+
+<!-- Responsive form layout with variable density -->
+<div class="slds-form-element slds-var-m-bottom_medium">
+  <label class="slds-form-element__label">Field Label</label>
+  <input class="slds-input" />
+</div>
+<div class="slds-form-element slds-var-m-bottom_medium">
+  <label class="slds-form-element__label">Another Field</label>
+  <input class="slds-input" />
+</div>
+
+<!-- Remove default margins when needed -->
+<ul class="slds-m-around_none">
+  <li>List item without inherited margins</li>
+  <li>Another item</li>
+</ul>
+```
+
+## Implementation Guidelines
+
+### Standard Spacing Values
+
+| Context | Recommended Class | Size |
+|---------|------------------|------|
+| Between cards/tiles | `slds-m-bottom_medium` | 16px |
+| Between buttons | `slds-m-left_small` | 12px |
+| Between form fields | `slds-m-bottom_medium` | 16px |
+| Between page sections | `slds-m-vertical_large` | 24px |
+| Icon to text | `slds-m-right_x-small` | 8px |
+| Dense layouts | `slds-m-around_small` | 12px |
+| Remove spacing | `slds-m-around_none` | 0px |
+
+### Responsive Considerations
+
+Use variable density classes for layouts that adapt to user preferences:
+- Desktop comfy mode: Full spacing values
+- Desktop compact mode: 50% reduced spacing
+- Mobile: Consider using smaller sizes by default
+
+## Best Practices
+
+✅ Use `slds-m-bottom_medium` (16px) between stacked components
+✅ Use `slds-m-left_small` (12px) between inline buttons
+✅ Use `slds-m-vertical_large` (24px) between major page sections
+✅ Use `slds-m-around_none` to remove default element margins
+✅ Use variable density classes (`slds-var-m-*`) for responsive layouts
+✅ Apply margins to the element that needs spacing from its siblings
+
+❌ Don't use margins larger than `xx-large` (48px)
+❌ Don't apply both top and bottom margins when one suffices
+❌ Don't mix standard and variable density classes on the same element
+❌ Don't use margin for internal spacing - use [Padding Utilities](ref:slds.guidance.utilities.padding) instead

package/skills/applying-slds/guidance/utilities/media-object.md

@@ -0,0 +1,161 @@
+---
+id: slds.guidance.utilities.media-object
+title: Media Object Utilities
+description: SLDS media object utility classes for image and text layouts
+summary: "Utilities for image+text layouts. Provides flexible pairing of media elements (icons/images) with text content. Includes size variants (small/large), positioning (left/right/center), and responsive stacking."
+
+artifact_type: reference
+domain: utilities
+topic: media-object
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.hooks.spacing
+
+tags: [utilities, media-object, layout, flexbox]
+keywords: [slds-media, media object, figure, image layout]
+---
+
+# Media Object - Image & Text Layouts
+
+Flexible image and text pairing layouts using flexbox.
+
+## Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-media` | Creates flex container for media object layout |
+| `slds-media__figure` | Container for media element (image/icon/avatar) |
+| `slds-media__body` | Container for text content next to figure |
+| `slds-media__figure_reverse` | Positions figure on the right side instead of left |
+
+## Size Variants
+
+| Class | Purpose | Spacing |
+|-------|---------|---------|
+| `slds-media_small` | Reduces spacing between figure and body | 8px (`--slds-g-spacing-2`) |
+| Default spacing | Standard spacing between figure and body | 12px (`--slds-g-spacing-3`) |
+| `slds-media_large` | Increases spacing between figure and body | 20px (`--slds-g-spacing-5`) |
+
+## Layout Modifiers
+
+| Class | Purpose |
+|-------|---------|
+| `slds-media_center` | Vertically centers figure and body content |
+| `slds-media_inline` | Makes body flow inline instead of taking full width |
+| `slds-media_responsive` | Stacks figure above body on smaller screens |
+| `slds-media__figure_fixed-width` | Sets fixed width on figure container (40px) |
+
+## Common Patterns
+
+```html
+<!-- Basic media object with avatar and text -->
+<div class="slds-media">
+  <div class="slds-media__figure">
+    <span class="slds-avatar slds-avatar_circle slds-avatar_medium">
+      <img src="/avatar.jpg" alt="User" />
+    </span>
+  </div>
+  <div class="slds-media__body">
+    <h3 class="slds-text-heading_small">John Smith</h3>
+    <p class="slds-text-body_regular">Sales Representative</p>
+  </div>
+</div>
+
+<!-- Vertically centered icon and text -->
+<div class="slds-media slds-media_center">
+  <div class="slds-media__figure">
+    <span class="slds-icon_container slds-icon-standard-account">
+      <svg class="slds-icon slds-icon_small">
+        <use href="/icons/standard-sprite.svg#account"></use>
+      </svg>
+    </span>
+  </div>
+  <div class="slds-media__body">
+    <p>Acme Corporation</p>
+  </div>
+</div>
+
+<!-- Figure on right side -->
+<div class="slds-media">
+  <div class="slds-media__body">
+    <h4>Notification Settings</h4>
+    <p>Email notifications are enabled</p>
+  </div>
+  <div class="slds-media__figure slds-media__figure_reverse">
+    <button class="slds-button slds-button_icon">
+      <svg class="slds-button__icon">
+        <use href="/icons/utility-sprite.svg#settings"></use>
+      </svg>
+    </button>
+  </div>
+</div>
+
+<!-- Small spacing variant for compact lists -->
+<ul>
+  <li class="slds-media slds-media_small">
+    <div class="slds-media__figure">
+      <span class="slds-icon_container">
+        <svg class="slds-icon slds-icon_x-small">
+          <use href="/icons/utility-sprite.svg#file"></use>
+        </svg>
+      </span>
+    </div>
+    <div class="slds-media__body">
+      <span>Document.pdf</span>
+    </div>
+  </li>
+</ul>
+
+<!-- Responsive stacking for mobile -->
+<div class="slds-media slds-media_responsive">
+  <div class="slds-media__figure">
+    <img src="/product.jpg" alt="Product" width="120" />
+  </div>
+  <div class="slds-media__body">
+    <h3>Product Name</h3>
+    <p>Product description that will stack below image on mobile devices</p>
+  </div>
+</div>
+```
+
+## Implementation Guidelines
+
+### Component Combinations
+
+| Use Case | Classes | Description |
+|----------|---------|-------------|
+| Avatar with name | `slds-media` | Standard user profile display |
+| Icon with label | `slds-media slds-media_center slds-media_small` | Compact icon labels |
+| Product image with details | `slds-media slds-media_large` | E-commerce layouts |
+| Notification with action | `slds-media` + `slds-media__figure_reverse` | Action button on right |
+| Mobile-friendly layout | `slds-media slds-media_responsive` | Stacks on small screens |
+
+### Spacing Guidelines
+
+| Context | Recommended Variant | Gap Size |
+|---------|-------------------|----------|
+| List items | `slds-media_small` | 8px |
+| Standard cards | Default (no modifier) | 12px |
+| Featured content | `slds-media_large` | 20px |
+
+## Best Practices
+
+✅ Use `slds-media__body` for text content to enable proper truncation
+✅ Use `slds-media_center` when icon and text should align middle
+✅ Use `slds-media_small` for compact list items
+✅ Use `slds-media_responsive` for mobile-optimized layouts
+✅ Place avatars and icons in `slds-media__figure`
+✅ Use `min-width: 0` on body for text truncation support
+
+❌ Don't nest media objects more than 2 levels deep
+❌ Don't use media objects for complex grid layouts
+❌ Don't forget `slds-media__figure` wrapper for images
+❌ Don't apply spacing utilities directly to figure or body