ui-uitk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Understand existing Unity UI Toolkit code, make targeted edits, generate new UXML/USS files, Manipulators, and handle UI runtime binding.

理解现有Unity UI Toolkit代码，进行针对性编辑，生成新的UXML/USS文件、Manipulators，并处理UI运行时绑定。

References

参考资料

Read these as needed:

```
references/uss-guide.md
```
— USS patterns and examples
```
references/svg-icons.md
```
— SVG icon generation (only when generating icons)
```
references/common-issues.md
```
— Common mistakes to avoid
```
references/ui-runtime-binding.md
```
— Patterns and guide to bind data to UI at runtime (only when requested or when bindings are involved)
```
references/painter2d.md
```
— Painter2D API for custom visuals: gradients, shapes, arcs, procedural drawing (read this whenever gradients, custom shapes, progress rings, procedural drawing, or any visual beyond what USS can express is needed)
```
references/pointermanipulator-guide.md
```
— Patterns and guide to create and use Manipulators (only when requested or when manipulators are involved). This helps with setting up drag and drop features or simple event handling for a Visual Element.
```
references/custom-elements.md
```
— Custom UI Element patterns and guide to create reusable components with UXML, USS, and C#. This helps with creating complex UI components for reuse across the project.

Paths are relative to this skill's folder — read

references/uss-guide.md

directly.

按需阅读以下内容：

```
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
```
— 创建和使用Manipulators的模式与指南（仅在有相关请求或涉及Manipulators时使用）。这有助于为Visual Element设置拖放功能或简单事件处理。
```
references/custom-elements.md
```
— 自定义UI元素的模式与指南，可通过UXML、USS和C#创建可复用组件。这有助于创建可在项目中复用的复杂UI组件。

路径相对于本技能的文件夹——直接读取

references/uss-guide.md

即可。

Understanding

理解代码

When explaining UI structure, use this format:

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

解释UI结构时，请使用以下格式：

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

Editing

编辑操作

Common edit requests:

Request	Action
"Change button color"	Edit USS selector for that button
"Add a label here"	Add element to UXML at specified location
"Make this bigger"	Edit width/height in USS
"Hide this element"	Add `display: none` to USS or remove from UXML
"Rename this element"	Update `name` attribute in UXML

Don't over-edit:

Change only what's requested
Preserve formatting and structure
Don't "improve" unrelated code
Don't add comments unless asked
For targeted changes, prefer modifying specific elements or selectors over rewriting entire files — but use judgment; if a change touches most of the file, a rewrite may be cleaner
Be careful not to accidentally drop existing elements, styles, or references when making edits
When editing USS, focus on the properties and selectors relevant to the request — avoid unnecessary reorganization, but restructure if the change genuinely requires it

常见编辑请求：

请求内容	操作方式
"更改按钮颜色"	编辑该按钮的USS选择器
"在此处添加标签"	在指定位置向UXML中添加元素
"把这个放大"	在USS中编辑宽/高属性
"隐藏这个元素"	在USS中添加 `display: none` 或从UXML中移除该元素
"重命名这个元素"	更新UXML中的 `name` 属性

避免过度编辑：

仅修改请求的内容
保留原有格式和结构
不要“优化”无关代码
除非被要求，否则不要添加注释
对于针对性修改，优先修改特定元素或选择器，而非重写整个文件——但需灵活判断；如果修改涉及文件大部分内容，重写可能更清晰
编辑时注意不要意外丢失现有元素、样式或引用
编辑USS时，专注于与请求相关的属性和选择器——避免不必要的重组，但如果修改确实需要，则进行重组

Validation

验证方式

There is no way to validate UXML or USS from outside the Editor — Unity parses these files on import and reports problems in the Console. Write the files, then have the user check the result.

Workflow:

Write the complete file to its target path in the project. Do not write partial or draft content — a half-written UXML file is a parse error the moment the Editor picks it up.
Ask the user to focus the Unity Editor. That triggers a reimport of the changed assets.
Ask them to report anything in the Console. UXML parse errors name the file and line; USS problems appear as warnings about unknown properties or selectors.
Fix what they report and repeat from step 1.

Because feedback costs a user round-trip, get it right the first time:

