Uno Themes
Uno Themes supplies the look of an Uno Platform app through one of two design themes, Simple (the template default) or Material (MD3), built on a shared semantic layer of style keys, typography keys, palette colors, and generated brushes. Generic agents restyle Uno apps by hard-coding hex colors, font sizes, and copied control templates; that breaks dark mode, theme switching, and brand overrides at once. This skill routes you to the right reference and keeps styling on the semantic keys so the theme does the work.
Workflow
- Find the task in the topic map and read the matching
references/*.mdfile before writing XAML. Start withsemantic-colors-brushes.mdwhen the styling should stay portable between Material and Simple. - The reference answers the common case; the docs pages it names are for what it leaves out. Then search with
uno_platform_docs_search(...)and fetch only the section you need:uno_platform_docs_fetch(sourcePath="…", anchor="…"), both values from a search result. A whole page is 2,000 to 6,000 tokens that stay in context for the rest of the session. Never pass a URL,.htmllink, or hand-built path. Simple's pages areexternal/uno.themes/doc/simple-getting-started.mdandsimple-controls-styles.md. - Apply the critical rules below to every brush, style, and font you emit, then check the generated XAML against them before finishing.
Topic map
| Task | Read | Key APIs |
|---|---|---|
| Pick a brush, a text style, or a control style that works in any theme | references/semantic-colors-brushes.md |
PrimaryBrush/OnPrimaryBrush pairs, BodyMedium, FilledButtonStyle |
| Which brush for text on a surface, an error banner, a snackbar, a CTA | references/semantic-colors-brushes.md (Decision Guides) |
OnSurfaceBrush, OnSurfaceVariantBrush, ErrorContainerBrush, SurfaceInverseBrush |
| Understand palette → brushes → control keys and override precedence | references/semantic-colors-brushes.md (Part 3, Part 4) |
*Color keys, {Role}{State}Brush, FilledButtonBackground |
Install Material, set up MaterialTheme, Material control styles, FAB, elevation, icons |
references/material.md |
<UnoFeatures>Material</UnoFeatures>, MaterialTheme, ut:ControlExtensions.Icon, FabStyle |
| Customize the primary color or fonts for Material, Theme Builder, migration between versions | references/material-customization.md |
Colors (ThemeColors.OverrideSource / PrimarySeed), DefaultFontFamily, material-migration.md |
Simple theme (the template default), SimpleTheme, grayscale palette, Inter font, density and corner radius |
references/simple.md |
<UnoFeatures>SimpleTheme</UnoFeatures>, SimpleTheme, DefaultDensity, DefaultCornerRadius |
| Danger buttons, error inputs, Expander, AutoSuggestBox, ToolTip, PersonPicture, overlay/scrim brushes | references/simple-styles.md |
SimpleDangerPrimaryButtonStyle, SimpleTextBoxErrorStyle, SimpleBackgroundUtilitiesScrimBrush |
| Change one control's color without touching the palette | references/semantic-colors-brushes.md (Part 4) or references/material-customization.md |
Layer 3 keys such as FilledButtonBackground, Control.Resources |
Style Uno Toolkit controls or configure MaterialToolkitTheme / SimpleToolkitTheme / CupertinoToolkitResources |
the uno-toolkit skill (references/material-theme.md, references/lightweight-styling.md) |
MaterialToolkitTheme, SimpleToolkitTheme |
Critical rules
- Never hard-code colors, fonts, or sizes in page XAML. A literal
#RRGGBB,FontSize="14", orFontFamily="Segoe UI"ignores dark mode and every brand override. Use a semantic brush ({ThemeResource OnSurfaceBrush}) and a typography style (Style="{StaticResource BodyMedium}"); the theme supplies the concrete values. - Brushes use
{ThemeResource}, styles use{StaticResource}. Brushes must re-resolve when the app switches between Light and Dark; styles never change with the theme and their internal bindings already useThemeResource. Getting this backwards produces text that vanishes in dark mode. - Pair every background role with its
Onforeground.PrimaryBrushtakesOnPrimaryBrush,ErrorContainerBrushtakesOnErrorContainerBrush,SurfaceBrushtakesOnSurfaceBrush(high emphasis) orOnSurfaceVariantBrush(medium). Unpaired combinations fail contrast in one of the two modes. - Use semantic keys, never theme-prefixed ones, in portable XAML. Write
FilledButtonStyleandDisplayLarge, notMaterialFilledButtonStyleorSimpleDisplayLarge. Prefixed keys such asMaterialBodyMediumandSimpleFilledButtonStyleexist, but only the unprefixed aliases resolve under both themes; theSimple*prefix is required only for Simple-only control styles. - Restyle through resource keys, not copied templates. Each control exposes lightweight styling keys (
FilledButtonBackground,BodyMediumFontSize) at app, page, or control scope. Copying a control template freezes it against theme updates and doubles the XAML to maintain. - Rebrand at the palette, not brush by brush. Override the
*Colorkeys through the theme'sColorsproperty:<MaterialTheme.Colors>(or<SimpleTheme.Colors>) holding<ut:ThemeColors xmlns:ut="using:Uno.Themes" OverrideSource="ms-appx:///..." />(orOverrideDictionary).ColorOverrideSource/ColorOverrideDictionaryare obsolete but still work, and the template still emitsColorOverrideSource; migrate it when touching that line. Provide bothLightandDefault(Dark) values; all 280 brushes and every control follow. The fastest path to a brand palette is a seed:<ut:ThemeColors PrimarySeed="#0F62FE" />(alsoSecondarySeed,TertiarySeed) generates every role except Error (ErrorColor,OnErrorColor,ErrorContainerColor,OnErrorContainerColorkeep the theme's base values; override them explicitly). Override an individual brush only for a one-off exception. - Pick seed or override from what the design fixes. In the default
SeedColorMode(Fidelity) only the lightPrimaryColoris the seed verbatim; every other role, dark Primary included, is generated at fixed tones, and aSecondarySeedorTertiarySeedkeeps its hue, not its hex. One or two brand colours: a seed. Some roles given exactly: a seed plusOverrideDictionaryfor those roles, which wins over the generated values. A full token table with light and dark values: override the whole palette, because any generated role a control draws is a colour the design does not list. Tokens with no palette role (statuses, chart steps, map pins) are the app's own brushes inApp.xaml'sLightandDefaulttheme dictionaries, and every token that does have a role is used through the role's brush (PrimaryBrush,OnSurfaceBrush), not mirrored under the design's name. - Switch the palette at runtime through the theme, never by rewriting brushes. Assign a new dictionary to
SemanticThemeHelper.GetTheme().Colors.OverrideDictionary(or setOverrideSource), or setSemanticThemeHelper.PrimarySeedand the other seeds; the theme regenerates the palette and every brush follows. A brand picker or an extra mode such as a high-contrast outdoor theme is one override dictionary per variant that the app keeps and assigns. Editing the assigned dictionary in place triggers nothing, and walkingMergedDictionariesto rewrite*Colorand*Brushkeys duplicates what the theme already does. - Material setup is
<UnoFeatures>Material</UnoFeatures>plus<MaterialTheme xmlns="using:Uno.Material" />inApp.xamlmerged dictionaries. With Uno Toolkit present, useMaterialToolkitThemeinstead ofMaterialTheme+ToolkitResources; loading both duplicates resources. The Simple equivalent is<utus:SimpleToolkitTheme xmlns:utus="using:Uno.Toolkit.UI.Simple" />, which the recommended preset emits; it derives fromSimpleTheme, so setColors,DefaultFontFamily,DefaultDensity, andDefaultCornerRadiuson it and never add a bareSimpleThemenext to it. - Keep the project's theme; for a new app, follow the template.
dotnet new unoapp -preset recommendedselects Simple, a lightweight design system with minimal styling (grayscale palette, Inter font,DefaultDensityCompact/Regular/Comfy) that also carries controls Material lacks (Expander, AutoSuggestBox, ToolTip, PersonPicture). Choose Material when the brief or design asks for Material Design 3, MD3 color roles or elevation. Both implement the shared semantic layer, so the role brushes (PrimaryBrush,SurfaceBrush,OnSurfaceVariantBrush, ...) resolve under either. Do not switch an existing app's theme unasked, and do not mix theme-specific keys from one into a project running the other. An app created with-preset blankuses Fluent and has no Material or Simple theme, so no semantic key resolves there; use WinUI resources, or add a theme only with the user's consent. - Spacing and sizes come from design tokens.
Space*,Radius*, andControlHeight*resource keys (seeexternal/uno.themes/doc/design-tokens.md) replace literal margins and heights. On the theme,DefaultDensityandDefaultSpacingscale only theSpace*tokens andDefaultCornerRadiusonly theRadius*tokens;ControlHeight*,IconSize*, andTouchTargetMinSizeare fixed. Set a design's base radius, spacing unit and density there instead of defining app keys for them. All three can change at runtime onSemanticThemeHelper.GetTheme()(the helper has no property of its own for them): controls created afterwards follow, while controls already on screen keep their values until a theme-change pass (toggle the root element'sRequestedThemeaway from itsActualThemeand back) or recreated root content. - Version migration is a docs task. Resource keys, converters, and package names change between major versions; fetch
external/uno.themes/doc/material-migration.mdbefore upgrading rather than guessing renamed keys. Uno.Themes 8.0 removesSimpleFontFamilyand the per-weight font keys (the root token isDefaultFontFamily) and reworks seed generation (SeedColorMode). This skill targets Uno.Themes 9.0 (Uno.Sdk 7.0.0-dev.77 pins 9.0.0-dev.42; the 8.0 changes above still apply); an app still on 7.x lacksDefaultFontFamily,DefaultSpacing, andSeedColorMode.
Related skills
uno-toolkitforMaterialToolkitTheme/CupertinoToolkitResourcessetup and lightweight styling of Toolkit controls (TabBar,CardContentControl,NavigationBar).uno-platformfor project-wide rules and<UnoFeatures>configuration.uno-testingto confirm a restyle renders correctly in both Light and Dark in the running app.