applying-slds

应用 SLDS

Salesforce Lightning Design System（SLDS） 是一个包含数千种元素的 CSS 框架。本技能将教 Agent 如何找到这些元素并正确使用它们。

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

审查范围： 配套的 validating-slds 技能分析器仅扫描 .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 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 蓝图。请参阅 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 脚本或 metadata/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>"	metadata/hooks-index.json
工具类（slds-*）	node scripts/search-utilities.cjs --search "<class-name>"	metadata/utilities-index.json
蓝图 / CSS 类	node scripts/search-blueprints.cjs --search "<pattern>"，然后读取 YAML	metadata/blueprints/components/*.yaml
图标	node scripts/search-icons.cjs --query "<description>"	metadata/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"

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

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

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

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

文件	内容	行数
metadata/blueprints/components/*.yaml	85 个蓝图规格（类、变体、无障碍、HTML）	每个约 50-200 行
metadata/hooks-index.json	523 个 Hook，包含值和 CSS 属性	约 6,300 行
metadata/icon-metadata.json	1,732 个带同义词、可供搜索的图标	约 38,500 行
metadata/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：查看 metadata/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 linter。 这是必需步骤。目标是零违规。

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

linter 会检测硬编码值、类覆盖和已弃用的令牌。继续之前，修复所有违规。 不要将违规辩解为可以接受。

步骤 2：确认没有臆造的钩子。 确认输出中的每个 --slds-g-* 钩子都存在于 metadata/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（可选）：使用 validating-slds 技能运行完整质量审计，在代码审查或部署之前获取评分报告。对于 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，其中提供了与 validating-slds 技能相匹配的验证清单。

资源

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