Semantic Styles

Uno Themes provides a semantic style abstraction layer that lets you write theme-agnostic XAML. Instead of referencing theme-prefixed style keys (e.g. MaterialFilledButtonStyle or SimpleFilledButtonStyle), you use a single semantic key like FilledButtonStyle and the active theme resolves it to the correct design-system-specific style at runtime.

<!-- Works under both Material and Simple themes -->
<Button Style="{StaticResource FilledButtonStyle}" Content="Save" />

How It Works

Each theme's SemanticStyles.xaml defines <StaticResource> aliases that map semantic keys to theme-specific styles:

  • Material: FilledButtonStyle → MaterialFilledButtonStyle
  • Simple: FilledButtonStyle → SimpleFilledButtonStyle

Semantic style aliases exist only in Material v2 and Simple. The Material v1 styles and Cupertino declare none, so a semantic style key does not resolve under them.

Runtime discovery (for tooling)

Semantic resources are declared in dictionaries of type Uno.Themes.SemanticResources, a ResourceDictionary subclass with no members: the type is the signal. This covers the style aliases above, the control lightweight-styling brushes and layout tokens, the shared colour palette and brushes, the shared typography tokens, and the generated spacing, shape and density scales. Theme-prefixed keys are never declared in one.

A tool walking a theme's dictionaries treats a key as semantic when any dictionary declaring it is a SemanticResources, or is one of the ThemeDictionaries of a SemanticResources (a file loaded through Source copies its theme dictionaries in as plain ResourceDictionary instances). MergedDictionaries do not inherit the marker. Read the theme dictionaries through the ThemeDictionaries indexer rather than by enumerating its values: a dictionary loaded through Source holds them as lazy initializers until first indexed.

The marker type only survives when the dictionary is constructed in C#: a <SemanticResources Source="…"/> element declared in XAML compiles and resolves, but the XAML generator emits it as a plain ResourceDictionary, so a runtime walk does not see the type. Create such a dictionary in code instead (new SemanticResources { Source = new Uri("ms-appx:///…") }), as the themes do.

Control Style Mappings

The following tables show every semantic style key and how it resolves under each theme.

Button

Semantic Key Material Simple Notes
FilledButtonStyle MaterialFilledButtonStyle SimpleFilledButtonStyle Default implicit style for both themes
ElevatedButtonStyle MaterialElevatedButtonStyle GAP Simple has no elevated/shadow variant
FilledTonalButtonStyle MaterialFilledTonalButtonStyle SimpleFilledTonalButtonStyle Simple "Neutral" is closest tonal match
OutlinedButtonStyle MaterialOutlinedButtonStyle SimpleFilledTonalButtonStyle Same Simple target as FilledTonal
TextButtonStyle MaterialTextButtonStyle SimpleTextButtonStyle Text-only appearance
IconButtonStyle MaterialIconButtonStyle SimpleIconButtonStyle Simple has multiple icon button colors; Primary is default

Floating Action Button (FAB)

FAB is a Material-specific concept. Under Simple theme, FAB keys resolve to existing icon button styles.

Semantic Key Material Simple Notes
FabStyle MaterialFabStyle SimpleIconButtonStyle Primary icon button as FAB equivalent
SmallFabStyle MaterialSmallFabStyle SimpleIconButtonStyle Same as FabStyle
LargeFabStyle MaterialLargeFabStyle SimpleIconButtonStyle No large variant in Simple
SecondaryFabStyle MaterialSecondaryFabStyle SimpleIconButtonNeutralStyle
SecondarySmallFabStyle MaterialSecondarySmallFabStyle SimpleIconButtonNeutralStyle
SecondaryLargeFabStyle MaterialSecondaryLargeFabStyle SimpleIconButtonNeutralStyle
TertiaryFabStyle MaterialTertiaryFabStyle SimpleIconButtonSubtleStyle
TertiarySmallFabStyle MaterialTertiarySmallFabStyle SimpleIconButtonSubtleStyle
TertiaryLargeFabStyle MaterialTertiaryLargeFabStyle SimpleIconButtonSubtleStyle
SurfaceFabStyle MaterialSurfaceFabStyle SimpleIconButtonNeutralStyle
SurfaceSmallFabStyle MaterialSurfaceSmallFabStyle SimpleIconButtonNeutralStyle
SurfaceLargeFabStyle MaterialSurfaceLargeFabStyle SimpleIconButtonNeutralStyle

ToggleButton

Semantic Key Material Simple Notes
TextToggleButtonStyle MaterialTextToggleButtonStyle SimpleTextToggleButtonStyle Text content toggle
IconToggleButtonStyle MaterialIconToggleButtonStyle SimpleIconToggleButtonStyle Compact icon-only toggle

