Salesforce Lightning Design System 2 开发者指南

探索 Salesforce Lightning Design System 2（01 Explore SLDS 2）

本单元从开发者视角探索 SLDS 2：定义它是什么、介绍开发者的两大收益、解释架构与能力，然后聚焦你在工作中最常使用的两样东西——全局样式钩子和组件。

完成本单元后，你将能够：

描述 SLDS 2 是什么；
定义它带给开发者的两大关键收益；
解释样式钩子和组件是什么。

开始前：本模块面向开发者。如果你是管理员，请看 SLDS 2 for Admins 模块。建议先完成 Salesforce Cosmos Theme: Quick Look 模块。

什么是 SLDS 2？（一）：概览（What Is SLDS 2? (1): Overview）

Salesforce Lightning Design System 2（SLDS 2） 是 Lightning 平台产品最新的设计系统，也是 Salesforce agentic 设计系统的基础。

它的目标是帮助你创建一致、可访问、可扩展的用户界面，贯穿你的应用和平台。对管理员、开发者和设计师，SLDS 2 提供工具、组件和指南，让应用匹配 Salesforce 的设计原则和视觉语言。

SLDS 2 面向未来，旨在把你的用户界面体验带入 agentic 时代乃至更远。它不只是视觉刷新，而是一套完整的设计系统。

什么是 SLDS 2？（二）：关键特性（What Is SLDS 2? (2): Key Features）

SLDS 2 的关键特性包括：

Lightning 组件——构建 UI 的积木；
语义化样式钩子框架——灵活的主题定制；
内置 Salesforce Cosmos 主题——现代默认视觉；
工具套件——SLDS Linter 和 SLDS Validator。

这些共同带来增强、灵活的架构和更新的支持工具。对开发者而言，价值在于增强的架构加上让组件构建和验证更轻松的更新工具。

开发者的收益（Benefits for Developers）

SLDS 2 给你更多pro-code、细粒度的控制力，作用于组织的 UI。两大关键收益：

轻松评估代码质量——SLDS Linter 按 SLDS 2 规则分析代码并提出改进建议，还能自动修复并跨整个仓库批量应用更改。Salesforce 推荐使用 SLDS Linter；
更快编码——得益于基于全局样式钩子的灵活、面向 agentic 的架构。

SLDS Linter 是最新的代码分析工具，分析代码是否符合 SLDS 2 规则、提供改进建议、自动修复并在仓库中批量应用。这两点对开发效率的提升是实实在在的。

架构与能力（一）：新 CSS 框架（Architecture (1): The New CSS Framework）

SLDS 2 基于一个新的 CSS 框架，用样式钩子把结构与主题分离。架构包含：

Lightning Base Components——首选的开箱即用方案；
与 SLDS 1 向后兼容——两者共享公共 CSS 和样式钩子，你的组件蓝图继续可用（但推荐升级到 Lightning Base Components）；
面向 agent-first 体验的下一代组件——Agentforce 就是当前与下一代组件的混合，并带描述性元数据增强。用 SLDS 2 定制 agent UI 的样式和性能。

样式钩子是新框架的核心：结构（组件做什么）与主题（组件长什么样）分离，让你获得真正的定制和主题化能力。

架构与能力（二）：Pro-Code 控制（Architecture (2): Pro-Code Control）

Pro-code 能力：

现代 Web 标准——用 CSS 自定义属性和直接编写，而不是 Aura 和 SaSS；
SLDS 2 架构——把结构与视觉样式解耦，优先 CSS 自定义属性而非设计令牌；
开发者工具——新规则集、内联指导、批量报告，更轻松地创建、验证、迁移组件；
高级 Figma kits——预置组件、刷新样式、1:1 代码映射。

SLDS 2 全面拥抱现代 Web 标准，把 CSS 自定义属性作为视觉语言，减少对设计令牌的依赖。全局样式钩子建立在一个灵活的样式框架上，用来改变 UI 外观。

架构与能力（三）：No-Code 设计（Architecture (3): No-Code Design）

No-code 能力：

Themes and Branding（主题与品牌）——预置主题 + 在扩展色板上构建自有主题，提供更细粒度的定制；
Salesforce Cosmos 主题——现代直观的视觉设计，圆形图案、刷新配色、改进排版；
用户个性化——密度控制和偏好设置，让用户有更多方式个性化 UI。

