design-systems-slds-apply

应用 SLDS

Salesforce Lightning Design System (SLDS) 是一个包含数千种资源的 CSS 框架。本技能将教 Agent 如何查找并正确使用这些资源。

**版本：**本技能面向 SLDS v2。旧版 --lwc-* 令牌和 slds-*--modifier 语法已弃用。

**审计范围：**配套的 design-systems-slds-validate 技能分析器只扫描 .css、.html 和 .js 文件。对于 LWC 及类似的 HTML/CSS/JS 组件，请直接使用该分析器；对于 JSX/TSX 或其他特定于框架的模板格式，应将其视为部分参考，并辅以人工审查。

什么是 SLDS？

资源	数量	描述
Lightning Base Components	~70	预构建的 LWC 组件（仅限 LWC）
SLDS Blueprints	85	适用于任何框架的 CSS/HTML 模式
Styling Hooks	523	用于主题化的 CSS 自定义属性（--slds-g-*）
Utility Classes	1,147	用于间距、布局、可见性的快速样式类
Icons	1,732	涵盖 5 个类别的 SVG 图标

---

范围

本技能涵盖：

• 针对给定 UI 模式应使用哪个蓝图
• 如何使用钩子设置样式（颜色、间距、排版、阴影、边框）
• 布局、间距和可见性应使用哪些实用类
• 应使用哪个图标以及它属于哪个类别
• SLDS 命名约定、类结构和钩子语法

本技能包含基本的无障碍提醒（图标替代文本、焦点轮廓、颜色不作为唯一指示）并列于验证清单中。要完全符合 WCAG 标准，需要进行专门的无障碍审查。

本技能不涵盖以下内容（请使用配套技能）：

• 设计决策——视觉层次、构图、交互模式
• LWC 机制——组件结构、@wire、@api、生命周期、事件（尚不可用）
• 完整无障碍——WCAG 合规性、ARIA 模式、键盘导航、焦点管理、对比度（尚不可用）

---

组件选择层级

务必遵循以下顺序：

1. Lightning Base Components (LWC only)    ← Check first
2. SLDS Blueprints (any framework)         ← Use exact SLDS classes
3. Custom with Styling Hooks               ← Use var(--slds-g-*)
4. Custom CSS (last resort)                ← Still use hooks for values

如果使用 LWC 构建，请先检查是否有 LBC：Lightning Component Library

如果不存在 LBC（或未使用 LWC），请选择 SLDS Blueprint。参阅 references/component-selection.md。

---

核心规则

应做

• 遵循选择层级：LBC > Blueprint > Hooks > 自定义 CSS
• 所有可主题化的值都使用 var(--slds-g-*, fallback)
• 创建自定义类（my-*、c-*），而不是覆盖 .slds-*
• 使用前验证每个钩子、类和实用类是否存在——运行搜索脚本；切勿根据命名模式假设某项资源存在（参阅使用前验证）
• 为表面颜色搭配文本的表面上颜色
• 为每个 <lightning-icon> 提供 alternative-text

不应做

• 将颜色、间距或排版值硬编码
• 直接覆盖 .slds-* 类
• 将已弃用的 --lwc-* 令牌用作主要值
• 使用 --slds-s-*（共享）钩子——它们是私有/内部的
• 重新赋值钩子值——只能使用 var() 引用它们
• 仅用颜色传达含义
• 根据其他系列的模式插值并杜撰钩子名称（参阅下文的命名陷阱）

---

钩子命名陷阱

SLDS 钩子系列并不都遵循相同的命名模式。Agent 经常误以为 {prefix}-{number} 适用于所有情况，从而杜撰不存在的钩子。使用前务必通过随附的 search-hooks.cjs 脚本或 assets/hooks-index.json 确认钩子存在。

陷阱 1：字体大小 Hook 不使用编号

错误（不存在）	正确	说明
--slds-g-font-size-3	--slds-g-font-scale-1	字体大小使用 font-scale-*，而不是 font-size-*
--slds-g-font-size-4	--slds-g-font-scale-2	只有 --slds-g-font-size-base 存在（基础字号）
--slds-g-font-size-8	--slds-g-font-scale-6	范围为 neg-4 到 10

规则： 字体大小请使用 --slds-g-font-size-base（唯一的基础字号）或 --slds-g-font-scale-*（编号范围）。切勿使用 --slds-g-font-size-N。

陷阱 2：颜色 Hook 始终需要编号

