design-systems-slds-validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SLDS Quality Audit

SLDS质量审计

Audit Lightning Web Components for SLDS compliance and produce an automated scorecard plus a required manual review gate. Combines SLDS linter output with supplementary static analysis to catch what the linter misses.

审计Lightning Web Components（LWC）的SLDS合规性，生成自动化评分卡并设置必要的人工审核关卡。结合SLDS linter输出结果与补充静态分析，捕捉linter未检测到的问题。

Scope

适用范围

Also valid for: auditing SLDS compliance across a project or component set, and before/after quality comparison after making changes.

Not for:

Fixing linter violations — use
```
design-systems-slds2-migrate
```
instead
Building new components — use
```
design-systems-slds-apply
```
instead

Just running the linter — run

npx @salesforce-ux/slds-linter@latest lint .

directly

Full WCAG accessibility audit — this skill checks attribute presence only (labels, alt text, focus indicators), not contrast ratios, keyboard flows, or screen reader behavior
Framework-specific template auditing beyond
```
.css
```
,
```
.html
```
, and
```
.js
```
files — JSX/TSX/Vue/Svelte outputs need additional manual review

同样适用于：跨项目或组件集审计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输出需额外人工审核

Quality Validation Process

质量验证流程

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的任务）
2. 运行分析脚本        → 检查linter未覆盖的内容（补充分析）
3. 人工审核           → 必要的人工审核关卡
4. 评分与评级         → 计算自动化分数 + 最终建议
5. 生成报告           → 生成格式化评分卡

Step 1: Run SLDS Linter

步骤1：运行SLDS Linter

Run the linter to collect baseline violation data:

bash

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

Count violations by rule. These feed directly into the Linter Compliance score:

Rule	Impact
`slds/class-override`	Breaks theming, dark mode
`slds/lwc-token-to-slds-hook`	SLDS 1 technical debt
`slds/no-hardcoded-values`	Breaks theming, accessibility

Linter Compliance Score =

100 - (total_violations × 10)

, minimum 0.

If the linter is unavailable (no Node.js, no network access, CI sandbox restrictions): skip this step, note "Linter not run" in the report header, mark Linter Compliance as N/A, and compute the Overall score using the remaining 4 categories renormalized to 100%:

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

运行linter以收集基准违规数据：

bash

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 - (总违规数 × 10)

，最低为0。

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

整体得分（linter不可用） = (主题 × 0.29) + (可访问性 × 0.29)
                              + (代码质量 × 0.21) + (组件使用 × 0.21)

Step 2: Run Supplementary Analysis

步骤2：运行补充分析

Run the analyze script to catch issues the linter doesn't cover. The bundled analyzer scans

.css

.html

, and

.js

files only:

bash

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

The script outputs JSON with findings organized by severity. It checks:

运行分析脚本以捕捉linter未覆盖的问题。内置分析器仅扫描

.css

、

.html

和

.js

文件：

bash

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

脚本输出按严重程度分类的检测结果JSON。它会检查以下内容：

CSS Checks (linter-complementary)

CSS检查（补充linter）

Check	What It Catches	Severity
Missing fallbacks	`var(--slds-g-*)` without a fallback value	Critical
Invented hooks (T051)	`--slds-g-*` tokens not found in `hooks-index.json` (requires `--hooks-index` )	Critical
Hook pairing	Background hooks without matching foreground hooks	Warning
`!important`	Specificity overrides	Warning
Magic pixel values	Hardcoded `px` not using spacing hooks	Warning
High z-index	z-index values > 99	Warning
Outline removal	`outline: none` without alternative focus style	Warning

检查项	检测内容	严重程度
缺少回退值	`var(--slds-g-*)` 未设置回退值	严重
自定义钩子（T051）	`--slds-g-*` 令牌未在 `hooks-index.json` 中找到（需使用 `--hooks-index` 参数）	严重
钩子配对	背景钩子未匹配对应的前景钩子	警告
`!important`	优先级覆盖	警告
魔法像素值	硬编码 `px` 未使用间距钩子	警告
高z-index值	z-index值 > 99	警告
移除轮廓	`outline: none` 未设置替代焦点样式	警告

JS Checks

JS检查

Check	What It Catches	Severity
Inline style assignment	`.style.*=` direct property assignment	Warning
SLDS class manipulation	Dynamic `.classList.add('slds-*')` manipulation	Warning

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

HTML Checks

HTML检查

Check	What It Catches	Severity
LBC input labels	`<lightning-input>` without `label` attribute	Critical
Icon alt text	`<lightning-icon>` without `alternative-text`	Critical
Image alt text	`<img>` without `alt`	Critical
Heading hierarchy	Skipped heading levels (h2 to h4)	Warning
Positive tabindex	`tabindex` values other than 0 or -1	Warning
Clickable divs	`<div onclick>` instead of `<button>`	Warning
Inline styles	`style="..."` attributes	Warning
Native elements	`<input>` , `<button>` , `<select>` where LBC alternatives exist	Warning

检查项	检测内容	严重程度
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 Pairing Validation

