问题：升级后 Salesforce UI 样式损坏
您刚刚更新了 Salesforce 组织或启动了一个新项目，突然发现精心设计的 Lightning Web Components (LWC) 看起来不一样了。按钮颜色错误、间距不一致、排版与设计系统不匹配。检查控制台会看到关于弃用令牌、硬编码值和类覆盖的警告。这是 Salesforce 将设计系统从 SLDS 1 更新到 SLDS 2 时的常见场景，而您现有的组件尚未迁移。
核心问题是 SLDS 2 引入了一套新的样式钩子系统——CSS 自定义属性，用于替代硬编码值和弃用的令牌。如果您的组件仍使用旧模式，如 --lwc-colorBackground、t(fontSizeMedium) 或直接覆盖 SLDS 类，它们将无法正确适应 SLDS 2 的主题、辅助功能和密度设置。手动迁移既繁琐又容易出错：您必须识别每个违规，从数百个选项中选择正确的替换钩子，并确保保留向后兼容的回退值。
这不仅仅是外观问题。损坏的样式可能影响用户体验、辅助功能合规性，甚至在布局偏移时影响功能。对于维护包含数百个组件的大型 Salesforce 应用的团队来说，系统化的方法对于避免回归错误和确保 UI 一致性至关重要。
好的解决方案应该改变什么
一个合适的迁移工具或技能应该做的不仅仅是发现问题——它应该帮助高效地解决问题。以下是您希望解决方案具备的特点：
- 自动检测：扫描所有 CSS 和标记文件，识别违反 SLDS 2 标准的违规。
- 引导式修复：为每种违规类型提供清晰、上下文感知的建议，而不仅仅是通用建议。
- 保留功能：确保迁移后的组件外观和行为与之前相同，并具有适当的回退值。
- 支持所有钩子类别：处理颜色、间距、尺寸、排版、边框、圆角和阴影——而不仅仅是一两个。
- 集成到工作流：与您现有的开发设置配合工作，无论是 VS Code、CI/CD 管道还是命令行工具。
目标是将手动工作从几天减少到几小时，最大限度地降低引入新错误的风险，并让开发人员对其组件符合 SLDS 2 标准充满信心。
介绍 SLDS 2 迁移技能
一个值得检查的实用选项是 design-systems-slds2-migrate 技能。此技能专门用于通过利用官方 SLDS linter 并提供修复违规的结构化指导，将 LWC 组件从 SLDS 1 迁移到 SLDS 2。
它不是自动重写代码的魔法棒。相反，它提供了一个系统化的工作流程：运行 linter、分析违规、按类别应用修复、选择正确的钩子并验证结果。该技能涵盖所有样式钩子类别，并为每种违规类型提供参考指南，帮助开发人员做出明智的决策，而不是猜测。
技能工作原理：分步概述
该技能遵循清晰、可重复的工作流程。以下是简化分解：
第 1 步：运行 SLDS Linter
第一步是强制性的：在组件文件上运行 SLDS linter。此工具分析 .html 和 .css 文件，自动修复简单的违规，并报告需要手动处理的问题。
npx @salesforce-ux/slds-linter@latest lint --fix .
Linter 输出将显示警告和错误，包含特定行号和规则名称，如 slds/no-hardcoded-values-slds2 或 slds/lwc-token-to-slds-hook。
第 2 步：按类型分析违规
Linter 将违规分为四种主要类型：
- 硬编码值：静态 CSS 值，如
#ffffff或16px，应使用 SLDS 钩子。 - 弃用的令牌：旧的
--lwc-*令牌或t()语法需要替换。 - 类覆盖：在 CSS 中直接覆盖
.slds-*类。 - 令牌迁移：遗留令牌使用需要带回退的钩子替换。
每种类型都有不同的修复方法。例如，硬编码值需要替换为钩子加上原始值作为回退：var(--slds-g-color-surface-1, #ffffff)。
第 3 步：使用上下文感知指导修复违规
这是该技能增加价值的地方。它不是让您猜测使用哪个钩子，而是为每条规则提供参考指南。对于需要最多判断的颜色钩子——它包含基于 CSS 属性和上下文的决策指南。对于间距或排版等非颜色钩子，它提供将值映射到编号比例的查找表。
一个常见的陷阱是选择 linter 输出中的第一个钩子建议。该技能强调您必须先阅读颜色钩子决策指南，因为正确的钩子取决于您是设置背景、文本还是边框颜色。
第 4 步：仔细处理类覆盖
覆盖 SLDS 类是一个常见问题。该技能解释说，您需要同时更改 CSS 和标记：
- 在 CSS 中，将选择器从
.slds-button重命名为组件前缀类，如.myComponent-button。 - 在 HTML 中，将新类与原始 SLDS 类一起添加——永远不要移除 SLDS 类。
这确保您的自定义样式不会干扰 SLDS 更新并保持辅助功能。
第 5 步：验证和迭代
完成修复后，重新运行 linter 直到错误为零。该技能包含一个验证检查清单，以确保所有钩子都有回退值，没有遗留的弃用令牌，并且组件在不同主题和密度设置下正确渲染。
何时考虑此技能
如果出现以下情况，此技能可能值得检查：
- 您维护的 Salesforce LWC 组件使用 SLDS 1 样式模式。
- 您遇到过关于弃用令牌或硬编码值的 linter 警告。
- 您的团队计划进行 SLDS 2 提升，并希望采用结构化方法。
- 您需要确保大型代码库中多个组件的一致性。
它特别适合熟悉 CSS 和命令行工具但希望避免识别和修复每个违规的繁琐手动工作的前端开发人员或 Salesforce 管理员。
能力边界和最佳用例
该技能专门针对 LWC 组件的 SLDS 1 到 SLDS 2 迁移。它不涵盖：
- Aura 组件迁移（尽管它可以分析
.cmp文件，但指导以 LWC 为中心）。 - 与样式无关的 JavaScript 逻辑更改。
- SLDS 之外的自定义设计系统。
最佳用例包括：
- 增量迁移：在持续开发过程中逐个迁移组件。
- 代码库审计：在主要发布前识别所有 SLDS 1 违规。
- 团队入职：帮助新开发人员理解 SLDS 2 模式并避免常见错误。
何时不使用它
如果出现以下情况，您可能不需要此技能：
- 您的组件已完全符合 SLDS 2 标准。
- 您使用不同的设计系统或自定义 CSS 框架。
- 您更喜欢在没有工具辅助的情况下手动处理迁移。
- 您的项目不使用 Lightning Web Components。
设置上下文和安全信号
该技能要求：
- Node.js 14.x 或更高版本。
- 访问您的组件文件（CSS 和标记）。
- 运行 linter 的终端。
- 用于备份的 Git 存储库（推荐用于跟踪更改）。
从安全角度来看，该技能使用官方 Salesforce SLDS linter，这是一个受信任的工具。迁移过程将原始值保留为回退，降低了破坏性更改的风险。但是，迁移后始终要彻底测试组件，尤其是在不同主题和辅助功能模式下。
存储库信号
该技能是 forcedotcom 的 sf-skills 存储库 的一部分，该存储库有 780 个星标和 285 个分支。它采用 Apache-2.0 许可证，表明它开放使用和修改。该存储库似乎积极维护，主题与 Salesforce 开发相关。
最终想法
从 SLDS 1 迁移到 SLDS 2 是保持 Salesforce UI 现代化和可访问性的必要步骤。虽然涉及仔细的工作，但像 design-systems-slds2-migrate 技能 这样的工具可以提供结构并减轻负担。关键是系统化地处理：运行 linter、按类别修复违规、明智地选择钩子并彻底验证。始终备份代码并在沙盒中测试，然后再将更改应用到生产环境。