mirror of https://github.com/forcedotcom/afv-library.git synced 2026-07-30 03:09:50 +08:00

W-21831072: Add skill: uplifting-components-to-slds2 (#152 )

Add skill: uplifting components to slds2

Made-with: Cursor

2026-03-31 21:03:28 +05:30

7.5 KiB

Raw Blame History

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:

/* 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:

/* 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:

/* 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:

/* 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

7.5 KiB Raw Blame History