☂️ Material Theme System Updates

[guidezpl]

This issue mirrors the design of https://flutter.dev/go/material-theme-system-updates

Rename the TextTheme TextStyles

• Migrate TextTheme to 2018 APIs #48547
• Deprecate Material 2 text style properties #98746

Deprecate/remove the accent properties

• ☂️ Remove accentColor and accentTextTheme from ThemeData et al. #56918

Compute brightness, primaryColorBrightness, accentColorBrightness

• Deprecate accentColorBrightness Deprecate ThemeData accentColor, accentColorBright, accentIconTheme, accentTextTheme #81336
• Change ThemeData.brightness to be a simple getter that returns colorScheme.brightness ThemeData.brightness == ThemeData.colorScheme.brightness #56956
• Update SearchDelegate Updated SearchDelegate to follow custom InputDecorationTheme #55209
• Update GridTileBar Removed GridTileBar accentColor dependency. #78574
• Deprecate primaryColorBrightness Deprecate primaryColorBrightness #93396

Deprecate/move/remove the 21 grab-bag properties

(x) indicates number of references, excludingtheme_data.dart and tests. This can be used a proxy for disruptiveness/ease of deprecation.

• Deprecate ThemeData.canvasColor [ThemeData 🧹] Remove canvasColor usages #116350
• Deprecate ThemeData.scaffoldBackgroundColor [ThemeData 🧹] Remove scaffoldBackgroundColor usages #116341
• Deprecate ThemeData.cardColor [ThemeData 🧹] Remove cardColor usages #116349
• Deprecate ThemeData.dividerColor [ThemeData 🧹] Remove dividerColor usages #116347
• Deprecate ThemeData.secondaryHeaderColor [ThemeData 🧹] Remove secondaryHeaderColor usages #116342
• Deprecate ThemeData.hintColor [ThemeData 🧹] Remove hintColor usages #116346
• Deprecate ThemeData.splashColor (5) ⇒ inkColor or inkFeatureColor
• Deprecate ThemeData.unselectedWidgetColor (11) ⇒ see toggleableActiveColor deprecation
• Deprecate ThemeData.bottomAppBarColor ⇒ Deprecate ThemeData.bottomAppBarColor #111080
• Deprecate ThemeData.selectedRowColor Deprecate ThemeData.selectedRowColor #109070
• Deprecate ThemeData.buttonColor Deprecated ThemeData buttonColor #82196
• Deprecate ThemeData.textSelectionColor TextSelectionTheme support (step 3 of 3) #66482
• Deprecate ThemeData.cursorColor TextSelectionTheme support (step 3 of 3) #66482
• Deprecate ThemeData.textSelectionHandleColor TextSelectionTheme support (step 3 of 3) #66482
• Deprecate ThemeData.backgroundColor Deprecate ThemeData errorColor and backgroundColor #110162
• Deprecate ThemeData.dialogBackgroundColor Deprecate ThemeData.dialogBackgroundColor in favor of DialogThemeData.backgroundColor #155072
• Deprecate ThemeData.indicatorColor Deprecate ThemeData.indicatorColor in favor of TabBarThemeData.indicatorColor #160024
• Deprecate ThemeData.errorColor Deprecate ThemeData errorColor and backgroundColor #110162
• Deprecate ThemeData.toggleableActiveColor Deprecate toggleableActiveColor #97972

Additional grab-bag properties

These grab-bag properties not in the original linked proposal, but can also be deprecated:

• Deprecate ThemeData.shadowColor [ThemeData 🧹] Remove shadowColor usages #116343
• Deprecate ThemeData.splashFactory (4) ⇒ inkFactory or inkFeatureFactory
• Deprecate primaryColor Deprecate ThemeData.primaryX #110848
• Deprecate primaryColorDark [ThemeData 🧹] Remove primaryColorLight & primaryColorDark usages #116362
• Deprecate primaryColorLight [ThemeData 🧹] Remove primaryColorLight & primaryColorDark usages #116362
• Deprecate ThemeData.fixTextFieldOutlineLabel Deprecate ThemeData.fixTextFieldOutlineLabel #87281

These factory constructor parameters can also be deprecated:

