@salesforce/mcp-provider-lwc-experts 0.6.3 → 0.6.4

package/knowledge/slds/styling-hooks/categories/spacing.md

@@ -0,0 +1,501 @@
+# SLDS Spacing System: Comprehensive Guide for Coding Agents
+
+## Overview
+
+The SLDS spacing system includes **48 spacing hooks** (10% of all 473 global hooks) that create consistent whitespace, rhythm, and visual hierarchy across interfaces. All spacing follows a **4-point grid system** aligned with the root font size.
+
+**Total Spacing Hooks:** 48
+
+- **Base Spacing:** 12 hooks (`spacing-1` through `spacing-12`)
+- **Density-Aware (All Sides):** 12 hooks (`spacing-var-1` through `spacing-var-12`)
+- **Density-Aware (Vertical):** 12 hooks (`spacing-var-block-1` through `spacing-var-block-12`)
+- **Density-Aware (Horizontal):** 12 hooks (`spacing-var-inline-1` through `spacing-var-12`)
+
+**Reference:** [SLDS Spacing and Sizing](https://www.lightningdesignsystem.com/2e1ef8501/p/03d6b0-spacing-and-sizing)
+
+---
+
+## Base Spacing Scale (`--slds-g-spacing-*`)
+
+### Complete Scale
+
+| Hook                  | Value   | Pixels @ 16px Root | Legacy Name | Common Use                        |
+| --------------------- | ------- | ------------------ | ----------- | --------------------------------- |
+| `--slds-g-spacing-1`  | 0.25rem | 4px                | xx-small    | Minimal gaps, tight spacing       |
+| `--slds-g-spacing-2`  | 0.5rem  | 8px                | x-small     | Icon-text gaps, compact padding   |
+| `--slds-g-spacing-3`  | 0.75rem | 12px               | small       | Small component padding           |
+| `--slds-g-spacing-4`  | 1rem    | 16px               | medium      | Standard padding, common margins  |
+| `--slds-g-spacing-5`  | 1.5rem  | 24px               | large       | Generous padding, section spacing |
+| `--slds-g-spacing-6`  | 2rem    | 32px               | x-large     | Large component spacing           |
+| `--slds-g-spacing-7`  | 2.5rem  | 40px               | xx-large    | Major section dividers            |
+| `--slds-g-spacing-8`  | 3rem    | 48px               | xxx-large   | Page section spacing              |
+| `--slds-g-spacing-9`  | 3.5rem  | 56px               | -           | Large layout spacing              |
+| `--slds-g-spacing-10` | 4rem    | 64px               | -           | Major layout divisions            |
+| `--slds-g-spacing-11` | 4.5rem  | 72px               | -           | Extra large spacing               |
+| `--slds-g-spacing-12` | 5rem    | 80px               | -           | Maximum spacing                   |
+
+### When to Use Base Spacing
+
+✅ **Use base spacing when:**
+
+- Fixed spacing is required regardless of density setting
+- Creating layout structures that shouldn't change
+- Defining spacing in non-interactive components
+- Setting gaps in flexbox/grid that should remain constant
+
+❌ **Don't use base spacing when:**
+
+- Component needs to adapt to user density preferences
+- Interactive elements need density-aware padding
+- Form elements should respond to compact/comfy modes
+
+---
+
+## Density-Aware Spacing
+
+SLDS provides three types of density-aware spacing that automatically adjust when users switch between **comfy** (default) and **compact** display modes.
+
+### All-Sides Spacing (`--slds-g-spacing-var-*`)
+
+Applies equally to top, bottom, left, and right. Use when padding should be uniform on all sides.
+
+| Hook                      | Comfy Value    | Compact Value  | Use For          |
+| ------------------------- | -------------- | -------------- | ---------------- |
+| `--slds-g-spacing-var-1`  | 0.25rem (4px)  | 0.125rem (2px) | Minimal padding  |
+| `--slds-g-spacing-var-2`  | 0.5rem (8px)   | 0.125rem (2px) | Tight padding    |
+| `--slds-g-spacing-var-3`  | 0.75rem (12px) | 0.25rem (4px)  | Small padding    |
+| `--slds-g-spacing-var-4`  | 1rem (16px)    | 0.5rem (8px)   | Standard padding |
+| `--slds-g-spacing-var-5`  | 1.5rem (24px)  | 0.75rem (12px) | Generous padding |
+| `--slds-g-spacing-var-6`  | 2rem (32px)    | 1rem (16px)    | Large padding    |
+| `--slds-g-spacing-var-7`  | 2.5rem (40px)  | 1.5rem (24px)  | XL padding       |
+| `--slds-g-spacing-var-8`  | 3rem (48px)    | 2rem (32px)    | XXL padding      |
+| `--slds-g-spacing-var-9`  | 3.5rem (56px)  | 2.5rem (40px)  | XXXL padding     |
+| `--slds-g-spacing-var-10` | 4rem (64px)    | 3rem (48px)    | Major padding    |
+| `--slds-g-spacing-var-11` | 4.5rem (72px)  | 3.5rem (56px)  | Extra large      |
+| `--slds-g-spacing-var-12` | 5rem (80px)    | 4rem (64px)    | Maximum padding  |
+
+**Example:**
+
+```css
+.card {
+  /* Adapts to density - uniform padding on all sides */
+  padding: var(--slds-g-spacing-var-4); /* 16px comfy, 8px compact */
+}
+```
+
+---
+
+### Vertical Spacing (`--slds-g-spacing-var-block-*`)
+
+Controls top and bottom spacing. Use with `padding-block` or `margin-block` CSS properties.
+
+| Hook                            | Comfy Value    | Compact Value  | Use For           |
+| ------------------------------- | -------------- | -------------- | ----------------- |
+| `--slds-g-spacing-var-block-1`  | 0.25rem (4px)  | 0.125rem (2px) | Minimal vertical  |
+| `--slds-g-spacing-var-block-2`  | 0.5rem (8px)   | 0.25rem (4px)  | Tight vertical    |
+| `--slds-g-spacing-var-block-3`  | 0.75rem (12px) | 0.5rem (8px)   | Small vertical    |
+| `--slds-g-spacing-var-block-4`  | 1rem (16px)    | 0.5rem (8px)   | Standard vertical |
+| `--slds-g-spacing-var-block-5`  | 1.5rem (24px)  | 0.75rem (12px) | Generous vertical |
+| `--slds-g-spacing-var-block-6`  | 2rem (32px)    | 1rem (16px)    | Large vertical    |
+| `--slds-g-spacing-var-block-7`  | 2.5rem (40px)  | 1.5rem (24px)  | XL vertical       |
+| `--slds-g-spacing-var-block-8`  | 3rem (48px)    | 2rem (32px)    | XXL vertical      |
+| `--slds-g-spacing-var-block-9`  | 3.5rem (56px)  | 2.5rem (40px)  | XXXL vertical     |
+| `--slds-g-spacing-var-block-10` | 4rem (64px)    | 3rem (48px)    | Major vertical    |
+| `--slds-g-spacing-var-block-11` | 4.5rem (72px)  | 3.5rem (56px)  | Extra large       |
+| `--slds-g-spacing-var-block-12` | 5rem (80px)    | 4rem (64px)    | Maximum vertical  |
+
+**Example:**
+
+```css
+.list-item {
+  /* Vertical padding adapts to density */
+  padding-block: var(--slds-g-spacing-var-block-3); /* 12px comfy, 8px compact */
+  padding-inline: var(--slds-g-spacing-4); /* Fixed horizontal */
+}
+```
+
+---
+
+### Horizontal Spacing (`--slds-g-spacing-var-inline-*`)
+
+Controls left and right spacing. Use with `padding-inline` or `margin-inline` CSS properties.
+
+| Hook                             | Comfy Value    | Compact Value  | Use For             |
+| -------------------------------- | -------------- | -------------- | ------------------- |
+| `--slds-g-spacing-var-inline-1`  | 0.25rem (4px)  | 0.125rem (2px) | Minimal horizontal  |
+| `--slds-g-spacing-var-inline-2`  | 0.5rem (8px)   | 0.25rem (4px)  | Tight horizontal    |
+| `--slds-g-spacing-var-inline-3`  | 0.75rem (12px) | 0.5rem (8px)   | Small horizontal    |
+| `--slds-g-spacing-var-inline-4`  | 1rem (16px)    | 0.75rem (12px) | Standard horizontal |
+| `--slds-g-spacing-var-inline-5`  | 1.5rem (24px)  | 0.75rem (12px) | Generous horizontal |
+| `--slds-g-spacing-var-inline-6`  | 2rem (32px)    | 1rem (16px)    | Large horizontal    |
+| `--slds-g-spacing-var-inline-7`  | 2.5rem (40px)  | 1.5rem (24px)  | XL horizontal       |
+| `--slds-g-spacing-var-inline-8`  | 3rem (48px)    | 2rem (32px)    | XXL horizontal      |
+| `--slds-g-spacing-var-inline-9`  | 3.5rem (56px)  | 2.5rem (40px)  | XXXL horizontal     |
+| `--slds-g-spacing-var-inline-10` | 4rem (64px)    | 3rem (48px)    | Major horizontal    |
+| `--slds-g-spacing-var-inline-11` | 4.5rem (72px)  | 3.5rem (56px)  | Extra large         |
+| `--slds-g-spacing-var-inline-12` | 5rem (80px)    | 4rem (64px)    | Maximum horizontal  |
+
+**Example:**
+
+```css
+.button {
+  /* Horizontal padding adapts, vertical doesn't */
+  padding-block: var(--slds-g-spacing-3); /* Fixed 12px */
+  padding-inline: var(--slds-g-spacing-var-inline-4); /* 16px comfy, 12px compact */
+}
+```
+
+---
+
+## Decision Tree: Which Spacing Hook to Use?
+
+```
+1. Does this element need to adapt to user density preference?
+   ├─ NO → Use base spacing (--slds-g-spacing-*)
+   └─ YES → Continue to step 2
+
+2. Should spacing be uniform on all sides?
+   ├─ YES → Use all-sides var (--slds-g-spacing-var-*)
+   └─ NO → Continue to step 3
+
+3. Is this primarily vertical spacing (top/bottom)?
+   ├─ YES → Use block var (--slds-g-spacing-var-block-*)
+   └─ NO → Continue to step 4
+
+4. Is this primarily horizontal spacing (left/right)?
+   ├─ YES → Use inline var (--slds-g-spacing-var-inline-*)
+   └─ NO → Mix block + inline vars, or use all-sides
+```
+
+---
+
+## Common Patterns for Agents
+
+### Pattern 1: Button with Density-Aware Padding
+
+```css
+.button {
+  /* Horizontal padding adapts to density */
+  padding-inline: var(--slds-g-spacing-var-inline-4); /* 16px → 12px compact */
+
+  /* Vertical padding adapts to maintain target size */
+  padding-block: var(--slds-g-spacing-var-block-2); /* 8px → 4px compact */
+
+  /* Gap between icon and text (fixed) */
+  gap: var(--slds-g-spacing-2); /* Always 8px */
+
+  /* External margin (fixed) */
+  margin-right: var(--slds-g-spacing-3); /* Always 12px */
+}
+```
+
+### Pattern 2: Card Layout with Mixed Spacing
+
+```css
+.card {
+  /* Internal padding adapts to density */
+  padding: var(--slds-g-spacing-var-4); /* 16px → 8px compact */
+
+  /* External margin stays fixed */
+  margin-bottom: var(--slds-g-spacing-4); /* Always 16px */
+
+  /* Border radius (not spacing - hard-coded) */
+  border-radius: 0.25rem;
+}
+
+.card-header {
+  /* Smaller padding inside card */
+  padding-block: var(--slds-g-spacing-var-block-3); /* 12px → 8px */
+  border-bottom: 1px solid var(--slds-g-color-palette-neutral-80);
+}
+
+.card-body {
+  /* Standard padding */
+  padding: var(--slds-g-spacing-var-4);
+}
+```
+
+### Pattern 3: Form with Adaptive Spacing
+
+```css
+.form-group {
+  /* Vertical spacing between form fields (fixed) */
+  margin-bottom: var(--slds-g-spacing-4); /* Always 16px */
+}
+
+.input {
+  /* Input padding adapts to density */
+  padding: var(--slds-g-spacing-var-3); /* 12px → 4px compact */
+
+  /* Or use directional for asymmetric padding */
+  padding-block: var(--slds-g-spacing-var-block-2); /* 8px → 4px */
+  padding-inline: var(--slds-g-spacing-var-inline-3); /* 12px → 8px */
+}
+
+.label {
+  /* Label margin (fixed) */
+  margin-bottom: var(--slds-g-spacing-2); /* Always 8px */
+}
+```
+
+### Pattern 4: List with Density-Aware Items
+
+```css
+.list {
+  /* Container padding (fixed) */
+  padding: var(--slds-g-spacing-4); /* Always 16px */
+
+  /* Gap between items (fixed) */
+  gap: var(--slds-g-spacing-2); /* Always 8px */
+}
+
+.list-item {
+  /* Item padding adapts vertically */
+  padding-block: var(--slds-g-spacing-var-block-3); /* 12px → 8px compact */
+
+  /* Item padding fixed horizontally */
+  padding-inline: var(--slds-g-spacing-4); /* Always 16px */
+
+  /* Border separation */
+  border-bottom: 1px solid var(--slds-g-color-palette-neutral-80);
+}
+
+.list-item:last-child {
+  border-bottom: none;
+}
+```
+
+### Pattern 5: Page Layout Structure
+
+```css
+.page-container {
+  /* Large fixed padding for page structure */
+  padding: var(--slds-g-spacing-6); /* Always 32px */
+}
+
+.section {
+  /* Section spacing (fixed) */
+  margin-bottom: var(--slds-g-spacing-7); /* Always 40px */
+}
+
+.section-header {
+  /* Header padding adapts */
+  padding-block: var(--slds-g-spacing-var-block-4); /* 16px → 8px */
+  margin-bottom: var(--slds-g-spacing-4); /* Fixed 16px */
+}
+
+.section-content {
+  /* Content padding (fixed for consistency) */
+  padding: var(--slds-g-spacing-5); /* Always 24px */
+}
+```
+
+---
+
+## Accessibility Considerations
+
+### Target Size Requirements
+
+Spacing is **the primary method** for achieving minimum interactive target sizes:
+
+#### WCAG 2.2 Requirements:
+
+- **Desktop/Pointer:** Minimum 24×24px (AA), 44×44px recommended (AAA)
+- **Mobile/Touch:** Minimum 44×44pt/dp/px
+- **Salesforce Default:** 44×44px for consistency across environments
+
+#### Using Spacing for Target Sizes:
+
+```css
+/* ✅ COMPLIANT - Button achieves 44×44px target */
+.button-small {
+  /* Text is ~14px, line-height ~20px */
+  padding-block: var(--slds-g-spacing-var-block-4); /* 16px top+bottom = 32px */
+  padding-inline: var(--slds-g-spacing-var-inline-4); /* 16px each side */
+  /* Total height: 20px text + 32px padding = 52px (compliant) */
+}
+
+/* ⚠️ BORDERLINE - May fall below 44px in compact mode */
+.button-compact {
+  padding-block: var(--slds-g-spacing-var-block-3); /* 12px → 8px compact */
+  /* Comfy: 20px + 24px = 44px ✅ */
+  /* Compact: 20px + 16px = 36px ❌ (non-compliant) */
+}
+
+/* ✅ BETTER - Maintains compliance in both modes */
+.button-adaptive {
+  /* Use larger var or fixed spacing for critical targets */
+  padding-block: var(--slds-g-spacing-4); /* Always 16px = 52px total ✅ */
+  padding-inline: var(--slds-g-spacing-var-inline-4); /* Can adapt */
+}
+```
+
+### Spacing Exception
+
+Interactive elements **smaller than 24×24px** are acceptable if:
+
+- Sufficient spacing ensures a **24px diameter circle** around each target doesn't intersect another target
+- This means minimum `--slds-g-spacing-6` (32px) between small targets
+
+```css
+/* ✅ ACCEPTABLE - Small icon buttons with spacing */
+.icon-button-small {
+  width: 20px;
+  height: 20px;
+  margin: var(--slds-g-spacing-3); /* 12px = 24px total space around */
+}
+```
+
+### Readability and Scannability
+
+- **Consistent spacing** improves scanability for all users
+- **Adequate spacing** between interactive elements supports users with motor impairments
+- **Clear visual grouping** through spacing helps users with cognitive disabilities
+- **Vertical rhythm** supports readability
+
+---
+
+## Common Mistakes and Solutions
+
+### Mistake 1: Using Named Hooks
+
+```css
+/* ❌ WRONG - These don't exist */
+.element {
+  padding: var(--slds-g-spacing-small);
+  margin: var(--slds-g-spacing-medium);
+}
+
+/* ✅ CORRECT - Use numbered hooks */
+.element {
+  padding: var(--slds-g-spacing-3); /* 12px */
+  margin: var(--slds-g-spacing-4); /* 16px */
+}
+```
+
+### Mistake 2: Using Spacing for Dimensions
+
+```css
+/* ❌ WRONG - Don't use spacing for width/height */
+.box {
+  width: var(--slds-g-spacing-12);
+  height: var(--slds-g-spacing-10);
+}
+
+/* ✅ CORRECT - Use sizing hooks or hard-code */
+.box {
+  width: var(--slds-g-sizing-12); /* If sizing hooks available */
+  height: 5rem; /* Or hard-code with comment */
+}
+```
+
+### Mistake 3: Mixing Density Types Inconsistently
+
+```css
+/* ⚠️ INCONSISTENT - Mixing strategies without reason */
+.element {
+  padding-top: var(--slds-g-spacing-var-block-3);
+  padding-right: var(--slds-g-spacing-4);
+  padding-bottom: var(--slds-g-spacing-var-2);
+  padding-left: var(--slds-g-spacing-var-inline-4);
+}
+
+/* ✅ BETTER - Consistent approach */
+.element {
+  padding-block: var(--slds-g-spacing-var-block-3);
+  padding-inline: var(--slds-g-spacing-var-inline-4);
+}
+
+/* ✅ OR - All fixed if density shouldn't change */
+.element {
+  padding: var(--slds-g-spacing-3) var(--slds-g-spacing-4);
+}
+```
+
+### Mistake 4: Hard-Coding Pixel Values
+
+```css
+/* ❌ WRONG - Hard-coded values */
+.element {
+  padding: 16px;
+  margin: 24px;
+  gap: 8px;
+}
+
+/* ✅ CORRECT - Use spacing hooks */
+.element {
+  padding: var(--slds-g-spacing-4); /* 16px */
+  margin: var(--slds-g-spacing-5); /* 24px */
+  gap: var(--slds-g-spacing-2); /* 8px */
+}
+```
+
+---
+
+## Summary for Coding Agents
+
+### Quick Selection Guide
+
+**For fixed spacing that never changes:**
+
+- Use `--slds-g-spacing-[1-12]`
+- Common: `spacing-2` (8px), `spacing-4` (16px), `spacing-5` (24px)
+
+**For interactive components that adapt to density:**
+
+- Uniform padding: `--slds-g-spacing-var-[1-12]`
+- Vertical only: `--slds-g-spacing-var-block-[1-12]`
+- Horizontal only: `--slds-g-spacing-var-inline-[1-12]`
+
+**Most Common Hooks:**
+
+- `spacing-2` (8px) - Icon gaps, small margins
+- `spacing-3` (12px) - Small padding, label margins
+- `spacing-4` (16px) - Standard padding/margins
+- `spacing-5` (24px) - Generous padding
+- `spacing-6` (32px) - Large component spacing
+
+### Search for Hooks
+
+```javascript
+// Find all spacing hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-g-spacing-' });
+
+// Find density-aware hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'spacing-var' });
+
+// Check specific hook
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ hooks: ['--slds-g-spacing-4'] });
+```
+
+### Key Rules
+
+1. ✅ Use numbered hooks (1-12), not named (small/medium/large)
+2. ✅ Use density-aware hooks for interactive components
+3. ✅ Use fixed spacing for layout structure
+4. ✅ Maintain 44×44px minimum target sizes with padding
+5. ❌ Never use spacing hooks for element dimensions (width/height)
+6. ❌ Never hard-code pixel values when hooks exist
+
+---
+
+**References:**
+
+- [SLDS Spacing and Sizing](https://www.lightningdesignsystem.com/2e1ef8501/p/03d6b0-spacing-and-sizing)
+- [Complete Hooks Index](../metadata/hooks-index.json)
+- [Guidance Overview](../guidance.md)