钩子配对验证

The script checks that background/foreground hooks are semantically paired:

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

Limitation: Hook pairing is checked at the file level, not per-selector. A file with
surface-1
in
.classA
and
on-accent-1
in
.classB
would pass because both surface and accent families are present. Review pairing correctness per-selector during manual review (Step 3).

脚本会检查背景/前景钩子是否语义配对：

surface-* 背景 → on-surface-* 文本
surface-container-* 背景 → on-surface-* 文本
accent-* 背景 → on-accent-* 文本
accent-container-* 背景 → on-accent-* 文本

局限性： 钩子配对在文件级别检查，而非选择器级别。若某个文件中
.classA
包含
surface-1
，
.classB
包含
on-accent-1
，则会通过检查，因为surface和accent系列均存在。需在人工审核（步骤3）中按选择器检查配对正确性。

Invented Hook Detection (T051)

自定义钩子检测（T051）

The script cross-references every

--slds-g-*

token in CSS against

hooks-index.json

. Any hook not found in metadata is flagged as critical — this catches the most common agent mistake of inventing hooks from naming patterns.

脚本会将CSS中所有

--slds-g-*

令牌与

hooks-index.json

交叉比对。任何未在元数据中找到的钩子都会被标记为严重问题——这能捕捉到最常见的人工错误：根据命名模式自定义钩子。

Step 3: Agent Manual Review

步骤3：人工审核

These checks require understanding the component's purpose and cannot be automated reliably. Review each and classify findings as either:

Blocking — incorrect blueprint structure, missing required states, or semantic/interaction issues that make the component not production-ready
Advisory — worthwhile improvements that do not block shipping on their own

Review Area	What to Look For
Loading states	Does the component show a spinner or skeleton when fetching data?
Error states	Are errors surfaced to the user with actionable messages?
Empty states	Is there a meaningful empty state when no data exists?
Disabled states	Do interactive elements visually and functionally handle disabled?
Semantic HTML	Are `<nav>` , `<article>` , `<section>` used where appropriate?
SLDS blueprint compliance	Do cards, modals, forms follow SLDS blueprint structure?

Manual review findings are not automated, but they do affect the final recommendation. Do not report an automated grade as the only verdict.

这些检查需要理解组件的用途，无法可靠自动化。逐一检查并将检测结果分类为：

阻塞性 —— 蓝图结构错误、缺少必要状态，或语义/交互问题导致组件无法投入生产
建议性 —— 值得改进，但不单独影响发布

审核领域	检查内容
加载状态	组件在获取数据时是否显示加载动画或骨架屏？
错误状态	是否向用户展示错误信息并提供可操作建议？
空状态	无数据时是否显示有意义的空状态？
禁用状态	交互元素是否在视觉和功能上正确处理禁用状态？
语义化HTML	是否在合适的场景使用 `<nav>` 、 `<article>` 、 `<section>` ？
SLDS蓝图合规性	卡片、模态框、表单是否遵循SLDS蓝图结构？

人工审核结果无法自动化，但会影响最终建议。请勿仅以自动化评级作为唯一结论。

Step 4: Calculate Automated Scores and Final Recommendation

步骤4：计算自动化分数与最终建议

Component Complexity

组件复杂度

Before scoring, classify the component to give the score context:

Complexity	Criteria	Report Note
Small	1-2 files, < 100 total lines	Score is high-confidence (small surface area)
Medium	3-6 files, 100-500 total lines	Score reflects typical component
Large	7+ files, 500+ total lines	Score reflects absolute issue count — even well-built large components may score lower

Include the complexity classification in the report header. This prevents misreading a "B" on a 1000-line component vs. a "B" on a 20-line component.

评分前先对组件分类，为分数提供上下文：

复杂度	判定标准	报告备注
小型	1-2个文件，总代码行数<100	分数可信度高（影响范围小）
中型	3-6个文件，总代码行数100-500	分数反映典型组件情况
大型	7个及以上文件，总代码行数500+	分数反映绝对问题数量——即使构建良好的大型组件分数也可能较低

在报告标题中包含复杂度分类，避免误读：比如1000行组件的“B”级与20行组件的“B”级意义不同。

Automated Scoring Formula

自动化评分公式

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

类别得分 = 100 - (严重问题数 × 10) - (警告数 × 3) - (信息提示数 × 1)
最低得分：0

Categories and Weights

类别与权重

Category	Weight	Source
Linter Compliance	30%	SLDS linter output (Step 1)
Theming	20%	Script: fallbacks, hook pairing (Step 2)
Accessibility	20%	Script: labels, alt text, focus (Step 2)
Code Quality	15%	Script: !important, inline styles, z-index (Step 2)
Component Usage	15%	Script: native elements (Step 2) plus manual semantic/blueprint review (Step 3)

类别	权重	数据来源
Linter合规性	30%	SLDS linter输出（步骤1）
主题	20%	脚本：回退值、钩子配对（步骤2）
可访问性	20%	脚本：标签、替代文本、焦点（步骤2）
代码质量	15%	脚本：!important、内联样式、z-index（步骤2）
组件使用	15%	脚本：原生元素（步骤2） + 人工语义/蓝图审核（步骤3）