• Deprecate primarySwatch from ThemeData factory constructor (8) ⇒ colorScheme or colorSchemeSeedColor (related Deprecate ColorScheme.fromSwatch #120064)

Property colors not subject to removal

• State colors like ThemeData.disabledColor (26), ThemeData.focusColor (19), and ThemeData.hoverColor (19) have high usage and are shared amongst many components
• There is similar widespread usage for ThemeData.highlightColor (13)
• Other parameters can remain in the factory constructor (e.g. ThemeData.fontFamily and ThemeData.fontFamilyFallback) for convenience

Component Theme Normalization

All of the existing themes have been normalized except for the following:

• AppBarTheme Normalize AppBarTheme #169130
• BottomAppBarTheme Normalize BottomAppBarTheme #168586
• InputDecorationTheme Normalize input decoration theme #168981
• CardTheme Normalize Card theme #151914
• ChipTheme Reland "ChipThemeData is now conventional" #94179
• DialogThemeNormalize Dialog theme #153982
• ListTileTheme Reland Refactored ListTileTheme: ListTileThemeData, ThemeData.listThemeData #91840
• SnackBarTheme Add SnackBarTheme #180001
• TabBarTheme Normalize TabBarTheme #155476

[rydmike]

Nice summary @guidezpl and great to see this collection issue for moving this topic forward and tracking its progress. It will certainly make things clearer when completed. The current situation seems to be a source of a lot of confusion for many Flutter developers, quite a few related issues open and more arriving ever so often. This will help, eventually.

Most of the colors properties already have proper homes in the ColorScheme and/or appropriate sub-themes, where you can override widget default inherited colors, that properly designed SDK Material UI widgets now get from ThemeData.colorScheme.

For those colors everything looks fine, but not all color properties in ThemeData are so lucky and at that stage. Below I highlight one important case: scaffoldBackgroundColor, there might be others too.

Things to Consider during the Theme System Update and Migration

In case it is not obvious, but as far as I know e.g. ThemeData.scaffoldBackgroundColor currently does not have a home anywhere else. If you do not want it to be same color as ThemeData.colorScheme.background, which presumably would be its new default, ThemeData.from() already assigns this color to it. Then there is no other way to currently theme it.

The only way to set it separately, is to define the ThemeData.scaffoldBackgroundColor, so it needs a new home somewhere.

Being able define slightly different background colors depending on type of surface/background is important. It makes it possible in current version of Flutter to create applications that uses background colors with slightly different nuances, typically with different alpha blend strengths of primary color in the different surface/background colors used by Widgets, depending on their type and current default themed color behavior.

For example, currently with the factory ThemeData.from, that is the most up to date one of the color factories for using proper ColorScheme based themes, we for example have:

• colorScheme.surface, that is assigned to cardColor, used by Card and Material of type card. Expecting these widgets to use colorScheme.surface directly after migration. This is fine and will not hard break anything, change can imo be done easily, everything looks ready for it.
• colorScheme.background, that is assigned to canvasColor, used by Material of type canvas, and via that many widgets. Expecting Material of type canvas to use colorScheme.background directly after migration. This is fine and will not hard break anything, change can imo be done easily, everything looks ready for it.
• dialogBackgroundColor that gets assigned colorScheme.background, already has its own sub-theme, so we can easily theme it to whatever we like (we already use that route in anticipation of dialogBackgroundColor deprecation. This prop can imo be deprecated easily already now, migration path is clear/ready.
• scaffoldBackgroundColor, is also assigned colorScheme.background, but has no other source that can be used to theme it, other than the current ThemeData. It will need it's own new sub-theme, otherwise scaffoldBackgroundColor cannot be deprecated without reduction in currently used theming capabilities and flexibility. It would break things very badly in our apps if it cannot be themed to another color than ThemeData.colorScheme.background going forward.

This might apply to a few other ThemeData color properties on the deprecation list as well.

PS. Yes, I'm aware Material3 brings new containers used for color and onColor, so it will have less/none of these current messy issue that many Flutter devs struggle with when it comes to theme colors for Flutter apps. Although I suspect many will think that M3 color design might be a bit complex. I think it seems pretty straight forward and makes a lot of sense. Looking forward to see how it gets implemented in Flutter. Might be a bit tricky with backward compatibility issues and potential challenges merging it with current widgets. Plus it will increase widget branching for color logic and calculation, potentially decreasing performance of current widgets. Hopefully not, will be interesting to see what the chosen approach is. Just new M3 widgets that uses new Theme designs and concepts, might be simplest, but not ideal either.

[talamaska]

@rydmike From what I see, the scaffoldBackgroundColor is moved in a ScaffoldThemeData. Maybe that's a change after your recommendations. Anyways, thanks for keeping track of the ThemeData changes for all of us.

[rydmike]

@talamaska Thanks, I noticed the addition as well. Perhaps it was a part of the plan all along. Probably so, since if it were not, it would result in new ThemeData that has no migration path for certain use cases.