ui-uitk

既存の Unity UI Toolkit コードを理解し、対象を絞って編集し、新しい UXML／USS ファイルや Manipulator を作成し、UI のランタイムバインディングを処理します。

参考資料

必要に応じて、以下を読んでください。

• references/uss-guide.md — USS のパターンと例
• references/svg-icons.md — SVG アイコンの生成（アイコンを生成する場合のみ）
• references/common-issues.md — 避けるべきよくある間違い
• references/ui-runtime-binding.md — 実行時にデータを UI にバインドするためのパターンとガイド（依頼された場合、またはバインディングが関係する場合のみ）
• references/painter2d.md — カスタムビジュアル向けの Painter2D API：グラデーション、図形、円弧、プロシージャル描画（グラデーション、カスタム図形、進行状況リング、プロシージャル描画、または USS で表現できる範囲を超えるビジュアルが必要な場合は、必ず読んでください）
• references/pointermanipulator-guide.md — Manipulator を作成して使用するためのパターンとガイド（依頼された場合、または Manipulator が関係する場合のみ）。Visual Element のドラッグ＆ドロップ機能や簡単なイベント処理を設定する際に役立ちます。
• references/custom-elements.md — UXML、USS、C# を使用して再利用可能なコンポーネントを作成するためのカスタム UI Element のパターンとガイド。プロジェクト内で複雑な UI コンポーネントを再利用する際に役立ちます。

パスはこのスキルのフォルダーからの相対パスです。references/uss-guide.md を直接読んでください。

理解

UI 構造を説明するときは、次の形式を使用してください。

[ElementType] name="elementName" class="class1 class2"
├── [ChildType] name="childName"
│   └── [GrandchildType]
└── [ChildType] class="another-class"

編集

よくある編集依頼：

依頼	対応
「ボタンの色を変えて」	そのボタンの USS セレクターを編集します
「ここにラベルを追加して」	指定された位置の UXML に要素を追加します
「これを大きくして」	USS で幅／高さを編集します
「この要素を非表示にして」	USS に display: none を追加するか、UXML から削除します
「この要素の名前を変えて」	UXML の name 属性を更新します

過剰に編集しないでください。

• 依頼された箇所だけを変更します
• 書式と構造を維持します
• 関係のないコードを「改善」しないでください
• 求められない限り、コメントを追加しないでください
• 対象を絞った変更では、ファイル全体を書き直すより、特定の要素やセレクターを変更することを優先します。ただし、適宜判断してください。ファイルの大部分に変更が及ぶ場合は、書き直したほうが明確なこともあります
• 編集時に既存の要素、スタイル、参照を誤って削除しないよう注意してください
• USS を編集する場合、依頼に関係するプロパティとセレクターに注力してください。不必要な再構成は避けますが、変更に本当に必要な場合は構成を変更してください

検証

Editor の外部から UXML や USS を検証する方法はありません。Unity はインポート時にこれらのファイルを解析し、問題があれば Console に報告します。ファイルを書き込んだら、ユーザーに結果を確認してもらってください。

ワークフロー：

1. プロジェクト内の対象パスに完全なファイルを書き込みます。部分的な内容や下書きは書き込まないでください。書きかけの UXML ファイルは、Editor が認識した時点で解析エラーになります。
2. Unity Editor にフォーカスするようユーザーに依頼します。これにより、変更されたアセットが再インポートされます。
3. Console に表示された内容を報告するようユーザーに依頼します。UXML の解析エラーにはファイル名と行番号が示され、USS の問題は不明なプロパティやセレクターに関する警告として表示されます。
4. 報告された問題を修正し、手順 1 から繰り返します。

ユーザーとのやり取りが必要になるため、最初から正しく仕上げてください。

• ユーザーに確認を依頼する前にすべてのファイルを完成させてください。ファイルごとに再インポートするのではなく、一度の再インポートですべて確認できるようにします
• エラーが返ってきてからではなく、書き込み前に references/uss-guide.md と references/common-issues.md を読み直してください
• 解析は通っても描画が誤るようなミスに注意してください。こうした問題は Console に表示されないため、ユーザーが UI を目視で確認する必要があります。references/common-issues.md に一覧があります

