コンテンツにスキップ

Wireframe Component コレクション

概要

ワイヤーフレームキットのレジストリを保持するコレクション — des2wf の実行が mode を kit とするときに引き当てる語彙である。デザインシステム側の design_component と同じドキュメント形状であり、対象が別のライブラリである点だけが異なる。キットはデザインシステムの部分集合ではないため、デザインレジストリには置かない。共有のコンポーネントスイープが、そのワイヤーフレームレジストリターゲットの下でこれを書き込む（決定論的な Figma REST 全ファイル走査、_id での upsert、single-flight ガード付き、LLM なし）。des2wf の選択は実行時にこれを読み取り、各ドキュメントをバリアントごとに 1 行へ展開する。primitives の実行はこれを一切読まない。

テーブル定義

論理名 物理名 カラム名 データ型 主キー リレーション ユニーク NULL許可 デフォルト値 備考
Wireframe Component wireframe_component _id string ◯ {project_id}_{component_key} — componentSet のパブリッシュキーによる複合 id であり、node id ではない。node id はファイルのコピーごとに異なる: キットのページは作業ファイルへコピーされるため、同じキットを 2 つのボードに複製すると 1 つのマスターが異なる id を持つことになり、node id をキーとしたキットは同じマスターを二重に登録してどちらも確実には一致しない。パブリッシュキーを持たないマスターは、未登録にするのではなくノード複合 id {project_id}_{figma_file_key}_{node_id} にフォールバックする。セットのすべてのバリアントが共有するため、選択が投票する対象ではない
organization_id number テナント所有者
project_id number project:id プロジェクトスコープ
component_key string ◯ Figma のパブリッシュキー — 同一性である _id はこれから組み立てられる。NULL 可: キーがまだ読み取れていないマスターでは null であり、ノード複合 id のフォールバックはそのために存在する
component_node_id string ◯ マスターがどこにあるか — COMPONENT_SET（または単体の COMPONENT）のノード id。導出ではなく格納する: デザインレジストリは複合 _id から node id を復元できるが、キットのエントリはパブリッシュキーをキーとするため復元できない。キットのマスターはローカルのコピーであり、importComponentByKeyAsync に取り込むものが存在しないため、プラグインがインスタンス化する手段はこれだけである
name string 表示名。同一性ではないことを明示する
family object ◯ { name, node_id, node_type } — このエントリをスイープしたボード、すなわちキット自身のグルーピング。互換的な代替物をまとめるために使い、デザイン側のレイヤー名と突き合わせることは決してない。node_type は分類（SECTION）と単なる出所（コンポーネントがたまたま置かれていた FRAME）を区別する
kind string published / local — Type Codes を参照
default_size object { w: number, h: number }。例: {"w": 375, "h": 56} — セット自身のサイズであり、デフォルトバリアントのものである。バリアントを宣言しないドキュメントでのみ直接読まれる。自身のサイズを持たないバリアントはこれにフォールバックする
text_slots object[] テキスト置換スロット [{ layer_path: string, default_text: string, ambiguous: boolean }]（曖昧性はスイープ時にフラグ付け）— セット自身のもの、すなわちデフォルトバリアントのものである。variants が空のときにのみ直接読まれる。それ以外では容量はバリアント自身のリストで測る
image_slots object[] スイープがコンポーネント内で発見する画像レイヤー（text_slots と並行）[{ layer_path: string, ambiguous: boolean }] — instancing コンテキスト用に記録される構造的プレースホルダー。自動塗りはされない
text_props string[] コンポーネントが公開する非バリアントのテキストプロパティ名
variant_properties object セット全体の軸 { <property>: [string] }。例: {"type": ["default", "logged-in"]}。セットが列挙していないバリアント値は決して受理されない — Figma がマテリアライズ時に拒否するためである
variant_defaults object 軸 → デフォルト値（コンポーネントセットの宣言どおり）
variants object[] バリアントごとのプロファイル [{ variant_props, size, text_slots[], nested_components[], layout_shape, appearance[], semantics[] }] — 選択可能な行そのものである。コンポーネントセットはインスタンス化できず、インスタンス化できるのはそのバリアントである。兄弟バリアントはサイズ、テキストレイヤーの構成、取り込む下位コンポーネントで異なるため、軸ラベルではなくバリアント自身の内容で記述する
semantics object ◯ { kind, also_kinds[], is_placeholder, function[], appearance[], model_id, prompt_version, tagged_at, facts_hash }。意味付けの拡充はデザインシステム向けのパスであり — デザイン UI の語彙に対してコンポーネントをラベル付けする — キットターゲットには適用されない。キットのアトムはすでに自身の形で名付けられているためである。ここでは NULL となる
lineage object 全ドキュメント共通の lineage ブロック { source_url, source_hash, processor_version, index_schema_version, processed_at, job_id }。source_hash ≡ コンポーネントサブツリーのコンテンツハッシュ。job_id = 生成元のスイープ実行。これはエントリがどのキットの、どのバージョンから来たかを識別する — キットはデザイナーが選ぶものであり、差し替えは再登録であるため、古いエントリと現行のエントリを区別できる必要がある

