Uno Themes Material

Uno Material — Agent Skill

Consolidated reference for the Uno Material theme. For any deep dive (full key tables, code samples, version-specific gotchas), fetch the authoritative docs via the steps below; the inline tables here cover the most-asked-for facts for fast lookup.

Workflow

Docs lookup: call uno_platform_docs_search(...) first, then uno_platform_docs_fetch(sourcePath="…") using the sourcePath field from a result (a relative .md path; add the result's anchor for a section). Never pass a URL, a .html link, or a hand-built path.

Step 1: Pick the relevant topic and search the docs

Step 2: Fetch the canonical pages

• Material Getting Started: external/uno.themes/doc/material-getting-started.md
• Material Toolkit Getting Started: external/uno.toolkit.ui/doc/material-getting-started.md (use MaterialToolkitTheme for Toolkit+Material)
• Material Controls Styles: external/uno.themes/doc/material-controls-styles.md
• Lightweight Styling: external/uno.themes/doc/lightweight-styling.md
• Material Migration: external/uno.themes/doc/material-migration.md

uno_platform_docs_fetch(sourcePath="…")  # the sourcePath field from a search result above; never a URL/.html

Critical Rules

• Brushes use {ThemeResource}, NOT {StaticResource} — so the bound color follows the active theme (Light / Dark) at runtime. <TextBlock Foreground="{ThemeResource PrimaryBrush}" />.
• Styles use {StaticResource} — control styles don't change with the theme; their internal bindings already use ThemeResource for brushes.
• Use MaterialToolkitTheme or MaterialTheme, not both — when using both Toolkit + Material, MaterialToolkitTheme replaces MaterialTheme + ToolkitResources. Mixing them double-loads resources.

Installation (quick reference)

In .csproj:

<UnoFeatures>Material</UnoFeatures>             <!-- or Material;Toolkit -->

In App.xaml:

<ResourceDictionary.MergedDictionaries>
    <MaterialTheme xmlns="using:Uno.Material" />
</ResourceDictionary.MergedDictionaries>

Use <MaterialToolkitTheme xmlns="using:Uno.Toolkit.Material" /> if also using Uno Toolkit.

Control Style Keys (quick reference)

Button

FAB (FloatingActionButton; applied to Button)

TextBox / PasswordBox

Color Palette Keys (Layer 1)

Material follows the MD3 role system. 32 color keys with Light/Dark variants. Most-used role families:

• Primary: PrimaryColor, OnPrimaryColor, PrimaryContainerColor, OnPrimaryContainerColor, PrimaryInverseColor
• Secondary: SecondaryColor, OnSecondaryColor, SecondaryContainerColor, OnSecondaryContainerColor
• Tertiary: TertiaryColor, OnTertiaryColor, TertiaryContainerColor, OnTertiaryContainerColor
• Error: ErrorColor, OnErrorColor, ErrorContainerColor, OnErrorContainerColor
• Surface: SurfaceColor, OnSurfaceColor, SurfaceVariantColor, OnSurfaceVariantColor, SurfaceInverseColor, OnSurfaceInverseColor, SurfaceTintColor
• Background / Outline / Shadow: BackgroundColor, OnBackgroundColor, OutlineColor, OutlineVariantColor, ShadowColor

Pairing rule: every background role has a designated foreground role. PrimaryBrush ↔ OnPrimaryBrush. ErrorContainerBrush ↔ OnErrorContainerBrush. Don't mix unpaired colors. (See uno-themes-semantic-colors-brushes for the shared semantic surface common to Material + Simple.)

Brush System (Layer 2)

Each color key generates ~9 brush variants with opacity tokens. Pattern: {ColorRole}{StateVariant}Brush.

Total: ~288 brushes generated from the palette + opacity tokens.

Typography (Layer)

M3 type scale, used as TextBlock styles. Never theme-prefix typography keys — write DisplayLarge, not MaterialDisplayLarge.

Each style exposes {StyleKey}FontFamily, FontSize, FontWeight resource keys for lightweight styling overrides.

Control Extensions

Material ships attached properties for icon, elevation, and toggle-content patterns (namespace using:Uno.Material.Controls):

• Icons.Icon — adds an icon to a Button (esp. IconButtonStyle).
• Elevation extensions — apply MD3 elevation shadows; layered with ShadowContainer for richer effects.
• Alternate content — display different content based on ToggleButton.IsChecked.

Customization

Three escalating scopes:

1. Palette override (full cascade) — override *Color keys via ColorOverrideSource / ColorOverrideDictionary on MaterialTheme. All ~288 brushes and controls update automatically. Generate the palette XAML via Material Theme Builder (DSP format).
2. Specific brush override (targeted) — drop a <SolidColorBrush x:Key="FilledButtonBackground" Color="..." /> into App.xaml or scoped resources.
3. Per-instance override (scoped) — wrap the override in the control's Resources block.

Font override: set FontOverrideSource / FontOverrideDictionary on MaterialTheme, or override individual *FontFamily keys.

C# Markup

Use Uno.Themes.WinUI.Markup for fluent C# styling — .MaterialFilledButtonStyle(), .MaterialOutlinedTextBoxStyle(), etc. Resource keys exposed as constants under MaterialThemeResources.

new Button().Content("Save").MaterialFilledButtonStyle()

Migration

Between major versions, resource keys, converters, and style names can change. Fetch the migration page on upgrade:

uno_platform_docs_fetch(sourcePath="external/uno.themes/doc/material-migration.md")

Key checks: renamed resource keys, removed converters, NuGet package renames, UnoFeatures flag changes.

Related Skills

• [[uno-themes-semantic-colors-brushes]] — Shared semantic design language (style keys + typography + colors that work across Material AND Simple themes). Read this first if styling needs to be portable between themes.
• [[uno-themes-simple]] — Simple theme specifics. Use when targeting Simple (designer/wireframe look) or its theme-specific styles (danger buttons, size variants, utility brushes, PersonPicture, etc.).
• [[uno-toolkit-material-theme]] — MaterialToolkitTheme setup for Toolkit + Material.