unity-ui-toolkit-design-system

# Unity UI Toolkit Design System > Skill by [ara.so](https://ara.so) — Design Skills collection. A drop-in design system for Unity 6 UI Toolkit (UIDocument + UXML + USS) providing tokens, 24+ components, 63 icons, mobile responsiveness, and runtime helpers. Battle-tested in production cross-platform games. ## What It Provides - **Token-based theming**: Dark theme by default with `var(--color-*)` cascade, light theme override available - **24 ready components**: Buttons, inputs, tabs, toggles, modals, toasts, badges, navigation, progress indicators, etc. - **63 SVG icons**: Auto-tinting via `-unity-background-image-tint-color` for state changes - **Mobile responsiveness**: Single `.mobile` class flips all spacing and touch targets - **Runtime helper**: Auto-attaches to UIDocuments, handles toggle knobs, spinner rotation, skeleton shimmer - **Themed scrollbars**: 8px slim scrollbar that auto-themes with palette ## Installation ### Requirements - Unity 6 (6000.x or newer) - `com.unity.ui` (UI Toolkit) — built-in module - `com.unity.modules.vectorgraphics` — built-in module ### Option A: Direct Copy ```powershell # From your Unity project root git clone https://github.com/sinanata/unity-ui-document-design-system ../design-system-src cp -r ../design-system-src/Assets/DesignSystem Assets/DesignSystem ``` ### Option B: Git Submodule (Recommended) ```bash cd your-unity-project git submodule add https://github.com/sinanata/unity-ui-document-design-system Vendor/unity-ui-document-design-system ``` Create OS-level link: ```powershell # Windows (no admin required) cmd /c mklink /J Assets\DesignSystem Vendor\unity-ui-document-design-system\Assets\DesignSystem ``` ```bash # macOS/Linux ln -s ../Vendor/unity-ui-document-design-system/Assets/DesignSystem Assets/DesignSystem ``` Add to `.gitignore`: ```gitignore # Per-clone link to vendored design system Assets/DesignSystem Assets/DesignSystem.meta ``` ## Basic Usage ### Attach Stylesheet to UXML ```xml <ui:UXML xmlns:ui="UnityEngine.UIElements"> <Style src="project://database/Assets/DesignSystem/Resources/UI/Styles/DesignSystem/DesignSystem.uss" /> <ui:VisualElement class="ds-root"> <!-- Your UI here --> </ui:VisualElement> </ui:UXML> ``` The `ds-root` class is required as the container for all design system components. ### Runtime Auto-Attachment The `DesignSystemRuntime.cs` automatically attaches to every UIDocument in the scene. No manual setup needed. ## Component Patterns ### Buttons Five variants with automatic hover/press/disabled states: ```xml <!-- Primary CTA --> <ui:Button text="Get Started" class="ds-btn ds-btn--primary" /> <!-- Secondary outline --> <ui:Button text="Cancel" class="ds-btn ds-btn--secondary" /> <!-- Tertiary text-only --> <ui:Button text="Learn More" class="ds-btn ds-btn--tertiary" /> <!-- Warning --> <ui:Button text="Delete" class="ds-btn ds-btn--warning" /> <!-- Danger --> <ui:Button text="Remove" class="ds-btn ds-btn--danger" /> <!-- Full width --> <ui:Button text="Continue" class="ds-btn ds-btn--primary ds-btn--block" /> <!-- Small size --> <ui:Button text="Small" class="ds-btn ds-btn--primary ds-btn--sm" /> <!-- Large size --> <ui:Button text="Large" class="ds-btn ds-btn--primary ds-btn--lg" /> <!-- With icon --> <ui:Button class="ds-btn ds-btn--primary"> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--plus" /> <ui:Label text="Add Item" /> </ui:Button> ``` Disable programmatically: ```csharp button.SetEnabled(false); // USS handles :disabled state styling ``` ### Inputs Text fields with search, textarea variants: ```xml <!-- Basic input --> <ui:TextField class="ds-input" /> <!-- Search with icon --> <ui:VisualElement class="ds-search"> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--search ds-search__icon" /> <ui:TextField class="ds-search__field" /> </ui:VisualElement> <!-- Textarea --> <ui:TextField multiline="true" class="ds-input ds-input--textarea" /> <!-- Password --> <ui:TextField password="true" class="ds-input" /> ``` Set placeholders from C#: ```csharp var searchField = root.Q<TextField>(className: "ds-search__field"); searchField.textEdition.placeholder = "Search animals..."; var emailField = root.Q<TextField>("email-field"); emailField.textEdition.placeholder = "name@example.com"; ``` ### Tabs Segmented control with active state: ```xml <ui:VisualElement class="ds-tabs"> <ui:Button text="All" class="ds-tab is-active" name="tab-all" /> <ui:Button text="Active" class="ds-tab" name="tab-active" /> <ui:Button text="Archived" class="ds-tab" name="tab-archived" /> </ui:VisualElement> ``` Handle tab switching: ```csharp var tabs = root.Query<Button>(className: "ds-tab").ToList(); foreach (var tab in tabs) { tab.clicked += () => { // Remove active from all tabs.ForEach(t => t.RemoveFromClassList("is-active")); // Add to clicked tab.AddToClassList("is-active"); // Handle content switching string tabName = tab.name; ShowContentFor(tabName); }; } ``` ### Icons 63 built-in SVG icons with auto-tinting: ```xml <!-- Basic icon --> <ui:VisualElement class="ds-icon ds-icon--paw" /> <!-- Small size --> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--user" /> <!-- Large size --> <ui:VisualElement class="ds-icon ds-icon--lg ds-icon--store" /> <!-- Common icons --> <ui:VisualElement class="ds-icon ds-icon--heart" /> <ui:VisualElement class="ds-icon ds-icon--cart" /> <ui:VisualElement class="ds-icon ds-icon--settings" /> <ui:VisualElement class="ds-icon ds-icon--chevron-right" /> <ui:VisualElement class="ds-icon ds-icon--arrow-left" /> <ui:VisualElement class="ds-icon ds-icon--check" /> <ui:VisualElement class="ds-icon ds-icon--close" /> <ui:VisualElement class="ds-icon ds-icon--plus" /> <ui:VisualElement class="ds-icon ds-icon--minus" /> ``` Icons automatically tint based on parent state (hover, active, disabled) via `-unity-background-image-tint-color`. ### Toggles & Checkboxes iOS-style toggle and square checkbox: ```xml <!-- Toggle switch (runtime adds sliding knob) --> <ui:Toggle class="ds-toggle" /> <!-- Checkbox --> <ui:Toggle class="ds-check" /> <!-- With label --> <ui:VisualElement class="ds-row"> <ui:Toggle class="ds-check" name="remember-me" /> <ui:Label text="Remember me" class="ds-body-1" /> </ui:VisualElement> ``` Handle changes: ```csharp var toggle = root.Q<Toggle>("remember-me"); toggle.RegisterValueChangedCallback(evt => { bool isChecked = evt.newValue; PlayerPrefs.SetInt("RememberMe", isChecked ? 1 : 0); }); ``` ### Modals & Dialogs Overlay components with header/body/actions slots: ```xml <!-- Modal --> <ui:VisualElement class="ds-modal" name="settings-modal"> <ui:VisualElement class="ds-modal__content"> <ui:VisualElement class="ds-modal__header"> <ui:Label text="Settings" class="ds-h3" /> <ui:Button class="ds-btn ds-btn--tertiary ds-btn--sm" name="close-modal"> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--close" /> </ui:Button> </ui:VisualElement> <ui:VisualElement class="ds-modal__body"> <!-- Modal content --> </ui:VisualElement> <ui:VisualElement class="ds-modal__actions"> <ui:Button text="Cancel" class="ds-btn ds-btn--secondary" /> <ui:Button text="Save" class="ds-btn ds-btn--primary" /> </ui:VisualElement> </ui:VisualElement> </ui:VisualElement> <!-- Confirm dialog --> <ui:VisualElement class="ds-dialog" name="confirm-delete"> <ui:VisualElement class="ds-dialog__content"> <ui:Label text="Delete item?" class="ds-h4" /> <ui:Label text="This action cannot be undone." class="ds-body-2" /> <ui:VisualElement class="ds-dialog__actions"> <ui:Button text="Cancel" class="ds-btn ds-btn--secondary" /> <ui:Button text="Delete" class="ds-btn ds-btn--danger" /> </ui:VisualElement> </ui:VisualElement> </ui:VisualElement> ``` Show/hide with display toggle: ```csharp var modal = root.Q("settings-modal"); modal.style.display = DisplayStyle.Flex; // Show modal.style.display = DisplayStyle.None; // Hide // Close button handler var closeBtn = root.Q<Button>("close-modal"); closeBtn.clicked += () => modal.style.display = DisplayStyle.None; ``` ### Toasts Non-blocking notifications: ```xml <ui:VisualElement class="ds-toast ds-toast--success"> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--check" /> <ui:Label text="Changes saved" class="ds-body-2" /> </ui:VisualElement> <ui:VisualElement class="ds-toast ds-toast--error"> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--close" /> <ui:Label text="Connection failed" class="ds-body-2" /> </ui:VisualElement> <ui:VisualElement class="ds-toast ds-toast--warning"> <ui:VisualElement class="ds-icon ds-icon--sm ds-icon--alert" /> <ui:Label text="Low storage" class="ds-body-2" /> </ui:VisualElement> ``` Create and auto-dismiss: ```csharp public void ShowToast(VisualElement root, string message, string type = "success") { var toast = new VisualElement(); toast.AddToClassList("ds-toast"); toast.AddToClassList($"ds-toast--{type}"); var icon = new VisualElement(); icon.AddToClassList("ds-icon");