Theming

The flutter_miuix theme system has three layers — pick what you need:

Widget	Use case
MiuixTheme	Manually provide a fixed MiuixThemeData (lowest level)
MiuixSystemTheme	Follow the system light/dark mode, with optional custom light/dark colors (most common)
MiuixThemeController	Full controller: forced light/dark, Monet dynamic color, palette styles

See Theme, Colors & Motion for the complete API reference.

Follow the system: MiuixSystemTheme

Most apps only need MiuixSystemTheme at the root:

MiuixSystemTheme(
  child: Builder(builder: (context) {
    final theme = MiuixTheme.of(context);
    return MaterialApp(
      theme: ThemeData(brightness: theme.brightness),
      home: const HomePage(),
    );
  }),
)

Reading the theme

Anywhere in the tree, read the current theme via MiuixTheme.of(context):

final theme = MiuixTheme.of(context);

theme.colors.primary;        // colors: 50+ HyperOS semantic roles
theme.textStyles.title2;     // text styles: 14 presets
theme.brightness;            // current brightness

Without a theme widget above, MiuixTheme.of falls back to MiuixThemeData.light(); MiuixTheme.maybeOf(context) returns null without establishing a dependency.

Custom colors

Defaults come from lightColorScheme() / darkColorScheme() (matching the HyperOS spec: light primary 0xFF3482FF, dark primary 0xFF277AF7). Override selected roles with copy and pass the result to MiuixSystemTheme:

MiuixSystemTheme(
  light: lightColorScheme().copy(
    primary: const Color(0xFFFF6B35),
    background: const Color(0xFFFFFBF8),
  ),
  dark: darkColorScheme().copy(
    primary: const Color(0xFFFF8C5A),
  ),
  child: ...,
)

All semantic roles of MiuixColors (primary / surface / containers / disabled states — 50+ fields) are listed in the MiuixColors reference.

Custom text styles

MiuixSystemTheme(
  textStyles: defaultTextStyles().copy(
    title1: const TextStyle(fontSize: 36, fontWeight: FontWeight.w600),
  ),
  child: ...,
)

Styles carry only size / weight / line height; the color is supplied at runtime from the theme's onBackground.

Full control: MiuixThemeController

For forced light/dark or Monet dynamic color, use MiuixThemeController instead:

MiuixThemeController(
  colorSchemeMode: MiuixColorSchemeMode.monetSystem,
  keyColor: const Color(0xFF6750A4),   // seed color; null = platform wallpaper color
  child: MyApp(),
)

Color scheme modes

MiuixColorSchemeMode	Description
system	Follow system brightness with static light/dark colors (default)
light	Force light
dark	Force dark
monetSystem	Follow system brightness + Monet dynamic color
monetLight	Light + Monet dynamic color
monetDark	Dark + Monet dynamic color

How Monet resolves colors

1. keyColor non-null → synchronously calls miuixColorsFromSeed (pure HCT math, no platform channel) to generate the full 27-role scheme from the seed.
2. keyColor null → asynchronously calls miuixPlatformDynamicColors: on Android it reads the system wallpaper/theme seed color; other platforms fall back to the fixed seed 0xFF6750A4. While the result is pending, miuixMonetSystemColors is used as a placeholder to avoid flicker.

Palette styles

Switch the Monet palette flavor with paletteStyle (mapping to Material's 9 DynamicSchemes):

MiuixThemeController(
  colorSchemeMode: MiuixColorSchemeMode.monetSystem,
  keyColor: const Color(0xFF6750A4),
  paletteStyle: MiuixThemePaletteStyle.vibrant,
  child: MyApp(),
)

Options: tonalSpot (default), neutral, vibrant, expressive, rainbow, fruitSalad, monochrome, fidelity, content.

Generating a scheme manually

You can also generate a MiuixColors from a seed without the controller:

final colors = miuixColorsFromSeed(
  seed: const Color(0xFF6750A4),
  dark: false,
  paletteStyle: MiuixThemePaletteStyle.tonalSpot,
);

MiuixTheme(
  data: MiuixThemeData.light(colors: colors),
  child: ...,
)

Mixing with Material widgets

Miuix widgets depend only on MiuixTheme. If a page also uses Material widgets, bridge the Miuix primary color into Material's ColorScheme so both look consistent:

final theme = MiuixTheme.of(context);

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(
      seedColor: theme.colors.primary,
      brightness: theme.brightness,
    ),
    brightness: theme.brightness,
  ),
  home: ...,
)

Next steps

• Theme, Colors & Motion API reference — full parameter tables for MiuixThemeData / MiuixColors / MiuixTextStyles / MiuixMotion
• Blur & Liquid Glass — frosted glass and bloom strokes