@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/applying-slds/guidance/styling-hooks/index.md

@@ -0,0 +1,327 @@
+---
+id: slds.guidance.hooks
+title: SLDS Styling Hooks - Agent Guidance
+description: Comprehensive guidance for using SLDS styling hooks in component development
+summary: "Entry point for all styling hooks guidance. Covers the three-tier hook hierarchy (global, shared, component), core categories (color, spacing, typography, shadows, borders), usage patterns, decision trees, and accessibility requirements. Use styling hooks instead of hard-coded values for theme-aware, maintainable components."
+
+artifact_type: index
+domain: styling-hooks
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, implement, troubleshoot]
+
+children:
+  - slds.guidance.hooks.color
+  - slds.guidance.hooks.typography
+  - slds.guidance.hooks.spacing
+  - slds.guidance.hooks.borders
+  - slds.guidance.hooks.shadows
+
+refs:
+  - slds.guidance.hooks.shadows
+  - slds.guidance.hooks.borders
+tags: [styling-hooks, index, color, spacing, typography, shadows, borders, theming]
+keywords: [styling hooks, CSS custom properties, theming, accessibility, design tokens, SLDS]
+---
+
+# SLDS Styling Hooks: Guidance for Coding Agents
+
+## Overview
+
+The Salesforce Lightning Design System (SLDS) styling hooks are CSS custom properties that provide a theme-aware, maintainable styling system. When generating or optimizing SLDS components, **always use styling hooks instead of hard-coded values** to ensure components adapt automatically to:
+
+- Brand themes and customizations
+- Light/dark mode switches
+- Density settings (compact, comfy, spacious)
+- Accessibility requirements
+- Future design system updates
+
+**Critical Rule:** Reference styling hooks using `var()` — never reassign their values. Salesforce controls these values and can change them at any time.
+
+---
+
+## Styling Hook Hierarchy
+
+SLDS styling hooks follow a three-tier naming convention:
+
+1. **Global Semantic** (`--slds-g-*`): System-wide hooks for universal use across all components
+2. **Shared** (`--slds-s-*`): Private/internal hooks — **DO NOT USE** (reserved for Salesforce)
+3. **Component-Specific** (`--slds-c-*`): Hooks scoped to individual component types for fine-tuning
+
+**Always use global hooks (`--slds-g-*`) unless component-specific hooks exist for your use case.**
+
+---
+
+## Core Categories
+
+### 1. Color Hooks (`--slds-g-color-*`)
+
+SLDS provides a comprehensive color system organized into three tiers:
+
+#### **Tier 1: Semantic UI Colors (PREFERRED)**
+
+Purpose-driven colors that automatically adapt to themes and modes:
+
+- **Surface** (`surface-*`): Page backgrounds, panels, modal overlays
+- **Container** (`container-*`): Buttons, cards, tabs, input fields
+- **Accent** (`accent-*`): Brand emphasis and selection states
+- **Border** (`border-*`): Component borders, dividers, separators
+- **Feedback** (`feedback-*`): Alerts, notifications, validation states
+- **On-Colors** (`on-*`): Text and icons on colored backgrounds
+
+#### **Tier 2: System Colors**
+
+Accessible, system-wide colors for edge cases where semantic colors don't apply.
+
+#### **Tier 3: Palette Colors (Use Sparingly)**
+
+Raw color values for data visualization and custom scenarios.
+
+> **💡 Detailed color guidance:** See [Color Styling Hooks Index](ref:slds.guidance.hooks.color) for the complete color system documentation.
+
+---
+
+### 2. Spacing Hooks (`--slds-g-spacing-*`)
+
+SLDS uses a numbered scale (NOT named like "small/medium/large"):
+
+| Hook Name             | Value   | Pixels | Legacy Equivalent |
+| --------------------- | ------- | ------ | ----------------- |
+| `--slds-g-spacing-1`  | 0.25rem | 4px    | xx-small          |
+| `--slds-g-spacing-2`  | 0.5rem  | 8px    | x-small           |
+| `--slds-g-spacing-3`  | 0.75rem | 12px   | small             |
+| `--slds-g-spacing-4`  | 1rem    | 16px   | medium            |
+| `--slds-g-spacing-5`  | 1.5rem  | 24px   | large             |
+| `--slds-g-spacing-6`  | 2rem    | 32px   | x-large           |
+| `--slds-g-spacing-7`  | 2.5rem  | 40px   | xx-large          |
+| `--slds-g-spacing-8`  | 3rem    | 48px   | xxx-large         |
+| `--slds-g-spacing-9`  | 3.5rem  | 56px   | -                 |
+| `--slds-g-spacing-10` | 4rem    | 64px   | -                 |
+| `--slds-g-spacing-11` | 4.5rem  | 72px   | -                 |
+| `--slds-g-spacing-12` | 5rem    | 80px   | -                 |
+
+**Usage:**
+
+```css
+/* Use numbered hooks - NOT named ones */
+margin: var(--slds-g-spacing-4); /* ✅ Correct */
+padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4); /* ✅ Correct */
+
+/* DON'T use named hooks - they don't exist */
+margin: var(--slds-g-spacing-medium); /* ❌ Wrong - hook doesn't exist */
+```
+
+> **💡 Detailed spacing guidance:** See [Spacing and Sizing Hooks](ref:slds.guidance.hooks.spacing) for complete documentation.
+
+---
+
+### 3. Typography Hooks (`--slds-g-font-*`)
+
+#### Font Families
+
+- `--slds-g-font-family` - Default font family
+- `--slds-g-font-family-base` - Base font family
+- `--slds-g-font-family-monospace` - For code snippets
+
+#### Font Weights (Numbered 1-7)
+
+| Hook Name                | Typical Value | Common Name |
+| ------------------------ | ------------- | ----------- |
+| `--slds-g-font-weight-1` | 300           | Light       |
+| `--slds-g-font-weight-2` | 300           | Light       |
+| `--slds-g-font-weight-3` | 400           | Regular     |
+| `--slds-g-font-weight-4` | 400           | Regular     |
+| `--slds-g-font-weight-5` | 500           | Medium      |
+| `--slds-g-font-weight-6` | 600           | Semi-Bold   |
+| `--slds-g-font-weight-7` | 700           | Bold        |
+
+**Usage:**
+
+```css
+/* Use numbered hooks */
+font-weight: var(--slds-g-font-weight-7); /* Bold */
+
+/* DON'T use named hooks - they don't exist */
+font-weight: var(--slds-g-font-weight-bold); /* ❌ Wrong */
+```
+
+> **💡 Detailed typography guidance:** See [Typography Styling Hooks](ref:slds.guidance.hooks.typography) for complete documentation.
+
+---
+
+### 4. Other Styling Hooks
+
+- **Sizing** (`--slds-g-sizing-*`): Component dimensions, icon sizes, border widths
+- **Shadow** (`--slds-g-shadow-*`): Elevation and depth effects
+- **Radius** (`--slds-g-radius-*`): Border radius values for rounded corners
+
+---
+
+## Usage Patterns
+
+### Pattern 1: Interactive Component States (Accent Colors)
+
+```css
+.button {
+  background: var(--slds-g-color-accent-container-1);
+  color: var(--slds-g-color-on-accent-1);
+  border: 1px solid var(--slds-g-color-border-accent-1);
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+  border-radius: var(--slds-g-radius-border-1);
+}
+
+.button:hover {
+  background: var(--slds-g-color-accent-container-2);
+  color: var(--slds-g-color-on-accent-2);
+  border-color: var(--slds-g-color-border-accent-2);
+}
+
+.button:active {
+  background: var(--slds-g-color-accent-container-3);
+  color: var(--slds-g-color-on-accent-3);
+  border-color: var(--slds-g-color-border-accent-3);
+}
+```
+
+### Pattern 2: Semantic Surfaces
+
+```css
+.card {
+  background: var(--slds-g-color-surface-container-1);
+  color: var(--slds-g-color-on-surface-1);
+  padding: var(--slds-g-spacing-4);
+  border: 1px solid var(--slds-g-color-border-1);
+  border-radius: var(--slds-g-radius-border-1);
+}
+```
+
+### Pattern 3: Feedback States
+
+```css
+.alert-error {
+  background: var(--slds-g-color-error-container-1);
+  color: var(--slds-g-color-on-error-1);
+  border-left: 4px solid var(--slds-g-color-error-1);
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+}
+
+.alert-success {
+  background: var(--slds-g-color-success-container-1);
+  color: var(--slds-g-color-on-success-1);
+  border-left: 4px solid var(--slds-g-color-success-1);
+}
+```
+
+---
+
+## Decision Tree for Coding Agents
+
+### Step 1: Check for Component-Specific Hooks
+
+Search for `--slds-c-[component-name]-*` hooks first (highest specificity).
+
+### Step 2: Use Semantic UI Colors (Preferred)
+
+For colors, prefer semantic hooks:
+
+- **Surface/Container**: `surface-1/2/3`, `surface-container-1/2/3`, `on-surface-1/2/3`
+- **Accent**: `accent-1/2/3`, `accent-container-1/2/3`, `border-accent-1/2/3`, `on-accent-1/2/3`
+- **Feedback**: `error-1`, `success-1`, `warning-1`, `info-1` with their container and on-color variants
+
+### Step 3: Use Numbered Spacing & Typography
+
+Always use numbered hooks where available:
+
+```css
+padding: var(--slds-g-spacing-4);
+font-weight: var(--slds-g-font-weight-5);
+font-size: var(--slds-g-font-size-base); /* Or use rem values */
+```
+
+---
+
+## Critical Rules
+
+### ✅ DO:
+
+- Reference hooks with `var()`: `color: var(--slds-g-color-accent-1);`
+- Use numbered spacing: `spacing-4` not `spacing-medium`
+- Use numbered font weights: `font-weight-5` not `font-weight-medium`
+- Prefer semantic UI colors over system colors and palette colors
+- Pair container colors with on-colors for text/icons
+- Follow the 50-point rule for text contrast, 40-point rule for UI elements
+
+### ❌ DON'T:
+
+- Reassign hook values: `--slds-g-color-accent-1: #ff0000;` ❌
+- Use private hooks (`--_slds-*` or `--slds-s-*`)
+- Use `@layer` syntax (reserved for Salesforce)
+- Use named spacing hooks (`spacing-small`, `spacing-medium`) - they don't exist
+- Use named font hooks (`font-weight-medium`, `font-weight-bold`) - they don't exist
+- Hard-code values when hooks exist
+
+---
+
+## Accessibility Compliance
+
+### Color Contrast Rules
+
+| Separation | Contrast Ratio | Use Case                   |
+| ---------- | -------------- | -------------------------- |
+| 50 points  | 4.5:1          | Text (WCAG AA)             |
+| 40 points  | 3:1            | UI elements, borders       |
+
+### Automatic Compliance with Semantic Colors
+
+When using semantic accent colors, SLDS ensures contrast automatically:
+
+```css
+/* ✅ ALWAYS COMPLIANT when using matching pairs */
+.accent-button {
+  background: var(--slds-g-color-accent-container-1);
+  color: var(--slds-g-color-on-accent-1); /* Pre-validated pairing */
+}
+```
+
+---
+
+## Troubleshooting
+
+### Problem: Hook name not working
+
+**Solution:** Verify naming convention:
+
+- Use numbered spacing: `spacing-4` NOT `spacing-medium`
+- Use numbered fonts: `font-weight-5` NOT `font-weight-medium`
+
+### Problem: Colors have poor contrast
+
+**Solution:**
+
+- Use semantic hooks with paired on-colors
+- For palette: 50-point separation for text, 40-point for UI elements
+
+### Problem: Spacing inconsistent
+
+**Solution:**
+
+- Use numbered spacing hooks: `spacing-2`, `spacing-4`
+- Check spacing scale: 8px=spacing-2, 16px=spacing-4, 24px=spacing-5
+
+---
+
+## Summary
+
+When generating or optimizing SLDS components:
+
+1. **Use semantic hooks first** — Prefer semantic UI colors over system/palette
+2. **Use numbered hooks** — spacing-4, font-weight-5 (NOT named like "medium")
+3. **Font sizes** — Use `font-size-base` or rem values
+4. **Follow the three-tier color system** — Semantic UI → System Colors → Expressive Palette
+5. **Pair containers with on-colors** — Use `on-surface-*`, `on-accent-*`, `on-error-*` for text/icons
+6. **Test accessibility** — Verify contrast ratios and keyboard navigation
+
+**The goal:** Build theme-aware, accessible components that adapt automatically to brand customizations, light/dark modes, and density settings.

