|
Window Framework for UI Toolkit v2.0.x
|
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.
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 stylesheets contain selectors and the rules that consume theme values:
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.
A selected theme's settings USS owns its colors, spacing, typography, dimensions, image references, and supported extension defaults. For example:
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.
The supplied Default 2.0 theme's TSS imports its own settings 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.
For a modern theme using collection application sheets, the order is:
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.
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.
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.
Put this rule in your registered application stylesheet:
Then apply your class in code:
Or add it to authored content:
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.
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.
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:
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:
The application stylesheet then consumes it:
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.
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.
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.
If a class seems to do nothing:
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.