code-to-figma

Code to Figma

プロジェクト固有の Figma エクスポートパイプラインを生成します。コンパイル済みの HTML と CSS を読み取り、クラス → トークンのバインディングを解決し、構造化された JSON アーティファクトを GitHub Gist にプッシュするウォーカーです。このアーティファクトは、tokens-sync-to-figma Figma プラグインが読み込みます。

このパイプラインは、意図的に一方向で、CI を起点としています。setup の実行時にプロジェクトを一度評価し、スクリプトを生成して CI に組み込みます。その後は、設定したトークンまたはテンプレートのパスに変更を加えるプッシュのたびに、Figma API キーなしで Gist が自動更新されます。同梱のプラグインは、既存の Figma 変数を使ってページ構造を再構築します。Figma との整合性を確認するには、トークン値の変更後、別途コレクションを更新して読み戻す必要があります。

コマンド

コマンド	使用する状況	結果
/code-to-figma setup	初回。スクリプトがまだない場合	ウォーカーとトークンスクリプトを生成し、Gist を作成、CI を設定し、設定を保存します
/code-to-figma sync	スクリプトが存在し、現在の状態を Gist にプッシュする場合	figma-export.json を作成し、Gist にパッチを適用します
/code-to-figma update	技術スタックまたはトークンの命名規則が大きく変わった場合	スクリプトを再生成し、CI と設定を更新します
/code-to-figma status	パイプラインの状態を確認する場合	Gist の経過時間、CI の状態、スクリプトの有無、設定の妥当性を表示します

修飾子のない setup/sync リクエストでは、figma-sync.config.json とウォーカースクリプトが見つからない場合、/code-to-figma setup を既定として使用します。明示的な読み取り専用の status リクエストは維持し、パイプラインがないことを報告して、作成はしません。

---

/code-to-figma setup

1 — プロジェクトを評価する

生成を始める前に、次の順で読み取ります。

1. パッケージマニフェスト — package.json、pyproject.toml などを確認します。フレームワーク（Next.js、Eleventy、SolidJS、プレーン HTML）とパッケージマネージャーを特定します。
2. CSS／トークンファイル — ソースではなく、コンパイル済みの出力を探します。一般的なパス：
   • Tailwind v4：out/assets/css/tailwind.css または同等のビルド出力
   • カスタム CSS：--token-name: value; 形式のカスタムプロパティ宣言を含むファイルを探します
   • Style Dictionary：tokens.json、variables.css、または dist/ 内の生成済み出力
3. コンポーネント CSS — メインの CSS ファイルと同じ場所に components.css または utilities.css がないか探します。
4. ビルド済み HTML — ソーステンプレートではなく、コンパイル済みの出力ページを探します。一般的なパス：out/index.html、dist/index.html、_site/index.html。Next.js：通常のビルドでは単一の HTML ファイルは生成されません。先に output: 'export' を必須とします（out/index.html が生成されます）。詳しくは references/walker-patterns.md の Next.js に関する注記を参照してください。静的 HTML アーティファクトを生成できない場合は、パスを推測せずに停止してユーザーに伝えます。
5. トークンの命名規則 — CSS カスタムプロパティ名を読み取り、プレフィックスからグループへの対応関係を抽出します（例：beige-* → palette/beige/、fs-* → typography/scale/）。
6. セクション構造 — HTML を確認し、セクションの区切り方を調べます：<section id="...">、[data-section]、<article>、ヘッダー／フッターのランドマークなど。

ウォーカーの形式が実際に異なるものとして二通り考えられる場合（例：セクションを ID で識別するか、クラスで識別するか）は、焦点を絞った質問を 1 つします。それ以外の場合は推測し、その選択を明示します。

2 — スキャフォールドを生成して検証する

プロジェクト固有の walker、DTCG 2025.10 トークンコンバーター、汎用 Gist プッシャー、figma-sync.config.json、パッケージスクリプト、GitHub Actions ワークフロー、Gist、シークレット、初回同期、Figma プラグイン接続を作成または更新します。ファイル仕様については references/setup-scaffold.md を読み込み、標準の Gist、シークレット、CI、プラグインのセットアップコマンドについては references/ci-and-gist-setup.md を読み込みます。

