FlexColorScheme

FlexColorScheme is a Flutter package used to create beautiful, color-scheme-based themes. While Flutter's standard ThemeData.from(ColorScheme) is the baseline, it often leaves gaps where the color scheme is not consistently applied to all standard Material UI widgets.

FlexColorScheme addresses these inconsistencies and provides opinionated theme modifications to ensure a more cohesive look. It is designed to work with both light and dark ColorScheme modes and is used in the Flexfold web demo to enable effortless theme switching.

FlexColorScheme provides 34 ready-made light and dark color scheme pairs. These include Flutter and Material 2 Design Guide examples, as well as high-contrast versions like Amber blue.

Built-in Schemes:

• Tuned light and dark pairs.
• Available as const values, allowing you to use them as a starting point for custom schemes.
• If you only use your own custom schemes and do not reference the built-in ones, the built-in definitions will not be included in your application's compiled release.

Custom Schemes:

• You can create custom schemes from scratch.
• You can reuse colors from existing schemes using their const FlexColor names.
• You can create a custom list of schemes to provide users with specific theme options, or append built-in schemes to your custom list.

The tabBarStyle property determines the TabBarTheme applied to your application. Choosing the right style depends on where your TabBar is located:

• FlexTabBarStyle.forAppBar: Designed to fit inside an AppBar. This is the default.
• Other styles: Designed to fit well on background colors, making them suitable for TabBar widgets placed in a Scaffold body, Dialog, or Drawer.

If you use TabBar in both AppBars and on surfaces, you may need to theme them separately or choose a style that works for both.

When using the true black option for dark mode, FlexColorScheme sets surface, background, and scaffoldBackground to fully black (#000000).

Key considerations:

• OLED Power Saving: Can save power on OLED screens by turning pixels off.
• Scrolling Artefacts: Rapidly turning pixels on and off during scrolling can cause visual artefacts (as noted in the Material Design guide).
• Branding Impact: If you use branded surfaces with true black enabled, branding has a lower impact. Only strong or heavy branding levels will be visible. To achieve complete black for all surfaces, avoid combining true black mode with branded surfaces.

Even if you define your own custom color schemes, FlexColorScheme provides several core benefits:

• Widget Consistency: Fixes inconsistencies in Flutter's standard ThemeData to ensure all SDK widgets (including deprecated ones) use the specified color scheme correctly.
• Branded Surfaces: Easy creation of themes with primary-color branded and blended backgrounds/surfaces with adjustable blend levels.
• AppBar Styles: Quick toggling of AppBar styles that automatically match the TabBar.
• True Black Mode: Optional support for true black in dark themes.
• Color Swapping: Ability to quickly swap primary and secondary color definitions.
• System UI: Theming the Android System navigation bar to match the app theme (including transparency).
• Material 3 Support: Provides an opt-in way to get refined, opinionated sub-themes inspired by the Material 3 guide.

The appBarStyle property allows you to choose how the AppBar background is colored. This is independent of the standard ColorScheme.primary behavior.

Use the FlexAppBarStyle enum to select from:

• FlexAppBarStyle.primary: Uses the scheme's primary color.
• FlexAppBarStyle.custom: Uses a custom color defined in the scheme's appBarColor property (often mapped from secondaryVariant).
• Other variants that allow matching the AppBar to branded surfaces or background colors.

You can also control the appBarElevation directly via the FlexColorScheme factory.

When defining themes, you can control the visualDensity of your widgets. FlexColorScheme provides a helper called FlexColorScheme.comfortablePlatformDensity which is an alternative to Flutter's standard VisualDensity.adaptivePlatformDensity.

• FlexColorScheme.comfortablePlatformDensity: On desktop and web, it uses comfortable density (providing more white space/touch-friendly area). On mobile devices, it defaults to the standard density.
• VisualDensity.adaptivePlatformDensity: The standard Flutter approach that uses compact density on desktop/web.
• No specification: If you do not specify a density, Flutter uses standard density on all platforms, which may result in excessive white space on desktop/web.

When implementing setters in the ThemeController, follow these rules for null handling:

• Non-nullable properties: Add a null check in the setter to prevent errors.
  • Pattern: if (value == null) return;
• Nullable properties: Do not add a null check; null is a valid value representing the default state.
• Nullable with M2/M3 meaning: Default to null to allow the system to use mode-specific defaults.
• Nullable with global cascade: If a property follows a global default, show that global value in the UI label (e.g., "global 12 dp").

When building custom reusable widgets, do not hardcode constant color values (e.g., Colors.blue). Instead, use the colors provided by the application's inherited theme.

Why: By using the theme's color properties (e.g., Theme.of(context).colorScheme.primary), your custom widgets will automatically adapt whenever the application theme changes (such as switching from light to dark mode or changing the active color scheme).

The useFlutterDefaults property in FlexSubThemesData (introduced in v5.0.0-dev.1) allows you to toggle between harmonized FlexColorScheme sub-theme settings and the standard Flutter SDK defaults.

• false (Default): Uses FlexColorScheme's recommended, harmonized settings for components like BottomNavigationBar, NavigationBar, and NavigationRail.
• true: Reverts to the standard, un-harmonized Flutter SDK defaults. This is useful if you want to build custom component themes starting from less opinionated SDK defaults.

FlexSubThemesData(
  useFlutterDefaults: true,
)