Version 6.1.2

6.1.2

Dec 26, 2022

FIX

• Fix for issue #106 bottomSheetModalBackgroundColor not correctly set. Thanks mcssym for the fix PR #107.

Version 6.1.1

6.1.1

Nov 22, 2022

FIX

• Themes Playground (Example 5): Fixed scroll issue in page view mode on Web builds. Only examples related, no package impact.
• API doc updates.

Version 6.1.0

6.1.0

Nov 20, 2022

FlexColorScheme version 6.1.0 contains many new features, more component sub-themes and configurable properties. It improves seed-generated color scheme capabilities by adding more pre-configured seed generation configurations and color contrast accessibility options.

A criticism of Material 3's color system and seed-generated color schemes, is that using colored contrasting colors may be less accessible. FlexColorScheme offers a way to enable in-app modification of its seed-generated color schemes, any seed generation configuration can optionally return results with plain white and black contrasting on colors. This can be applied separately for main on colors and on surfaces.

The Themes Playground application, has been updated to include most of the new features. It has been improved to make it easier to discover some of its previously existing features, like using custom colors in the Playground to define your own theme.

NEW

• Scaffold background color can now be used as the themed AppBar background color. The enum FlexAppBarStyle that is used by property appBarStyle got a new value scaffoldBackground that enables this. This is useful for matching the AppBar color exactly to the Scaffold background color, when Scaffold background uses different surface blends than the theme's ColorScheme surface or background colors.
• Added properties materialTapTargetSize and pageTransitionsTheme to FlexColorScheme and FlexThemeData. They are only convenience properties to avoid having to use a copyWith on FlexColorScheme produced ThemeData, to define them.
• Property swapLegacyOnMaterial3 in FlexColorScheme.light/dark and FlexThemeData.light/dark allows for better automatic adjustment of built-in scheme colors to the Material 3 color-system. It applies to color schemes that were originally designed for Material 2, when using the Material 3 mode with or without seed-generated ColorSchemes.
  • Setting swapLegacyOnMaterial3 to true, will when useMaterial3 is true, swap the built-in scheme colors secondary and tertiary and also their container colors.
  • This only happens for built-in schemes where this swap makes the color design more compatible with the intended design and usage of the secondary and tertiary colors in Material 3 color system.
  • To implement this, the class FlexSchemeColor has a new boolean meta-data property called swapOnMaterial3, that has been defined to be true, if the FlexSchemeColor it defines, benefits design compliance wise from swapping its secondary and tertiary colors when using Material 3.
  • For backwards compatibility the swapLegacyOnMaterial3 is false by default, but it is recommended to always set it to true. The flag has no impact when using Material 2.
  • The swapLegacyOnMaterial3 flag can also be toggled in the Themes Playground, it is on by default there.
  • When the swap is done for a FlexSchemeColor, it is done before any other built-in scheme modifier properties, including swapColor and usedColors.
• The FloatingActionButton can now be set to always be circular, also in Material 3 and without assigning a high-radius setting. If you always want a circular FAB, and stadium on extended FAB, then set fabAlwaysCircular in FlexSubThemesData to true, and FAB stays circular regardless of if you use M2 or M3, or how you modify the global default border radius. You could get this effect before too by setting a very high themed radius on the FAB, but this is more convenient.
• Additional new FlexSubThemesData properties:
  • Slider theme can now be adjusted via FlexSubThemesData properties sliderBaseSchemeColor, sliderValueTinted and sliderTrackHeight.
  • The chipSelectedSchemeColor was added as themed background color, it is used by Chips that are selectable. The chipDeleteIconSchemeColor can be used to theme the "Delete" icon color on Chips. While adding these features, some Flutter M3 Chip spec and theming issues were found, see issue #115364 for more information.
  • Switch got a switchThumbSchemeColor property, to control the thumb color separately. A switch custom color theme was prepared for M3 Switch, which is not yet available in Flutter 3.3.
  • Tooltip theme now has FlexSubThemesData properties tooltipRadius, tooltipWaitDuration, tooltipShowDuration, tooltipSchemeColor and tooltipSchemeColor.
  • The bottomSheetBackgroundColor and bottomSheetModalBackgroundColor can be used to theme the background color of the BottomSheet.
  • Use navigationBarElevation to adjust the themed elevation of NavigationBar.
  • Use popupMenuElevation and popupMenuSchemeColor to further quick theme the PopupMenuButton.
  • The outlinedButtonBorderWidth, outlinedButtonPressedBorderWidth, toggleButtonsBorderWidth, inputDecoratorBorderWidth and inputDecoratorFocusedBorderWidth define the themed outline border thickness in different states of their respective components. These properties use previously existing properties thinBorderWidth and thickBorderWidth as their defaults. Resulting in that, the new properties are API backwards compatible, and they have shared global default settings. The new part is that you can now define themed outline border thickness separately for these components.
  • The elevatedButtonTextStyle, outlinedButtonTextStyle and textButtonTextStyle were added to be able to theme TextStyle on ElevatedButton, OutlinedButton, TextButton. These are convenience properties to allow different text styles on buttons without having to use copyWith on the overall ThemeData and its button component themes to modify the text styles, often sizes.
    • These properties do not offer any simplification over standard ThemeData and its button themes. The current version does not include adjusting them in the Themes Playground. Adding all possible usage of them is currently not in the scope of the Playground app. However, button font size changes may be added later as a usage example of these properties. These properties are using the tricky MaterialStateProperty, that have so far been avoided in this flattened simplified theming. It was used for the benefit of offering the text styles as ThemeData pass along properties. Modifying the ButtonStyle theme using copyWith, is a bit more involved than for other sub themes, with these properties you can customize the button text style using FlexSubThemesData properties instead. If you need to modify the FlexColorScheme created buttons themes even further for some not included properties, an example of how to do that can be found here.