CI に依存する前に必須となるローカルチェック：

node scripts/tokens-to-figma/convert-to-dtcg.mjs
git status --short -- scripts/tokens-to-figma/*.w3c.json
node scripts/figma-export/walk-<site>.mjs | jq -e '.sections | type == "array"'

中核となる境界を明確に保ちます。CI は figma-export.json を生成し、コミット済みの <project>-tokens.w3c.json をチェックします。tokens-sync-to-figma プラグインが使用するのは figma-export.json のみです。Figma 変数の管理には、DTCG アーティファクトを別途使用してください。CI で Figma API キーを要求しないでください。

生成されたスクリプトが実行でき、Gist に検証済みのエクスポートが含まれ、CI が設定され、ユーザーが コレクションの調整 を通じてプラグイン接続と変数値を確認できた時点で、セットアップは完了です。Figma へのアクセスや手動の手順が保留中の場合は、パイプラインのセットアップと Figma の検証を分けて報告してください。

---

/code-to-figma sync

1. figma-sync.config.json が存在し、walker のパスが有効であることを確認します。
2. プロジェクトのビルドコマンドで現在のサイトをビルドし、node scripts/tokens-to-figma/convert-to-dtcg.mjs を再生成して、既存の値やエイリアスの変更を含め、.w3c.json の差分を確認します。その後、node <walker> > figma-export.tmp.json を実行します。
3. 検証します：jq -e '.sections | type == "array"' figma-export.tmp.json が終了コード 0 で終了する必要があります。失敗した場合は中止します。
4. references/ci-and-gist-setup.md に従い、シークレットマネージャーから GIST_TOKEN がすでにエクスポートされていることを確認します。コマンドラインに PAT を入力しないでください。
5. プッシュします：node scripts/tokens-to-figma/push-to-figma.mjs < figma-export.tmp.json
6. 調整手順 を使用して、トークンの変更を Figma コレクションと調整します。Gist の認証は、Figma 内への書き込みを許可するものではありません。エクスポートのアップロード済みとFigma トークンの一致を検証済み／未検証を別々のステータスとして報告します。Figma への認証済みアクセス、または手動での読み戻しがなければ、一致は未検証であり、保留中の差分を一覧表示します。
7. 完了したら figma-export.tmp.json を削除し、エクスポートしたセクション数とノード数、Gist の URL、Figma の検証ステータスを別々に報告します。コレクションの値とプラグインの結果を検証した後に限り、Figma との一致を報告してください。

---

/code-to-figma update

フレームワークの出力、トークンの命名規則、セクションセレクター、CSS のビルドパスが変更され、既存の walker が古くなっている可能性がある場合に使用します。

1. 現在のコンパイル済み HTML/CSS とトークンファイルを対象に、セットアップの評価を再実行します。
2. walk-<site>.mjs、convert-to-dtcg.mjs、figma-sync.config.json、CI のパスをまとめて更新し、tokenPath()、明示的なトークン型、ファイルパスの整合性を保ちます。
3. DTCG トークンアーティファクトを再生成します：node scripts/tokens-to-figma/convert-to-dtcg.mjs。
4. walker の出力を検証します：node <walker> > figma-export.tmp.json && jq -e '.sections | type == "array"' figma-export.tmp.json。
5. スクリプトと .w3c.json の差分を確認した後、/code-to-figma sync または CI を通じてプッシュし、コレクションの変更を調整して、エクスポートと Figma との一致を別々に報告します。

---

/code-to-figma status

報告内容：

チェック項目	方法
Walker スクリプト	figma-sync.config.json が存在するか確認します。walker ファイルが存在するか確認します。
Gist の鮮度	gh api gists/<id> --jq '.updated_at' — Gist が更新されてからどれくらい経過しているか報告します
CI の接続	figma-sync.yml が存在するか確認します。workflow_dispatch が含まれているか確認します。
シークレット	gh secret list --repo <org>/<repo> — GIST_TOKEN と FIGMA_EXPORT_GIST_ID が存在することを確認します
最後の実行	gh run list --workflow=figma-sync.yml --limit=1
Figma トークンの一致	現在の .w3c.json と、利用可能なコレクションの読み戻し結果を比較します。Figma にアクセスできない場合や読み戻しが利用できない場合は、未検証と報告します。Gist の鮮度だけでは不十分です。

---

スキルの適用範囲

ユーザーの意図	使用するもの
コードトークンとページ構造を Figma にエクスポートする	このスキル
Figma のデザインをコードにインポートする	figma-to-code スキル
エージェント主導で、1 回限りの Figma 書き込みを行う：エージェントのセッション中にファイル内の変数、コレクション、ノード、コンポーネントを作成または編集する	use_figma MCP ツールを使う公式の figma-use スキル（再利用可能な変数／トークンコレクションには figma-generate-library も使用）— このスキルではありません
コード、HTML、または公開中のページから、Figma で1回限りの画面やデザインを生成する	公式の figma-generate-design スキルまたは Figma MCP 書き込みツール（generate_figma_design、html_to_figma、send_code_to_figma）（Figma MCP tools、2026-10-21 確認）— このスキルではありません
既存の Gist を手動で同期する	/code-to-figma sync

このスキルは Figma ファイルを編集しません。プラグイン（tokens-sync-to-figma）は Figma 側のコンシューマーであり、このスキルはプラグインが読み込む成果物を生成します。プラグインは既存の Design Tokens コレクションに接続するため、そのコレクションを一度作成しておく必要があります。また、オプションのエージェントパスは figma-use に引き継ぎます（references/ci-and-gist-setup.md を参照）。

動作評価

作成者／レビュアーのみ： このスキルを明示的に評価する場合は、シナリオカタログを使用してください。通常のタスク実行時には使用しません。このカタログには、説明のみのルーティングプロンプトと、独立した同期／読み戻しフィクスチャが含まれています。実行するエージェントにはラベルとアサーションを見せないでください。このカタログは実行に合格した証拠ではなく、合成読み戻しでは実際の Figma 統合を検証できません。コンバーターの動作は tests/walker-patterns-snippets.test.mjs でフィクスチャテストされています。

参照ファイル

ファイル	読み込むタイミング
references/walker-patterns.md	walker、DTCG コンバーター、または汎用 Gist プッシャーを生成または更新するとき、tokenPath()、明示的なトークン分類、セクション検出、または Next.js の静的エクスポート制約に対応するとき
references/setup-scaffold.md	セットアップファイル、パッケージスクリプト、Gist コマンド、GitHub シークレット、初回同期、またはプラグイン側の仕様を生成するとき
references/figma-export-contract.md	walker の JSON 出力形式（meta、sections、ノード、トークン参照）を検証するとき
references/ci-and-gist-setup.md	figma-sync.yml、GitHub シークレット、初回の Gist プッシュ、または tokens-sync-to-figma プラグインを設定するとき
references/benchmarks.md	skills.sh 上の同種スキルを比較するとき、またはこのパイプラインを代替手段と比較して位置付けるとき

運用原則

• ソースではなく、コンパイル済みの出力を読み取ります。 トークンのバインディングを解決できるのは、ビルド済みの HTML＋CSS の中だけです。ソーステンプレートでは、まだ置換されていない変数が使われている場合があります。
• tokenPath() と明示的な $type マッピングが契約です。 ウォーカーと DTCG コンバーターでは同じパス関数を使う必要があり、エクスポートするすべてのトークンに意図した DTCG 型を割り当てる必要があります。生の CSS 値から $type を推測してはいけません。分類体系が不明な場合や、値が規定に準拠していない場合はエラーにしてください。
• ウォーカーはプロジェクト固有、プッシャーは汎用です。 ウォーカーはプロジェクトの HTML 構造を理解し、プッシャーは Gist API のみを扱います。両者は分離したままにしてください。
• DTCG JSON をコミットしてください。 .w3c.json ファイルは、トークンの変更を人が読み取れる差分として確認するためのものです。リポジトリに含め、.gitignore に追加しないでください。
• CI では pnpm ではなく node を使ってください。 pnpm でライフサイクルスクリプトを実行すると、標準出力にスクリプトヘッダーが書き込まれ、> file.json のリダイレクトが壊れます。CI のステップでは、必ず node から直接ウォーカーを呼び出してください。