figma-variables-tokens-generator

Figma Variables Tokens Generator

エラーなしでインポートできる、本番環境対応の Figma Variables JSON ZIP を生成します。 各システムに、シニアプロダクトデザイナーとシニアフロントエンドエンジニアの両方の視点で取り組みます。 モード間で ID の安定性を保ち、常に絶対パスに正規化します。

生成に関する必須不変条件

これらのルールは、あらゆるアーキテクチャ、コレクション、命名スタイル、ユーザー入力の組み合わせに適用されます。

1. 変数ごとに正規トークンパスを 1 つだけ定める

   • トークンパスは、以下のすべてで正規表現が厳密に 1 つだけでなければなりません。
     • 計画／データマップ
     • prebuild_ids()
     • create_token()
     • 出力される JSON のネストキー
     • aliasData.targetVariableName
     • 検証レジストリ
   • JSON で使う大文字・小文字の形式と、レジストリで使う形式を変えてはいけません。
   • エイリアスのターゲットを、出力される変数名と異なる形式に正規化してはいけません。

2. 変数パスはアーキテクチャデータであり、コード構文ではありません

   • com.figma.codeSyntax は、キャメルケース、ケバブケース、CSS カスタムプロパティ、Android、iOS のいずれでもかまいません。
   • トークンパス自体は、安定したコレクションパスのまま維持してください。
   • コード構文の規則に合わせてトークンパスを変換してはいけません。
   • 参照で指定されているセマンティックな区切り文字をそのまま維持してください。例：link-hover、on-brand、on-surface-variant、lineHeight、letterSpacing、borderWidth、minWidth、maxWidth。

3. パスを文字どおり維持する

   • 参照ファイルでパスが文字どおり定義されている場合は、そのパスをそのまま出力してください。
   • ケバブケースをキャメルケースに暗黙的に書き換えたり、セマンティック名からハイフンを取り除いたりしてはいけません。
   • コンポーネントコレクションとカスタムコレクションでは新しいパスを追加できますが、一度決めた表記は最初から最後まで同一に維持してください。

4. 成果物レベルの検証は必須です

   • 内部レジストリだけを信頼してはいけません。
   • すべてのファイルを構築した後、すべてのコレクションから実際に出力された JSON キーをフラット化し、すべてのエイリアスターゲットを出力済みパスと照合して検証してください。
   • 出力された JSON グラフと内部レジストリが完全に一致していない限り、安全なビルドとはいえません。

5. スコープの正確性は必須です

   • スコープは、ヘルパーの意図ではなく、出力された成果物から検証してください。
   • text/* とすべてのテキストロールの子孫は TEXT_FILL に解決されなければなりません。
   • border/* とボーダーロールの子孫は STROKE に解決されなければなりません。
   • icon/* は SHAPE_FILL と STROKE に解決されなければなりません。
   • shadow/*/color は EFFECT_COLOR に解決されなければなりません。
   • 数値のタイポグラフィパスは FONT_SIZE、LINE_HEIGHT、LETTER_SPACING に解決されなければなりません。
   • パスが曖昧な場合は、生成前に明示的なルールを追加してください。セマンティックなテキストトークンやボーダートークンに、広範な塗りつぶしのフォールバックを適用してはいけません。

6. カバレッジの下限は契約上の要件です

   • ユーザーが Lean、Standard、または Enterprise を選択した場合、生成されるトークンの一覧は、関連する参照で定められた密度の下限を満たさなければなりません。
   • 手動のデータマップが途中で終わっていることを理由に、生成するトークンを減らしてはいけません。
   • Theme／Semantic／Component の出力は、まず必須パスの一覧から導出し、その後必要に応じて拡張してください。

7. バックフィルは不足を防ぎますが、識別子の不整合は防ぎません

   • 親コレクションを保存する前に、不足している親の値をバックフィルしてください。
   • ただし、バックフィルによってパスの大文字・小文字、パス表記、エイリアス名の不一致が解消されると考えてはいけません。
   • トークンの不足とトークンの不一致は異なるエラーの種類であり、それぞれ別々に検証する必要があります。

出力形式： JSON トークンを含む .zip ファイルのみを出力してください。.skill ファイルを出力したり、生の Python スクリプトを貼り付けたりしてはいけません。ユーザーが求めているのは、すぐにインポートできる ZIP であり、コードではありません。チャットにスクリプトを貼り付けるとコンテキストが途中で切り詰められ、生成に支障をきたします。

ローカル IDE／CLI の出力ルール

ローカルの IDE または CLI ワークスペースで実行する場合：

• exports/ フォルダーが存在しない場合は、必ず作成してください
• 最終的なトークン ZIP は exports/ 内に保存してください
• 生成された成果物をプロジェクトのルートに散らばらせないでください
• ユーザーから明示的に依頼された場合、または生成失敗からの復旧に必要な場合を除き、追加のマニフェスト、デバッグ用 JSON ファイル、補助レポート、ジェネレータースクリプトを作成しないでください

デフォルトの想定：

• exports/ 内に最終 ZIP が 1 つ
• 追加ファイルは最小限

読み込み順 — 段階的な読み込み

コンテキストの汚染を防ぐため、現在の読み込み段階で必要なファイルのみを読み込んでください。

読み込み段階 1：調査と戦略（ターン 1 で読み込む）

#	ファイル	目的
1	instructions/01-interview-setup.md	初期設定とターン 1～3
2	instructions/02-questionnaire-and-generation.md	ターン 4～10 の質問票と生成
3	references/01-architecture.md	必須の戦略： 理解度の階層とエイリアスのルール。

読み込み段階 2：アーキテクチャの確認（フェーズ 2 の前に読み込む）

#	ファイル	目的
4	references/05a-collections-core.md	Core コレクションの設計仕様
5	references/05b-collections-semantic-components.md	Semantic／Component コレクションの設計仕様

読み込み段階 3：生成ロジック（フェーズ 3 の前に読み込む）

#	ファイル	目的
6	references/02-scoping-rules.md	技術的なスコーピング表
7	references/03-json-format.md	正確な W3C JSON 構造
8	references/04-primitives.md	生の 16 進数／間隔／フォントデータ
9	references/06-generator-utility.md	Python 生成スクリプトのパターン
10	scripts/generator_core.py	実行可能な Python エンジン（ローカル／IDE 環境向け）

読み込み段階 4：納品と引き継ぎ（ZIP の納品とトークン数の報告が完了した後に読み込む）

#	ファイル	目的
11	instructions/03-import-and-handoff.md	インポートガイドと ZIP の参照表

インタビューが 100％ 完了するまで、読み込み段階 3 の実装ファイル（スコーピングルール、JSON 形式、ジェネレーターユーティリティ）は読み込まないでください。早い段階で読み込むと、まだ必要のない技術データでコンテキストが埋まってしまいます。