Finish all files before asking the user to check, so one reimport covers everything rather than one per file.
Re-read
```
references/uss-guide.md
```
and
```
references/common-issues.md
```
before writing, rather than after an error comes back.
Watch for the mistakes that survive a parse but render wrong — those will not appear in the Console at all, so the user has to eyeball the UI.
```
references/common-issues.md
```
lists them.

无法在Unity编辑器外部验证UXML或USS——Unity会在导入时解析这些文件，并在控制台中报告问题。生成文件后，请让用户检查结果。

工作流程：

将完整文件写入项目中的目标路径。不要写入部分或草稿内容——未完成的UXML文件会在编辑器识别时立即触发解析错误。
请用户聚焦Unity编辑器，这会触发已修改资源的重新导入。
请用户报告控制台中的任何信息。UXML解析错误会指明文件和行号；USS问题会以未知属性或选择器的警告形式出现。
根据用户反馈修复问题，然后从步骤1重复操作。

由于反馈需要用户来回沟通，务必一次做对：

在让用户检查前完成所有文件，这样一次重新导入即可覆盖所有内容，而非逐个文件导入。
在编写前重新阅读
```
references/uss-guide.md
```
和
```
references/common-issues.md
```
，而非在出现错误后才阅读。
注意那些能通过解析但显示异常的错误——这些错误不会出现在控制台中，需要用户肉眼检查UI。
```
references/common-issues.md
```
中列出了这类错误。

Generation

生成新UI

When creating new UI:

Generate only what is requested:

Request	Output
USS only	`.uss` file only
UXML only	`.uxml` file only
UI screen / menu / panel	`.uss` + `.uxml` only
"with code" / "with logic" / "functional"	`.uss` + `.uxml` + `.cs`

These do NOT imply C#:

"proper buttons" → well-styled Button elements
"currency display" → a Label element
"working UI" → valid UXML/USS that renders
"inventory screen" → visual layout only
"inventory system" / "equipment system" / "crafting system" → Ask: "Should items be draggable?" If yes, see
```
references/pointermanipulator-guide.md
```
for patterns

Generation workflow:

Analyze — Determine exactly what files are needed. No extras.
Search — Find existing USS, UXML, assets. Don't assume paths.
Follow project patterns — Match folder structure and naming conventions.
Reuse — Check for shared stylesheets. Reuse if appropriate.
Write USS first — Verify against restrictions below.
Write UXML — Reference the USS, verify structure.
Write the files out complete — never partial content; see Validation above for how errors come back and why one round of files beats several.
Scene setup — Assign PanelSettings if adding UI to scene.
Data binding — If requested, add C# script with runtime data binding patterns (see
```
references/ui-runtime-binding.md
```
). Generate the scriptable object asset if needed. Assign the asset to the UI element root in UXML or via datasource in C#.

Color, visibility, and specification rules:

Ensure text is readable by default: When choosing colors, ensure text contrasts with its background — but respect intentional low-contrast uses (disabled states, placeholder text, decorative elements). When using design tokens, check that text and background variables provide adequate contrast.
Honor exact values: User-specified hex colors, pixel dimensions, spacing — use exactly as given. Do not approximate or substitute.

Styling / Theme When styling UI or adjusting theme make sure to not only apply to the elements directly in the current UXML but also to the core elements of UI Toolkit which are composed of several child elements usually.

创建新UI时：

仅生成请求的内容：

请求内容	输出结果
仅USS	仅生成 `.uss` 文件
仅UXML	仅生成 `.uxml` 文件
UI界面/菜单/面板	仅生成 `.uss` + `.uxml` 文件
"带代码" / "带逻辑" / "功能性"	生成 `.uss` + `.uxml` + `.cs` 文件

以下表述不意味着需要生成C#代码：

"合适的按钮" → 样式完善的Button元素
"货币显示" → Label元素
"可运行的UI" → 可正常渲染的有效UXML/USS
"背包界面" → 仅视觉布局
"背包系统" / "装备系统" / " crafting系统" → 询问：“物品是否需要支持拖放？”如果是，请查看
```
references/pointermanipulator-guide.md
```
中的模式

生成工作流程：

