@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/applying-slds/guidance/styling-hooks/color/index.md

@@ -0,0 +1,171 @@
+---
+id: slds.guidance.hooks.color
+title: SLDS Color Styling Hooks
+description: Index and decision guide for color styling hooks - semantic, system, and expressive palettes
+summary: "Entry point for color styling hooks. Provides hook selection hierarchy (semantic 85%, system 5-10%, palette 5%), quick decision guide, and pointers to detailed documentation for accent, surface, feedback, system, and expressive colors."
+
+artifact_type: index
+domain: styling-hooks
+topic: color
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, explore]
+
+children:
+  - 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
+
+refs:
+  - slds.guidance.hooks
+  - 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: [styling-hooks, color, index, semantic, system, palette]
+keywords: [color hooks, accent, surface, feedback, system colors, expressive palette, color selection]
+---
+
+# SLDS Color Styling Hooks
+
+## Overview
+
+SLDS color styling hooks provide a systematic approach to applying colors that maintain accessibility, support theming (including dark mode), and create consistent visual hierarchy across all Salesforce interfaces.
+
+## Hook Selection Hierarchy
+
+When choosing color hooks, follow this priority order:
+
+1. **Semantic Hooks (85% of use cases)** - First choice for standard UI
+2. **System Hooks (5-10%)** - Edge cases where semantic hooks don't apply
+3. **Palette Hooks (5%)** - Data visualization and decorative purposes
+
+---
+
+## Semantic Color Hooks
+
+Semantic hooks are purpose-driven and automatically handle accessibility and theming.
+
+### Accent Colors
+
+Brand identity and interactive elements like links, buttons, and icons.
+
+**Hook patterns:** `--slds-g-color-accent-*`, `--slds-g-color-accent-container-*`, `--slds-g-color-border-accent-*`, `--slds-g-color-on-accent-*`
+
+**Use for:** Links, brand buttons, interactive icons, selected states
+
+> **Detailed guidance:** [Accent Color Hooks](ref:slds.guidance.hooks.color.accent)
+
+### Surface Colors
+
+Backgrounds and canvases that establish visual stacking context and enable theming.
+
+**Hook patterns:** `--slds-g-color-surface-*`, `--slds-g-color-surface-container-*`, `--slds-g-color-on-surface-*`
+
+**Use for:** Page backgrounds, modals, cards, panels, popovers
+
+> **Detailed guidance:** [Surface Color Hooks](ref:slds.guidance.hooks.color.surface)
+
+### Feedback Colors
+
+Visual feedback for status and state communication.
+
+**Hook patterns:** `--slds-g-color-error-*`, `--slds-g-color-warning-*`, `--slds-g-color-success-*`, `--slds-g-color-info-*`, `--slds-g-color-disabled-*`
+
+**Use for:** Error messages, warnings, success confirmations, informational alerts, disabled states
+
+> **Detailed guidance:** [Feedback Color Hooks](ref:slds.guidance.hooks.color.feedback)
+
+---
+
+## System Color Hooks
+
+Direct access to brand, neutral, and feedback color palettes for edge cases.
+
+**Hook patterns:** `--slds-g-color-neutral-base-{grade}`, `--slds-g-color-brand-base-{grade}`, `--slds-g-color-error-base-{grade}`, `--slds-g-color-warning-base-{grade}`, `--slds-g-color-success-base-{grade}`
+
+**Use for:** Data visualization, custom brand elements, legacy migration, specialized UI
+
+**Important:** System colors bypass built-in accessibility guarantees. Manual verification required.
+
+> **Detailed guidance:** [System Color Hooks](ref:slds.guidance.hooks.color.system)
+
+---
+
+## Expressive Palette Hooks
+
+Extended color palettes for data visualization and highlighting.
+
+### Cool Tones (Recommended)
+
+- **Cloud Blue:** `--slds-g-color-palette-cloud-blue-{grade}` - Professional, calm
+- **Indigo:** `--slds-g-color-palette-indigo-{grade}` - Similar to brand
+- **Purple:** `--slds-g-color-palette-purple-{grade}` - Expressive, creative
+- **Violet:** `--slds-g-color-palette-violet-{grade}` - Accent, emphasis
+
+### Warm Tones (Use with caution)
+
+- **Green:** `--slds-g-color-palette-green-{grade}` - Highlights (avoid confusion with success)
+- **Orange:** `--slds-g-color-palette-orange-{grade}` - Attention-grabbing
+- **Hot Orange:** `--slds-g-color-palette-hot-orange-{grade}` - Maximum emphasis
+- **Red:** `--slds-g-color-palette-red-{grade}` - Urgent (avoid confusion with error)
+
+**Use for:** Charts, graphs, dashboards, data categories, infographics
+
+> **Detailed guidance:** [Expressive Palette Hooks](ref:slds.guidance.hooks.color.expressive-palette)
+
+---
+
+## The Numerical Color System
+
+SLDS uses a 0-100 grade scale where:
+
+- **0** = Darkest
+- **100** = Lightest
+
+### Accessibility Guarantees
+
+| Separation | Contrast Ratio | Use Case             |
+| ---------- | -------------- | -------------------- |
+| 50 points  | 4.5:1          | Text (WCAG AA)       |
+| 40 points  | 3:1            | UI elements, borders |
+
+### Common Pairings
+
+| Background           | Foreground         | Purpose          |
+| -------------------- | ------------------ | ---------------- |
+| `surface-1`          | `on-surface-1/2/3` | Standard content |
+| `accent-container-1` | `on-accent-1`      | Brand buttons    |
+| `error-container-1`  | `on-error-1`       | Error alerts     |
+
+---
+
+## Quick Decision Guide
+
+| Need              | Hook Category      | Example                                |
+| ----------------- | ------------------ | -------------------------------------- |
+| Link color        | Accent             | `--slds-g-color-accent-2`              |
+| Page background   | Surface            | `--slds-g-color-surface-1`             |
+| Card background   | Surface Container  | `--slds-g-color-surface-container-1`   |
+| Button background | Accent Container   | `--slds-g-color-accent-container-1`    |
+| Error message     | Feedback           | `--slds-g-color-error-1`               |
+| Chart colors      | Expressive Palette | `--slds-g-color-palette-cloud-blue-50` |
+| Body text         | On Surface         | `--slds-g-color-on-surface-2`          |
+
+---
+
+## Detailed Guidance
+
+For implementation details on specific color types, see:
+
+1. **Accent colors:** [Accent Color Hooks](ref:slds.guidance.hooks.color.accent)
+2. **Surface colors:** [Surface Color Hooks](ref:slds.guidance.hooks.color.surface)
+3. **Feedback colors:** [Feedback Color Hooks](ref:slds.guidance.hooks.color.feedback)
+4. **System colors:** [System Color Hooks](ref:slds.guidance.hooks.color.system)
+5. **Expressive palette:** [Expressive Palette Hooks](ref:slds.guidance.hooks.color.expressive-palette)

