design-systems-slds-validate

SLDS 质量审计

审计 Lightning Web Components 是否符合 SLDS，并生成自动化评分卡以及必需的人工审核关卡。结合 SLDS linter 输出与补充静态分析，捕获 linter 遗漏的问题。

范围

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

不适用于：

• 修复 linter 违规 — 请改用 design-systems-slds2-migrate
• 构建新组件 — 请改用 design-systems-slds-apply
• 仅运行 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-*)	严重
自创 Hook（T051）	hooks-index.json 中不存在的 --slds-g-* 令牌（需要 --hooks-index）	严重
Hook 配对	没有匹配前景 Hook 的背景 Hook	警告
!important	特异性覆盖	警告
魔法像素值	未使用间距 Hook 的硬编码 px 值	警告
高 z-index	大于 99 的 z-index 值	警告
移除轮廓	没有替代焦点样式的 outline: none	警告

JS 检查

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

HTML 检查

检查项	检测内容	严重性
LBC 输入标签	没有 label 属性的 <lightning-input>	严重
图标替代文本	没有 alternative-text 的 <lightning-icon>	严重
图片替代文本	没有 alt 的 <img>	严重
标题层级	跳过标题级别（从 h2 跳到 h4）	警告
正值 tabindex	值不是 0 或 -1 的 tabindex	警告
可点击的 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. 运行 linter：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 和 linter 类别评分
包装器／容器组件	CSS 较少可能是合理的；不要因钩子使用率低而扣分
有意使用原生元素	自定义 SLDS 蓝图中的 <button> 是正确的；如果它位于 slds-* 蓝图结构中，则抑制 C002
LEX 以外的组件	LWR／Experience Cloud 组件可能不会使用 Lightning Base Components；在报告中注明上下文
测试／演示组件	放宽标准——在报告中注明，但不要因警告而阻止

如果某项检查产生误报，请在报告中说明其为“已抑制”，并给出理由，而不是悄然忽略。

---

参考资料

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