CHANGE

• FlexColorScheme now uses FlexSeedScheme version 1.1. It includes the following new features and changes:
  • Features that enabled implementation of just black and white seeded on colors.
  • Additional FlexTones, the FlexTones.oneHue and FlexTones.vividBackground.
  • See FlexSeedScheme on pub.dev for more information.
• In FlexSubThemesData all component controlling properties except booleans, are now nullable and null by default. FlexColorScheme made sub themes still default to same values as before when assigning a default FlexSubThemesData() to FlexColorScheme.subThemesData. The properties are nullable to enable using different defaults in FlexColorScheme made sub-themes for Material 2 and Material 3 modes.
• Style breaking: Changed component themes thinBorderWidth to default to 1.0. It was 1.5 before. This is a style breaking change from previous thin outline style in FlexColorScheme.
  • Using fractional values may cause artefacts on monitors using native resolution where 1 dp = 1 physical display pixel (common on desktop PC/Linux monitors). We see the new default as a design FIX to avoid such issues with default settings. You can still set thinBorderWidth to 1.5, to get the same result as previous default theme.
• Style breaking: When opting in on opinionated sub-themes, the Chip style is slightly modified from previous versions. The new opinionated FCS default style is more distinct than before and more aligned with styling borrowed from the Material 3 mode Chip design. The deleteIconnColor now defaults to onSurface instead of primary and it can be defined to be any color scheme based color. The Chips revised style, look better than before. Using Material 3 and with it themed Chips is also fully supported, also customizing color on selected state of selectable Chips is available. Color-tinted chips are also available as before. Be aware though that Material 3 theming in the current 3.3 version of Flutter has some limitations. If you assign a custom color to selected chips, the disabled state of Chips can no longer conform, to M3 spec of disabled selected Chips.
  • For more information, see issue #115364. Note that if you deviate on Chips from its expected designed background brightness, which is now possible to do for selected Chips with the new theming capabilities in the Playground. There is no way via theming to set correct text and icon contrasting brightness for selected Chips that require dark text and icons on bright Chips in dark theme mode. Wise versa for light theme mode, setting light text on dark selected Chips in light mode, is also not possible. This limitation applies to selected FilterChip and InputeChip, there is simple not enough theme properties in ChipTheme to support this. Due to this limitation, we recommend only using Chip theme designs that work with dark text in light mode, and light text in dark mode.
• Style breaking: Wh...

Version 6.0.1

6.0.1

Sep 21, 2022

FIX

• A null check was fixed by sososdk in FlexColorScheme.light when using custom scheme PR #90. Issue did not exist in FlexColorScheme.dark.

• Cam16 from Material Color Utilities was exported by accident by FlexColorScheme in version 6.0.0 via its FlexSeedScheme package export. This export was removed. Cam16 was not exported before moving features to FlexSeedScheme and should not have been now either. FlexSeedScheme does however export it as before, it is used by the FlexColorPicker.

Version 6.0.0

6.0.0

Aug 31, 2022

• Updated minimum dependencies to Dart >=2.18.0 and Flutter >= 3.3.0.

Due to a number of known and below documented Flutter SDK issues when using useMaterial3 set to
true, we cannot yet recommend using the option in production. Use it only if you are willing to
accept the still incomplete Material 3 implementation in Flutter and the issues. If you
keep useMaterial3 set to false, and use FCS opinionated component themes, you can create a
theme that is visually fairly similar to M3, but still using M2 ThemeData mode to avoid many
issues.

BREAKING

• This FlexColorScheme version no longer directly depends on package Material Color Utilities package, which is also used by Flutter SDK. Instead, it uses package
  FlexSeedScheme that depends on it. As a part of this change classes FlexTones, FlexTonalPalette and FlexCorePalette where moved into the package FlexSeedScheme. FlexColorScheme still exports these classes. If you were using them directly before, you can still do so without adding the FlexSeedScheme package.

• In FlexSeedScheme, FlexTones contains a minor breaking change to make the API cleaner. The FlexTones.light and FlexTones.dark no longer produce the config for the Material 3 tone and chroma setup. They no longer lock the chroma values to the default values for M3, but use null in their configs for their chroma values. Resulting in that chroma from key colors will be used, as long as they are over set minimum values. These named constructors then provide a cleaner starting API for defining additional configurations, by not forcing null to be passed to use chroma value in key colors. To get the Material 3 configuration, use the factory FlexTones.material instead of FlexTones.light and FlexTones.light. It as before produces the correct Material 3 configuration, by defining secondaryChroma: 16 and tertiaryChroma: 24 using FlexTones.light and FlexTones.dark to return the correct Material 3 matching FlexTones configuration as before. This change was introduced to prepare for extracting FlexTones and FlexSeedScheme to their own package that will provide a fromFlexSeeds extension on ColorScheme. It is unlikely to impact any normal usage of FlexColorScheme, but it is still a breaking change.

• In FlexSeedScheme FlexCorePalette.fromSeeds properties secondaryChroma and tertiaryChroma now default to null instead of previous M3 palette default generating values 16 and 24 respectively. Set them to values 16 and 24 to create same tonal palettes as Material Color Utilities CorePalette and previous versions of FlexCorePalette.

• To allow for greater flexibility and addition of tonal palette tones 5 (custom for FCS) and 98 (Google Material 3 Web theme builder app includes tone 98 to, but not Flutter SDK), FlexCorePalette no longer extends CorePalette, it is a modified re-implementation.

