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

package/knowledge/slds/styling-hooks/global-semantic/surface-hooks.md

@@ -0,0 +1,215 @@
+# Surface Color Styling Hooks
+
+## Overview
+
+**Reference:** [Lightning Design System - Color](https://www.lightningdesignsystem.com/2e1ef8501/p/655b28-color/b/25b51f)
+
+A surface is a canvas that UI elements sit on. Surface colors express the visual stacking context of an app. Surface colors work together to enable sweeping changes, like dark mode. Surface colors are reserved for the bottom layer of a surface and establish the foundation for visual depth in the application.
+
+---
+
+## `--slds-g-color-surface-*`
+
+### Description
+
+Surface colors used for backgrounds and large areas of the application that express a new visual stacking context to create visual depth.
+
+### Available Hooks
+
+- `--slds-g-color-surface-1` - Primary page background (lightest, typically white)
+- `--slds-g-color-surface-2` - Secondary page background (light gray, for visual distinction)
+- `--slds-g-color-surface-3` - Tertiary page background (medium gray, for additional hierarchy)
+- `--slds-g-color-surface-inverse-1` - Primary inverse surface background color
+- `--slds-g-color-surface-inverse-2` - Secondary inverse surface background color
+
+> **Note on Inverse Hooks:** Inverse hooks provide dark background colors designed for dark mode or inverted color schemes. They enable light content on dark backgrounds, as opposed to standard hooks which provide dark content on light backgrounds. Use inverse hooks for dark mode implementations, high-contrast sections, or visual emphasis through color inversion.
+
+### Understanding Surface Numbering: NOT State-Based
+
+**Critical Distinction**: Unlike accent or feedback hooks, surface variant numbers (1-2-3) do **NOT** represent interaction states (default/hover/active). They represent:
+
+1. **Color progression from light to dark** (1 = lightest, 3 = darkest)
+2. **Designer's aesthetic choice** for visual hierarchy or separation
+3. **Contextual background needs** (e.g., white cards need gray backgrounds to stand out)
+
+**When to choose which:**
+
+- **`surface-1` (white)**: Clean, high-contrast base; use when cards/containers need strong definition
+- **`surface-2` (light gray)**: Softer separation; use when layering elements without harsh white backgrounds
+- **`surface-3` (medium gray)**: Additional depth; rare in practice, used for specific hierarchical needs
+
+**NOT a rule**: There is no algorithmic decision tree. Designers choose based on composition, not function.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for application backgrounds to establish the base canvas
+- Effective for panels that create new visual contexts
+- Suitable for modals that sit above other content
+- Can be applied to docked surfaces that establish surfaces
+- Works well for popovers and other elevated UI elements
+- Anything that comes into the application's view with a higher stacking context establishes a new surface
+
+#### ❌ Don't
+
+- Avoid applying any decoration, brand bands, or textures to application backgrounds
+- Avoid using for container elements that sit on top of surfaces (use surface-container instead)
+- Avoid mixing surface colors with container colors in the same layer
+- Don't use surface colors for text or icon fills
+- **Don't assume numbering indicates states**: Surface variants are NOT for hover/active states—those typically use surface-container variants, accent colors, or component-level styling hooks depending on the theme
+
+#### Context
+
+- Application background (base canvas)
+- Panels that establish new surfaces
+- Modals and dialog backgrounds
+- Docked containers
+- Popovers and elevated UI elements
+- Any element with a higher stacking context than previous surfaces
+
+### Accessibility
+
+- Surface colors are designed to work with on-surface colors for proper contrast
+- Ensure WCAG 2.1 color contrast requirements by pairing with appropriate on-surface values
+- Use `--slds-g-color-on-surface-*` for text and icons on surface backgrounds. Choose on-surface level based on content importance and required contrast, not strict number matching. For example, pair `--slds-g-color-surface-1` with `--slds-g-color-on-surface-1` for consistency, though other on-surface levels may be used based on emphasis needs while maintaining accessibility compliance
+
+---
+
+## `--slds-g-color-surface-container-*`
+
+### Description
+
+Surface container colors reserved for elements that sit on top of a surface and contain other UI elements or artifacts, such as text or icons.
+
+### Available Hooks
+
+- `--slds-g-color-surface-container-1` - Lightest container background (typically white)
+- `--slds-g-color-surface-container-2` - Light gray container background
+- `--slds-g-color-surface-container-3` - Medium gray container background for additional hierarchy
+- `--slds-g-color-surface-container-inverse-1` - Primary inverse surface container background
+- `--slds-g-color-surface-container-inverse-2` - Secondary inverse surface container background
+
+> **Note on Inverse Hooks:** Inverse hooks provide dark background colors for containers in dark mode or inverted color schemes. They work with on-surface-inverse hooks to maintain proper contrast for light content on dark container backgrounds.
+
+### Overlap with Surface Hooks
+
+Surface and surface-container hooks use the **same color values** (e.g., `surface-1` and `surface-container-1` are both white). The distinction is **semantic**, not visual:
+
+- **`surface-*`**: Reserved for page-level backgrounds that establish stacking context
+- **`surface-container-*`**: For contained elements (cards, buttons, panels) that sit **on top of** surfaces
+
+**When in doubt**: If the element contains text/icons/UI artifacts, it's a container. If it's the foundational layer (page, modal base, panel background), it's a surface.
+
+### State Progression Logic
+
+**Design Intent-Dependent Patterns**: Unlike semantic accent or feedback containers with universal state progressions, surface-container state behavior varies based on design intent and interaction context:
+
+- **For neutral hover states**: Use `surface-container-2` for hover states when default is `surface-container-1`
+- **For brand-emphasized hover states**: Use brand colors (e.g., `brand-base-90` from the color palette) instead of surface-container variants
+- **Context-Dependent**: Choice also depends on parent surface color and desired contrast level
+
+**Why the variation**: Surface containers serve as neutral, foundational backgrounds for UI elements. Interactive hover states can either maintain neutral emphasis (using surface-container progression) or add brand emphasis (using brand colors from the palette), depending on the design's intent for that specific component.
+
+**Best Practice**: Refer to component-level styling hooks for specific interactive patterns. Button, card, and list item components each have their own hover state definitions that may use surface-container variants, brand colors, accent colors, or component-specific styling hooks based on design requirements.
+
+**Example**: A neutral card on `surface-1` might use `surface-container-1` as default with `surface-container-2` on hover to maintain neutral emphasis. Alternatively, the same card could use `brand-base-90` on hover if the design calls for brand color emphasis on interaction.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for cards or containers that sit on surfaces
+- Can be applied to button icons that contain content
+- Effective for button backgrounds
+- Suitable for tabset backgrounds
+- One of the clearest signals is if the element contains text or icons
+
+#### ❌ Don't
+
+- Avoid using for the base application background
+- Avoid using for elements that don't contain other UI elements
+- Avoid mixing with surface colors on the same visual layer
+- Avoid using for decorative elements that don't establish containers
+
+#### Context
+
+- Cards or container components
+- Button backgrounds
+- Button icon containers
+- Tabset backgrounds
+- Any element that contains text, icons, or other UI artifacts
+- Interactive containers that sit above surfaces
+
+### Accessibility
+
+- All surface container colors are designed to work with `--slds-g-color-on-surface-*` values for proper contrast
+- Ensures proper WCAG 2.1 color contrast requirements are met
+- Choose on-surface level based on content importance and required contrast, not strict number matching. For example, pair `--slds-g-color-surface-container-3` with `--slds-g-color-on-surface-3` for consistency, though other on-surface levels may be used based on emphasis needs while maintaining accessibility compliance
+- Valid to use accent or feedback colors for text/icons on top of surface containers as alternatives (e.g., `--slds-g-color-accent-1`)
+
+---
+
+## `--slds-g-color-on-surface-*`
+
+### Description
+
+Foreground colors for text or icons that appear on top of a surface or surface container, ensuring proper color contrast requirements.
+
+### Available Hooks
+
+- `--slds-g-color-on-surface-1` - De-emphasized text (lightest gray, for captions and secondary content)
+- `--slds-g-color-on-surface-2` - Body text (medium gray, for standard content and labels)
+- `--slds-g-color-on-surface-3` - High-emphasis text (darkest/black, for headings and primary content)
+- `--slds-g-color-on-surface-inverse-1` - Primary inverse foreground color for inverse surfaces
+- `--slds-g-color-on-surface-inverse-2` - Secondary inverse foreground color for inverse surfaces
+
+> **Note on Inverse Hooks:** Inverse hooks provide light foreground colors (text/icons) designed for use on dark surface or surface-container inverse backgrounds. They ensure proper contrast when displaying content in dark mode or inverted color schemes.
+
+### Pairing Logic: Contrast Over Number-Matching
+
+While the naming suggests pairing `on-surface-1` with `surface-1`, this is **NOT a strict rule**. Choose on-surface variants based on:
+
+1. **Content importance**: Headlines use `on-surface-3` (highest contrast), body text uses `on-surface-2`, labels/captions use `on-surface-1`
+2. **Accessibility requirements**: Always maintain 4.5:1 contrast ratio
+3. **Visual hierarchy needs**: NOT the surface variant number
+
+**Example**: A card using `surface-container-1` (white) might contain:
+
+- Heading: `on-surface-3` (black)
+- Body text: `on-surface-2` (medium gray)
+- Caption: `on-surface-1` (light gray)
+
+All three `on-surface` variants can appear on the same `surface-container-1` background.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for text that appears on surface or surface container backgrounds
+- Effective for icons displayed on surfaces
+- Suitable for any content that needs to meet WCAG 2.1 color contrast requirements
+
+#### ❌ Don't
+
+- Avoid using on accent color backgrounds (use on-accent colors instead)
+- Avoid using on feedback color backgrounds (use on-feedback colors instead)
+- Avoid using for large background areas
+- Avoid using as standalone colors without appropriate surface backgrounds
+
+#### Context
+
+- Text on surface backgrounds
+- Icons on surface or container backgrounds
+- Body copy and content text
+- UI labels and descriptive text
+- Any foreground content requiring readability
+
+### Accessibility
+
+- All on-surface colors are AA compliant and maintain a 4.5:1 contrast ratio with their corresponding surface backgrounds
+- Designed specifically to meet Web Content Accessibility Guidelines (WCAG) 2.1
+- Best paired with matching surface or surface-container colors. Choose on-surface level based on content importance and required contrast, not strict number matching. For example, pair `--slds-g-color-on-surface-1` with `--slds-g-color-surface-1` or `--slds-g-color-surface-container-1` for consistency, though other pairings may be used based on emphasis needs while maintaining accessibility compliance
+- Text links can use `--slds-g-color-accent-2` on surface backgrounds
+- Disabled text uses `--slds-g-color-on-disabled-2`
+- Feedback text uses appropriate `--slds-g-color-on-error-*`, `--slds-g-color-on-warning-*`, etc.