penpot-audit-tokens

penpot-audit-tokens — 设计系统治理审计工具

1. 标题 + 工作原理

penpot-audit-tokens 强制执行令牌治理——这与无障碍性是不同的关注点。每次修改都通过 execute_code 进行；使用 export_shape 进行视觉验证；使用 penpotUtils.shapeStructure 读取结构（完整工具接口：shared/penpot-mcp-tool-reference.md）。它会收集所有填充／描边／间距／圆角值，与当前激活的令牌系统（penpotUtils.tokenOverview()）进行比较，并报告硬编码值、不符合网格的间距、孤立／未解析的令牌及重复项——每项都附有建议替换使用的语义令牌。

2. 最重要的一条规则

只提供建议，且只自动替换完全相等的值。 唯一安全的自动修复，是将一个原始值替换为某个现有令牌，前提是该原始值与令牌解析后的值完全相等。其他情况（近似匹配、将不符合网格的值取整、新建令牌）都只能作为建议，留待审核。

3. Penpot MCP 工具参考

完整接口：shared/penpot-mcp-tool-reference.md。关键调用：使用 penpotUtils.analyzeDescendants 收集值的 execute_code，以及用于对照令牌系统的 penpotUtils.tokenOverview() / findTokenByName。

4. 插件 API 要点

• 从 shape.fills / shape.strokes（十六进制值）、shape.borderRadius*、flex 的 rowGap / columnGap / *Padding、布局边距中读取原始值。
• 形状已应用的令牌位于 shape.tokens（{ property: tokenName }）中。属性有原始值，但在其中没有对应条目时，就属于“硬编码”。
• 令牌解析后的值通过 token.resolvedValue 获取。使用 shared/tokens-schema.json 中完全一致的令牌 type 字符串。
• 比较操作为只读；唯一的修改操作（完全相等时替换）使用 shape.applyToken——参见 shared/plugin-api-gotchas.md 中的第 2 项：它是异步的，按批次执行，并且需要在后续调用中验证。
• 依赖不熟悉的签名之前，先用 penpot_api_info 验证。

5. 令牌感知型任务说明约定

• 上下文——范围（页面／所选内容／库）、当前激活的令牌系统。
• 目标——单一目标：“审计 X 的令牌治理”。
• 输入——目标形状、4px 网格、当前激活的令牌集。
• 约束——除完全相等的自动替换（需明确选择启用）外，只读。
• 验收标准——报告所有原始值；列出不符合网格的间距；找出孤立／未使用的令牌；每项发现都附有建议令牌和置信度。

以设计系统治理工程师的身份行事。

6. 强制工作流

阶段 0 — 检查。 执行 high_level_overview；使用 scripts/collectStyleUsage.js 收集用法，使用 tokenOverview() 获取令牌系统（references/01-inspection.md）。

阶段 1 — 硬编码值。 执行 scripts/detectHardcodedValues.js（references/02-hardcoded-value-detection.md）——比较原始填充／描边值与令牌；标记完全相等和近似匹配。

阶段 2 — 网格与孤立项。 执行 scripts/checkGridAndOrphans.js（references/03-orphan-and-grid-checks.md）——检查不符合网格的间距、未解析的引用、未使用的令牌及重复项。

阶段 3 — 报告。 执行 scripts/generateTokenReport.js（references/04-report-generation.md）。✋ 检查点：展示发现；询问是否要仅自动应用完全相等的替换（审核后应用），并将其余问题（新令牌、取整）交由 penpot-foundations 处理。

7. 关键规则

1. 治理 ≠ 无障碍性——范围仅限于令牌／系统一致性。
2. 只有原始值与令牌完全相等时，才可自动替换（安全范围）。
3. 不符合网格的间距 → 建议最接近的 4px 令牌；绝不静默取整。
4. 只提出新令牌建议，不在此处创建（移交给 penpot-foundations）。
5. 每项发现都必须包含严重性 + 影响 + 建议令牌 + 置信度。
6. 不得静默缩减范围。

8. 领域架构

检查结果映射到 shared/tokens-schema.json 的 governanceRules：noHardcodedColor、noOffGridSpacing、 noOrphanTokens、preferSemantic。报告架构：

{ severity, rule, element, property, current, suggestedToken, exactMatch:bool, confidence }

最终报告还必须按照 shared/report-schemas/token-governance-report.schema.json 输出为 JSON 对象（检查结果包含 exactMatch——只有完全相等的替换才属于安全集），并同步到运行账本。

9. 模式与策略

默认采用 suggest。根据 shared/modes-and-policies.md 中的安全集，唯一允许的自动修复是完全相等的替换，而且只能在检查点明确选择启用后执行。几何调整、新建令牌、分离：绝不自动执行。

10. 状态管理

在 RUN_ID 下记录账本：phase、findings:[...]、autoSwapped:[...]、sampled。

11. 用户检查点

阶段之后	产物	询问
3 报告	治理报告	自动应用完全相等的替换？其余问题转交给基础团队？

12. 命名约定

shared/naming-conventions.md + shared/tokens-schema.json（点号表示法、实际类型字符串）。

13. 防止自我合理化对照表

借口	错误原因	应对措施（停止）
“这个原始十六进制值基本上就是令牌。”	“基本上”不等于完全相等；静默替换会破坏原意。	仅在完全相等时自动替换；否则提供建议和置信度。
“我直接创建缺失的令牌并替换就行。”	新建令牌应由基础团队决定。	提出令牌方案；将创建工作转交给 penpot-foundations。
“自动把 18px 舍入到 16px。”	向非网格值舍入可能导致布局偏移。	建议使用最接近的 4px 令牌；需要审核。
“跳过孤立／未使用令牌检查。”	孤立项会形成隐性技术债务。	执行完整的网格／孤立项检查。
“这是个小文件，目测一下就行。”	这样会漏掉系统性原始值的使用情况。	通过程序遍历整个树；报告计数。

14. 辅助代码片段

// Is a property hardcoded? (raw value present, no token bound)
function isHardcoded(shape, prop){
  const hasRaw = prop === 'fill' ? (shape.fills||[]).length>0 : shape[prop] != null;
  const bound = shape.tokens && shape.tokens[prop];
  return hasRaw && !bound;
}
return { ok: true };

15. 参考资源

• shared/tokens-schema.json（governanceRules）、penpot_api_info('Shape','tokens')、penpot_api_info('Token','resolvedValue')。

16. 支持文件

references/：01-inspection.md、02-hardcoded-value-detection.md、03-orphan-and-grid-checks.md、04-report-generation.md。 scripts/：collectStyleUsage.js、detectHardcodedValues.js、checkGridAndOrphans.js、generateTokenReport.js。

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