ui-ugui

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:

Generate only what is requested:

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.

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 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:

1. Set anchor preset first (corner, edge, or stretch)
2. Then set position/offset values
3. 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"):

1. Determine if it's a corner (fixed point), an edge (stretch along one axis), or fill (stretch both axes)
2. Set anchor min and anchor max — for corners these are the same point; for edges/fill they span a range
3. 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
4. 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

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:

1. EventSystem must exist in the scene (exactly one)
2. GraphicRaycaster must be on the Canvas
3. Raycast Target = true on interactive elements (and false on non-interactive ones to avoid blocking)
4. 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:

1. Verify the target object exists
2. Identify the specific property or component to change
3. Make the minimal change required
4. 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