pro-code 与 no-code 结合，覆盖了整个能力谱系。接下来聚焦两个对开发工作最关键的能力：样式钩子和下一代组件。

全局样式钩子（一）：它们是什么（Global Styling Hooks (1): What They Are）

全局样式钩子控制组件的颜色、间距、字体、边框等样式。用样式钩子把组件样式改成你的品牌、并规模化主题更新。如果你熟悉 SLDS 1，样式钩子就是 SLDS 1 设计令牌的演进。

样式钩子使用 CSS 自定义属性，让定制组件样式、表达品牌变得容易，尤其配合 Lightning Web Components（LWC）和 Shadow DOM 时。SLDS 的官方样式钩子命名空间是 --slds。

示例：把硬编码的背景色和边框圆角替换为使用相同值的全局样式钩子，同时保留硬编码值作为回退（fallback）。样式钩子既能控制代码、也能控制 Figma 中的视觉样式。

全局样式钩子（二）：代码与 Figma 中的工作方式（Global Styling Hooks (2): How They Work）

样式钩子在代码和 Figma 中一致呈现：代码里是 CSS 变量，Figma 里是经样式属性使用的变量。

命名反映结构，例如 --slds-g-color-border-disabled-1——编码了系统、作用域、区域和规模。这种有组织的命名让你一眼看懂钩子如何被使用和应用。

为什么重要：样式钩子是浏览器标准（CSS 自定义属性），非常适合需要响应式、动态样式的 Web 应用，是前端团队想要灵活样式的理想选择。可以把样式钩子理解为 CSS 变量，而 CSS 变量是浏览器项目或需要浏览器内响应式动态样式场景的标准。

组件（Components）

组件是 UI 中执行特定功能或动作的积木。SLDS 2 中重要的组件类型：

Lightning Web Component（LWC）——现代、基于标准的框架，用原生 JavaScript、HTML、CSS 构建模块化、可复用的 UI 组件；
Lightning Base Component——按 SLDS 组件蓝图库构建的程序化组件，提供最小功能；
Custom Lightning Component——客户在 Lightning 平台构建的功能性、可复用组件，可用或不用 Base 组件；
Component Blueprint——代表组件视觉设计部分的框架无关 HTML 或 CSS。

现在你了解了 SLDS 2 的架构、能力和关键特性。接下来学习如何评估组织与 SLDS 2 的兼容性，以及如何把自定义组件升级到 SLDS 2。

从 SLDS 1 过渡到 SLDS 2（02 Transition Your Org）

本单元是动手核心。我们梳理开发者的过渡工作流——评估代码、设置测试环境、用 SLDS Linter 和 SLDS Validator 分析代码、更新与测试、最终上线——同时覆盖设计师和管理员的任务。

完成本单元后，你将能够：

列出开发者的 SLDS 2 过渡任务；
列出管理员和设计师的过渡任务；
讨论如何设置测试组织、SLDS Linter、SLDS Validator 和 SARIF Viewer 来审计设计代码。

你的 SLDS 2 过渡（Your SLDS 2 Transition）

把代码从 SLDS 1 升级到 SLDS 2 很直接，工作量取决于你有多少自定义组件。注意：从 SLDS 1 到 SLDS 2 / Salesforce Cosmos 的过渡，比从 Classic 到 Lightning 的过渡轻松得多。

作为开发者，你负责评估自定义组件和第三方应用与 SLDS 2 兼容性的深层技术细节，并与设计师、管理员作为一个团队协作。五大高层步骤：

设置开发环境并评估组织就绪度；
用 SLDS Linter/Validator 和 Figma kits 分析代码；
更新组件代码以符合 SLDS 2 标准；
在开发环境测试；
重新部署并上线新版本组织。

设计师的过渡任务（Transition Tasks for Your Designer）

设计师负责品牌在组织中的一致观感。他们的工作：

验证整个 UI 的视觉一致性；
用 Figma kits 更新设计；
支持测试自定义组件，留意向 SLDS 2 迁移时的意外视觉行为。

