uplifting-components-to-slds2

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Systematically migrate Lightning Web Components from SLDS 1 to SLDS 2 using the SLDS linter and structured guidance for fixing violations across all styling hook categories.

通过SLDS linter和针对所有样式钩子类别的结构化修复指南，系统性地将Lightning Web Components从SLDS 1迁移到SLDS 2。

SLDS 2 Styling Hook Categories

SLDS 2样式钩子类别

Category	Hook Prefix	What It Replaces
Color	`--slds-g-color-*`	Hardcoded colors, `--lwc-color*` tokens
Spacing	`--slds-g-spacing-*`	Hardcoded margins, padding, gaps
Sizing	`--slds-g-sizing-*`	Hardcoded widths, heights, dimensions
Typography	`--slds-g-font-*`	Hardcoded font sizes, weights, line heights
Border/Radius	`--slds-g-radius-border-` , `--slds-g-sizing-border-`	Hardcoded border-radius, border-width
Shadow	`--slds-g-shadow-*`	Hardcoded box-shadow values

Color hooks require the most judgment (context-dependent selection). Non-color hooks are mostly numbered scales with straightforward mappings.

类别	钩子前缀	替代内容
颜色	`--slds-g-color-*`	硬编码颜色、 `--lwc-color*` 令牌
间距	`--slds-g-spacing-*`	硬编码外边距、内边距、间隙
尺寸	`--slds-g-sizing-*`	硬编码宽度、高度、尺寸
排版	`--slds-g-font-*`	硬编码字体大小、字重、行高
边框/圆角	`--slds-g-radius-border-` , `--slds-g-sizing-border-`	硬编码border-radius、border-width
阴影	`--slds-g-shadow-*`	硬编码box-shadow值

颜色钩子需要结合上下文判断（依赖场景选择）。非颜色钩子大多为编号刻度，映射方式简单直接。

Prerequisites

前提条件

Node.js 14.x or higher installed
Access to component CSS and markup files (
```
.html
```
for LWC,
```
.cmp
```
for Aura)
Terminal/command line access to run linter
Git repository for backup (recommended)

已安装Node.js 14.x或更高版本
可访问组件CSS和标记文件（LWC对应
```
.html
```
，Aura对应
```
.cmp
```
）
可通过终端/命令行运行linter
建议使用Git仓库进行备份

Workflow

工作流程

1. Run SLDS linter with auto-fix -> Handles simple violations automatically
2. Review linter output -> Identify remaining manual fixes needed
3. Fix by violation type -> Use per-rule reference guides
4. Choose the right hook -> Context-first, inspect HTML before deciding
5. Validate -> Re-run linter and confirm zero errors

1. 运行带自动修复功能的SLDS linter -> 自动处理简单违规项
2. 查看linter输出 -> 识别需要手动修复的剩余问题
3. 按违规类型修复 -> 使用对应规则的参考指南
4. 选择合适的钩子 -> 优先考虑上下文，先检查HTML再做决定
5. 验证 -> 重新运行linter并确认无错误

Step 1: Run SLDS Linter

步骤1：运行SLDS Linter

bash

npx @salesforce-ux/slds-linter@latest lint --fix .

The linter analyzes all CSS and markup files (

.html

for LWC,

.cmp

for Aura), auto-fixes simple violations, and reports remaining issues requiring manual intervention.

bash

npx @salesforce-ux/slds-linter@latest lint --fix .

linter会分析所有CSS和标记文件（LWC对应

.html

，Aura对应

.cmp

），自动修复简单违规项，并报告需要手动干预的剩余问题。

Step 2: Analyze Linter Output

步骤2：分析Linter输出

The linter reports violations in this format:

componentName.css
  15:3  warning  Overriding slds-button isn't supported. To differentiate SLDS and
                 custom classes, create a CSS class in your namespace.
                 Examples: myapp-input, myapp-button.                        slds/no-slds-class-overrides

  23:5  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

  30:8  warning  Consider replacing the #ffffff static value with an SLDS 2 styling hook
                 that has a similar value:
                 1. --slds-g-color-surface-1
                 2. --slds-g-color-surface-container-1
                 3. --slds-g-color-on-accent-1
                 4. --slds-g-color-on-accent-2
                 5. --slds-g-color-on-accent-3                              slds/no-hardcoded-values-slds2

  31:15  error   Consider removing t(fontSizeMedium) or replacing it with
                 var(--slds-g-font-size-base, var(--lwc-fontSizeMedium, 0.8125rem)).
                 Set the fallback to t(fontSizeMedium). For more info, see
                 Styling Hooks on lightningdesignsystem.com.               slds/no-deprecated-tokens-slds1

