@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/applying-slds/guidance/utilities/name-value-list.md

@@ -0,0 +1,152 @@
+---
+id: slds.guidance.utilities.name-value-list
+title: Name-Value List Utilities
+description: SLDS name-value list utility classes for structured data display
+summary: "Utilities for structured data lists (labels and details). Creates horizontal, vertical, and inline label-value pair layouts."
+
+artifact_type: reference
+domain: utilities
+topic: name-value-list
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.hooks.spacing
+
+tags: [utilities, name-value-list, data-display, lists]
+keywords: [slds-list_horizontal, slds-list_vertical, slds-list_inline, slds-item_label, slds-item_detail]
+---
+
+# Name-Value List - Structured Data Display
+
+Creating label-value pair layouts in horizontal, vertical, and inline configurations.
+
+## Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-list_horizontal` | Layout container for horizontal name-value pairs with 30/70 split |
+| `slds-list_vertical` | Layout container for vertical (stacked) name-value pairs |
+| `slds-list_inline` | Inline flex container for compact name-value pairs |
+| `slds-item_label` | Label element with 30% width and right padding (12px) |
+| `slds-item_detail` | Detail/value element with 70% width |
+
+## Layout Variants
+
+### Horizontal Layout (30/70 Split)
+| Variant | Label Width | Detail Width | Spacing |
+|---------|-------------|--------------|---------|
+| `slds-list_horizontal` | 30% | 70% | 12px gap |
+
+### Vertical Layout
+| Variant | Display | Spacing |
+|---------|---------|---------|
+| `slds-list_vertical` | Block stacked | Default line height |
+
+### Inline Layout
+| Variant | Display | Max Width |
+|---------|---------|-----------|
+| `slds-list_inline` | `inline-flex` | 100% |
+
+## Common Patterns
+
+### Horizontal Name-Value List
+```html
+<!-- Standard 30/70 horizontal layout -->
+<dl class="slds-list_horizontal">
+  <dt class="slds-item_label">Account Name</dt>
+  <dd class="slds-item_detail">Acme Corporation</dd>
+
+  <dt class="slds-item_label">Account Type</dt>
+  <dd class="slds-item_detail">Enterprise Customer</dd>
+
+  <dt class="slds-item_label">Industry</dt>
+  <dd class="slds-item_detail">Technology</dd>
+</dl>
+```
+
+### Vertical Stacked List
+```html
+<!-- Vertical stacked layout for long content -->
+<dl class="slds-list_vertical">
+  <dt class="slds-item_label">Description</dt>
+  <dd class="slds-item_detail">
+    This is a detailed description that spans multiple lines
+    and works better in a vertical layout.
+  </dd>
+
+  <dt class="slds-item_label">Notes</dt>
+  <dd class="slds-item_detail">
+    Additional notes and comments that may be lengthy.
+  </dd>
+</dl>
+```
+
+### Inline Compact List
+```html
+<!-- Inline layout for compact display -->
+<dl class="slds-list_inline">
+  <dt class="slds-item_label">Status:</dt>
+  <dd class="slds-item_detail">Active</dd>
+
+  <dt class="slds-item_label">Priority:</dt>
+  <dd class="slds-item_detail">High</dd>
+</dl>
+```
+
+### Mixed Layout in Card
+```html
+<!-- Name-value list within a card component -->
+<article class="slds-card">
+  <div class="slds-card__header">
+    <h2>Contact Details</h2>
+  </div>
+  <div class="slds-card__body">
+    <dl class="slds-list_horizontal">
+      <dt class="slds-item_label">Name</dt>
+      <dd class="slds-item_detail">John Smith</dd>
+
+      <dt class="slds-item_label">Email</dt>
+      <dd class="slds-item_detail">john.smith@example.com</dd>
+
+      <dt class="slds-item_label">Phone</dt>
+      <dd class="slds-item_detail">(555) 123-4567</dd>
+    </dl>
+  </div>
+</article>
+```
+
+## Best Practices
+
+✅ Use `slds-list_horizontal` for compact record details with short values
+✅ Use `slds-list_vertical` for long text content or descriptions
+✅ Use `slds-list_inline` for status indicators and brief metadata
+✅ Use semantic `<dl>`, `<dt>`, `<dd>` elements for accessibility
+✅ Apply `slds-item_label` to `<dt>` and `slds-item_detail` to `<dd>`
+✅ Maintain the 30/70 ratio for horizontal layouts to ensure consistency
+
+❌ Avoid using name-value lists for form inputs (use form layouts instead)
+❌ Avoid mixing layout types within the same list
+❌ Never omit `slds-item_label` or `slds-item_detail` classes
+❌ Avoid horizontal layout for values longer than 2-3 lines
+
+## Spacing Details
+
+The name-value list utilities use these specific spacing tokens:
+- **Horizontal gap**: `var(--slds-g-spacing-3)` (12px)
+- **Inline spacing**: `var(--slds-g-spacing-3)` to `var(--slds-g-spacing-4)` (12-16px)
+- **Label padding**: `padding-inline-end: var(--slds-g-spacing-3)` (12px right padding)
+
+## Accessibility Notes
+
+- Use `<dl>` (description list) as the container
+- Use `<dt>` (description term) for labels with `slds-item_label`
+- Use `<dd>` (description details) for values with `slds-item_detail`
+- Screen readers announce the semantic relationship between labels and values
+- Maintain logical reading order in the HTML structure

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

