uplifting-components-to-slds2

What this skill does

# Goal

Systematically migrate Lightning Web Components from SLDS 1 to SLDS 2 using the SLDS linter and structured guidance for fixing violations across all styling hook categories.

## SLDS 2 Styling Hook Categories

| Category | Hook Prefix | What It Replaces |
|---|---|---|
| Color | `--slds-g-color-*` | Hardcoded colors, `--lwc-color*` tokens |
| Spacing | `--slds-g-spacing-*` | Hardcoded margins, padding, gaps |
| Sizing | `--slds-g-sizing-*` | Hardcoded widths, heights, dimensions |
| Typography | `--slds-g-font-*` | Hardcoded font sizes, weights, line heights |
| Border/Radius | `--slds-g-radius-border-*`, `--slds-g-sizing-border-*` | Hardcoded border-radius, border-width |
| Shadow | `--slds-g-shadow-*` | Hardcoded box-shadow values |

Color hooks require the most judgment (context-dependent selection). Non-color hooks are mostly numbered scales with straightforward mappings.

## Prerequisites

- Node.js 14.x or higher installed
- Access to component CSS and markup files (`.html` for LWC, `.cmp` for Aura)
- Terminal/command line access to run linter
- Git repository for backup (recommended)

---

# Workflow

```
1. Run SLDS linter with auto-fix -> Handles simple violations automatically
2. Review linter output -> Identify remaining manual fixes needed
3. Fix by violation type -> Use per-rule reference guides
4. Choose the right hook -> Context-first, inspect HTML before deciding
5. Validate -> Re-run linter and confirm zero errors
```

## Step 1: Run SLDS Linter

```bash
npx @salesforce-ux/slds-linter@latest lint --fix .
```

The linter analyzes all CSS and markup files (`.html` for LWC, `.cmp` for Aura), auto-fixes simple violations, and reports remaining issues requiring manual intervention.

## Step 2: Analyze Linter Output

The linter reports violations in this format:

```
componentName.css
  15:3  warning  Overriding slds-button 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

  23:5  error    The '--lwc-colorBackground' design token is deprecated. Replace it with
                 the SLDS 2 styling hook and set the fallback to '--lwc-colorBackground'.
                 1. --slds-g-color-surface-2
                 2. --slds-g-color-surface-container-2                      slds/lwc-token-to-slds-hook

  30:8  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

  31:15  error   Consider removing t(fontSizeMedium) or replacing it with
                 var(--slds-g-font-size-base, var(--lwc-fontSizeMedium, 0.8125rem)).
                 Set the fallback to t(fontSizeMedium). For more info, see
                 Styling Hooks on lightningdesignsystem.com.               slds/no-deprecated-tokens-slds1
```

Four violation types, each with its own fix approach (see Step 3).

**Important:** The linter flags all hardcoded values. Fix color, spacing, sizing, typography, border, and shadow values — but **skip layout values** (`100%`, `auto`, `0`, `inherit`, `none`). See [rule-no-hardcoded-values.md](references/rule-no-hardcoded-values.md) for the full fix-vs-skip triage table.

## Step 3: Fix Violations by Type

Each rule has a dedicated reference guide with full examples and decision logic:

| Violation Rule | Quick Summary | Reference |
|---|---|---|
| `slds/no-hardcoded-values-slds2` | Replace hardcoded values with SLDS hook + original as fallback | [rule-no-hardcoded-values.md](references/rule-no-hardcoded-values.md)|
| `slds/lwc-token-to-slds-hook` | Replace `--lwc-*` tokens with SLDS 2 hook, keep LWC token as fallback | [rule-lwc-token-to-slds-hook.md](references/rule-lwc-token-to-slds-hook.md) |
| `slds/no-slds-class-overrides` | Create component-prefixed class, add to markup alongside SLDS class | [rule-no-slds-class-overrides.md](references/rule-no-slds-class-overrides.md) |
| `slds/no-deprecated-tokens-slds1` | Replace legacy `t()`/`token()` syntax with SLDS 2 hook + LWC fallback | [rule-no-deprecated-tokens-slds1.md](references/rule-no-deprecated-tokens-slds1.md) |

**Always include fallback values** — `var(--slds-g-hook, originalValue)` where `originalValue` is the exact original from the source CSS.

### Class Override Quick Reference

Class overrides require changes to **both CSS and markup** (`.html` or `.cmp`). This is the most commonly missed step:

1. **CSS:** Rename `.slds-*` selector → `{componentName}-{sldsElementPart}` (camelCase)
2. **Markup:** Add the new class **alongside** the SLDS class — never remove the SLDS class

```css
/* Before */ .slds-button { border-radius: 8px; }
/* After */  .myComponent-button { border-radius: 8px; }
```
```html
<!-- Markup: both classes --> <button class="slds-button myComponent-button">Click</button>
```

See [rule-no-slds-class-overrides.md](references/rule-no-slds-class-overrides.md) for descendant selectors, multi-class selectors, and naming conventions.

## Step 4: Choose the Right Hook

**Color hooks** require context-based selection — inspect the HTML to determine the element's role before choosing a hook family. See **[color-hooks-decision-guide.md](references/color-hooks-decision-guide.md)** for decision trees, all 5 hook families, and background-foreground pairing rules.

**Non-color hooks** are simpler — match the CSS value to the numbered scale. See **[non-color-hooks-decision-guide.md](references/non-color-hooks-decision-guide.md)** for value-to-hook lookup tables covering spacing, sizing, typography, borders, radius, and shadows.

## Step 5: Validate and Verify

**Linter feedback loop — repeat until zero errors:**

```
1. npx @salesforce-ux/slds-linter@latest lint .
2. Review errors -> fix by type (Step 3)
3. Re-run linter
4. Repeat until output shows: 0 errors
```

---

# Validation

- [ ] No `.slds-*` classes in CSS selectors
- [ ] No `var(--lwc-*)` tokens without SLDS 2 replacements
- [ ] All hooks include fallback values
- [ ] Background/foreground color hooks from same family
- [ ] Original SLDS classes preserved in HTML
- [ ] Spacing uses numbered hooks (not named like `spacing-medium`)
- [ ] Typography uses numbered hooks (not named like `font-weight-bold`)
- [ ] Component renders correctly in light/dark mode and density settings

See **[migration-checklist.md](references/migration-checklist.md)** for the full validation checklist.

---

# Output

Return the fully migrated CSS (and updated HTML markup where class overrides were fixed) with zero SLDS linter violations. All styling hooks must include fallback values preserving the original CSS values.

---

# Advanced Patterns

## Color-Mix for Transparency

When a hardcoded value uses `rgba()` or transparency, use `color-mix()` with the SLDS hook to preserve opacity:

```css
/* Before */
border-color: rgba(186, 5, 23, 0.7);

/* After — use oklab color space for perceptual consistency */
border-color: color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);
```

**Formula:** To achieve X% opacity, use `(100 - X)%` transparent in `color-mix`.
- 70% opacity → `transparent 30%`
- 50% opacity → `transparent 50%`

Use opaque `rgb()` as fallback (not `rgba()`) — `color-mix` handles the transparency.

## calc() Expressions with Tokens

When migrating `t('calc(...)')` or `calc()` with deprecated tokens:

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

/* After — if calc is still needed */
height: calc(var(--lwc-lineHeightButton) + 2px);

/* After — if calc was unnecessary, simplify */
height: var(--lwc-lineHeightButton)