uitk-import: デザイン→UXML/USS→Unity検証 自動化スキル

デザインソースからUnityで表示・動作確認済みのUXML/USSを作るまでの全工程。

前提

• Unityプロジェクトを unity-cli-loop（uLoopMCP） で操作できること（uloop-compile / uloop-screenshot / uloop-execute-dynamic-code 等の同梱スキルを使う）
• UI Toolkitの画面確認はwindowモードスクショ、UI操作はSendEvent方式で行う（uloop-uitk-interact スキル参照。renderingモードはUI Toolkitが正しく写らず、simulate-mouse系はUI Toolkitに届かない）
• 生成後のUSSは references/css-to-uss-checklist.md で必ず自己検査する
• プロジェクト固有の設定（UXML/USSの配置先・機能要件や要素名の契約・結線するコントローラ名）は、プロジェクトの CLAUDE.md や要件ドキュメントで指定されている前提。無ければ人間に確認する

手順

0. 前提チェック（ゲート — 満たさなければ中断して人間に依頼）

0. MCPツールの存在確認: ローカルDev Modeサーバー（Figmaデスクトップアプリ内蔵）のMCPツール（get_metadata等）がツール一覧に見えるか確認。見えない場合は代替手段で進めず中断して人間に報告する。MCP接続はセッション開始時にしか張られないため、復旧はFigmaデスクトップアプリ（対象ファイルを開いた状態）を先に起動してからセッションを開き直してもらうのが確実。似た名前のリモートコネクタ（選択ノードを取得できないもの）と取り違えないこと
1. フレームサイズ検査: get_metadata で選択フレームの width/height を確認。Game Viewの検証解像度（推奨1920x1080）と不一致なら中断し、Figma側でのリサイズを人間に依頼する（一致しないとピクセル比較が成立しない）
2. 正解画像の確認: 正解画像置き場（例: docs/design-refs/<画面名>.png）に人間がFigmaからエクスポートしたPNG（1x・検証解像度と同サイズ）があるか確認。無ければ人間に依頼する（Figmaで対象フレームを右クリック→Export）
   • MCPの get_screenshot はチャット内でしか画像を見られずファイル保存できない。目視比較には使ってよいが、正解画像の代わりに自作のHTML再現を使うことは禁止（自分の再現物と照合する循環評価になり、ground truthが失われる）

1. 入力の正規化

• Figma MCP経由の場合: get_variable_defs → get_design_context（get_code） → get_screenshot（目視用）
  • get_variable_defs が {} なのは正常系（Figma Make生成物はFigma Variablesを持たない）。トークンの正は次の優先順で採用する: ①壁打ちで確定したデザイン選好ドキュメント（例: docs/デザイン選好.md） ②get_design_contextのCSS実測値
  • get_codeのReact+Tailwind出力は「デザインの表現」であって最終コードではない。UXML/USSへ翻訳する（Figma公式の位置づけ）
• HTML/CSSやテキスト仕様の場合: 要素ツリーとスタイル値を抽出してから変換に入る

1.5. 要件対照チェック（実装前・必須）

デザインの要素一覧と機能要件を突き合わせ、要件にない要素を列挙する（例: 設定/実績ボタン・装飾的な統計表示など、生成AIが自主的に追加しがちな要素）。各要素を 残す(装飾) / 消す / ロジック結線する のいずれにするか人間に確認してから実装する（プロジェクト側で方針が決まっていればそれに従う）。

動的生成コードとの契約ズレも同時に確認する: デザインの構造（例: リスト行のアイコン・レート表示・バッジ）が、実行時にコードが生成する構造より豊かな場合、デザイン側を先回りして貧しくしない。人間に確認の上、このワークフローの中でコントローラ側の生成コードを拡張し、手順5の結線検証で確かめる。

演出仕様も要件として取り込む: アニメーション・エフェクト（押下時スケール、カウント加算の浮遊表示等）は、デザインを静的ファイルに貼り出した時点で失われておりMCPからは取得できない。壁打ちログ等の演出仕様（どの操作で何がどう動くか）を確認し、USSの transition / コントローラ側実装としてこのワークフローの中で実装する。演出仕様が文書に無ければ人間に確認する。

