Skip to content

forcedotcom/sf-skills / skills/design-systems-slds2-migrate

design-systems-slds2-migrate

Verified

Migrate Lightning Web Components from SLDS 1 to SLDS 2 by running the SLDS linter and fixing violations. Use this skill whenever users mention SLDS 2, SLDS uplift, linter violations, LWC token migration, class overrides, hardcoded CSS values that need SLDS hook replacement, or styling hook selection. Covers all styling hook categories — color, spacing, sizing, typography, borders, radius, and shadows. Also use when users mention no-hardcoded-values, no-slds-class-overrides, lwc-to-slds-hooks, no-deprecated-tokens-slds1, or ask about SLDS component migration — even if they don't explicitly say "uplift" or "migration".

references/rule-no-deprecated-tokens-slds1.md

View on GitHub
# Rule: No Deprecated Tokens SLDS1

**Rule ID:** `slds/no-deprecated-tokens-slds1`
**Severity:** Error
**Scope:** Replaces legacy Aura `t(tokenName)` and `token(tokenName)` syntax with SLDS 2 styling hooks.

---

## What the Linter Does

The linter detects `t()` and `token()` function calls in CSS, `.cmp`, and `.html` files. These are Aura-era token accessors that are deprecated in SLDS 2.

Two message types:

**When a replacement exists:**
```text
Consider removing t(colorTextDefault) or replacing it with --slds-g-color-on-surface-3.
Set the fallback to t(colorTextDefault).
```

**When no replacement exists:**
```text
Update outdated design tokens to SLDS 2 styling hooks with similar values.
```

---

## Replacement Pattern

Always wrap in `var()` with the original LWC token as fallback:

```css
/* Before — Aura t() syntax */
color: t(colorTextDefault);
background-color: t(colorBackgroundAlt);

/* After — SLDS 2 hook with LWC fallback */
color: var(--slds-g-color-on-surface-3, var(--lwc-colorTextDefault));
background-color: var(--slds-g-color-surface-container-1, var(--lwc-colorBackgroundAlt));
```

The nested `var()` fallback ensures compatibility during migration — if the SLDS 2 hook isn't available, the LWC token still resolves.

---

## Common Token Mappings

### Text Colors

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(colorTextPlaceholder)` | `--slds-g-color-on-surface-2` | `--lwc-colorTextPlaceholder` |
| `t(colorTextWeak)` | `--slds-g-color-on-surface-1` | `--lwc-colorTextWeak` |
| `t(colorTextDefault)` | `--slds-g-color-on-surface-3` | `--lwc-colorTextDefault` |
| `t(colorTextIconInverse)` | `--slds-g-color-on-surface-inverse-1` | `--lwc-colorTextIconInverse` |

### Background Colors

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(colorBackground)` | `--slds-g-color-surface-container-2` | `--lwc-colorBackground` |
| `t(colorBackgroundAlt)` | `--slds-g-color-surface-container-1` | `--lwc-colorBackgroundAlt` |
| `t(colorBackgroundAlt2)` | `--slds-g-color-surface-container-2` | `--lwc-colorBackgroundAlt2` |

### Spacing

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(spacingXxSmall)` | `--slds-g-spacing-1` | `--lwc-spacingXxSmall` |
| `t(spacingXSmall)` | `--slds-g-spacing-2` | `--lwc-spacingXSmall` |
| `t(spacingSmall)` | `--slds-g-spacing-3` | `--lwc-spacingSmall` |
| `t(spacingMedium)` | `--slds-g-spacing-4` | `--lwc-spacingMedium` |
| `t(spacingLarge)` | `--slds-g-spacing-5` | `--lwc-spacingLarge` |
| `t(templateGutters)` | `--slds-g-spacing-3` | `--lwc-templateGutters` |

### Border Radius

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(borderRadiusSmall)` | `--slds-g-radius-border-1` | `--lwc-borderRadiusSmall` |
| `t(borderRadiusMedium)` | `--slds-g-radius-border-2` | `--lwc-borderRadiusMedium` |
| `t(borderRadiusLarge)` | `--slds-g-radius-border-3` | `--lwc-borderRadiusLarge` |

### Font Sizes

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(fontSizeSmall)` | `--slds-g-font-scale-1` | `--lwc-fontSizeSmall` |
| `t(fontSizeMedium)` | `--slds-g-font-scale-2` | `--lwc-fontSizeMedium` |
| `t(fontSizeLarge)` | `--slds-g-font-scale-3` | `--lwc-fontSizeLarge` |
| `t(fontSizeXLarge)` | `--slds-g-font-scale-4` | `--lwc-fontSizeXLarge` |

### Font Weights

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(fontWeightLight)` | `--slds-g-font-weight-3` | `--lwc-fontWeightLight` |
| `t(fontWeightRegular)` | `--slds-g-font-weight-4` | `--lwc-fontWeightRegular` |
| `t(fontWeightBold)` | `--slds-g-font-weight-7` | `--lwc-fontWeightBold` |

