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（値の収集）と penpotUtils.tokenOverview()／ findTokenByName（比較対象のトークンシステム）を使った execute_code。

4. プラグイン API の基本

• 生の値は shape.fills／shape.strokes（16 進数）、shape.borderRadius*、フレックスの 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. モードとポリシー

デフォルトは 提案 です。shared/modes-and-policies.md の安全な適用対象に従い、自動修正できるのは完全一致の置き換えのみで、チェックポイントで明示的にオプトインした場合に限ります。ジオメトリ、新しいトークン、デタッチは自動適用しません。

10. 状態管理

RUN_ID の下に台帳を保存します：phase、findings:[...]、autoSwapped:[...]、sampled。

11. ユーザーチェックポイント

フェーズ後	成果物	確認事項
3 レポート	ガバナンスレポート	完全一致する置き換えを自動適用しますか？残りは基盤チームに回しますか？

12. 命名規則

shared/naming-conventions.md + shared/tokens-schema.json（ドット記法、実際の型文字列）。

13. 合理化を防ぐための表

言い訳	誤りである理由	対策（停止）
"この生の16進数値は、実質的にはトークンと同じだ。"	「実質的に」は完全一致ではありません。無断で置き換えると意図が損なわれます。	完全一致の場合のみ自動置き換えします。それ以外は信頼度を添えて提案します。
"不足しているトークンを作成して置き換えればいい。"	新しいトークンの作成は基盤チームが決定します。	トークンを提案し、作成は 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/… はこのファイルから 2 つ上のディレクトリです。