2. UXML/USS生成

• トークンはハードコードせずUSSカスタムプロパティにする: :root { --color-primary: #xxxxxx; } → color: var(--color-primary);（var()は関数の中では使えない点に注意）
• 配置先: プロジェクト指定のUIディレクトリ（例: Assets/_Project/UI/<画面名>.uxml / <画面名>.uss）
• 絵文字はそのまま使う（🍙等）。「Unityでは豆腐化する」と思い込んで図形や画像に代替しない — UI Toolkitはシステムの絵文字フォントにフォールバックし、300px程度までカラー描画できる（Unity 6 / macOSで実機検証済み。他OSビルドでは要再確認）。歯車等は字形バリアント注意（⚙ではなく⚙️=U+FE0F付き）
• フォント: デザインが指定するフォントが未導入なら、このワークフローの中で導入する（事前に仕込まない）。再配布可能なライセンス（OFL等）か確認し、ライセンス文を同梱し、プロジェクトのクレジット記録（参考文献ドキュメント等）に追記した上で、USSから相対参照する:

  .root { -unity-font-definition: url("../Fonts/YourFont-Regular.ttf"); }
  

• インタラクション状態も写す: デザインのhover/押下表現を :hover / :active ＋ transition で再現する（例: .main-button { transition: scale 0.08s ease-out; } .main-button:active { scale: 0.92; }）
• 生成直後に references/css-to-uss-checklist.md の全項目で自己検査し、違反を直してから次へ進む

3. シーン配置（検証用シーンを新規作成 — 既存シーンに触らない）

既存シーンは変更しない。 検証は専用シーン（例: Assets/_Project/Scenes/UITKImportTest.unity）で行う。 以下のcsxをテンプレートとして execute-dynamic-code --code-file で実行する（__UXML_PATH__ / __SCENE_PATH__ / __PANEL_SETTINGS_PATH__ / __THEME_PATH__ を差し替え）。 注意: csx内に絵文字リテラルを書くと不安定。絵文字が必要な場合は \U0001F359 形式のエスケープを使う。

using UnityEngine;
using UnityEditor;
using UnityEngine.UIElements;
using UnityEditor.SceneManagement;

AssetDatabase.Refresh();

string uxmlPath = "__UXML_PATH__";                      // 例: Assets/_Project/UI/TitleScreen.uxml
string scenePath = "__SCENE_PATH__";                    // 例: Assets/_Project/Scenes/UITKImportTest.unity
string panelSettingsPath = "__PANEL_SETTINGS_PATH__";   // 例: Assets/_Project/UI/ScreenPanelSettings.asset
string themePath = "__THEME_PATH__";                    // 例: Assets/_Project/UI/UnityDefaultRuntimeTheme.tss

// 検証用シーンを開く（なければ新規作成して保存）
// ※必ずシーン切替を先に行うこと。シーン切替(NewScene/OpenScene)の前に取得したアセット参照を
//   切替後のオブジェクトに代入すると、保存時に参照が失われることがある（実測）
var scene = EditorSceneManager.GetActiveScene();
if (scene.path != scenePath)
{
    if (AssetDatabase.LoadAssetAtPath<SceneAsset>(scenePath) == null)
    {
        var newScene = EditorSceneManager.NewScene(NewSceneSetup.DefaultGameObjects, NewSceneMode.Single);
        EditorSceneManager.SaveScene(newScene, scenePath);
        scene = newScene;
    }
    else
    {
        scene = EditorSceneManager.OpenScene(scenePath);
    }
}

// PanelSettings（共用アセットを再利用、なければ作成）— シーン切替の後に読み込む
var panelSettings = AssetDatabase.LoadAssetAtPath<PanelSettings>(panelSettingsPath);
if (panelSettings == null)
{
    var theme = AssetDatabase.LoadAssetAtPath<ThemeStyleSheet>(themePath);
    panelSettings = ScriptableObject.CreateInstance<PanelSettings>();
    panelSettings.themeStyleSheet = theme;
    panelSettings.scaleMode = PanelScaleMode.ScaleWithScreenSize;
    panelSettings.referenceResolution = new Vector2Int(1920, 1080);
    AssetDatabase.CreateAsset(panelSettings, panelSettingsPath);
}

var existing = GameObject.Find("ImportedUI");
if (existing != null) Object.DestroyImmediate(existing);
var go = new GameObject("ImportedUI");
var uiDoc = go.AddComponent<UIDocument>();
uiDoc.panelSettings = panelSettings;
uiDoc.visualTreeAsset = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>(uxmlPath);

EditorSceneManager.MarkSceneDirty(scene);
EditorSceneManager.SaveOpenScenes();
return "scene=" + scene.path + ", uxml=" + (uiDoc.visualTreeAsset != null);

3.5. 配置後の必須確認

csx実行後、PlayModeに入る前に参照が保存されたか確認する（execute-dynamic-codeで doc.panelSettings != null && doc.visualTreeAsset != null をチェック）。nullならシーンを開いた状態で再代入して保存する。 症状: panelSettingsがnullのままPlayすると、エラーも出ずにUIが一切描画されない。

4. コンパイル→スクショ→自己評価ループ

npx --yes uloop-cli@<バージョン> compile --project-path <proj>
npx --yes uloop-cli@<バージョン> control-play-mode --action Play --project-path <proj>
npx --yes uloop-cli@<バージョン> screenshot --window-name Game --output-directory <スクショ保存先> --project-path <proj>

自己評価は必須ゲート（スクショを撮らずに完了と言わない）。正解画像は手順0で確認した人間エクスポートのPNGを使い、以下の4観点を別々に評価する:

1. レイアウト: 要素の位置・整列・重なり・見切れ（正解画像とスクショを並べて比較）
2. 色・トークン準拠: 主要色がトークン値と一致するか（目測せずUSSの値とデザイン側の値を突き合わせる）
3. テキスト: 文言・フォントサイズ・折返し・文字化け（日本語フォント）
4. 余白・サイズ: 基準余白の一貫性、ボタン等の実寸

不一致があればUSS/UXMLを修正して手順4を繰り返す（最大5回。収束しない場合は人間にエスカレーション）。

5. 結線検証（見た目OKの後・必須）

UIは表示できてもゲームロジックが付いていなければ動作確認になっていない。

1. ImportedUI にプロジェクト指定のコントローラ（例: ClickerScreenController）を AddComponent で付与する
2. Play → uloop-uitk-interact の方式（SendEvent）でクリック等の操作を実行し、ラベル値をreturnで検証する（要素名・クラス契約がC#と噛み合うかの確認）
3. スクショで動作後の見た目も確認（動的生成された要素がUSSスタイルと噛み合っているか）
   • ※:active などの押下表現・演出（浮遊テキスト等）はSendEventや静止画では確認しきれない。演出仕様との照合を人間レビュー項目として明記し、実装漏れがないかレビュー依頼時に列挙する

6. 後始末とコミット

• Playモード停止（control-play-mode --action Stop）
• スクショ（失敗版含む）は削除せず保存したままにする（試行錯誤の記録として価値がある）
• 工程ごとにコミット: feat(ui): <画面名>のUXML/USS生成 → feat(ui): <画面名>検証OK など

精度のための決まりごと

• Figmaフレームは検証解像度（推奨1920x1080）で作らせる（Game Viewの解像度と一致させ、ピクセル比較を成立させる）。手順0でゲート済み
• 正解画像との比較は「見た印象」ではなく要素単位で座標・サイズ・色を列挙して差分を書き出す
• 「AIがスクショを見て問題なしと判定しても人間には崩れて見える」ケースは実際に起きる。最終判定は人間。ループの終わりに必ずスクショのパスを提示してレビューを求める
• 検証せずに「できない」と判断しない（例: 「絵文字は豆腐化するはず」という思い込みで図形に代替して品質を落とした実例がある）。不確かな制約は最小の実機テストで確認してから代替策を取る