@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/applying-slds/guidance/icons-guidance.md

@@ -0,0 +1,186 @@
+---
+id: slds.guidance.icons
+title: SLDS Icons Guidance
+description: Icon selection and implementation guidance for coding agents
+summary: "Icon implementation guide covering the sprite:symbol naming model, category decision guide (action, utility, standard, custom, doctype), implementation patterns for Lightning and SLDS markup, and accessibility requirements."
+
+artifact_type: guide
+domain: icons
+topic: icons
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, implement]
+
+refs:
+  - slds.guidance.development
+  - slds.guidance.design
+  - slds.guidance.blueprints
+
+tags: [icons, sprites, svg, utility-icons, action-icons, standard-icons]
+keywords: [icon sprites, utility icons, action icons, standard icons, custom icons, doctype icons, icon accessibility, SVG icons]
+---
+
+# SLDS Icons Guidance
+
+## Overview
+
+SLDS icons are a curated set of reusable SVG symbols grouped into **sprite categories**. They're used to add quick, consistent visual meaning to UI elements (buttons, navigation, record headers, status indicators, file types, and more).
+
+This guidance covers:
+
+- **Category guidance** for picking the right sprite
+- **Implementation patterns** (Lightning + SLDS markup)
+- **Accessibility requirements** for icons in UI
+
+---
+
+## Icon Naming Model (Critical)
+
+An icon is referenced as:
+
+- **`sprite:symbol`** (example: `utility:search`, `action:save`, `standard:account`)
+
+Where:
+
+- **sprite** = category (action, utility, standard, custom, doctype)
+- **symbol** = the icon name within that sprite
+
+---
+
+## Category Decision Guide (What to Use When)
+
+### Action Icons (`action:*`)
+
+- **Use for**: verbs / user actions (save, delete, edit, add, close)
+- **Common placements**: buttons, menus, toolbars, row actions
+- **Rule of thumb**: if the UI text could start with "Do …", use `action:`
+
+### Utility Icons (`utility:*`)
+
+- **Use for**: general interface affordances and controls (search, settings, filter, chevrons)
+- **Common placements**: nav, search fields, utility panels, small inline UI hints
+- **Rule of thumb**: if it's a UI control concept (not a business object), use `utility:`
+
+### Standard Icons (`standard:*`)
+
+- **Use for**: Salesforce objects/entities (Account, Contact, Case, Opportunity)
+- **Common placements**: record headers, object pickers, list tiles
+- **Rule of thumb**: if the icon represents "what this thing is" (a noun/object), use `standard:`
+
+### Custom Icons (`custom:*`)
+
+- **Use for**: generic shapes/symbols, often for custom objects when no standard icon fits
+- **Common placements**: custom object tiles, app launcher tiles, branded placeholders
+- **Rule of thumb**: use `custom:` when `standard:` is not appropriate and you still want a "record/object style" icon
+
+### Doctype Icons (`doctype:*`)
+
+- **Use for**: file types (pdf, image, spreadsheet, etc.)
+- **Common placements**: attachments, file lists, previews
+- **Rule of thumb**: if you're representing a file format, use `doctype:`
+
+---
+
+## How to Search Icons
+
+**Effective query patterns:**
+
+- **Intent-first**: "save", "delete", "filter", "settings", "add user"
+- **Object-first**: "account", "contact", "case"
+- **UI affordance**: "chevron right", "close x", "search magnifier"
+
+**Optional filters:**
+
+- Restrict to a sprite category (action / utility / standard / custom / doctype)
+- Limit results to keep responses tight
+
+### Searchable Metadata Fields
+
+Each icon entry in the JSON metadata supports these lookup strategies:
+
+- **Exact match**: `category` + icon name (mapped to `sprite:symbol` at runtime, e.g. `utility:chevronright`)
+- **Discovery**: `synonyms` (best for intent searches — e.g. "next" finds `chevronright`)
+- **Styling**: `className` (computed as `slds-icon-{category}-{name}` for SLDS `<svg>` containers)
+- **Context**: `description` (matches long-form queries about icon purpose)
+- **RTL**: `directionality.hasRtl` (rare, but important for directional glyphs)
+
+---
+
+## Implementation Patterns
+
+### Lightning Web Components (preferred inside Salesforce)
+
+**Icon only:**
+
+```html
+<lightning-icon
+  icon-name="utility:search"
+  alternative-text="Search"
+  title="Search"
+  size="x-small">
+</lightning-icon>
+```
+
+**Icon button:**
+
+```html
+<lightning-button-icon
+  icon-name="action:save"
+  alternative-text="Save"
+  title="Save"
+  onclick={handleSave}>
+</lightning-button-icon>
+```
+
+### SLDS (raw HTML/SVG usage)
+
+If you're implementing outside Lightning components, use the `className` from the JSON (example: `slds-icon-utility-search`) with the appropriate SLDS blueprint patterns for icon containers.
+
+---
+
+## Sizes
+
+When rendering icons in Lightning Web Components, prefer the built-in size tokens on `lightning-icon` / `lightning-button-icon` instead of custom CSS.
+
+| Size token | Typical use |
+|-----------|-------------|
+| `xx-small` | Inline with dense UI or text-adjacent glyphs |
+| `x-small` | Compact layouts / tight controls |
+| `small` | Default for most utility UI icons |
+| `medium` | Default for object/record representation icons |
+| `large` | Featured / hero contexts (use sparingly) |
+
+---
+
+## Accessibility Requirements (Do Not Skip)
+
+### When the icon communicates meaning
+
+- **Provide text** for assistive tech:
+  - LWC: `alternative-text` (required), `title` (recommended)
+  - HTML/SVG: ensure an accessible name via text, `aria-label`, or `title` as appropriate
+
+### When the icon is purely decorative
+
+- Hide it from assistive tech (don't create "noise"):
+  - LWC: use an empty `alternative-text=""` only if the containing control already has an accessible label
+  - HTML/SVG: `aria-hidden="true"` on the decorative icon element
+
+### Don't rely on icons alone
+
+If the icon represents status (success/error/warning), ensure there's **text and/or non-color cues** in addition to the icon.
+
+---
+
+## Icon Metadata Structure
+
+All 1,732 icons are stored in a single `icon-metadata.json` file, keyed by icon name. Each entry includes:
+
+- `displayName` — the icon identifier (e.g. `chevronright`, `add_contact`)
+- `category` — sprite category: `action`, `utility`, `standard`, `custom`, `doctype`
+- `synonyms` — search terms for discovery (e.g. `["next", "forward", "arrow", "chevron"]`)
+- `description` — what the icon represents
+- `directionality` — `type` (`common` or `directional`) and `hasRtl` flag

package/skills/applying-slds/guidance/overviews/borders.md

@@ -0,0 +1,236 @@
+---
+id: slds.guidance.overview.borders
+title: Borders and Radius Overview
+description: Foundational principles and constraints for border and radius decisions in SLDS
+summary: "Comprehensive border guidance covering SLDS 2 design philosophy (minimal borders), border width usage, radius categories, and when borders are appropriate. Critical for SLDS 1 to SLDS 2 migration."
+
+artifact_type: overview
+domain: overviews
+topic: borders
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.hooks.borders
+
+tags: [borders, radius, corners, visual-structure, slds2-migration]
+keywords: [border width, border radius, corners, SLDS 2 design, minimal borders, visual separation, container borders]
+---
+
+# Borders and Radius Guidance for SLDS Implementation
+
+**Purpose:** This document provides the foundational principles and constraints for all border and radius decisions in Salesforce Lightning Design System. Borders and radiuses are basic visual design elements that help create clarity, hierarchy, and a consistent look. When implementing components and layouts, follow these guidelines to ensure visual harmony and cohesion across all experiences.
+
+---
+
+## Core Principles
+
+When working with borders and radiuses in UI interfaces, adhere to these foundational principles:
+
+1. **Create clarity through structure.** Borders delineate components and sections for better readability and navigation. Use them to separate content areas, indicate clickable elements, or highlight active states.
+
+2. **Support hierarchy and meaning.** Borders differentiate elements to show importance or interactivity. Ensure border treatments draw attention to important features without overwhelming the experience.
+
+3. **Maintain consistency and harmony.** Apply consistent thickness, color, and radius across similar elements. Avoid mixing sharp and rounded corners within the same component to keep designs looking polished and cohesive.
+
+4. **Foster accessibility.** Use subtle but effective visual cues to support usability for all users. Ensure borders remain visible and easy to perceive across all screen sizes and resolutions.
+
+---
+
+## SLDS 2 Design Philosophy
+
+**CRITICAL:** SLDS 2 does not use borders around cards and components, unlike SLDS 1.
+
+This represents a significant design shift from previous versions. When uplifting code from SLDS 1 to SLDS 2, remove decorative borders from cards, panels, and container components. SLDS 2 relies more on spacing, shadows, and surface colors to create visual separation rather than explicit borders.
+
+**When borders ARE appropriate in SLDS 2:**
+- Separating content using neutral borders to divide sections or groups of related content
+- Highlighting interactive elements by applying neutral borders for structure, or accent colors for specific branded variants and focus states
+- Communicating component states with context-appropriate colors like red for error states or lighter shades for disabled components
+- Creating subtle divider lines between content areas
+
+---
+
+## Borders Fundamentals
+
+### What are Borders?
+
+Borders outline elements and provide structure, serving as visual separators, indicators of interactivity, or highlights for active or selected states. Border width, sometimes called stroke width, refers to the thickness of the lines that define the edges of components, containers, and other visual elements.
+
+**Borders help with these design aspects:**
+- Differentiate between various UI elements, such as cards, panels, or input fields
+- Highlight important information and de-emphasize less important information
+- Make content more accessible by ensuring that borders are always visible and easy to read on all screen sizes and resolutions
+
+### Best Practices for Borders
+
+- **Less is Best** — Apply borders sparingly to avoid visual clutter. SLDS 2 favors minimal border usage.
+- **Consistency** — Use consistent thickness and color across similar elements.
+- **Subtlety** — Use light or subtle borders to create separation without overwhelming the interface.
+
+---
+
+## Radius Fundamentals
+
+### What is Radius?
+
+Radius defines how rounded the corners are on elements. Borders have a radius, and container elements such as cards and buttons have a radius too. Rounded corners soften the visual appearance and create a more approachable design style.
+
+**Radius contributes to the design in these ways:**
+- Establish a consistent style for rounded corners across components such as cards, modals, and buttons
+- Create a modern, approachable aesthetic that aligns with the brand identity
+- Improve usability by subtly guiding users' focus to key interface elements
+
+> **For radius sizing guidance** and component examples, refer to the Borders and Radius Styling Hooks documentation.
+
+### Best Practices for Radius
+
+- **Consistency** — Apply the same radius to similar elements for a cohesive design style throughout the interface.
+- **Harmony** — Avoid mixing sharp and rounded corners. Mixing these styles within the same component can create a visually jarring experience and reduce design harmony.
+- **Branding** — Use the radius to reflect the brand's personality. Whether the brand should be approachable, professional, or bold, use the SLDS 2 design guidelines to choose the right radius for the elements.
+- **Usability** — Confirm through testing that rounded corners don't detract from clarity or usability, especially for focus and hover states in interactive elements.
+
+### Nested Container Pattern
+
+Nested containers should use the next smaller radius value to maintain visual harmony. For example, if an outer card uses `--slds-g-radius-border-4`, a nested card inside should use `--slds-g-radius-border-3`. This creates a consistent visual rhythm where inner elements have subtly tighter corners than their parent containers.
+
+---
+
+## Border Color Fundamentals
+
+SLDS 2 uses specific colors for borders to align with the system's visual design, ensuring clarity and usability across all products.
+
+### Common Border Colors and Meanings
+
+- **Neutral grays** — The standard choice for creating structural separation and outlining functional components
+- **Accent colors (Blue)** — Reserved for specialized branded treatments and thematic emphasis
+- **Dark blue** — Indicates an element has focus
+- **Red** — Indicates an error state
+- **Yellow** — Indicates a warning state
+- **Transparent or white** — Maintains visual balance in lighter or less prominent elements
+
+### Where to Use Border Colors
+
+- **Separate and outline content** — Use neutral gray borders to divide sections or outline standard functional components (buttons, inputs)
+- **Highlight branded elements** — Apply accent colors for specialized branded treatments or thematic emphasis
+- **Communicate focus** — Use dark blue focus indicators to support accessibility
+
+> **For complete border color hook details**, refer to the Color Overview and Semantic Color Styling Hooks documentation, which covers the full semantic color system including border-specific tokens.
+
+---
+
+## Theming Considerations
+
+SLDS 2 allows for customizable theming. When making changes to borders or radiuses:
+
+- Ensure any customizations align with brand guidelines
+- Maintain contrast ratios for accessibility
+- Verify border treatments appear correctly across light/dark themes
+- Use styling hooks to enable theme adaptability rather than hard-coded values
+
+---
+
+## Density Awareness Note
+
+**Important:** Unlike spacing and typography, borders and radius values are NOT density-aware in SLDS 2. Border width and radius values remain constant regardless of whether the user has selected comfy or compact display density mode.
+
+When implementing density-aware layouts, note that:
+- Border thickness stays the same across density modes
+- Radius values stay the same across density modes
+- Spacing around bordered elements may change (via density-aware spacing hooks), but the borders themselves do not adapt
+
+---
+
+## Available Styling Hooks
+
+### Border Width Hooks
+
+- `--slds-g-sizing-border-*`
+
+### Border Radius Hooks
+
+- `--slds-g-radius-border-*`
+- `--slds-g-radius-border-circle`
+- `--slds-g-radius-border-pill`
+
+### Border Color Hooks
+
+Border color hooks are part of the semantic color system. Key hooks include:
+
+- `--slds-g-color-border-*` — Neutral borders for functional structure
+- `--slds-g-color-border-accent-*` — Branded emphasis and thematic exceptions
+- `--slds-g-color-border-error-*` — Error state borders
+- `--slds-g-color-border-success-*` — Success state borders
+- `--slds-g-color-border-warning-*` — Warning state borders
+- `--slds-g-color-border-disabled-*` — Disabled state borders
+- `--slds-g-color-border-inverse-*` — Borders on dark backgrounds
+
+> **For detailed usage patterns**, refer to the Borders and Radius Styling Hooks documentation.
+
+---
+
+## Implementation Workflow
+
+Follow this sequence when implementing any border or radius solution:
+
+### Step 1: Determine if a Border is Needed
+
+Apply the SLDS 2 design philosophy — borders should be used sparingly. Ask:
+- Is this border necessary for structure or clarity?
+- Could spacing or shadows achieve the same visual separation?
+- Am I uplifting from SLDS 1 where borders were used decoratively?
+
+### Step 2: Select the Appropriate Treatment
+
+If a border is needed, determine:
+- **Width** — Select the visual weight needed for the component type
+- **Radius** — Match to content density (smaller for dense, larger for spacious)
+- **Color** — Select based on semantic meaning (neutral, accent, feedback, inverse)
+
+### Step 3: Apply Styling Hooks
+
+Never use hard-coded values. Use the appropriate styling hooks:
+- Width: `--slds-g-sizing-border-*`
+- Radius: `--slds-g-radius-border-*`
+- Color: `--slds-g-color-border-*`
+
+### Step 4: Validate Implementation
+
+Before finalizing, verify the implementation using the Pre-Implementation Checklist below.
+
+---
+
+## Pre-Implementation Checklist
+
+Before generating or modifying any border or radius related code, verify:
+
+| Requirement | Status |
+|-------------|--------|
+| **Design Philosophy** | |
+| Confirmed border is necessary (not decorative holdover from SLDS 1) | [ ] |
+| Evaluated alternatives (spacing, shadows) before adding border | [ ] |
+| **Hook Selection** | |
+| Using styling hooks (no hard-coded pixel values) | [ ] |
+| Width hook selected matches visual weight needed | [ ] |
+| Radius hook selected matches content density | [ ] |
+| Color hook selected matches semantic meaning | [ ] |
+| **Consistency & Harmony** | |
+| Consistent border treatment across similar elements | [ ] |
+| No mixing of sharp and rounded corners in same component | [ ] |
+| Border color aligns with surrounding design context | [ ] |
+| **Accessibility** | |
+| Border visible and perceivable across screen sizes | [ ] |
+| Sufficient contrast with adjacent surfaces | [ ] |
+| Focus states clearly indicated | [ ] |
+| **Theming** | |
+| Works across light/dark themes | [ ] |
+| Maintains brand alignment | [ ] |
+
+**Target outcome:** Clean, minimal interfaces that use borders purposefully for structure and meaning, not decoration. Visual separation achieved through spacing and depth where possible.
+
+
+

package/skills/applying-slds/guidance/overviews/color.md

@@ -0,0 +1,266 @@
+---
+id: slds.guidance.overview.color
+title: Color Overview
+description: Foundational principles and constraints for all color decisions in SLDS
+summary: "Comprehensive color guidance covering the 85-5-10 density rule, color role taxonomy, hook selection hierarchy, and numerical color system. The primary reference for all color implementation decisions."
+
+artifact_type: overview
+domain: overviews
+topic: color
+
+content_format: narrative
+complexity: foundational
+audience: [implementer, designer]
+
+tasks: [learn, choose, implement]
+
+refs:
+  - slds.guidance.hooks.color.accent
+  - slds.guidance.hooks.color.surface
+  - slds.guidance.hooks.color.feedback
+  - slds.guidance.hooks.color.system
+  - slds.guidance.hooks.color.expressive-palette
+
+tags: [color, semantic-color, accessibility, visual-hierarchy, theming]
+keywords: [color roles, 85-5-10 rule, hook selection, semantic hooks, color taxonomy, surfaces, accents, feedback colors]
+---
+
+# Color Guidance for SLDS Implementation
+
+**Purpose:** This document provides the foundational principles and constraints for all color-related decisions in Salesforce Lightning Design System. Always reference the companion metadata files for specific token names, contrast pairings, and approved combinations.
+
+---
+
+## Core Principles
+
+When working with colors in UI interfaces, adhere to these three foundational principles:
+
+1. **Signal hierarchy and meaning.** Color must highlight actions, alerts, and key information without overpowering the experience. Do not use color decoratively.
+
+2. **Accessibility is mandatory.** All implementations must meet WCAG 2.1 AA minimum standards for text and interactive elements. Use only the approved pairings documented in the metadata layer.
+
+3. **Maintain system consistency.** Always use semantic styling hooks. These tokens automatically adapt to brand themes, density modes, and light/dark modes. Never use hard-coded color values.
+
+---
+
+## Color Role Taxonomy
+
+Every element must be classified into one of these five color roles before selecting a token:
+
+- **Surfaces:** The base canvas for content. Each new layer (panel, modal, popover) is a distinct surface with its own depth level. Use surface tokens for backgrounds.
+
+- **Containers:** Elements that hold interactive or readable content (cards, buttons, tabsets). Always pair container background colors with their corresponding "on-container" tokens for text and icons.
+
+- **Accents:** Colors that draw attention to primary interactions or selected states. Use sparingly and only for meaningful emphasis. Overuse destroys visual hierarchy.
+
+- **Feedback colors:** Status indicators (error, warning, success, info, disabled). Reserve exclusively for CRUD operations and system feedback. Never use for general styling.
+
+- **Borders/dividers:** Structural elements that create separation. Must maintain sufficient contrast with adjacent surfaces and containers.
+
+---
+
+## Color Density Rule (85-5-10)
+
+**CONSTRAINT:** All UI implementations should maintain the following color distribution. This distribution is strongly recommended for maintaining SLDS visual consistency.
+
+### UI Foundation: 85% (Required)
+Foundational colors create the neutral canvas for all content. Use whites, light grays, dark grays, and dark blue for contrast with text and interactive elements.
+
+**Allowed Palettes:** Whites, light grays, dark grays, dark blue  
+**Usage:** Page backgrounds, surface layers, neutral containers, structural elements
+
+### Accents: 5% (Required)
+Accent colors are reserved for strategic emphasis on interactive elements. Use the foundational accent (electric blue) and feedback palettes (pink, yellow, teal, blue) to guide users toward task completion.
+
+**Allowed Palettes:** Foundational accent (electric blue), feedback (pink, yellow, teal, blue), functional accent colors  
+**Usage:** Primary actions, selected states, status indicators, critical CTAs
+
+### Expressive Colors: 10% (Maximum)
+Expressive palettes provide 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
+
+**Strict Usage Rules:**
+- **Cool tones first.** Prioritize Cloud Blue, Purple, Indigo, Violet for general page designs. These integrate better with the foundational palette.
+- **Indigo warning.** Indigo resembles electric blue. Using it carelessly will break button hierarchy and confuse users about interactive affordances.
+- **Warm = attention only.** Orange, Red, and Green signal importance or issues. Reserve them exclusively for drawing user attention to critical information.
+- **Prevent feedback confusion.** Expressive colors can be misinterpreted as system feedback (pink=error, yellow=warning, teal=success, blue=info). Apply expressive colors minimally to avoid this conflict.
+
+---
+
+## The Numerical Color System
+
+**System Architecture:** SLDS uses a 0-100 point scale where accessibility compliance is mathematically guaranteed:
+
+- **100 points** = white
+- **0 points** = black
+- **Color lane** = full 0-100 spectrum of a single hue
+- **Color step** = 5-10 point increments within a lane (e.g., Cloud Blue-15, Cloud Blue-25, Cloud Blue-35)
+
+### How It Works
+
+Colors share horizontal point values across different hues. This means the same mathematical rules apply:
+- Vertically within each monochromatic palette (single lane)
+- Horizontally across all color lanes (different hues)
+
+This consistency enables pattern replication across the entire system.
+
+### Automatic Accessibility: Magic Numbers
+
+**CRITICAL:** Use these point separations to achieve WCAG compliance without manual checking:
+
+| Separation | Contrast Ratio | Use Case | WCAG Level |
+|------------|----------------|----------|------------|
+| **50 points** | 4.5:1+ | Text on backgrounds, body copy | AA (required) |
+| **40 points** | 3:1+ | UI elements, borders, non-text | AA (required) |
+
+**Works across hues:** A 50-point separation maintains 4.5:1 contrast even when using different color lanes.
+
+**Example Application:**
+- Page background: Gray-95
+- Button background: Any-50 (45 point difference = compliant)
+- Button hover: Any-40 (55 point difference = compliant)
+- Button text: Any-0 or Any-100 depending on background
+
+The 10-point step from 50→40 creates consistent hover states across all color lanes.
+
+**Attribution:** The "magic numbers" concept originates from the U.S. Web Design System (USWDS) and has been adopted into SLDS to ensure systematic color progression and accessibility.
+
+---
+
+## Implementation Workflow
+
+Follow this mandatory sequence when implementing any color solution:
+
+### Step 1: Classify the Element
+Identify the element's semantic role:
+- Is it a **surface** (background layer)?
+- Is it a **container** (holds content)?
+- Is it an **accent** (emphasis/interaction)?
+- Is it **feedback** (status/state)?
+- Is it a **border/divider** (structure)?
+
+### Step 2: Reference the Metadata
+Never invent color values. The companion metadata files contain:
+- Approved styling hook names
+- Pre-validated contrast pairings
+- State transition sequences (default → hover → active → disabled)
+- Theme adaptations (light/dark/branded)
+
+### Step 3: Handle Exceptions
+If no semantic hook matches the requirement:
+1. Document why standard patterns don't apply
+2. Verify contrast manually using the numerical system
+3. Ensure brand consistency is maintained
+4. Flag for design system team review
+
+### Step 4: Validate Implementation
+Before finalizing, verify the implementation using the Pre-Implementation Checklist below to ensure all color requirements are met.
+
+---
+
+## Metadata Integration
+
+**Source of Truth:** The metadata files are authoritative for all implementation details.
+
+**What the metadata provides:**
+- Exact token names and values
+- Pre-validated contrast pairings (text-on-background, icon-on-surface)
+- State progression maps (default → hover → active → focus → disabled)
+- Cross-reference between semantic roles and color values
+- Theme-specific overrides
+
+**When to consult metadata:**
+- Before selecting any color token
+- When implementing state changes
+- When validating a custom pattern
+- When introducing new component styles
+
+**Validation question:** Does this color choice reinforce semantic meaning, meet accessibility standards, and maintain brand consistency?
+
+---
+
+## Hook Selection Hierarchy
+
+When selecting color hooks, follow this decision order:
+
+### 1. Semantic Hooks (First Choice — 85% of Cases)
+**Pattern:** `--slds-g-color-{purpose}-{n}` (e.g., `error-1`, `accent-container-1`, `surface-1`)
+
+Use semantic hooks for standard UI patterns. These hooks:
+- Are purpose-built for specific UI use cases (errors, accents, surfaces, feedback)
+- Automatically adapt to light/dark mode with curated values
+- Have pre-validated accessibility pairings
+- Reference system and palette hooks underneath
+
+**Use when:** You can describe your element using semantic terms (surface, accent, error, warning, success, disabled).
+
+### 2. System Hooks (Edge Cases — 5-10% of Cases)
+**Pattern:** `--slds-g-color-{category}-base-{grade}` (e.g., `error-base-50`, `brand-base-40`)
+
+Use system hooks when semantic hooks don't cover your specific need. These hooks:
+- Provide grade-level control within a color category
+- Still adapt to light/dark mode with curated values per mode
+- Reference palette hooks underneath
+
+**Use when:** Data visualization, legacy migration, or custom requirements where semantic hooks are insufficient.
+
+### 3. Palette Hooks (Raw Access — Rare Cases)
+**Pattern:** `--slds-g-color-palette-{color}-{grade}` (e.g., `palette-pink-50`, `palette-cloud-blue-30`)
+
+Use palette hooks only when system hooks don't meet your requirements. These hooks:
+- Provide direct access to the color palette by color name and grade
+- Have light/dark mode variants
+- Are the foundation that semantic and system hooks reference
+
+**Use when:** Custom color requirements that don't fit any semantic or system category.
+
+### Internal Hooks (Not for External Use)
+
+The following hook prefixes are **internal to Salesforce** and should not be used by external developers:
+
+| Prefix | Name | Audience |
+|--------|------|----------|
+| `--slds-s-*` | Shared hooks | Internal Salesforce only |
+| `--slds-c-*` | Component hooks | Internal Salesforce only |
+
+### How They Connect (Aliasing Chain)
+
+Semantic hooks reference system hooks, which reference palette hooks. When the theme changes (light → dark), the underlying references change, so semantic hooks automatically adapt.
+
+**Example:** `--slds-g-color-error-1`
+- Light mode: → `error-base-50` → `palette-pink-50` → #hex
+- Dark mode: → `error-base-40` → `palette-pink-40` → #different-hex
+
+This aliasing chain means you get theme adaptation "for free" when using semantic hooks.
+
+---
+
+## Pre-Implementation Checklist
+
+Before generating or modifying any color-related code, verify:
+
+| Requirement | Status |
+|-------------|--------|
+| **Element Classification** | |
+| Element classified by semantic role (surface/container/accent/feedback/border) | [ ] |
+| **Token Selection & Metadata** | |
+| Color token identified from metadata (no hard-coded hex/RGB values) | [ ] |
+| Metadata consulted for approved styling hook names | [ ] |
+| Pre-validated contrast pairings referenced from metadata | [ ] |
+| "On" counterpart specified (for containers) | [ ] |
+| **Contrast & Accessibility** | |
+| Contrast requirements met using numerical system (50pts text, 40pts UI) | [ ] |
+| Works with the numerical color system for automatic accessibility | [ ] |
+| **Color Distribution & Usage** | |
+| 85-5-10 density rule maintained (85% foundation, 5% accent, 10% expressive) | [ ] |
+| Accent/feedback colors used sparingly and meaningfully | [ ] |
+| Color reinforces semantic meaning rather than decorative use | [ ] |
+| **Theme Support & States** | |
+| All theme modes supported (light/dark/compact/branded) | [ ] |
+| State transitions defined (hover/active/focus/disabled) | [ ] |
+| Theme-specific overrides reviewed from metadata where applicable | [ ] |
+
+**Target outcome:** Calm, purposeful interfaces that are unmistakably Salesforce. Color should enhance usability without becoming decorative.
+