一、激活 SLDS 2 并预览深色模式
本模块超越基础——你将激活 SLDS 2、创建自定义主题、用样式钩子（styling hooks）构建「模式感知」的组件，并用 SLDS Linter 验证代码，最终把一个「深色模式就绪」的自定义组件部署到组织。完成本单元后，你将能够：解释 SLDS 2 深色模式是什么、样式钩子如何支持定制；列出管理员和开发者可定制的深色模式方面；在组织里激活 SLDS 2；创建自定义主题；预览深色模式。
开始前：深色模式仅限 SLDS 2 主题——如果组织还在用 SLDS 1，必须先迁移。截至 Winter ’26，深色模式可用于 Free/Starter/Pro/Professional/Enterprise/Developer 版本。建议先完成「SLDS 2 for Admins」「The Salesforce Cosmos Theme: Quick Look」「Dark Mode in SLDS 2: Quick Look」等前置模块。本模块还需一个已启用深色模式、含示例数据的特殊 Developer Edition 组织（通过 Trailhead 提供的链接注册并连接到 Trailhead）。
Dark Mode 概述
深色模式（Dark Mode）是 Salesforce 呼声最高的功能之一：它是一种视觉显示设置，反转传统浅色配色，在深色背景上呈现浅色文字与视觉元素，尤其适合长时间面对屏幕的用户。深色模式不只是美观——它满足视力受损用户、以及因明亮屏幕而偏头痛用户的关键可访问性需求（参见 IdeaExchange 上「Lightning Night Mode」的高需求）。管理员/开发者在组织级别预览并激活深色模式，之后用户在自己的个人组织视图里开启。
架构关键：深色模式构建在 SLDS 2 样式钩子架构之上，不是简单的颜色反转，而是一个复杂、模式感知的设计系统。许多界面元素在启用深色模式时自动适配；而自定义组件需要显式使用样式钩子才能正确适配——如果自定义 CSS 里硬编码了颜色，这些组件在深色模式下就会「坏掉」。理解这一区别是本模块一切的关键。注意：深色模式是 pilot/beta 服务，受 Beta Services Terms 约束。
自定义选项
Salesforce 原生深色模式是一个构建在 SLDS 2 样式钩子架构上的复杂实现。要定制深色模式，你有两条路径：
- 方式一（推荐）：为组织选择一个独特的品牌色用于深色模式。Salesforce 会自动为你的深色模式强调色生成一套互补的调色板，保证对比度与可访问性。
- 方式二（不推荐）：让组织使用与浅色模式相同的品牌色，只编辑深色模式的强调色。虽然可以这么做，但 Salesforce 强烈建议不要覆盖自动生成的强调色——这可能会破坏有保证的对比度与可访问性合规。坚持默认值能提供最佳视觉体验与合规。
样式钩子（Styling Hooks）
深色模式适配自定义组件的核心是 SLDS 2 样式钩子（styling hooks）。它们就像 CSS 里的「智能变量」，会根据当前颜色模式与组织品牌自动调整取值。对开发者而言，这些钩子让自定义组件集成深色模式变得异常简单：与其定义固定颜色值，你只需引用一个样式钩子。所有 SLDS 2 兼容的样式钩子都是全局样式钩子，以 --slds-g 开头。
例如，用 --slds-g-color-surface-3 这个全局样式钩子，而不是硬编码 #F3F3F3 来设置浅灰色表面。
使用样式钩子创建自定义组件的思路：
- 背景与表面（Backgrounds and surfaces）：不用固定颜色（如
#FFFFFF白色），改用全局样式钩子（如--slds-g-color-surface-1），它们会自动解析为对应的深色背景色。 - 交互元素、文字或强调色：不用固定颜色（如
#066AFE、#022AC0），改用--slds-g-color-accent-1、--slds-g-color-accent-container-3等钩子，它们会适配浅色/深色模式并反映组织自定义主题里的品牌强调色。
例如，创建一个「白底蓝按钮」的 Lightning Web Component，就用主品牌蓝的钩子 + 白色文字的钩子。始终使用全局样式钩子，就能确保自定义组件在浅色模式、深色模式以及任何自定义主题下都有正确的样式——无需为每种颜色模式写条件逻辑。
深色模式开发流程
要确保深色模式与你的品牌和品牌色协同工作，推荐的高层开发流程如下：
- 在组织里激活 SLDS 2（如果还没开启）
- 为你的品牌创建一个自定义 SLDS 2 主题
- 保存主题
- 为用户启用深色模式选项
- 在深色模式下预览你的自定义主题
- 用 SLDS Linter 识别预览中看起来不对的地方并修复
- 激活新主题和深色模式
关键在于：先预览、后激活，尽早发现问题——SLDS Linter 能捕捉到肉眼可能漏掉的问题。
激活 SLDS 2
要使用深色模式，组织必须运行在 SLDS 2 上。通过激活构建在 SLDS 2 上的主题（如默认主题 Salesforce Cosmos）来开启 SLDS 2：
- 在组织里点击齿轮图标，选择 Setup（本模块使用特殊 Developer Edition 组织；在 Starter Suite 组织里则是点齿轮后选 Open Advanced Setup）
- 在 Quick Find 搜索并选择 Themes and Branding
- 从 Salesforce Cosmos 主题下拉列表选择 Activate
- 再点一次 Activate 确认
完成！SLDS 2 已在组织里激活。注意：完整迁移到 SLDS 2 不止是激活主题——你的自定义组件也需要提升（uplift）到 SLDS 2 标准，详见 SLDS 2 网站的「Transition Your Org to SLDS 2」。
创建自定义主题
SLDS 2 的默认主题 Salesforce Cosmos 已经很棒，但你可能希望组织看起来更像你的品牌。通过创建自定义主题来实现：输入品牌色，Salesforce 会用其颜色系统生成一套优化了对比度与可访问性的调色板（必要时可在 Advanced Configuration 里手动调整单个强调色类别——但 Salesforce 无法保证手动调整后的对比度，可能影响组织的可访问性合规）。
- 从 Setup 的 Quick Find 搜索并选择 Themes and Branding
- 点击 New Theme
- 命名主题为
My Theme - Brand Color 输入
#9900FF（会看到基于品牌的调色板自动变为与 #9900FF 相配的紫色系可访问色） - 点击 Save
注意：先不要激活新主题——最佳实践是先启用并预览深色模式，确认一切正常后再激活。
预览深色模式
在面向所有用户开放前，你可以先预览刚创建的主题在深色模式下的效果。在 Themes and Branding 页面：
- 打开 My Theme 编辑，在 Dark Mode 区域勾选 Let users enable Dark Mode，点击 Save，再点 Preview
- 注意：启用预览后你仍停留在 Setup——深色模式不会在 Setup 中生效，请导航到 Setup 之外的应用查看
- 点击 App Finder，搜索并选择 Trailhead 应用（保持 Setup 标签页打开），你会看到紫色文字和页面顶部的「You’re previewing a theme!」提示
- 点击头像查看个人档案，在 Color Mode 选择 Dark，关闭档案
现在你看到品牌色 #9900FF 在深色模式下正常显示。但仔细看——有没有什么不对劲？Hello, World! 应用是深色文字配浅色背景！这就是一个深色模式 bug：该应用的自定义 CSS 用了硬编码颜色，而不是样式钩子，所以没有正确响应深色模式。标准组件会自动适配（内部用了样式钩子），而硬编码颜色的自定义组件会在深色模式下「露馅」。这种问题正是要在预览阶段、而非生产环境里发现。下一个单元我们就来修复它。
二、用 SLDS Linter 修改自定义组件
现在戴上开发者帽子。你将用 SLDS Linter（一个免费的代码分析工具）修复 Hello World 的深色模式 bug，学习如何把自定义组件提升到完全 SLDS 2 与深色模式合规。完成本单元后，你将能够：解释如何用 SLDS Linter 验证自定义组件是否符合 SLDS 2 深色模式样式；创建 Salesforce DX 项目并编辑自定义组件代码；激活自定义主题并在组织里启用深色模式；把深色模式就绪的组件部署到组织。
修复深色模式 bug
还记得预览里那个 Hello, World! bug 吗？是时候解决它了。本单元的整体步骤是：1) 安装先决条件；2) 使用 SLDS Linter（识别 SLDS 2 代码差异的免费代码分析工具）；3) 创建 Salesforce DX（SFDX）项目（一套精简 Salesforce 应用开发与管理的工具）；4) 把编辑后的代码部署回特殊 Developer Edition 组织。
好消息是，Hello, World! 应用已经安装在你的特殊 Developer Edition 组织里，我们直接从编辑它的自定义组件代码入手。
先决条件与创建 SFDX 项目
开始编码前，先装好这些工具：
- Visual Studio Code（VS Code） + Salesforce Extension Pack（提供代码补全、语法高亮、Apex 调试等）
- Node.js（最低 v18.4.0，推荐最新 Active LTS）——运行 SLDS Linter 所需
- （可选）SARIF Viewer VS Code 扩展，用于查看 SLDS Linter 生成的报告
创建 Salesforce DX 项目：在 VS Code 里按 Ctrl+Shift+P 打开命令面板 → 选 SFDX: Create Project → 接受标准选项 → 项目名输入 HelloWorldLightningWebComponent → 选根文件夹 → Create Project。
授权并打开项目：命令面板选 SFDX: Authorize an Org → 接受 Project Default 登录 URL 与默认别名 → 浏览器里登录 Developer Edition 凭据并 Allow。然后在终端运行 sf project retrieve start -m LightningComponentBundle:helloWorld 拉取已部署的 helloWorld 组件，再 cd force-app/main/default/lwc/helloWorld 进入组件目录，在 VS Code Explorer 打开 helloWorld.css 和 helloWorld.html——这就是需要修复的有 bug 的代码。
用 SLDS Linter 验证与提升组件
SLDS Linter 帮助开发者验证代码是否符合 SLDS 2 标准与最佳实践（包括深色模式样式），主动识别问题，助力 100% 设计一致性并满足 WCAG 颜色对比度指南。它就像组件 SLDS 2 / 深色模式兼容性的「拼写检查器」——能捕捉肉眼可能漏掉的问题，并给出具体修复建议。
运行 SLDS Linter：在 VS Code 项目根目录的终端运行 npx @salesforce-ux/slds-linter@latest lint（若询问安装包则输入 y）。输出会显示行号与列号——helloWorld 组件通常有两个违规：一个在 CSS 文件、一个在 HTML 文件。
把组件提升到 SLDS 2：修复有两种方式——自动修复与手动修复。先运行 npx @salesforce-ux/slds-linter@latest lint --fix 自动修复 HTML 与 CSS（通常立即解决 HTML 违规）；剩下的 CSS 问题手动修复：把硬编码颜色替换为全局样式钩子（例如把 --lwc-colorBackgroundAlt 换成 --slds-g-color-surface-1），并确保文字颜色与背景正确对比。为什么新代码合规？因为全局样式钩子会拉取对应的浅色或深色值，而不是静态值；文字颜色与背景正确对比；不再有静态/硬编码颜色值。
保存后重新运行 SLDS Linter 验证——零违规，组件已提升到 SLDS 2 标准！
部署并激活
部署编辑后的代码：在 VS Code Explorer 右键 /force-app/main/default/lwc 文件夹 → 选 SFDX: Deploy this Source to Org → 等待部署完成 → 在浏览器刷新 Hello, World! 应用页面。现在它正确显示在深色模式下了：背景是深色、字体是浅色，组件看起来与整体协调一致。
激活自定义主题与深色模式：预览并修复了 bug 后，就可以对所有用户激活了。在 Themes and Branding 里，从 My Theme 旁的下拉选 Edit → 点击 Activate 确认。现在每个用户都能通过个人设置开启深色模式。
用户如何开启：点击头像打开档案 → 在 Color Mode (Beta) 点 Dark，界面即刻切换，无需刷新。想关闭就选 Light 或 System（跟随系统偏好）。这个两层设计——管理员控制可用性，用户控制个人偏好——兼顾了治理与选择。记住：如果从 SLDS 2 主题切换回 SLDS 1 主题，深色模式会自动停用。
总结
你已经走了很远：探索了深色模式如何与 Salesforce 自定义组件集成；走完了推荐的深色模式开发流程；使用了强大的 SLDS 2 样式钩子替代硬编码颜色；用 SLDS Linter 验证了代码（自动 + 手动修复）；在组织里激活并启用了深色模式。
通过这些思路，你的自定义解决方案无论在浅色还是深色模式下都好看，为所有用户提供简单一致的体验，并开箱即用地满足可访问性标准。继续尝试，享受自适应设计的力量！