WF2Des — 使い方

Summary

WF2Des は、ワイヤーフレームのフレームを Figma のネイティブなデザインに変換します。生成に使うのは、そのプロジェクトに登録済みのコンポーネントとデザイントークンだけです。
新しい UI を描き起こすツールではありません。ワイヤーフレームの各部分をどの登録済みコンポーネントにするかを判断し、レイアウトと文言を保ったまま、開いているファイル上に組み立てます。

事前準備

操作はすべて Figma プラグイン内で完結します。生成の前に以下を用意してください。

1. サインイン

Plabs アカウントでサインインします。プロジェクトの選択が必要です — デザインは常に、そのプロジェクトのレジストリとルールに基づいて生成されます。

2. デザインシステムを含むファイルを開く

生成に使うコンポーネントは、ワイヤーフレームと同じ Figma ファイル内に存在する必要があります。開いているファイルで見つからないコンポーネントは配置できません。

3. ボードを準備する

セットアップでは 2 種類のボードを読み取ります。

ボード	内容
コンポーネントボード	デザインシステムのコンポーネントセット（ボタン、フォーム項目、ヘッダー、カードなど）
ガイドラインボード	記述されたルール（カラー、タイポグラフィ、スペーシング、コンポーネント別の用法）

初回セットアップ

Setup タブを開きます。どちらの手順もキャンバスの選択を読み取るため、先にボードのフレームを選択してください。

1. コンポーネントライブラリ

コンポーネントボードを選択し、Review sync → Confirm sync を実行します。

進行は Resolve → Sweep → Register → Save の 4 ステップで表示されます。選択したボード上のコンポーネントセットをすべて読み取り、バリアント、テキストスロット、サイズ、publish key を記録します。

Note

同期が Completed になった後、Figma から直接バリアント詳細を取得する 2 回目のパスが走ります。選択したボードの全ノードを走査するため、大きなライブラリでは数分かかるのが正常です（処理中は走査済みノード数が表示されます）。同期結果はすでに保存済みで、この処理は情報を追加するだけです。

確認方法: What's in the registry を開くと、ボード単位で登録内容が一覧表示されます。

2. デザインルールボード

ガイドラインボードを選択し、Review upload → Confirm upload を実行します。

進行は Render → Extract → Merge → Save で表示され、ルールセットの新しいリビジョンが作成されます。過去のリビジョンは保持されます。Current rules & history でカラー・タイポグラフィ・スペーシングを確認でき、 Revert で任意のリビジョンに戻せます。

デザインを生成する

Generate タブを開きます。

変換したいワイヤーフレームのフレームを 1 つだけ選択します。複数選択やフレーム以外のノードは受け付けられず、理由が表示されます。
必要に応じて Screen id を指定します。空欄の場合はフレーム名から導出されます。
Generate design を押します。

進行は Trigger → Parse → Assemble → Build の 4 ステップです。parse と assemble はサーバー側、 build は開いているファイル内で実行されます。監視を停止（処理は継続） はいつでも押せます — 実行はサーバー側で継続し、後から再接続できます。

完了すると Total / Placed / Unmatched が表示されます。

結果の読み方

表示	意味
Placed	登録済みコンポーネントから生成され、ワイヤーフレームの文言がスロットに配置された
Unmatched	レジストリに合致するものがなかった。破線のオレンジ枠で描画され、欠落が見えるようになる（黙って省略されることはない）
ワイヤーフレームに画像があった箇所の破線枠	本来は起きません。実画像はワイヤーフレームから自動的に複製されます。表示された場合、元ノードに画像塗りがありません
ワイヤーフレームより行数が増えたテキスト	正常です。デザインシステムのフォントはワイヤーフレームのものと異なるため、縦に伸びます

出力は 1 つのフレームで、単一の undo ステップとして構築されます（undo 1 回で丸ごと取り消せます）。同じワイヤーフレームを再生成すると、横に増えるのではなく前回の出力を置き換えます。

うまくいかないとき

「Attached to a run already in progress…」と表示される
同じフレームに対する実行がまだ開いています。1 つのワイヤーフレームにつき同時に実行できるのは 1 件です。完了しないまま残った実行は、キャンセルされるまで新規実行をブロックします。

「select exactly one frame」/「selected node is not a frame」
ワイヤーフレームは単一の FRAME である必要があります。グループや複数選択は受け付けられません。

すべてが破線枠になる
このプロジェクトのレジストリが空か、別のファイルを開いています。先にコンポーネント同期を実行し、 What's in the registry を確認してください。

コンポーネントは配置されるがバリアントが違う
レジストリはコンポーネントを把握していますが、どのバリアントを使うかの情報が不足しています。コンポーネント同期を再実行し、各バリアントの内容を取得させてください。

更新後もプラグインの表示が古いまま
プラグインを一度閉じて開き直してください。UI はバンドルされているため、再読み込みで最新ビルドが反映されます。

このツールがしないこと

出力を正しく読むために、明示しておきます。

