Window Framework for UI Toolkit v2.0.x
Stylesheet Setup and Theme Structure

Use the same theme values across your own controls without turning those controls into WindowFrames.

The key is to keep values, application rules, and control structure separate. A theme supplies a color or dimension. An application stylesheet decides where that value is used. Your code or UXML supplies the element and its classes.

This guide explains the current 2.0 setup. For existing class names and their intended use, see Built-in Styling Class Reference.

Before You Begin

  • Complete Installation and Setup and use a project-owned repository.
  • Keep the three essential application stylesheet roles configured before your additional rules.
  • Apply the theme to a scope containing the controls you want to style.
  • Use the actual class names or define your own application classes; a theme-variable name is not a class name.

1. Know Which File Owns What

ThemeData — the Collection and Configuration

The ThemeData asset is a ScriptableObject collection. It references the available themes, the shared application stylesheet list, and framework configuration. It is not the USS file containing all selectors or a replacement for a theme's settings sheet.

Each theme entry points to its own ThemeStyleSheet (.tss). Modern entries use the collection's configured application rules before their selected theme settings.

Application USS — Where Values Are Applied

Application stylesheets contain selectors and the rules that consume theme values:

.my-content-background {
background-color: var(--wfw-surface-background);
}

This defines your own reusable class. It does not create a new theme setting, and it does not change the selected background value.

Keep your application's layout, control rules, and theme-variable consumers in its application stylesheet. Fixed layout decisions can also live there when they are intentionally not editable theme settings.

Theme Settings USS — the Values for One Look

A selected theme's settings USS owns its colors, spacing, typography, dimensions, image references, and supported extension defaults. For example:

:root {
--wfw-surface-background: rgba(19, 23, 32, 1);
--wfw-surface-header: rgba(26, 32, 44, 1);
--wfw-input-bg: var(--wfw-surface-sunken);
}

This is a fragment illustrating value ownership, not a complete replacement for the generated settings file. Preserve the full modern settings and required metadata when editing a theme.

An alias such as --wfw-input-bg: var(--wfw-surface-sunken) uses another setting. It is not a second independent palette value. Custom properties inherit through the styled element hierarchy, subject to declarations at more local scopes.

TSS — the Theme Entry and Imports

The supplied Default 2.0 theme's TSS imports its own settings USS:

@import url("WFW.DefaultTheme2.uss");

The shared framework rules are configured separately by ThemeData. Do not add a second full framework import chain to every modern theme TSS just because that theme needs framework controls.

2. Follow the Actual Composition Order

Application rules and selected theme values meet within the controller's configured scope. The custom class in the diagram is an application example, not a built-in class.

For a modern theme using collection application sheets, the order is:

  1. Native UI controls: WFW.UnityControls.tss, which imports Unity's native control theme.
  2. WindowFramework components: WFW.Styling.uss, which also imports WFW.Modal.uss.
  3. Slide-toggle controls: WFW.SlideToggle.uss.
  4. Additional application rules: your configured USS references, in their authored order.
  5. Selected theme settings: the theme entry's TSS and its imports.

The composition skips duplicate/null references and appends the selected settings once. An optional distinct controller Global Stylesheet is inserted first or last according to Globals Load Order. That is an additional ordering choice, not a second theme-values authority.

WFW.BaseRuntimeTheme2.tss is a shared import wrapper for the application rules. The normal collection workflow already supplies those roles individually; do not also attach the wrapper as a duplicate application layer.

WFW.Tokens.Primitives.uss is a retained reference library of scales and sample values. The current modern theme settings contain their own values, and the current shared wrapper does not import that library. It is not a mandatory palette foundation for your project themes.

Legacy self-contained theme entries can opt out of the collection application sheets. Do not assume that their composition follows the modern layout described here; use the existing upgrade workflow when moving a legacy theme to 2.0.

3. Organize Your Project Files

Repository creation supplies the configured starter assets. You can add an application-rule file alongside them; you do not need to move every generated file into a new layout.

The following is an illustrative arrangement. Theme names and copied subfolder paths can differ in your actual repository:

Assets/MyProject/UI/Resources/ProjectThemes/
    ProjectThemeData.asset              Collection/configuration
    RuntimeWindowFrameworkController.prefab
    WindowFrameworkRuntimeRoot.uxml     Your UI structure
    PanelSettings.asset                Or a shared existing panel
    ProjectControls.uss                Your application rules
    Runtime/                           Copied shared framework rules
        WFW.UnityControls.tss
        WFW.Styling.uss
        WFW.Modal.uss
        WFW.SlideToggle.uss
    v2.0/
        MyTheme/
            MyTheme.tss                Theme entry/imports
            MyTheme.uss                This theme's values

The roles and references matter more than the folder names.** USS imports resolve from their declaring file or configured asset URL/GUID. Resource references use a Resources-relative path without the extension. Moving an image or changing an import requires maintaining those references; being somewhere under Assets does not make an arbitrary resource path valid.

Keep your own files in your project area. Do not modify the installed asset's defaults to create your application theme. A generated repository can retain intentionally shared external artwork references; copying a repository is not proof that every external dependency was duplicated.

4. Register Your Application Stylesheet

  1. Create your application USS file, such as ProjectControls.uss, in your project-owned area.
  2. Open Tools > Garage-Ware Games > Window Framework > Theme Manager and open your project repository.
  3. Choose Shared Stylesheets in the toolbar.
  4. Under Additional Application Rules, choose Add Application Stylesheet and assign your USS asset.
  5. Drag additional application rows to set their relative order when needed.

The three essential roles are pinned first. Only additional application rows can be removed or reordered. The interface rejects null, duplicate, essential-role, and selected-theme-sheet references as additional rules. A new unassigned row is not saved into ThemeData; assigning a valid asset or reordering/removing an existing application row saves that configuration.

