Skip to content

Commit e850eb1

Browse files
kenamvermakenamverma
authored
W-21831072: Add skill: uplifting-components-to-slds2 (#152)
Add skill: uplifting components to slds2 Made-with: Cursor
1 parent ce36522 commit e850eb1

10 files changed

Lines changed: 2236 additions & 0 deletions

‎skills/uplifting-components-to-slds2/SKILL.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
---
2+
name: uplifting-components-to-slds2
3+
description: 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".
4+
---
5+
6+
# Goal
7+
8+
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.
9+
10+
## SLDS 2 Styling Hook Categories
11+
12+
| Category | Hook Prefix | What It Replaces |
13+
|---|---|---|
14+
| Color | `--slds-g-color-*` | Hardcoded colors, `--lwc-color*` tokens |
15+
| Spacing | `--slds-g-spacing-*` | Hardcoded margins, padding, gaps |
16+
| Sizing | `--slds-g-sizing-*` | Hardcoded widths, heights, dimensions |
17+
| Typography | `--slds-g-font-*` | Hardcoded font sizes, weights, line heights |
18+
| Border/Radius | `--slds-g-radius-border-*`, `--slds-g-sizing-border-*` | Hardcoded border-radius, border-width |
19+
| Shadow | `--slds-g-shadow-*` | Hardcoded box-shadow values |
20+
21+
Color hooks require the most judgment (context-dependent selection). Non-color hooks are mostly numbered scales with straightforward mappings.
22+
23+
## Prerequisites
24+
25+
- Node.js 14.x or higher installed
26+
- Access to component CSS and markup files (`.html` for LWC, `.cmp` for Aura)
27+
- Terminal/command line access to run linter
28+
- Git repository for backup (recommended)
29+
30+
---
31+
32+
# Workflow
33+
34+
```
35+
1. Run SLDS linter with auto-fix -> Handles simple violations automatically
36+
2. Review linter output -> Identify remaining manual fixes needed
37+
3. Fix by violation type -> Use per-rule reference guides
38+
4. Choose the right hook -> Context-first, inspect HTML before deciding
39+
5. Validate -> Re-run linter and confirm zero errors
40+
```
41+
42+
## Step 1: Run SLDS Linter
43+
44+
```bash
45+
npx @salesforce-ux/slds-linter@latest lint --fix .
46+
```
47+
48+
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.
49+
50+
## Step 2: Analyze Linter Output
51+
52+
The linter reports violations in this format:
53+
54+
```
55+
componentName.css
56+
15:3 warning Overriding slds-button isn't supported. To differentiate SLDS and
57+
custom classes, create a CSS class in your namespace.
58+
Examples: myapp-input, myapp-button. slds/no-slds-class-overrides
59+
60+
23:5 error The '--lwc-colorBackground' design token is deprecated. Replace it with
61+
the SLDS 2 styling hook and set the fallback to '--lwc-colorBackground'.
62+
1. --slds-g-color-surface-2
63+
2. --slds-g-color-surface-container-2 slds/lwc-token-to-slds-hook
64+
65+
30:8 warning Consider replacing the #ffffff static value with an SLDS 2 styling hook
66+
that has a similar value:
67+
1. --slds-g-color-surface-1
68+
2. --slds-g-color-surface-container-1
69+
3. --slds-g-color-on-accent-1
70+
4. --slds-g-color-on-accent-2
71+
5. --slds-g-color-on-accent-3 slds/no-hardcoded-values-slds2
72+
73+
31:15 error Consider removing t(fontSizeMedium) or replacing it with
74+
var(--slds-g-font-size-base, var(--lwc-fontSizeMedium, 0.8125rem)).
75+
Set the fallback to t(fontSizeMedium). For more info, see
76+
Styling Hooks on lightningdesignsystem.com. slds/no-deprecated-tokens-slds1
77+
```
78+
79+
Four violation types, each with its own fix approach (see Step 3).
80+
81+
**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.
82+
83+
## Step 3: Fix Violations by Type
84+
85+
Each rule has a dedicated reference guide with full examples and decision logic:
86+
87+
| Violation Rule | Quick Summary | Reference |
88+
|---|---|---|
89+
| `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)|
90+
| `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) |
91+
| `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) |
92+
| `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) |
93+
94+
**Always include fallback values** — `var(--slds-g-hook, originalValue)` where `originalValue` is the exact original from the source CSS.
95+
96+
### Class Override Quick Reference
97+
98+
Class overrides require changes to **both CSS and markup** (`.html` or `.cmp`). This is the most commonly missed step:
99+
100+
1. **CSS:** Rename `.slds-*` selector → `{componentName}-{sldsElementPart}` (camelCase)
101+
2. **Markup:** Add the new class **alongside** the SLDS class — never remove the SLDS class
102+
103+
```css
104+
/* Before */ .slds-button { border-radius: 8px; }
105+
/* After */ .myComponent-button { border-radius: 8px; }
106+
```
107+
```html
108+
<!-- Markup: both classes --> <button class="slds-button myComponent-button">Click</button>
109+
```
110+
111+
See [rule-no-slds-class-overrides.md](references/rule-no-slds-class-overrides.md) for descendant selectors, multi-class selectors, and naming conventions.
112+
113+
## Step 4: Choose the Right Hook
114+
115+
**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.
116+
117+
**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.
118+
119+
## Step 5: Validate and Verify
120+
121+
**Linter feedback loop — repeat until zero errors:**
122+
123+
```
124+
1. npx @salesforce-ux/slds-linter@latest lint .
125+
2. Review errors -> fix by type (Step 3)
126+
3. Re-run linter
127+
4. Repeat until output shows: 0 errors
128+
```
129+
130+
---
131+
132+
# Validation
133+
134+
- [ ] No `.slds-*` classes in CSS selectors
135+
- [ ] No `var(--lwc-*)` tokens without SLDS 2 replacements
136+
- [ ] All hooks include fallback values
137+
- [ ] Background/foreground color hooks from same family
138+
- [ ] Original SLDS classes preserved in HTML
139+
- [ ] Spacing uses numbered hooks (not named like `spacing-medium`)
140+
- [ ] Typography uses numbered hooks (not named like `font-weight-bold`)
141+
- [ ] Component renders correctly in light/dark mode and density settings
142+
143+
See **[migration-checklist.md](references/migration-checklist.md)** for the full validation checklist.
144+
145+
---
146+
147+
# Output
148+
149+
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.
150+
151+
---
152+
153+
# Advanced Patterns
154+
155+
## Color-Mix for Transparency
156+
157+
When a hardcoded value uses `rgba()` or transparency, use `color-mix()` with the SLDS hook to preserve opacity:
158+
159+
```css
160+
/* Before */
161+
border-color: rgba(186, 5, 23, 0.7);
162+
163+
/* After — use oklab color space for perceptual consistency */
164+
border-color: color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);
165+
```
166+
167+
**Formula:** To achieve X% opacity, use `(100 - X)%` transparent in `color-mix`.
168+
- 70% opacity → `transparent 30%`
169+
- 50% opacity → `transparent 50%`
170+
171+
Use opaque `rgb()` as fallback (not `rgba()`) — `color-mix` handles the transparency.
172+
173+
## calc() Expressions with Tokens
174+
175+
When migrating `t('calc(...)')` or `calc()` with deprecated tokens:
176+
177+
```css
178+
/* Before — Aura t() with calc */
179+
height: t('calc(' + lineHeightButton + ' + 2px)');
180+
181+
/* After — if calc is still needed */
182+
height: calc(var(--lwc-lineHeightButton) + 2px);
183+
184+
/* After — if calc was unnecessary, simplify */
185+
height: var(--lwc-lineHeightButton);
186+
```
187+
188+
For `calc()` with `--lwc-*` tokens being replaced:
189+
190+
```css
191+
/* Before */
192+
padding: calc(var(--lwc-spacingMedium) + 4px);
193+
194+
/* After */
195+
padding: calc(var(--slds-g-spacing-4, var(--lwc-spacingMedium)) + 4px);
196+
```
197+
198+
**Tip:** Often the `calc()` is unnecessary and can be simplified. Check if the result matches an existing hook value.
199+
200+
---
201+
202+
# Key Constraints
203+
204+
- **Never invent hook names** — only use hooks documented in the SLDS design system
205+
- **Always include fallback values** — the fallback must be the exact original value from the source CSS
206+
- **Never change hardcoded numerical values** — values like `100%`, `50%`, `200px`, `1.5`, `auto`, `0`, `inherit`, `none`, `flex: 1` are structural/layout values. Do not replace them with hooks and do not remove them — they are not styling hook candidates
207+
- **No exact match? Leave as-is** — if a hardcoded value doesn't closely correspond to any hook's rendered value, leave it unchanged rather than force-fitting
208+
- **Match hook number to original value intensity** — don't default to `-1`. Pick the variant closest to the original. See [color-hooks-decision-guide.md](references/color-hooks-decision-guide.md)
209+
- **Only numbered scales** — named hooks like `spacing-medium`, `font-weight-bold`, `radius-large` do NOT exist
210+
211+
# Troubleshooting
212+
213+
| Issue | Solution |
214+
|---|---|
215+
| Linter suggests 2+ color hook options | Inspect HTML context to determine element's semantic role — see color-hooks-decision-guide.md |
216+
| Visual appearance changed after migration | Verify fallback values match originals; check surface vs container family |
217+
| No hook available for hardcoded value | Leave unchanged; do not invent custom hook names |
218+
| Linter says "Remove the static value" for `100%`, `auto`, etc. | Leave unchanged — these are layout values. Removing them breaks rendering. |
219+
| CSS class naming errors | Use exact camelCase component name: `myComponent-button`, not `MyComponent-button` |
220+
| Spacing/sizing doesn't match | Check value-to-hook mapping in non-color-hooks-decision-guide.md; verify spacing vs sizing usage |
221+
| Named hook not working (e.g., `spacing-medium`) | Named hooks don't exist — use numbered scale: `spacing-4` for 16px, `font-weight-7` for inline bold emphasis (not headings) |
222+
| Component looks different in compact density | Use density-aware hooks (`--slds-g-spacing-var-*`) for components that adapt to density |
223+
224+
---
225+
226+
# References
227+
228+
- **[Color Hooks Decision Guide](references/color-hooks-decision-guide.md)** — All 5 color hook families, decision trees, background-foreground pairing, palette accessibility
229+
- **[Non-Color Hooks Decision Guide](references/non-color-hooks-decision-guide.md)** — Spacing, sizing, typography, borders, radius, and shadow hooks with lookup tables
230+
- **[Rule: No Hardcoded Values](references/rule-no-hardcoded-values.md)** — Linter behavior, fix-vs-skip triage, replacement pattern, utility class workflow
231+
- **[Rule: LWC Token to SLDS Hook](references/rule-lwc-token-to-slds-hook.md)** — Deprecated `--lwc-*` token replacement patterns
232+
- **[Rule: No Deprecated Tokens SLDS1](references/rule-no-deprecated-tokens-slds1.md)** — Legacy `t()`/`token()` Aura syntax replacement patterns
233+
- **[Rule: No SLDS Class Overrides](references/rule-no-slds-class-overrides.md)** — Class renaming and HTML updates
234+
- **[Migration Examples](references/examples.md)** — Before/after examples by scenario and complexity
235+
- **[Common Patterns](references/common-patterns.md)** — Classes never to override, deprecated SLDS 2 classes, palette fallbacks, tokens with no SLDS 2 equivalent
236+
- **[Migration Checklist](references/migration-checklist.md)** — Full validation checklist

0 commit comments

Comments
 (0)