Four violation types, each with its own fix approach (see Step 3).

Important: The linter flags all hardcoded values. Fix color, spacing, sizing, typography, border, and shadow values — but skip layout values (

100%

auto

inherit

none

). See rule-no-hardcoded-values.md for the full fix-vs-skip triage table.

linter会以如下格式报告违规项：

componentName.css
  15:3  warning  Overriding slds-button isn't supported. To differentiate SLDS and
                 custom classes, create a CSS class in your namespace.
                 Examples: myapp-input, myapp-button.                        slds/no-slds-class-overrides

  23:5  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

  30:8  warning  Consider replacing the #ffffff static value with an SLDS 2 styling hook
                 that has a similar value:
                 1. --slds-g-color-surface-1
                 2. --slds-g-color-surface-container-1
                 3. --slds-g-color-on-accent-1
                 4. --slds-g-color-on-accent-2
                 5. --slds-g-color-on-accent-3                              slds/no-hardcoded-values-slds2

  31:15  error   Consider removing t(fontSizeMedium) or replacing it with
                 var(--slds-g-font-size-base, var(--lwc-fontSizeMedium, 0.8125rem)).
                 Set the fallback to t(fontSizeMedium). For more info, see
                 Styling Hooks on lightningdesignsystem.com.               slds/no-deprecated-tokens-slds1

共有四种违规类型，每种类型对应不同的修复方法（见步骤3）。

重要提示： linter会标记所有硬编码值。需修复颜色、间距、尺寸、排版、边框和阴影值，但跳过布局值（

100%

、

auto

、

inherit

、

none

）。完整的修复/跳过分类表请参考rule-no-hardcoded-values.md。

Step 3: Fix Violations by Type

步骤3：按违规类型修复

Each rule has a dedicated reference guide with full examples and decision logic:

Violation Rule	Quick Summary	Reference
`slds/no-hardcoded-values-slds2`	Replace hardcoded values with SLDS hook + original as fallback	rule-no-hardcoded-values.md
`slds/lwc-token-to-slds-hook`	Replace `--lwc-*` tokens with SLDS 2 hook, keep LWC token as fallback	rule-lwc-token-to-slds-hook.md
`slds/no-slds-class-overrides`	Create component-prefixed class, add to markup alongside SLDS class	rule-no-slds-class-overrides.md
`slds/no-deprecated-tokens-slds1`	Replace legacy `t()` / `token()` syntax with SLDS 2 hook + LWC fallback	rule-no-deprecated-tokens-slds1.md

Always include fallback values —

var(--slds-g-hook, originalValue)

where

originalValue

is the exact original from the source CSS.

每条规则都有专门的参考指南，包含完整示例和决策逻辑：

违规规则	快速概述	参考文档
`slds/no-hardcoded-values-slds2`	用SLDS钩子替换硬编码值，并保留原值作为回退	rule-no-hardcoded-values.md
`slds/lwc-token-to-slds-hook`	用SLDS 2钩子替换 `--lwc-*` 令牌，保留LWC令牌作为回退	rule-lwc-token-to-slds-hook.md
`slds/no-slds-class-overrides`	创建组件前缀的类，添加到标记文件中与SLDS类共存	rule-no-slds-class-overrides.md
`slds/no-deprecated-tokens-slds1`	用SLDS 2钩子+LWC回退替换旧版 `t()` / `token()` 语法	rule-no-deprecated-tokens-slds1.md

务必包含回退值 —— 使用

var(--slds-g-hook, originalValue)

格式，其中

originalValue

是源CSS中的原始值。

Class Override Quick Reference

类覆盖快速参考

Class overrides require changes to both CSS and markup (

.html

.cmp

). This is the most commonly missed step:

CSS: Rename

.slds-*

selector →

{componentName}-{sldsElementPart}

(camelCase)

Markup: Add the new class alongside the SLDS class — never remove the SLDS class

css

/* Before */ .slds-button { border-radius: 8px; }
/* After */  .myComponent-button { border-radius: 8px; }

html

<!-- Markup: both classes --> <button class="slds-button myComponent-button">Click</button>

See rule-no-slds-class-overrides.md for descendant selectors, multi-class selectors, and naming conventions.

类覆盖需要同时修改CSS和标记文件（

.html

或

.cmp

）。这是最容易遗漏的步骤：

CSS： 将
```
.slds-*
```
选择器重命名为
```
{componentName}-{sldsElementPart}
```
（驼峰命名）
标记： 将新类添加到SLDS类旁边——切勿移除SLDS类

css

/* 之前 */ .slds-button { border-radius: 8px; }
/* 之后 */  .myComponent-button { border-radius: 8px; }

html

<!-- 标记：同时保留两个类 --> <button class="slds-button myComponent-button">点击</button>

后代选择器、多类选择器和命名规范请参考rule-no-slds-class-overrides.md。

Step 4: Choose the Right Hook

步骤4：选择合适的钩子

Color hooks require context-based selection — inspect the HTML to determine the element's role before choosing a hook family. See color-hooks-decision-guide.md for decision trees, all 5 hook families, and background-foreground pairing rules.

Non-color hooks are simpler — match the CSS value to the numbered scale. See non-color-hooks-decision-guide.md for value-to-hook lookup tables covering spacing, sizing, typography, borders, radius, and shadows.

颜色钩子需要基于上下文选择——选择钩子系列前，先检查HTML以确定元素的角色。决策树、所有5个钩子系列以及背景-前景配对规则请参考**color-hooks-decision-guide.md**。

非颜色钩子更简单——将CSS值与编号刻度匹配。间距、尺寸、排版、边框、圆角和阴影的值到钩子的对照表请参考**non-color-hooks-decision-guide.md**。

Step 5: Validate and Verify

步骤5：验证与确认

Linter feedback loop — repeat until zero errors:

1. npx @salesforce-ux/slds-linter@latest lint .
2. Review errors -> fix by type (Step 3)
3. Re-run linter
4. Repeat until output shows: 0 errors

linter反馈循环——重复直到无错误：

1. npx @salesforce-ux/slds-linter@latest lint .
2. 查看错误 -> 按类型修复（步骤3）
3. 重新运行linter
4. 重复直到输出显示：0 errors

Validation

验证清单

No
```
.slds-*
```
classes in CSS selectors
No
```
var(--lwc-*)
```
tokens without SLDS 2 replacements
All hooks include fallback values
Background/foreground color hooks from same family
Original SLDS classes preserved in HTML
Spacing uses numbered hooks (not named like
```
spacing-medium
```
)
Typography uses numbered hooks (not named like
```
font-weight-bold
```
)
Component renders correctly in light/dark mode and density settings

See migration-checklist.md for the full validation checklist.

CSS选择器中无
```
.slds-*
```
类
无未替换为SLDS 2钩子的
```
var(--lwc-*)
```
令牌
所有钩子均包含回退值
背景/前景颜色钩子来自同一系列
HTML中保留原始SLDS类
间距使用编号钩子（而非
```
spacing-medium
```
这类命名钩子）
排版使用编号钩子（而非
```
font-weight-bold
```
这类命名钩子）
组件在亮/暗模式和密度设置下渲染正常

完整验证清单请参考**migration-checklist.md**。

Output

输出结果

Return the fully migrated CSS (and updated HTML markup where class overrides were fixed) with zero SLDS linter violations. All styling hooks must include fallback values preserving the original CSS values.

返回完全迁移后的CSS（以及修复类覆盖时更新的HTML标记），确保无SLDS linter违规项。所有样式钩子必须包含保留原始CSS值的回退值。

Advanced Patterns

高级模式

Color-Mix for Transparency

用于透明度的color-mix

When a hardcoded value uses

rgba()

or transparency, use

color-mix()

with the SLDS hook to preserve opacity:

