penpot-audit-accessibility

penpot-audit-accessibility — WCAG AA 审核工具

1. 标题 + 工作原理

penpot-audit-accessibility 会检查设计并报告无障碍问题。所有修改都必须通过 execute_code（此技能只读取）；使用 export_shape 进行视觉验证；使用 penpotUtils.shapeStructure 读取结构（完整工具列表：shared/penpot-mcp-tool-reference.md）。它会读取对象树（penpotUtils.shapeStructure/analyzeDescendants），根据解析后的填充计算 WCAG 对比度，检查尺寸和语义命名，并输出按严重程度排序的报告。它只提出建议，不会自动修复。

2. 最重要的一条规则

报告问题，不要暗中修复。 每个问题都要说明严重程度、影响、具体修复方案和置信度。验收标准（AA 对比度、目标尺寸）是硬性门槛——全部通过后，屏幕才能算“完成”。

3. Penpot MCP 工具参考

完整工具列表：shared/penpot-mcp-tool-reference.md。关键调用：使用 execute_code 搭配 penpotUtils.analyzeDescendants（收集文本/颜色/尺寸）；如有需要，使用 penpot.shapesColors(shapes)； 使用 export_shape 为报告采集证据。

4. Plugin API 基础知识

注意事项编号对应 shared/plugin-api-gotchas.md：

• #1 — 从 shape.fills/shape.strokes 中读取解析后的颜色（数组；其中的条目不可变）。文本颜色是 Text 图形的填充色。
• #5 — 从 shape.width/shape.height/shape.bounds 获取尺寸（只读；此技能不会调整尺寸）。
• 标题层级取决于语义图层名称（h1…h6）——如果图层未命名，建议先使用 penpot-rename-layers。
• 焦点/键盘顺序根据布局顺序 + 交互推断；这是启发式判断，需标明。
• 依赖不熟悉的签名前，先通过 penpot_api_info 验证。

5. 考虑 Token 的简报约定

• Context — 审核对象（页面/选区/组件）；产品界面。
• Objective — 唯一目标：“依据 WCAG 2.1 AA 审核 X”（如要求 AAA，则注明）。
• Inputs — 目标图形、符合性级别、已知例外。
• Constraints — 只读；不修改画布。
• Acceptance Criteria — 检查每个交互元素；对比度 4.5:1（普通文本）/ 3:1（大文本和 UI）；目标尺寸 ≥24×24（WCAG 2.2；主要目标需注明 44×44）；标题顺序正确；报告完整。

scope:deck（由 penpot-build-deck 构建的幻灯片，在 brief-to-deck 中评估）。 范围为演示文稿页面；每个名为 NN-… 的顶层画板即为一张幻灯片。调整规则：文本 ≥ 24 px，或文本 ≥ 18.67 px 且 fontWeight ≥ 700，视为大文本 → 3:1；较小文本 → 4.5:1（尤其要检查渐变/玻璃表面上的正文和说明文字——对渐变色标取平均值，并将结果标记为启发式判断）。跳过目标尺寸检查（演示文稿除导航外没有交互控件）。标题层级 = 每张幻灯片恰好一个 h1。报告中的 scope 设为演示文稿页面名称，并在每条发现中注明幻灯片名称。

请以无障碍专家的身份行事。

6. 强制工作流

阶段 0 — 检查。 high_level_overview；使用 scripts/collectAccessibilityData.js 收集数据（references/01-inspection.md）。

阶段 1 — 对比度。 scripts/checkColorContrast.js（references/02-contrast-checks.md）——文本与背景、UI 组件对比度。

阶段 2 — 尺寸。 scripts/checkTouchTargets.js（references/03-sizing-checks.md）——交互目标尺寸。

阶段 3 — 语义。 标题层级、标签/替代文本（来自语义名称）、键盘/焦点顺序启发式判断。

阶段 4 — 报告。 scripts/generateReport.js（references/04-report-generation.md）——按严重程度排序，可直接交接。✋ 检查点：呈现发现；如果收到修复要求，将安全修复转交给负责的技能（例如，由 penpot-foundations 处理 Token 替换），并进行审核。

