mcpField
S
scan-code-accessibility-figma

scan-code-accessibility-figma

github.com/southleft测试与质量2068 次安装21 周前更新
代码仓库

关于 scan-code-accessibility-figma

scan-code-accessibility-figma 使用 axe-core 和 JSDOM 扫描 HTML 的结构与语义无障碍问题，适用于 Figma 转代码工作流。它可输出用于设计一致性检查的数据；由于 JSDOM 没有布局引擎，因此不检查视觉规则。

主要功能

  1. 01使用 axe-core 扫描 HTML
  2. 02按 WCAG 标签筛选
  3. 03限定 CSS 选择器范围
  4. 04以 JSON 报告违规项
  5. 05输出 codeSpec 无障碍数据

适用场景

  1. 01检查生成组件 HTML 的无障碍性
  2. 02查找缺失的标签、角色或替代文本
  3. 03仅检查指定组件
  4. 04为一致性检查准备无障碍数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/southleft/skills-for-figma --skill scan-code-accessibility-figma

安装后在 Claude Code 中输入/scan-code-accessibility-figma确认已加载。

附带文件scripts/package.jsonscripts/scan.mjs

详细介绍

scan-code-accessibility-figma — 使用 axe-core + JSDOM 扫描 HTML

使用 JSDOM 对 HTML 字符串运行 axe-core（Deque 的无障碍引擎）。这是无障碍实践中的代码侧：它会检查 Figma 到代码工作流生成的标记。它与 lint-design-figma（设计侧）配合，覆盖两端。

这不是 use_figma 技能。 它在纯 Node 中运行——无需 Figma 文件，也无需 Plugin API。规则数据库由 axe-core 管理；本技能绝不会自行编造规则。

技能边界

  • 设计侧视觉无障碍（对比度、焦点环、目标尺寸、仅依赖颜色）→ 使用 lint-design-figma。这些规则在此处特意禁用。
  • 单个组件的设计评分卡 → 使用 audit-accessibility-figma。
  • 设计与代码的匹配度 → 使用 check-design-parity-figma（将本次扫描可输出的 codeSpec.accessibility 传给它）。
  • 本技能不使用 use_figma，因此 figma-use 约定不适用。

为什么禁用视觉规则

JSDOM 提供 DOM，但没有布局引擎，也无法获取计算后的视觉样式——没有可用于测量的像素或渲染颜色。因此，axe 的视觉规则始终会给出“未完成”或错误的结果。本次扫描会明确禁用这些规则：

  • color-contrast 和 color-contrast-enhanced — 需要渲染后的颜色。
  • link-in-text-block — 需要周围文本的布局。
  • target-size — 需要渲染后的盒模型尺寸。

所有结构和语义规则（ARIA、角色、名称、标签、alt、标题、地标、lang、重复 ID、tabindex，共约 50 条规则）都会正常运行。对于视觉方面，请对设计运行 lint-design-figma。

用法

  1. 安装一次依赖（在此技能的 scripts/ 目录中）： 
    cd scripts && npm install
    安装 axe-core 和 jsdom。
  2. 运行扫描，检查 HTML 文件或内联字符串： 
    node scan.mjs path/to/component.html
node scan.mjs --html '<button>Save</button>'
    可选标志：
    • --tags wcag22aa — 按 WCAG 标签集筛选（wcag2a、wcag2aa、wcag21aa、wcag22aa、best-practice）。可重复使用或用逗号分隔。
    • --context '#my-component' — 将扫描范围限制为 CSS 选择器。
    • --include-passing — 包含通过、不完整和不适用规则的数量。
    • --map-to-codespec — 同时输出 codeSpecAccessibility 对象（语义元素、角色、aria-label、focusVisible、键盘交互、禁用/错误状态支持），可直接放入 check-design-parity-figma 的 codeSpec.accessibility。
  3. 读取 stdout 中的 JSON：按规则分组的违规项，包含 severity（根据 axe 的 impact 映射为 critical/warning/info）、wcagTags、helpUrl，以及每条规则最多 10 个问题节点，另附 summary。

扫描前，纯 HTML 片段会自动包装为 <!DOCTYPE html><html lang="en">…<body>…。

输出格式

{
  "engine": "axe-core", "version": "4.x", "mode": "jsdom-structural",
  "note": "JSDOM mode: structural/semantic checks only. Visual rules disabled — use lint-design-figma.",
  "categories": [ { "rule": "button-name", "severity": "critical", "count": 1, "description": "...", "wcagTags": ["wcag2a","wcag412"], "helpUrl": "...", "nodes": [ { "html": "...", "target": ["button"], "failureSummary": "..." } ] } ],
  "summary": { "critical": 1, "warning": 0, "info": 0, "total": 1 }
}

严重性映射：axe 的 critical/serious → critical，moderate → warning，minor → info。

评论

支持 Markdown