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

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:

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.

---

Replacement Pattern

Always include the original LWC token as fallback:

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