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

package/knowledge/slds/styling-hooks/guidance.md

@@ -0,0 +1,906 @@
+# 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 with ~375 hooks 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
+  - Use for: primary actions, selected items, brand highlights
+  - Hooks: `accent-1/2/3`, `accent-container-1/2/3`, `border-accent-1/2/3`, `on-accent-1/2/3`
+  - Numbered variants represent state progression: 1 = default, 2 = hover, 3 = active
+- **Border** (`border-*`): Component borders, dividers, separators
+- **Feedback** (`feedback-*`): Alerts, notifications, validation states
+  - Types: `error`, `warning`, `success`, `info`, `discovery`
+- **On-Colors** (`on-*`): Text and icons on colored backgrounds
+  - **Always pair with corresponding container colors for accessibility**
+
+#### **Tier 2: System Colors**
+
+Accessible, system-wide colors for edge cases where semantic colors don't apply:
+
+- Base colors for neutrals, brand, and feedback states
+- Use when semantic UI colors don't match your use case
+
+#### **Tier 3: Palette Colors (Use Sparingly)**
+
+Raw color values organized on a 0-100 scale for data visualization and custom scenarios:
+
+- **Palettes:** `neutral`, `brand`, `red`, `pink`, `orange`, `yellow`, `green`, `teal`, `cloud-blue`, `blue`, `indigo`, `purple`, `violet`
+- **Scale:** 0 (darkest) to 100 (lightest) in 5-point increments
+- **Accessibility Built-In:** 50-point separation = WCAG AA text contrast (4.5:1), 40-point = UI element contrast (3:1)
+- **When to Use:** Data visualization, custom charts, situations undefined by semantic system
+- **Example:** `--slds-g-color-palette-blue-50`
+
+**How to use palette colors:**
+
+```css
+/* Text on light background - use low numbers (dark colors) */
+color: var(--slds-g-color-palette-neutral-10); /* Very dark gray text */
+background: var(--slds-g-color-palette-neutral-95); /* Very light gray background */
+/* 85-point separation = excellent contrast */
+
+/* Border on white - use mid-range */
+border: 1px solid var(--slds-g-color-palette-neutral-60);
+/* 40-point separation from neutral-100 (white) = compliant */
+```
+
+**Color Density Rule:** Maintain 85% neutral, 5% accent, 10% expressive colors for proper visual hierarchy.
+
+> **💡 For comprehensive color system guidance:** Use `{{GUIDE_SLDS_STYLING_TOOL}}({ topic: "colors" })` to get detailed documentation on the three-tier color system, palette families, accessibility rules, decision trees, and usage patterns.
+
+---
+
+### 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 */
+gap: var(--slds-g-spacing-3); /* ✅ Correct */
+
+/* DON'T use named hooks - they don't exist */
+margin: var(--slds-g-spacing-medium); /* ❌ Wrong - hook doesn't exist */
+```
+
+**Principle:** Use spacing hooks to maintain consistent whitespace and rhythm across your component.
+
+> **💡 For comprehensive spacing system guidance:** Use `{{GUIDE_SLDS_STYLING_TOOL}}({ topic: "spacing" })` to get detailed documentation on the spacing scale, density-aware hooks, directional variants, accessibility requirements, and usage patterns.
+
+---
+
+### 3. Typography Hooks (`--slds-g-font-*`)
+
+#### Font Families
+
+- `--slds-g-font-family` - Default font family
+- `--slds-g-font-family-base` - Base font family (same as above)
+- `--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 */
+font-weight: var(--slds-g-font-weight-5); /* Medium */
+
+/* DON'T use named hooks - they don't exist */
+font-weight: var(--slds-g-font-weight-bold); /* ❌ Wrong */
+font-weight: var(--slds-g-font-weight-medium); /* ❌ Wrong */
+```
+
+#### Line Heights (Numbered 1-6)
+
+- `--slds-g-font-lineheight-1` through `--slds-g-font-lineheight-6`
+
+#### Font Sizes
+
+Only one font size hook exists:
+
+- `--slds-g-font-size-base` - Base font size for body text
+
+For other font sizes, use rem values directly (e.g., `1.5rem`, `0.875rem`, `0.75rem`).
+
+**Principle:** Use typography hooks to ensure text renders consistently and scales properly across density settings.
+
+> **💡 For comprehensive typography system guidance:** Use `{{GUIDE_SLDS_STYLING_TOOL}}({ topic: "typography" })` to get detailed documentation on numbered weights, line heights, font families, typography hierarchy patterns, and accessibility requirements.
+
+---
+
+### 4. Other Styling Hooks
+
+- **Sizing** (`--slds-g-sizing-*`): Component dimensions, icon sizes, border widths
+
+  > **💡 For comprehensive sizing guidance:** Use `{{GUIDE_SLDS_STYLING_TOOL}}({ topic: "sizing" })` to get detailed documentation on element dimensions, border widths, typography widths, and 8-point grid alignment.
+
+- **Shadow** (`--slds-g-shadow-*`): Elevation and depth effects
+
+  > **💡 For comprehensive shadow guidance:** Use `{{GUIDE_SLDS_STYLING_TOOL}}({ topic: "shadows" })` to get detailed documentation on elevation levels, focus states, directional shadows, and inverse shadows.
+
+- **Radius** (`--slds-g-radius-*`): Border radius values for rounded corners
+  > **💡 For comprehensive border radius guidance:** Use `{{GUIDE_SLDS_STYLING_TOOL}}({ topic: "borders" })` to get detailed documentation on progressive rounding, circle vs pill shapes, and component-specific usage.
+
+Use `{{EXPLORE_SLDS_STYLING_TOOL}}` to search for specific hooks in these categories as needed.
+
+---
+
+## Usage Patterns for Coding Agents
+
+### Pattern 1: Interactive Component States (Accent Colors)
+
+For components with hover/active states, use numbered accent variants:
+
+```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
+
+Use semantic surface and container hooks for backgrounds:
+
+```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
+
+Use semantic feedback hooks for alerts and notifications:
+
+```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);
+  border-radius: var(--slds-g-radius-border-1);
+}
+
+.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);
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+}
+
+.alert-warning {
+  background: var(--slds-g-color-warning-container-1);
+  color: var(--slds-g-color-on-warning-1);
+  border-left: 4px solid var(--slds-g-color-warning-1);
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+}
+```
+
+---
+
+### Pattern 4: Data Visualization with Palette Colors
+
+Use palette colors for charts and data viz:
+
+```css
+/* Custom chart colors - using palette for data differentiation */
+.chart-series-1 {
+  background: var(--slds-g-color-palette-blue-50);
+}
+
+.chart-series-2 {
+  background: var(--slds-g-color-palette-green-50);
+}
+
+.chart-series-3 {
+  background: var(--slds-g-color-palette-purple-50);
+}
+
+.chart-series-4 {
+  background: var(--slds-g-color-palette-orange-50);
+}
+
+/* Verified: 50-point separation from neutral-100 background = WCAG AA compliant */
+```
+
+---
+
+### Pattern 5: Typography Hierarchy
+
+Use typography hooks for consistent type styling:
+
+```css
+.heading {
+  font-family: var(--slds-g-font-family-base);
+  font-size: 1.5rem; /* Use rem values - no numbered font-size hooks exist */
+  font-weight: var(--slds-g-font-weight-7);
+  line-height: var(--slds-g-font-lineheight-2);
+  color: var(--slds-g-color-on-surface-3); /* Highest emphasis */
+}
+
+.body-text {
+  font-family: var(--slds-g-font-family-base);
+  font-size: var(--slds-g-font-size-base);
+  font-weight: var(--slds-g-font-weight-4);
+  line-height: var(--slds-g-font-lineheight-3);
+  color: var(--slds-g-color-on-surface-2); /* Standard text */
+}
+
+.caption {
+  font-family: var(--slds-g-font-family-base);
+  font-size: 0.75rem; /* Use rem values - no numbered font-size hooks exist */
+  font-weight: var(--slds-g-font-weight-4);
+  color: var(--slds-g-color-on-surface-1); /* De-emphasized */
+}
+```
+
+---
+
+## Decision Tree for Coding Agents
+
+When styling a component, follow this hierarchy:
+
+### Step 1: Check for Component-Specific Hooks
+
+Search for `--slds-c-[component-name]-*` hooks first (highest specificity):
+
+```javascript
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-c-button-' });
+```
+
+### 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
+- **Border**: `border-1/2`, `border-accent-*`, `border-error-*`, `border-success-*`
+
+### Step 3: Use System Colors When Needed
+
+For edge cases where semantic UI doesn't fit, use system colors:
+
+```javascript
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'system' });
+```
+
+### Step 4: Use Palette Colors for Data Viz
+
+Only for data visualization or undefined scenarios:
+
+```javascript
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-g-color-palette-' });
+```
+
+- Ensure 50-point separation for text (4.5:1 contrast)
+- Ensure 40-point separation for UI elements (3:1 contrast)
+
+### Step 5: 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 */
+```
+
+---
+
+## How to Get More Information
+
+> **Note:** Contextual tool references are embedded throughout this document. Look for 💡 callouts in each category section (Colors, Spacing, Typography, etc.) for quick access to category-specific guidance.
+
+### Using the `{{EXPLORE_SLDS_STYLING_TOOL}}` Tool
+
+To find specific styling hooks or explore categories:
+
+```javascript
+// Search for all accent color hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'accent' });
+
+// Find all spacing hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-g-spacing-' });
+
+// Look up specific hooks by name
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ hooks: ['--slds-g-color-accent-1', '--slds-g-spacing-4'] });
+
+// Filter by category
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ category: 'color' });
+
+// Get detailed information
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'palette', detail_level: 'full' });
+```
+
+**Common Search Patterns:**
+
+- Spacing values: `prefix: "--slds-g-spacing-"`
+- Accent colors: `search: "accent"`
+- Palette colors: `prefix: "--slds-g-color-palette-"`
+- Typography: `prefix: "--slds-g-font-"`
+- Shadows: `prefix: "--slds-g-shadow-"`
+- Sizing: `prefix: "--slds-g-sizing-"`
+
+### Tool Output
+
+The tool returns:
+
+- **Hook name** - The full CSS custom property name
+- **Value** - Current value (may change with themes)
+- **Category** - Color, spacing, font, sizing, etc.
+- **Usage guidance** - When and how to use the hook
+- **Related hooks** - Complementary hooks to consider
+
+---
+
+## Critical Rules for Agents
+
+### ✅ 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`
+- Use `font-size-base` or rem values for font sizes (no numbered font-size hooks exist)
+- Prefer semantic UI colors over system colors and palette colors
+- Pair container colors with on-colors for text/icons (e.g., `surface-container-1` with `on-surface-1/2/3`)
+- Follow the 50-point rule for text contrast, 40-point rule for UI elements
+- Use numbered variants (1/2/3) for state progression where available
+- Use `{{EXPLORE_SLDS_STYLING_TOOL}}` to verify hook names
+
+### ❌ 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
+- Mix palette levels without checking contrast (maintain 40-50 point separation)
+- Hard-code values when hooks exist
+
+---
+
+## Quick Reference: Common Patterns
+
+### Button Component
+
+```css
+.myCustomButton {
+  /* Colors */
+  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);
+
+  /* Spacing */
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+  margin-bottom: var(--slds-g-spacing-3);
+
+  /* Typography */
+  font-family: var(--slds-g-font-family-base);
+  font-size: var(--slds-g-font-size-base);
+  font-weight: var(--slds-g-font-weight-5);
+  line-height: var(--slds-g-font-lineheight-3);
+
+  /* Borders */
+  border-radius: var(--slds-g-radius-border-1);
+
+  /* States */
+  transition: all 0.2s ease;
+}
+
+.myCustomButton: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);
+}
+
+.myCustomButton: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);
+}
+```
+
+---
+
+### Card Component
+
+```css
+.slds-card {
+  /* Surface Container */
+  background: var(--slds-g-color-surface-container-1);
+  color: var(--slds-g-color-on-surface-2);
+
+  /* Spacing */
+  padding: var(--slds-g-spacing-4);
+  margin-bottom: var(--slds-g-spacing-4);
+
+  /* Borders & Elevation */
+  border: 1px solid var(--slds-g-color-border-1);
+  border-radius: var(--slds-g-radius-border-1);
+  box-shadow: var(--slds-g-shadow-1);
+
+  /* Typography */
+  font-family: var(--slds-g-font-family-base);
+}
+
+.slds-card-title {
+  font-size: 1.125rem; /* 18px - use rem values */
+  font-weight: var(--slds-g-font-weight-7);
+  line-height: var(--slds-g-font-lineheight-2);
+  color: var(--slds-g-color-on-surface-3); /* High emphasis */
+  margin-bottom: var(--slds-g-spacing-2);
+}
+```
+
+---
+
+### Input Field
+
+```css
+.slds-input {
+  /* Background & Text */
+  background: var(--slds-g-color-surface-container-1);
+  color: var(--slds-g-color-on-surface-2);
+
+  /* Border */
+  border: 1px solid var(--slds-g-color-border-1);
+  border-radius: var(--slds-g-radius-border-1);
+
+  /* Spacing */
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-3);
+
+  /* Typography */
+  font-family: var(--slds-g-font-family-base);
+  font-size: var(--slds-g-font-size-base);
+  font-weight: var(--slds-g-font-weight-4);
+  line-height: var(--slds-g-font-lineheight-3);
+}
+
+.slds-input:focus {
+  /* Focus state using accent colors */
+  border-color: var(--slds-g-color-accent-1);
+  outline: none;
+  box-shadow: 0 0 0 2px var(--slds-g-color-accent-container-1);
+}
+
+.slds-input:disabled {
+  background: var(--slds-g-color-disabled-container-1);
+  color: var(--slds-g-color-on-disabled-1);
+  cursor: not-allowed;
+}
+```
+
+---
+
+### Alert/Notification
+
+```css
+.slds-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);
+  border-radius: var(--slds-g-radius-border-1);
+}
+
+.slds-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);
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+}
+```
+
+---
+
+## Migration Patterns: Converting Hard-Coded CSS to Hooks
+
+### Converting Legacy CSS to SLDS Hooks
+
+**Before: Hard-Coded Values**
+
+```css
+.old-button {
+  background: #0176d3;
+  color: #ffffff;
+  border: 1px solid #0176d3;
+  padding: 8px 16px;
+  border-radius: 4px;
+  font-weight: 500;
+}
+
+.old-button:hover {
+  background: #014486;
+}
+```
+
+**After: SLDS Hooks**
+
+```css
+.new-button {
+  /* Replace hex colors with semantic hooks */
+  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);
+
+  /* Replace px values with spacing hooks */
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+
+  /* Replace px with radius hooks */
+  border-radius: var(--slds-g-radius-border-1);
+
+  /* Replace numeric weight with hook */
+  font-weight: var(--slds-g-font-weight-5);
+}
+
+.new-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);
+}
+```
+
+### Migration Steps:
+
+1. **Replace colors** → Semantic hooks (accent, surface-container, error, success) or system colors
+2. **Replace spacing** → Numbered spacing hooks (spacing-2, spacing-4)
+3. **Replace typography** → Font hooks (font-weight-5, font-size-base or rem)
+4. **Replace borders** → Border hooks (radius-border-1, border-1)
+5. **Replace shadows** → Shadow hooks (shadow-1, shadow-2)
+6. **Add state transitions** → Use numbered variants (1/2/3 for default/hover/active)
+
+---
+
+## Handling Edge Cases
+
+### When to Use Palette Colors
+
+Some scenarios require palette colors instead of semantic hooks:
+
+#### 1. Data Visualization
+
+Use palette colors for charts and data differentiation:
+
+```css
+/* Custom chart colors - palette allows precise color selection */
+.chart-series-1 {
+  background: var(--slds-g-color-palette-blue-50);
+}
+.chart-series-2 {
+  background: var(--slds-g-color-palette-green-50);
+}
+.chart-series-3 {
+  background: var(--slds-g-color-palette-purple-50);
+}
+.chart-series-4 {
+  background: var(--slds-g-color-palette-orange-50);
+}
+.chart-series-5 {
+  background: var(--slds-g-color-palette-teal-50);
+}
+/* 50-point separation from neutral-100 background = WCAG AA compliant */
+```
+
+#### 2. Custom Gradients
+
+Complex gradients benefit from palette precision:
+
+```css
+.gradient-background {
+  background: linear-gradient(
+    135deg,
+    var(--slds-g-color-palette-blue-40) 0%,
+    var(--slds-g-color-palette-purple-60) 100%
+  );
+}
+```
+
+#### 3. Third-Party Library Integration
+
+When external libraries require specific values, document the reason:
+
+```css
+/* Leaflet map requires specific z-index - library requirement */
+.map-container {
+  z-index: 400;
+}
+
+/* Date picker overlay - library-specific styling */
+.datepicker-overlay {
+  background: var(--slds-g-color-overlay-backdrop);
+  backdrop-filter: blur(4px);
+}
+```
+
+**Rule:** Use semantic hooks first, palette colors for specific needs, and document any edge cases.
+
+---
+
+## Accessibility Compliance
+
+SLDS styling hooks are designed with accessibility built-in:
+
+### Color Contrast Rules
+
+#### Text on Backgrounds (50-point separation)
+
+```css
+/* ✅ COMPLIANT - 50+ point separation */
+.text-example-1 {
+  background: var(--slds-g-color-palette-neutral-95); /* Light */
+  color: var(--slds-g-color-palette-neutral-10); /* Dark */
+  /* 85-point separation = excellent contrast (>4.5:1) */
+}
+
+.text-example-2 {
+  background: var(--slds-g-color-palette-blue-30); /* Dark */
+  color: var(--slds-g-color-palette-blue-85); /* Light */
+  /* 55-point separation = compliant (>4.5:1) */
+}
+```
+
+#### UI Elements (40-point separation)
+
+```css
+/* ✅ COMPLIANT - 40+ point separation */
+.border-example {
+  background: var(--slds-g-color-palette-neutral-100); /* White */
+  border: 1px solid var(--slds-g-color-palette-neutral-60); /* Mid gray */
+  /* 40-point separation = compliant for UI elements (>3:1) */
+}
+```
+
+### 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 */
+}
+```
+
+### Testing Checklist
+
+- ✅ Verify components work in both light and dark modes
+- ✅ Test with high contrast settings enabled
+- ✅ Ensure keyboard focus states use accent colors with proper contrast
+- ✅ Validate color-only indicators have non-color alternatives (icons, text)
+
+---
+
+## Validation Checklist for Generated Code
+
+Before finalizing generated CSS, verify:
+
+### Hook Usage
+
+- [ ] Semantic UI colors used where appropriate (surface-container, accent, error, success)
+- [ ] All spacing hooks use numbered format (spacing-1 to spacing-12)
+- [ ] All font hooks use numbered format (font-weight-1 to font-weight-7)
+- [ ] Font sizes use `font-size-base` or rem values (no numbered font-size hooks exist)
+- [ ] Palette colors follow point separation rules (50 for text, 40 for UI)
+- [ ] No private hooks used (`--_slds-*`, `--slds-s-*`)
+- [ ] No `@layer` syntax
+- [ ] No reassignment of hook values
+
+### Accessibility
+
+- [ ] Text contrast verified (50-point separation or 4.5:1)
+- [ ] UI element contrast verified (40-point separation or 3:1)
+- [ ] Container colors paired with on-\* colors
+- [ ] Focus states visible and use accent colors
+
+### Code Quality
+
+- [ ] State transitions defined (hover/active/focus/disabled)
+- [ ] 85-5-10 color density maintained
+- [ ] Semantic hooks preferred over palette colors
+- [ ] Hook names verified with `{{EXPLORE_SLDS_STYLING_TOOL}}` if unsure
+
+---
+
+## Troubleshooting for Agents
+
+### Problem: Component doesn't match SLDS visual style
+
+**Solution:** Check hook usage:
+
+- Replace `#0176d3` → `var(--slds-g-color-accent-1)`
+- Replace `16px` → `var(--slds-g-spacing-4)`
+- Replace `500` → `var(--slds-g-font-weight-5)`
+
+### 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`
+- Use `{{EXPLORE_SLDS_STYLING_TOOL}}` to verify exact hook name
+
+### 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
+- Ensure accent containers paired with on-accent colors
+
+### Problem: Spacing inconsistent
+
+**Solution:**
+
+- Use numbered spacing hooks: `spacing-2`, `spacing-4`
+- Check spacing scale: 8px=spacing-2, 16px=spacing-4, 24px=spacing-5
+
+### Problem: Font weight not applying
+
+**Solution:**
+
+- Use numbered hooks: `font-weight-5`, `font-weight-7`
+- Common values: Regular=weight-4, Medium=weight-5, Bold=weight-7
+
+---
+
+## Summary for Coding Agents
+
+When generating or optimizing SLDS components:
+
+1. **Use semantic hooks first** — Prefer semantic UI colors (surface-container, accent, error, success) 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 (no numbered font-size hooks exist)
+4. **Follow the three-tier color system** — Semantic UI → System Colors → Expressive Palette
+5. **Use numbered variants for states** — Progression (1/2/3 for default/hover/active where available)
+6. **Follow contrast rules** — 50-point for text, 40-point for UI elements
+7. **Pair containers with on-colors** — Use `on-surface-*`, `on-accent-*`, `on-error-*` for text/icons
+8. **Use {{EXPLORE_SLDS_STYLING_TOOL}}** — Search for specific hooks by name, prefix, or category
+9. **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.
+
+---
+
+**Document Version:** 3.0  
+**Last Updated:** November 2025  
+**SLDS Version:** 2.27+  
+**Total Global Hooks:** 473 (`--slds-g-*`)
+
+**Major Categories:**
+
+- Color hooks: ~375 (semantic, system, palette)
+- Typography hooks: 61 (families, weights, sizes, line heights)
+- Spacing hooks: 48 (numbered 1-12 + density variants)
+- Shadow hooks: 39
+- Sizing hooks: 32
+- Radius hooks: 12
+
+**Tool Reference:** Use `{{EXPLORE_SLDS_STYLING_TOOL}}` to search all hooks by name, prefix, or category