Understand existing Unity uGUI, make targeted edits, and generate new Canvas-based hierarchies.
When working with ScrollRect/ScrollView, read the reference file:
references/scrollview-setup.md — Required hierarchy, setup rules, and common failures
Scope
Determine what the user is asking for:
| Request Type |
Action |
| Question about UI |
Understand — analyze hierarchy, explain structure |
| Change specific element |
Edit — targeted modification only |
| Create new UI |
Generate — create new hierarchy |
| Fix/improve existing UI |
Edit — modify existing, don't rebuild |
Generate only what is requested:
| Request |
Output |
| UI layout |
Prefab or scene hierarchy only |
| "with code" / "with logic" / "functional" |
Hierarchy + scripts |
These do NOT imply scripts:
- "proper buttons" → well-configured Button components
- "working UI" → valid hierarchy that renders
- "menu screen" → visual layout only
Critical Rules
Namespace disambiguation:
- Always use fully qualified type names when creating or referencing UI components
UnityEngine.UI.Image, not Image
UnityEngine.UI.Button, not Button
- Other namespaces in the project can cause ambiguous type errors
Verify before modifying:
- Always check what currently exists before making changes
- Confirm parent objects exist before adding children
- Verify components are present before modifying properties
- Never assume hierarchy state — query it first
Incremental fixes over rebuilds:
- When fixing issues, make targeted corrections
- Never destroy and recreate entire hierarchies to fix problems — destroyed objects cause null reference cascades
- Prefer identifying the specific broken property and fixing only that over rewriting large sections
- When a fix fails, revert the change before trying an alternative approach
One change at a time:
- Make a single change, then verify the result
- Do not batch multiple unrelated modifications
- Be careful not to inadvertently modify or remove adjacent elements when editing a specific one
- If something fails, understand why before trying alternatives
- Avoid "shotgun debugging" with multiple simultaneous changes
Color and visibility:
- 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)
- Check visibility for new elements: After creating UI elements, verify they have non-zero size and are within parent bounds. Elements intentionally created hidden (for later toggling, animation, etc.) are fine
Specification adherence:
- Honor user specifications exactly: When the user provides pixel dimensions, hex colors, positions, spacing, or other exact values, apply them precisely — do not approximate or substitute
- Minimize unrelated changes: When editing, avoid changing properties the user didn't ask about unless a related adjustment is necessary for the fix to work
Conventions
Follow project patterns first. Search existing files before applying defaults.
| Type |
Convention |
Good |
Bad |
| GameObject names |
PascalCase |
SubmitButton |
submit-button |
| Prefab paths |
Feature folders |
Assets/UI/Inventory/ |
Assets/Prefabs/UI/ |
Workflow
- Verify state — Check what exists in the scene/hierarchy before any action.
- Analyze — Determine exactly what's needed. No extras.
- Search — Find existing prefabs, canvases, assets. Don't assume paths.
- Follow project patterns — Match folder structure and naming.
- Create or edit — Build structure with proper anchoring, or make targeted edits.
- Confirm result — Verify the change worked before moving on.
Canvas Setup
Every UI needs a Canvas:
Canvas (Screen Space - Overlay or Camera)
├── CanvasScaler (Scale With Screen Size recommended)
├── GraphicRaycaster
└── [UI Content]
CanvasScaler settings:
- Default to UI Scale Mode "Scale With Screen Size" unless the project has a specific reason for "Constant Pixel Size" (e.g., pixel-art, fixed-resolution targets)
- Reference Resolution: Match project standards (e.g., 1920x1080)
- When creating a Canvas with Screen Space - Camera, read the camera's reference resolution first
- Match Width Or Height: 0.5 (balanced)
- If an existing Canvas uses "Constant Pixel Size", flag it and ask the user before changing
- Prefer anchors and Layout Groups over absolute pixel positions for layout
Layout Components
Layout Groups control child sizing:
- When a parent has a Layout Group, it manages child RectTransforms
- Children's anchors and sizeDelta may be overridden by the parent
- Understand whether the parent or child controls size before setting values
Vertical/Horizontal Layout Groups:
- Control Child Size: determines if parent sets child dimensions
- Child Force Expand: determines if children stretch to fill space
- If Control Child Size is off, children must have explicit sizes
Avoiding layout conflicts:
- Do not manually set child anchors/size when parent controls them
- Do not add Layout Group to an element that should have fixed size
- Nested Layout Groups require careful configuration of each level
- When layout is wrong, check parent settings before modifying child
- ContentSizeFitter on the same object as a Layout Group that has Control Child Size enabled = conflict
- ContentSizeFitter on a child whose parent has Control Child Size enabled = ContentSizeFitter is overridden (wasted)
- When using ContentSizeFitter with a Layout Group parent, disable Control Child Size on the parent for the relevant axis
- Common pattern: ScrollView Content should have ContentSizeFitter + VerticalLayoutGroup where VLG controls children but ContentSizeFitter sizes the Content itself
Grid Layout Group:
- For inventory grids, card layouts
- Cell Size must be set explicitly — children are sized to match
- Constraint controls row/column limits
Content Size Fitter:
- Horizontal/Vertical Fit: Preferred Size
- Use on containers that should size to their content
- Requires a layout element or text component to provide preferred size
RectTransform Anchoring
Elements must have non-zero size to be visible:
- Set explicit width/height via sizeDelta, or
- Use stretch anchors with proper offsets, or
- Let a parent Layout Group control size (with Control Child Size enabled)
Anchor configuration order:
- Set anchor preset first (corner, edge, or stretch)
- Then set position/offset values
- Verify the resulting size is non-zero
Common patterns:
- Stretch anchors — for responsive elements that fill available space
- Corner anchors — for fixed-position, fixed-size elements
- Edge anchors — for elements that stretch in one direction only
Positioning from natural language descriptions:
When the user describes a position (e.g., "top right", "bottom bar", "left side"):
- Determine if it's a corner (fixed point), an edge (stretch along one axis), or fill (stretch both axes)
- Set anchor min and anchor max — for corners these are the same point; for edges/fill they span a range
- Set pivot to match the anchor point — pivot must align with where the element is anchored, not left at the default (0.5, 0.5). A "top right" element needs pivot at the top-right corner; a "top bar" needs pivot at the top edge center
- Set position/offset values after anchors and pivot are configured
Visibility checklist:
- Width and height are both greater than zero
- Element is within parent bounds
- Element is not obscured by siblings (check hierarchy order)
- Image component has a sprite or color with alpha > 0
Common Components
| Component |
Use Case |
Image |
Backgrounds, icons |
RawImage |
Render textures, videos |
Text (TMP) |
All text (use TextMeshPro) |
Button |
Clickable elements |
Toggle |
Checkboxes, radio buttons |
Slider |
Value ranges |
ScrollRect |
Scrollable content |
InputField (TMP) |
Text input |
Best Practices
- Use TextMeshPro for all text (not legacy Text)
- WorldSpace UI that have text should also use Text Mesh Pro, be sure to review the project and import the TMP essentials if they are not present in the project
- If the TextMeshPro Essentials were imported be sure to close the TMP Importer Windows and the Import Unity Package Window once the assets are imported
- Organize hierarchy logically (Header, Content, Footer)
- Use Layout Groups instead of manual positioning where possible
- Set Raycast Target = false on non-interactive images
- Use sprite atlases for performance
Never use EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources"), unless the user asks for an interactive TMP Essentials installation. It opens a modal dialog that blocks whatever invoked it until a human dismisses it.
Do not use AssetDatabase.ImportPackage() for TMP resources, instead TMP_PackageResourceImporter.ImportResources() is the canonical non-interactive API.
Interaction Readiness
Before completing any UI that contains interactive elements, verify:
- EventSystem must exist in the scene (exactly one)
- GraphicRaycaster must be on the Canvas
- Raycast Target = true on interactive elements (and false on non-interactive ones to avoid blocking)
- Button.onClick should be wired (via inspector or script) — only when scripts or logic were requested
If the first three are missing, interactive elements will exist visually but fail silently.
Understanding
When the user asks questions about existing UI:
Read the hierarchy first. Don't assume — always inspect the scene or prefab before answering.
Analyze structure:
- Identify the Canvas and its render mode
- Map the parent-child relationships
- Identify which Layout Groups control which children
- Check RectTransform anchor configurations
Answer questions about:
- "What does this button do?" → Explain component, hierarchy position, event wiring
- "How is this laid out?" → Describe Layout Groups, anchoring, hierarchy
- "Why is this invisible?" → Check size, anchors, parent bounds, component state
- "What controls this element's size?" → Trace Layout Group settings or anchors
Editing
For targeted changes to existing UI:
Read before editing. Always inspect the current state first.
Edit workflow:
- Verify the target object exists
- Identify the specific property or component to change
- Make the minimal change required
- Verify the result before proceeding
Never destroy to fix:
- Destroying objects cascades to null references elsewhere
- Fix properties in place rather than recreating
- If an element must be removed, update all references first
C# (Only When Requested)
- Use fully qualified UI types to avoid namespace conflicts
- Use
[SerializeField] for inspector references
- Cache component references in Awake()
- Use events/delegates for button callbacks
- Place scripts in same folder as prefabs (follow project patterns)
Component references:
- Verify referenced objects exist before accessing them
- Handle cases where serialized references may be null
- When wiring up references, confirm the target component is present
Error Recovery
When something goes wrong:
Stop and diagnose:
- Identify the exact error or symptom
- Determine the root cause before attempting fixes
- Do not make speculative changes
Fix incrementally:
- Address one issue at a time
- Verify each fix before moving to the next
- Keep track of what was changed
Avoid destructive patterns:
- "Start fresh" strategies destroy working elements along with broken ones
- Rebuilding entire hierarchies creates more problems than it solves
- Prefer surgical fixes to wholesale replacements
When stuck:
- Re-verify the current state of the hierarchy
- Check if previous changes were actually applied
- Consider if the approach itself is wrong rather than the implementation
1---
2name: ui-ugui
3description: Unity uGUI (Canvas-based) UI expert. Understands, edits, and generates Canvas hierarchies, RectTransforms, Layout Groups, and prefab UI. Use for requests involving Canvas, uGUI, RectTransform, or .prefab UI files.
4allowed-tools:
5 - Read
6 - Write
7 - Edit
8 - Glob
9 - Grep
10metadata:
11 source: https://skillmd.com/skills/unity-technologies/ui-ugui
12---
13
14Understand existing Unity uGUI, make targeted edits, and generate new Canvas-based hierarchies.
15
16When working with ScrollRect/ScrollView, read the reference file:
17- `references/scrollview-setup.md` — Required hierarchy, setup rules, and common failures
18
19## Scope
20
21Determine what the user is asking for:
22
23| Request Type | Action |
24|--------------|--------|
25| Question about UI | **Understand** — analyze hierarchy, explain structure |
26| Change specific element | **Edit** — targeted modification only |
27| Create new UI | **Generate** — create new hierarchy |
28| Fix/improve existing UI | **Edit** — modify existing, don't rebuild |
29
30**Generate only what is requested:**
31
32| Request | Output |
33|---------|--------|
34| UI layout | Prefab or scene hierarchy only |
35| "with code" / "with logic" / "functional" | Hierarchy + scripts |
36
37**These do NOT imply scripts:**
38- "proper buttons" → well-configured Button components
39- "working UI" → valid hierarchy that renders
40- "menu screen" → visual layout only
41
42## Critical Rules
43
44**Namespace disambiguation:**
45- Always use fully qualified type names when creating or referencing UI components
46- `UnityEngine.UI.Image`, not `Image`
47- `UnityEngine.UI.Button`, not `Button`
48- Other namespaces in the project can cause ambiguous type errors
49
50**Verify before modifying:**
51- Always check what currently exists before making changes
52- Confirm parent objects exist before adding children
53- Verify components are present before modifying properties
54- Never assume hierarchy state — query it first
55
56**Incremental fixes over rebuilds:**
57- When fixing issues, make targeted corrections
58- Never destroy and recreate entire hierarchies to fix problems — destroyed objects cause null reference cascades
59- Prefer identifying the specific broken property and fixing only that over rewriting large sections
60- **When a fix fails, revert the change** before trying an alternative approach
61
62**One change at a time:**
63- Make a single change, then verify the result
64- Do not batch multiple unrelated modifications
65- Be careful not to inadvertently modify or remove adjacent elements when editing a specific one
66- If something fails, understand why before trying alternatives
67- Avoid "shotgun debugging" with multiple simultaneous changes
68
69**Color and visibility:**
70- **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)
71- **Check visibility for new elements:** After creating UI elements, verify they have non-zero size and are within parent bounds. Elements intentionally created hidden (for later toggling, animation, etc.) are fine
72
73**Specification adherence:**
74- **Honor user specifications exactly:** When the user provides pixel dimensions, hex colors, positions, spacing, or other exact values, apply them precisely — do not approximate or substitute
75- **Minimize unrelated changes:** When editing, avoid changing properties the user didn't ask about unless a related adjustment is necessary for the fix to work
76
77## Conventions
78
79**Follow project patterns first.** Search existing files before applying defaults.
80
81| Type | Convention | Good | Bad |
82|------|------------|------|-----|
83| GameObject names | PascalCase | `SubmitButton` | `submit-button` |
84| Prefab paths | Feature folders | `Assets/UI/Inventory/` | `Assets/Prefabs/UI/` |
85
86## Workflow
87
881. **Verify state** — Check what exists in the scene/hierarchy before any action.
892. **Analyze** — Determine exactly what's needed. No extras.
903. **Search** — Find existing prefabs, canvases, assets. Don't assume paths.
914. **Follow project patterns** — Match folder structure and naming.
925. **Create or edit** — Build structure with proper anchoring, or make targeted edits.
936. **Confirm result** — Verify the change worked before moving on.
94
95## Canvas Setup
96
97Every UI needs a Canvas:
98
99```
100Canvas (Screen Space - Overlay or Camera)
101├── CanvasScaler (Scale With Screen Size recommended)
102├── GraphicRaycaster
103└── [UI Content]
104```
105
106**CanvasScaler settings:**
107- Default to UI Scale Mode "Scale With Screen Size" unless the project has a specific reason for "Constant Pixel Size" (e.g., pixel-art, fixed-resolution targets)
108- Reference Resolution: Match project standards (e.g., 1920x1080)
109- When creating a Canvas with Screen Space - Camera, **read the camera's reference resolution** first
110- Match Width Or Height: 0.5 (balanced)
111- If an existing Canvas uses "Constant Pixel Size", flag it and ask the user before changing
112- Prefer anchors and Layout Groups over absolute pixel positions for layout
113
114## Layout Components
115
116**Layout Groups control child sizing:**
117- When a parent has a Layout Group, it manages child RectTransforms
118- Children's anchors and sizeDelta may be overridden by the parent
119- Understand whether the parent or child controls size before setting values
120
121**Vertical/Horizontal Layout Groups:**
122- Control Child Size: determines if parent sets child dimensions
123- Child Force Expand: determines if children stretch to fill space
124- If Control Child Size is off, children must have explicit sizes
125
126**Avoiding layout conflicts:**
127- Do not manually set child anchors/size when parent controls them
128- Do not add Layout Group to an element that should have fixed size
129- Nested Layout Groups require careful configuration of each level
130- When layout is wrong, check parent settings before modifying child
131- ContentSizeFitter on the **same** object as a Layout Group that has Control Child Size enabled = conflict
132- ContentSizeFitter on a child whose parent has Control Child Size enabled = ContentSizeFitter is overridden (wasted)
133- When using ContentSizeFitter with a Layout Group parent, disable Control Child Size on the parent for the relevant axis
134- Common pattern: ScrollView Content should have ContentSizeFitter + VerticalLayoutGroup where VLG controls children but ContentSizeFitter sizes the Content itself
135
136**Grid Layout Group:**
137- For inventory grids, card layouts
138- Cell Size must be set explicitly — children are sized to match
139- Constraint controls row/column limits
140
141**Content Size Fitter:**
142- Horizontal/Vertical Fit: Preferred Size
143- Use on containers that should size to their content
144- Requires a layout element or text component to provide preferred size
145
146## RectTransform Anchoring
147
148**Elements must have non-zero size to be visible:**
149- Set explicit width/height via sizeDelta, or
150- Use stretch anchors with proper offsets, or
151- Let a parent Layout Group control size (with Control Child Size enabled)
152
153**Anchor configuration order:**
1541. Set anchor preset first (corner, edge, or stretch)
1552. Then set position/offset values
1563. Verify the resulting size is non-zero
157
158**Common patterns:**
159- **Stretch anchors** — for responsive elements that fill available space
160- **Corner anchors** — for fixed-position, fixed-size elements
161- **Edge anchors** — for elements that stretch in one direction only
162
163**Positioning from natural language descriptions:**
164When the user describes a position (e.g., "top right", "bottom bar", "left side"):
1651. Determine if it's a **corner** (fixed point), an **edge** (stretch along one axis), or **fill** (stretch both axes)
1662. Set anchor min and anchor max — for corners these are the same point; for edges/fill they span a range
1673. **Set pivot to match the anchor point** — pivot must align with where the element is anchored, not left at the default (0.5, 0.5). A "top right" element needs pivot at the top-right corner; a "top bar" needs pivot at the top edge center
1684. Set position/offset values **after** anchors and pivot are configured
169
170**Visibility checklist:**
171- Width and height are both greater than zero
172- Element is within parent bounds
173- Element is not obscured by siblings (check hierarchy order)
174- Image component has a sprite or color with alpha > 0
175
176## Common Components
177
178| Component | Use Case |
179|-----------|----------|
180| `Image` | Backgrounds, icons |
181| `RawImage` | Render textures, videos |
182| `Text (TMP)` | All text (use TextMeshPro) |
183| `Button` | Clickable elements |
184| `Toggle` | Checkboxes, radio buttons |
185| `Slider` | Value ranges |
186| `ScrollRect` | Scrollable content |
187| `InputField (TMP)` | Text input |
188
189## Best Practices
190
191- Use TextMeshPro for all text (not legacy Text)
192- WorldSpace UI that have text should also use Text Mesh Pro, be sure to review the project and import the TMP essentials if they are not present in the project
193- If the TextMeshPro Essentials were imported be sure to close the TMP Importer Windows and the Import Unity Package Window once the assets are imported
194- Organize hierarchy logically (Header, Content, Footer)
195- Use Layout Groups instead of manual positioning where possible
196- Set Raycast Target = false on non-interactive images
197- Use sprite atlases for performance
198
199**Never use** `EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources")`, unless the user asks for an interactive TMP Essentials installation. It opens a modal dialog that blocks whatever invoked it until a human dismisses it.
200
201**Do not use** `AssetDatabase.ImportPackage()` for TMP resources, instead `TMP_PackageResourceImporter.ImportResources()` is the canonical non-interactive API.
202
203## Interaction Readiness
204
205Before completing any UI that contains interactive elements, verify:
206
2071. **EventSystem** must exist in the scene (exactly one)
2082. **GraphicRaycaster** must be on the Canvas
2093. **Raycast Target = true** on interactive elements (and false on non-interactive ones to avoid blocking)
2104. **Button.onClick should be wired** (via inspector or script) — only when scripts or logic were requested
211
212If the first three are missing, interactive elements will exist visually but fail silently.
213
214## Understanding
215
216When the user asks questions about existing UI:
217
218**Read the hierarchy first.** Don't assume — always inspect the scene or prefab before answering.
219
220**Analyze structure:**
221- Identify the Canvas and its render mode
222- Map the parent-child relationships
223- Identify which Layout Groups control which children
224- Check RectTransform anchor configurations
225
226**Answer questions about:**
227- "What does this button do?" → Explain component, hierarchy position, event wiring
228- "How is this laid out?" → Describe Layout Groups, anchoring, hierarchy
229- "Why is this invisible?" → Check size, anchors, parent bounds, component state
230- "What controls this element's size?" → Trace Layout Group settings or anchors
231
232## Editing
233
234For targeted changes to existing UI:
235
236**Read before editing.** Always inspect the current state first.
237
238**Edit workflow:**
2391. Verify the target object exists
2402. Identify the specific property or component to change
2413. Make the minimal change required
2424. Verify the result before proceeding
243
244**Never destroy to fix:**
245- Destroying objects cascades to null references elsewhere
246- Fix properties in place rather than recreating
247- If an element must be removed, update all references first
248
249## C# (Only When Requested)
250
251- Use fully qualified UI types to avoid namespace conflicts
252- Use `[SerializeField]` for inspector references
253- Cache component references in Awake()
254- Use events/delegates for button callbacks
255- Place scripts in same folder as prefabs (follow project patterns)
256
257**Component references:**
258- Verify referenced objects exist before accessing them
259- Handle cases where serialized references may be null
260- When wiring up references, confirm the target component is present
261
262## Error Recovery
263
264When something goes wrong:
265
266**Stop and diagnose:**
267- Identify the exact error or symptom
268- Determine the root cause before attempting fixes
269- Do not make speculative changes
270
271**Fix incrementally:**
272- Address one issue at a time
273- Verify each fix before moving to the next
274- Keep track of what was changed
275
276**Avoid destructive patterns:**
277- "Start fresh" strategies destroy working elements along with broken ones
278- Rebuilding entire hierarchies creates more problems than it solves
279- Prefer surgical fixes to wholesale replacements
280
281**When stuck:**
282- Re-verify the current state of the hierarchy
283- Check if previous changes were actually applied
284- Consider if the approach itself is wrong rather than the implementation