错误（不存在）	正确	说明
--slds-g-color-on-surface	--slds-g-color-on-surface-2	所有颜色 Hook 都需要编号
--slds-g-color-on-accent	--slds-g-color-on-accent-1	根据强调程度选择 1/2/3
--slds-g-color-surface	--slds-g-color-surface-1	不存在不带编号的基础形式

规则： 每个 --slds-g-color-* Hook 都以数字结尾。根据强调程度选择：-1（低）、-2（中）、-3（高）。

陷阱 3：并非所有值都有对应的 Hook

有些 CSS 值（例如用于标签对齐的 min-width: 7rem）没有对应的 SLDS Hook。这是可以接受的：

.c-field-label {
  /* No SLDS hook exists for this width; intentional custom value */
  min-width: 7rem;
}

规则： 如果不存在对应的 Hook，可直接使用该值，并添加注释说明这是有意为之。在可行的情况下，优先使用 SLDS 网格实用类（slds-size_*）替代硬编码宽度。

---

使用前先验证

规则： 生成的代码中不得包含未经元数据确认存在的 SLDS Hook、实用类、蓝图类或图标。根据命名模式猜测，是臆造产物的主要来源。

输出任何 SLDS 产物前，请先运行相应的搜索命令：

产物	验证命令	唯一可信来源
样式 Hook（--slds-g-*）	node scripts/search-hooks.cjs --prefix "<hook-name>"	assets/hooks-index.json
实用类（slds-*）	node scripts/search-utilities.cjs --search "<class-name>"	assets/utilities-index.json
蓝图 / CSS 类	node scripts/search-blueprints.cjs --search "<pattern>"，然后读取 YAML	assets/blueprints/components/*.yaml
图标	node scripts/search-icons.cjs --query "<description>"	assets/icon-metadata.json

如果搜索没有匹配结果：不要使用该产物。 请从搜索结果中寻找替代方案，或使用已验证的 Hook 构建自定义实现。

---

命名约定

自定义类请使用一致的前缀，以避免与 SLDS 冲突：

模式	用途	示例
my-*	通用自定义样式	my-card-header
c-*	LWC 组件专用	c-accountList-row
[namespace]-*	软件包 / 应用命名空间	acme-dashboard-widget

避免使用： 通用名称（container、wrapper）、类似 SLDS 的名称（custom-slds-button）、在 SLDS 类上使用 BEM（slds-card__custom-header）。

自定义 Hook 命名空间：

:root {
  --my-app-primary: var(--slds-g-color-accent-1);
  --my-app-card-padding: var(--slds-g-spacing-4);
}

---

知识地图

此技能包含全面的 SLDS 知识。按需读取文件，不要一开始就全部读取。

决策指南（每项任务都从这里开始）

文件	阅读时机
references/component-selection.md	选择组件或蓝图时
references/styling-decision-guide.md	应用颜色、间距、排版、阴影时
references/icons-decision-guide.md	选择或实现图标时
references/utilities-quick-ref.md	使用实用类进行布局 / 间距设置时

搜索脚本（查找特定资源）

脚本	搜索内容	示例
scripts/search-blueprints.cjs	85 个蓝图 YAML 文件	--search "dialog"
scripts/search-hooks.cjs	523 个样式 Hook	--prefix "--slds-g-color-accent-"
scripts/search-icons.cjs	1,732 个带同义词的图标	--query "save button"
scripts/search-utilities.cjs	1,147 个工具类	--category "grid"

深入指南（阅读详细规则）

文件夹	内容	索引
references/overviews/	基础概念（颜色、间距、字体排版等）	references/README.md
references/styling-hooks/	Hook 分类及详细用法	references/README.md
references/utilities/	27 类工具类	references/README.md
references/slds-development-guide.md	完整的 SLDS 开发指南	--

原始元数据（用于查询的结构化数据）

请勿直接读取元数据 JSON 文件——它们对于 Agent 上下文来说过于庞大（hooks-index.json 超过 6,000 行；icon-metadata.json 超过 38,000 行）。请使用上面的搜索脚本进行查询。

文件	内容	行数
assets/blueprints/components/*.yaml	85 个蓝图规范（类、变体、无障碍、HTML）	每个约 50-200 行
assets/hooks-index.json	523 个 Hook，包含值和 CSS 属性	约 6,300 行
assets/icon-metadata.json	1,732 个带同义词的图标，供搜索使用	约 38,500 行
assets/utilities-index.json	1,147 个工具类及其 CSS 规则	约 6,900 行

---

编写工作流

阶段 1：了解需求

确定：

• 需要哪种 UI 模式？（表单、表格、模态框、卡片等）
• 使用哪种框架？（LWC、React、Vue、Angular、原生）
• 将显示哪些数据？
• 需要哪些状态？（加载中、空、错误、成功）

阶段 2：选择资源

1. 如果使用 LWC：在 Lightning Component Library 中查找 LBC
2. 搜索蓝图：node scripts/search-blueprints.cjs --search "<pattern>"
3. 阅读蓝图 YAML：查看 assets/blueprints/components/<name>.yaml，了解准确的类、修饰符、状态和无障碍要求
4. 没有匹配项？ 使用 Hook 构建自定义方案（参见阶段 3）

详情：references/component-selection.md

阶段 3：应用样式

1. 阅读：references/styling-decision-guide.md
2. 颜色：确定角色（表面、强调、反馈、边框），然后选择 Hook
3. 间距：使用工具类（slds-p-*、slds-m-*）或 Hook（--slds-g-spacing-*）
4. 布局：使用网格工具类（slds-grid、slds-col、slds-size_*）
5. 自定义 CSS：仅使用 var(--slds-g-*, fallback) 和自定义类名前缀

阶段 4：添加图标

1. 阅读：references/icons-decision-guide.md
2. 搜索：node scripts/search-icons.cjs --query "<description>"
3. 在 LWC 中：使用带有 alternative-text 的 <lightning-icon>
4. 在非 LWC 中：使用带有 slds-icon 类和 slds-assistive-text 的 SVG

第 5 阶段：验证（必做 — 不可跳过）

步骤 1：运行 SLDS 检查器。 此步骤为必需。目标是不出现任何违规项。

npx @salesforce-ux/slds-linter@latest lint <component-path>

检查器会发现硬编码值、类覆盖和已弃用的令牌。继续之前，请修复所有违规项。 不要把违规项解释为可接受的情况。

步骤 2：确认没有虚构的钩子。 确认输出中的每个 --slds-g-* 钩子都存在于 assets/hooks-index.json 中。对照 checklists.md 中的 T051 检查项。

步骤 3：按照 checklists.md 检查检查器无法自动化的项目：

• 所有 var(--slds-g-*) 都有回退值（T002）
• 表面／强调色／反馈颜色钩子均正确配对（T010–T013）
• 间距使用钩子或实用类——不使用魔法 px 值（T020–T021）
• 字体大小使用 --slds-g-font-scale-*，而非 --slds-g-font-size-N（T031）
• 所有图标都带有无障碍文本（A004）
• 自定义类使用 my-* 或 c-* 前缀（Q010）

步骤 4（可选）：使用 design-systems-slds-validate 技能运行完整质量审计，在代码审查或部署前获取评分报告。对于 LWC / HTML-CSS-JS 组件，可直接使用此技能；对于 JSX/TSX 输出，仅将结果视为部分覆盖。标记工作完成前，目标等级应达到 B（≥80）或更高。

---

快速参考

常见钩子模式

/* Surface + text pairing (always use numbered variants) */
background: var(--slds-g-color-surface-1, #ffffff);
color: var(--slds-g-color-on-surface-2, #181818);

/* Standard padding */
padding: var(--slds-g-spacing-4, 1rem);

/* Card-like container */
border-radius: var(--slds-g-radius-border-2, 0.25rem);
box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1));

/* Accent for primary actions */
background: var(--slds-g-color-accent-1, #0176d3);
color: var(--slds-g-color-on-accent-1, #ffffff);

/* Typography -- use font-scale-*, NOT font-size-* (only font-size-base exists) */
font-size: var(--slds-g-font-scale-2, 0.875rem);

常见实用类模式

<div class="slds-grid slds-wrap slds-gutters">
  <div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2">...</div>
</div>


<div class="slds-p-around_medium slds-m-bottom_small">...</div>


<p class="slds-truncate" title="Full text here">Full text here</p>

---

示例

请参阅 examples.md，其中包含演示从意图到 SLDS 产物选择的完整工作流示例。

验证

请参阅 checklists.md，其中包含与 design-systems-slds-validate 技能相对应的验证清单。

资源

资源	URL
SLDS 网站	https://www.lightningdesignsystem.com/
Lightning 组件库	https://developer.salesforce.com/docs/component-library/overview/components
SLDS 检查器	https://developer.salesforce.com/docs/platform/slds-linter/guide
样式钩子参考	https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks