design-systems-slds2-migrate

目标

使用 SLDS linter 和结构化指导，系统地将 Lightning Web Components 从 SLDS 1 迁移到 SLDS 2，并修复所有样式钩子类别中的违规项。

SLDS 2 样式钩子类别

类别	钩子前缀	替代内容
颜色	--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-*	硬编码 box-shadow 值

颜色钩子最需要根据具体情境进行判断。非颜色钩子大多采用编号刻度，映射方式较为直接。

前置条件

• 已安装 Node.js 14.x 或更高版本
• 可访问组件 CSS 和标记文件（LWC 使用 .html，Aura 使用 .cmp）
• 可访问终端／命令行以运行 linter
• 用于备份的 Git 仓库（推荐）

---

工作流

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：运行 SLDS Linter

必须执行：此步骤不可跳过。

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

linter 会分析所有 CSS 和标记文件（LWC 使用 .html，Aura 使用 .cmp），自动修复简单的违规项，并报告需要手动处理的剩余问题。

步骤 2：分析 Linter 输出

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、0、inherit、none）。完整的修复与跳过分类表请参见 rule-no-hardcoded-values.md。

步骤 3：按类型修复违规项

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

违规规则	快速说明	参考资料
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 中的原始值，且完全一致。

类覆盖快速参考

类覆盖需要同时修改 CSS 和标记（.html 或 .cmp）。这是最常被遗漏的一步：

1. CSS： 将 .slds-* 选择器重命名为 {componentName}-{sldsElementPart}（驼峰命名）
2. 标记： 将新类与 SLDS 类一同添加，绝不要移除 SLDS 类

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

 <button class="slds-button myComponent-button">Click</button>

有关后代选择器、多类选择器和命名约定，请参见 rule-no-slds-class-overrides.md。

第 4 步：选择正确的 Hook

颜色 Hook 需要根据上下文选择。必须遵循：只要任何违规涉及颜色属性（color、background-color、background、fill、border-color），就必须先阅读 color-hooks-decision-guide.md，然后再选择 Hook。 Linter 列出的可能 Hook 没有特定顺序，切勿选择第一条建议。该指南包含基于属性的规则，用于确定正确的 Hook。

非颜色 Hook 更简单：将 CSS 值与编号刻度匹配。请参阅 non-color-hooks-decision-guide.md，其中提供了涵盖间距、尺寸、排版、边框、圆角和阴影的值到 Hook 对照表。

第 5 步：验证与确认

Linter 反馈循环——重复执行，直到错误数为零：

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

---

验证

• CSS 选择器中没有 .slds-* 类
• 所有 var(--lwc-*) 令牌都已替换为 SLDS 2 对应项
• 所有 Hook 都包含回退值
• 背景色和前景色 Hook 来自同一系列
• HTML 中保留了原始 SLDS 类
• 间距使用编号 Hook（而非 spacing-medium 这类命名 Hook）
• 排版使用编号 Hook（而非 font-weight-bold 这类命名 Hook）
• 组件在浅色／深色模式和密度设置下均可正确呈现

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

---

输出

返回完全迁移后的 CSS（以及修正了类覆盖的更新后 HTML 标记），且不包含任何 SLDS Linter 违规。所有样式 Hook 都必须包含保留原始 CSS 值的回退值。

---

高级模式

使用 Color-Mix 实现透明效果

当硬编码值使用 rgba() 或透明度时，请使用带 SLDS Hook 的 color-mix() 来保留透明度：

/* 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%);

公式： 要实现 X% 的不透明度，请在 color-mix 中使用 (100 - X)% 的透明部分。

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

回退值使用不透明的 rgb()（而非 rgba()）——透明度由 color-mix 处理。

使用令牌的 calc() 表达式

迁移 t('calc(...)') 或包含已弃用令牌的 calc() 时：

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

替换包含 --lwc-* 令牌的 calc() 时：

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

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

提示： calc() 通常并非必需，可以简化。检查计算结果是否与现有 Hook 值一致。

---

关键约束

• 切勿臆造 Hook 名称——只能使用 SLDS 设计系统中记录的 Hook
• 始终包含回退值——回退值必须与源 CSS 中的原始值完全一致
• 切勿更改硬编码数值——100%、50%、200px、1.5、auto、0、inherit、none、flex: 1 等值属于结构／布局值。不要将其替换为 Hook，也不要移除；它们不是样式 Hook 的候选值
• 没有精确匹配？保持原样——如果硬编码值与任何 Hook 的渲染值都不接近，就保持不变，不要勉强套用
• 让 Hook 编号与原始值的强度相匹配——不要默认使用 -1。选择最接近原始值的变体。请参阅 color-hooks-decision-guide.md
• 仅使用编号刻度——spacing-medium、font-weight-bold、radius-large 等命名 Hook 并不存在

故障排除

问题	解决方案
Linter 建议使用 2 个或更多颜色钩子选项	检查 HTML 上下文，确定元素的语义角色——参见 color-hooks-decision-guide.md
迁移后视觉外观发生变化	验证回退值是否与原值一致；检查属于表面还是容器系列
硬编码值没有可用的钩子	保持不变；不要杜撰自定义钩子名称
Linter 对 100%、auto 等值提示“Remove the static value”	保持不变——这些是布局值。移除它们会导致渲染异常。
CSS 类命名错误	使用准确的 camelCase 组件名称：myComponent-button，而不是 MyComponent-button
间距／尺寸不匹配	查看 non-color-hooks-decision-guide.md 中的值到钩子映射；确认间距与尺寸的使用方式
命名钩子不起作用（例如 spacing-medium）	命名钩子并不存在——使用编号刻度：16px 对应 spacing-4，行内粗体强调（非标题）使用 font-weight-7
组件在紧凑密度下的外观不同	对会随密度调整的组件使用适配密度的钩子（--slds-g-spacing-var-*）

---

参考资料

• 颜色钩子决策指南 — 全部 5 个颜色钩子系列、决策树、背景与前景配对、调色板可访问性
• 非颜色钩子决策指南 — 间距、尺寸、排版、边框、圆角和阴影钩子及其查找表
• 规则：禁止硬编码值 — Linter 行为、修复与跳过的分流、替换模式、工具类工作流
• 规则：LWC 令牌转 SLDS 钩子 — 已弃用的 --lwc-* 令牌替换模式
• 规则：禁止使用已弃用的 SLDS1 令牌 — 旧版 t()／token() Aura 语法的替换模式
• 规则：禁止覆盖 SLDS 类 — 类重命名和 HTML 更新
• 迁移示例 — 按场景和复杂程度分类的迁移前后示例
• 常见模式 — 绝不可覆盖的类、已弃用的 SLDS 2 类、调色板回退，以及没有对应 SLDS 2 项的令牌
• 迁移检查清单 — 完整的验证检查清单