nikbearbrown/figma-webdesigner

サイトデザイン監査 → ワイヤーフレーム → 意思決定台帳

目的

ローカルにクローンしたウェブサイトを、以下のアウトプットに変換します：(1) Gitコミットに固定されたハッシュ証拠、(2) 各ルールを引用し、関連するソースファイルを指摘する調査結果、(3) Figmaの現状と改善案のワイヤーフレーム、(4) すべての変更を説明する決定記録、(5) 人間による承認記録、(6) 承認された決定に対する実装指示書（Claude CodeまたはCodexが別のセッションで実行）。Git台帳が唯一の真実の情報源です。Figmaはその投影です。このスキルは設計と記録を行います。サイトのソースを編集することはありません。

想定ワークフロー

1. 学生が自分のサイトのリポジトリ（GitHub、またはVercelプロジェクトがデプロイするリポジトリ）をクローンし、ローカルで実行します。学生はFigma MCPへの教育アクセス権を持っていることが期待されます。
2. このスキルがローカル開発サーバーから情報を取得し、監査し、Figmaにワイヤーフレームを構築します。
3. 人間が調査結果をトリアージし、決定をレビューし、承認します。
4. このスキルが、承認された決定ごとに引き継ぎ指示書を作成します。Claude CodeまたはCodexが各指示を独自のブランチで実装します。このスキルが再取得して検証します。

コマンド

スキルフォルダにはコマンド fwd と、それにどう応答するかを示す CLAUDE.md があります。ユーザーが help、check、init、tutorial と入力した場合は、CLAUDE.md に従ってください。

• help は fwd help（セットアップチェックと次のステップ1つ）を実行し、Figmaツールが存在する場合は whoami でシート情報を取得します。不足しているものを先に確認し、次のステップを1つ提示します。ユーザーに代わって変更は行いません。
• tutorial は7ステップの最初のチュートリアル（ホームページのリデザイン）を実行します。これはこのスキル独自のフェーズであり、ステップバイステップで進められます。
• fwd approve|reject|defer <D-id> は学生が自分のターミナルで実行するものです。承認ファイルと台帳イベントを作成します。譲れないルール1が適用されます。エージェントがこれを実行したり、audit/approvals/ に書き込んだりしてはなりません。
• fwd ledger verify はハッシュチェーンと、各承認ファイルが台帳と一致するかを確認します。

譲れないルール

1. 決定を承認済み、却下、または延期に設定したり、再開したりできるのは人間だけです。エージェントがこれらの状態を書き込んだり、audit/approvals/ にファイルを書き込んだりしてはなりません。
2. すべての調査結果は、audit/rulebook/rules.yaml の rule_id を引用しなければなりません。ルールがない場合、調査結果にはなりません。代わりに observation として記録し、人間に判断を委ねます。
3. 調査結果のラベルはルールの階層に従います。規範的ルール → failure、ヒューリスティックルール → concern、ハウスルール → deviation。ヒューリスティックな調査結果をfailureと呼んではいけません。ヒューリスティックな調査結果に合格/不合格のアイコンや単語（✅ ❌ 「違反」）を使用してはいけません。
4. as-isフレームとto-beフレームのすべての違いには、少なくとも1つの決定IDが関連付けられていなければなりません。タグ付けされていない違いを発見したら報告し、無視してはいけません。
5. 00 As-Is ページを編集してはいけません。スキルが作成していないノードを修正または削除してはいけません。スキル自身のカテゴリ内の注釈のみを操作し、常に読み取り→マージ→書き込みを実行します。
6. Dev Modeステータス（開発準備完了 / 完了）を設定してはいけません。人間のコメントを解決または削除してはいけません。
7. 人間が名前付きのベースラインバージョンを保存し、そのIDが記録されるまで、既存のFigmaファイルに書き込んではいけません。例外：この実行で自ら作成したFigmaファイル。空のファイルはそれ自体がベースラインであるため、capabilities.json にその旨を記録します。
8. ユーザーが所有または作業権限を持つリポジトリのローカルクローン（localhostで提供）、またはユーザーがURLを提供した同じリポジトリのデプロイ済みサイト/Vercelプレビューからのみ情報を取得します。サードパーティのライブサイトに対して、情報取得、スクリプト注入、セキュリティヘッダーの除去を行ってはいけません。intent.yaml にはリポジトリと固定されたコミットを記録しなければなりません。
9. 以前の調査結果フレームや以前の実行出力を上書きしてはいけません。再実行は新しいバージョン管理されたフレームを作成します（フェーズ7参照）。レイヤー名、塗りつぶし色、テキストヒューリスティックで自身のノードを特定してはいけません。台帳に記録されたノードIDを使用します。
10. サイトのソースコードを編集してはいけません。実装は、承認された決定に対する引き継ぎ指示書を使用して、別のClaude CodeまたはCodexセッションでのみ行われます。

