SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场validating-slds

validating-slds

测试与质量

查看项目

更新于 10-15 14:07

技能介绍

用途

该技能用于审计 Lightning Web Components 是否符合 SLDS（Salesforce Lightning Design System）规范，并生成自动评分卡与必需的人工复核关卡。它结合 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. 运行 SLDS Linter：收集违规计数。运行命令：npx @salesforce-ux/slds-linter@latest lint <component-path> 2>&1。按规则统计违规。Linter 合规分 = 100 - (总违规数 × 10)，最低 0。若 linter 不可用（无 Node.js、无网络、CI 沙箱限制），跳过此步，在报告头注明“Linter not run”，将 Linter 合规标记为 N/A，并用其余 4 个类别重新归一化计算总分：Overall (linter unavailable) = (Theming × 0.29) + (Accessibility × 0.29) + (CodeQuality × 0.21) + (ComponentUsage × 0.21)。

  2. 运行补充分析：运行 node scripts/analyze-quality.cjs <component-path>。脚本仅扫描 .css、.html 和 .js 文件，输出按严重程度组织的 JSON 结果。

CSS 检查（补充 linter）：缺失回退值（var(--slds-g-) 无回退，Critical）；虚构钩子 T051（--slds-g- 未在 hooks-index.json 中找到，需 --hooks-index，Critical）；钩子配对（背景钩子无匹配前景钩子，Warning）；!important（Warning）；魔法像素值（硬编码 px 未使用间距钩子，Warning）；高 z-index（> 99，Warning）；移除轮廓（outline: none 无替代焦点样式，Warning）。

JS 检查：内联样式赋值（.style.= 直接属性赋值，Warning）；SLDS 类操作（动态 .classList.add('slds-')，Warning）。

HTML 检查：LBC 输入标签（<lightning-input> 无 label 属性，Critical）；图标替代文本（<lightning-icon> 无 alternative-text，Critical）；图片替代文本（<img> 无 alt，Critical）；标题层级（跳过标题级别，Warning）；正 tabindex（非 0 或 -1，Warning）；可点击 div（<div onclick> 而非 <button>，Warning）；内联样式（style="..."，Warning）；原生元素（<input>、<button>、<select> 存在 LBC 替代时，Warning）。

钩子配对验证：检查背景/前景钩子语义配对，如 surface-* 背景 → on-surface-* 文本；surface-container-* 背景 → on-surface-* 文本；accent-* 背景 → on-accent-* 文本；accent-container-* 背景 → on-accent-* 文本。限制：配对在文件级别检查，非按选择器。

虚构钩子检测（T051）：将 CSS 中每个 --slds-g-* 令牌与 hooks-index.json 交叉引用，未找到的标记为 Critical。

  1. 代理人工复核：需理解组件用途，无法可靠自动化。将发现分类为 Blocking（蓝图结构错误、缺少必需状态或语义/交互问题）或 Advisory（非阻塞改进）。复核领域：加载状态、错误状态、空状态、禁用状态、语义 HTML、SLDS 蓝图合规性。

  2. 计算自动评分与最终建议：先分类组件复杂度（Small：1-2 文件，<100 行；Medium：3-6 文件，100-500 行；Large：7+ 文件，500+ 行）。类别分 = 100 - (critical_issues × 10) - (warnings × 3) - (info × 1)，最低 0。类别与权重：Linter 合规 30%、Theming 20%、Accessibility 20%、Code Quality 15%、Component Usage 15%。总分 = (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。人工复核关卡：Pass（无人工发现）、Advisory（仅非阻塞发现）、Blocking（一个或多个阻塞发现）。最终建议规则：Ready for production（A/B，无 critical，Pass）；Ready with follow-ups（A/B，无 critical，Advisory）；Needs work（任何 critical、C/D 或 Blocking）；Failing（F）。

  3. 生成质量报告：使用 report-format.md 模板，默认紧凑格式。报告包括执行摘要、人工复核关卡结果、各类别评分、按严重程度组织的详细发现、具体代码位置与建议、必需操作清单。

快速验证模式：运行 linter，按类型统计违规，仅报告摘要。

使用方式

运行 SLDS linter：npx @salesforce-ux/slds-linter@latest lint <component-path> 2>&1。运行补充分析：node scripts/analyze-quality.cjs <component-path>。人工复核后按公式计算评分并生成报告。

适用场景

审计项目或组件集的 SLDS 合规性；修改前后的质量对比；需要自动评分卡与人工复核关卡的质量验证。

限制

不修复违规；不构建新组件；不执行完整 WCAG 审计（仅检查属性存在性）；不审计 .css、.html、.js 之外的框架特定模板；钩子配对在文件级别检查，非按选择器；linter 不可用时需重新归一化评分。边缘情况与误报处理：无头组件跳过 HTML 检查；包装/容器组件可能合法地有最少 CSS；自定义 SLDS 蓝图内的原生元素可抑制 C002；LEX 外组件可能不使用 LBC；测试/演示组件降低标准。误报应在报告中注明“suppressed”并说明理由。