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/examples.md

View on GitHub
# SLDS Migration Examples

Before/after examples organized by violation type.

## Table of Contents

- [Class Override Example](#class-override-example)
- [LWC Token Example](#lwc-token-example)
- [Hardcoded Value Examples](#hardcoded-value-examples)
- [Aura t() Token Migration](#aura-t-token-migration)
- [Deprecated Class Removal](#deprecated-class-removal)
- [Color-Mix with Transparency](#color-mix-with-transparency)
- [calc() with Legacy Tokens](#calc-with-legacy-tokens)
- [Tokens with No SLDS 2 Equivalent](#tokens-with-no-slds-2-equivalent)
- [Multi-File End-to-End (Aura)](#multi-file-end-to-end-aura)

---

## Class Override Example

**Violation:**
```text
dataTable.css
  5:1   warning  Overriding slds-table isn't supported. To differentiate SLDS and
                 custom classes, create a CSS class in your namespace.
                 Examples: myapp-input, myapp-button.                      slds/no-slds-class-overrides
  12:1  warning  Overriding slds-button isn't supported...                 slds/no-slds-class-overrides
```

**Before:**
```css
.slds-table {
  border-width: var(--slds-g-sizing-border-1, 1px);
  border-radius: var(--slds-g-radius-border-2, 0.25rem);
}

.slds-table .slds-button {
  padding: var(--slds-g-spacing-2, 0.5rem) var(--slds-g-spacing-2, 1rem);
}
```

```html
<table class="slds-table">
  <tr><td><button class="slds-button">Edit</button></td></tr>
</table>
```

**After:**
```css
.dataTable-table {
  border-width: var(--slds-g-sizing-border-1, 1px);
  border-radius: var(--slds-g-radius-border-2, 0.25rem);
}

.dataTable-table .dataTable-button {
  padding: var(--slds-g-spacing-2, 0.5rem) var(--slds-g-spacing-2, 1rem);
}
```

```html
<table class="slds-table dataTable-table">
  <tr><td><button class="slds-button dataTable-button">Edit</button></td></tr>
</table>
```

---

## LWC Token Example

**Violation:**
```text
panelHeader.css
  3:3  error  The '--lwc-colorBackgroundAlt' design token is deprecated. Replace it with
              the SLDS 2 styling hook and set the fallback to '--lwc-colorBackgroundAlt'.
              1. --slds-g-color-surface-2
              2. --slds-g-color-surface-container-2                        slds/lwc-token-to-slds-hook
```

**Before:**
```css
.header-bar {
  background-color: var(--lwc-colorBackgroundAlt);
}
```

```html
<div class="THIS">
  <div class="header-bar">Settings</div>
  <div class="panel-content">...</div>
</div>
```

**Context:** `.header-bar` is a section within the component → choose container.

**After:**
```css
.header-bar {
  background-color: var(--slds-g-color-surface-container-2, var(--lwc-colorBackgroundAlt));
}
```

---

## Hardcoded Value Examples

### Tile with Border and Spacing

**Violation:**
```text
tile.css
  2:20  warning  Consider replacing the #ffffff static value with an SLDS 2 styling hook
                 that has a similar value:
                 1. --slds-g-color-surface-1
                 2. --slds-g-color-surface-container-1
                 3. --slds-g-color-on-accent-1
                 4. --slds-g-color-on-accent-2
                 5. --slds-g-color-on-accent-3                             slds/no-hardcoded-values-slds2
```

**Before:**
```css
.info-tile {
  background-color: #ffffff;
  border: 1px solid #e5e5e5;
  padding: 1rem;
}
```

**Context:** Tile is a container sitting on a page surface → choose `surface-container-1` from the list.

**After:**
```css
.info-tile {
  background-color: var(--slds-g-color-surface-container-1, #ffffff);
  border: var(--slds-g-sizing-border-1, 1px) solid var(--slds-g-color-border-1, #e5e5e5);
  padding: var(--slds-g-spacing-4, 1rem);
}
```

### Modal Background

**Before:**
```css
.modal-overlay {
  background-color: #ffffff;
}
```

**Context:** Modal creates a new stacking context (overlay) → choose `surface-1`, NOT `surface-container-1`.

**After:**
```css
.modal-overlay {
  background-color: var(--slds-g-color-surface-1, #ffffff);
}
```

### Link Colors

**Before:**
```css
.nav-link {
  color: #0176d3;
}

.nav-link:hover {
  color: #014486;
}
```

**Context:** Links are interactive → accent family. Default = accent-2 (accessible). Hover goes one up: accent-3.

**After:**
```css
.nav-link {
  color: var(--slds-g-color-accent-2, #0176d3);
}

.nav-link:hover {
  color: var(--slds-g-color-accent-3, #014486);
}
```

### Alert Validation States

**Before:**
```css
.alert-error {
  border-color: #c23934;
  background: #fddde3;
}

.alert-error-text {
  color: #c23934;
  font-size: 12px;
}

.alert-success {
  border-color: #4bca81;
}
```

**After:**
```css
.alert-error {
  border-color: var(--slds-g-color-border-error-1, #c23934);
  background: var(--slds-g-color-error-container-1, #fddde3);
}

.alert-error-text {
  color: var(--slds-g-color-on-error-1, #c23934);
  font-size: var(--slds-g-font-scale-neg-1, 12px);
}

.alert-success {
  border-color: var(--slds-g-color-border-success-1, #4bca81);
}
```

### Brand Icon with Accent Background

**Before:**
```css
.icon-container {
  width: 2rem;
  height: 2rem;
  background-color: #066AFE;
}

.account-icon {
  fill: #FFFFFF;
}
```

**Context:** Blue background with white icon = brand element → accent family. `on-accent` pairs with `accent-container`.

**After:**
```css
.icon-container {
  width: var(--slds-g-sizing-9, 2rem);
  height: var(--slds-g-sizing-9, 2rem);
  background-color: var(--slds-g-color-accent-container-1, #066AFE);
}

.account-icon {
  fill: var(--slds-g-color-on-accent-1, #FFFFFF);
}
```

### Profile Header — Spacing, Typography, and Shadow

**Before:**
```css
.profile-header {
  padding: 1.5rem;
  border-radius: 0.75rem;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.profile-name {
  font-size: 18px;
  font-weight: 700;
  line-height: 1.25;
  margin-bottom: 0.5rem;
}

.profile-role {
  font-size: 14px;
  font-weight: 400;
  line-height: 1.5;
}
```

**After:**
```css
.profile-header {
  padding: var(--slds-g-spacing-5, 1.5rem);
  border-radius: var(--slds-g-radius-border-3, 0.75rem);
  box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1));
}

.profile-name {
  font-size: var(--slds-g-font-scale-4, 18px);
  font-weight: var(--slds-g-font-weight-7, 700);
  line-height: var(--slds-g-font-lineheight-2, 1.25);
  margin-bottom: var(--slds-g-spacing-2, 0.5rem);
}

.profile-role {
  font-size: var(--slds-g-font-scale-1, 14px);
  font-weight: var(--slds-g-font-weight-4, 400);
  line-height: var(--slds-g-font-lineheight-4, 1.5);
}
```

### Search Input — Border and Focus

**Before:**
```css
.search-input {
  border: 1px solid #ccc;
  border-radius: 0.5rem;
  padding: 0.5rem 0.75rem;
  font-size: 14px;
}

.search-input:focus {
  border-width: 3px;
}
```

**After:**
```css
.search-input {
  border: var(--slds-g-sizing-border-1, 1px) solid var(--slds-g-color-border-2, #ccc);
  border-radius: var(--slds-g-radius-border-2, 0.5rem);
  padding: var(--slds-g-spacing-2, 0.5rem) var(--slds-g-spacing-3, 0.75rem);
  font-size: var(--slds-g-font-scale-1, 14px);
}

.search-input:focus {
  border-width: var(--slds-g-sizing-border-3, 3px);
}
```

### What NOT to Replace

Layout values (`100%`, `auto`, `0`, `flex: 1`, `none`), animation properties, opacity, and overlay alpha values (`rgba(0,0,0,0.5)`) should remain unchanged. See [rule-no-hardcoded-values.md](rule-no-hardcoded-values.md) for the full list.

---

## Aura t() Token Migration

**Before:**
```css
.THIS .stepTitle {
  color: t(colorTextPlaceholder);
  font-size: t(fontSizeMedium);
  padding: t(spacingSmall);
}
```

**After:**
```css
.THIS .stepTitle {
  color: var(--slds-g-color-on-surface-2, var(--lwc-colorTextPlaceholder));
  font-size: var(--slds-g-font-scale-2, var(--lwc-fontSizeMedium));
  padding: var(--slds-g-spacing-3, var(--lwc-spacingSmall));
}
```

**Why these hooks:** `colorTextPlaceholder` maps to `on-surface-2` (muted foreground text). `fontSizeMedium` maps to `font-scale-2` (1rem). `spacingSmall` maps to `spacing-3` (0.75rem). See [rule-no-deprecated-tokens-slds1.md](rule-no-deprecated-tokens-slds1.md) for all token mappings.

---

## Deprecated Class Removal

**Before (`.cmp`):**
```html
<span class="slds-icon_container slds-icon-utility-error">
  <lightning:icon iconName="utility:error" />
</span>
```

**After:**
```html
<span class="slds-icon_container">
  <lightning:icon iconName="utility:error" />
</span>
```

**Why remove:** `slds-icon-utility-*` classes are removed in SLDS 2. The `<lightning:icon>` component applies its own styling via `iconName`. Keeping the deprecated class causes linter errors and has no visual effect.

---

## Color-Mix with Transparency

**Before:**
```css
.THIS .errorBorder { border: 2px solid rgba(186, 5, 23, 0.7); }
```

**After:**
```css
.THIS .errorBorder {
  border: var(--slds-g-sizing-border-2, 2px) solid color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);
}
```

**Why color-mix:** `rgba()` can't wrap a CSS variable for the color component alone. `color-mix(in oklab, ...)` lets you apply transparency to the hook's resolved value at runtime. Formula: X% opacity = (100-X)% transparent. Use opaque `rgb()` fallback to avoid double transparency when both `color-mix` and `rgba` are applied.

---

## calc() with Legacy Tokens

**Before:**
```css
height: t('calc(' + lineHeightButton + ' + 2px)');
```

**After (if calc needed):**
```css
height: calc(var(--lwc-lineHeightButton) + 2px);
```

**Simplified (try first):**
```css
height: var(--lwc-lineHeightButton);
```

**Why simplify:** The `+ 2px` in legacy `t()` calc expressions was often a workaround for rendering inconsistencies. Try without it first — if the component renders correctly, the simpler form is preferred.

---

## Tokens with No SLDS 2 Equivalent

```css
/* Before */
z-index: var(--lwc-zIndexSticky);
transition: opacity var(--slds-g-duration-slowly, var(--lwc-durationSlowly)) ease-in-out;

/* After — z-index: hardcoded, duration: --lwc-* directly */
z-index: 9000;
transition: opacity var(--lwc-durationSlowly) ease-in-out;
```

**Why:** Not every legacy token has an SLDS 2 equivalent. Z-index and duration are internal layout/animation concerns — hardcode z-index, use `--lwc-*` for duration. Inventing `--slds-g-duration-*` triggers `slds/no-slds-namespace-for-custom-hooks`.

---

## Multi-File End-to-End (Aura)

**CSS before:**
```css
.THIS .slds-card__header {
  background: var(--lwc-colorBackgroundAlt);
  z-index: var(--lwc-zIndexSticky);
  border-bottom: 1px solid #ddd;
}
```

**CSS after:**
```css
.THIS .relatedList-card-header {
  background: var(--slds-g-color-surface-container-2, var(--lwc-colorBackgroundAlt));
  z-index: 9000;
  border-bottom: var(--slds-g-sizing-border-1, 1px) solid var(--slds-g-color-border-1, #ddd);
}
```

**Markup before (`.cmp`):**
```html
<h2 class="slds-card__header">Related Items</h2>
```

**Markup after:**
```html
<h2 class="slds-card__header relatedList-card-header">Related Items</h2>
```

Three rules applied: token replacement, class override, hardcoded border. `slds-card__header` is a part within a card → choose `container`.
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