ディレクトリ構成

audit/
  intent.yaml                 # 人間が入力（フェーズ0）
  rulebook/rules.yaml         # 人間が確認（フェーズ1）
  schema/                     # 調査結果、決定、承認、イベントのスキーマ
  runs/R-YYYYMMDD-NN/
    capabilities.json         # この実行で実際に可能だったこと
    manifest.json             # キャプチャのハッシュと状態
    captures/{width}/         # screenshot.png, dom.html, axe.json, checks.json, skeleton.json
    findings.json
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # 人間のみ
  handoff/                    # 実装指示書、承認された決定のみ
    README.md                 # 実装者エージェント向けの共通ルール
    D-NNNN.md                 # 承認された決定ごとに1つの指示書
  ledger.jsonl                # 追記専用、ハッシュチェーンイベント

サイトのクローンは audit/ の外（local_path）にあります。このスキルはそれを読み取り、書き込みはしません。audit/ は兄弟フォルダまたは独自のブランチに配置できるため、監査記録がサイトのコミットと混ざることはありません。

フェーズ0 — 意図（ゲートG0）

audit/intent.yaml がないか、必須フィールドが空の場合は、会話形式で1つか2つずつ、不足しているフィールドを尋ねます。すべての必須フィールドがユーザーによって入力されるまで、キャプチャ、評価、書き込みを行ってはいけません。ユーザーがまだリポジトリをクローンしていない場合は、正確な git clone コマンド（Vercelプロジェクトの場合は、そのデプロイ元のGitHubリポジトリ）を専用のコードブロックで伝え、待機します。

repo: ""                      # 必須：サイトのGitHub URL（またはVercelプロジェクト）
local_path: ""                # 必須：ローカルクローンのパス
commit: ""                    # 必須：監査が固定されるコミットSHA
dev_command: ""               # 必須：例 "npm run dev"
dev_url: "http://localhost:3000"
routes: []                    # 必須：監査するパス、例 ["/", "/apply"]
ownership: ""                 # 必須："own repo"、または許可を与えた人物と日時
implementer: ""               # 必須："claude-code" または "codex"
conformance_target: "WCAG 2.2 AA"
breakpoints: "derive"         # サイトCSSから "derive"、または幅のリスト
house_rules: ""               # デザインシステムトークンへのパス、または "none"
figma_file: ""                # Figmaフェーズに必須。空欄はJSONのみモード
approvers: []                 # 必須：名前と役割
out_of_scope: []

フェーズ1 — スキーマ（ゲートG1）

ルールブック（階層とモード別のルール数）とレコードスキーマを要約します。ユーザーに確認または編集を求めます。ユーザーの名前と日付を含む schema.confirmed 台帳イベントを記録します。確認なしに先に進んではいけません。

ランタイム機能プローブ

フェーズ2の前に、capabilities.json を作成します。