TextBox

Semantic Key Material Simple Notes
FilledTextBoxStyle MaterialFilledTextBoxStyle SimpleFilledTextBoxStyle Background fill, no border
OutlinedTextBoxStyle MaterialOutlinedTextBoxStyle SimpleOutlinedTextBoxStyle Default implicit style for Simple

PasswordBox

Semantic Key Material Simple Notes
FilledPasswordBoxStyle MaterialFilledPasswordBoxStyle SimpleFilledPasswordBoxStyle Background fill with border
OutlinedPasswordBoxStyle MaterialOutlinedPasswordBoxStyle SimpleOutlinedPasswordBoxStyle Default implicit style for Simple

HyperlinkButton

Semantic Key Material Simple Notes
HyperlinkButtonStyle MaterialHyperlinkButtonStyle SimpleHyperlinkButtonStyle Primary underlined link
SecondaryHyperlinkButtonStyle MaterialSecondaryHyperlinkButtonStyle SimpleSecondaryHyperlinkButtonStyle Secondary underlined link

ComboBox

Semantic Key Material Simple Notes
ComboBoxStyle MaterialComboBoxStyle SimpleComboBoxStyle Direct match
ComboBoxItemStyle MaterialComboBoxItemStyle SimpleComboBoxItemStyle Direct match

CheckBox

Semantic Key Material Simple Notes
CheckBoxStyle MaterialCheckBoxStyle SimpleCheckBoxStyle Direct match

RadioButton

Semantic Key Material Simple Notes
RadioButtonStyle MaterialRadioButtonStyle SimpleRadioButtonStyle Direct match

ToggleSwitch

Semantic Key Material Simple Notes
ToggleSwitchStyle MaterialToggleSwitchStyle SimpleToggleSwitchStyle Direct match

Slider

Semantic Key Material Simple Notes
SliderStyle MaterialSliderStyle SimpleSliderStyle Direct match

ProgressBar

Semantic Key Material Simple Notes
ProgressBarStyle MaterialProgressBarStyle SimpleProgressBarStyle Horizontal indicator

ProgressRing

Semantic Key Material Simple Notes
ProgressRingStyle MaterialProgressRingStyle SimpleProgressRingStyle Circular indicator

ListView

Semantic Key Material Simple Notes
ListViewStyle MaterialListViewStyle SimpleListViewStyle Direct match
ListViewItemStyle MaterialListViewItemStyle SimpleListViewItemStyle Direct match

ContentDialog

Semantic Key Material Simple Notes
ContentDialogStyle MaterialContentDialogStyle SimpleContentDialogStyle Direct match

CommandBar

Semantic Key Material Simple Notes
CommandBarStyle MaterialCommandBarStyle GAP Simple has no CommandBar style

AppBarButton

Semantic Key Material Simple Notes
AppBarButtonStyle MaterialAppBarButtonStyle SimpleAppBarButtonStyle Direct match
Semantic Key Material Simple Notes
NavigationViewStyle MaterialNavigationViewStyle SimpleNavigationViewStyle
NavigationViewItemStyle MaterialNavigationViewItemStyle SimpleNavigationViewItemStyle

CalendarView

Semantic Key Material Simple Notes
CalendarViewStyle MaterialCalendarViewStyle SimpleCalendarViewStyle Direct match

CalendarDatePicker

Semantic Key Material Simple Notes
CalendarDatePickerStyle MaterialCalendarDatePickerStyle SimpleCalendarDatePickerStyle Direct match

DatePicker

Semantic Key Material Simple Notes
DatePickerStyle MaterialDatePickerStyle SimpleDatePickerStyle Direct match
DatePickerFlyoutPresenterStyle MaterialDatePickerFlyoutPresenterStyle GAP Simple declares no alias for its SimpleDatePickerFlyoutPresenterStyle

MediaPlayerElement

Semantic Key Material Simple Notes
MediaTransportControlsStyle MaterialMediaTransportControlsStyle GAP Simple has no media style

PipsPager

Semantic Key Material Simple Notes
PipsPagerStyle MaterialPipsPagerStyle SimplePipsPagerStyle Pagination dots

RatingControl

Semantic Key Material Simple Notes
RatingControlStyle MaterialRatingControlStyle SimpleRatingControlStyle Star rating with brand colors

Ripple

Semantic Key Material Simple Notes
RippleStyle MaterialRippleStyle GAP Ripple is a Uno Material control

Flyout / MenuFlyout