• In FlexSeedScheme the FlexTonalPalette method asList and constructor fromList, now include the values of the error color in produced asList, and as required values in fromList.

NEW

• In FlexSeedScheme, added customization possibility of error tonal palette to the default FlexTonalPalette constructor.

• In FlexSeedScheme, added two new FlexTones:

  1. FlexTones.ultraContrast with even more contrast that highContrast.
  2. FlexTones.jolly for a seeded ColorScheme with more poppy and jolly seed colors.

• In FlexSeedScheme, added SeedColorScheme.fromSeeds(...) that can be used to create a seeded ColorScheme using multiple seed colors and FlexTones configuration.

• In FlexSeedScheme, added FlexTonalPalette a re-implementation of Material Color Utilities TonalPalette, with addition of tonal palette tones 5 and 98. The tone 98 also exists in the Web Material Theme Builder app, but not in Flutter or Material Color Utilities package. Tone 5 is custom addition for FlexTones and FlexColorScheme.

• Added appBarCenterTitle property to FlexSubThemesData configuration. It works the same way as centerTitle in AppBar and its theme. The property is not available in the Themes Playground app, only via the API. We recommend keeping it null to use platform
  adaptive default behavior, but offer it as convenience property for those that like to use same centering style regardless of used platform.

• Added two new properties to FlexSubThemes.elevatedButtonTheme.

  • Boolean useMaterial3, defaults to false.
  • onBaseSchemeColor, defaults to null SchemeColor?.

  When useMaterial3 is false, the elevatedButtonTheme.baseSchemeColor is used as background color as before, and the new property elevatedButtonTheme.onBaseSchemeColor is used as foreground color. However, when useMaterial3 is true, their foreground and background color roles are reversed, and baseSchemeColor becomes its foreground color and the onBaseSchemeColor its background color.

• Added elevatedButtonSecondarySchemeColor property of type SchemeColor? to FlexSubThemesData. Use it to control secondary color of the ElevatedButton in its sub-themes. FCS applies this color to FlexSubThemes.elevatedButtonTheme.onBaseSchemeColor. If useMaterial3 is false, it is the foreground color. If useMaterial3 is true, it is the background color. Material 3 and 2 have a completely different default elevated button styles. The Material 2 elevated button is color wise, like the M3 filled button, but with elevation.

• Added two new properties to FlexSubThemes.outlinedButtonTheme.

  • Boolean useMaterial3, defaults to false.
  • outlineSchemeColor, defaults to null SchemeColor?.
    When useMaterial3 is false, the outlineSchemeColor defaults to baseSchemeColor.
    When useMaterial3 is true, the outlineSchemeColor defaults to SchemeColor.outline.

REMOVED EARLIER DEPRECATED MEMBERS

As a chore and clean up all previously deprecated members have been removed from version 6.0.0. It no longer has any self deprecated members. This removes a lot legacy backwards compatibility with deprecated members from versions 2, 3 and 4, and even one from version 5.1.0. Removed all earlier self deprecated members as follows:

• FlexSubThemesData:
  inputDecorationRadius, bottomNavigationBarSchemeColor, navigationBarIsStyled, navigationBarTextSchemeColor, navigationBarMutedUnselectedText, navigationBarIconSchemeColor, navigationBarHighlightSchemeColor.
• FlexColorScheme:
  primaryVariant, secondaryVariant, useSubThemes. Removed static FlexColorScheme.m3TextTheme deprecated in 5.1.0 and static FlexColorScheme.themedSystemNavigationBar in version 2 its deprecated parameter nullContextBackground.
• FlexThemeData:
  primaryVariant, secondaryVariant, useSubThemes.
• FlexSchemeColor:
  primaryVariant, secondaryVariant.
• SchemeColor:
  primaryVariant, secondaryVariant.
• FlexConstants:
  kDarkenSecondaryVariant, kDarkenSecondaryVariantFromSecondary, kDarkenPrimaryVariant.
• FlexSubThemes.bottomNavigationBar:
  baseSchemeColor.
• FlexSubThemes.navigationBarTheme:
  textSchemeColor, unselectedTextSchemeColor, mutedUnselectedText, iconSchemeColor, highlightSchemeColor.

STYLE CHANGE - BREAKING

• FlexSubThemesData.fabUseShape opinionated component theme style default was changed from true to false, this breaks previous default style. The opinionated style change was done to use a style that by default matches M3 style when ThemeData.useMaterial3 is true. The new default style is also a way to work around issue #107946, where it is shown that you cannot create a theme that replicates the default roundings in M3 of the FAB.
  Style migration: If you had kept FlexSubThemesData.fabUseShape unspecified and relied on default value in a previous version, you must set it to true to get the same result as before. Breaking style changes like this, in the opinionated opt in component sub-themes are unfortunate. However, required as FlexColorScheme continues to evolve with Flutter SDK to support Material 3 theming, while offering its own opinionated tweaks on some M3 default styles as well.

STYLE CHANGE - MINOR

• The M3 color utilities package material_color_utilities from the Material team, that Flutter SDK depends on and FCS also uses, introduced a minor breaking change going from version 0.1.4 to 0.1.5. Some colors in the tonal palettes no longer give exactly the same color values as before. This changes the results for some colors when you create a ColorScheme.fromSeed or FCS does it internally with its extended version SeedColorScheme.fromSeeds. The new algorithm changes for example all the default M3 error colors slightly. The changes in the color values are minor, and not visually noticeable to the eye. Values are however slightly different, and this release uses the new value for FCS M3 error colors. Tests were also updated to use the new values. The change did break FCS color value tests, and should be per its own policy be considered a major breaking change. However, since the Material 3 design and material_color_utilities calls this change minor, then so does FCS.