• どのFigma MCPツールが存在するか（use_figma, generate_figma_design, html_to_figma, get_metadata, get_screenshot, generate_diagram, upload_assets）。
• whoami の結果：figma_file を所有するプランのシートタイプ。書き込みが不可能な場合は、mode: json-only を設定し、実行中のFigma書き込みをスキップします。学生は教育プランアクセスを持っていることが期待されますが、想定せずに実際のシートとプランを記録し、レート制限エラーがあればメモします。
• ローカル環境：Node.jsとパッケージマネージャーのバージョン、dev_command が起動するか、local_path のワーキングツリーがクリーンで commit にあるか。
• 任意の use_figma 呼び出しの前に、Figmaの figma-use スキルをロードします。
• ライブの use_figma ツールスキーマを読み取り、skillNames パラメータを受け入れるかどうかを記録します。同等のFigmaスキル（Throughline）はすべての呼び出しで skillNames: "throughline" を渡します。パラメータが存在する場合は、すべての use_figma 呼び出しで skillNames: "figma-webdesigner" を渡します。存在しない場合は、skillNames: unsupported と記録します。
• 最初の実行（2026-11-07、Full Studentシート）から判明していることですが、想定せずに再確認します。setSharedPluginData が機能すること。addAnnotationCategoryAsync と node.annotations（labelMarkdown と categoryId を使用）が機能すること。figma.saveVersionHistoryAsync はサポートされていないため、エージェントはベースラインバージョンを作成できません。figma.root.name は設定不可であるため、APIを介してファイル名を変更することはできません。これらのいずれかが失敗した場合は、決定IDをフレーム名に ⟦D-0007⟧ と注釈として含め、結果を記録します。
• Figmaファイルの名前は、create_new_file を呼び出すときにサイトにちなんで付けます（例：jobs.humanitarians.ai）。後で名前を変更することはできません。ページはステージです（00 Kit & Legend、01 As-Is Wireframes、02 To-Be Wireframes）。フレームは page / width / as-is|to-be / state です。

use_figma スクリプトの規約

このスキルが use_figma を介して送信するすべてのスクリプトは、次のルールに従う必要があります。

0. 同じ高さの兄弟要素には、各子要素に layoutSizingVertical = 'FILL' が必要です（親が高さを内容に合わせる場合、layoutAlign = 'STRETCH' だけでは不十分です）。ハブやテーブルセル内で折り返す必要のあるテキストには、textAutoResize = 'HEIGHT' と幅が必要です。
1. 最初にフォントをロードします。 スクリプトが使用するすべてのフォントスタイル（イタリックやミディアムも含む）に対して、テキストを作成または編集する前に、1つの Promise.all で figma.loadFontAsync を呼び出します。
2. 親子関係を設定した後にサイズ設定を行います。 各ノードを親に追加した後、layoutSizingHorizontal と layoutSizingVertical を設定します。文書化されたプロパティ名のみを使用します（cornerRadius は使用可、corner は不可）。不明なプロパティは静かに無視されます。
3. 書き込みレシートを返します。 スクリプトは、createdNodeIds と mutatedNodeIds（どちらも常に正直に入力されます。該当するものがない場合のみ空の配列）、frameId、stamped（プラグインデータが書き込まれたかどうか）、pageId を含むオブジェクトを返さなければなりません。
4. レシートを台帳に記録します。 各呼び出しの後、レシート、実行ID、関連する決定ID、version_before を含む figma.write イベントを追加します。後のフェーズでは、これらのIDからスキル所有のノードを見つけます。名前や色からは見つけません。
5. 変更の事前状態を記録します。 スクリプトが既存のノード（スキル作成ノードの注釈、テキスト、塗りつぶし）を変更する場合は、台帳が記録できるように、レシートに以前の値を返します。事前状態を記録せずに上書きすることは許可されていません。
6. 失敗した場合は明確に報告します。 黙って成功を報告してはいけません。ルックアップで何も見つからない場合は、見つかったものをリストしたエラーを返します。何も実行しなかったのに成功を報告してはいけません。

フェーズ2 — キャプチャ

