Uitoolkit

---
name: unity-uitoolkit
description: "UI Toolkit (UITK) for Unity — create/edit USS stylesheets and UXML layouts, configure UIDocument + PanelSettings in scenes, generate EditorWindow / runtime UI scaffolds. This is the UXML/USS/VisualElement system; for Canvas-based UGUI use the `ui` module. Triggers: UI Toolkit, UITK, UXML, USS, UIDocument, PanelSettings, VisualElement, stylesheet, design token, CSS variable, flex, flexbox, flex-direction, runtime UI, EditorWindow UI, ScaleWithScreenSize, ConstantPixelSize, scaleMode, 界面工具包, UI样式, 样式表, 可视化元素, 弹性布局, 编辑器窗口, 设计令牌."
---

# Unity UI Toolkit Skills

Use this module for Unity UI Toolkit only: `UXML` for structure, `USS` for styling, `UIDocument` for scene attachment, and `PanelSettings` for runtime rendering.

> **Requires Unity 2022.3+**. Do not mix this module with `ui_*` UGUI/Canvas skills.
> **Localization**: Match visible UI text to the user's language. Chinese conversation -> Chinese labels/placeholders/button text. USS class names and CSS variables stay English.

## Operating Mode

- **Approval**（默认）：查询类 skill（`uitk_read_file` / `uitk_find_files` / `uitk_get_panel_settings` / `uitk_list_documents` / `uitk_inspect_uxml` / `uitk_list_uss_variables` / `uitk_inspect_document`，源码标 `SkillMode.SemiAuto`）直接执行；其余文件/场景写入类（`uitk_create_*` / `uitk_write_file` / `uitk_add_*` / `uitk_modify_element` 等，标 `SkillMode.FullAuto`）需用户 grant，grant 后服务端一步执行返结果。
- **Auto / Bypass**：未被禁列表拦截的 skill 直接执行。
- 本模块**含 Delete 类 skill**：`uitk_delete_file`、`uitk_remove_element`、`uitk_remove_uss_rule` 标记为 `SkillOperation.Delete`，被 `IsForbiddenInSemi` 静态拦截 —— 仅 **Bypass** 模式或加入 **Allowlist** 才能调用。
- **Asset 重导行为**：所有写文件/删文件 skill 通过 `AssetDatabase.ImportAsset(path)` 对单个 USS/UXML 资产单独触发导入，**不会**调 `AssetDatabase.Refresh()` 触发全项目扫描；批量创建依次单独 Import。但 USS/UXML 是 ScriptedImporter 类型，Import 仍会重建依赖此资产的 PanelSettings/UIDocument 引用，触发 IMGUI 检查器刷新与场景视图重绘。

**DO NOT** (common hallucinations):
- `uitoolkit_create_button` / `uitoolkit_create_label` do not exist -> use `uitk_add_element`
- `uitoolkit_set_style` does not exist -> use `uitk_add_uss_rule`, `uitk_remove_uss_rule`, or `uitk_modify_element`
- `uitoolkit_create_canvas` does not exist -> UI Toolkit uses `UIDocument`, not Canvas
- `uitk_*` and `ui_*` are different systems. Do not mix UI Toolkit structure/styling assumptions into UGUI workflows
- USS is **not full CSS**. `display:grid`, `box-shadow`, `calc()`, `@media`, `::before`, `z-index`, and gradients are unsupported

**Routing**:
- For UGUI Canvas/Button/Text/Image -> use the `ui` module
- For XR world-space Canvas conversion -> use `xr_setup_ui_canvas`
- For generated starter layouts -> use `uitk_create_from_template`
- For attaching an existing UXML to a scene object -> use `uitk_create_document` or `uitk_set_document`

## Skills

### File Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_create_uss` | Create USS file | `savePath`, `content?` |
| `uitk_create_uxml` | Create UXML file | `savePath`, `content?`, `ussPath?` |
| `uitk_read_file` | Read USS/UXML content | `filePath` |
| `uitk_write_file` | Overwrite file content | `filePath`, `content` |
| `uitk_delete_file` | Delete USS/UXML file | `filePath` |
| `uitk_find_files` | Search files by name/path | `type?`, `folder?`, `filter?`, `limit?` |
| `uitk_create_batch` | Create 2+ files in one call | `items` |

### Scene Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_create_document` | Create `UIDocument` GameObject | `name`, `uxmlPath?`, `panelSettingsPath?`, `sortOrder?`, `parentName?`/`parentInstanceId?`/`parentPath?` |
| `uitk_set_document` | Change UIDocument asset bindings | `name`/`instanceId`, `uxmlPath?`, `panelSettingsPath?` |
| `uitk_create_panel_settings` | Create PanelSettings asset | `savePath`, `scaleMode`, `referenceResolutionX/Y`, Unity 6 world-space options |
| `uitk_get_panel_settings` | Read PanelSettings values | `assetPath` |
| `uitk_set_panel_settings` | Update PanelSettings selectively | `assetPath`, changed fields only |
| `uitk_list_documents` | List scene UIDocuments | none |
| `uitk_inspect_document` | Inspect live VisualElement tree | `name`/`instanceId`/`path`, `depth` |

### UXML Structure Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_add_element` | Add a child element | `filePath`, `elementType`, `parentName?`, `elementName?`, `text?`, `classes?` |
| `uitk_remove_element` | Remove by `name` | `filePath`, `elementName` |
| `uitk_modify_element` | Change attributes/classes/text | `filePath`, `elementName`, `text?`, `classes?`, `style?`, `newName?`, `bindingPath?`, custom attribute fields |
| `uitk_clone_element` | Duplicate an element subtree | `filePath`, `elementName`, `newName?` |
| `uitk_inspect_uxml` | Parse UXML hierarchy | `filePath`, `depth?` |

