mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 03:09:50 +08:00
136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
# 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
|