### Line Heights

| Legacy Token | SLDS2 Hook | LWC Fallback |
|---|---|---|
| `t(lineHeightHeading)` | `--slds-g-font-lineheight-2` | `--lwc-lineHeightHeading` |

---

## Tokens with No SLDS 2 Equivalent

### Z-Index

Z-index tokens have no SLDS 2 hook. Use the hardcoded value directly:

```css
/* Before */
z-index: t(zIndexSticky);

/* After — hardcoded, no hook available */
z-index: 9000;
```

### Duration

Duration tokens are for internal component transitions. Use `--lwc-*` directly — do NOT invent `--slds-g-duration-*` hooks:

```css
/* Bad — inventing a non-existent hook */
transition: var(--slds-g-duration-slowly, var(--lwc-durationSlowly));

/* Good — use --lwc-* directly */
transition: var(--lwc-durationSlowly);
```

Available duration tokens: `--lwc-durationInstantly`, `--lwc-durationPromptly`, `--lwc-durationSlowly`.

---

## Wizard Token Mappings

### oneDesktopSetupWizardTokens

From `oneDesktopSetupWizardTokens.tokens` — map wizard token → base token → SLDS 2:

| Wizard Token | SLDS2 Replacement |
|---|---|
| `wizardColorTextHeader` | `var(--slds-g-color-on-surface-3, var(--lwc-colorTextDefault))` |
| `wizardColorActiveMilestoneTracker` | `var(--lwc-colorBackgroundButtonBrand)` |
| `wizardColorInactiveMilestoneTracker` | `var(--slds-g-color-surface-container-1, var(--lwc-colorBackgroundInputDisabled))` |
| `wizardColorTextMilestoneTracker` | `var(--slds-g-color-on-surface-3, var(--lwc-colorTextActionLabelActive))` |
| `wizardFontWeightMilestoneTracker` | `var(--slds-g-font-weight-4, var(--lwc-fontWeightRegular))` |
| `wizardFontSizeMilestoneTracker` | `var(--slds-g-font-scale-2, var(--lwc-fontSizeMedium))` |
| `wizardColorBackgroundError` | `var(--slds-g-color-surface-container-2, var(--lwc-colorBackgroundInput))` |
| `wizardBorderRadiusError` | `var(--slds-g-radius-border-2, var(--lwc-borderRadiusMedium))` |

### s1wizardNamespace

From `s1wizardNamespace.tokens`:

| S1wizard Token | SLDS2 Replacement |
|---|---|
| `s1wizardContactFieldBackground` | `var(--slds-g-color-on-surface-1, var(--lwc-colorBackgroundActionbarIconUtility))` |
| `s1wizardComicHeadingFontFamily` | `var(--slds-g-font-family, var(--lwc-fontFamily))` |
| `s1wizardComicHeadingTextSize` | `var(--slds-g-font-scale-4, var(--lwc-fontSizeXLarge))` |
| `s1wizardComicHeadingTextColor` | `var(--slds-g-color-on-surface-3, var(--lwc-colorTextDefault))` |

---

## Font-Family Cleanup

After the linter runs, it may add verbose font-stack fallbacks to `font-family`. For **font-family only**, trim to just the hook tokens — remove the hardcoded font stack:

```css
/* Linter output — verbose */
font-family: var(--slds-g-font-family, var(--lwc-fontFamily, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif));

/* Cleaned up — tokens only */
font-family: var(--slds-g-font-family, var(--lwc-fontFamily));
```

For all other properties, **keep** the linter's fallbacks (rgb, rem, px values).

---

## Mandatory Rules

**Rule 1: ONLY USE LINTER-SUGGESTED HOOKS**
- Read the linter output first
- Only use hooks that the linter suggests as replacements
- If the linter says "no replacement", see "Tokens with No SLDS 2 Equivalent" above

**Rule 2: ALWAYS INCLUDE FALLBACK**
- Format: `var(--slds-g-[hook], var(--lwc-[token]))`
- The `--lwc-*` fallback ensures the component still works if the SLDS 2 hook isn't available

**Rule 3: MINIMAL CHANGES**
- Only fix actual `slds/no-deprecated-tokens-slds1` violations
- Do not refactor surrounding code or styles
- Reference line numbers for all modifications

---

## Validation Checklist

- [ ] All `t()` and `token()` calls have SLDS 2 replacements (or documented as no-equivalent)
- [ ] Replacements use linter-suggested hooks
- [ ] Original token included as LWC fallback: `var(--slds-g-*, var(--lwc-*))`
- [ ] Duration tokens use `--lwc-*` directly (not invented `--slds-g-duration-*`)
- [ ] Z-index tokens use hardcoded values
- [ ] Font-family has no font-stack fallback (tokens only)
- [ ] Re-run linter shows zero errors for this rule
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall