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

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

@@ -0,0 +1,963 @@
+# SLDS Color System: Comprehensive Guide for Coding Agents
+
+## Overview
+
+The SLDS color system includes **~312 color hooks** organized into a three-tier hierarchy. This guide explains when and how to use each tier effectively.
+
+---
+
+## Three-Tier Color System
+
+SLDS organizes colors into three tiers, each serving a different purpose:
+
+### 1. Semantic UI Colors (PREFERRED - Top Tier)
+
+**Purpose:** Theme-aware, purpose-driven colors that automatically adapt to themes and modes.
+
+**When to use:** Default choice for all UI components and page elements.
+
+**Characteristics:**
+
+- ✅ Automatically adapt to brand themes, light/dark modes
+- ✅ Named by purpose/location (surface, container, accent, feedback)
+- ✅ Mutable - values change with theme selection
+- ✅ Pre-validated accessibility pairings (e.g., accent-container + on-accent)
+
+**Available Semantic Colors:**
+
+- **Accent Colors:** ✅ 12 hooks available (`accent-1/2/3`, `accent-container-1/2/3`, `border-accent-1/2/3`, `on-accent-1/2/3`)
+- **Surface Colors:** 🚧 Exist in SLDS but not yet in knowledge base
+- **Container Colors:** 🚧 Exist in SLDS but not yet in knowledge base
+- **Feedback Colors:** 🚧 Exist in SLDS but not yet in knowledge base
+- **On Colors:** 🚧 Exist in SLDS but not yet in knowledge base (except on-accent)
+
+**Examples:**
+
+```css
+/* Semantic accent colors - currently available */
+background: var(--slds-g-color-accent-container-1);
+color: var(--slds-g-color-on-accent-1);
+
+/* Semantic surface colors - coming soon */
+background: var(--slds-g-color-surface-1); /* Not yet in knowledge base */
+color: var(--slds-g-color-on-surface-2); /* Not yet in knowledge base */
+```
+
+---
+
+### 2. System Colors (Middle Tier)
+
+**Purpose:** Accessible system-wide colors for edge cases where semantic UI colors don't make sense.
+
+**When to use:** Only when semantic UI colors (surface, accent, container) don't fit your use case.
+
+**Characteristics:**
+
+- ✅ Accessible colors used throughout the UI
+- ✅ Named by semantic category (brand, neutral, error, warning, success)
+- ✅ Follow 0-100 scale like palettes
+- ✅ Mutable - values can change with theme
+- ⚠️ Less theme-adaptive than semantic UI colors
+
+**Available System Color Families:**
+
+#### `--slds-g-color-neutral-base-*`
+
+Used for text, surfaces, and non-functional UI elements.
+
+- **Levels:** 10, 15, 20, 30, 40, 50, 60, 65, 70, 80, 90, 95, 100
+- **Examples:** `neutral-base-10` (very dark gray), `neutral-base-95` (very light gray)
+
+#### `--slds-g-color-brand-base-*`
+
+Electric blue for buttons, hover states, selected/active states. **Do not use decoratively.**
+
+- **Levels:** 10, 15, 20, 30, 40, 50, 60, 65, 70, 80, 90, 95, 100
+- **Note:** Only use for interactive states, not decoration
+
+#### `--slds-g-color-error-base-*` (Pink)
+
+**Only** for error feedback states, invalid inputs, destructive actions.
+
+- **Levels:** 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100
+
+#### `--slds-g-color-warning-base-*` (Yellow)
+
+**Only** for warning feedback states, caution messages.
+
+- **Levels:** 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100
+
+#### `--slds-g-color-success-base-*` (Teal)
+
+**Only** for success feedback states, completed actions.
+
+- **Levels:** 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100
+
+**Example Usage:**
+
+```css
+/* System colors for feedback when semantic feedback hooks aren't available */
+.error-alert {
+  background: var(--slds-g-color-error-base-95); /* Light pink background */
+  color: var(--slds-g-color-error-base-10); /* Dark pink text */
+  border-left: 4px solid var(--slds-g-color-error-base-50);
+}
+
+/* System neutral for general UI */
+.text {
+  color: var(--slds-g-color-neutral-base-20); /* Dark gray text */
+}
+```
+
+**Important Rules:**
+
+- ⚠️ Use only in edge cases where semantic colors don't fit
+- ❌ Don't mix with other color groups (e.g., don't use brand-base with accent-container)
+- ❌ Don't use brand-base/error-base/warning-base/success-base decoratively - only for their intended purpose
+
+---
+
+### 3. Color Palettes (Bottom Tier)
+
+**Purpose:** Raw, immutable color values for undefined situations and data visualization.
+
+**When to use:** When semantic and system colors don't fit (data viz, custom charts, granular control).
+
+**Characteristics:**
+
+- ✅ Full spectrum of colors
+- ✅ Follow 0-100 scale with magic numbers (50-point, 40-point separation)
+- ✅ Immutable - values never change regardless of theme
+- ✅ No semantic assignment - can be used anywhere
+- ⚠️ You're responsible for accessibility
+
+**Available Palette Families:**
+
+- `neutral`, `brand`, `red`, `pink`, `orange`, `yellow`, `green`, `teal`, `cloud-blue`, `blue`, `indigo`, `purple`, `violet`
+
+**Examples:**
+
+```css
+/* Palette colors for data visualization */
+.chart-bar-1 {
+  fill: var(--slds-g-color-palette-purple-50);
+}
+.chart-bar-2 {
+  fill: var(--slds-g-color-palette-cloud-blue-50);
+}
+
+/* Palette colors when semantic/system don't exist yet */
+.card {
+  background: var(--slds-g-color-palette-neutral-100); /* White */
+  color: var(--slds-g-color-palette-neutral-10); /* Near black */
+}
+```
+
+---
+
+## Palette Color System
+
+### The 0-100 Numerical Scale
+
+Palette colors use a 0-100 point scale where **accessibility is mathematically guaranteed**:
+
+- **0-100 Scale:** 0 = darkest (black), 100 = lightest (white)
+- **Available Steps:** Every 5 points (0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 100)
+- **Cross-Palette Consistency:** Same point values across different color lanes (e.g., blue-50 and green-50 have similar lightness)
+
+### Magic Numbers for Accessibility
+
+**Critical Rule:** Point separation determines contrast compliance:
+
+| Separation    | Contrast Ratio | Use Case             | WCAG Level    |
+| ------------- | -------------- | -------------------- | ------------- |
+| **50 points** | 4.5:1+         | Text on backgrounds  | AA (required) |
+| **40 points** | 3:1+           | UI elements, borders | AA (required) |
+
+**Works across hues:** A 50-point separation maintains 4.5:1 contrast even when using different color lanes.
+
+**Example:**
+
+```css
+/* ✅ WCAG AA Compliant - 50-point separation */
+.text-example {
+  background: var(--slds-g-color-palette-neutral-95); /* Very light */
+  color: var(--slds-g-color-palette-neutral-10); /* Very dark */
+  /* 85-point separation = excellent contrast (>4.5:1) */
+}
+
+/* ✅ WCAG AA Compliant for UI - 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 borders (>3:1) */
+}
+
+/* ✅ Cross-palette works too */
+.cross-palette {
+  background: var(--slds-g-color-palette-blue-20); /* Dark blue */
+  color: var(--slds-g-color-palette-green-75); /* Light green */
+  /* 55-point separation = compliant */
+}
+```
+
+### How State Transitions Work with Palettes
+
+Use 10-point steps for interactive states:
+
+```css
+.button {
+  background: var(--slds-g-color-palette-blue-50); /* Default */
+}
+
+.button:hover {
+  background: var(--slds-g-color-palette-blue-40); /* Hover: 10 points darker */
+}
+
+.button:active {
+  background: var(--slds-g-color-palette-blue-30); /* Active: 20 points darker */
+}
+```
+
+---
+
+## Available Palette Families
+
+### Foundation Palettes (Always Use These First)
+
+#### Neutral (Primary Choice)
+
+**85% of your UI should use neutral colors**
+
+- **Hook Pattern:** `--slds-g-color-palette-neutral-{level}`
+- **Levels:** 0, 5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100
+- **Use For:**
+  - Page backgrounds (95, 100)
+  - Text colors (10, 20, 30)
+  - Borders and dividers (60, 70)
+  - Disabled states (50, 60)
+  - Shadows and subtle effects (80, 90)
+
+**Common Patterns:**
+
+```css
+/* Page background */
+background: var(--slds-g-color-palette-neutral-100); /* White */
+
+/* Surface/card background */
+background: var(--slds-g-color-palette-neutral-95); /* Very light gray */
+
+/* Primary text */
+color: var(--slds-g-color-palette-neutral-10); /* Near black */
+
+/* Secondary text */
+color: var(--slds-g-color-palette-neutral-30); /* Dark gray */
+
+/* Borders */
+border-color: var(--slds-g-color-palette-neutral-70); /* Mid-light gray */
+
+/* Disabled text */
+color: var(--slds-g-color-palette-neutral-50); /* Mid gray */
+```
+
+#### Brand
+
+**5% of your UI - Use for accent elements only**
+
+- **Hook Pattern:** `--slds-g-color-palette-brand-{level}`
+- **Levels:** Same as neutral (0-100 in 5-point steps)
+- **Use For:** Primary actions, brand identity elements
+- **When to Use Semantic Instead:** If accent hooks are available, prefer `--slds-g-color-accent-*` over brand palette
+
+---
+
+### Feedback Palettes (Status Indicators)
+
+Use these for system feedback when semantic feedback hooks aren't available:
+
+#### Pink (Errors)
+
+- **Hook Pattern:** `--slds-g-color-palette-pink-{level}`
+- **Use For:** Error messages, invalid states, destructive actions
+- **Example:** `background: var(--slds-g-color-palette-pink-95); color: var(--slds-g-color-palette-pink-10);`
+
+#### Yellow (Warnings)
+
+- **Hook Pattern:** `--slds-g-color-palette-yellow-{level}`
+- **Use For:** Warning messages, caution states
+- **Example:** `background: var(--slds-g-color-palette-yellow-95); color: var(--slds-g-color-palette-yellow-10);`
+
+#### Teal (Success)
+
+- **Hook Pattern:** `--slds-g-color-palette-teal-{level}`
+- **Use For:** Success messages, completed states
+- **Example:** `background: var(--slds-g-color-palette-teal-95); color: var(--slds-g-color-palette-teal-10);`
+
+#### Blue (Information)
+
+- **Hook Pattern:** `--slds-g-color-palette-blue-{level}`
+- **Use For:** Informational messages, help text
+- **Example:** `background: var(--slds-g-color-palette-blue-95); color: var(--slds-g-color-palette-blue-10);`
+
+---
+
+### Expressive Palettes (Data Visualization - Use Sparingly)
+
+**10% of your UI maximum** - Use only when semantic and foundation palettes don't fit.
+
+#### Cool Tones (Recommended for General Use)
+
+**Cloud Blue**
+
+- **Hook Pattern:** `--slds-g-color-palette-cloud-blue-{level}`
+- **Use For:** Data visualization, cool-toned accents
+- **Note:** Use intentionally to avoid confusion with blue (info feedback)
+
+**Indigo**
+
+- **Hook Pattern:** `--slds-g-color-palette-indigo-{level}`
+- **Use For:** Data visualization
+- **Warning:** Similar to brand color - avoid using for interactive elements that could disrupt button hierarchy
+
+**Purple**
+
+- **Hook Pattern:** `--slds-g-color-palette-purple-{level}`
+- **Use For:** Data visualization, expressive interfaces
+- **Good For:** Charts, dashboards
+
+**Violet**
+
+- **Hook Pattern:** `--slds-g-color-palette-violet-{level}`
+- **Use For:** Data visualization emphasis
+- **Good For:** Accent colors in visualizations
+
+#### Warm Tones (Use with Caution - Attention-Grabbing)
+
+**Green**
+
+- **Hook Pattern:** `--slds-g-color-palette-green-{level}`
+- **Use For:** Drawing attention to important information
+- **Warning:** Use sparingly to avoid confusion with teal (success feedback)
+
+**Orange**
+
+- **Hook Pattern:** `--slds-g-color-palette-orange-{level}`
+- **Use For:** Highlighting critical areas
+- **Warning:** Use sparingly to avoid confusion with yellow (warning feedback)
+
+**Hot Orange**
+
+- **Hook Pattern:** `--slds-g-color-palette-hot-orange-{level}`
+- **Use For:** Maximum attention-grabbing, critical states
+- **Reserve For:** Truly critical states only
+
+**Red**
+
+- **Hook Pattern:** `--slds-g-color-palette-red-{level}`
+- **Use For:** Issues, urgent information
+- **Warning:** Use intentionally and sparingly to avoid confusion with pink (error feedback)
+
+---
+
+## Critical: Dark Mode Support with `light-dark()`
+
+### The `light-dark()` Function
+
+**⚠️ IMPORTANT:** Modern SLDS uses the `light-dark()` CSS function to enable automatic dark mode support. Understanding this is critical for proper color usage.
+
+#### What is `light-dark()`?
+
+The `light-dark()` function automatically selects between two color values based on the user's color scheme preference:
+
+```css
+/* Syntax */
+color: light-dark(<light-mode-color>, <dark-mode-color>);
+
+/* Example */
+color: light-dark(#000000, #ffffff);
+/* Light mode: black text */
+/* Dark mode: white text */
+```
+
+#### How SLDS Hooks Use `light-dark()`
+
+**Many SLDS hooks internally use `light-dark()` to adapt to themes:**
+
+```css
+/* What you write */
+color: var(--slds-g-color-accent-1);
+
+/* What the hook actually contains */
+--slds-g-color-accent-1: light-dark(#066afe, #066afe);
+/* Adapts: blue in light mode, same blue in dark mode */
+
+/* Another example */
+--slds-g-color-palette-neutral-10: light-dark(#181818, #f3f3f3);
+/* Adapts: near-black in light mode, near-white in dark mode */
+```
+
+#### Why This Matters
+
+**❌ DON'T hard-code colors - breaks dark mode:**
+
+```css
+/* BAD - Hard-coded colors don't adapt */
+.card {
+  background: #ffffff; /* Always white - breaks dark mode */
+  color: #000000; /* Always black - invisible on dark backgrounds */
+}
+
+/* Result in dark mode: White card on dark background = blinding */
+/* Text: Black on black = invisible */
+```
+
+**✅ DO use SLDS hooks - automatic adaptation:**
+
+```css
+/* GOOD - Hooks adapt automatically */
+.card {
+  background: var(--slds-g-color-surface-container-1);
+  /* Light mode: white background */
+  /* Dark mode: dark background */
+
+  color: var(--slds-g-color-on-surface-2);
+  /* Light mode: dark text */
+  /* Dark mode: light text */
+}
+
+/* Result: Perfect in both modes */
+```
+
+#### When Single Colors Are Dangerous
+
+**Single color values assume a specific background:**
+
+```css
+/* DANGEROUS - Assumes light background */
+.text {
+  color: #333333; /* Dark gray */
+  /* Works in light mode */
+  /* FAILS in dark mode - low contrast */
+}
+
+/* SAFE - Uses hook with light-dark() */
+.text {
+  color: var(--slds-g-color-on-surface-2);
+  /* Automatically adapts to background */
+}
+```
+
+#### The Neutral Palette Inversion
+
+**Critical Understanding:** Neutral palette colors often INVERT between light and dark modes:
+
+```css
+/* Neutral-10 (near black → near white) */
+--slds-g-color-palette-neutral-10: light-dark(#181818, #f3f3f3);
+/* Light mode: very dark (10 on scale) */
+/* Dark mode: very light (90 on scale) - INVERTED */
+
+/* Neutral-95 (near white → near black) */
+--slds-g-color-palette-neutral-95: light-dark(#f3f3f3, #181818);
+/* Light mode: very light (95 on scale) */
+/* Dark mode: very dark (10 on scale) - INVERTED */
+```
+
+**This means:**
+
+- Text colors (neutral-10, neutral-20) become light in dark mode
+- Background colors (neutral-95, neutral-100) become dark in dark mode
+- The 50-point separation rule maintains contrast in both modes
+
+#### Complete Example: Light/Dark Aware Component
+
+```css
+/* ✅ FULLY DARK MODE COMPATIBLE */
+.card {
+  /* Background: white in light mode, dark in dark mode */
+  background: var(--slds-g-color-palette-neutral-100);
+
+  /* Text: dark in light mode, light in dark mode */
+  color: var(--slds-g-color-palette-neutral-10);
+
+  /* Border: mid-gray adapts to theme */
+  border: 1px solid var(--slds-g-color-palette-neutral-70);
+}
+
+.card-header {
+  /* Semantic hook handles dark mode automatically */
+  background: var(--slds-g-color-accent-container-1);
+  color: var(--slds-g-color-on-accent-1);
+}
+
+/* Hover states work in both modes */
+.button {
+  background: var(--slds-g-color-palette-brand-50);
+  color: var(--slds-g-color-palette-brand-100);
+}
+
+.button:hover {
+  /* 10-point shift maintains contrast in both modes */
+  background: var(--slds-g-color-palette-brand-40);
+}
+```
+
+#### Red Flags for Agents
+
+**🚨 Avoid these patterns:**
+
+```css
+/* ❌ Hard-coded hex colors */
+color: #000000;
+background: #ffffff;
+
+/* ❌ Hard-coded rgb colors */
+color: rgb(0, 0, 0);
+background: rgb(255, 255, 255);
+
+/* ❌ Named colors */
+color: black;
+background: white;
+
+/* ❌ Mixing hooks with hard-coded colors */
+background: var(--slds-g-color-surface-1); /* Good */
+color: #333333; /* Bad - won't adapt */
+```
+
+**✅ Safe patterns:**
+
+```css
+/* ✅ SLDS hooks for everything */
+color: var(--slds-g-color-on-surface-2);
+background: var(--slds-g-color-surface-container-1);
+
+/* ✅ Palette hooks (they contain light-dark()) */
+color: var(--slds-g-color-palette-neutral-10);
+background: var(--slds-g-color-palette-neutral-95);
+
+/* ✅ Semantic hooks (pre-configured for dark mode) */
+background: var(--slds-g-color-accent-container-1);
+color: var(--slds-g-color-on-accent-1);
+```
+
+#### Testing Dark Mode
+
+**How to verify your colors work in both modes:**
+
+1. **Use SLDS hooks exclusively** - They handle `light-dark()` internally
+2. **Test with system dark mode** - Enable OS dark mode to see adaptation
+3. **Check contrast in both modes** - 50-point rule works in both
+4. **Never hard-code colors** - Always use hooks
+
+#### Exception: When Hard-Coded Colors Are OK
+
+**Only use hard-coded colors when:**
+
+- Building data visualizations that should look identical in both modes
+- Creating brand assets with specific required colors
+- Logos and images (use as images, not CSS backgrounds)
+
+**Even then, consider:**
+
+```css
+/* Better: Use palette for data viz but acknowledge it's fixed */
+.chart-bar {
+  fill: var(--slds-g-color-palette-purple-50);
+  /* This is immutable - same in light/dark mode */
+  /* Ensure surrounding UI adapts even if chart doesn't */
+}
+```
+
+#### Key Takeaways for Agents
+
+1. **Never hard-code colors** - Always use SLDS hooks
+2. **SLDS hooks contain `light-dark()`** - Automatic adaptation
+3. **Neutral palette inverts** - neutral-10 ↔ neutral-95 swap in dark mode
+4. **50-point rule works in both modes** - Contrast maintained automatically
+5. **Test both modes** - Enable system dark mode to verify
+6. **Semantic hooks are safest** - Pre-validated for dark mode
+
+---
+
+## When to Use Each Tier
+
+### Decision Tree
+
+```
+1. Does a SEMANTIC UI COLOR exist for this use case?
+   ├─ YES → Use semantic hook (Tier 1)
+   │        Examples: --slds-g-color-accent-1, --slds-g-color-surface-1
+   └─ NO → Continue to step 2
+
+2. Is this an edge case where a SYSTEM COLOR makes sense?
+   ├─ YES → Use system color (Tier 2)
+   │        - For brand interactive states: brand-base-*
+   │        - For feedback alerts: error-base-*, warning-base-*, success-base-*
+   │        - For neutral UI: neutral-base-*
+   └─ NO → Continue to step 3
+
+3. Use COLOR PALETTE (Tier 3)
+   - For data visualization: expressive palettes (purple, cloud-blue, etc.)
+   - For general UI when semantic/system don't fit: palette-neutral-*
+   - For custom requirements: any palette color
+
+   Remember: Follow 50-point rule for text, 40-point for UI elements
+```
+
+### Use Semantic UI Colors (Tier 1) When:
+
+- ✅ Building standard UI components (buttons, cards, inputs)
+- ✅ Interactive elements need theme-aware colors
+- ✅ Want automatic light/dark mode adaptation
+- ✅ Need pre-validated accessible pairings
+- **Available Now:** accent-\* hooks (12 total)
+- **Coming Soon:** surface-_, container-_, feedback-_, on-_ hooks
+
+### Use System Colors (Tier 2) When:
+
+- ✅ Semantic UI colors don't make sense for your use case
+- ✅ Need brand-base for interactive states (but accent-\* semantic preferred)
+- ✅ Need feedback colors (error/warning/success) but semantic feedback hooks aren't available
+- ✅ Need neutral colors for edge cases
+- ⚠️ **Important:** These are for edge cases only - prefer semantic when available
+
+### Use Color Palettes (Tier 3) When:
+
+- ✅ Data visualization requiring multiple distinct colors
+- ✅ Custom charts and graphs
+- ✅ Neither semantic nor system colors fit your use case
+- ✅ Need granular control over exact color values
+- ✅ Building custom themes or branding
+- ⚠️ **Remember:** You're responsible for accessibility
+
+---
+
+## The 85-5-10 Color Density Rule
+
+**Mandatory Distribution:**
+
+### 85% - Foundation Colors (Neutral)
+
+```css
+/* Page backgrounds, surfaces, text, borders, structural elements */
+background: var(--slds-g-color-palette-neutral-95);
+color: var(--slds-g-color-palette-neutral-10);
+border-color: var(--slds-g-color-palette-neutral-70);
+```
+
+**Purpose:** Creates the neutral canvas for all content. Uses whites, light grays, dark grays for contrast.
+
+**Allowed Palettes:** Neutral (primary)
+
+**Usage:** Page backgrounds, surface layers, neutral containers, text, borders, structural elements
+
+### 5% - Accents (Brand + Feedback)
+
+```css
+/* Primary actions, selected states, status indicators, CTAs */
+background: var(--slds-g-color-accent-container-1);
+background: var(--slds-g-color-palette-brand-50); /* or brand palette */
+background: var(--slds-g-color-palette-pink-95); /* error feedback */
+```
+
+**Purpose:** Strategic emphasis on interactive elements. Reserved for guiding users toward task completion.
+
+**Allowed Palettes:** Brand, accent semantic, feedback palettes (pink, yellow, teal, blue)
+
+**Usage:** Primary actions, selected states, status indicators, critical CTAs, feedback messages
+
+### 10% - Expressive (Data Viz + Custom)
+
+```css
+/* Data charts, visualization highlights, app-specific accents */
+.chart-series-1 {
+  background: var(--slds-g-color-palette-purple-50);
+}
+.chart-series-2 {
+  background: var(--slds-g-color-palette-cloud-blue-50);
+}
+.chart-series-3 {
+  background: var(--slds-g-color-palette-green-50);
+}
+```
+
+**Purpose:** Extended color options for data visualization and customized app experiences. Use with restraint.
+
+**Allowed Palettes:** Green, Cloud Blue, Indigo, Purple, Violet, Red, Hot Orange, Orange
+
+**Usage:** Data charts, custom branding, visualization highlights, app-specific accents
+
+**Rules:**
+
+- **Cool tones first:** Prioritize Cloud Blue, Purple, Indigo, Violet for general designs - integrate better with foundation palette
+- **Indigo warning:** Resembles brand blue - using carelessly breaks button hierarchy
+- **Warm = attention only:** Orange, Red, Green signal importance - reserve for critical information
+- **Prevent feedback confusion:** Expressive colors can be misinterpreted as system feedback
+
+---
+
+## Common Patterns for Agents
+
+### Pattern 1: Page with Card Layout
+
+```css
+/* 85% - Foundation */
+.page {
+  background: var(--slds-g-color-palette-neutral-100); /* White */
+}
+
+.card {
+  background: var(--slds-g-color-palette-neutral-95); /* Light gray */
+  border: 1px solid var(--slds-g-color-palette-neutral-70);
+  color: var(--slds-g-color-palette-neutral-10);
+}
+
+/* 5% - Accent */
+.primary-button {
+  background: var(--slds-g-color-accent-container-1); /* If available */
+  /* OR */
+  background: var(--slds-g-color-palette-brand-50);
+  color: var(--slds-g-color-palette-brand-100); /* White on brand */
+}
+
+.link {
+  color: var(--slds-g-color-palette-brand-30); /* Brand link color */
+}
+```
+
+### Pattern 2: Form with Validation
+
+```css
+/* Foundation inputs */
+.input {
+  background: var(--slds-g-color-palette-neutral-100);
+  border: 1px solid var(--slds-g-color-palette-neutral-70);
+  color: var(--slds-g-color-palette-neutral-10);
+}
+
+/* 5% - Feedback states */
+.input-error {
+  border-color: var(--slds-g-color-palette-pink-50);
+  background: var(--slds-g-color-palette-pink-95);
+}
+
+.error-message {
+  color: var(--slds-g-color-palette-pink-10);
+  /* 85-point separation from pink-95 background = compliant */
+}
+
+.input-success {
+  border-color: var(--slds-g-color-palette-teal-50);
+}
+```
+
+### Pattern 3: Data Visualization Dashboard
+
+```css
+/* 85% - Foundation */
+.dashboard {
+  background: var(--slds-g-color-palette-neutral-100);
+}
+
+.chart-container {
+  background: var(--slds-g-color-palette-neutral-95);
+  border: 1px solid var(--slds-g-color-palette-neutral-80);
+}
+
+/* 10% - Expressive for data */
+.chart-bar-1 {
+  fill: var(--slds-g-color-palette-purple-50);
+}
+.chart-bar-2 {
+  fill: var(--slds-g-color-palette-cloud-blue-50);
+}
+.chart-bar-3 {
+  fill: var(--slds-g-color-palette-indigo-50);
+}
+.chart-bar-4 {
+  fill: var(--slds-g-color-palette-violet-50);
+}
+
+/* Labels maintain neutral foundation */
+.chart-label {
+  fill: var(--slds-g-color-palette-neutral-20);
+}
+```
+
+### Pattern 4: Interactive States with Palette
+
+```css
+.custom-button {
+  /* Default state - using brand palette */
+  background: var(--slds-g-color-palette-brand-50);
+  color: var(--slds-g-color-palette-brand-100); /* White */
+  border: 1px solid var(--slds-g-color-palette-brand-40);
+}
+
+.custom-button:hover {
+  /* 10 points darker for hover */
+  background: var(--slds-g-color-palette-brand-40);
+  border-color: var(--slds-g-color-palette-brand-30);
+}
+
+.custom-button:active {
+  /* 20 points darker for active */
+  background: var(--slds-g-color-palette-brand-30);
+  border-color: var(--slds-g-color-palette-brand-20);
+}
+
+.custom-button:disabled {
+  /* Use neutral for disabled */
+  background: var(--slds-g-color-palette-neutral-90);
+  color: var(--slds-g-color-palette-neutral-50);
+  border-color: var(--slds-g-color-palette-neutral-80);
+}
+```
+
+---
+
+## Accessibility Best Practices
+
+### Text Contrast (50-Point Rule)
+
+```css
+/* ✅ ALWAYS COMPLIANT */
+.text-light-bg {
+  background: var(--slds-g-color-palette-neutral-95);
+  color: var(--slds-g-color-palette-neutral-10);
+  /* 85-point separation = 7:1+ contrast */
+}
+
+.text-dark-bg {
+  background: var(--slds-g-color-palette-blue-20);
+  color: var(--slds-g-color-palette-blue-75);
+  /* 55-point separation = 5:1+ contrast */
+}
+
+/* ⚠️ BORDERLINE - Test manually */
+.text-mid-bg {
+  background: var(--slds-g-color-palette-neutral-50);
+  color: var(--slds-g-color-palette-neutral-100);
+  /* Exactly 50-point separation = ~4.5:1 */
+}
+```
+
+### UI Element Contrast (40-Point Rule)
+
+```css
+/* ✅ COMPLIANT borders and icons */
+.bordered-element {
+  background: var(--slds-g-color-palette-neutral-100);
+  border: 2px solid var(--slds-g-color-palette-neutral-60);
+  /* 40-point separation = 3:1+ contrast */
+}
+
+.icon-button {
+  background: var(--slds-g-color-palette-neutral-95);
+  /* Icon color */
+  color: var(--slds-g-color-palette-neutral-40);
+  /* 55-point separation = good contrast for icons */
+}
+```
+
+### Additional Considerations
+
+1. **Don't rely on color alone** - Always pair with icons, labels, or patterns
+2. **Test with colorblind simulation** - Especially for data visualizations with multiple colors
+3. **Provide text alternatives** - For charts and visualizations
+4. **Use semantic colors when possible** - They're pre-validated for accessibility
+
+---
+
+## Troubleshooting for Agents
+
+### Problem: Colors look wrong or don't match designs
+
+**Solution:**
+
+- Check if you should be using semantic accent hooks instead of palette
+- Verify you're using the correct point level (50 for mid-tone, 10 for dark text, 95 for light backgrounds)
+- Ensure 85-5-10 density rule is maintained
+
+### Problem: Text is hard to read
+
+**Solution:**
+
+- Verify 50-point separation between text and background
+- Use lower numbers (10-30) for text on light backgrounds
+- Use higher numbers (70-95) for text on dark backgrounds
+
+### Problem: Too much color in the UI
+
+**Solution:**
+
+- Check 85-5-10 distribution - most UI should be neutral
+- Reserve accent colors for primary actions only
+- Use expressive palettes only for data visualization
+
+### Problem: Interactive states are unclear
+
+**Solution:**
+
+- Use 10-point steps for state transitions (50 → 40 → 30)
+- Ensure borders also darken with background
+- Consider using semantic accent hooks if available
+
+---
+
+## Summary for Coding Agents
+
+**Quick Rules:**
+
+1. **NEVER hard-code colors** - Always use SLDS hooks (they contain `light-dark()`)
+2. **85% neutral** - Use `neutral-*` palette for foundation
+3. **5% accent** - Use `accent-*` semantic or `brand-*` palette for actions
+4. **10% expressive** - Use cool tone palettes for data viz
+5. **50-point separation** - For text on backgrounds (4.5:1)
+6. **40-point separation** - For UI elements like borders (3:1)
+7. **10-point steps** - For interactive state transitions
+8. **Test dark mode** - Hooks adapt automatically via `light-dark()`
+
+**Search for Hooks:**
+
+```javascript
+// Find all palette colors
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-g-color-palette-' });
+
+// Find specific palette
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'palette-neutral' });
+
+// Check specific hook
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ hooks: ['--slds-g-color-palette-blue-50'] });
+```
+
+**When in Doubt:**
+
+- Use `neutral-95` for backgrounds
+- Use `neutral-10` for text
+- Use `neutral-70` for borders
+- Use semantic `accent-*` hooks when available
+- Test contrast with the magic numbers
+
+---
+
+**References:**
+
+- [SLDS Color Overview](https://www.lightningdesignsystem.com/2e1ef8501/p/655b28-color)
+- [Accent Hooks Documentation](../global-semantic/accent-hooks.json)
+- [Complete Hooks Index](../metadata/hooks-index.json)