css

/* Before */
border-color: rgba(186, 5, 23, 0.7);

/* After — use oklab color space for perceptual consistency */
border-color: color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);

Formula: To achieve X% opacity, use

(100 - X)%

transparent in

color-mix

70% opacity →
```
transparent 30%
```
50% opacity →
```
transparent 50%
```

Use opaque

rgb()

as fallback (not

rgba()

) —

color-mix

handles the transparency.

当硬编码值使用

rgba()

或透明度时，使用

color-mix()

结合SLDS钩子来保留透明度：

css

/* 之前 */
border-color: rgba(186, 5, 23, 0.7);

/* 之后 — 使用oklab色彩空间保证感知一致性 */
border-color: color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);

公式： 要实现X%不透明度，在

color-mix

中使用

transparent (100 - X)%

。

70%不透明度 →
```
transparent 30%
```
50%不透明度 →
```
transparent 50%
```

使用不透明的

rgb()

作为回退（而非

rgba()

）——

color-mix

会处理透明度。

calc() Expressions with Tokens

带令牌的calc()表达式

When migrating

t('calc(...)')

calc()

with deprecated tokens:

css

/* Before — Aura t() with calc */
height: t('calc(' + lineHeightButton + ' + 2px)');

/* After — if calc is still needed */
height: calc(var(--lwc-lineHeightButton) + 2px);

/* After — if calc was unnecessary, simplify */
height: var(--lwc-lineHeightButton);

For

calc()

with

--lwc-*

tokens being replaced:

css

/* Before */
padding: calc(var(--lwc-spacingMedium) + 4px);

/* After */
padding: calc(var(--slds-g-spacing-4, var(--lwc-spacingMedium)) + 4px);

Tip: Often the

calc()

is unnecessary and can be simplified. Check if the result matches an existing hook value.

迁移

t('calc(...)')

或包含已弃用令牌的

calc()

时：

css

/* 之前 — Aura的t()结合calc */
height: t('calc(' + lineHeightButton + ' + 2px)');

/* 之后 — 如果仍需要calc */
height: calc(var(--lwc-lineHeightButton) + 2px);

/* 之后 — 如果calc不必要，简化 */
height: var(--lwc-lineHeightButton);

对于包含待替换

--lwc-*

令牌的

calc()

：

css

/* 之前 */
padding: calc(var(--lwc-spacingMedium) + 4px);

/* 之后 */
padding: calc(var(--slds-g-spacing-4, var(--lwc-spacingMedium)) + 4px);

提示： 通常

calc()

是不必要的，可以简化。检查结果是否与现有钩子值匹配。

Key Constraints

关键约束

Never invent hook names — only use hooks documented in the SLDS design system
Always include fallback values — the fallback must be the exact original value from the source CSS
Never change hardcoded numerical values — values like
```
100%
```
,
```
50%
```
,
```
200px
```
,
```
1.5
```
,
```
auto
```
,
```
0
```
,
```
inherit
```
,
```
none
```
,
```
flex: 1
```
are structural/layout values. Do not replace them with hooks and do not remove them — they are not styling hook candidates
No exact match? Leave as-is — if a hardcoded value doesn't closely correspond to any hook's rendered value, leave it unchanged rather than force-fitting
Match hook number to original value intensity — don't default to
```
-1
```
. Pick the variant closest to the original. See color-hooks-decision-guide.md
Only numbered scales — named hooks like
```
spacing-medium
```
,
```
font-weight-bold
```
,
```
radius-large
```
do NOT exist

切勿自创钩子名称 —— 仅使用SLDS设计系统中记录的钩子
务必包含回退值 —— 回退值必须与源CSS中的原始值完全一致
切勿修改硬编码数值 —— 诸如
```
100%
```
、
```
50%
```
、
```
200px
```
、
```
1.5
```
、
```
auto
```
、
```
0
```
、
```
inherit
```
、
```
none
```
、
```
flex: 1
```
这类值属于结构/布局值。不要用钩子替换它们，也不要删除——它们不属于样式钩子的替换范畴
无精确匹配则保留原值 —— 如果硬编码值与任何钩子的渲染值都不接近，请勿强行替换，保留原值即可
钩子编号与原始值强度匹配 —— 不要默认使用
```
-1
```
。选择最接近原始值的变体。请参考color-hooks-decision-guide.md
仅使用编号刻度 —— 不存在
```
spacing-medium
```
、
```
font-weight-bold
```
、
```
radius-large
```
这类命名钩子