Do not insert every theme's settings TSS into Additional Application Rules. The active theme entry supplies its own settings during composition; adding all theme palettes would create competing declarations rather than theme selection.

Additional example application sheets may be present in a supplied or copied collection. For example, DevExtensionsHotbarDemo.uss targets the Demo's ToolbarWindowExample. It is not required to style an arbitrary custom control; distinguish it from the three pinned framework roles.

5. Theme Your Own Control

Reuse Content Background Without a New Setting

Put this rule in your registered application stylesheet:

.my-content-background {
background-color: var(--wfw-surface-background);
}

Then apply your class in code:

var customControl = new UnityEngine.UIElements.VisualElement();
customControl.AddToClassList("my-content-background");
window.Content.Add(customControl);

Or add it to authored content:

<ui:VisualElement class="my-content-background" />

The UXML line is a fragment to place inside your document. my-content-background is your example class, defined by the rule above. It is not supplied as a built-in class by WindowFramework.

This uses the existing Content Background setting. No new data asset, new theme field, or Developer Extension is needed. A custom element still needs useful layout/content to be visible; assigning a background class does not construct that content.

For Header Surface, define the same kind of application rule using var(--wfw-surface-header). Do not add windowFrame just to obtain a background: that class applies frame fonts, sizing, images, borders, radius, padding, and margin as well. Do not rename your element windowFrameHeader to impersonate a framework-owned part either.

Make Sure the Theme Reaches the Control

  • Window Frames Only: the framework installs the composition on its WindowFrames. Custom content inside a themed frame can use it; unrelated controls outside those frames do not become themed merely by receiving a class.
  • Parent Panel: the controller applies the composition to its own panel's visual tree. Your custom controls in that panel can inherit the values and match the application rules.
  • All Panels: the theme is applied to available active UIDocument panels. This is a styling scope, not a request to create windows or globally block input.

Choose the smallest appropriate scope when integrating with another UI system. Panel-wide theme rules also target native classes such as unity-label and unity-button, so existing controls can change appearance even if you did not assign an application-specific class to them.

Keep using the configured theme-selection path so the controller removes its prior tracked sheets and installs the new composition. Do not blanket-clear another system's stylesheets or repeatedly attach every available theme.

6. Add an Independent Studio/Player Setting When Needed

Use a Developer Extension when you want a new supported setting to appear in Studio and be available to player themes—for example, a Profile Card Background that can differ from Content Background.

Keep the responsibilities separate:

  • Developer declaration/default: the custom property and its WFWDevExt metadata in the selected theme's settings/developer-authoring section.
  • Application rule: the selector/property that consumes that variable.
  • Control: the matching class and structure.

The metadata is a block comment immediately before the custom-property declaration, inside the section marked WFW:BEGIN DEVELOPER and WFW:END DEVELOPER. Each metadata field occupies its own line. A color setting's comment would contain:

WFWDevExt: game.profile.background
type: color
label: Profile Card Background
description: Background of the player's profile card.

The following declaration supplies its default, for example in a :root rule in that marked section:

--game-profile-background: var(--wfw-surface-background);

The application stylesheet then consumes it:

.my-profile-card {
background-color: var(--game-profile-background);
}

Use my-profile-card on the control. The metadata identity game.profile.background is not the class name, a C# type, or executable code. It identifies the editable setting; the USS declaration owns its default.

A settings default may initially link to a framework value. That does not require cloning the existing palette or declaring the same setting again in the application sheet. The marked declaration and its supported consumers must be present in the configured graph used for preparation.

Numeric declarations additionally require the supported unit and explicit bounds; image declarations follow the existing supported asset workflow. Do not assume every USS property or selector can be exported to player themes. See Developer Extensions and Player Themes for the complete authoring, preparation, and runtime workflows.

7. Understand Overrides and Inheritance

A theme value, class selector, named-element selector, and component/state selector serve different purposes.

A later stylesheet is not an unconditional override of everything before it. Selector specificity, inheritance, inline styles, and any applicable important declaration still affect the result.

  • A class selector such as .form__label-element matches membership in the element's class list.
  • An ID selector such as #windowFrameHeader matches the element's name.
  • A type selector matches the actual UI Toolkit type; adding a class with that type's name does not change the element's type.
  • A descendant/state selector requires its hierarchy and state, not just one isolated class.
  • A custom property supplies a value; it does not select an element or automatically create a reusable class.

Text properties and custom properties can inherit; a parent's background does not mean every child owns the same background rule. Write an explicit rule for the element that needs the appearance.

For styles intended to follow the theme, prefer USS consumers over setting the same property inline in code. Explicit inline sizing can intentionally win—for example, creation-time WindowFrame dimensions. Do not remove those values indiscriminately just to make a stylesheet appear stronger.

Player-theme application is a separate prepared binding path. It can apply supported values to target properties, including inline values. A stylesheet-only preview is therefore not proof that every arbitrary rule will behave identically under player overrides.

Check Your Setup

If a class seems to do nothing:

  1. Confirm the exact class spelling and case. C# and UXML class lists use the name without a leading dot.
  2. Confirm that a rule for that class exists; a token in a settings file alone is not a class rule.
  3. Check that the application USS is registered and the selected settings are composed.
  4. Check that the control is inside the configured theme scope.
  5. Inspect the required parent, element type, state, and other classes.
  6. Check inline values and more specific selectors before changing theme values.
  7. Test theme switching and, if enabled, prepared player-theme application in your actual application.

Use Built-in Styling Class Reference to look up the classes that really exist. It separates reusable form roles from native/internal classes and component states; it does not promise one standalone class for every theme setting.