design-systems-slds2-migrate

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-`	硬编码圆角半径、边框宽度
阴影	`--slds-g-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. **REQUIRED — ALWAYS run first:** npx @salesforce-ux/slds-linter@latest lint --fix . — NEVER skip this step. This 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. **必填——始终首先执行：** npx @salesforce-ux/slds-linter@latest lint --fix . — 绝不能跳过此步骤。该命令将自动处理简单的违规问题。
2. 查看linter输出 -> 识别需要手动修复的剩余问题
3. 按违规类型修复 -> 使用对应规则的参考指南
4. 选择合适的钩子 -> 优先考虑上下文，先检查HTML再做决定
5. 验证 -> 重新运行linter并确认无错误

Step 1: Run SLDS Linter

步骤1：运行SLDS Linter

MANDATORY: This step is NOT optional.

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">Click</button>

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

Step 4: Choose the Right Hook

步骤4：选择合适的钩子

Color hooks require context-based selection. REQUIRED: When any violation involves a color property (
color
,
background-color
,
background
,
fill
,
border-color
), you MUST read color-hooks-decision-guide.md BEFORE choosing a hook. The linter lists possible hooks in no particular order — do NOT pick the first suggestion. The guide contains property-based rules that determine the correct hook.

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.

颜色钩子需要基于上下文选择。必填：当任何违规涉及颜色属性（
color
、
background-color
、
background
、
fill
、
border-color
）时，必须先阅读color-hooks-decision-guide.md再选择钩子。 linter列出的候选钩子无特定顺序 — 不要直接选择第一个建议。该指南包含基于属性的规则，可帮助确定正确的钩子。

非颜色钩子更简单 — 将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等效的令牌
迁移清单 — 完整验证清单