package/skills/applying-slds/guidance/styling-hooks/color/semantic/accent-hooks.md

@@ -0,0 +1,204 @@
+---
+id: slds.guidance.hooks.color.accent
+title: Accent Color Styling Hooks
+description: Semantic hooks for brand identity, interactive elements, and visual emphasis
+summary: "Guidance for accent color hooks used for links, buttons, and brand emphasis. Covers accent, accent-container, border-accent, and on-accent hooks with state progression and accessibility pairing."
+
+artifact_type: reference
+domain: styling-hooks
+topic: color
+subtopic: semantic
+
+content_format: structured
+complexity: intermediate
+audience: [implementer]
+
+tasks: [choose, implement, troubleshoot]
+
+refs:
+  - slds.guidance.hooks.color.surface
+  - slds.guidance.hooks.color
+  - slds.guidance.hooks.color.feedback
+
+tags: [styling-hooks, color, semantic, accent, brand, interactive, links, buttons]
+keywords: [accent color, brand color, links, buttons, interactive elements, visual hierarchy, hover states]
+---
+
+# Accent Color Styling Hooks
+
+> **Hook Selection:** Semantic hooks like accent are the first choice (85% of use cases). See [Hook Selection Hierarchy](ref:slds.guidance.hooks.color).
+
+## Overview
+
+Accent colors express a brand's accent color throughout the user interface or to draw attention to an action. Brand colors highlight actions on the page through buttons and links.
+
+---
+
+## `--slds-g-color-accent-*`
+
+### Description
+Accent colors that are generally used for text or icons.
+
+### Available Hooks
+- `--slds-g-color-accent-1` - Lightest accent color
+- `--slds-g-color-accent-2` - Medium accent color
+- `--slds-g-color-accent-3` - Darkest accent color
+
+### State Progression Logic
+
+The variant number you use depends on the default state's contrast requirements:
+- **If default state uses `accent-1`**: Use `accent-2` for hover states
+- **If default state uses `accent-2`**: Use `accent-3` for hover states
+
+**Why this matters**: `accent-2` is often the default for links and interactive text because `accent-1` may not meet accessibility contrast requirements on non-white backgrounds. The hover state then uses the next darker variant.
+
+### Usage
+
+####  Do
+- Use accent colors for brand identity and interactive elements (links, buttons, icons)
+- Use accent colors for emphasizing key actions and content
+- Use accent colors to create visual hierarchy with brand colors
+<!-- - Consider brand-base-90 and 80 for backgrounds and hover states for menu type components using the brand-base styling hook -->
+
+####  Don't
+- Avoid using for large background areas
+- Avoid using for container backgrounds
+- Avoid for body text or long-form content
+- Avoid using without ensuring proper contrast
+- Avoid using as the only color indicator for status
+- Avoid using system colors or colors from another group like surface colors in combination with accent colors
+
+#### Context
+- Links and interactive text (commonly use accent-2 by default, accent-3 on hover)
+- Brand elements and identity
+- Icon fills and accents
+- Icon Buttons and interactive text
+- Indicates active or selected states in components
+- **Note**: Interactive icons that respond to hover are treated as Button Icon components and handle the state changes on their own.
+
+### Accessibility
+- All accent colors are AA compliant and maintain a 4.5:1 contrast using semantic colors with a 50 gradepoint difference between the background and foreground
+- Best paired with on-accent colors for foreground text and icons. Choose on-accent level based on content importance and required contrast, not strict number matching. For example, pair `--slds-g-color-accent-1` with `--slds-g-color-on-accent-1` for consistency, though other on-accent levels may be used based on emphasis needs while maintaining accessibility compliance
+
+---
+
+## `--slds-g-color-accent-container-*`
+
+### Description
+Background fills using accent colors for containers.
+
+### Available Hooks
+- `--slds-g-color-accent-container-1` - Lightest accent container background
+- `--slds-g-color-accent-container-2` - Medium accent container background
+- `--slds-g-color-accent-container-3` - Darkest accent container background
+
+### State Progression Logic
+
+Container variants follow a straightforward state progression pattern:
+- **If default state uses `accent-container-1`**: Use `accent-container-2` for hover/active states
+- **If default state uses `accent-container-2`**: Use `accent-container-3` for hover/active states
+
+**Why this pattern**: Higher numbered variants provide increased visual emphasis and contrast, making interactive states clearly distinguishable from default states.
+
+### Usage
+
+####  Do
+- Use accent container colors for containers such as brand buttons and their hover and active states
+- Use accent container colors for interactive container backgrounds that need accent color emphasis
+- Use accent container colors for interactive element backgrounds
+- Use accent container colors for hover/focus/active states of interactive containers
+
+####  Don't
+- Avoid using for non-interactive decorative elements
+- Avoid using as primary or secondary brand colors outside interactive container contexts
+- Avoid for subtle interactions where less emphasis is needed
+- Avoid using for large areas without specific interaction requirements
+- Avoid without proper interaction context
+- Avoid using system colors or colors from another group like surface colors in combination with accent container colors
+
+**Important**: Accent containers carry brand significance indicating interaction and should only be used for interactive elements, not for non-interactive decorative purposes.
+
+#### Context
+- Brand button backgrounds and their interactive states
+- Interactive element backgrounds
+- Hover/focus/active state backgrounds for interactive containers
+- Interactive content areas requiring brand emphasis
+
+### Accessibility
+- All container colors are AA compliant and maintain a 4.5:1 contrast using semantic colors with a 50 gradepoint difference between the background and foreground
+- Best paired with on-accent colors for foreground text and icons. Choose on-accent level based on content importance and required contrast, not strict number matching. For example, pair `--slds-g-color-accent-container-1` with `--slds-g-color-on-accent-1` for consistency, though other on-accent levels may be used based on emphasis needs while maintaining accessibility compliance
+
+---
+
+## `--slds-g-color-border-accent-*`
+
+### Description
+Accent border colors for brand-colored outlines when higher visual emphasis is required beyond neutral borders.
+
+### Available Hooks
+- `--slds-g-color-border-accent-1` - Lightest accent border color
+- `--slds-g-color-border-accent-2` - Medium accent border color
+- `--slds-g-color-border-accent-3` - Darkest accent border color
+
+### Usage
+
+####  Do
+- Use neutral border hooks (`--slds-g-color-border-2`) as the primary choice for standard interactive elements to ensure cross-component consistency
+- Use border-accent hooks only when explicit brand-colored outlines are required by the design
+- Use border-accent hooks for high-emphasis brand identity elements that need to stand out from standard UI
+- Pair with accent container colors for unified brand treatments
+
+####  Don't
+- Avoid using border-accent hooks as the default border choice — prefer neutral borders unless brand emphasis is explicitly needed
+- Avoid using as the default border for interactive elements unless a high-contrast brand treatment is specifically required
+- Avoid using for large background areas (borders should define, not fill)
+- Avoid for body text or long-form content
+- Avoid using without ensuring proper contrast
+- Avoid using as the only color indicator for status
+- Avoid using non-border accent colors on borders to achieve a border with an accent color
+
+#### Context
+- Brand button outlines
+- Interactive element outlines
+
+**Note**: To align with current design patterns, most interactive components—including brand-variant buttons—rely on neutral border hooks (`--slds-g-color-border-2`) or are borderless. Border-accent hooks are primarily reserved for specialized theming, custom brand components, or specific focus indicators where standard neutral borders do not provide sufficient emphasis.
+
+### Accessibility
+- All border accent colors are AA compliant and maintain a 4.5:1 contrast using semantic colors with a 50 gradepoint difference between the background
+- Works best on neutral backgrounds or paired with matching accent container colors.
+- Maintains visibiltiy and consisteny when paired with `--slds-g-sizing-border-*` sizing hooks
+
+---
+
+## `--slds-g-color-on-accent-*`
+
+### Description
+Foreground colors for content placed on accent color backgrounds, such as text and icons.
+
+### Available Hooks
+- `--slds-g-color-on-accent-1` - Lightest foreground color for accent backgrounds
+- `--slds-g-color-on-accent-2` - Medium foreground color for accent backgrounds
+- `--slds-g-color-on-accent-3` - Darkest foreground color for accent backgrounds
+
+### Usage
+
+####  Do
+- Use on-accent colors for text placed on accent color backgrounds
+- Use on-accent colors for icons displayed on accent color backgrounds
+- Use on-accent colors for any content that needs to be readable on accent backgrounds
+- Pair on-accent colors with the corresponding accent background color
+
+####  Don't
+- Avoid using on light or non-accent backgrounds
+- Avoid using without the corresponding accent background
+- Avoid using for decorative elements that don't require readability
+- Avoid mixing with non-matching accent backgrounds
+
+#### Context
+- Text on accent backgrounds
+- Icons on accent surfaces
+
+### Accessibility
+- All on-accent colors are AA compliant and maintain a 4.5:1 contrast using semantic colors with a 50 gradepoint difference between the background
+- Works best paired with a corresponding accent background color. Choose on-accent level based on content importance and required contrast, not strict number matching. For example, pair `--slds-g-color-on-accent-1` with `--slds-g-color-accent-1` or `--slds-g-color-accent-container-1` for consistency, though other pairings may be used based on emphasis needs while maintaining accessibility compliance
+