@@ -0,0 +1,155 @@
+---
+id: slds.guidance.utilities.padding
+title: Padding Utilities
+description: SLDS padding utility classes for internal spacing
+summary: "Utilities for internal spacing within elements. Includes directional variants, size scale from xxx-small to xx-large, and variable density classes."
+
+artifact_type: reference
+domain: utilities
+topic: padding
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+  - slds.guidance.utilities.margin
+  - slds.guidance.hooks.spacing
+
+tags: [utilities, padding, spacing, internal-spacing]
+keywords: [slds-p, slds-p-around, slds-p-horizontal, slds-p-vertical, padding]
+---
+
+# Padding - Internal Spacing
+
+Internal spacing within elements. Base unit: **4px**.
+
+## Size Scale
+
+| Size | Token | Value | Pixels |
+|------|-------|-------|--------|
+| `none` | 0 | 0 | 0px |
+| `xxx-small` | `--slds-g-spacing-1` | 0.125rem | 2px |
+| `xx-small` | `--slds-g-spacing-2` | 0.25rem | 4px |
+| `x-small` | `--slds-g-spacing-3` | 0.5rem | 8px |
+| `small` | `--slds-g-spacing-4` | 0.75rem | 12px |
+| `medium` | `--slds-g-spacing-5` | 1rem | 16px |
+| `large` | `--slds-g-spacing-6` | 1.5rem | 24px |
+| `x-large` | `--slds-g-spacing-7` | 2rem | 32px |
+| `xx-large` | `--slds-g-spacing-8` | 3rem | 48px |
+
+## Core Classes
+
+### Directional Padding
+
+| Class | Purpose |
+|-------|---------|
+| `slds-p-top_*` | Applies padding to element's top edge |
+| `slds-p-right_*` | Applies padding to element's right edge |
+| `slds-p-bottom_*` | Applies padding to element's bottom edge |
+| `slds-p-left_*` | Applies padding to element's left edge |
+| `slds-p-horizontal_*` | Applies padding to left and right edges |
+| `slds-p-vertical_*` | Applies padding to top and bottom edges |
+| `slds-p-around_*` | Applies padding to all four edges |
+
+### Special Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-has-cushion` | Applies default padding of 12px (small) to all sides |
+
+## Common Patterns
+
+```html
+<!-- Card with standard padding -->
+<div class="slds-card">
+  <div class="slds-card__header slds-p-around_medium">
+    <!-- 16px padding on all sides -->
+    Card Header
+  </div>
+  <div class="slds-card__body slds-p-horizontal_medium slds-p-vertical_small">
+    <!-- 16px left/right, 12px top/bottom -->
+    Card Content
+  </div>
+</div>
+
+<!-- Button with extra padding -->
+<button class="slds-button slds-button_neutral slds-p-horizontal_large">
+  <!-- 24px left and right padding for wider button -->
+  Wide Action Button
+</button>
+
+<!-- Form element spacing -->
+<div class="slds-form-element slds-p-bottom_small">
+  <!-- 12px bottom padding between form elements -->
+  <label class="slds-form-element__label">Field Label</label>
+  <div class="slds-form-element__control">
+    <input type="text" class="slds-input" />
+  </div>
+</div>
+
+<!-- Modal with appropriate padding -->
+<div class="slds-modal__container">
+  <div class="slds-modal__header slds-p-around_medium">
+    <!-- 16px padding in header -->
+    Modal Title
+  </div>
+  <div class="slds-modal__content slds-p-around_large">
+    <!-- 24px padding for modal body content -->
+    Modal content with comfortable spacing
+  </div>
+  <div class="slds-modal__footer slds-p-around_medium">
+    <!-- 16px padding in footer -->
+    Footer actions
+  </div>
+</div>
+
+<!-- List item with asymmetric padding -->
+<li class="slds-p-vertical_x-small slds-p-horizontal_medium">
+  <!-- 8px top/bottom, 16px left/right for list items -->
+  List item with comfortable touch target
+</li>
+```
+
+## Variable Density Classes
+
+Adapt padding to user density preferences (comfy/compact modes).
+
+| Class | Comfy Mode | Compact Mode |
+|-------|------------|--------------|
+| `slds-var-p-around_small` | 0.75rem (12px) | 0.375rem (6px) |
+| `slds-var-p-around_medium` | 1rem (16px) | 0.5rem (8px) |
+| `slds-var-p-around_large` | 1.5rem (24px) | 0.75rem (12px) |
+| `slds-var-p-horizontal_medium` | 1rem (16px) | 0.5rem (8px) |
+| `slds-var-p-vertical_medium` | 1rem (16px) | 0.5rem (8px) |
+
+## Common Use Cases
+
+| Use Case | Class | Value |
+|----------|-------|-------|
+| Card body padding | `slds-p-around_medium` | 16px all sides |
+| Button padding | `slds-p-horizontal_medium` | 16px left/right |
+| Modal content | `slds-p-around_large` | 24px all sides |
+| List item padding | `slds-p-vertical_x-small slds-p-horizontal_medium` | 8px top/bottom, 16px left/right |
+| Compact form fields | `slds-p-around_small` | 12px all sides |
+| Section padding | `slds-p-vertical_large` | 24px top/bottom |
+| Icon button padding | `slds-p-around_x-small` | 8px all sides |
+| Remove padding | `slds-p-around_none` | 0px all sides |
+
+## Best Practices
+
+✅ Use `slds-p-around_medium` (16px) for standard component padding
+✅ Use `slds-p-around_small` (12px) for compact layouts and dense information
+✅ Use `slds-p-around_large` (24px) for spacious layouts and primary content areas
+✅ Use `slds-p-horizontal_*` and `slds-p-vertical_*` for asymmetric padding
+✅ Use `slds-has-cushion` for quick default padding of 12px
+✅ Use variable density classes (`slds-var-p-*`) for responsive density
+
+❌ Avoid combining `slds-has-cushion` with other padding classes
+❌ Avoid using padding for external spacing between elements (use [Margin Utilities](ref:slds.guidance.utilities.margin) instead)
+❌ Avoid mixing different size scales within the same component
+❌ Avoid excessive padding that creates wasted space

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