生成

新しい UI を作成する場合：

依頼されたものだけを生成します：

依頼	出力
USS のみ	.uss ファイルのみ
UXML のみ	.uxml ファイルのみ
UI 画面／メニュー／パネル	.uss + .uxml のみ
「コード付き」／「ロジック付き」／「機能する」	.uss + .uxml + .cs

次の依頼は C# を意味しません：

• 「適切なボタン」→ スタイルが適切に設定された Button 要素
• 「通貨表示」→ Label 要素
• 「動作する UI」→ 描画される有効な UXML/USS
• 「インベントリ画面」→ 見た目のレイアウトのみ
• 「インベントリシステム」／「装備システム」／「クラフトシステム」→ 「アイテムをドラッグ可能にしますか？」と確認します。可能にする場合は、パターンについて references/pointermanipulator-guide.md を参照してください。

生成ワークフロー：

1. 分析 — 必要なファイルを正確に判断します。余分なファイルは作りません。
2. 検索 — 既存の USS、UXML、アセットを探します。パスを決めつけないでください。
3. プロジェクトのパターンに従う — フォルダー構造と命名規則を合わせます。
4. 再利用 — 共有スタイルシートがあるか確認します。適切であれば再利用します。
5. USS を先に作成 — 以下の制限に照らして確認します。
6. UXML を作成 — USS を参照し、構造を確認します。
7. ファイルを完全な状態で出力 — 内容を途中で省略しないでください。エラーがどのように返されるか、また複数回に分けるより一度にファイルを出力するほうがよい理由については、上記の「検証」を参照してください。
8. シーンの設定 — UI をシーンに追加する場合は、PanelSettings を割り当てます。
9. データバインディング — 依頼された場合は、実行時データバインディングのパターンを使った C# スクリプトを追加します（references/ui-runtime-binding.md を参照）。必要に応じてスクリプタブルオブジェクトのアセットを生成します。UXML の UI 要素ルート、または C# のデータソースを介してアセットを割り当てます。

色、視認性、仕様のルール：

• デフォルトでテキストを読みやすくする： 色を選ぶ際は、テキストと背景のコントラストを確保します。ただし、意図的にコントラストを低くしている用途（無効状態、プレースホルダーテキスト、装飾要素）は尊重します。デザイントークンを使う場合は、テキストと背景の変数が十分なコントラストを確保しているか確認します。
• 指定値を正確に守る： ユーザーが指定した HEX カラー、ピクセル寸法、間隔は、そのまま使用します。近似値にしたり、別の値に置き換えたりしないでください。

スタイリング／テーマ UI のスタイリングやテーマの調整では、現在の UXML に直接含まれる要素だけでなく、通常は複数の子要素で構成される UI Toolkit のコア要素にもスタイルが適用されるようにしてください。

規約

まずプロジェクトのパターンに従います。 デフォルトを適用する前に既存のファイルを検索してください。

種類	規約	良い例	悪い例
name 属性	camelCase	submitButton	submit-button
class 属性／USS	kebab-case	.submit-button	.submitButton
ファイルパス	機能別フォルダー	Assets/UI/Inventory/	Assets/Scripts/UI/

出力形式：

<ui:UXML>...</ui:UXML>

.class { ... }

USS の制限事項

Unity の USS は CSS のサブセットです。以下のプロパティは存在しません。絶対に使用しないでください。

使用禁止	代わりに使用
border のショートハンド	border-width と border-color を個別に指定
gap	子要素に margin を指定
z-index	DOM の順序または親要素のネスト
pointer-events	UXML 属性の picking-mode
filter	サポートされていません
outline	border-* プロパティ
box-shadow	ネストした要素または背景画像
:first-child、:last-child、:nth-child	明示的なクラス
[attribute] セレクター	明示的なクラス
transition-property: <value>	完全に省略するか、none／initial／inherit のみを指定
linear-gradient()、radial-gradient()	Painter2D を使用したカスタム VisualElement（references/painter2d.md を参照）