• The opt-in opinionated tinted text themes were made less aggressive on the tint, and received a bit of opacity for styles that in 2014/2018/2021 styles have opacity. The custom styles uses significantly less opacity since they already also get alpha blended tint color applied. Combining it with same level of opacity would make them too low contrast.

• Style fix, the ...

Version 6.0.0-dev.1

6.0.0-dev.1

Aug 28, 2022

This dev release is for Flutter beta 3.3.0-0.5.pre, it will be released when next Flutter stable version after 3.0 comes out, presumably version 3.3.

If you experiment with this dev release and want to use the Theme Playground, then please use the version 6 beta build, here. The doc site does not yet contain any information about version 6, it will be added after its stable release.

Due to a number of known and below documented Flutter SDK issues when using useMaterial3 set to true, we cannot yet recommend using the option in production. Use it only if you are willing to accept the still incomplete Material 3 implementation in Flutter and the issues. If you keep useMaterial3 set to false, and use FCS opinionated component themes, you can create a theme that is visually fairly similar to M3, but still using M2 ThemeData mode to avoid many issues.

BREAKING

• This FlexColorScheme version no longer directly depends on package Material Color Utilities package, which is also used by Flutter SDK. Instead, it uses package
  FlexSeedScheme that depends on it. As a part of this change classes FlexTones, FlexTonalPalette and FlexCorePalette where moved into the package FlexSeedScheme. FlexColorScheme still exports these classes. If you were using them directly before, you can still do so without adding the FlexSeedScheme package.

• In FlexSeedScheme, FlexTones contains a minor breaking change to make the API cleaner. The FlexTones.light and FlexTones.dark no longer produce the config for the Material 3 tone and chroma setup. They no longer lock the chroma values to the default values for M3, but use null in their configs for their chroma values. Resulting in that chroma from key colors will be used, as long as they are over set minimum values. These named constructors then provide a cleaner starting API for defining additional configurations, by not forcing null to be passed to use chroma value in key colors. To get the Material 3 configuration, use the factory FlexTones.material instead of FlexTones.light and FlexTones.light. It as before produces the correct Material 3 configuration, by defining secondaryChroma: 16 and tertiaryChroma: 24 using FlexTones.light and FlexTones.dark to return the correct Material 3 matching FlexTones configuration as before. This change was introduced to prepare for extracting FlexTones and FlexSeedScheme to their own package that will provide a fromFlexSeeds extension on ColorScheme. It is unlikely to impact any normal usage of FlexColorScheme, but it is still a breaking change.

• In FlexSeedScheme FlexCorePalette.fromSeeds properties secondaryChroma and tertiaryChroma now default to null instead of previous M3 palette default generating values 16 and 24 respectively. Set them to values 16 and 24 to create same tonal palettes as Material Color Utilities CorePalette and previous versions of FlexCorePalette.

• To allow for greater flexibility and addition of tonal palette tones 5 (custom for FCS) and 98 (Google Material 3 Web theme builder app includes tone 98 to, but not Flutter SDK), FlexCorePalette no longer extends CorePalette, it is a modified re-implementation.

• In FlexSeedScheme the FlexTonalPalette method asList and constructor fromList, now include the values of the error color in produced asList, and as required values in fromList.

NEW

• In FlexSeedScheme, added customization possibility of error tonal palette to the default FlexTonalPalette constructor.

• In FlexSeedScheme, added two new FlexTones:

  1. FlexTones.ultraContrast with even more contrast that highContrast.
  2. FlexTones.jolly for a seeded ColorScheme with more poppy and jolly seed colors.

• In FlexSeedScheme, added SeedColorScheme.fromSeeds(...) that can be used to create a seeded ColorScheme using multiple seed colors and FlexTones configuration.

• In FlexSeedScheme, added FlexTonalPalette a re-implementation of Material Color Utilities TonalPalette, with addition of tonal palette tones 5 and 98. The tone 98 also exists in the Web Material Theme Builder app, but not in Flutter or Material Color Utilities package. Tone 5 is custom addition for FlexTones and FlexColorScheme.

• Added appBarCenterTitle property to FlexSubThemesData configuration. It works the same way as centerTitle in AppBar and its theme. The property is not available in the Themes Playground app, only via the API. We recommend keeping it null to use platform
  adaptive default behavior, but offer it as convenience property for those that like to use same centering style regardless of used platform.

• Added two new properties to FlexSubThemes.elevatedButtonTheme.

  • Boolean useMaterial3, defaults to false.
  • onBaseSchemeColor, defaults to null SchemeColor?.

  When useMaterial3 is false, the elevatedButtonTheme.baseSchemeColor is used as background color as before, and the new property elevatedButtonTheme.onBaseSchemeColor is used as foreground color. However, when useMaterial3 is true, their foreground and background color roles are reversed, and baseSchemeColor becomes its foreground color and the onBaseSchemeColor its background color.

• Added elevatedButtonSecondarySchemeColor property of type SchemeColor? to FlexSubThemesData. Use it to control secondary color of the ElevatedButton in its sub-themes. FCS applies this color to FlexSubThemes.elevatedButtonTheme.onBaseSchemeColor. If useMaterial3 is false, it is the foreground color. If useMaterial3 is true, it is the background color. Material 3 and 2 have a completely different default elevated button styles. The Material 2 elevated button is color wise, like the M3 filled button, but with elevation.

