Configuring UI Documents and Style Sheets

In this lesson, you will learn how to decouple your interface structure from its visual appearance by masterfully linking UXML documents to USS style sheets.

When building complex interfaces, writing layout code directly in C# scripts makes your UI hard to maintain and prone to "spaghetti" logic. Instead, Unity’s UI Toolkit uses UXML (Unity XML) to define the skeleton of your interface—the hierarchy of buttons, labels, and panels—and USS (Unity Style Sheets) to define how they look.

The Separation of Concerns

Think of UXML as the "What" and USS as the "How."

• UXML (.uxml): Defines the structure. It acts as a blueprint that tells Unity, "There is a container here, a button inside it, and a label inside that button."
• USS (.uss): Defines the visual properties. It contains rules like background-color, font-size, or margin.

By separating these, you can update the look of your entire game—changing every button color at once, for example—simply by editing one central .uss file without touching your structural .uxml layout.

Workflow in Practice

To link these, you use the UI Builder or the Inspector window:

1. Create a UIDocument component on a GameObject in your scene.
2. Assign your .uxml file to the Source Asset slot.
3. Inside your .uxml file, you add a reference to your .uss file by dragging it into the Style Sheets section of the UI Builder.

If you inspect the raw UXML file, you will see a reference that looks like this:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <Style src="project://database/Assets/Styles/MainTheme.uss" />
    <ui:VisualElement class="my-container" />
</ui:UXML>

By applying a class name (like my-container) in your UXML, the USS file can target it specifically:

.my-container {
    background-color: blue;
    padding: 10px;
}

This workflow keeps your project clean. You can hand the UI design off to an artist who works on the USS, while you handle the C# logic that interacts with the UXML elements via the UIDocument.rootVisualElement.

Key Takeaway: By separating your UI structure (UXML) from your styling (USS), you create a modular workflow that allows for global aesthetic updates without risking structural integrity.