package/skills/applying-slds/guidance/styling-hooks/shadows.md

@@ -0,0 +1,238 @@
+---
+id: slds.guidance.hooks.shadows
+title: Shadows Styling Hooks
+description: Styling hooks for depth shadows, directional shadows, and inset shadows
+summary: "Guidance for shadow styling hooks that establish visual hierarchy and elevation. Covers depth shadows (1-4), directional shadows, and inset shadows for pressed/focused states."
+
+artifact_type: reference
+domain: styling-hooks
+topic: shadows
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, implement, troubleshoot]
+
+refs:
+  - slds.guidance.hooks
+  - slds.guidance.hooks.borders
+  - slds.guidance.hooks.color.surface
+tags: [styling-hooks, shadows, elevation, depth, visual-hierarchy]
+keywords: [shadow depth, elevation, stacking order, directional shadow, inset shadow, focus shadow]
+---
+
+# Shadows Styling Hooks
+
+## Overview
+
+Shadow styling hooks establish visual hierarchy, depth, and elevation in UI interfaces. All shadow styling hooks are prefixed with `--slds-g-` for global scope, `--slds-s-` for shared scope, or `--slds-c-` for component scope, followed by the shadow name. For example, `--slds-g-shadow-1` is the styling hook for a shadow depth of 1.
+
+---
+
+## `--slds-g-shadow-*`
+
+### Description
+
+Depth shadow hooks communicate elevation and visual hierarchy. Use these hooks to indicate which elements appear above others in the stacking order. Higher shadow values indicate elements that are visually higher in the stacking order.
+
+**Hook Pattern:** `--slds-g-shadow-{n}` where `{n}` is the depth level
+
+### Usage
+
+####  Do
+
+- Match shadow values to stacking order — elements with higher stacking order should have higher shadow values
+- Leverage z-index to manage stacking order alongside shadow values
+- Use depth shadows for elements that need to appear above the base surface
+
+####  Don't
+
+- Avoid applying shadows to base level components — components that sit on the surface and don't cover other components should not have shadows in SLDS 2
+
+#### Context
+
+| Shadow Hook | Components |
+|-------------|------------|
+| `--slds-g-shadow-1` | Page headers, joined tables, filter panels, dropdowns, inline edit, images, slider handles |
+| `--slds-g-shadow-2` | Menu, docked form footer, docked utility bar, color picker, notifications |
+| `--slds-g-shadow-3` | Panel, docked composer, tooltip, toast |
+| `--slds-g-shadow-4` | Modal, popover, App Launcher |
+
+**Note:** `shadow-5` and `shadow-6` are aliases that inherit from `shadow-4`.
+
+---
+
+## `--slds-g-shadow-{direction}-*`
+
+### Description
+
+Directional shadow hooks allow shadows to be cast in specific directions. Use these hooks for components positioned against edges of the screen where the shadow direction matters.
+
+**Hook Pattern:** `--slds-g-shadow-{direction}-{n}` where `{direction}` is the shadow direction and `{n}` is the depth level
+
+**Available Directions:**
+- `block-start` — Upward shadow
+- `block-end` — Downward shadow (inherits from base `shadow-{n}`)
+- `inline-start` — Left shadow
+- `inline-end` — Right shadow
+
+### Usage
+
+####  Do
+
+- Use directional shadows for panels and side-docked components
+- Use directional shadows when components are positioned against screen edges
+- Use `shadow-3 left` or `shadow-3 right` on panels depending on screen position
+
+#### Context
+
+- Panels use directional shadows based on which side of the screen they are placed
+- `block-start` and `block-end` follow CSS logical properties (vertical axis)
+- `inline-start` and `inline-end` follow CSS logical properties (horizontal axis)
+
+---
+
+## `--slds-g-shadow-{type}-focus-*`
+
+### Description
+
+Focus shadow hooks provide visual feedback for keyboard navigation and accessibility. Use these hooks to ensure focus states meet accessibility requirements across all backgrounds.
+
+**Hook Pattern:** `--slds-g-shadow-{type}-focus-{n}` where `{type}` is the focus style and `{n}` is the focus level
+
+**Available Types:**
+- `outline-focus` — Simple outline focus
+- `outset-focus` — Double ring outset focus (white inner ring, brand outer ring)
+- `inset-focus` — Single ring inset focus
+- `inset-inverse-focus` — Double ring inset focus (brand inner, white outer)
+
+### Usage
+
+####  Do
+
+- Focus states within SLDS 2 consist of a white border outline surrounded by a dark blue border outline
+- This style ensures that the focus state passes accessibility requirements on any background
+
+#### Context
+
+- Focus states within enhanced Lightning UI are applied via shadow
+- The double-ring focus pattern provides sufficient contrast on both light and dark backgrounds
+
+### Accessibility
+
+- Focus shadows ensure minimum 3:1 contrast against any background color
+- The white + dark blue double-ring pattern guarantees visibility on both light and dark backgrounds
+- Focus visibility is required for WCAG 2.1 keyboard navigation compliance
+- Accessibility requirements apply — consult your project's accessibility standards
+
+---
+
+## `--slds-s-button-shadow-*`
+
+### Description
+
+Button shadow hooks control the visual states for button interactions. Use these hooks for focus, active (pressed), and hover states on buttons.
+
+**Available Hooks:**
+- `--slds-s-button-shadow-focus` — Focus state for neutral buttons
+- `--slds-s-button-shadow-focus-inverse` — Focus state for inverse buttons
+- `--slds-s-button-shadow-active` — Pressed/active state (inset shadow)
+- `--slds-s-button-brand-shadow-hover` — Hover lift effect for brand buttons
+- `--slds-s-button-bordered-shadow-hover` — Hover lift effect for bordered/neutral buttons
+
+### Usage
+
+####  Do
+
+- Button components use a hover bevel and inner shadow on click that is separate from the elevation system
+- `button-shadow-active` is used on all buttons when pressed, regardless of color or border
+
+####  Don't
+
+- Avoid using bevel and inset shadows in custom situations — they are only used on buttons and inputs where specified
+
+#### Context
+
+- Active state uses inset shadows to create a "pressed in" appearance
+- Hover state uses drop shadows with transform for a "lift" effect
+- Focus state uses the standard focus ring pattern
+
+---
+
+## `--slds-s-input-shadow-*`
+
+### Description
+
+Input shadow hooks control the visual states for input field interactions. Use these hooks for focus and validation states on input containers.
+
+**Available Hooks:**
+- `--slds-s-input-shadow-focus` — Focus state for input containers (includes inset shadow + focus ring)
+- `--slds-s-input-shadow-invalid` — Error state for input containers
+
+### Usage
+
+####  Do
+
+- Input focus combines an inset shadow with the standard focus ring
+- Use input shadow hooks for text inputs, comboboxes, and text areas
+
+####  Don't
+
+- Avoid using input inset shadows in custom situations — they are only used where specified in the design system
+
+#### Context
+
+- Focus state combines visual depth (inset shadow) with accessibility (focus ring)
+- Invalid state may remove shadows to emphasize the error border treatment
+
+---
+
+## `--slds-s-mark-shadow-*`
+
+### Description
+
+Mark shadow hooks control the visual states for checkbox, radio button, and toggle interactions. Use these hooks for focus and checked states on mark elements.
+
+**Available Hooks:**
+- `--slds-s-mark-shadow-focus` — Focus state for checkboxes, radios, and toggles
+- `--slds-s-mark-shadow-checked` — Checked/selected state (inset shadow)
+
+### Usage
+
+####  Do
+
+- `mark-shadow-checked` is used on selected or active checkboxes, radio buttons, and checkbox toggles
+- Use mark shadow hooks for indicating the selected state with visual depth
+
+####  Don't
+
+- Avoid using mark inset shadows in custom situations — they are only used on marks where specified
+
+#### Context
+
+- Checked state uses inset shadow to create visual depth indicating selection
+- Focus state uses the standard focus ring pattern for accessibility
+
+---
+
+## `--slds-c-button-{variant}-shadow-hover`
+
+### Description
+
+Component-level button variant shadow hooks provide hover effects for specific button variants. Use these hooks when implementing success, destructive, or inverse button variants.
+
+**Available Hooks:**
+- `--slds-c-button-success-shadow-hover` — Hover shadow for success buttons
+- `--slds-c-button-destructive-shadow-hover` — Hover shadow for destructive buttons
+- `--slds-c-button-inverse-shadow-hover` — Hover shadow for inverse buttons
+
+### Usage
+
+#### Context
+
+- These hooks provide variant-specific hover lift effects
+- Each uses a tinted shadow that matches the button's color scheme
+- Used in combination with transform for the lift animation effect
+
+