Uplifting Components To Slds2
Replace hardcoded colors in LWC and Aura components with correct SLDS 2 semantic color hooks using markup-aware decisions.
Overview
Uplifting Components to SLDS2 is an agent skill for the Build phase that guides replacement of hardcoded colors with the correct SLDS 2 semantic hooks after markup and JS context review.
Install
npx skills add https://github.com/forcedotcom/afv-library --skill uplifting-components-to-slds2What is this skill?
- Hook selection priority: semantic surface, accent, and feedback hooks first (~85–90% of decisions)
- Requires inspecting markup then JS for dynamic classes before choosing any hook
- Documents surface, accent, feedback, palette, and system families with pairing rules
- Guides numbered variants and background–foreground accessibility pairing
- Applied examples tie color context investigation to real component uplift scenarios
- Semantic hooks should cover ~85–90% of color decisions
- Hook families: surface, accent, feedback, palette, system
Adoption & trust: 1.3k installs on skills.sh; 513 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are uplifting Salesforce components to SLDS 2 but hardcoded colors and ambiguous linter suggestions make it unclear which semantic hook fits each element.
Who is it for?
Indie Salesforce front-end developers doing SLDS 2 migrations on LWC or Aura with agent-assisted refactors.
Skip if: Greenfield UI layout from scratch, non-Salesforce design systems, or projects not targeting SLDS 2 token semantics.
When should I use this skill?
User is replacing hardcoded colors, uplifting to SLDS 2, or needs help choosing among linter-suggested color hooks on Salesforce components.
What do I get? / Deliverables
Components use prioritized SLDS 2 color hooks with accessible background–foreground pairs aligned to real markup and dynamic class behavior.
- Per-element SLDS 2 hook recommendations with semantic priority
- Refactored color token mappings respecting background–foreground pairing rules
Recommended Skills
Journey fit
SLDS 2 uplift is front-end construction work while you are actively building or refactoring Salesforce UI components. Frontend is the shelf because decisions depend on HTML, Aura markup, and JS class bindings before picking surface, accent, or feedback hooks.
How it compares
A component-level color hook checker guide, not a general Tailwind or CSS theme generator.
Common Questions / FAQ
Who is uplifting-components-to-slds2 for?
It is for builders maintaining Salesforce Lightning UI who need consistent SLDS 2 color token choices during component uplift.
When should I use uplifting-components-to-slds2?
Use it during Build frontend work when replacing hardcoded colors, responding to SLDS linter warnings, or validating dark-mode-ready semantic hooks on specific components.
Is uplifting-components-to-slds2 safe to install?
Review the Security Audits panel on this Prism page; the skill is documentation-driven and does not require elevated permissions beyond your normal repo access.
SKILL.md
READMESKILL.md - 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