@salesforce/afv-skills 1.21.0 → 1.22.0

package/skills/design-systems-slds2-migrate/references/examples.md

@@ -0,0 +1,461 @@
+# 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:**
+```
+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:**
+```
+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:**
+```
+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`.

package/skills/design-systems-slds2-migrate/references/migration-checklist.md

@@ -0,0 +1,67 @@
+# SLDS 2 Uplift Checklist
+
+Validation checklist for each CSS file after applying SLDS 2 uplift fixes.
+
+---
+
+## Per-Rule Checks
+
+### `slds/no-slds-class-overrides`
+
+**CSS:**
+- [ ] All `.slds-*` overrides reported by the linter are renamed to `{componentName}-{sldsElementPart}`
+- [ ] Component name is camelCase
+- [ ] SLDS element names preserved after prefix (e.g., `.slds-button` → `myComponent-button`)
+- [ ] Each SLDS class in a compound selector gets its own component class
+
+**HTML:**
+- [ ] Original SLDS classes preserved (never removed)
+- [ ] Component classes added alongside SLDS classes
+- [ ] Every element in CSS selector chain updated in HTML
+
+### `slds/lwc-token-to-slds-hook`
+
+- [ ] All `var(--lwc-*)` tokens replaced with SLDS 2 hooks
+- [ ] Hooks chosen from linter's numbered suggestion list (not invented)
+- [ ] Surface vs container choice matches DOM context
+- [ ] Fallback includes original token: `var(--slds-g-[hook], var(--lwc-[token]))`
+
+### `slds/no-hardcoded-values-slds2`
+
+- [ ] Color values replaced with context-appropriate hooks (surface, accent, feedback, etc.)
+- [ ] Non-color values (spacing, sizing, typography, border, radius, shadow) replaced where exact match exists
+- [ ] Hardcoded numerical values left unchanged — do not replace or remove values like `100%`, `50%`, `200px`, `1.5`, `auto`, `0`, `inherit`, `none`, `flex: 1`
+- [ ] All replacements include original value as fallback: `var(--slds-g-[hook], originalValue)`
+- [ ] Only numbered hooks used (no `spacing-medium`, `font-weight-bold`, etc.)
+
+---
+
+## Cross-Cutting Checks
+
+### Hook Selection
+- [ ] Background-foreground hooks paired from same family (e.g., `surface-container-*` with `on-surface-*`)
+- [ ] Spacing hooks for margin/padding/gap; sizing hooks for width/height
+- [ ] Density-aware variants (`--slds-g-spacing-var-*`) used where component adapts to comfy/compact
+
+### Linter Validation
+- [ ] `npx @salesforce-ux/slds-linter@latest lint .` — zero errors
+- [ ] Warnings reviewed — remaining warnings are for values with no available hook
+
+---
+
+## Troubleshooting
+
+### Visual appearance changed
+1. Check fallback values match original hardcoded values exactly
+2. Verify correct hook family (surface vs container)
+3. Ensure background-foreground hooks properly paired
+
+### Linter still shows violations
+1. Verify hook names exactly match linter suggestions
+2. Check for missed CSS files in subdirectories
+3. Ensure all elements in selector chains updated in HTML
+
+### Functionality broken
+1. Check original SLDS classes preserved in HTML
+2. Verify JavaScript selectors updated if CSS classes changed (class overrides rule)
+3. Update tests that use class-based query selectors