Automated Overall Score

自动化整体得分

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

整体得分 = (Linter合规性 × 0.30) + (主题 × 0.20) + (可访问性 × 0.20)
        + (代码质量 × 0.15) + (组件使用 × 0.15)

Automated Grade Thresholds

自动化评级阈值

Score	Grade	Meaning
90-100	A	Excellent automated score
80-89	B	Good automated score
70-79	C	Acceptable automated score
60-69	D	Weak automated score
0-59	F	Failing automated score

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

Manual Review Gate

人工审核关卡

After computing the automated score, apply the manual review outcome:

Gate	When to use it	Effect on final recommendation
Pass	No manual findings	Final recommendation can follow the automated score
Advisory	Only non-blocking manual findings	Final recommendation can be "Ready with follow-ups" at best
Blocking	One or more blocking manual findings	Final recommendation is not ready for production, regardless of automated grade

计算自动化分数后，结合人工审核结果：

关卡状态	适用场景	对最终建议的影响
通过	无人工检测问题	最终建议可遵循自动化分数
建议性	仅存在非阻塞性人工检测问题	最终建议最高为“可发布，需后续优化”
阻塞性	存在一个或多个阻塞性人工检测问题	最终建议为不可投入生产，无论自动化评级如何

Final Recommendation Rules

最终建议规则

Use both the automated score and the manual review gate:

Final Recommendation	Conditions
Ready for production	Automated grade A/B, no critical findings, manual gate = Pass
Ready with follow-ups	Automated grade A/B, no critical findings, manual gate = Advisory
Needs work	Any critical findings, automated grade C/D, or manual gate = Blocking
Failing	Automated grade F

结合自动化分数与人工审核关卡结果：

最终建议	条件
可投入生产	自动化评级A/B，无严重问题，人工审核关卡=通过
可发布，需后续优化	自动化评级A/B，无严重问题，人工审核关卡=建议性
需要优化	存在任何严重问题、自动化评级C/D，或人工审核关卡=阻塞性
不合格	自动化评级F

Step 5: Generate Quality Report

步骤5：生成质量报告

Use the template in report-format.md to produce the final report. Default to the compact format for initial output and expand sections on request.

The report includes:

Executive summary with automated grade and final recommendation
Manual review gate outcome (
```
Pass
```
,
```
Advisory
```
, or
```
Blocking
```
)
Scores by category with visual indicators
Detailed findings organized by severity
Specific code locations and recommendations
Checklist of required actions

使用**report-format.md中的模板生成最终报告。默认输出紧凑格式**，按需展开章节。

报告包含：

自动化评级与最终建议的执行摘要
人工审核关卡结果（
```
通过
```
、
```
建议性
```
或
```
阻塞性
```
）
带视觉标识的各类别得分
按严重程度分类的详细检测结果
具体代码位置与建议
必要操作清单

Quick Validation Mode

快速验证模式

For a rapid quality check without full analysis:

Run linter:

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

Count violations by type
Report summary only

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.

无需完整分析的快速质量检查：

运行linter：

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

按类型统计违规数量
仅报告摘要

快速质量检查：<component-name>
─────────────────────────────────────
Linter违规情况：
  • Class Override:     0
  • Deprecated Tokens:  3
  • Hardcoded Values:   5

快速自动化评级：C（估算）
运行完整验证以获取详细报告。

Edge Cases and False Positives

边缘情况与误报

Situation	Guidance
Headless components (JS-only, no HTML)	Skip HTML checks; score only CSS + linter categories
Wrapper/container components	May legitimately have minimal CSS; don't penalize low hook usage
Intentional native elements	`<button>` inside custom SLDS blueprints is correct; suppress C002 if inside an `slds-*` blueprint structure
Components outside LEX	LWR/Experience Cloud components may not use Lightning Base Components; note context in report
Test/demo components	Lower the bar — note in report but don't block on warnings

If a check produces a false positive, note it in the report as "suppressed" with justification rather than silently dropping it.

场景	处理指南
无头组件（仅JS，无HTML）	跳过HTML检查；仅对CSS + linter类别评分
包装器/容器组件	可能合理使用少量CSS；不要因钩子使用率低而扣分
有意使用原生元素	在自定义SLDS蓝图内使用 `<button>` 是正确的；若位于 `slds-*` 蓝图结构内，可抑制C002警告
LEX外的组件	LWR/Experience Cloud组件可能不使用Lightning Base Components；在报告中注明上下文
测试/演示组件	降低标准——在报告中注明，但不因警告阻止发布

若检查出现误报，请在报告中注明“已抑制”并说明理由，而非直接忽略。

References

参考资料

Quality Checks - Complete list of all quality checks with detection patterns
Report Format - Quality report template and formatting guide
Analyze Script - Automated analysis for linter-complementary checks
design-systems-slds2-migrate skill - How to fix linter violations
design-systems-slds-apply skill - Guide for building new components with correct patterns

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