@@ -0,0 +1,177 @@
+---
+id: slds.guidance.utilities.position
+title: Position Utilities
+description: SLDS CSS positioning utility classes
+summary: "Utilities for CSS positioning (static, relative, absolute, fixed). Controls element positioning for dropdowns, modals, and overlays."
+
+artifact_type: reference
+domain: utilities
+topic: position
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+
+tags: [utilities, position, css-positioning]
+keywords: [slds-is-relative, slds-is-absolute, slds-is-fixed, slds-is-static]
+---
+
+# Position - CSS Positioning Control
+
+CSS positioning including static, relative, absolute, and fixed positioning.
+
+## Core Classes
+
+| Class | CSS Property | Purpose |
+|-------|-------------|---------|
+| `slds-is-static` | `position: static` | Reset element to normal document flow |
+| `slds-is-relative` | `position: relative` | Position element relative to its normal position, create containing block for absolute children |
+| `slds-is-absolute` | `position: absolute` | Position element relative to nearest positioned ancestor |
+| `slds-is-fixed` | `position: fixed` | Position element relative to viewport |
+
+## Common Patterns
+
+### Dropdown Positioning
+```html
+<!-- Dropdown container with relative positioning -->
+<div class="slds-dropdown-trigger slds-is-relative">
+  <button class="slds-button">Actions</button>
+  <!-- Dropdown positioned absolutely below trigger -->
+  <div class="slds-dropdown slds-is-absolute" style="top: 100%; left: 0;">
+    <ul class="slds-dropdown__list">
+      <li class="slds-dropdown__item">Edit</li>
+      <li class="slds-dropdown__item">Delete</li>
+    </ul>
+  </div>
+</div>
+```
+
+### Modal Overlay
+```html
+<!-- Fixed position modal covering viewport -->
+<section class="slds-modal slds-is-fixed" style="top: 0; left: 0; right: 0; bottom: 0; z-index: 9000;">
+  <div class="slds-modal__container">
+    <div class="slds-modal__content">
+      Modal content here
+    </div>
+  </div>
+</section>
+<!-- Fixed backdrop behind modal -->
+<div class="slds-backdrop slds-is-fixed" style="top: 0; left: 0; width: 100%; height: 100%; z-index: 8999;"></div>
+```
+
+### Badge Indicator
+```html
+<!-- Icon with absolutely positioned badge -->
+<div class="slds-icon_container slds-is-relative">
+  <svg class="slds-icon slds-icon-text-default">
+    <use xlink:href="/assets/icons/utility-sprite.svg#notification"></use>
+  </svg>
+  <!-- Badge positioned at top-right corner -->
+  <span class="slds-badge slds-is-absolute" style="top: -4px; right: -4px;">
+    5
+  </span>
+</div>
+```
+
+### Tooltip Positioning
+```html
+<!-- Button with absolutely positioned tooltip -->
+<div class="slds-is-relative">
+  <button class="slds-button">Hover for info</button>
+  <!-- Tooltip positioned above button -->
+  <div class="slds-popover slds-is-absolute" style="bottom: 100%; left: 50%; transform: translateX(-50%); margin-bottom: 0.5rem;">
+    <div class="slds-popover__body">Helpful information</div>
+  </div>
+</div>
+```
+
+### Sticky Elements
+```html
+<!-- Use CSS sticky for header (not utility class) -->
+<header class="slds-page-header" style="position: sticky; top: 0; z-index: 100;">
+  Page header remains visible on scroll
+</header>
+
+<!-- Fixed action bar at bottom -->
+<div class="slds-is-fixed" style="bottom: 0; left: 0; right: 0; z-index: 100;">
+  <div class="slds-button-group">
+    <button class="slds-button slds-button_brand">Save</button>
+    <button class="slds-button slds-button_neutral">Cancel</button>
+  </div>
+</div>
+```
+
+## Best Practices
+
+✅ Use `slds-is-relative` on parent containers for absolutely positioned children
+✅ Use `slds-is-absolute` for dropdowns, tooltips, and popovers
+✅ Use `slds-is-fixed` for modals, backdrops, and viewport-relative elements
+✅ Always specify positioning coordinates (`top`, `right`, `bottom`, `left`)
+✅ Include appropriate `z-index` values for stacking context
+✅ Use `slds-is-static` to reset positioning when needed
+
+❌ Never use `slds-is-absolute` without a positioned ancestor
+❌ Avoid `slds-is-fixed` for elements that should scroll with content
+❌ Never position elements without defining coordinates
+❌ Avoid excessive z-index values (stay within defined ranges)
+
+## Z-Index Guidelines
+
+| Layer | Z-Index Range | Use For |
+|-------|---------------|---------|
+| Base content | 1-10 | Regular page elements |
+| Dropdowns | 5000-5999 | Dropdown menus, select lists |
+| Sticky elements | 6000-6999 | Sticky headers, navigation |
+| Modals | 9000-9999 | Modal dialogs, overlays |
+| Toasts | 10000+ | Toast notifications, alerts |
+
+### Z-Index Example
+```html
+<!-- Properly layered elements -->
+<div class="slds-dropdown slds-is-absolute" style="z-index: 5000;">Dropdown</div>
+<header class="slds-is-fixed" style="z-index: 6000;">Sticky header</header>
+<div class="slds-modal slds-is-fixed" style="z-index: 9000;">Modal</div>
+<div class="slds-notification slds-is-fixed" style="z-index: 10000;">Toast</div>
+```
+
+## Positioning Coordinates
+
+When using position utilities, always define coordinates:
+
+| Coordinate | Description | Example |
+|------------|-------------|---------|
+| `top` | Distance from top edge | `top: 0` or `top: 100%` |
+| `right` | Distance from right edge | `right: 0` or `right: 1rem` |
+| `bottom` | Distance from bottom edge | `bottom: 0` or `bottom: 100%` |
+| `left` | Distance from left edge | `left: 0` or `left: 50%` |
+
+### Coordinate Combinations
+```html
+<!-- Full coverage -->
+<div class="slds-is-fixed" style="top: 0; right: 0; bottom: 0; left: 0;">
+
+<!-- Top-right corner -->
+<div class="slds-is-absolute" style="top: 0; right: 0;">
+
+<!-- Centered horizontally -->
+<div class="slds-is-absolute" style="left: 50%; transform: translateX(-50%);">
+
+<!-- Bottom-aligned -->
+<div class="slds-is-absolute" style="bottom: 0; left: 0; right: 0;">
+```
+
+## Browser Compatibility
+
+All position utilities are fully supported in modern browsers:
+- Chrome 1+
+- Firefox 1+
+- Safari 1+
+- Edge 12+
+- No vendor prefixes required

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