• Added two new properties to FlexSubThemes.outlinedButtonTheme.

  • Boolean useMaterial3, defaults to false.
  • outlineSchemeColor, defaults to null SchemeColor?.
    When useMaterial3 is false, the outlineSchemeColor defaults to baseSchemeColor.
    When useMaterial3 is true, the outlineSchemeColor defaults to SchemeColor.outline.

REMOVED EARLIER DEPRECATED MEMBERS

As a chore and clean up all previously deprecated members have been removed from version 6.0.0. It no longer has any self deprecated members. This removes a lot legacy backwards compatibility with deprecated members from versions 2, 3 and 4, and even one from version 5.1.0. Removed all earlier self deprecated members as follows:

• FlexSubThemesData:
  inputDecorationRadius, bottomNavigationBarSchemeColor, navigationBarIsStyled, navigationBarTextSchemeColor, navigationBarMutedUnselectedText, navigationBarIconSchemeColor, navigationBarHighlightSchemeColor.
• FlexColorScheme:
  primaryVariant, secondaryVariant, useSubThemes. Removed static FlexColorScheme.m3TextTheme deprecated in 5.1.0 and static FlexColorScheme.themedSystemNavigationBar in version 2 its deprecated parameter nullContextBackground.
• FlexThemeData:
  primaryVariant, secondaryVariant, useSubThemes.
• FlexSchemeColor:
  primaryVariant, secondaryVariant.
• SchemeColor:
  primaryVariant, secondaryVariant.
• FlexConstants:
  kDarkenSecondaryVariant, kDarkenSecondaryVariantFromSecondary, kDarkenPrimaryVariant.
• FlexSubThemes.bottomNavigationBar:
  baseSchemeColor.
• FlexSubThemes.navigationBarTheme:
  textSchemeColor, unselectedTextSchemeColor, mutedUnselectedText, iconSchemeColor, highlightSchemeColor.

STYLE CHANGE - BREAKING

• FlexSubThemesData.fabUseShape opinionated component theme style default was changed from true to false, this breaks previous default style. The opinionated style change was done to use a style that by default matches M3 style when ThemeData.useMaterial3 is true. The new default style is also a way to work around issue #107946, where it is shown that you cannot create a theme that replicates the default roundings in M3 of the FAB.
  Style migration: If you had kept FlexSubThemesData.fabUseShape unspecified and relied on default value in a previous version, you must set it to true to get the same result as before. Breaking style changes like this, in the opinionated opt in component sub-themes are unfortunate. However, required as FlexColorScheme continues to evolve with Flutter SDK to support Material 3 theming, while offering its own opinionated tweaks on some M3 default styles as well.

STYLE CHANGE - MINOR

• The M3 color utilities package material_color_utilities from the Material team, that Flutter SDK depends on and FCS also uses, introduced a minor breaking change going from version 0.1.4 to 0.1.5. Some colors in the tonal palettes no longer give exactly the same color values as before. This changes the results for some colors when you create a ColorScheme.fromSeed or FCS does it internally with its extended version SeedColorScheme.fromSeeds. The new algorithm changes for example all the default M3 error colors slightly. The changes in the color values are minor, and not visually noticeable to the eye. Values are however slightly different, and this release uses the new value for FCS M3 error colors. Tests were also updated to use the new values. The change did break FCS color value tests, and should be per its own policy be considered a major breaking change. However, since the Material 3 design and material_color_utilities calls this change minor, then so does ...

Version 5.1.0

v5.1.0 - July 8, 2022

• Updated to support Flutter 3.0.0, Dart 2.17 and latest Flutter package dependencies in example apps. Requires at least Flutter 3.0.0 and Dart 2.17.0.

NEW

• Added full support for in Flutter 3.0.0 new ColorScheme.surfaceTint color. It is set to ColorScheme.primary color by default, as Flutter and Material 3 does. If a custom surfaceTint color is provided, it is also used as the blend color, instead of primary color, for
  FlexColorScheme's surface blend feature.

• Added API for using Flutter 3.0.0 theme extensions directly via FlexColorScheme API. It was added as a convenience feature in order to avoid having to add theme extensions with a copyWith on FlexColorScheme produced ThemeData. With the FlexColorScheme.extensions and FlexThemeData.extensions properties you can add custom theme extensions directly.

DEPRECATED

• Deprecated: FlexColorScheme.m3TextTheme. The custom M3 text theme is no longer needed after Flutter 3.0.0 release that includes the new M3 Typography in addition to its earlier released TextTheme. You can opt in on using the new M3 style TextTheme as before by setting FlexColorScheme.subThemesData.useTextTheme to true or by setting FlexColorScheme.useMaterial3 to true. Using either does however come with known issue #103864, where dynamically switching Typography, e.g. from 2014 or 2018, to M3 2021 Typography, triggers the mentioned assert in issue
  #103864. This issue has always existed in Flutter SDK ThemeData when dynamically changing between different Typography. Before FlexColorScheme avoided triggering this issue by only using Typography 2018, also when
  opting in on M3 TextTheme, that before used 2018 based Typography to make a custom M3 like TextTheme. Avoiding this issue is no longer possible when opting in on M3, that now correctly uses its own and different Typography from M2. This exposes this issue if you dynamically change ThemeData from one to another Typography. To avoid this Flutter SDK issue, use the same Typography for all your themes in your app and don't dynamically switch theme between ThemeData objects that uses different Typography in your application. The use cases for doing this are few, but it is still a Flutter SDK limitation to be aware about.