分析 — 确定确切需要的文件，不要额外生成。
搜索 — 查找现有USS、UXML、资源，不要假设路径。
遵循项目模式 — 匹配文件夹结构和命名规范。
复用 — 检查是否有共享样式表，如有合适则复用。
先编写USS — 根据下方限制进行验证。
编写UXML — 引用USS，验证结构。
完整写入文件 — 绝不写入部分内容；参考上述验证部分了解错误反馈方式，以及为何一次性生成所有文件更优。
场景设置 — 如果向场景中添加UI，需分配PanelSettings。
数据绑定 — 如果有请求，添加包含运行时数据绑定模式的C#脚本（见
```
references/ui-runtime-binding.md
```
）。如有需要，生成可脚本化对象资源。在UXML中或通过C#的数据源将资源分配给UI元素根节点。

颜色、可见性和规范规则：

确保文本默认可读： 选择颜色时，确保文本与背景有足够对比度——但尊重故意使用低对比度的场景（禁用状态、占位符文本、装饰元素）。使用设计令牌时，检查文本和背景变量是否提供足够对比度。
严格遵循精确值： 用户指定的十六进制颜色、像素尺寸、间距——完全按给定值使用，不要近似或替换。

样式/主题 设置UI样式或调整主题时，确保不仅应用于当前UXML中的直接元素，还要应用于UI Toolkit的核心元素，这些元素通常由多个子元素组成。

Conventions

规范约定

Follow project patterns first. Search existing files before applying defaults.

Type	Convention	Good	Bad
`name` attribute	camelCase	`submitButton`	`submit-button`
`class` attribute / USS	kebab-case	`.submit-button`	`.submitButton`
File paths	Feature folders	`Assets/UI/Inventory/`	`Assets/Scripts/UI/`

Output format:

uxml

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

uss

.class { ... }

优先遵循项目现有模式。在应用默认规则前先搜索现有文件。

类型	约定规则	正确示例	错误示例
`name` 属性	小驼峰命名（camelCase）	`submitButton`	`submit-button`
`class` 属性 / USS	短横线命名（kebab-case）	`.submit-button`	`.submitButton`
文件路径	按功能划分文件夹	`Assets/UI/Inventory/`	`Assets/Scripts/UI/`

输出格式：

uxml

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

uss

.class { ... }

USS Restrictions

USS限制

Unity's USS is a subset of CSS. These properties do NOT exist — NEVER use them:

NEVER Use	Use Instead
`border` shorthand	`border-width` , `border-color` separately
`gap`	`margin` on children
`z-index`	DOM order or parent nesting
`pointer-events`	`picking-mode` UXML attribute
`filter`	Not supported
`outline`	`border-*` properties
`box-shadow`	Nested elements or background image
`:first-child` , `:last-child` , `:nth-child`	Explicit classes
`[attribute]` selectors	Explicit classes
`transition-property: <value>`	Omit entirely, or `none` / `initial` / `inherit` only
`linear-gradient()` , `radial-gradient()`	Custom `VisualElement` with Painter2D (see `references/painter2d.md` )

Inline styles: NEVER use

style="..."

in UXML. All styling in USS only.

External URLs: NEVER use

url()

with external paths. Only

url("project://database/Assets/...")

Prefer flexible layouts over hardcoded sizes:

Use
```
flex-grow
```
,
```
flex-shrink
```
, or
```
%
```
instead of fixed
```
width
```
/
```
height
```
values
Let elements flow naturally and be constrained by their parent container
Set explicit pixel sizes only on root containers or when a fixed size is truly required
Child elements should adapt to available space rather than define their own dimensions

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/...")

。

优先使用弹性布局而非硬编码尺寸：

使用
```
flex-grow
```
、
```
flex-shrink
```
或
```
%
```
替代固定
```
width
```
/
```
height
```
值
让元素自然流动并受父容器约束
仅在根容器或确实需要固定尺寸时设置明确的像素尺寸
子元素应适应可用空间，而非自行定义尺寸

USS Brevity

USS简洁性

No default values (
```
flex-direction: column
```
is default)
No default fonts
No redundant constraints (
```
width: 100px
```
doesn't need
```
min-width
```
/
```
max-width
```
)
No overlapping properties (
```
flex: 1
```
already sets grow/shrink)
Simplest selector that works
Never duplicate selectors

不写默认值（
```
flex-direction: column
```
是默认值）
不写默认字体
不写冗余约束（
```
width: 100px
```
不需要
```
min-width
```
/
```
max-width
```
）
不写重叠属性（
```
flex: 1
```
已包含grow/shrink）
使用最简单的有效选择器
绝不重复选择器

