@salesforce/afv-skills 1.5.2 → 1.6.0

package/skills/uplifting-components-to-slds2/references/non-color-hooks-decision-guide.md

@@ -0,0 +1,333 @@
+# Non-Color Styling Hooks Guide
+
+Reference for replacing hardcoded spacing, sizing, typography, border, radius, and shadow values with SLDS 2 styling hooks. These hooks use numbered scales with straightforward mappings — unlike color hooks, they rarely require context-based decisions.
+
+**Pattern for all replacements:**
+```css
+property: var(--slds-g-[hook], originalValue);
+```
+
+**Important: Only replace values that match a hook's actual rendered value.** If a hardcoded value falls between two hooks (e.g., `3px` when hooks offer `4px` and `8px`), leave it unchanged. The linter auto-fix handles exact matches; manual fixes should only apply when there's a clear correspondence. Forcing a non-matching value into the nearest hook changes the component's visual appearance.
+
+---
+
+## Critical Rule: Never Invent Hooks
+
+**Only use hooks that actually exist in SLDS 2.** The linter is the source of truth for which hooks exist and what values they map to. Do not:
+
+- **Guess hook names** — Hooks like `--slds-g-spacing-medium`, `--slds-g-font-weight-bold`, `--slds-g-radius-large` do NOT exist. SLDS 2 uses numbered scales only (e.g., `--slds-g-spacing-4`, `--slds-g-font-weight-7`).
+- **Extrapolate patterns** — If you see `--slds-g-spacing-1` through `--slds-g-spacing-12`, do not assume `--slds-g-spacing-13` exists. Each category has a fixed scale defined by the design system.
+- **Invent semantic names** — There are no `--slds-g-spacing-page`, `--slds-g-font-heading`, or `--slds-g-shadow-modal` hooks. Hooks are numeric, not semantic.
+
+**When unsure whether a hook exists:** Run the linter (`npx @salesforce-ux/slds-linter@latest lint --fix .`). It will suggest valid hooks for flagged values. If the linter doesn't flag a value or doesn't suggest a hook, leave it hardcoded.
+
+---
+
+## Table of Contents
+
+- [Spacing Hooks](#spacing-hooks)
+- [Sizing Hooks](#sizing-hooks)
+- [Typography Hooks](#typography-hooks)
+- [Border Width Hooks](#border-width-hooks)
+- [Border Radius Hooks](#border-radius-hooks)
+- [Shadow Hooks](#shadow-hooks)
+- [Uplift Decision Tree](#uplift-decision-tree--non-color)
+- [Common Mistakes](#common-mistakes)
+- [Accessibility Notes](#accessibility-notes)
+
+---
+
+## Spacing Hooks
+
+**Prefix:** `--slds-g-spacing-*`
+**Use for:** `margin`, `padding`, `gap`, `row-gap`, `column-gap`
+**Do NOT use for:** `width`, `height`, or other dimension properties (use sizing hooks)
+
+**Scale range: 1–12.** There is no `--slds-g-spacing-13` or higher. If a value exceeds 5rem/80px, leave it hardcoded.
+
+### Density-Aware Spacing
+
+For components that adapt between comfy and compact display density, use density-aware variants:
+
+| Hook Pattern | Applies To |
+|---|---|
+| `--slds-g-spacing-var-*` | All sides (margin, padding) |
+| `--slds-g-spacing-var-block-*` | Vertical only (top/bottom) |
+| `--slds-g-spacing-var-inline-*` | Horizontal only (left/right) |
+
+Use density-aware hooks for data tables, forms, cards, tabs, and navigation components that need to respond to the user's density preference.
+
+### Examples
+
+```css
+/* Before */
+.card-body { padding: 1rem; }
+.list-item { margin-bottom: 0.5rem; }
+.grid { gap: 1.5rem; }
+
+/* After — hook names come from the linter, not guesswork */
+.card-body { padding: var(--slds-g-spacing-4, 1rem); }
+.list-item { margin-bottom: var(--slds-g-spacing-2, 0.5rem); }
+.grid { gap: var(--slds-g-spacing-5, 1.5rem); }
+
+/* Multi-value shorthand */
+.button { padding: var(--slds-g-spacing-2, 0.5rem) var(--slds-g-spacing-4, 1rem); }
+```
+
+---
+
+## Sizing Hooks
+
+**Prefix:** `--slds-g-sizing-*`
+**Use for:** `width`, `height`, `min-width`, `max-width`, `min-height`, `max-height`
+**Do NOT use for:** `margin`, `padding`, `gap` (use spacing hooks)
+**Scale range: 1–16.** There is no `--slds-g-sizing-17` or higher.
+
+### Examples
+
+```css
+/* Before */
+.icon { width: 32px; height: 32px; }
+
+/* After */
+.icon { width: var(--slds-g-sizing-9, 32px); height: var(--slds-g-sizing-9, 32px); }
+```
+
+---
+
+## Typography Hooks
+
+### Font Scale
+
+**Prefix:** `--slds-g-font-scale-*` (and `--slds-g-font-size-base` for 13px)
+**Use for:** `font-size`
+**Scale range: neg-4 through 10**, plus `base` (0.8125rem/13px). Negative values (`neg-1` to `neg-4`) are for small/caption text. There is no `--slds-g-font-scale-11` or higher.
+
+Density-aware variant: `--slds-g-font-scale-var-*` (also 1–10) — adapts between comfy and compact.
+
+### Font Weight
+
+**Prefix:** `--slds-g-font-weight-*`
+**Use for:** `font-weight`
+**Scale range: 1–7.** Maps to CSS weight values 100–700. There is no `--slds-g-font-weight-8` or higher.
+
+**Weight pairing guidance in SLDS 2:**
+- Display text (large scale) → lighter weight
+- Titles/headings → regular weight
+- Buttons/small body titles → semi-bold weight
+- Inline emphasis within body → bold weight (sparingly)
+
+### Line Height
+
+**Prefix:** `--slds-g-font-lineheight-*`
+**Use for:** `line-height`
+**Scale range: 1–6.** Values range from 1 to 2. There is no `--slds-g-font-lineheight-7` or higher.
+
+### Font Family
+
+| Hook | Use Case |
+|---|---|
+| `--slds-g-font-family` | Default font family |
+| `--slds-g-font-family-base` | Base font family |
+| `--slds-g-font-family-monospace` | Code snippets |
+
+### Content Width
+
+**Prefix:** `--slds-g-sizing-content-*` and `--slds-g-sizing-heading-*`
+**Use for:** `max-width` on text containers (uses `ch` units for readable line lengths)
+**Scale range:** `content` 1–3, `heading` 1–3.
+
+### Typography Examples
+
+```css
+/* Before */
+.title { font-size: 18px; font-weight: bold; line-height: 1.25; }
+.body { font-size: 14px; font-weight: normal; line-height: 1.5; }
+
+/* After — let the linter confirm the correct scale numbers */
+.title {
+  font-size: var(--slds-g-font-scale-4, 18px);
+  font-weight: var(--slds-g-font-weight-4, bold);
+  line-height: var(--slds-g-font-lineheight-2, 1.25);
+}
+.body {
+  font-size: var(--slds-g-font-scale-1, 14px);
+  font-weight: var(--slds-g-font-weight-4, normal);
+  line-height: var(--slds-g-font-lineheight-4, 1.5);
+}
+```
+
+---
+
+## Border Width Hooks
+
+**Prefix:** `--slds-g-sizing-border-*`
+**Use for:** `border-width`, `border`, `border-top`, etc. (the width component)
+**Scale range: 1–4.** Maps to 1px–4px. There is no `--slds-g-sizing-border-5` or higher.
+
+Border widths are NOT density-aware — they stay constant regardless of comfy/compact settings.
+
+**SLDS 2 philosophy:** Use borders sparingly. Prefer spacing or shadows for visual separation. Use borders purposefully for structure, interactivity indication, and state communication.
+
+### Examples
+
+```css
+/* Before */
+.input { border: 1px solid #ccc; }
+
+/* After */
+.input { border: var(--slds-g-sizing-border-1, 1px) solid var(--slds-g-color-border-2, #ccc); }
+```
+
+---
+
+## Border Radius Hooks
+
+**Prefix:** `--slds-g-radius-border-*`
+**Use for:** `border-radius`
+**Scale range: 1–4** plus special values `circle` and `pill`. There is no `--slds-g-radius-border-5` or higher.
+
+Choose radius by **component type**, not by matching px values. The hook resolves to the design-system value; the original value is preserved as fallback only.
+
+| Hook | Components |
+|---|---|
+| `--slds-g-radius-border-1` | Badges, checkboxes |
+| `--slds-g-radius-border-2` | Text inputs, comboboxes, text areas, tooltips |
+| `--slds-g-radius-border-3` | Menus, popovers |
+| `--slds-g-radius-border-4` | Cards, modals, docked composers |
+| `--slds-g-radius-border-circle` | Buttons, button icons, avatars, radios, pills |
+| `--slds-g-radius-border-pill` | Pill-shaped elements |
+
+Border radius hooks are NOT density-aware.
+
+### Examples
+
+```css
+/* Before */
+.card { border-radius: 8px; }
+.button { border-radius: 50%; }
+
+/* After — chosen by component type, not px value */
+.card { border-radius: var(--slds-g-radius-border-4, 8px); }
+.button { border-radius: var(--slds-g-radius-border-circle, 50%); }
+```
+
+---
+
+## Shadow Hooks
+
+**Prefix:** `--slds-g-shadow-*`
+**Use for:** `box-shadow`
+**Scale range: 1–6.** Directional variants (`-block-start-*`, `-block-end-*`, `-inline-start-*`, `-inline-end-*`) use range **1–4**. Focus variants (`-outline-focus-*`, `-outset-focus-*`, `-inset-focus-*`, `-inset-inverse-focus-*`) only have **1**.
+
+Match shadow depth to the element's stacking order — higher shadows for elements visually above others:
+
+| Hook | Components |
+|---|---|
+| `--slds-g-shadow-1` | Page headers, joined tables, filter panels, dropdowns, inline edit, slider handles |
+| `--slds-g-shadow-2` | Menus, docked form footer, docked utility bar, color picker, notifications |
+| `--slds-g-shadow-3` | Panels, docked composer, tooltips, toasts |
+| `--slds-g-shadow-4` | Modals, popovers, App Launcher |
+
+### Directional Shadows
+
+For components positioned against screen edges:
+
+| Hook Pattern | Direction |
+|---|---|
+| `--slds-g-shadow-block-start-*` | Upward |
+| `--slds-g-shadow-block-end-*` | Downward (inherits from base) |
+| `--slds-g-shadow-inline-start-*` | Left |
+| `--slds-g-shadow-inline-end-*` | Right |
+
+### Focus Shadows
+
+| Hook Pattern | Use Case |
+|---|---|
+| `--slds-g-shadow-outline-focus-*` | Simple outline focus |
+| `--slds-g-shadow-outset-focus-*` | Double ring outset focus (white inner, brand outer) |
+| `--slds-g-shadow-inset-focus-*` | Single ring inset focus |
+| `--slds-g-shadow-inset-inverse-focus-*` | Double ring inset focus (brand inner, white outer) |
+
+**SLDS 2 philosophy:** Don't apply shadows to base-level components that sit on a surface without covering other components.
+
+### Examples
+
+```css
+/* Before */
+.modal { box-shadow: 0 4px 8px rgba(0,0,0,0.1); }
+.dropdown { box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
+
+/* After */
+.modal { box-shadow: var(--slds-g-shadow-4, 0 4px 8px rgba(0,0,0,0.1)); }
+.dropdown { box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1)); }
+```
+
+---
+
+## Uplift Decision Tree — Non-Color
+
+When the linter flags a non-color hardcoded value, follow this process:
+
+### Step 1: Run the Linter First
+
+Always run `npx @salesforce-ux/slds-linter@latest lint --fix .` before manual fixes. The linter handles exact value-to-hook matches automatically. Only proceed to manual fixes for values the linter flags but cannot auto-fix.
+
+### Step 2: Density-Aware or Standard?
+
+Only use density-aware hooks if the original value was a variable density token:
+- `--lwc-varSpacingMedium` → `--slds-g-spacing-var-4`
+- `--lwc-spacingMedium` → `--slds-g-spacing-4` (non-variable, use standard hook)
+
+### Step 3: No Exact Match — Should You Replace?
+
+**Shadow:** If a shadow hook is nearly identical (e.g., offset differs by 1px), replace with the closest equivalent. Otherwise, leave as-is.
+
+**Border Radius:** Replace by component type (see table above), not by px value. If the element doesn't match a known component type, leave hardcoded.
+
+**Typography:** If between two scale values, use the closest. If far outside the available range, leave as-is.
+
+**Spacing/Sizing:** If within 10% of a hook value, update to the closest hook. Otherwise leave as-is.
+
+**Hardcoded numerical/structural values:** Never change or remove values like `width: 100%`, `height: 50%`, `max-width: 200px`, `flex: 1`, `height: auto`, `display: none`, `line-height: 1.5`, or `0`. These are layout and structural values, not candidates for hooks. Leave them exactly as they are in the source CSS.
+
+---
+
+## Common Mistakes
+
+1. **Inventing hooks that don't exist** — This is the most common and damaging mistake. Named hooks (`--slds-g-spacing-medium`) and out-of-range numbered hooks do not exist. Always verify with the linter.
+
+2. **Confusing spacing and sizing** — Spacing is for margins/padding/gaps. Sizing is for width/height/dimensions. Using the wrong one makes the value density-unaware or disrupts the grid system.
+
+3. **Replacing or removing hardcoded numerical values** — Never change `width: 100%`, `height: 50%`, `max-width: 200px`, `flex: 1`, `height: auto`, `display: none`, `line-height: 1.5`, or `0`. These are structural/layout values — do not replace them with hooks and do not remove them.
+
+4. **Missing fallback values** — Always include the original value as fallback: `var(--slds-g-spacing-4, 1rem)`. Without fallbacks, the component breaks if the hook is unavailable.
+
+5. **Ignoring density-aware variants** — For data-dense components (tables, forms, lists), use `--slds-g-spacing-var-*` and `--slds-g-font-scale-var-*` so spacing and text adapt to comfy/compact settings.
+
+6. **Using `--slds-c-*` or `--slds-s-*` hooks** — Only `--slds-g-*` (global) hooks are valid for migration. Component and scoped hooks are not for direct use in CSS.
+
+---
+
+## Accessibility Notes
+
+### Touch Targets
+- Minimum 24x24 CSS pixels for pointer inputs (WCAG 2.2 Level AA)
+- Minimum 44x44 for touch inputs (industry standard)
+- Use spacing hooks for padding to achieve target sizes on interactive elements
+
+### Typography Readability
+- Use body-level font scale or larger for primary body text
+- Default base font size (13px) is at the lower limit for comfortable reading
+- Use a line height of 1.5 as default for body text (WCAG 1.4.12)
+- Optimal line length: 45-75 characters (use content width hooks for max-width)
+
+### Focus Visibility
+- Use appropriate border-width hooks for focus state borders
+- Use `--slds-g-shadow-outset-focus-*` for focus rings (double-ring pattern visible on any background)
+- Focus borders must maintain 3:1 minimum contrast with adjacent surfaces
+
+### Border Contrast
+- Borders must maintain 3:1 contrast ratio with adjacent surfaces
+- Use higher-contrast border color hooks for interactive elements
+- Use lower-contrast border color hooks for decorative/non-interactive borders

package/skills/uplifting-components-to-slds2/references/rule-lwc-token-to-slds-hook.md

@@ -0,0 +1,135 @@
+# Rule: LWC Token to SLDS Hook
+
+**Rule ID:** `slds/lwc-token-to-slds-hook`
+**Severity:** Error
+**Scope:** Replaces deprecated `--lwc-*` design tokens with SLDS 2 styling hooks.
+
+---
+
+## What the Linter Does
+
+The linter detects deprecated `--lwc-*` tokens and reports them as **errors**. When there is only one suggestion, `--fix` auto-applies it. When there are multiple suggestions, manual selection is required. Here's real linter output for a multiple-suggestion case:
+
+```
+  2:14  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
+
+✖ 1 SLDS Violation (1 error, 0 warnings)
+```
+
+---
+
+## CRITICAL: Two-Step Workflow
+
+### Step 1: Read Linter Suggestions First (Mandatory)
+
+Before doing anything else, extract the numbered suggestions from the linter output.
+
+**ABSOLUTE RULE: You can ONLY use hooks from the linter's numbered list. You CANNOT use any other hooks.**
+
+- If linter suggests `1. --slds-g-color-surface-2` and `2. --slds-g-color-surface-container-2`
+- You can ONLY choose between those two
+- Using `--slds-g-color-surface-1` is FORBIDDEN (not in the list)
+
+### Step 2: Apply Context-Based Decision (Only After Step 1)
+
+Now that you have the linter's suggestions, use context to choose the best option FROM THE LIST.
+
+---
+
+## Decision Process
+
+### Single Suggestion
+
+If the linter gives ONE option, `--fix` auto-applies it. The result looks like:
+
+```css
+color: var(--slds-g-color-on-surface-2, var(--lwc-colorTextDefault));
+```
+
+### Multiple Suggestions
+
+If the linter gives MULTIPLE options, apply pattern matching to choose.
+
+**Surface vs Container — Core Concept:**
+
+**SURFACE** = The overlay itself — the element that creates a new stacking context (pages, modals, popovers, dialogs)
+- The modal/popover/dialog body background (e.g., `.slds-modal`, `.slds-popover`)
+- Main component backgrounds like `.main-body`, `.page-wrapper`, `.THIS`
+
+**CONTAINER** = Elements that sit on top of a surface (cards, tiles, headers, footers, list items)
+- Parts within an overlay like `.slds-modal__header`, `.slds-modal__footer`
+- Card components like `.card-header`, `.card-footer`, `.tile-body`
+- Repeating items like `.list-item`, `.table-row`
+
+### Pattern Matching
+
+When the linter gives surface vs container options:
+
+**Choose SURFACE when:**
+- `.slds-modal`, `.slds-popover`, `.slds-dialog` — the overlay itself (creates new stacking context)
+- `main-*`, `*-body`, `*-page`, `*-root`, `*-wrapper`, `*-background` — primary/root elements
+- `.THIS` — component root
+
+**Choose CONTAINER when:**
+- `.slds-modal__*`, `.slds-popover__*`, `.slds-dialog__*` — parts within an overlay (header, footer, content)
+- `*-card-*`, `*-tile-*`, `*-item*`, `*-row*` — nested elements within surfaces
+- Sections/panels nested within a card, tile, or item
+
+### Step-by-Step Decision Process
+
+1. **READ LINTER SUGGESTIONS** — Extract the numbered list of hooks
+2. **IDENTIFY CLASS NAME** — Look at the CSS selector being styled
+3. **PATTERN MATCH** — Check surface patterns first, then container patterns
+4. **SELECT FROM LINTER OPTIONS** — Choose the corresponding option
+5. **NEVER INVENT HOOKS** — Only use hooks explicitly listed by the linter
+
+For deeper context investigation (class usage in HTML/JS, component structure), see [color-hooks-decision-guide.md](color-hooks-decision-guide.md).
+
+---
+
+## Replacement Pattern
+
+Always include the original LWC token as fallback:
+
+```css
+property: var(--slds-g-[hook], var(--lwc-[originalToken]));
+```
+
+The nested `var()` fallback ensures compatibility during migration.
+
+---
+
+## Mandatory Rules
+
+**Rule 1: ONLY USE LINTER-SUGGESTED HOOKS**
+- Read the linter output first
+- Only use hooks that appear in the linter's numbered list
+- Cannot invent or use hooks not suggested by the linter
+
+**Rule 2: USE PATTERN RECOGNITION TO CHOOSE FROM LINTER OPTIONS**
+- One option → use that exact option
+- Multiple options → apply pattern matching:
+  - Surface: `.slds-modal`, `.slds-popover`, `.slds-dialog`, `main-*`, `*-body`, `*-page`, `*-root`, `.THIS`
+  - Container: `.slds-modal__*`, `.slds-popover__*`, `.slds-dialog__*`, `*-card-*`, `*-tile-*`, `*-item*`, `*-row*`
+- Apply patterns generically — don't memorize specific examples
+
+**Rule 3: ALWAYS INCLUDE FALLBACK**
+- Format: `var(--slds-g-[hook], var(--lwc-[originalToken]))`
+
+**Rule 4: MINIMAL CHANGES**
+- Only fix actual `slds/lwc-token-to-slds-hook` violations
+- Do not remove any other code or styles
+- Reference line numbers for all modifications
+- If no violations found, return empty list
+
+---
+
+## Validation Checklist
+
+- [ ] All `var(--lwc-*)` tokens have SLDS 2 replacements
+- [ ] Replacements are from the linter's suggested list (not invented)
+- [ ] Original token included as fallback: `var(--slds-g-*, var(--lwc-*))`
+- [ ] Context-appropriate choice when multiple options given

package/skills/uplifting-components-to-slds2/references/rule-no-deprecated-tokens-slds1.md

@@ -0,0 +1,211 @@
+# 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:**
+```
+Consider removing t(colorTextDefault) or replacing it with --slds-g-color-on-surface-3.
+Set the fallback to t(colorTextDefault).
+```
+
+**When no replacement exists:**
+```
+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