• Deprecated: FlexSubThemes.buttonTheme that creates an opinionated ButtonThemeData. The ButtonThemeData is marked as obsolete in Flutter SDK, but not yet deprecated in Flutter version 3.0.0. FlexColorscheme now marks it as deprecated. It will be removed in a future FlexColorScheme release when Flutter SDK deprecates ButtonThemeData.

M3 STYLE FIXES AND CHANGES

• FAB M3 defaults change: Floating Action Button background color, will when opting in on ThemeData.useMaterail3, use color theme.colorScheme.primaryContainer, otherwise theme.colorScheme.secondary is used.

• Input Decorator default change: The TextField and its InputDecorator border radius default value was changed from 20dp to 16 dp when using opinionated component themes. If opting in on Material 3, the default value for M3 design is used, which is only 4 dp. See specification https://m3.material.io/components/text-fields/specs. Flutter 3.0.x does not yet implement the new M3 TextField style, but via this change when opting in on M3, FlexColorScheme offers an early approximation of it.

• NavigationBar M3 defaults change: Default colors of NavigationBar when opting in on useMaterial3 and not using opinionated component themes will now match M3 default colors. The background color will follow M3 style also by default when component themes are enabled and useMaterial3 is true. This style is difficult to replicate with a single color otherwise. The difference is subtle for FCS surface tinted background colors. You can still set it to background color to replicate past FCS default color when sub-themes were enabled. For other properties, if opinionated component themes are not used, FCS will use default M3 theme styles on NavigationBar when useMaterial3 is true. If opting in on opinionated component themes, FCS uses its own custom opinionated default style. Which can be modified to be the same as default M3 style too, just as before. The change also includes a default font size change for FCS opinionated styled navigation bar, from 11dp to 12dp. This change was done to harmonize it with its M3 style.

• NavigationRail M3 defaults change: Default colors of NavigationRail when opting in on useMaterial3 and not using opinionated component themes will now match M3 default colors. If opinionated component themes are not used, FCS will use default M3 theme styles on NavigationRail when useMaterial3 is true. If opting in on opinionated component themes, FCS uses its own custom opinionated default style. Which can be modified to be the same as default M3 style too, just as before. The change also includes a default font size change for FCS opinionated styled rail, from 14dp to 12dp. This change was done to harmonize it with its M3 style.

• Toggleable M3 style change: Default color of toggles (Switch, CheckBox and Radio) are now using primary color as default themed color when opting in on opinionated component themes or setting ThemeData.useMaterail3 to true. The Switch, CheckBox and Radio themes then use a style that match the M3 color design intent. In it, switches and toggles are mostly primary color based. In M3 color design, the secondary color is a poor choice for switches and toggles, and it is therefore not used as their default color. It does not look nice with M3 based ColorSchemes, created e.g. using M3 color seeding. If you use a custom M3 color design, where secondary color is still prominent, you can of course still use it.

• Fixed lint: "Avoid using private types in public APIs". See tweet discussion about why and when you might run into this lint being triggered by older Stateful Widgets. The lint warning was addressed in the package and examples.

EXAMPLE UPDATES

• Added a Theme Extensions example to the default example app, i.e. the "Hot Reload Playground".

• Themes Playground: Updated the default style info labels for Switch, CheckBox and Radio.

• Themes Playground: To the top row theme selector, where the FlexColorScheme and component themes switches are, added the "Use Material 3" toggle. Previously this toggle was only available on the introduction panel. The availability in the header makes it easy to toggle it ON and OFF at any time, to see what impact it has on widgets.

• Themes Playground: Updated the default style info labels for the NavigationBar. The logic to display default color labels in different config modes (M2/M3/FCS/FCS+M2/FCS+M3) is quite involved, please report any issues.

• Themes Playground: Updated the default style info labels for the NavigationRail. The logic to display default color labels in different config modes (M2/M3/FCS/FCS+M2/FCS+M3) is quite involved, please report any issues.

• Themes Playground: Due to issue #107190, the Playground previous default to use Material 3 was changed to false.

• Added support in Themes Playground to customize the surfaceTint color. It controls both the elevation color used for elevated Material surfaces in M3. Plus for FlexColorScheme it is also used as the surface blend color. By default, the surfaceTint color equals ColorScheme.primary color. Generally there are not many good design reasons to change the color, but it is now possible to do so. A good graphical designer can use it to create subtle difference from the standard surface elevation color branding effects. Used poorly, it mostly creates not so appealing visual and coloring results.

KNOWN FLUTTER SDK ISSUES

The issues below in the Flutter SDK itself, are known to impact FlexColorScheme and Flutter theming in general.

• Switching Typography dynamically in Flutter SDK ThemeData is broken, see issue #103864 for more information. If it is done and the error ignored, an app doing so eventually become unstable.

• The Themes Playground app contains a workaround to avoid issue #103864. The workaround is done by always using 2021 Typography, but simulating 2018 Typography. This is done by using a custom TextTheme that looks like 2018 Typography is used when using M2 theme mode. The Playground App actually always stays in 2021 Typography, but looks
  like it switches it. Which it does by applying a custom TextTheme in 2021 Typography, that looks like 2018 Typography is used. All other examples also avoid the issue by only using the M3 2021 Typography and not even mimicking a switch between M2 and M3 Typography. The above workaround is needed because the Playground app has toggles that switches Typography frequently, without the workaround it will eventually crash. With this workaround it never switches Typography, it just looks like it does, but app stays in 2021 Typography all the time. The by Themes Playground generated ThemeData config will use the actual real effective Typography. This is also fine, since an app using the theme will likely never switch used Typography. However, if it does, it will face the same issue the Playground app did. The issue is a Flutter SDK issue that FlexColorScheme cannot fix. Most likely 99% of apps will never run into this issue.

