FlexColorScheme builds a matched light and dark theme from one scheme

One scheme, two themes, and the reason the API is shaped that way

The package is a Flutter favourite, and the pitch is that you get standard ThemeData out of it. FlexColorScheme 9.x builds matched light and dark ThemeData for Flutter 3.47 and later, with full support for the SDK-decoupled material_ui and cupertino_ui packages. The stated aim is to make Material Design themes with optional surface blends, seed generated ColorSchemes and quick component settings, and the result is standard ThemeData with more complete ColorScheme wiring than Flutter's own ThemeData.from and colorSchemeSeed factories. That last clause is the whole argument. The SDK factory is a convenience, and this package is the version of that convenience with the gaps filled, and it themes all the Flutter SDK UI components from your ColorScheme and your custom colors, including the legacy ThemeData color properties, in Material 2 or Material 3 mode.

Version 9 exists because Flutter's UI libraries left the SDK

The reason for the major version is stated in one sentence, that version 9.0 is a major release because Flutter's UI libraries left the SDK. The material_ui and cupertino_ui packages are now separate, and FlexColorScheme 9.0 supports them, with the SDK-decoupled packages linked in the README. The rest of the version is otherwise an easy step from 8.4, and the breaking API and seed-tone details are in the changelog and on the documentation site. The dependency floor is stated precisely too. Version 9.0 allows any material_ui or cupertino_ui 1.x, meaning ^1.0.0, and it does not use APIs added after 1.0.0 of those packages, and later FlexColorScheme releases will raise that floor when they adopt new features from them. Your app still needs a direct material_ui import for MaterialApp and the widgets, which is a small detail that catches people out when they upgrade and find the imports have to change.

The playground is the configuration tool

The workflow the package wants is visual rather than textual. You configure visually in the Themes Playground and copy the API setup into your app, which is the right way round for a theme because a colour scheme is a large object with many fields and tuning it in code is slow. The package also ships a heavily commented default example, which the README calls the default example guide, and the documentation site carries a set of examples and a tutorial. The package's own documentation in the repository is unusually extensive, with a FEATURES.md, an INSIDE.md, a changelog/ directory of fragments, a docs/ directory, a scripts/ directory, a full example/ application for every platform including web, and separate README-V3.md and README-V4.md files for the older major versions, which is what a package with nine years of users tends to accumulate.

Seed generation, with more than one seed and a tone curve

The part that goes past the SDK is the colour scheme generation. The README says that surface alpha blends and seed generated ColorSchemes go beyond Flutter's seed factory, with multiple seed colors, custom minimum chroma and custom tone mapping. Each of those is a knob the SDK does not expose. Multiple seed colors let a scheme be built from a primary and an accent rather than a single seed, which is what produces the branded schemes in the screenshots, where a Verdun green or a Rust palette has a recognisable identity rather than being a tint of one hue. Custom minimum chroma controls how saturated the darkest and lightest tones are allowed to be, and tone mapping controls the curve that maps a seed onto the tonal palette, and both of those are the difference between a scheme that looks muddy in dark mode and one that does not.

Component themes with flat properties and opt-in

Beyond the colours, the package lets you adjust the component themes, and the model has two levels. You opt in on component themes to adjust shared styles, for example border radius on many widgets with one property, and the component themes use simple flat properties so you can skip the verbose SDK ShapeBorder and WidgetState theme objects for common cases. Material 3 is the default since FlexColorScheme v8, matching Flutter's own ThemeData, and the component theme defaults follow Material 3 including the per-widget radii that the Material 3 guide specifies, and you can keep those defaults, set a shared global radius, or override the radius per widget. That three-way choice is the sensible part, because a per-widget override is where a theme starts to become a pile of exceptions, and the package makes the cheapest option the easiest one to reach for.

Getting started, and the counter app in full

The install is one command and the imports are two lines:

flutter pub add flex_color_scheme

import 'package:flex_color_scheme/flex_color_scheme.dart';
import 'package:material_ui/material_ui.dart';

The example the README walks through is the default Flutter counter app, themed with the Oh Mandy red, FlexScheme.mandyRed, and the point of it is that the light and dark variants come from the same scheme with one call each:

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: FlexThemeData.light(scheme: FlexScheme.mandyRed),
      darkTheme: FlexThemeData.dark(scheme: FlexScheme.mandyRed),
      themeMode: ThemeMode.system,
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

ThemeMode.system is what makes the light and dark pair matter, since the app follows the device setting and the two themes have to be designed together rather than one being an afterthought. The requirement is Flutter 3.47 or later, and the package is on pub.dev with a BSD 3-Clause licence.

What it does not do, and what it costs

The scope is theming, and it is worth being clear that this is not a component library and not a design system. It produces ThemeData and it does not produce the widgets that use it, so the visual result depends on the components you put in it. The second limit is the dependency on the new SDK-decoupled packages, which is a one-time migration cost for a project on an older Flutter and a standing constraint afterwards, since the package will keep raising the floor as it adopts new features from material_ui and cupertino_ui. The third is the size of the API, which is the trade the package makes deliberately, since the feature list is long and the docs are correspondingly long, and a project that only needs a seed colour and a radius would be better served by the SDK factory. The honest summary is that this is a package for a team that has a brand and cares how the app looks, and it is wasted on a team that has neither.

Editorial conclusion

FlexColorScheme is worth adopting if your app has a brand and you want light and dark versions of it that look designed rather than generated, because the surface blends and the tone mapping are the parts the SDK factory does not give you, and the playground removes the usual problem of tuning a theme through code. It is the wrong choice if your app uses the platform default look, since the package's whole value is the deviation from the default, and it is a poor fit if you cannot move to Flutter 3.47, because the 9.x line requires the SDK-decoupled material_ui and cupertino_ui packages. Before you upgrade, read the changelog, because version 9.0 carries breaking API and seed-tone details, and keep your direct material_ui import, since the package does not replace it and your app still needs it for MaterialApp and the widgets.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. rydmike/flex_color_scheme on GitHub