设计师在过渡中守护品牌一致性——他们验证视觉一致、用 Figma kits 更新设计稿、并协助测试自定义组件是否有意外视觉表现。

管理员的过渡任务（Transition Tasks for Your Admin）

依赖 Salesforce 管理员来协调从 SLDS 1 到 SLDS 2 的整体升级项目。管理员：

协调整体 SLDS 1 → SLDS 2 升级项目；
让开发者和设计师保持在正轨上。

管理员的更多细节出现在本单元的 Go Live（上线）部分——他们是过渡的项目负责人。

你的过渡任务：评估代码并升级到 SLDS 2（Transition Tasks for You）

你的职责是处理深层技术细节。高层步骤：

设置开发环境并评估组织就绪度；
用 SLDS Linter 或 SLDS Validator 和 Figma kits 分析代码；
更新组件代码以符合 SLDS 2 标准；
在开发环境测试代码；
重新部署代码并上线新版本组织。

这是你的使命——评估自定义组件和第三方应用的 SLDS 2 能力与升级需求。开始吧。

设置你的开发环境（Set Up Your Development Environment）

你需要一个测试 SLDS 2 的环境。测试组织必须满足最低要求：

最低 Salesforce 版本：Winter '25；
支持的浏览器：最新版 Chrome、Firefox、Safari、Edge。

创建 scratch 或 sandbox 组织并配置。根据组织的产品和版本，SLDS 2 和 Salesforce Cosmos 可能已启用；如果没启用：

在组织里点击设置齿轮，选 Setup；
Starter 组织点击 Open Advanced Setup，其它组织跳过；
Quick Find 搜索选择 Themes and Branding；
从 Salesforce Cosmos 主题下拉列表选 Activate。

注意：激活 Salesforce Cosmos 时，SLDS 2 也会为整个组织激活。然后审查代码中需特别关注的常见特性，如托管包组件或 Lightning Out（Beta）实现。

用 SLDS Linter 分析代码（一）：设置与运行（Analyze with SLDS Linter (1): Setup & Run）

用 SLDS Linter 审计并自动修复代码。前置条件：

安装 VS Code；
（可选）安装 SARIF Viewer 扩展；
安装 Node.js——最低 v18.4.0，推荐最新 Active LTS 版本。

运行步骤：

在 VS Code 打开终端；
运行 SLDS Linter（若未安装会提示安装包，输入 y 安装）；
查看控制台输出的 lint 结果——注意它包含行号和列号；
点击数字跳转到源码对应行（macOS 上 Command+Click）；
运行命令生成 SARIF 报告，输出文件名为 slds-linter-report.sarif。

SLDS Linter 是推荐工具，设置简单、自动化程度高、规则库丰富，反映了新的 SLDS 2 样式指南。

用 SLDS Linter 分析代码（二）：修复与重新验证（Analyze with SLDS Linter (2): Fix & Revalidate）

用 VS Code 的 SARIF Viewer 打开报告，记下 SLDS Linter 标记了多少组件需要修复。修复错误有两种方式：

批量自动修复——运行一条命令自动修复；
手动修复——按 SLDS Linter 提供的建议手动改代码。

修复后，再次运行 SLDS Linter 重新验证代码。如果没有违规，说明你的代码已成功升级到 SLDS 2 标准。太棒了！

用 SLDS Validator 分析代码（一）：设置（Analyze with SLDS Validator (1): Setup）

偏好 SLDS Validator？设置它：

安装 VS Code v1.26 或更高版本；
安装 Salesforce Extension Pack——SLDS Validator 自动启用；
按说明设置 JDK。

为使用 SLDS Validator 的批量报告功能，安装 SARIF Viewer 扩展：

在 VS Code 点击 Extensions（Mac 上 Shift-Cmd-X，Windows 上 Ctrl+5）；
搜索选择 Sarif Viewer；
点击 Install。

SLDS Validator 是备选工具，也搭配 Figma kits 使用。

用 SLDS Validator 分析代码（二）：生成与读取报告（Analyze with SLDS Validator (2): Generate & Read）

验证代码：

在 VS Code 打开包含要验证组件代码的文件夹；
打开 VS Code 命令面板（Mac 上 Cmd-Shift-P，Windows 上 Win+P）；
输入选择 SLDS: Generate Sarif Report；
选 Folder and Output Directory；
点击 OK；
打开生成的 SARIF 文件。