• In Flutter SDK 3.0.x, when opting in on useMaterial3:true, the Material widget and other SDK widgets built on it, gets no elevation when only the elevation property is defined. It is required to also ...

Version 5.0.1

v5.0.1 - April 29, 2022

FIX

• For the custom and temporary m3TextTheme: Fixed the Typography letterSpacing for bodyLarge to match corrected M3 spec that had wrong specification on the M3 website 0.15 -> 0.5. See Flutter SDK issue 102121.
• Themes Playground: Fix wrong color code copied to clipboard when tapping input color.
• Themes Playground: Make prettier default constructor for FlexSubThemesData() if that is all that was defined in Themes Playground config.

Version 5.0.0

v5.0.0 - April 21, 2022

The full journey from version 4.2.0 to stable 5.0.0 includes the steps in change logs for development versions 5.0.0-dev.3, -dev.2 and -dev.1.
Please refer to them for all details. This changelog contains a summary of breaking and other critical changes from version 4.2.0.

Overview

FlexColorScheme version 5 is style wise a big breaking change since all the built-in produced ColorSchemes the themes use have been revised to follow the new Flutter 2.10.0 Material 3 based ColorScheme. The color changes to the built-in schemes have been kept minimal compared to previous styles.

Mostly new color values were added to provide support for all the new colors in the Flutter Material 3 ColorScheme update, that landed in Flutter 2.10.0. The new colors are style aligned with past styles as far possible, while also keeping them inline with the Material 3 ColorScheme design intent.

As ColorScheme.primaryVariant and secondaryVariant have been deprecated in Flutter 2.10 SDK, so have they in FlexColorScheme. All past color constants for all color values and helper classes with the name "variant" in them, have been self deprecated in FlexColorScheme. The variant color values still exists, if you have used any of them directly, they still work. The old built-in variant color values will remain available at least until version 6.0, maybe even 7.0 if so requested by users.

Breaking

• Requires at least Flutter 2.10.0.

  • Version 5.0.0 requires at least Flutter version 2.10.0 to work. This breaking change is required since the new color properties in ColorScheme do not exist in any stable version of Flutter before version 2.10.

• surfaceStyle removed.

  • In version 5.0.0, the in version 4.2.0 deprecated property surfaceStyle, including all its implementing classes, enums, helpers and tests have been removed.
  • Removed property: surfaceStyle in FlexColorScheme.light and FlexSchemeData.light.
  • Removed property: surfaceStyle in FlexColorScheme.dark and FlexSchemeData.dark.
  • Removed: enum FlexSurface, that only surfaceStyle was using.
  • Removed: factory FlexSchemeSurfaceColors.from that was used to create surface using the surfaceStyle. The factory FlexSchemeSurfaceColors.blend replaced it in version 4.0.0 already, when using surfaceMode and blendLevel.
  • Migration: Use surfaceMode and blendLevel instead, it has more blend styles and finer granularity than the removed surfaceStyle.

theme: FlexThemeData.light(
  scheme: FlexScheme.flutterDash,
  surfaceMode: FlexSurfaceMode.highScaffoldLowSurface,
  blendLevel: 20,
),

• FlexSubThemesData.navigationBarIsStyled removed.

  • The property navigationBarIsStyled in FlexSubThemesData has been removed. If you have used it, it has a broader more general replacement called FlexSubThemesData.useFlutterDefaults.
  • Migration: Consider using useFlutterDefaults instead, or set styles manually using individual properties to desired styles matching Flutter defaults un-themed component designs.

• FlexColorScheme.useSubThemes no function

  • Deprecated property useSubThemes. This property has no function after 4.2.0 stable and 5.0.0-dev.1. Previously setting this property to true activated the default set and configuration of the optional opinionated component sub-themes, even if you did not pass any FlexSubThemesData() configuration data to subThemesData. Before when useSubThemes was true and no subThemesData defined, it created one internally using the default constructor FlexSubThemesData() and used it. It also ignored any defined and to subThemesData assigned one, if the flag was set to false.
  • The default component sub-themes are now instead always activated and created by explicitly assigning at least a default constructor FlexSubThemesData() to FlexColorScheme.subThemesData.
  • Removing this property makes the API more consistent. It follows the same design that is used for keyColors with FlexKeyColors and tones with FlexTones.
  • Migration: If you previously had only set FlexColorScheme.useSubThemes to true and not specified any subThemesData properties, you must now add the default constructor. Likewise, if you had set FlexColorScheme.useSubThemes to false, and had a FlexColorScheme.subThemesData defined, you must remove it disable using it. If you need to toggle it ON and OFF, use a bool to enabled/disable it, then pass in the FlexSubThemesData when enabled, and null when not using it.

Breaking and deprecated due to Flutter SDK change in 2.10.0 stable release.