コンポーネントを創作しません。デザインシステムに該当コンポーネントがないものは unmatched のままです。
ワイヤーフレームの構造を作り直しません。レイアウト・順序・文言は意図的に保持されます — ワイヤーフレームが誤っていれば、デザインもそのとおり誤って再現されます。
デザインレビューの代わりにはなりません。confidence とフラグは「確認すべき箇所」を示すものであり、「正しさ」を保証するものではありません。

ローカル運用と評価

WF2Des は、プロジェクトのコンポーネントライブラリとデザインルールを使って、登録済み Figma ワイヤーフレームをネイティブ Figma ノードへ変換します。このセクションはローカル運用、診断、モデル評価を説明します。コマンドは guinness-ai-v2 ルートで実行してください。

前提条件

apps/wf2des/.env.example を apps/wf2des/.env.dev にコピーし、Figma OAuth（推奨）または FIGMA_PAT と、必要なモデルプロバイダー認証情報を設定する。
ローカル backend/harness、port 4566 の LocalStack、port 27019 のデータ投入済み Mongo を起動する。
一度 uv sync を実行する。

キュー済みジョブの処理

# Terminal 1: generation queue
uv run python -u apps/wf2des/scripts/consume_local.py

# Terminal 2: onboarding / component / actual-render review events
LOCAL_SQS_QUEUE_URL=http://localhost:4566/000000000000/wf2des-events \
  LOCAL_SQS_VISIBILITY_TIMEOUT=1800 uv run python -u apps/wf2des/scripts/consume_local.py

ローカル plugin flow 全体には両方の bridge が必要です。1 つ目は generation、2 つ目は registration、sweep、capture、および placement 後の visual review を処理します。どちらのコマンドにも --once を追加すると現在取得できるメッセージを処理して終了します。これは状態を変更する本番経路の実行で、SQS 消費、Figma 読み取り、モデル呼び出し、Mongo/S3 書き込み、ローカル status webhook 送信を行います。bridge は各メッセージ前に source mtime を確認し、読み込み済みコードが古い場合は停止します。コード変更後は再起動してください。

安全な確認とリプレイ

コマンド	用途	変更とコスト
`uv run python apps/wf2des/scripts/inspect_local.py 1 7`	collection 件数と tenant-scope record を確認	読み取り専用
`uv run python apps/wf2des/scripts/replay_generation.py RUN_ID --output-dir /tmp/wf2des-replay`	元 run の pin 済み source/component/rule/model/prompt version で再 assembly	ローカルファイルのみ。DB/S3/webhook/ledger は非変更。model cost が発生し得る
`uv run python apps/wf2des/scripts/replay_generation.py RUN_ID --stored --output-dir /tmp/wf2des-replay`	再 assembly せず保存済み result を export	ローカルファイルのみ。model call なし
`uv run python apps/wf2des/scripts/review_render.py --help`	明示的な source/output PNG を本番 render reviewer で評価	ローカルファイルのみ。DB/S3/queue/Figma は非変更。review model cost が発生し得る

リプレイは元の pin を保持します。新しい source manifest を指定する場合は元 generation のリプレイではなく実験なので、output をそのように区別してください。

Registry メンテナンス

コマンド	用途	変更とコスト
`uv run python apps/wf2des/scripts/sweep_components.py "FIGMA_URL" 7`	deterministic REST sweep を local `design_component` に実行	local Mongo と snapshot file を変更。LLM なし
`uv run python apps/wf2des/scripts/classify_slot_roles.py --org 1 --project 7 --dry-run`	content/placeholder 分類を preview	書き込みなし。未分類文字列の model cost が発生
`uv run python apps/wf2des/scripts/classify_slot_roles.py --org 1 --project 7`	分類を保存	`project_figma_file.slot_roles` を更新。model cost が発生
`uv run python apps/wf2des/scripts/tag_component_semantics.py --org 1 --project 7`	未設定 semantic tag を preview	registry 書き込みなし。model cost が発生し得る
`uv run python apps/wf2des/scripts/tag_component_semantics.py --org 1 --project 7 --apply`	component/variant の visual semantics を保存	component registry を変更。vision-model cost が発生

モデル設定

本番 default は matching と whole-screen review に openai:gpt-5.4、vision ingestion に openai:gpt-5.4-mini を使用します。model ID は provider prefix 付きで parse 時に pin されます。 Anthropic 直結は anthropic:... と ANTHROPIC_API_KEY を使います。OpenRouter は OPENAI_BASE_URL=https://openrouter.ai/api/v1、OPENAI_API_KEY に OpenRouter token、 openai:anthropic/claude-sonnet-4.6 のような model を使います。非 GPT review model では SCREEN_REVIEW_REASONING_EFFORT=none を設定してください。

ab_model_test.py は workspace/ab/ に local output を書く有料の評価ツールで、本番処理の一部ではありません。

失敗時の動作

credit 枯渇、無効な認証/アクセス権、利用不能な設定 model は再配信では直りません。worker は failed artifact/manifest を記録し、安全な error を client に表示します。通常の rate limit と provider 5xx は retryable のまま SQS 再配信へ返します。

plugin の materialization diagnostics は別に記録されます。event 値は name_fallback、 ordinal_fallback、build_error、font_fallback、prop_rejected、unmatched、preserved です。