报告会标出：组件级必须解决的问题、CSS 类违规、应更新为样式钩子的设计令牌实例、可访问性关注点。每个问题都会标明代码位置、问题描述、推荐修复和优先级（如 error 或 warning）。

更新与测试代码（一）：迭代升级（Update and Test Your Code (1): Iterate）

现在更新前一阶段识别出的组件，使其符合新设计和工具给出的建议：

用 SLDS Linter 或 SLDS Validator 审查并接受建议；
参照 Get Started: Developers 指南更新组件内的 CSS；
用 SLDS 2 Figma kits 支持新设计或定制；
迭代直到组件符合 SLDS 2 设计。

这是过渡真正落地的地方——持续迭代，让组件符合工具识别的 SLDS 2 建议。

更新与测试代码（二）：测试（Update and Test Your Code (2): Testing）

测试升级后的代码：

功能验证——确认功能正常；
视觉回归测试——捕捉样式漂移；
跨客户环境测试（如适用）。

测试让过渡变得真实。验证功能、跑视觉回归测试捕捉样式漂移、必要时跨不同客户环境测试，然后在发布前重新验证。

上线（Go Live）

上线前与 Salesforce 管理员和设计师确认，然后：

用 SLDS Linter 或 SLDS Validator 重新验证更新后的代码；
对设计做视觉回归测试（设计师可协助）；
更新文档和培训材料（管理员可协助）；
创建并发送面向客户的沟通——发布说明、博客文章。

发布后，鼓励在 Design Trailblazers 小组向 Salesforce Design Systems 团队提供发布后反馈。

继续前进（Onward and Upward）

呼——该庆祝了！你吸收了海量信息：设置了测试环境、用 Linter/Validator 分析了代码、更新并测试了组件、上了线。SLDS 2 很直观，但信息量确实不小。下一步前往下一单元，了解支持资源和一些最常见的问题。

获取 SLDS 2 帮助与支持（03 Get Help and Support with SLDS 2）

最后一个单元回答最常见的 SLDS 2 问题，告诉你在需要时如何获取帮助，并解释如何在 SLDS 2 生命周期中持续支持你的组织。

完成本单元后，你将能够：

回答关于 SLDS 2 的一些最常见问题；
描述需要时如何获取支持；
解释如何支持组织走过 SLDS 2 生命周期。

有问题吗？（Got Questions?）

把代码过渡到 SLDS 2 并不可怕，事实上它是效率提升和代码现代化的绝佳机会。即便如此，有时你仍有疑问。以下是我们收到的一些最常见问题：

SLDS 2 会影响我现有的定制吗？
需要时可以切回 SLDS 1 吗？
新设计会用于 Experience Cloud 站点吗？
新 Lightning UI 设计会影响我的 AgentExchange 解决方案吗？
我需要重新培训用户吗？
当前支持什么、不支持什么？

SLDS 2 会影响现有定制吗？（一）：预期（Will SLDS 2 affect my customizations? (1): What to Expect）

答案是：大多数定制能平滑过渡，因为它们依赖样式钩子。不过建议：

在 sandbox 里充分测试你的 SLDS 2 代码；
查看 Get Started: Developers 指南获取完整的测试清单。

下一节我们按使用模式逐一说明预期行为。

SLDS 2 会影响现有定制吗？（二）：预期行为（Will SLDS 2 affect my customizations? (2): Expected Behaviors）

不同使用模式的预期行为：

使用 Lightning Base Components（LBC）——无需操作，LBC 自动采用 SLDS 2；唯一例外是如果你对 LBC 应用了自定义 CSS 覆盖；
正确使用受支持的样式钩子和类——SLDS 2 激活时自动收到更新；
使用 CSS 覆盖——改用受支持的样式钩子，尽可能把硬编码值更新为样式钩子，移除尽可能多的 SLDS 类覆盖；
使用已弃用语法——更新旧的 BEM 语法，例如 .slds-button--neutral 改为 .slds-button_neutral；
未正确使用 SLDS 样式钩子和类——不会自动采用新设计，需确保正确使用 SLDS 类或样式钩子以对齐新设计系统。