Semantic Key Material Simple Notes
FlyoutPresenterStyle MaterialFlyoutPresenterStyle SimpleFlyoutPresenterStyle
MenuFlyoutPresenterStyle MaterialMenuFlyoutPresenterStyle SimpleMenuFlyoutPresenterStyle Direct match
MenuFlyoutItemStyle MaterialMenuFlyoutItemStyle SimpleMenuFlyoutItemStyle Direct match
MenuFlyoutSeparatorStyle MaterialMenuFlyoutSeparatorStyle SimpleMenuFlyoutSeparatorStyle Direct match
MenuFlyoutSubItemStyle MaterialMenuFlyoutSubItemStyle SimpleMenuFlyoutSubItemStyle Direct match
ToggleMenuFlyoutItemStyle MaterialToggleMenuFlyoutItemStyle SimpleToggleMenuFlyoutItemStyle Direct match
RadioMenuFlyoutItemStyle MaterialRadioMenuFlyoutItemStyle SimpleRadioMenuFlyoutItemStyle Radio bullet indicator

Typography

Both themes provide identical semantic typography keys based on the Material Design 3 type scale.

Every *FontFamily key derives from the single DefaultFontFamily root token, so overriding that one key swaps the typeface across the whole type scale; per-scale weight nuance is carried by the *FontWeight tokens. See Design Tokens - Typography.

Semantic Style Key Font Resource Keys
DisplayLarge DisplayLargeFontFamily, DisplayLargeFontSize, DisplayLargeFontWeight, DisplayLargeCharacterSpacing
DisplayMedium DisplayMediumFontFamily, DisplayMediumFontSize, DisplayMediumFontWeight
DisplaySmall DisplaySmallFontFamily, DisplaySmallFontSize, DisplaySmallFontWeight
HeadlineLarge HeadlineLargeFontFamily, HeadlineLargeFontSize, HeadlineLargeFontWeight
HeadlineMedium HeadlineMediumFontFamily, HeadlineMediumFontSize, HeadlineMediumFontWeight
HeadlineSmall HeadlineSmallFontFamily, HeadlineSmallFontSize, HeadlineSmallFontWeight
TitleLarge TitleLargeFontFamily, TitleLargeFontSize, TitleLargeFontWeight
TitleMedium TitleMediumFontFamily, TitleMediumFontSize, TitleMediumFontWeight
TitleSmall TitleSmallFontFamily, TitleSmallFontSize, TitleSmallFontWeight
BodyLarge BodyLargeFontFamily, BodyLargeFontSize, BodyLargeFontWeight, BodyLargeCharacterSpacing
BodyMedium BodyMediumFontFamily, BodyMediumFontSize, BodyMediumFontWeight, BodyMediumCharacterSpacing
BodySmall BodySmallFontFamily, BodySmallFontSize, BodySmallFontWeight, BodySmallCharacterSpacing
LabelLarge LabelLargeFontFamily, LabelLargeFontSize, LabelLargeFontWeight, LabelLargeCharacterSpacing
LabelMedium LabelMediumFontFamily, LabelMediumFontSize, LabelMediumFontWeight, LabelMediumCharacterSpacing
LabelSmall LabelSmallFontFamily, LabelSmallFontSize, LabelSmallFontWeight, LabelSmallCharacterSpacing
LabelExtraSmall LabelExtraSmallFontFamily, LabelExtraSmallFontSize, LabelExtraSmallFontWeight, LabelExtraSmallCharacterSpacing
CaptionLarge CaptionLargeFontFamily, CaptionLargeFontSize, CaptionLargeFontWeight, CaptionLargeCharacterSpacing
CaptionMedium CaptionMediumFontFamily, CaptionMediumFontSize, CaptionMediumFontWeight, CaptionMediumCharacterSpacing
CaptionSmall CaptionSmallFontFamily, CaptionSmallFontSize, CaptionSmallFontWeight, CaptionSmallCharacterSpacing

Each theme's Typography.xaml provides the concrete values for these keys. The font resource keys (e.g. BodyLargeFontSize) are the same across themes and can be used directly for lightweight styling overrides.

Lightweight Styling Portability

Semantic style keys also enable portable lightweight styling. Both themes expose semantic resource keys for customizing control appearance:

<!-- This override works under both Material and Simple themes -->
<SolidColorBrush x:Key="FilledButtonForeground" Color="Red" />

Both Material and Simple templates reference the same unprefixed keys (e.g. FilledButtonForeground) directly. Their lightweight-styling declarations live in the theme's SemanticStyles.xaml, alongside the style aliases, so tooling discovers them through SemanticResources too. Light, Default and any HighContrast entries keep their existing values; theme-prefixed compatibility aliases remain in the control dictionaries.

The color palette underneath these keys can itself be swapped wholesale — generated from a single seed color, and even changed at runtime — see Seed Color Palette.

For more details on per-control lightweight styling resources, see the individual control style pages: