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

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

@@ -0,0 +1,819 @@
+# Feedback Color Styling Hooks
+
+## Overview
+
+**Reference:** [Lightning Design System - Color](https://www.lightningdesignsystem.com/2e1ef8501/p/655b28-color/b/25b51f)
+
+Feedback or alert colors provide visual feedback to the user regarding the status of an action or event. These colors are intentionally reserved to convey specific associations throughout the Salesforce UI. Only use feedback colors for their intended meaning so users have clear color associations throughout all of Salesforce products.
+
+| **Color** | **Meaning**                                                 |
+| --------- | ----------------------------------------------------------- |
+| Error     | An error that needs to be addressed before progressing      |
+| Warning   | A warning of potential issues the user needs to be aware of |
+| Success   | A positive or successful action or outcome                  |
+| Info      | Convey non-critical information to users                    |
+| Disabled  | Indicates that a component is unavailable                   |
+
+---
+
+## Understanding Feedback Hook Variants
+
+### The 1-2 Pattern
+
+Feedback hooks that include `-1` and `-2` variants follow this pattern:
+
+- **`-1`**: Default state (lighter color, lower emphasis)
+- **`-2`**: Hover/active state OR higher emphasis state (darker color, higher emphasis)
+
+### Why Some Feedback Types Lack Variants
+
+Not all feedback categories have `-2` variants. This is **intentional** and based on component availability in SLDS2:
+
+| Feedback Type | Has `-2` Variant?                      | Reason                                                                     |
+| ------------- | -------------------------------------- | -------------------------------------------------------------------------- |
+| Error         | ✅ Yes (container, border, on-error)   | SLDS2 includes error/destructive buttons requiring hover states            |
+| Success       | ✅ Yes (container, border, on-success) | SLDS2 includes success buttons requiring hover states                      |
+| Warning       | ❌ No (except border-1)                | SLDS2 has no warning buttons; used for form validation and static alerts   |
+| Info          | ❌ No                                  | SLDS2 has no info buttons; only static badges, icons, and alert containers |
+| Disabled      | ✅ Yes (container, on-disabled)        | Multiple disabled states for different visual weights                      |
+
+**Future-proofing**: If interactive warning or info components (such as warning buttons) are added to SLDS2 in future releases, corresponding `-2` variants may be introduced for hover states.
+
+---
+
+## Quick Reference: Hook Selection Guide
+
+Use this table to quickly find the right hook for your use case:
+
+| Scenario                               | Hook                   | Paired With                      | Example Use Case            |
+| -------------------------------------- | ---------------------- | -------------------------------- | --------------------------- |
+| **Error text on neutral background**   | `error-1`              | neutral surface                  | Form validation message     |
+| **Error alert background**             | `error-container-1`    | `on-error-1`                     | Alert banner, toast         |
+| **Delete/destructive button**          | `error-container-2`    | `on-error-2`                     | Destructive action button   |
+| **Error input border**                 | `border-error-1`       | neutral or `error-container-1`   | Invalid form field          |
+| **High-emphasis error border**         | `border-error-2`       | `error-container-2`              | Destructive button outline  |
+| **Warning text on neutral background** | `warning-1`            | neutral surface                  | Caution message             |
+| **Warning alert background**           | `warning-container-1`  | `on-warning-1`                   | Warning banner, toast       |
+| **Warning input border**               | `border-warning-1`     | neutral or `warning-container-1` | Warning form field          |
+| **Success text on neutral background** | `success-1`            | neutral surface                  | Confirmation message        |
+| **Success alert background**           | `success-container-1`  | `on-success-1`                   | Success banner, toast       |
+| **Confirm/save button**                | `success-container-2`  | `on-success-2`                   | Confirmation action button  |
+| **Success input border**               | `border-success-1`     | neutral or `success-container-1` | Valid form field            |
+| **High-emphasis success border**       | `border-success-2`     | `success-container-2`            | Confirmation button outline |
+| **Info text on neutral background**    | `info-1`               | neutral surface                  | Helpful tip text            |
+| **Info alert background**              | `info-container-1`     | `on-info-1`                      | Info banner, help panel     |
+| **Disabled button (subtle)**           | `disabled-container-1` | `on-disabled-1`                  | Inactive neutral button     |
+| **Disabled button (strong)**           | `disabled-container-2` | `on-disabled-2`                  | Inactive branded button     |
+| **Disabled input border**              | `border-disabled-1`    | `disabled-container-1`           | Disabled form field         |
+
+---
+
+## General Guidelines (Applies to All Feedback Hooks)
+
+### Color Mixing Restrictions
+
+#### ❌ Critical Don'ts
+
+- **Do not mix feedback types**: Never combine colors from different feedback categories (e.g., `warning-container-1` with `on-error-1`)
+- **Do not mix with system colors**: Avoid using system-level colors or colors from other semantic groups (like surface colors) with feedback colors
+- **Do not use color alone**: Always pair color with text, icons, or ARIA attributes—never rely solely on color to convey meaning
+- **Do not use wrong hook types**: Use border-specific hooks for borders, container hooks for backgrounds, and on-\* hooks for foreground content
+
+### Interactive Icon Behavior
+
+If a feedback icon is **interactive** (clickable, shows tooltip on hover):
+
+- Treat it as a **button icon** component
+- Use button component styling hooks for hover/active states
+- Do NOT use standalone feedback hooks for interactive states
+
+**Applies to:** Error, Warning, Success, and Info icons
+
+### Best Practices
+
+- Always ensure proper contrast ratios are maintained
+- Use appropriate ARIA attributes to communicate state to assistive technologies
+- Match variant numbers for consistency (e.g., `container-1` with `on-[type]-1`)
+- Use `-1` variants for static/non-interactive elements
+- Use `-2` variants for interactive buttons (error/success only) or higher emphasis states
+
+---
+
+## Accessibility Principles (Applies to All Feedback Hooks)
+
+### Contrast Standards
+
+All feedback color hooks are **AA compliant** and maintain a **4.5:1 contrast ratio** using semantic colors with a 50 gradepoint difference between background and foreground colors.
+
+### Pairing Recommendations
+
+**Default Rule:** Match variant numbers for consistency
+
+- Pair `container-1` with `on-[type]-1`
+- Pair `container-2` with `on-[type]-2`
+- Pair `border-[type]-1` with `container-1` or neutral backgrounds
+- Pair `border-[type]-2` with `container-2` or for high-emphasis states
+
+**Flexibility:** While matching numbers is recommended for consistency, other pairings are acceptable if:
+
+- Content importance requires different emphasis levels
+- Accessibility compliance (≥ 4.5:1 contrast) is maintained
+- The visual hierarchy serves the user experience
+
+**For AI agents:** When in doubt, match the variant numbers.
+
+### Semantic HTML Requirements
+
+**For disabled states**, always include proper attributes:
+
+- Use `aria-disabled="true"` or the `disabled` attribute
+- Include descriptive text or tooltips explaining why an element is disabled
+- Ensure keyboard navigation properly skips disabled elements
+
+**For error/warning/success states**, provide clear communication:
+
+- Use `role="alert"` for dynamic error messages
+- Include `aria-live` regions for screen reader announcements
+- Provide error descriptions that are programmatically associated with form fields
+
+### Border Sizing Consistency
+
+When using border hooks, maintain consistency with `--slds-g-sizing-border-*` sizing hooks for proper visual weight across the system.
+
+---
+
+## Validation Checklist for AI Agents
+
+Before implementing feedback color hooks, verify:
+
+- [ ] **Correct hook type**: Used border-specific hooks for borders, container hooks for backgrounds, on-\* hooks for foreground
+- [ ] **Appropriate pairing**: Paired container colors with matching on-[type] colors (numbers match or justifiable variance)
+- [ ] **No type mixing**: Did not mix feedback types (e.g., warning + error colors together)
+- [ ] **No system color mixing**: Did not combine with system colors or surface colors from other semantic groups
+- [ ] **ARIA attributes**: Included proper ARIA attributes for disabled states (`aria-disabled`, `disabled`) and alerts (`role="alert"`)
+- [ ] **Not color-only**: Color is not the sole indicator—paired with text, icons, or semantic HTML
+- [ ] **Interactive vs static**: Interactive icons use button component styling; static icons use feedback hooks
+- [ ] **Variant logic**: Used `-1` for static/light emphasis, `-2` for interactive buttons or higher emphasis (where available)
+- [ ] **Contrast verified**: Maintained minimum 4.5:1 contrast ratio for all text and meaningful elements
+- [ ] **Semantic meaning**: Used feedback colors only for their intended purpose (error for errors, warning for warnings, etc.)
+
+---
+
+## `--slds-g-color-error-1`
+
+### Description
+
+Primary error color that indicates errors requiring user attention before progressing.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for indicating errors in forms and validation messages
+- Effective for critical error states requiring immediate attention
+- Can be used for error icons and text on neutral backgrounds
+- Use to signal blocking issues that prevent progression
+- Works well for destructive action text (delete, remove)
+
+#### ❌ Don't
+
+- Avoid using for large background areas (use error-container instead)
+- Avoid using for non-error contexts or decorative purposes
+
+#### Context
+
+- Form validation error text
+- Error icons on neutral backgrounds
+- Destructive action button text or icons
+- Error message text on light backgrounds
+- Critical system notification text
+
+---
+
+## `--slds-g-color-error-container-*`
+
+### Description
+
+Error background colors for containers that communicate error states with varying levels of emphasis.
+
+### Available Hooks
+
+- `--slds-g-color-error-container-1` - Light error background for subtle emphasis
+- `--slds-g-color-error-container-2` - Medium error background for higher emphasis
+
+### State Progression Logic
+
+Error container variants follow a state progression pattern for interactive destructive elements:
+
+- **`error-container-1`**: Light error background for non-interactive error messages, alerts, and banners
+- **`error-container-2`**: Medium error background for destructive button default states, or hover states when starting from container-1
+
+**Typical pattern for destructive buttons**: Use `error-container-2` as the default background, with darker borders or overlays for hover/active states (handled by component-level hooks).
+
+**Example**: A "Delete" button uses `error-container-2` as its background with `on-error-2` for text color.
+
+### Usage
+
+#### ✅ Do
+
+- Use for error alert backgrounds and error message containers
+- Works well for error banners and toast notifications
+- Effective for destructive button backgrounds (using container-2)
+- Suitable for hover/focus/active states of error-related containers
+
+#### ❌ Don't
+
+- Avoid using for non-error contexts
+
+#### Context
+
+- Error alert backgrounds
+- Error message containers
+- Destructive button backgrounds
+- Error banner backgrounds
+- Error toast notifications
+
+---
+
+## `--slds-g-color-border-error-*`
+
+### Description
+
+Error border colors for visual emphasis of error states with varying levels of emphasis.
+
+### Available Hooks
+
+- `--slds-g-color-border-error-1` - Primary error border color
+- `--slds-g-color-border-error-2` - Darker error border for increased emphasis
+
+### State Progression Logic
+
+Border error variants follow standard emphasis patterns:
+
+- **`border-error-1`**: Default error border for standard error states
+- **`border-error-2`**: Higher emphasis error border for increased visual weight or interactive hover states
+
+**Typical usage**: Use `-1` for default error borders, and `-2` when higher visual emphasis is needed or for interactive state changes.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for error form field borders
+- Effective for error container outlines
+- Can create visual emphasis for error states
+- Suitable for focus indicators on error elements
+- Can use this independently or pair it with an error container color
+- Use border-error-2 for high-emphasis error borders and destructive actions
+
+#### ❌ Don't
+
+- Avoid using for large background areas (borders should define, not fill)
+- Avoid using non-border error colors on borders to achieve a border with an error color
+
+#### Context
+
+- Error form field borders
+- Error container outlines
+- Error element indicators
+- Validation error borders
+- Destructive button outlines (border-error-2)
+
+---
+
+## `--slds-g-color-on-error-*`
+
+### Description
+
+Foreground colors for content placed on error backgrounds, with varying emphasis levels.
+
+### Available Hooks
+
+- `--slds-g-color-on-error-1` - Foreground for error-container-1 backgrounds
+- `--slds-g-color-on-error-2` - Darker foreground for error-container-2 backgrounds
+
+### Usage
+
+#### ✅ Do
+
+- Works well for text placed on error container backgrounds
+- Effective for icons displayed on error backgrounds
+- Can be used as error text color on neutral surfaces (on-error-1)
+- Best paired with the corresponding error container color
+- Use on-error-2 for destructive button text on error-container-2
+
+#### ❌ Don't
+
+- Avoid mixing on-error-1 with error-container-2 or vice versa (match variant numbers)
+
+#### Context
+
+- Text on error container backgrounds
+- Icons on error surfaces
+- Error message text
+- Destructive button text
+
+---
+
+## `--slds-g-color-warning-1`
+
+### Description
+
+Primary warning color that indicates potential issues requiring user awareness.
+
+> **Why no `-2` variant?** Warning hooks lack a `-2` variant because SLDS2 currently has no interactive warning button components. The `-1` variant serves non-interactive elements like static warning icons, badges, and alert containers. If warning buttons become interactive in future releases, a `-2` variant may be added for hover states.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for indicating warnings and cautions
+- Effective for alerting users to potential issues
+- Can be used for warning icons and text on neutral backgrounds
+- Use to signal non-blocking issues requiring attention
+- Suitable for informing users of consequences before actions
+
+#### ❌ Don't
+
+- Avoid using for large background areas (use warning-container instead)
+- Avoid using for non-warning contexts or decorative purposes
+
+#### Context
+
+- Warning message text
+- Caution indicators
+- Warning icons on neutral backgrounds
+- Pre-action warning text
+- Non-critical system notification text
+
+---
+
+## `--slds-g-color-warning-container-1`
+
+### Description
+
+Light warning background color for containers that communicate warning states.
+
+### Usage
+
+#### ✅ Do
+
+- Use for warning alert backgrounds
+- Works well for warning banners and toast notifications
+- Effective for caution message containers
+- Pair with `--slds-g-color-on-warning-1` for foreground content
+
+#### ❌ Don't
+
+- Avoid using for non-warning contexts
+
+#### Context
+
+- Warning alert backgrounds
+- Warning message containers
+- Caution banner backgrounds
+- Warning toast notifications
+
+---
+
+## `--slds-g-color-border-warning-1`
+
+### Description
+
+Warning border color for visual emphasis of warning states.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for warning form field borders
+- Effective for warning container outlines
+- Can create visual emphasis for warning states
+- Suitable for focus indicators on warning elements
+- Can use this independently or pair it with a warning container color
+
+#### ❌ Don't
+
+- Avoid using for large background areas (borders should define, not fill)
+- Avoid using non-border warning colors on borders to achieve a border with a warning color
+
+#### Context
+
+- Warning form field borders
+- Warning container outlines
+- Warning element indicators
+- Caution borders
+- **Note**: This hook was added to support form validation patterns. Unlike error/success, there is no `border-warning-2` since warning states don't typically have interactive hover requirements in current SLDS2 components.
+
+---
+
+## `--slds-g-color-on-warning-1`
+
+### Description
+
+Foreground color for content placed on warning backgrounds or for warning text on light surfaces.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for text placed on `--slds-g-color-warning-container-1` backgrounds
+- Effective for icons displayed on warning backgrounds
+- Can be used as warning text color on neutral surfaces
+- Best paired with the corresponding warning background color
+
+#### ❌ Don't
+
+- Avoid mixing with non-matching warning backgrounds
+
+#### Context
+
+- Text on warning-container-1 backgrounds
+- Icons on warning surfaces
+- Warning message text
+
+---
+
+## `--slds-g-color-success-1`
+
+### Description
+
+Primary success color that indicates positive outcomes and successful actions.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for indicating successful operations and confirmations
+- Effective for positive feedback and completion states
+- Can be used for success icons and text on neutral backgrounds
+- Use to signal successful outcomes and achievements
+- Suitable for confirming actions were completed
+
+#### ❌ Don't
+
+- Avoid using for large background areas (use success-container instead)
+- Avoid using for non-success contexts or decorative purposes
+
+#### Context
+
+- Success message text
+- Confirmation indicators
+- Success icons on neutral backgrounds
+- Completion state text
+- Positive system notification text
+
+---
+
+## `--slds-g-color-success-container-*`
+
+### Description
+
+Success background colors for containers that communicate success states with varying levels of emphasis.
+
+### Available Hooks
+
+- `--slds-g-color-success-container-1` - Light success background for subtle emphasis
+- `--slds-g-color-success-container-2` - Medium success background for higher emphasis
+
+### State Progression Logic
+
+Success container variants follow a state progression pattern for interactive confirmation elements:
+
+- **`success-container-1`**: Light success background for non-interactive success messages, alerts, and banners
+- **`success-container-2`**: Medium success background for confirmation button default states, or hover states when starting from container-1
+
+**Typical pattern for confirmation buttons**: Use `success-container-2` as the default background, with darker borders or overlays for hover/active states (handled by component-level hooks).
+
+**Example**: A "Confirm" or "Save" button uses `success-container-2` as its background with `on-success-2` for text color.
+
+### Usage
+
+#### ✅ Do
+
+- Use for success alert backgrounds and success message containers
+- Works well for success banners and toast notifications
+- Effective for confirmation button backgrounds (using container-2)
+- Suitable for hover/focus/active states of success-related containers
+
+#### ❌ Don't
+
+- Avoid using for non-success contexts
+
+#### Context
+
+- Success alert backgrounds
+- Success message containers
+- Confirmation button backgrounds
+- Success banner backgrounds
+- Success toast notifications
+
+---
+
+## `--slds-g-color-border-success-*`
+
+### Description
+
+Success border colors for visual emphasis of success states with varying levels of emphasis.
+
+### Available Hooks
+
+- `--slds-g-color-border-success-1` - Primary success border color
+- `--slds-g-color-border-success-2` - Darker success border for increased emphasis
+
+### State Progression Logic
+
+Border success variants follow standard emphasis patterns:
+
+- **`border-success-1`**: Default success border for standard success states
+- **`border-success-2`**: Higher emphasis success border for increased visual weight or interactive hover states
+
+**Typical usage**: Use `-1` for default success borders, and `-2` when higher visual emphasis is needed or for interactive state changes.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for success form field borders
+- Effective for success container outlines
+- Can create visual emphasis for success states
+- Suitable for focus indicators on success elements
+- Can use this independently or pair it with a success container color
+- Use border-success-2 for high-emphasis success borders
+
+#### ❌ Don't
+
+- Avoid using for large background areas (borders should define, not fill)
+- Avoid using non-border success colors on borders to achieve a border with a success color
+
+#### Context
+
+- Success form field borders
+- Success container outlines
+- Success element indicators
+- Confirmation borders
+- Emphasized confirmation outlines (border-success-2)
+
+---
+
+## `--slds-g-color-on-success-*`
+
+### Description
+
+Foreground colors for content placed on success backgrounds, with varying emphasis levels.
+
+### Available Hooks
+
+- `--slds-g-color-on-success-1` - Foreground for success-container-1 backgrounds
+- `--slds-g-color-on-success-2` - Darker foreground for success-container-2 backgrounds
+
+### Usage
+
+#### ✅ Do
+
+- Works well for text placed on success container backgrounds
+- Effective for icons displayed on success backgrounds
+- Can be used as success text color on neutral surfaces (on-success-1)
+- Best paired with the corresponding success container color
+- Use on-success-2 for confirmation button text on success-container-2
+
+#### ❌ Don't
+
+- Avoid mixing on-success-1 with success-container-2 or vice versa (match variant numbers)
+
+#### Context
+
+- Text on success container backgrounds
+- Icons on success surfaces
+- Success message text
+- Confirmation button text
+
+---
+
+## `--slds-g-color-info-1`
+
+### Description
+
+Primary info color that conveys non-critical information to users.
+
+> **Why no `-2` variant?** Info hooks lack a `-2` variant because SLDS2 currently has no interactive info button components. The `-1` variant serves non-interactive elements like static info badges, icons, and alert containers. If info buttons become interactive in future releases, a `-2` variant may be added for hover states.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for indicating informational messages
+- Effective for helpful tips and guidance
+- Can be used for info icons and text on neutral backgrounds
+- Use to signal non-critical information
+- Suitable for educational or contextual content
+
+#### ❌ Don't
+
+- Avoid using for large background areas (use info-container instead)
+- Avoid using for non-informational contexts or decorative purposes
+
+#### Context
+
+- Informational message text
+- Help text and tooltips
+- Info icons on neutral backgrounds
+- Contextual guidance text
+- Educational notification text
+
+---
+
+## `--slds-g-color-info-container-1`
+
+### Description
+
+Light info background color for containers that communicate informational states.
+
+### Usage
+
+#### ✅ Do
+
+- Use for info alert backgrounds
+- Works well for info banners and toast notifications
+- Effective for help panel backgrounds
+- Pair with `--slds-g-color-on-info-1` for foreground content
+
+#### ❌ Don't
+
+- Avoid using for non-informational contexts
+
+#### Context
+
+- Info alert backgrounds
+- Info message containers
+- Help panel backgrounds
+- Info banner backgrounds
+- Info toast notifications
+
+---
+
+## `--slds-g-color-on-info-1`
+
+### Description
+
+Foreground color for content placed on info backgrounds or for info text on light surfaces.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for text placed on `--slds-g-color-info-container-1` backgrounds
+- Effective for icons displayed on info backgrounds
+- Can be used as info text color on neutral surfaces
+- Best paired with the corresponding info background color
+
+#### ❌ Don't
+
+- Avoid mixing with non-matching info backgrounds
+
+#### Context
+
+- Text on info-container-1 backgrounds
+- Icons on info surfaces
+- Info message text
+- Help text on info backgrounds
+
+---
+
+## `--slds-g-color-disabled-1`
+
+### Description
+
+Primary disabled color that indicates components are unavailable for interaction.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for indicating disabled or inactive elements
+- Effective for non-interactive states
+- Can be used for disabled borders and backgrounds
+- Use to signal unavailable functionality
+- Suitable for inactive form fields and buttons
+
+#### ❌ Don't
+
+- Avoid using for active or interactive elements
+- Avoid using for decorative purposes
+
+#### Context
+
+- Disabled form field borders
+- Inactive button backgrounds
+- Unavailable menu items
+- Non-interactive element styling
+- Grayed-out content
+
+---
+
+## `--slds-g-color-disabled-container-*`
+
+### Description
+
+Disabled container background colors for unavailable states with varying levels of emphasis.
+
+### Available Hooks
+
+- `--slds-g-color-disabled-container-1` - Light disabled background
+- `--slds-g-color-disabled-container-2` - Medium emphasis disabled background
+
+### Understanding Disabled Container Variants
+
+Disabled container variants provide different visual weights for unavailable states:
+
+- **`disabled-container-1`**: Light disabled background for subtle de-emphasis
+- **`disabled-container-2`**: Medium disabled background for stronger visual de-emphasis
+
+**These are NOT state progressions**: Disabled elements have no interactive states. The variant numbers represent different levels of visual de-emphasis based on component needs, not hover/active states.
+
+**Typical usage**: Choose based on desired visual weight—`disabled-container-1` for subtle de-emphasis (common in form fields and neutral buttons), `disabled-container-2` for stronger de-emphasis (common in filled branded buttons).
+
+### Usage
+
+#### ✅ Do
+
+- Use for disabled button backgrounds
+- Works well for inactive form field backgrounds
+- Effective for unavailable container states
+- Suitable for grayed-out panel backgrounds
+
+#### ❌ Don't
+
+- Avoid using for active or interactive containers
+- Avoid for elements that should remain visually prominent
+
+#### Context
+
+- Disabled button backgrounds
+- Inactive form field backgrounds
+- Unavailable container backgrounds
+- Grayed-out panels
+- Non-interactive element backgrounds
+
+---
+
+## `--slds-g-color-border-disabled-1`
+
+### Description
+
+Disabled border color for visual emphasis of unavailable states.
+
+### Usage
+
+#### ✅ Do
+
+- Works well for disabled form field borders
+- Effective for inactive container outlines
+- Can create visual emphasis for disabled states
+- Can use this independently or pair it with a disabled container color
+
+#### ❌ Don't
+
+- Avoid using for active or interactive elements
+- Avoid using non-border disabled colors on borders
+
+#### Context
+
+- Disabled form field borders
+- Inactive container outlines
+- Unavailable element borders
+- Grayed-out element borders
+
+---
+
+## `--slds-g-color-on-disabled-*`
+
+### Description
+
+Foreground colors for content placed on disabled backgrounds, with varying emphasis levels.
+
+### Available Hooks
+
+- `--slds-g-color-on-disabled-1` - Foreground for disabled-container-1 backgrounds
+- `--slds-g-color-on-disabled-2` - Darker foreground for disabled content requiring more emphasis
+
+### Usage
+
+#### ✅ Do
+
+- Works well for text placed on disabled container backgrounds
+- Effective for icons displayed on disabled backgrounds
+- Best paired with the corresponding disabled container color
+- Use on-disabled-2 for disabled content requiring better readability
+
+#### ❌ Don't
+
+- Avoid using on active or interactive backgrounds
+- Avoid using for elements that should appear fully interactive
+
+#### Context
+
+- Text on disabled container backgrounds
+- Icons on disabled surfaces
+- Disabled button text
+- Inactive form field text