7. 关键规则

1. 仅限只读；在此技能中绝不修改画布。
2. 每个问题都必须包含：严重程度（High/Med/Low）+ 问题 + 影响 + 修复方案 + 置信度。
3. 使用精确阈值：4.5:1 / 3:1；目标尺寸 ≥24×24（AA 2.2）。
4. 如果缺少命名，则标记标题层级检查不可靠，并建议先重命名。
5. 将键盘顺序等启发式检查明确标记为启发式；不要夸大置信度。
6. 不得悄悄缩小范围——如果进行了抽样，必须说明。

8. 领域架构

每个问题的报告架构：

{ severity, criterion (e.g. "1.4.3 Contrast"), element, current, required, fix, confidence }

另附摘要：按严重程度统计数量、每项标准的通过/失败情况，以及交接清单。

最终报告还必须按照 shared/report-schemas/accessibility-report.schema.json 输出为 JSON 对象——包括派生的 highOrMedium 计数（严重程度为 High 或 Medium 的发现数量；brief-to-screen 工作流会据此分支）——并同步写入运行台账。

9. 模式与策略

默认采用 建议模式（只读）。任何修复都将在“应用并审核”流程中委派给负责的技能。

10. 状态管理

台账位于 RUN_ID 下：phase、issues:[...]、sampled。保持轻量；此技能主要用于读取。

11. 用户检查点

阶段后	产物	询问
4 报告	严重程度报告 + export_shape 证据	现在修复（转交负责的技能）还是交接？

12. 命名约定

shared/naming-conventions.md — 语义化 HTML 名称有助于进行标题层级和标签检查。

13. 反合理化表

借口	错在哪里	应对措施（停止）
“对比度看起来没问题。”	目测不符合 WCAG 标准。	计算比例；与 4.5:1 / 3:1 比较。
“我就悄悄自己修一下。”	此技能仅供只读参考。	报告严重程度；将修复转交负责的技能并进行审核。
“目标尺寸应该够大。”	猜测无法满足 AA 2.2。	测量宽度/高度；与 ≥24×24 比较。
“从尺寸就能看出标题层级。”	视觉尺寸 ≠ 语义顺序。	检查语义名称；如果缺少，建议使用 penpot-rename-layers。
“跳过键盘顺序吧，这很难判断。”	不说明遗漏会造成误导。	给出启发式顺序，并明确标注置信度。

14. 辅助代码片段

// WCAG relative luminance + contrast ratio
function lum(hex){const c=hex.replace('#','');const v=[0,2,4].map(i=>parseInt(c.substr(i,2),16)/255)
  .map(u=>u<=0.03928?u/12.92:Math.pow((u+0.055)/1.055,2.4));return 0.2126*v[0]+0.7152*v[1]+0.0722*v[2];}
function ratio(a,b){const L1=lum(a),L2=lum(b);const hi=Math.max(L1,L2),lo=Math.min(L1,L2);return (hi+0.05)/(lo+0.05);}
return { example: Number(ratio('#101114','#F7F8FA').toFixed(2)) }; // ~ AA pass

15. 参考资源

• WCAG 2.1/2.2 SC 1.4.3（对比度）、2.5.8（目标尺寸）、1.3.1（信息与关系）、2.4.3（焦点顺序）。
• penpot_api_info('Text')、penpot_api_info('Shape','fills')。

16. 支持文件

references/：01-inspection.md、02-contrast-checks.md、03-sizing-checks.md、04-report-generation.md。 scripts/：collectAccessibilityData.js、checkColorContrast.js、checkTouchTargets.js、generateReport.js。

Doctrine 路径。 在原生安装中，shared/… 和 policies/… 在此程序包内解析（由安装程序随附）；在 Claude Code 插件安装中，它们位于插件根目录 — ${CLAUDE_PLUGIN_ROOT}/shared/…，即本文件向上两级目录。