Theme Stack

Prerequisite: UI Toolkit Basics. This page assumes you know UXML, USS, TSS, VisualElement, Panel Settings.

When you imported the Essentials sample, you got the Theme folder. These are the assets Unity UI Toolkit reads to render Luna's components correctly.

Panel Settings (the asset)

Every UIDocument in your scene references a Panel Settings asset. Panel Settings tells Unity:

• which Theme StyleSheet (.tss) to load (Luna's Theme + your overrides arrive through this)
• scale mode — Constant Pixel Size / Constant Physical Size / Scale With Screen Size. The default scales with screen size, which softens custom shader effects at non-integer scale; consumer games often pick Constant Pixel Size with Scale=2 for crisp output (this is what HeroManager does — see Troubleshoot).
• target texture — set this for world-space UI rendered onto a quad via render texture (the World Space Panel Settings does exactly this).
• text settings — font fallback chain. UITextSettings.asset above is wired here; extend it (don't replace it) when adding fonts for new languages or emoji glyphs.

Essentials ships two Panel Settings: LunaPanelSettings.asset for screen-space UI, and LunaPanelSettingsWorldSpace.asset for in-world 3D UI. Wire your UIDocument's "Panel Settings" field to one of these and the full Luna theme applies automatically.

Theme StyleSheet (.tss) and @import inheritance

A .tss is just a USS file with one extra role: it's the root stylesheet that Panel Settings loads. Use TSS at the entry point; use plain USS for files imported into it.

Luna's theme is layered through @import:

• CupkekGamesMainTheme.tss (in Packages/com.cupkekgames.luna/Runtime/Setup/) imports every Luna USS: Unity-control restyles (UButton, UDropdown, UListView, USlider, UTabView, UToggle, URadio, UTextField), custom components (ProgressBar, InputPrompt, RenderElement), the Library utility classes (LibBorder, LibLayout, LibSize, LibColors*, LibFont*, LibMargin, LibPadding, LibPosition, LibTooltip), and UI Effects. Don't edit this — package updates would overwrite your changes.
• LunaUIDemoTheme.tss (in Essentials/Theme/) @imports the main theme then adds: color variables, component-color palettes, a font selection, scroll tuning, cursor/icons/patterns image atlases, and a Dropdown variant. This is where you override.

This is USS style inheritance: the demo TSS doesn't fork Luna's stylesheet, it imports and overrides selectively. When Luna updates CupkekGamesMainTheme.tss, you pick up the improvements; your local overrides survive.

Where to override what

For a new project, copy Essentials/Theme/ out of the imported sample (which gets overwritten on re-import) into Assets/UI/Theme/, then point your own Panel Settings at the copy.

Build colors with the Palette Generator instead of by hand

Theme/Colors/color-variables.uss is a flat list of --color-{name}-{tone} variables (e.g. --color-primary-500, --color-neutral-100) — 11 tones per palette color across a 50→950 ramp. Hand-tuning these from scratch is tedious and rarely produces a coherent palette.

Use the docs-site tool instead:

• Palette Generator — web tool that builds full 50→950 ramps per palette color + a neutral ramp. Adjust hue/saturation/lightness offsets per ramp until you're happy.
• Exports colors.uss (every --color-{name}-{tone} token) plus optional component templates (UButton_Colors.uss, USlider_Colors.uss, etc.) that map per-color CSS classes (.btn.red, .slider.coral) onto the component's internal vars.
• Drop the exports into Assets/UI/Theme/Colors/ and @import them in your TSS — colors.uss first, then any component templates.

Full round-trip walkthrough: Palette Export.

Once the palette is in place, switching a Luna component's color is a one-class change (<engine:Button class="btn red"/> → class="btn coral"); no per-element style overrides needed.

See also

• UI Toolkit Basics — UXML / USS / TSS primer
• Colors — the --color-* token scheme in depth
• Palette Export — Palette Generator round-trip in full
• Styling — per-topic deep dives (Layout, Text, Border, etc.)