@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,333 +0,0 @@
-# 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

@@ -1,135 +0,0 @@
-# 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

@@ -1,211 +0,0 @@
-# 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