Back to Details

validating-slds

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的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 
    uplifting-components-to-slds2
    instead
  • Building new components — use 
    applying-slds
    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违规问题 —— 请改用
    uplifting-components-to-slds2
  • 构建新组件 —— 请改用
    applying-slds
  • 仅运行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:
RuleImpact
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）

CheckWhat It CatchesSeverity
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 pairingBackground hooks without matching foreground hooksWarning
!important
Specificity overridesWarning
Magic pixel valuesHardcoded 
px
not using spacing hooks		Warning
High z-indexz-index values > 99Warning
Outline removal
outline: none
without alternative focus style		Warning
检查项检测内容严重程度
缺失回退值
var(--slds-g-*)
未设置回退值		严重
自定义钩子（T051）
--slds-g-*
令牌未在
hooks-index.json
中找到（需
--hooks-index
参数）		严重
钩子配对背景钩子未匹配对应前景钩子警告
!important
优先级覆盖警告
魔法像素值硬编码
px
未使用间距钩子		警告
高z-indexz-index值>99警告
移除轮廓
outline: none
未设置替代焦点样式		警告

JS Checks

JS检查

CheckWhat It CatchesSeverity
Inline style assignment
.style.*=
direct property assignment		Warning
SLDS class manipulationDynamic 
.classList.add('slds-*')
manipulation		Warning
检查项检测内容严重程度
内联样式赋值
.style.*=
直接属性赋值		警告
SLDS类操作动态
.classList.add('slds-*')
操作		警告

HTML Checks

HTML检查

CheckWhat It CatchesSeverity
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 hierarchySkipped 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 AreaWhat to Look For
Loading statesDoes the component show a spinner or skeleton when fetching data?
Error statesAre errors surfaced to the user with actionable messages?
Empty statesIs there a meaningful empty state when no data exists?
Disabled statesDo interactive elements visually and functionally handle disabled?
Semantic HTMLAre 
<nav>
, 
<article>
, 
<section>
used where appropriate?
SLDS blueprint complianceDo 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:
ComplexityCriteriaReport Note
Small1-2 files, < 100 total linesScore is high-confidence (small surface area)
Medium3-6 files, 100-500 total linesScore reflects typical component
Large7+ files, 500+ total linesScore 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

分类与权重

CategoryWeightSource
Linter Compliance30%SLDS linter output (Step 1)
Theming20%Script: fallbacks, hook pairing (Step 2)
Accessibility20%Script: labels, alt text, focus (Step 2)
Code Quality15%Script: !important, inline styles, z-index (Step 2)
Component Usage15%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

自动化评级阈值

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

Manual Review Gate

人工审核关卡

After computing the automated score, apply the manual review outcome:
GateWhen to use itEffect on final recommendation
PassNo manual findingsFinal recommendation can follow the automated score
AdvisoryOnly non-blocking manual findingsFinal recommendation can be "Ready with follow-ups" at best
BlockingOne or more blocking manual findingsFinal recommendation is not ready for production, regardless of automated grade
计算自动化得分后，结合人工审核结果：
关卡状态适用场景对最终建议的影响
通过无人工审核问题最终建议可遵循自动化得分
建议性仅存在非阻塞性人工审核问题最终建议最高为「需跟进优化，可发布」
阻塞性存在一个或多个阻塞性人工审核问题无论自动化评级如何，最终建议为未就绪，不可投入生产

Final Recommendation Rules

最终建议规则

Use both the automated score and the manual review gate:
Final RecommendationConditions
Ready for productionAutomated grade A/B, no critical findings, manual gate = Pass
Ready with follow-upsAutomated grade A/B, no critical findings, manual gate = Advisory
Needs workAny critical findings, automated grade C/D, or manual gate = Blocking
FailingAutomated 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:
  1. Run linter: 
    npx @salesforce-ux/slds-linter@latest lint <path>
  2. Count violations by type
  3. 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.
无需完整分析的快速质量检查：
  1. 运行linter：
    npx @salesforce-ux/slds-linter@latest lint <path>
  2. 按类型统计违规数量
  3. 仅报告摘要
快速质量检查：<component-name>
─────────────────────────────────────
Linter违规：
  • 类覆盖：     0
  • 已弃用令牌：  3
  • 硬编码值：   5

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

Edge Cases and False Positives

边缘情况与误报

SituationGuidance
Headless components (JS-only, no HTML)Skip HTML checks; score only CSS + linter categories
Wrapper/container componentsMay 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 LEXLWR/Experience Cloud components may not use Lightning Base Components; note context in report
Test/demo componentsLower 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
  • uplifting-components-to-slds2 skill - How to fix linter violations
  • applying-slds skill - Guide for building new components with correct patterns
  • 质量检查 - 所有质量检查的完整列表与检测模式
  • 报告格式 - 质量报告模板与格式指南
  • 分析脚本 - 用于补充linter检查的自动化分析工具
  • uplifting-components-to-slds2技能 - 如何修复linter违规问题
  • applying-slds技能 - 正确构建新组件的指南