インラインスタイル： UXML では style="..." を絶対に使用しないでください。スタイルはすべて USS のみに記述します。

外部 URL： 外部パスに対して url() を絶対に使用しないでください。url("project://database/Assets/...") のみ使用できます。

ハードコードしたサイズより柔軟なレイアウトを優先してください：

• 固定の width／height 値の代わりに、flex-grow、flex-shrink、または % を使用します
• 要素は自然に配置し、親コンテナーによって制約されるようにします
• ピクセル単位のサイズを明示するのは、ルートコンテナー、または固定サイズが本当に必要な場合のみにします
• 子要素は独自の寸法を定義するのではなく、使用可能なスペースに合わせて調整します

USS の簡潔さ

• デフォルト値を指定しない（flex-direction: column がデフォルトです）
• デフォルトのフォントを指定しない
• 冗長な制約を指定しない（width: 100px に min-width／max-width は不要です）
• 重複するプロパティを指定しない（flex: 1 はすでに grow／shrink を設定します）
• 動作する最もシンプルなセレクターを使用する
• セレクターを重複させない

UXML

すべてのファイルで、次の条件を満たす必要があります。

1. 名前空間を宣言する：<ui:UXML xmlns:ui="UnityEngine.UIElements">
2. スタイルシートをリンクする：<ui:Style src="Screen.uss" />
3. トップレベルのコンテナーをちょうど 1 つ持つ
4. style="..." 属性を使用しない — USS のみを使用する

<ui:UXML xmlns:ui="UnityEngine.UIElements">
  <ui:Style src="Panel.uss" />
  <ui:VisualElement name="root" class="panel">
    
  </ui:VisualElement>
</ui:UXML>

イベントとインタラクティブ機能

• VisualElement のイベント処理とインタラクティブ機能には、ポインターマニピュレーターを使用します（references/pointermanipulator-guide.md を参照）
• ドラッグ＆ドロップが求められている場合は、ポインターマニピュレーターを実装し、UXML 内または C# 経由で該当する Visual Element にアタッチします。
• シンプルなクリックイベントには、UXML の clickable マニピュレーターを使用できます
• より高度なインタラクションには、従来の C# イベントコールバックを作成し、必要に応じて要素にアタッチします

インベントリシステムとクラフトシステムの場合：

• ユーザーから「インベントリシステム」「装備システム」「クラフトシステム」の依頼があった場合は、明確に「プレイヤーはアイテムをドラッグ＆ドロップできるようにしますか？」と確認します。
• はいの場合は、インベントリ／クラフト固有のパターンについて references/pointermanipulator-guide.md を読みます
• いいえ、または不明確な場合は、静的なレイアウトのみを作成します

アセット

UnityDefaultRuntimeTheme.tss または Unity の組み込みテーマアイコンを参照しないでください。

アイコンの優先順位：

1. 既存のプロジェクトアイコンを再利用する
2. SVG を生成する（references/svg-icons.md を参照）
3. 画像生成ツールを使用する（最後の手段）

参照形式：

background-image: url("project://database/Assets/UI/Textures/icon.png");

シーンのセットアップ

PanelSettings は必須です — ないと UI は描画されません。

1. 既存の PanelSettings アセットを検索します
2. なければ、汎用アセットを作成します：Assets/UI/PanelSettings.asset
3. UIDocument の Panel Settings フィールドに割り当てます

Editor UI（EditorWindow、PropertyDrawer）では省略します。

C#（依頼があった場合のみ）

• USS クラス（AddToClassList()）でスタイルを設定します。element.style.* は使用しないでください。インラインスタイルは USS セレクターより優先度が高く、スタイルシートで上書きできないうえ、要素ごとのメモリーオーバーヘッドが発生するためです
• UITK では TextCore テキストアセットを使用します。TMP_FontAsset などの TextMeshPro 相当物ではなく、FontAsset、TextStyleSheet、TextSettings を使用します
• スクリプトは UXML／USS と同じフォルダーに配置します