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

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

@@ -0,0 +1,667 @@
+# SLDS Sizing Styling Hooks
+
+**Category:** Layout / Dimensions  
+**Total Hooks:** 26 sizing hooks (16 general + 4 border + 6 typography-width)  
+**Purpose:** Define element dimensions with consistent, scalable values
+
+---
+
+## Overview
+
+Sizing styling hooks create dimensions for elements using height and width-based properties. These hooks ensure visual consistency, align with grid systems, and scale relative to the root font-size for responsive behavior.
+
+**Key Principles:**
+
+- Use sizing hooks for element dimensions (width/height)
+- Values align with 8-point grid system (multiples of 8)
+- Sizing is relative to root font-size (responsive)
+- **Don't** use sizing hooks for spacing (use spacing hooks instead)
+- Most interactive elements achieve target sizing through padding, not fixed dimensions
+
+---
+
+## General Sizing Hooks (`--slds-g-sizing-*`)
+
+### Available Hooks
+
+| Hook                 | Value    | Pixels @ 16px base | Common Use              |
+| -------------------- | -------- | ------------------ | ----------------------- |
+| `--slds-g-sizing-1`  | 0.125rem | 2px                | Minimal dimensions      |
+| `--slds-g-sizing-2`  | 0.25rem  | 4px                | Very small elements     |
+| `--slds-g-sizing-3`  | 0.5rem   | 8px                | Small icons, indicators |
+| `--slds-g-sizing-4`  | 0.75rem  | 12px               | Small icons             |
+| `--slds-g-sizing-5`  | 1rem     | 16px               | Standard icons          |
+| `--slds-g-sizing-6`  | 1.25rem  | 20px               | Medium icons            |
+| `--slds-g-sizing-7`  | 1.5rem   | 24px               | Large icons             |
+| `--slds-g-sizing-8`  | 1.75rem  | 28px               | Extra large icons       |
+| `--slds-g-sizing-9`  | 2rem     | 32px               | Icon buttons, avatars   |
+| `--slds-g-sizing-10` | 3rem     | 48px               | Large avatars           |
+| `--slds-g-sizing-11` | 4rem     | 64px               | Extra large avatars     |
+| `--slds-g-sizing-12` | 5rem     | 80px               | Hero avatars            |
+| `--slds-g-sizing-13` | 10rem    | 160px              | Small containers        |
+| `--slds-g-sizing-14` | 15rem    | 240px              | Medium containers       |
+| `--slds-g-sizing-15` | 20rem    | 320px              | Large containers        |
+| `--slds-g-sizing-16` | 30rem    | 480px              | Extra large containers  |
+
+### Usage Guidance
+
+#### Small Sizing (1-4): Minimal Elements
+
+**Use For:**
+
+- Status indicators
+- Dots and bullets
+- Minimal visual elements
+
+```css
+.status-dot {
+  width: var(--slds-g-sizing-3);
+  height: var(--slds-g-sizing-3);
+  border-radius: var(--slds-g-radius-border-circle);
+}
+```
+
+#### Icon Sizing (3-8): Icon Elements
+
+**Use For:**
+
+- Icons in buttons
+- Standalone icons
+- Icon indicators
+
+```css
+.icon-small {
+  width: var(--slds-g-sizing-4);
+  height: var(--slds-g-sizing-4);
+}
+
+.icon-standard {
+  width: var(--slds-g-sizing-5);
+  height: var(--slds-g-sizing-5);
+}
+
+.icon-large {
+  width: var(--slds-g-sizing-7);
+  height: var(--slds-g-sizing-7);
+}
+```
+
+#### Avatar/Button Sizing (9-12): Interactive Elements
+
+**Use For:**
+
+- Icon-only buttons
+- Avatar images
+- Circular interactive elements
+
+```css
+.icon-button {
+  width: var(--slds-g-sizing-9);
+  height: var(--slds-g-sizing-9);
+  border-radius: var(--slds-g-radius-border-circle);
+}
+
+.avatar-standard {
+  width: var(--slds-g-sizing-10);
+  height: var(--slds-g-sizing-10);
+  border-radius: var(--slds-g-radius-border-circle);
+}
+```
+
+#### Container Sizing (13-16): Layout Containers
+
+**Use For:**
+
+- Fixed-width containers
+- Sidebars
+- Modal max-widths
+
+```css
+.sidebar {
+  width: var(--slds-g-sizing-14);
+}
+
+.modal-small {
+  max-width: var(--slds-g-sizing-15);
+}
+
+.modal-large {
+  max-width: var(--slds-g-sizing-16);
+}
+```
+
+---
+
+## Typography Width Hooks (`--slds-g-sizing-content-*`, `--slds-g-sizing-heading-*`)
+
+### Available Hooks
+
+Character-based width sizing for optimal text readability:
+
+| Hook                        | Value | Description                               |
+| --------------------------- | ----- | ----------------------------------------- |
+| `--slds-g-sizing-content-1` | 20ch  | Narrow content width (20 characters)      |
+| `--slds-g-sizing-content-2` | 45ch  | Comfortable reading width (45 characters) |
+| `--slds-g-sizing-content-3` | 60ch  | Wide content width (60 characters)        |
+| `--slds-g-sizing-heading-1` | 20ch  | Short heading width (20 characters)       |
+| `--slds-g-sizing-heading-2` | 25ch  | Medium heading width (25 characters)      |
+| `--slds-g-sizing-heading-3` | 30ch  | Long heading width (30 characters)        |
+
+### Usage Guidance
+
+**Character Width (`ch`) Units:**
+
+- `1ch` = width of the "0" character in the current font
+- Ensures consistent line lengths regardless of font-size
+- Optimal for readability: 45-75 characters per line
+
+#### Content Width Hooks
+
+**Use For:**
+
+- Constraining paragraph widths for readability
+- Article or blog content containers
+- Form field max-widths
+
+```css
+.article-content {
+  max-width: var(--slds-g-sizing-content-2); /* 45ch - optimal reading */
+}
+
+.narrow-content {
+  max-width: var(--slds-g-sizing-content-1); /* 20ch - compact */
+}
+
+.wide-content {
+  max-width: var(--slds-g-sizing-content-3); /* 60ch - generous */
+}
+```
+
+#### Heading Width Hooks
+
+**Use For:**
+
+- Preventing headings from becoming too wide
+- Maintaining visual hierarchy
+- Short, punchy headings
+
+```css
+.page-title {
+  max-width: var(--slds-g-sizing-heading-2); /* 25ch */
+}
+
+.section-heading {
+  max-width: var(--slds-g-sizing-heading-3); /* 30ch */
+}
+```
+
+### Readability Guidelines
+
+**Optimal Line Lengths:**
+
+- **Body text:** 45-75 characters per line (use `sizing-content-2`)
+- **Headings:** 20-30 characters (use `sizing-heading-*`)
+- **Narrow columns:** 20-40 characters (use `sizing-content-1`)
+
+```css
+/* Optimal readability pattern */
+.readable-content {
+  max-width: var(--slds-g-sizing-content-2); /* 45ch */
+  font-size: var(--slds-g-font-size-base);
+  line-height: var(--slds-g-font-lineheight-4); /* 1.5 */
+}
+```
+
+---
+
+## Border Sizing Hooks (`--slds-g-sizing-border-*`)
+
+### Available Hooks
+
+| Hook                       | Value | Description           |
+| -------------------------- | ----- | --------------------- |
+| `--slds-g-sizing-border-1` | 1px   | Thin border (default) |
+| `--slds-g-sizing-border-2` | 2px   | Medium border         |
+| `--slds-g-sizing-border-3` | 3px   | Thick border          |
+| `--slds-g-sizing-border-4` | 4px   | Extra thick border    |
+
+### Usage Guidance
+
+#### Border-1: Standard Borders (1px)
+
+**Most Common** - Default border thickness
+
+```css
+.card {
+  border: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1);
+}
+
+.input {
+  border: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1);
+}
+```
+
+#### Border-2: Emphasis Borders (2px)
+
+**Increased visibility**
+
+```css
+.card-emphasized {
+  border: var(--slds-g-sizing-border-2) solid var(--slds-g-color-border-accent-1);
+}
+
+.input:focus {
+  border-width: var(--slds-g-sizing-border-2);
+}
+```
+
+#### Border-3 & Border-4: Heavy Borders (3px, 4px)
+
+**Strong visual weight**
+
+```css
+.alert-error {
+  border-left: var(--slds-g-sizing-border-4) solid var(--slds-g-color-error-1);
+}
+
+.sidebar-divider {
+  border-right: var(--slds-g-sizing-border-3) solid var(--slds-g-color-border-1);
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+
+1. **Use sizing hooks for element dimensions**
+
+   ```css
+   .icon {
+     width: var(--slds-g-sizing-5);
+     height: var(--slds-g-sizing-5);
+   }
+   ```
+
+2. **Use border sizing for border widths**
+
+   ```css
+   .card {
+     border: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1);
+   }
+   ```
+
+3. **Keep icons square (equal width/height)**
+
+   ```css
+   .icon-button {
+     width: var(--slds-g-sizing-9);
+     height: var(--slds-g-sizing-9);
+   }
+   ```
+
+4. **Use max-width for containers, not fixed width**
+
+   ```css
+   .modal {
+     max-width: var(--slds-g-sizing-15);
+   }
+   ```
+
+5. **Let padding define button dimensions**
+
+   ```css
+   /* Good - padding determines height */
+   .button {
+     padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+   }
+
+   /* Avoid - fixed height */
+   .button {
+     height: 2.5rem; /* Less flexible */
+   }
+   ```
+
+### ❌ DON'T:
+
+1. **Don't use sizing hooks for spacing**
+
+   ```css
+   /* Bad - use spacing hooks instead */
+   margin: var(--slds-g-sizing-5);
+
+   /* Good */
+   margin: var(--slds-g-spacing-4);
+   ```
+
+2. **Don't hard-code pixel values**
+
+   ```css
+   /* Bad */
+   width: 24px;
+   border-width: 1px;
+
+   /* Good */
+   width: var(--slds-g-sizing-7);
+   border-width: var(--slds-g-sizing-border-1);
+   ```
+
+3. **Don't mix sizing scales**
+
+   ```css
+   /* Bad - inconsistent sizing */
+   .icon-1 {
+     width: 18px;
+   }
+   .icon-2 {
+     width: 22px;
+   }
+
+   /* Good - consistent scale */
+   .icon-1 {
+     width: var(--slds-g-sizing-5);
+   }
+   .icon-2 {
+     width: var(--slds-g-sizing-6);
+   }
+   ```
+
+4. **Don't set fixed heights on text-based buttons**
+
+   ```css
+   /* Bad - breaks with font scaling */
+   .button {
+     height: 2rem;
+   }
+
+   /* Good - padding allows flexibility */
+   .button {
+     padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+   }
+   ```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Icon Sizing
+
+```css
+.icon-tiny {
+  width: var(--slds-g-sizing-3);
+  height: var(--slds-g-sizing-3);
+}
+
+.icon-small {
+  width: var(--slds-g-sizing-4);
+  height: var(--slds-g-sizing-4);
+}
+
+.icon-medium {
+  width: var(--slds-g-sizing-5);
+  height: var(--slds-g-sizing-5);
+}
+
+.icon-large {
+  width: var(--slds-g-sizing-7);
+  height: var(--slds-g-sizing-7);
+}
+```
+
+### Pattern 2: Icon-Only Button
+
+```css
+.icon-button {
+  /* Fixed dimensions for circular button */
+  width: var(--slds-g-sizing-9);
+  height: var(--slds-g-sizing-9);
+
+  /* Center icon */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  /* Circle shape */
+  border-radius: var(--slds-g-radius-border-circle);
+
+  /* Visual style */
+  background: var(--slds-g-color-surface-container-1);
+  border: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1);
+}
+
+.icon-button:hover {
+  background: var(--slds-g-color-surface-container-2);
+}
+```
+
+### Pattern 3: Avatar Variations
+
+```css
+.avatar {
+  border-radius: var(--slds-g-radius-border-circle);
+  object-fit: cover;
+}
+
+.avatar-small {
+  width: var(--slds-g-sizing-7);
+  height: var(--slds-g-sizing-7);
+}
+
+.avatar-medium {
+  width: var(--slds-g-sizing-9);
+  height: var(--slds-g-sizing-9);
+}
+
+.avatar-large {
+  width: var(--slds-g-sizing-10);
+  height: var(--slds-g-sizing-10);
+}
+
+.avatar-hero {
+  width: var(--slds-g-sizing-12);
+  height: var(--slds-g-sizing-12);
+}
+```
+
+### Pattern 4: Card with Border
+
+```css
+.card {
+  background: var(--slds-g-color-surface-container-1);
+  border: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1);
+  border-radius: var(--slds-g-radius-border-2);
+  padding: var(--slds-g-spacing-4);
+  box-shadow: var(--slds-g-shadow-2);
+}
+```
+
+### Pattern 5: Status Indicator
+
+```css
+.status-indicator {
+  width: var(--slds-g-sizing-3);
+  height: var(--slds-g-sizing-3);
+  border-radius: var(--slds-g-radius-border-circle);
+  background: var(--slds-g-color-success-1);
+}
+```
+
+### Pattern 6: Modal Dialog
+
+```css
+.modal {
+  background: var(--slds-g-color-surface-1);
+  border-radius: var(--slds-g-radius-border-2);
+  box-shadow: var(--slds-g-shadow-4);
+  padding: var(--slds-g-spacing-6);
+
+  /* Responsive width with max */
+  width: 90%;
+  max-width: var(--slds-g-sizing-15);
+}
+```
+
+### Pattern 7: Alert with Accent Border
+
+```css
+.alert-error {
+  background: var(--slds-g-color-error-container-1);
+  color: var(--slds-g-color-on-error-1);
+  padding: var(--slds-g-spacing-3) var(--slds-g-spacing-4);
+  border-radius: var(--slds-g-radius-border-1);
+  border-left: var(--slds-g-sizing-border-4) solid var(--slds-g-color-error-1);
+}
+```
+
+### Pattern 8: Sidebar Panel
+
+```css
+.sidebar {
+  width: var(--slds-g-sizing-14);
+  background: var(--slds-g-color-surface-2);
+  border-right: var(--slds-g-sizing-border-1) solid var(--slds-g-color-border-1);
+  padding: var(--slds-g-spacing-4);
+}
+```
+
+---
+
+## Important: Target Sizing vs Fixed Sizing
+
+### Interactive Elements: Use Padding (Recommended)
+
+Most interactive elements should achieve target sizing through padding, **not** fixed dimensions:
+
+```css
+/* ✅ RECOMMENDED - Flexible button using padding */
+.button {
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+  /* Height automatically determined by padding + content */
+}
+
+/* ❌ AVOID - Fixed height is less flexible */
+.button {
+  height: 2.5rem; /* Breaks with font size changes */
+}
+```
+
+### When to Use Fixed Sizing
+
+**DO use fixed sizing for:**
+
+1. **Icon-only buttons** (square, circular)
+2. **Avatars** (always square/circular)
+3. **Status indicators** (fixed dots, badges)
+4. **Icons** (consistent sizing)
+5. **Container max-widths** (responsive constraints)
+
+```css
+/* ✅ Fixed sizing appropriate here */
+.icon-button {
+  width: var(--slds-g-sizing-9);
+  height: var(--slds-g-sizing-9);
+}
+
+.avatar {
+  width: var(--slds-g-sizing-10);
+  height: var(--slds-g-sizing-10);
+}
+```
+
+---
+
+## Accessibility Considerations
+
+### Target Sizing
+
+Ensure interactive elements meet minimum target sizes:
+
+**WCAG 2.2 Requirements:**
+
+- Desktop/Pointer: 24×24px minimum (AA), 44×44px recommended (AAA)
+- Mobile/Touch: 44×44px minimum
+- Salesforce default: 44×44px for consistency
+
+```css
+/* Icon button meets minimum target size */
+.icon-button {
+  width: var(--slds-g-sizing-9); /* 32px */
+  height: var(--slds-g-sizing-9);
+  /* Still needs adequate spacing to meet 44px in context */
+}
+
+/* Text button meets target through padding */
+.button {
+  padding: var(--slds-g-spacing-3) var(--slds-g-spacing-4);
+  /* Results in 44px+ height */
+}
+```
+
+### Responsive Sizing
+
+Sizing hooks scale with root font-size:
+
+```css
+/* Automatically scales with user font size preferences */
+.icon {
+  width: var(--slds-g-sizing-5); /* 1rem = 16px at default */
+  height: var(--slds-g-sizing-5);
+}
+
+/* If user increases font to 20px, icon becomes 20px */
+```
+
+---
+
+## Quick Decision Guide
+
+**Choose sizing hook based on element type:**
+
+| Element Type    | Recommended Hook           | Why                            |
+| --------------- | -------------------------- | ------------------------------ |
+| Tiny status dot | `sizing-2` or `sizing-3`   | Minimal visual indicator       |
+| Small icon      | `sizing-4`                 | Compact icon                   |
+| Standard icon   | `sizing-5`                 | Default icon size              |
+| Large icon      | `sizing-7`                 | Prominent icon                 |
+| Icon button     | `sizing-9`                 | Touch-friendly circular button |
+| Small avatar    | `sizing-7`                 | Compact profile image          |
+| Standard avatar | `sizing-9` or `sizing-10`  | Default profile size           |
+| Large avatar    | `sizing-11` or `sizing-12` | Hero profile image             |
+| Modal width     | `sizing-15` or `sizing-16` | Content container              |
+| Sidebar width   | `sizing-13` or `sizing-14` | Side panel                     |
+
+**Choose border sizing based on emphasis:**
+
+| Border Context     | Hook                                   | Why                  |
+| ------------------ | -------------------------------------- | -------------------- |
+| Standard borders   | `sizing-border-1`                      | Default, subtle      |
+| Emphasized borders | `sizing-border-2`                      | Noticeable           |
+| Accent borders     | `sizing-border-3` or `sizing-border-4` | Strong visual weight |
+
+---
+
+## Complete Hook Reference
+
+**General Sizing (16 hooks):**
+
+- `--slds-g-sizing-1` through `--slds-g-sizing-16`
+
+**Border Sizing (4 hooks):**
+
+- `--slds-g-sizing-border-1` through `--slds-g-sizing-border-4`
+
+**Typography Width (6 hooks):**
+
+- `--slds-g-sizing-content-1/2/3` (content width)
+- `--slds-g-sizing-heading-1/2/3` (heading width)
+
+**Total: 26 sizing hooks**
+
+---
+
+**References:**
+
+- Source: `/source-data/sds-metadata/styling-hooks/globalstylinghooks.metadata.json`
+- Source: `/source-data/final-ux-guidance/styling-hooks/spacing-and-sizing/spacing-and-sizing-hooks.md`
+- SLDS Documentation: [Spacing & Sizing](https://www.lightningdesignsystem.com/2e1ef8501/p/03d6b0-spacing-and-sizing)