# Unity UI Toolkit

> Master guide for high-performance interface development using UI Toolkit. Based on Unity 6+ standards and hardware optimization.

- Skill: `unlince/unity-ui-toolkit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add unlince/unity-ui-toolkit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unlince/unity-ui-toolkit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: UnLince (https://skillmd.com/u/unlince)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/unlince/unity-ui-toolkit

---


# Skill: Unity UI Toolkit - Best Practices & Performance (Unity 6+)

The master guide for high-performance interface development using UI Toolkit. Based on Unity 6+ standards and hardware-accelerated optimization.

---

## 🏗️ Architecture and Standards

### 1. Flexbox-First (Yoga Engine)
*   **Default Behavior:** Orientation is `flex-direction: column`.
*   **No Inline Styles:** All styles must reside in `.uss` files. Use variables in `:root` for design tokens (colors, spacing).
*   **Custom Components (Unity 6):** Use `[UxmlElement]` and `[UxmlAttribute]` attributes on `partial` classes. Avoid the legacy `UxmlFactory` boilerplate.

### 2. UI Toolkit vs. uGUI (When to use what?)
*   **UI Toolkit (Retained Mode):** Ideal for static HUDs, Menus, Inventories, and Editor tools.
*   **uGUI (Immediate/GameObject Mode):** **Mandatory** for World Space UI with high density or complex billboard transformations (e.g., health bars over 100 enemies), unless using the specific Unity 6 World Space integration with extreme caution.

---

## ⚡ Performance Optimization (Critical)

### 1. GPU-Based Animations and Transforms
*   **Golden Rule:** NEVER animate layout properties (`width`, `height`, `margin`, `padding`, `top`, `left`). This forces a CPU-intensive "Layout Recalculation" of the entire visual tree.
*   **Solution:** Use GPU-accelerated transforms: `translate`, `rotate`, `scale`.
*   **Usage Hints:** Enable `UsageHints.DynamicTransform` on elements that move or animate frequently to ensure efficient GPU handling.

### 2. Panel Management and Draw Calls
*   **UIDocument:** Avoid having multiple `UIDocument` components for small elements. Group as many elements as possible under a single `UIDocument` to maximize batching.
*   **Vertex Budget:** If your UI is complex and you see flickering or disappearing elements, increase the **Vertex Budget** in the `Panel Settings` asset.
*   **Texturing and Atlasing:** Use the **Sprite Packer** to ensure all UI icons reside in the same atlas, preventing batching breaks.

### 3. "Smart Hiding"
*   **display: none** vs. **visibility: hidden**:
    *   `display: none`: Removes the element from layout calculations (most efficient for long-term hiding).
    *   `visibility: hidden`: The element still occupies layout space but is not rendered.
*   **Do NOT use opacity: 0** to hide elements: They still process events and consume rendering resources.

---

## 🛠️ Diagnostic Tools
1.  **UI Toolkit Debugger:** Essential for inspecting the visual tree and layout timings.
2.  **Panel Settings -> Live Reload:** Keep enabled during development to see USS/UXML changes instantly.
3.  **Frame Debugger:** Crucial for identifying why batching breaks between UI elements.

---

## 🚫 Common Pitfalls (Anti-Patterns)
*   **Deep Nesting:** Avoid excessively deep hierarchies of `VisualElements`. Every level adds cost to Flexbox calculations.
*   **Manual UxmlFactory:** Do not write `UxmlFactory` manually in Unity 6; leverage the code generator.
*   **Complex World Space Anchors:** Avoid dynamic layouts (Flex) on objects moving rapidly in 3D space.