unity-ui

UI Toolkit Rules (NOT UGUI)

Project Structure

Assets/
├── UI/
│   ├── Runtime/
│   │   ├── Controllers/
│   │   │   └── MainMenuController.cs
│   │   ├── Views/
│   │   │   └── MainMenuView.cs
│   │   ├── ViewModels/
│   │   │   └── HealthViewModel.cs
│   │   ├── UXML/
│   │   │   └── MainMenu.uxml
│   │   └── USS/
│   │       └── MainMenu.uss
│   └── Editor/
│       └── UIBuilderExtensions.cs

UXML Structure

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:VisualElement name="MainContainer" class="container">
        <ui:Label text="Health:" class="label" />
        <ui:ProgressBar name="HealthBar" high-value="100" />
        <ui:Button name="StartButton" text="Start Game" />
    </ui:VisualElement>
</ui:UXML>

USS Styling

/* Use CSS Variables for reusability */
:root {
    --primary-color: rgb(50, 150, 255);
    --secondary-color: rgb(255, 100, 50);
    --bar-height: 30px;
    --label-size: 24px;
    --container-padding: 20px;
}

.container {
    flex-direction: column;
    align-items: center;
    justify-content: center;
    padding: var(--container-padding);
}

.label {
    font-size: var(--label-size);
    color: white;
    -unity-font-style: bold;
}

#HealthBar {
    width: 300px;
    height: var(--bar-height);
    background-color: var(--primary-color);
    border-radius: 5px;
}

#StartButton {
    width: 200px;
    height: 50px;
    background-color: var(--secondary-color);
    margin-top: 20px;
}

#StartButton:hover {
    background-color: rgb(255, 120, 70);
}

C# View (Pure UI Logic)

using System;
using UnityEngine.UIElements;

namespace UI.Runtime.Views
{
    /// <summary>
    /// Pure UI view layer - handles only visual element queries and basic UI operations
    /// </summary>
    public class MainMenuView : IDisposable
    {
        private readonly VisualElement _root;
        private readonly Button _startButton;
        private readonly ProgressBar _healthBar;
        private readonly Label _statusLabel;
        
        // Events for controller communication
        public event Action StartButtonClicked;
        
        public MainMenuView(VisualElement root)
        {
            _root = root ?? throw new ArgumentNullException(nameof(root));
            
            // Query UI elements with null checks
            _startButton = _root.Q<Button>("StartButton");
            _healthBar = _root.Q<ProgressBar>("HealthBar");
            _statusLabel = _root.Q<Label>("StatusLabel");
            
            ValidateElements();
            BindEvents();
        }
        
        private void ValidateElements()
        {
            if (_startButton == null)
                throw new InvalidOperationException("StartButton not found in UXML");
            if (_healthBar == null)
                throw new InvalidOperationException("HealthBar not found in UXML");
        }
        
        private void BindEvents()
        {
            _startButton.clicked += OnStartButtonClicked;
        }
        
        private void OnStartButtonClicked()
        {
            StartButtonClicked?.Invoke();
        }
        
        // Public API for controllers
        public void SetHealth(float value)
        {
            if (_healthBar != null)
                _healthBar.value = value;
        }
        
        public void SetStatusText(string text)
        {
            if (_statusLabel != null)
                _statusLabel.text = text;
        }
        
        public void SetInteractable(bool interactable)
        {
            if (_startButton != null)
                _startButton.SetEnabled(interactable);
        }
        
        public void Show()
        {
            _root.style.display = DisplayStyle.Flex;
        }
        
        public void Hide()
        {
            _root.style.display = DisplayStyle.None;
        }
        
        public void Dispose()
        {
            if (_startButton != null)
                _startButton.clicked -= OnStartButtonClicked;
        }
    }
}