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 | Topic | Search query | |---|---| | Installation / `MaterialTheme` / `UnoFeatures` | `uno_platform_docs_search("Uno Material installation MaterialTheme UnoFeatures")` | | Control styles (Button / TextBox / FAB / etc.) | `uno_platform_docs_search("Uno Material controls styles")` | | Color palette + brushes (MD3) | `uno_platform_docs_search("Uno Material colors brushes MD3 palette")` | | Typography / type scale | `uno_platform_docs_search("Uno Material typography type scale")` | | Lightweight styling (per-control overrides) | `uno_platform_docs_search("Uno Material lightweight styling resource keys")` | | Color customization / Theme Builder | `uno_platform_docs_search("Uno Material color customization Theme Builder DSP")` | | Font customization | `uno_platform_docs_search("Uno Material font customization font family override")` | | Control extensions (icons, elevation) | `uno_platform_docs_search("Uno Material control extensions icons elevation")` | | C# Markup with Material | `uno_platform_docs_search("Uno.Themes.WinUI.Markup C# Markup Material")` | | Version migration | `uno_platform_docs_search("Uno Material migration v1 v2 v3")` | ### 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`: ```xml <UnoFeatures>Material</UnoFeatures> <!-- or Material;Toolkit --> ``` In `App.xaml`: ```xml <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 | Style key | Use for | |---|---| | `FilledButtonStyle` | **Default**. Primary actions ("Save", "Submit") | | `ElevatedButtonStyle` | Primary action with elevation/shadow | | `FilledTonalButtonStyle` | Secondary action; softer than Filled | | `OutlinedButtonStyle` | Secondary action with border | | `TextButtonStyle` | Tertiary / low-emphasis action | | `IconButtonStyle` | Icon-only action (pair with `Icons.Icon` attached property) | ### FAB (FloatingActionButton; applied to `Button`) | Style key family | Sizes | |---|---| | `FabStyle` / `SmallFabStyle` / `LargeFabStyle` | Primary FAB | | `SecondaryFabStyle` / `SecondarySmallFabStyle` / `SecondaryLargeFabStyle` | Secondary color | | `TertiaryFabStyle` / `TertiarySmallFabStyle` / `TertiaryLargeFabStyle` | Tertiary color | | `SurfaceFabStyle` / `SurfaceSmallFabStyle` / `SurfaceLargeFabStyle` | Surface color | ### TextBox / PasswordBox | Style key | Notes | |---|---| | `FilledTextBoxStyle` | **Material default** for TextBox | | `OutlinedTextBoxStyle` | Outlined variant | | `FilledPasswordBoxStyle` | **Material default** for PasswordBox | | `OutlinedPasswordBoxStyle` | Outlined variant | ## 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`. | Suffix | Opacity | Purpose | |---|---|---| | *(none)* | 1.0 | Rest state | | `Hover` | 0.08 | Pointer hover layer | | `Focused` | 0.12 | Keyboard focus layer | | `Pressed` | 0.12 | Active press layer | | `Dragged` | 0.16 | Drag operation layer | | `Selected` | 0.08 | Selected item layer | | `Medium` | 0.64 | Medium-emphasis text/icons | | `Low` | 0.32 | Low-emphasis text, placeholders | | `Disabled` | 0.12 | Disabled state | 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`. | Family | Keys | |---|---| | Display | `DisplayLarge`, `DisplayMedium`, `DisplaySmall` | | Headline | `HeadlineLarge`, `HeadlineMedium`, `HeadlineSmall` | | Title | `TitleLarge`, `TitleMedium`, `TitleSmall` | | Body | `BodyLarge`, `BodyMedium`, `BodySmall` | | Label | `LabelLarge`, `LabelMedium`, `LabelSmall`, `LabelExtraSmall` | | Caption | `CaptionLarge`, `CaptionMedium`, `CaptionSmall` | 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`. ```csharp 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.