@@ -0,0 +1,114 @@
+---
+id: slds.guidance.utilities.print
+title: Print Utilities
+description: SLDS print utility class for controlling element visibility when printing
+summary: "Utility class (.slds-no-print) for hiding elements when printing."
+
+artifact_type: reference
+domain: utilities
+topic: print
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [implement]
+
+refs:
+  - slds.guidance.utilities
+  - slds.guidance.overview.utilities
+
+tags: [utilities, print, visibility, media-query]
+keywords: [slds-no-print, print, hide-on-print]
+---
+
+# Print - Print Visibility Control
+
+Hiding elements when printing pages.
+
+## Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `slds-no-print` | Hides element when page is printed (display: none in @media print) |
+
+## Common Patterns
+
+```html
+<!-- Hide navigation when printing -->
+<nav class="slds-context-bar slds-no-print">
+  <!-- Navigation won't appear in printed output -->
+  <div class="slds-context-bar__primary">
+    Navigation Menu
+  </div>
+</nav>
+
+<!-- Hide action buttons when printing -->
+<div class="slds-page-header">
+  <div class="slds-page-header__title">
+    Report Title
+  </div>
+  <div class="slds-page-header__controls slds-no-print">
+    <!-- Buttons hidden in print -->
+    <button class="slds-button slds-button_neutral">Edit</button>
+    <button class="slds-button slds-button_brand">Save</button>
+  </div>
+</div>
+
+<!-- Hide UI controls on data table -->
+<table class="slds-table">
+  <thead>
+    <tr>
+      <th class="slds-no-print">
+        <!-- Checkbox column hidden in print -->
+        <input type="checkbox" />
+      </th>
+      <th>Name</th>
+      <th>Status</th>
+      <th class="slds-no-print">Actions</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td class="slds-no-print">
+        <input type="checkbox" />
+      </td>
+      <td>Record Name</td>
+      <td>Active</td>
+      <td class="slds-no-print">
+        <!-- Action buttons hidden in print -->
+        <button class="slds-button">Edit</button>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- Hide floating action button -->
+<div class="slds-fab slds-no-print">
+  <!-- Floating button hidden in print -->
+  <button class="slds-button slds-button_icon">
+    <svg class="slds-button__icon"><!-- Icon --></svg>
+  </button>
+</div>
+
+<!-- Hide page footer with metadata -->
+<footer class="slds-p-around_medium slds-no-print">
+  <!-- Footer info hidden in print -->
+  Last updated: Today at 3:45 PM
+  <br />
+  Page 1 of 10
+</footer>
+```
+
+## Best Practices
+
+✅ Use `slds-no-print` on navigation menus and app bars
+✅ Use `slds-no-print` on action buttons and interactive controls
+✅ Use `slds-no-print` on checkbox columns in data tables
+✅ Use `slds-no-print` on floating action buttons and overlays
+✅ Use `slds-no-print` on breadcrumbs and page metadata
+✅ Test print preview to ensure proper hiding of elements
+
+❌ Avoid hiding essential content that users need in printed output
+❌ Avoid hiding data table headers or important labels
+❌ Avoid hiding status badges or important visual indicators