validating-slds

SLDS 质量审计

审计 Lightning Web Components 的 SLDS 合规性，并生成自动化评分卡，同时设置必需的人工审核门槛。结合 SLDS linter 输出和补充静态分析，以捕获 linter 遗漏的问题。

范围

也适用于：审计整个项目或组件集的 SLDS 合规性，以及更改前后的质量对比。

不适用于：

• 修复 linter 违规 — 请改用 uplifting-components-to-slds2
• 构建新组件 — 请改用 applying-slds
• 仅运行 linter — 直接运行 npx @salesforce-ux/slds-linter@latest lint .
• 完整的 WCAG 无障碍审计 — 此技能只检查属性是否存在（标签、替代文本、焦点指示器），不检查对比度、键盘操作流程或屏幕阅读器行为
• 超出 .css、.html 和 .js 文件范围的框架专属模板审计 — JSX/TSX/Vue/Svelte 输出需要额外的人工审核

---

质量验证流程

1. Run SLDS Linter     → Collect violation counts (linter's job)
2. Run Analyze Script  → Check what linter doesn't cover (supplementary)
3. Agent Review        → Required manual review gate
4. Score & Grade       → Compute automated score + final recommendation
5. Generate Report     → Produce formatted scorecard

第 1 步：运行 SLDS Linter

运行 linter，收集基线违规数据：

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

按规则统计违规数量。这些数据会直接用于 Linter 合规性评分：

规则	影响
slds/class-override	破坏主题设置和深色模式
slds/lwc-token-to-slds-hook	SLDS 1 技术债务
slds/no-hardcoded-values	破坏主题设置和无障碍性

Linter 合规性得分 = 100 - (total_violations × 10)，最低为 0。

如果 linter 不可用（没有 Node.js、无法访问网络或受 CI 沙箱限制）：跳过此步骤，在报告标题中注明“未运行 Linter”，将 Linter 合规性标记为 N/A，并使用其余 4 个类别重新归一化至 100% 来计算总分：

Overall (linter unavailable) = (Theming × 0.29) + (Accessibility × 0.29)
                              + (CodeQuality × 0.21) + (ComponentUsage × 0.21)

第 2 步：运行补充分析

运行分析脚本，捕获 linter 未覆盖的问题。捆绑的分析器仅扫描 .css、.html 和 .js 文件：

node scripts/analyze-quality.cjs <component-path>

脚本会输出按严重性分类的 JSON 结果。检查项如下：

CSS 检查（补充 linter 检查）

检查项	检查内容	严重性
缺少回退值	var(--slds-g-*) 未提供回退值	严重
自定义 Hooks（T051）	在 hooks-index.json 中找不到的 --slds-g-* 令牌（需要 --hooks-index）	严重
Hook 配对	背景 Hook 缺少匹配的前景 Hook	警告
!important	特异性覆盖	警告
魔法像素值	使用硬编码的 px，而未使用间距 Hook	警告
高 z-index	z-index 值 > 99	警告
移除轮廓	使用 outline: none，但未提供替代焦点样式	警告

JS 检查

检查项	检查内容	严重性
内联样式赋值	直接赋值 .style.*= 属性	警告
SLDS 类操作	动态操作 .classList.add('slds-*')	警告

HTML 检查

检查项	检查内容	严重性
LBC 输入标签	<lightning-input> 缺少 label 属性	严重
图标替代文本	<lightning-icon> 缺少 alternative-text	严重
图片替代文本	<img> 缺少 alt	严重
标题层级	跳过标题级别（从 h2 跳到 h4）	警告
正数 tabindex	tabindex 值不是 0 或 -1	警告
可点击的 div	使用 <div onclick> 而非 <button>	警告
内联样式	style="..." 属性	警告
原生元素	存在 LBC 替代项时仍使用 <input>、<button>、<select>	警告

Hook 配对验证

脚本会检查背景/前景 Hook 在语义上是否配对：

surface-* backgrounds     → on-surface-* text
surface-container-* bg    → on-surface-* text
accent-* backgrounds      → on-accent-* text
accent-container-* bg     → on-accent-* text

**限制：**Hook 配对检查以文件为单位，而非按选择器检查。如果文件在 .classA 中包含 surface-1，并在 .classB 中包含 on-accent-1，检查仍会通过，因为文件中包含 surface 和 accent 两个系列。请在人工审核期间（第 3 步）逐个选择器检查配对是否正确。

虚构 Hook 检测（T051）

该脚本会将 CSS 中的每个 --slds-g-* 标记与 hooks-index.json 交叉比对。任何未在元数据中找到的 Hook 都会被标记为严重问题——这能发现 Agent 最常见的错误：根据命名模式虚构 Hook。

步骤 3：Agent 人工审核

这些检查需要理解组件的用途，无法可靠地自动化。逐项审核，并将发现的问题归类为：

• 阻塞性 — 蓝图结构错误、缺少必需状态，或存在导致组件无法用于生产环境的语义／交互问题
• 建议性 — 值得改进，但单凭这些问题不会阻碍发布

审核领域	检查内容
加载状态	获取数据时，组件是否显示微调器或骨架屏？
错误状态	是否向用户显示错误，并提供可采取措施的信息？
空状态	没有数据时，是否提供有意义的空状态？
禁用状态	交互元素是否在视觉和功能上正确处理禁用状态？
语义化 HTML	是否在适当的位置使用了 <nav>、<article>、<section>？
SLDS 蓝图合规性	卡片、模态框和表单是否遵循 SLDS 蓝图结构？

人工审核发现不会自动化处理，但会影响最终建议。不要只报告自动化评分作为唯一结论。

步骤 4：计算自动化评分并给出最终建议

组件复杂度

评分前，先对组件进行分类，为评分提供背景：

复杂度	标准	报告说明
小型	1-2 个文件，总行数 < 100	评分可信度高（范围较小）
中型	3-6 个文件，总行数为 100-500	评分反映典型组件的水平
大型	7 个或更多文件，总行数为 500 或更多	评分反映问题绝对数量——即使构建良好的大型组件，评分也可能较低

在报告标题中注明复杂度分类。这有助于避免误读 1000 行组件的“B”与 20 行组件的“B”。

自动化评分公式

Category Score = 100 - (critical_issues × 10) - (warnings × 3) - (info × 1)
Minimum score: 0

类别和权重

类别	权重	来源
Linter 合规性	30%	SLDS linter 输出（步骤 1）
主题化	20%	脚本：回退值、Hook 配对（步骤 2）
无障碍性	20%	脚本：标签、替代文本、焦点（步骤 2）
代码质量	15%	脚本：!important、内联样式、z-index（步骤 2）
组件用法	15%	脚本：原生元素（步骤 2），以及人工语义／蓝图审核（步骤 3）

自动化总分

Overall = (Linter × 0.30) + (Theming × 0.20) + (Accessibility × 0.20)
        + (CodeQuality × 0.15) + (ComponentUsage × 0.15)

自动化等级阈值

分数	等级	含义
90-100	A	自动化评分优秀
80-89	B	自动化评分良好
70-79	C	自动化评分合格
60-69	D	自动化评分较弱
0-59	F	自动化评分不合格

人工审核门槛

计算出自动化评分后，根据人工审核结果进行判断：

门槛	使用条件	对最终建议的影响
通过	没有人工审核发现的问题	最终建议可依据自动化评分
建议性	仅有非阻塞性人工审核发现的问题	最终建议最高为“可发布，但需跟进”
阻塞性	存在一个或多个阻塞性人工审核发现的问题	无论自动化等级如何，最终建议均为尚不适合用于生产环境

最终建议规则

综合自动化评分和人工审核门槛：

最终建议	条件
可用于生产环境	自动化等级为 A/B、没有严重问题，且人工审核门槛 = 通过
可发布，但需跟进	自动化等级为 A/B、没有严重问题，且人工审核门槛 = 建议性
需要改进	存在任何严重问题、自动化等级为 C/D，或人工审核门槛 = 阻塞性
不合格	自动化等级为 F

第 5 步：生成质量报告

使用 report-format.md 中的模板生成最终报告。初始输出默认采用精简格式，并根据请求展开各个部分。

报告包括：

• 执行摘要，包含自动评级和最终建议
• 人工审核关卡结果（Pass、Advisory 或 Blocking）
• 各类别的评分及可视化指示
• 按严重程度组织的详细发现
• 具体代码位置和建议
• 必要操作清单

---

快速验证模式

如需快速质量检查而不进行完整分析：

1. 运行检查程序：npx @salesforce-ux/slds-linter@latest lint <path>
2. 按类型统计违规项
3. 仅报告摘要

Quick Quality Check: <component-name>
─────────────────────────────────────
Linter Violations:
  • Class Override:     0
  • Deprecated Tokens:  3
  • Hardcoded Values:   5

Quick Automated Grade: C (estimated)
Run full validation for detailed report.

---

边缘情况和误报

情况	指引
无头组件（仅 JS，没有 HTML）	跳过 HTML 检查；仅对 CSS 和检查程序类别评分
包装器／容器组件	CSS 极少也可能完全合理；不要因钩子使用率低而扣分
有意使用原生元素	自定义 SLDS 蓝图中的 <button> 是正确的；如果位于 slds-* 蓝图结构中，则抑制 C002
LEX 之外的组件	LWR／Experience Cloud 组件可能不会使用 Lightning Base Components；在报告中注明上下文
测试／演示组件	降低标准——在报告中注明，但不要因警告而阻止

如果检查产生误报，请在报告中注明为“suppressed”，并说明理由，而不是默默忽略。

---

参考资料

• 质量检查 - 所有质量检查及检测模式的完整列表
• 报告格式 - 质量报告模板和格式指南
• 分析脚本 - 用于检查程序补充检查的自动化分析
• uplifting-components-to-slds2 技能 - 如何修复检查程序违规项
• applying-slds 技能 - 使用正确模式构建新组件的指南