• primaryVariant and secondaryVariant
  • The colors primaryVariant and secondaryVariant in FlexColorScheme are deprecated and can no longer be used to set colors values that result in any color values in Flutter SDK deprecated same named ColorScheme color properties.
  • The ColorScheme deprecated properties primaryVariant and secondaryVariant will always get their Flutter SDK default values,
    regardless of what input you give to them in FlexColorScheme. Flutter sets its deprecated primaryVariant equal to primary and secondaryVariant equal to secondary.
  • This means that if your application used those color scheme values on any custom widgets, their colors will change if you upgrade from a previous version of FlexColorScheme and don't do any other changes. You need to migrate to use primaryContainer, secondaryContainer, tertiary or tertiaryContainer color, as replacement colors in your custom widgets. The right choice depends on your color design.
  • If you use a FlexColorScheme setup made for a version before version 5.0, with version 5.0, and, if you have used custom color schemes where you defined theFlexColorScheme properties primaryVariant and secondaryVariant or defined and used them via custom FlexSchemeColors, in the colors property in FlexColorScheme. Then, in those cases the variant color properties will function as fallback input for color properties primaryContainer and secondaryContainer respectively, unless own color values for these properties are provided.
  • When you upgrade package version to 5.0.0 and have used custom color schemes, you will find your custom variant colors on the corresponding new container colors. Be aware that past variant color shades are not necessarily a great fit for a Material 3 design intent of container colors, but at least you will get your past custom colors used in the new theme by default.
  • Migration: Define new custom colors values for all container colors and tertiary color. Use them to make your custom FlexColorScheme instead. Then migrate away from using Flutter SDK ColorScheme colors primaryVariant and secondaryVariant anywhere in your application. Instead, use any of its new ColorScheme color properties as fitting with your design. This is something you have to do after Flutter 2.10, even if you are not using FlexColorScheme. Sure, not immediately, but eventually when the Flutter SDK ColorScheme colors primaryVariant and secondaryVariant are removed after a year or so.

Change and breaking past style.

• The custom "internal" and temporary m3TextTheme was changed. It is style breaking with 4.2.0 and 5.0.0-dev.1 & 2. It breaks past used style when opting in on component themes and its optional custom m3TextTheme enabled. The updated custom implementation of it now follows the implementation used in Flutter master channel, apart from this issue, where it for now implements the value used in the M3 Web guide. The changes in styles otherwise concern the addition of the font geometry height, which the previous custom implementation did not have. The usage of the custom m3TextTheme should be considered internal and temporary. It will be changed to use the actual Flutter implementation once PR #97829 lands in Flutter stable channel. The custom m3TextTheme will then be deprecated.

• The computed colors for ThemeData colors primaryColorLight, primaryColorDark and secondaryHeaderColor were changed.
  It is style breaking with 4.2.0 and 5.0.0-dev.1 & 2. The change breaks past used styles on these rarely used colors. These ThemeData colors are also on a deprecation path and will likely receive some new none MaterialColor dependent color defaults when that change happens. The new ColorScheme.primary computed colors for these rarely used colors are better balanced than before, and work well regardless of used ColorScheme.primary shade and tint.

• The color definition value for FlexColor.espressoLightPrimary color was changed. This is style breaking with 4.2.0 and 5.0.0-dev.1 & 2. The new color for FlexColor.espressoLightPrimary breaks past used color for this color constant. The color was changed from 0xFF220804 to 0xFF452F2B. Past color was too dark brown, almost black to be very usable in a UI. It was very black coffee like, but not very practical in a UI, it was too close to black. Since version 5 is anyway a major style breaking with the introduction of the new Material 3 ColorScheme, the opportunity to improve this color value used in the built-in theme espresso theme was used.

Beware

• SchemeColor values and order, potentially breaking. The enum SchemeColor has new values and past values are in a new order. The order was changed to accommodate all the new color values, and to keep them in the same order as their corresponding color properties in Flutter Material 3 ColorScheme color values. The change of order is potentially breaking, but highly unlikely to break anything in major ways in normal usage.

Version 5.0.0-dev.3

v5.0.0-dev.3 - April 20, 2022

Test release to verify builds and minor changes before stable release.

Documentation update

• The package documentation has now moved too its own site at docs.flexcolorscheme.com.

• It is a major update and rewrite of previous documentation. It also contains general Flutter theming guidance. One chapter is still work in progress. When it is completed, the stable v5.0.0 will be released.

Change: Custom "internal" and temporary m3TextTheme revised.

• Style breaking with 4.2.0 and 5.0.0-dev.1 & 2
• Breaks past used style when opting in on component themes and its optional custom m3TextTheme enabled. The updated custom implementation of it now follows the implementation used in Flutter master channel, apart from this issue, where it for now implements the value used in the M3 Web guide.
• The changes in styles otherwise concern the addition of the font geometry, height, which the previous custom implementation did not have. The usage of the custom m3TextTheme should be considered internal and temporary, it will be changed to use the actual Flutter implementation once PR #97829 lands in Flutter stable channel. The custom m3TextTheme will then be deprecated.

Change: Computed colors for ThemeData colors primaryColorLight, primaryColorDark and secondaryHeaderColor were changed.

• Style breaking with 4.2.0 and 5.0.0-dev.1 & 2, breaks past used styles on the rarely used colors primaryColorLight, primaryColorDark and secondaryHeaderColor.

• These ThemeData colors are on a deprecation path and will likely receive some new none MaterialColor dependent color defaults when that change happens. The new ColorScheme.primary computed colors for these rarely used colors are better balanced than before, and work well regardless of used ColorScheme.primary shade and tint.

Change: Color definition for FlexColor.espressoLightPrimary color was changed.

• Style breaking with 4.2.0 and 5.0.0-dev.1 & 2: New color for FlexColor.espressoLightPrimary breaks past used color for this color constant.

• The color was changed from 0xFF220804 to 0xFF452F2B. Past color was too dark brown, almost black to be very usable in a UI. It was very black coffee like, but not very practical in a UI, it was too close to black. Since version 5 is anyway a major style breaking with the introduction of the new Material 3 ColorScheme, the opportunity to improve this color value used in the built-in theme espresso theme was used.

Examples

• Examples contain minor improvements and fixes.