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. プラグイン 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. トークンを考慮したブリーフの契約

• コンテキスト — 何を監査するか（ページ／選択範囲／コンポーネント）、プロダクトの対象範囲。
• 目的 — 1つに絞ります：「X を WCAG 2.1 AA に照らして監査する」（AAA が必要な場合は明記）。
• 入力 — 対象シェイプ、適合レベル、既知の例外。
• 制約 — 読み取り専用。キャンバスは変更しません。
• 合格基準 — すべてのインタラクティブ要素を確認すること。コントラスト 4.5:1（通常）／3:1（大きなテキストと UI）。ターゲットは 24×24 以上（WCAG 2.2。主要なターゲットは 44×44 を推奨）。見出しの順序が適切であること。レポートが完全であること。

scope:deck（penpot-build-deck で作成されたスライド。評価者は brief-to-deck）。 スコープは デッキのページです。NN-… という名前のトップレベルのボードは、それぞれ1枚のスライドです。ルールを調整します。テキストが 24 px 以上、または fontWeight ≥ 700 で 18.67 px 以上の場合は大きなテキストとして 3:1、それより小さいテキストは 4.5:1 とします（グラデーションやガラス風の面では、特に本文と キャプションを確認してください。色の停止点を平均し、結果はヒューリスティックとして明記します）。 デッキにはナビゲーション以外のインタラクティブなコントロールがないため、ターゲットサイズの確認は省略します。見出し階層は、スライドごとに h1 がちょうど1つです。 レポートの 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）に引き継ぎます。

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. モードとポリシー

デフォルトは suggest（読み取り専用）です。修正はすべて、Apply-with-review のもとで担当スキルに委任してください。

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 プラグインとしてインストールした場合は、プラグインのルートにあります。このファイルから 2 つ上のディレクトリにある ${CLAUDE_PLUGIN_ROOT}/shared/… が該当します。