0. クローンを準備します。local_path が commit にあり、ワーキングツリーがクリーンであることを確認します（そうでない場合は、dirty: true を記録して停止し、ユーザーに尋ねます）。依存関係をインストールし、dev_command を起動し、dev_url が応答することを確認します。コミットSHA、ダーティフラグ、Node.jsのバージョンを manifest.json に記録します。ソースファイルは変更しません。プロジェクトに存在しない環境変数やシークレットが必要な場合はユーザーに尋ねます。決して捏造してはいけません。
1. リポジトリ自身の設定（Tailwind設定、CSSカスタムメディアクエリ、フレームワークテーマ）と、サイトの計算されたCSSメディアクエリからブレークポイントを導出します（intentに幅がリストされている場合を除く）。320px、各ブレークポイントの1ピクセル手前とブレークポイント、および1つの大きなデスクトップ幅でキャプチャします。
2. 幅ごとに：全ページスクリーンショット、DOM、axe-coreの結果（タグ wcag2a、wcag2aa、wcag21aa、wcag22aa）、オーバーフローチェック、ターゲットジオメトリチェック、構造スケルトン（ランドマーク、見出し、バウンディングボックス付きのインタラクティブクラスター）。
3. キャプチャ状態（同意バナー、認証、バリアント）とすべてのファイルのSHA-256ハッシュを manifest.json に記録します。
4. capture.completed イベントを追加します。

フェーズ3 — 測定

自動チェックとアシストチェックを実行します。自動チェックの結果はそのまま調査結果になります。アシストチェックの結果は、mode: assisted と triage: null を持つ調査結果になります。どの例外（spacing、inline、equivalent、essential、data table）が該当する可能性があるかをメモします。

ソースマッピング。 各調査結果について、クローン内で要素のソース（テキスト、クラス名、コンポーネント名、データ属性）を検索し、source: {file, line, confidence} を記録します。これはベストエフォートです。推測の場合は confidence: low を使用し、見つからなかった場所を主張するよりも source を省略します。これらは実装者へのヒントであり、指示ではありません。

フェーズ4 — 評価

ヒューリスティックパスを実行します。各調査結果について記録します。

• rule_id、ロケーター、証拠のパスとハッシュ
• 重大度 0～4（Nielsen：頻度、影響、持続性）
• 信頼度（high/medium/low）
• scope：single-section、cross-section、component、interaction のいずれか
• 証拠が示す内容を1文で

スコープガイダンス：

• single-section：問題が1つのページの1つのブロック内にある。
• cross-section：問題がブロック、ページ、または幅をまたがってのみ現れる（優先順位と視覚的順序の不一致、一貫性のないパターン、ページ間で変化するナビゲーション）。これらは意図的に探してください。多くの場合、これらが最も重要であり、1つのセクションずつレビューすると見逃しやすいです。
• component：再利用可能な要素が、出現する場所ごとに動作や外観が一貫していない。
• interaction：問題が静的なレイアウトではなく、状態、フロー、または動作にある。

長いページの場合は、各セクションを独自のスクリーンショットから評価し、y位置をメモします。その後、セクションをまたぐ調査結果のために別のパスを実行します。十分な視覚的証拠があるルールのみを含めます。キャプチャから評価できないルールは、推測する代わりにスキップします。自分自身を1人の評価者として扱い、調査結果のサマリーにその旨を明記します。

ゲートG2 — トリアージ

調査結果を重大度順、次にページ順にグループ化し、テーブルとして提示します：ID、ルール、ラベル、スコープ、ページ/幅、重大度、信頼度、1行の証拠。ユーザーに受け入れ、拒否、または再スコアリングを依頼します。各トリアージ呼び出しを、ユーザーに帰属する台帳イベントとして記録します。受け入れられた調査結果のみが先に進みます。

フェーズ5 — Figmaベースライン（ゲートG3）

1. generate_figma_design（または html_to_figma）を使用して、as-isスクリーンをページ 00 As-Is にキャプチャします。構造的な変更を示すキャプチャされた幅ごとに1つのフレームを作成します。
2. skeleton.json から、ページ 01 As-Is Wireframes に構造的なas-isワイヤーフレームを構築します。search_design_system でファイルのワイヤーフレームキットが見つかった場合はそれを使用します。
3. 引き継ぎ：ユーザーに 00 As-Is をロックし、baseline R-… というタイトルの名前付きバージョンを保存し、そのバージョンIDを提供するよう依頼します。エージェントはバージョンを自分で保存できません。
4. ID を version_before として記録します。このIDを取得するまで、これ以上書き込みを行ってはいけません。

フェーズ6 — 提案

1. 受け入れられた調査結果を決定にグループ化します。各 D-NNNN.json：タイトル、調査結果ID、コンテキスト、提案、代替案...

（内容が途中で切れています）