Troubleshooting

故障排除

Issue	Solution
Linter suggests 2+ color hook options	Inspect HTML context to determine element's semantic role — see color-hooks-decision-guide.md
Visual appearance changed after migration	Verify fallback values match originals; check surface vs container family
No hook available for hardcoded value	Leave unchanged; do not invent custom hook names
Linter says "Remove the static value" for `100%` , `auto` , etc.	Leave unchanged — these are layout values. Removing them breaks rendering.
CSS class naming errors	Use exact camelCase component name: `myComponent-button` , not `MyComponent-button`
Spacing/sizing doesn't match	Check value-to-hook mapping in non-color-hooks-decision-guide.md; verify spacing vs sizing usage
Named hook not working (e.g., `spacing-medium` )	Named hooks don't exist — use numbered scale: `spacing-4` for 16px, `font-weight-7` for inline bold emphasis (not headings)
Component looks different in compact density	Use density-aware hooks ( `--slds-g-spacing-var-*` ) for components that adapt to density

问题	解决方案
linter提供2+个颜色钩子选项	检查HTML上下文以确定元素的语义角色——请参考color-hooks-decision-guide.md
迁移后视觉外观发生变化	验证回退值是否与原值匹配；检查surface与container系列是否正确
硬编码值无对应钩子	保留原值；切勿自创自定义钩子名称
linter提示“移除静态值”针对 `100%` 、 `auto` 等	保留原值——这些是布局值，移除会破坏渲染
CSS类命名错误	使用精确的驼峰式组件名称： `myComponent-button` ，而非 `MyComponent-button`
间距/尺寸不匹配	检查non-color-hooks-decision-guide.md中的值到钩子映射表；验证间距与尺寸的使用是否正确
命名钩子无法生效（如 `spacing-medium` ）	不存在命名钩子——使用编号刻度： `spacing-4` 对应16px， `font-weight-7` 对应行内加粗强调（非标题）
组件在紧凑密度下显示异常	对适配密度的组件使用密度感知钩子（ `--slds-g-spacing-var-*` ）

References

参考文档

Color Hooks Decision Guide — All 5 color hook families, decision trees, background-foreground pairing, palette accessibility
Non-Color Hooks Decision Guide — Spacing, sizing, typography, borders, radius, and shadow hooks with lookup tables
Rule: No Hardcoded Values — Linter behavior, fix-vs-skip triage, replacement pattern, utility class workflow
Rule: LWC Token to SLDS Hook — Deprecated
```
--lwc-*
```
token replacement patterns
Rule: No Deprecated Tokens SLDS1 — Legacy
```
t()
```
/
```
token()
```
Aura syntax replacement patterns
Rule: No SLDS Class Overrides — Class renaming and HTML updates
Migration Examples — Before/after examples by scenario and complexity
Common Patterns — Classes never to override, deprecated SLDS 2 classes, palette fallbacks, tokens with no SLDS 2 equivalent
Migration Checklist — Full validation checklist

颜色钩子决策指南 —— 所有5个颜色钩子系列、决策树、背景-前景配对、调色板可访问性
非颜色钩子决策指南 —— 间距、尺寸、排版、边框、圆角和阴影钩子的对照表
规则：无硬编码值 —— Linter行为、修复/跳过分类、替换模式、工具类工作流程
规则：LWC令牌转SLDS钩子 —— 已弃用
```
--lwc-*
```
令牌的替换模式
规则：无SLDS 1已弃用令牌 —— 旧版
```
t()
```
/
```
token()
```
Aura语法的替换模式
规则：无SLDS类覆盖 —— 类重命名和HTML更新
迁移示例 —— 按场景和复杂度划分的前后对比示例
常见模式 —— 切勿覆盖的类、已弃用的SLDS 2类、调色板回退、无SLDS 2等效项的令牌
迁移清单 —— 完整验证清单