使用正确的蓝图、样式钩子、工具类和图标来应用符合 SLDS 的 UI。在构建任何需要 SLDS 的 UI 时使用，包括在 Lightning 基础组件和 SLDS 蓝图之间选择、应用样式钩子进行主题化、使用工具类进行布局和间距，或选择图标。触发词包括\"构建模态框\"、\"创建表单\"、\"数据表\"、\"SLDS 样式\"、\"使用钩子设置样式\"、\"添加图标\"。
应用 SLDS
Salesforce Lightning Design System (SLDS) 是一个包含数千个工件的 CSS 框架。本技能教代理如何查找并正确使用它们。
版本： 本技能针对 SLDS v2。旧的
--lwc-*令牌和slds-*--modifier语法已弃用。审计范围： 配套的
design-systems-slds-validate技能分析器仅扫描.css、.html和.js文件。直接用于 LWC 和类似的 HTML/CSS/JS 组件；对于 JSX/TSX 或其他框架特定的模板格式，将其视为部分信号，并辅以人工审查。
什么是 SLDS？
| 工件 | 数量 | 描述 |
|---|---|---|
| Lightning 基础组件 | ~70 | 预构建的 LWC 组件（仅限 LWC） |
| SLDS 蓝图 | 85 | 适用于任何框架的 CSS/HTML 模式 |
| 样式钩子 | 523 | 用于主题化的 CSS 自定义属性（--slds-g-*） |
| 工具类 | 1,147 | 用于间距、布局、可见性的快速样式类 |
| 图标 | 1,732 | 跨 5 个类别的 SVG 图标 |
范围
本技能涵盖：
- 针对给定 UI 模式应使用哪个蓝图
- 如何使用钩子进行样式设置（颜色、间距、排版、阴影、边框）
- 用于布局、间距、可见性应使用哪些工具类
- 应使用哪个图标以及来自哪个类别
- SLDS 命名约定、类结构、钩子语法
本技能包含基本的可访问性提醒（图标替代文本、焦点轮廓、颜色非唯一指示符）在验证清单中。完整的 WCAG 合规性需要专门的可访问性审查。
本技能不涵盖（使用配套技能）：
- 设计决策 -- 视觉层次、构图、交互模式
- LWC 机制 -- 组件结构、@wire、@api、生命周期、事件（尚不可用）
- 完全可访问性 -- WCAG 一致性、ARIA 模式、键盘导航、焦点管理、对比度（尚不可用）
组件选择层次结构
始终遵循此顺序：
1. Lightning 基础组件（仅限 LWC） ← 首先检查
2. SLDS 蓝图（任何框架） ← 使用精确的 SLDS 类
3. 使用样式钩子的自定义 ← 使用 var(--slds-g-*)
4. 自定义 CSS（最后手段） ← 仍然使用钩子作为值
如果在 LWC 中构建，首先检查是否有 LBC：Lightning 组件库
如果没有 LBC（或未使用 LWC），选择 SLDS 蓝图。请参阅 references/component-selection.md。
核心规则
应该
- 遵循选择层次结构：LBC > 蓝图 > 钩子 > 自定义 CSS
- 对所有可主题化的值使用
var(--slds-g-*, fallback) - 创建自定义类（
my-*、c-*）而不是覆盖.slds-* - 在使用前验证每个钩子、类和工具类是否存在 — 运行搜索脚本；切勿根据命名模式假设工件存在（请参阅 使用前验证）
- 将表面颜色与表面上的颜色配对用于文本
- 在每个
<lightning-icon>上提供alternative-text
不应该
- 硬编码颜色、间距或排版值
- 直接覆盖
.slds-*类 - 使用已弃用的
--lwc-*令牌作为主要值 - 使用
--slds-s-*（共享）钩子 -- 它们是私有的/内部的 - 重新分配钩子值 -- 仅使用
var()引用它们 - 仅使用颜色来传达含义
- 通过从其他系列插值模式来发明钩子名称（请参阅下面的命名陷阱）
钩子命名陷阱
SLDS 钩子系列并非都遵循相同的命名模式。代理经常通过假设 {prefix}-{number} 普遍适用而发明不存在的钩子。始终验证钩子存在 通过捆绑的 search-hooks.cjs 脚本或 assets/hooks-index.json 在使用之前。
陷阱 1：字体大小钩子不是编号的
| 错误（不存在） | 正确 | 备注 |
|---|---|---|
--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：颜色钩子总是需要数字
| 错误（不存在） | 正确 | 备注 |
|---|---|---|
--slds-g-color-on-surface |
--slds-g-color-on-surface-2 |
所有颜色钩子都需要数字 |
--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-* 钩子都以数字结尾。根据强调选择：-1（低）、-2（中）、-3（高）。
陷阱 3：并非所有值都有钩子等价物
某些 CSS 值（例如，标签对齐的 min-width: 7rem）没有 SLDS 钩子。这是可以接受的：
.c-field-label {
/* 此宽度没有 SLDS 钩子；有意的自定义值 */
min-width: 7rem;
}
规则： 当没有钩子时，直接使用该值并附上注释说明是有意的。尽可能优先使用 SLDS 网格工具类（slds-size_*）作为硬编码宽度的替代方案。
使用前验证
规则： 在生成的代码中，切勿包含 SLDS 钩子、工具类、蓝图类或图标，除非先确认它存在于元数据中。基于命名模式猜测是发明工件的主要来源。
在发出任何 SLDS 工件之前运行适当的搜索命令：
| 工件 | 验证命令 | 事实来源 |
|---|---|---|
样式钩子（--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 |
如果搜索没有返回匹配项：不要使用该工件。 从搜索结果中找到替代方案，或使用已验证的钩子构建自定义。
命名约定
为自定义类使用一致的前缀以避免与 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）。
自定义钩子命名空间：
: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 个样式钩子 | --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/ |
钩子类别及详细用法 | references/README.md |
references/utilities/ |
27 个工具类类别 | references/README.md |
references/slds-development-guide.md |
完整的 SLDS 开发指南 | -- |
原始元数据（用于查找的结构化数据）
不要直接阅读元数据 JSON 文件 — 它们对于代理上下文来说太大（hooks-index.json 有 6,000+ 行；icon-metadata.json 有 38,000+ 行）。使用上面的搜索脚本查询它们。
| 文件 | 内容 | 行数 |
|---|---|---|
assets/blueprints/components/*.yaml |
85 个蓝图规范（类、变体、可访问性、HTML） | 每个约 50-200 |
assets/hooks-index.json |
523 个钩子及值和 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：选择工件
- 如果是 LWC：检查 Lightning 组件库 是否有 LBC
- 搜索蓝图：
node scripts/search-blueprints.cjs --search "<pattern>" - 阅读蓝图 YAML：
assets/blueprints/components/<name>.yaml获取精确的类、修饰符、状态和可访问性要求 - 没有匹配项？ 使用钩子构建自定义（见阶段 3）
详细信息：references/component-selection.md
阶段 3：应用样式
- 阅读：references/styling-decision-guide.md
- 颜色：分类角色（表面、强调、反馈、边框）然后选择钩子
- 间距：使用工具类（
slds-p-*、slds-m-*）或钩子（--slds-g-spacing-*） - 布局：使用网格工具类（
slds-grid、slds-col、slds-size_*） - 自定义 CSS：仅使用
var(--slds-g-*, fallback)、自定义类前缀
阶段 4：添加图标
- 阅读：references/icons-decision-guide.md
- 搜索：
node scripts/search-icons.cjs --query "<description>" - 在 LWC 中：使用带有
alternative-text的<lightning-icon> - 在非 LWC 中：使用带有
slds-icon类和slds-assistive-text的 SVG
阶段 5：验证（强制 — 不要跳过）
步骤 1：运行 SLDS linter。 这是必需的。零违规是目标。
npx @salesforce-ux/slds-linter@latest lint <component-path>
linter 捕获硬编码值、类覆盖和已弃用的令牌。在继续之前修复所有违规。 不要将违规合理化。
步骤 2：验证没有发明的钩子。 确认输出中的每个 --slds-g-* 钩子都存在于 assets/hooks-index.json 中。对照 checklists.md 中的 T051 检查进行交叉引用。
步骤 3：运行 checklists.md 以进行 linter 无法自动化的检查：
- 所有
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）或更高，然后标记工作完成。
快速参考
常见钩子模式
/* 表面 + 文本配对（始终使用编号变体） */
background: var(--slds-g-color-surface-1, #ffffff);
color: var(--slds-g-color-on-surface-2, #181818);
/* 标准内边距 */
padding: var(--slds-g-spacing-4, 1rem);
/* 卡片式容器 */
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));
/* 主要操作强调色 */
background: var(--slds-g-color-accent-1, #0176d3);
color: var(--slds-g-color-on-accent-1, #ffffff);
/* 排版 -- 使用 font-scale-*，而不是 font-size-*（只有 font-size-base 存在） */
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="完整文本在此">完整文本在此</p>
示例
参见 examples.md 获取完整示例，展示从意图到 SLDS 工件选择的完整工作流程。
验证
参见 checklists.md 获取与 design-systems-slds-validate 技能对齐的验证清单。
