Uplifting Components To Slds2

# Color Hooks Decision Guide

This guide helps you choose the correct SLDS 2 color hook. Use it when replacing hardcoded colors or when the linter suggests multiple options.

> **BEFORE choosing any hook:** Always inspect the element's context in this order:
> 1. **Markup** (`.html` for LWC, `.cmp` for Aura) — search for the CSS class. Check parent containers, nesting depth, ARIA attributes, interactive role.
> 2. **JavaScript** — if not in markup, search the JS/TS files for dynamic class insertion (`classList.add`, template literals, conditional class bindings).
>
> CSS alone is never enough — always determine context from markup or JS before choosing a hook.

## Table of Contents

- [Hook Selection Priority](#hook-selection-priority)
- [Surface Family](#surface-family)
- [Accent Family](#accent-family)
- [Feedback Family](#feedback-family)
- [Palette Family](#palette-family)
- [System Family](#system-family)
- [Choosing the Numbered Variant](#choosing-the-numbered-variant)
- [Background-Foreground Pairing Rules](#background-foreground-pairing-rules)
- [Applied Examples](#applied-examples--color-context-investigation)

## Hook Selection Priority

**Always try semantic hooks first.** ~85-90% of color decisions should use semantic hooks. System and palette hooks are last resorts, not alternatives.

```
1. SEMANTIC HOOKS (try first, ~85-90% of decisions)
   surface-*, accent-*, error/warning/success/info/disabled-*
   • Accessibility built-in  • Theme-aware  • Dark mode ready

2. SYSTEM HOOKS (5-10%, only when no semantic family fits)
   *-base-*
   • Manual accessibility required  • No semantic meaning

3. PALETTE (data viz & decorative only, <5%)
   palette-*
   • Manual accessibility  • Non-semantic color only
```

If you find yourself reaching for a system hook, re-check whether a semantic hook applies — surface, accent, or feedback families cover most cases.

**Decision flow:**
1. Page/overlay/container background? → Surface hooks
2. Brand/interactive? → Accent hooks
3. Error/warning/success/info/disabled state? → Feedback hooks
4. Edge case with no semantic fit? → System hooks
5. Data viz or decorative? → Palette hooks

> **Visual color density rule (85-5-10):** ~85% of UI surface area should be neutral grays/whites (surface hooks), ~5% accent/feedback colors, ~10% maximum expressive colors.

### "Color ≠ Semantic Meaning"

| Scenario | Wrong Choice | Right Choice | Why |
|----------|--------------|--------------|-----|
| Red text but no error class | `--slds-g-color-error-1` | `--slds-g-color-palette-red-50` | Color for emphasis, not error state |
| Blue that's not clickable | `--slds-g-color-accent-2` | `--slds-g-color-palette-cloud-blue-50` | Decorative blue, not interactive |
| Green in data chart | `--slds-g-color-success-1` | `--slds-g-color-palette-green-50` | Data point, not success state |
| Orange highlight span | `--slds-g-color-warning-1` | `--slds-g-color-palette-orange-90` | Visual emphasis, not warning |

Use system hooks if the element matches a semantic meaning. If it explicitly does not, use the palette equivalent (e.g., `--slds-g-color-palette-red-40`). Evaluate background-color first, as it informs the correct foreground color pair.

---

## Surface Family

### Core Question
Is this element a page foundation, an overlay (modal/popover/dropdown), or does it sit within the content flow on an existing surface?

| Characteristic | Use `surface-*` | Use `surface-container-*` |
|---|---|---|
| Creates new stacking context | Yes | No |
| Elevated/overlays other content | Yes | No |
| Exists within page's content flow | No | Yes |
| Sits on top of an existing surface | No | Yes |

### Hook Types

| Hook Type | Pattern | Use For |
|---|---|---|
| Surface | `--slds-g-color-surface-1` / `-2` / `-3` | Pages, modals, popovers, overlays |
| Container | `--slds-g-color-surface-container-1` / `-2` / `-3` | Cards, buttons, panels on existing surfaces |
| On Surface | `--slds-g-color-on-surface-1` / `-2` / `-3` | Foregro