/ui-ugui

name: ui-ugui
description: Understands, edits, and generates Unity uGUI Canvas hierarchies, RectTransforms, Layout Groups, and prefab UI. Use for requests involving Canvas, uGUI, RectTransform, or prefab UI files.

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](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

1. **Verify state** — Check what exists in the scene/hierarchy before any action. 2. **Analyze** — Determine exactly what's needed. No extras. 3. **Search** — Find existing prefabs, canvases, assets. Don't assume paths. 4. **Follow project patterns** — Match folder structure and naming. 5. **Create or edit** — Build structure with proper anchoring, or make targeted edits. 6. **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