UXML

Every file must:

Declare namespace:

<ui:UXML xmlns:ui="UnityEngine.UIElements">

Link stylesheet(s):
```
<ui:Style src="Screen.uss" />
```
Have exactly one top-level container
No
style="..."
attributes — use USS only

uxml

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

每个文件必须：

声明命名空间：

<ui:UXML xmlns:ui="UnityEngine.UIElements">

链接样式表：
```
<ui:Style src="Screen.uss" />
```
仅有一个顶级容器
禁止使用
style="..."
属性 — 仅使用USS设置样式

uxml

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

Events and Interactivity

事件与交互

Use Pointer Manipulators for event handling and interactivity on a VisualElement (see
```
references/pointermanipulator-guide.md
```
)
If drag and drop is requested then write a pointer Manipulator and attach it to the relevant Visual Element in UXML or via C#.
For simple click events, you can use the
```
clickable
```
manipulator in UXML
For more advanced interactions, create use more traditional event callbacks in C# and attach them to elements as needed

For inventory and crafting systems:

When users request an "inventory system", "equipment system", or "crafting system", ask explicitly: "Should players be able to drag and drop items?"
If yes, read
```
references/pointermanipulator-guide.md
```
for inventory/crafting-specific patterns
If no or unclear, create static layout only

使用Pointer Manipulators处理VisualElement的事件和交互（见
```
references/pointermanipulator-guide.md
```
）
如果请求拖放功能，编写Pointer Manipulator并通过UXML或C#将其附加到相关Visual Element
对于简单点击事件，可在UXML中使用
```
clickable
```
manipulator
对于更复杂的交互，在C#中创建传统事件回调并根据需要附加到元素

对于背包和 crafting系统：

当用户请求“背包系统”、“装备系统”或“crafting系统”时，明确询问：“玩家是否需要拖放物品？”
如果是，阅读
```
references/pointermanipulator-guide.md
```
中针对背包/crafting的特定模式
如果否或不明确，仅创建静态布局

Assets

资源

Do NOT reference
UnityDefaultRuntimeTheme.tss
or Unity's built-in theme icons.

Icon priority:

Reuse existing project icons
Generate SVG (see
```
references/svg-icons.md
```
)
Image generators (last resort)

Reference format:

uss

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

**请勿引用

UnityDefaultRuntimeTheme.tss

**或Unity的内置主题图标。

图标优先级：

复用项目现有图标
生成SVG（见
```
references/svg-icons.md
```
）
图像生成工具（最后手段）

引用格式：

uss

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

Scene Setup

场景设置

PanelSettings is required — UI won't render without it.

Search for existing PanelSettings asset
If none, create generic:
```
Assets/UI/PanelSettings.asset
```
Assign to UIDocument's
```
Panel Settings
```
field

Skip for Editor UI (EditorWindow, PropertyDrawer).

必须使用PanelSettings — 没有它UI无法渲染。

搜索现有PanelSettings资源
如果没有，创建通用资源：
```
Assets/UI/PanelSettings.asset
```
分配给UIDocument的
```
Panel Settings
```
字段

编辑器UI（EditorWindow、PropertyDrawer）无需此步骤。

C# (Only When Requested)

C#（仅在被请求时使用）

Style via USS classes (
```
AddToClassList()
```
) — never use
```
element.style.*
```
as inline styles have higher specificity than USS selectors, making them impossible to override via stylesheets, and add per-element memory overhead
UITK uses TextCore text assets — use
```
FontAsset
```
,
```
TextStyleSheet
```
, and
```
TextSettings
```
, not their TextMeshPro equivalents (
```
TMP_FontAsset
```
, etc.)
Place scripts in same folder as UXML/USS

通过USS类设置样式（
```
AddToClassList()
```
） — 绝不要使用
```
element.style.*
```
，因为内联样式比USS选择器具有更高优先级，导致无法通过样式表覆盖，且会增加每个元素的内存开销
UITK使用TextCore文本资源 — 使用
```
FontAsset
```
、
```
TextStyleSheet
```
和
```
TextSettings
```
，而非对应的TextMeshPro等效资源（
```
TMP_FontAsset
```
等）
将脚本放在与UXML/USS相同的文件夹中