### USS Style Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_add_uss_rule` | Add or replace selector rule | `filePath`, `selector`, `properties` |
| `uitk_remove_uss_rule` | Remove selector rule | `filePath`, `selector` |
| `uitk_list_uss_variables` | Inspect design tokens / `var()` usage | `filePath` |

### Template and CodeGen Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_create_from_template` | Generate paired UXML+USS | `template`, `savePath`, `name?` |
| `uitk_create_editor_window` | Generate EditorWindow script | `savePath`, `className`, `uxmlPath?`, `ussPath?`, `menuPath?` |
| `uitk_create_runtime_ui` | Generate runtime MonoBehaviour query scaffold | `savePath`, `className`, `elementQueries?` |

Supported starter templates include `menu`, `hud`, `dialog`, `settings`, `inventory`, `list`, `tab-view`, `toolbar`, `card`, and `notification`.

## Core Domain Knowledge

### USS vs CSS

| Pattern | Supported in USS | What to do |
|---------|------------------|------------|
| Flex layout | Yes | Use `flex-direction`, `flex-wrap`, `align-items`, `justify-content` |
| `border-radius`, `opacity`, `overflow:hidden` | Yes | Safe to use |
| Transforms / transitions | Yes | `translate`, `scale`, `rotate` work |
| CSS variables | Yes | Prefer `:root` tokens |
| `display:grid` / `display:block` / `display:inline` | No | Everything is flex; emulate grids with wrapping rows |
| `box-shadow` | No | Fake with nested background element |
| `linear-gradient()` / `radial-gradient()` | No | Use image textures |
| `calc()` / `@media` | No | Use explicit values + `PanelSettings.scaleMode` |
| `::before` / `::after` | No | Add a real child `VisualElement` |
| `z-index` | No | Later siblings render on top |

### Common USS workarounds

| Need | USS-safe workaround |
|------|---------------------|
| Shadow | Extra child `VisualElement` behind content |
| Responsive scaling | `PanelSettings.scaleMode = ScaleWithScreenSize` |
| Grid cards | `flex-direction: row` + `flex-wrap: wrap` + child widths |
| Circular avatar | Equal width/height + radius = half size + `overflow:hidden` |
| Pseudo decoration | Add an extra absolutely positioned child |

### High-Frequency Parameters

| Skill | Parameters you usually need first |
|-------|-----------------------------------|
| `uitk_create_panel_settings` | `savePath`, `scaleMode`, `referenceResolutionX`, `referenceResolutionY` |
| `uitk_create_document` | `name`, `uxmlPath`, `panelSettingsPath`, `sortOrder?` |
| `uitk_add_element` | `filePath`, `elementType`, `parentName?`, `elementName?`, `text?`, `classes?` |
| `uitk_modify_element` | `filePath`, `elementName`, changed attributes only |
| `uitk_add_uss_rule` | `filePath`, `selector`, `properties` |

### `PanelSettings` choices

- `ScaleWithScreenSize`: default for runtime HUD/menu UI
- `ConstantPixelSize`: use when strict pixel mapping matters
- `ConstantPhysicalSize`: rare; only for physically sized UI requirements

Unity 6 world-space flows also need the scene-side document camera setup after configuring PanelSettings.

### File and Structure Rules

- Prefer one UXML root that references shared token/style files through `<Style src="..."/>`.
- Keep USS next to UXML when possible so relative style references stay short.
- Use `uitk_inspect_uxml` before complex structural edits if you did not create the file yourself.
- `uitk_create_uxml` can auto-reference a stylesheet when `ussPath` is provided.

## Workflow Notes

1. Create USS/UXML first, then attach them through `uitk_create_document`.
2. Runtime rendering needs a valid `PanelSettings` asset.
3. When USS and UXML are in the same folder, prefer `<Style src="MyStyle.uss" />`; use a full asset path only for cross-folder references.
4. Start with design tokens, then component rules, then layout containers.
5. For incremental edits, prefer `uitk_read_file` -> edit -> `uitk_write_file`.
6. When creating 2+ files, use `uitk_create_batch`.
7. Unity 6 world-space rendering uses PanelSettings world-space options plus the scene-side `UIDocument` camera setup.
8. Use `uitk_create_from_template` when the user needs a starter screen fast; use `uitk_add_element` / `uitk_add_uss_rule` for targeted edits on existing files.

## Minimal Example

```python
import unity_skills

unity_skills.call_skill("uitk_create_panel_settings",
    savePath="Assets/UI/GamePanel.asset",
    scaleMode="ScaleWithScreenSize",
    referenceResolutionX=1920,
    referenceResolutionY=1080
)

unity_skills.call_skill("uitk_create_uss",
    savePath="Assets/UI/HUD.uss",
    content=":root { --accent: #E8632B; } .title { color: var(--accent); }"
)

unity_skills.call_skill("uitk_create_uxml",
    savePath="Assets/UI/HUD.uxml",
    content="<?xml version=\"1.0\" encoding=\"utf-8\"?><engine:UXML xmlns:engine=\"UnityEngine.UIElements\"><Style src=\"HUD.uss\" /><engine:Label class=\"title\" text=\"Start\" /></engine:UXML>"
)

unity_skills.call_skill("uitk_create_document",
    name="HUD",
    uxmlPath="Assets/UI/HUD.uxml",
    panelSettingsPath="Assets/UI/GamePanel.asset"
)
```

## Exact Signatures

Exact names, parameters, defaults, and returns are defined by `GET /skills/schema` or `unity_skills.get_skill_schema()`, not by this file.
Load `USS_REFERENCE.md` before generating non-trivial USS systems, layout patterns, component styles, or complete examples.