リレーション

  • _id → {project_id}_{component_key}、値による。componentSet のパブリッシュキーそのものが同一性である（代理キーはない）。
  • project_id → project.id
  • DocumentDB 内ではリレーションは強制されない。論理リレーションであり、アプリケーションコードで検証する。

インデックス

  • PRIMARY KEY (_id)
  • コンポーネントスイープの single-flight ガード（project_figma_file ドキュメント上の sweep_marker）下での _id の upsert。代理のユニークキーはない。
  • 読み取りは project_id でスコープし、呼び出し元が保持している場合は organization_id を加える。

Type Codes

kind:

  • published: パブリッシュ済みの Figma コンポーネント。component_key を持ち、_id はそこから組み立てられる。
  • local: ローカル（未パブリッシュ）コンポーネント。component_key は null で、エントリはノード複合 id の下に登録される。

注記

  • 1 つのスイープが両方のライブラリを担う。 スイープはレジストリターゲットによってパラメータ化される。ターゲットが持つのは、異なる 3 つの事実だけである: コレクション、同一性の規則（キットは {project_id}_{component_key}、デザインシステムはノード複合 id）、そして意味付けの拡充パスを適用するかどうか。Figma ノードの読み取りからドキュメントの書き込みまで、その間はすべて同一である。
  • 同一性はパブリッシュキーであり、node id ではない。 デザインコンポーネントは「どこにあるか」— プロジェクトが所有するファイル内のノード — で指し示される。キットのコンポーネントは「それが何であるか」で指し示される。キットのページは作業ファイルへコピーされ、node id はファイルのコピーごとに異なるからである。キットを node id でキーにすると、同じマスターがコピーの数だけ登録され、どれとも確実には一致しない。したがって component_node_id は _id から切り出すのではなく、独立したフィールドとして格納する。
  • 選択可能な単位はバリアントであり、ドキュメントではない。 コンポーネントセットはインスタンス化できず、インスタンス化できるのはそのバリアントである。選択は各ドキュメントを variants のエントリごとに 1 行へ展開し — バリアントを宣言しないドキュメントでのみ最上位にフォールバックする — その行に固有のキーで投票し、解決する。すべてのバリアントがドキュメントの _id を共有するため、_id をキーにするとショートリストされたバリアントの任意の兄弟がガードに渡され、測る対象を誤る: 最上位が述べているのはデフォルトバリアントのスロットとサイズだからである。あるキットの実レジストリは 415 ドキュメントを保持し、927 のバリアント行へ展開される。
  • スロット容量は、バリアントが宣言する text_slots[].layer_path の相異なる値の数である。 マテリアライザーはスロットをパスで指して書き込むため、同一パスの 2 つの宣言は1 つの書き込み先である — 2 回目の書き込みが 1 回目を上書きし、そのデザイン文字列は失われる。容量は宣言数ではなく、常にパス数を数える。
  • component_key も component_node_id も持たないエントリは到達不能であり、ロード時に破棄される。インスタンスとして出力するとキャンバス上でビルドエラーのプレースホルダーになり、フォールバックが描くプリミティブなボックスより厳密に悪いためである。
  • キットはデザインシステムの部分集合ではなく、別のライブラリである。レジストリの読み取りはデザイン用のアクセサに束縛されたままとし、読み取りがキットへ流れてそのアトムが暗黙にデザインの候補になることを防ぐ。
  • 選択は事前計算テーブルではなく実行時にこのコレクションを読むため、キットを差し替えれば次の実行から効く: 現在登録されているキットに存在しないエントリは、その実行がロードするアトムに単に含まれない。キット固有のものはコードにもスキーマのデフォルトにも一切埋め込まない — キットの差し替えはここでのデータ変更だけで表現できる。
  • 選択・ガード・kit モードのフォールバックがこれらのフィールドをどう使うかは Des2WF ストア を参照。