☂️ 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
• BottomAppBarTheme
• InputDecorationTheme
• CardTheme Normalize Card theme #151914
• ChipTheme Reland "ChipThemeData is now conventional" #94179
• DialogThemeNormalize Dialog theme #153982
• ListTileTheme Reland Refactored ListTileTheme: ListTileThemeData, ThemeData.listThemeData #91840
• 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.

[ghost]

Currently, I am developing an app that should look Android'ish on Android and iOS'ish on iOS. So I use the MaterialApp for Android and the CupertinoApp for iOS. And I also try to get a Material- and CupertinoTheme together, both with dark and light colors. It isn't easy :(

I saw that CupertinoApp has only one theme parameter, and you use the CupertinoDynamicColor to define the light and dark colors (and some more).

Now I wonder why we don't have the same for the MaterialApp? Would it be a good idea to remove all these darkTheme, highContrastTheme, and highContrastDarkTheme from the MaterialApp and use a MaterialDynamicColor?

[rydmike]

Additional colors to add to above list?

Should perhaps the following colors also be mentioned above among the ThemeData colors that should be deprecated/moved/removed?

• primaryColorLight
• primaryColorDark

They are currently not listed, but I doubt the intention is for them to remain. (cc @guidezpl)

primaryColorLight

A lighter color of primary. It is only used by CircleAvatar.
A potential replacement color is ColorScheme.primaryContainer.

primaryColorDark

A darker color of primary, it is used by CircleAvatar.
A potential replacement color is ColorScheme.onPrimaryContainer.

Challenges

The replacements would not be an exact match, so it would be breaking, but it matches the current design intent, if primaryContainer and onPrimaryContainer are using color tones as intended by M3 color design.

Status of primaryColorLight and pimaryColorDark

I wrote quite a bit about some past ThemeData color challenges here #65782. I was about to close the old issue, since most of the topics mentioned in it have been or are being addressed by the in progress ThemeData migration being tracked in this issue.

I did however not see anything addressing or mentioning primaryColorLight and primaryColorDark in ThemeData. Which does not mean it does not already exist, I might just have missed it.

The presence of primaryColorLight and primaryColorDark in ThemeData if kept, will continue to cause potential confusion.

Currently if you create a theme with ThemeData.from or just ThemeData and you give it a ColorScheme in colorScheme and don't provide a primarySwatch that would match in tones what you used for your primary in the ColorScheme, or directly give the color properties primaryColorLight and primaryColorDark values that fit your ColorScheme's primary color. Well, then you end up with primaryColorLight and primaryColorDark having default color values (blue hues, or grey in dark mode) that have nothing to do with whatever color you used in your ColorScheme as primary color, unless it happened to be a shade of blue close to the M2 blue swatch. Plus in the deprecate/move/remove list above, there is also this:

Deprecate primarySwatch from ThemeData factory constructor (8)

Which further complicates the continued existence of primaryColorLight and primaryColorDark in ThemeData.

---

EDIT Aug 3, 2022: Obviously primaryColor itself is also not mentioned in the ThemeData System Updates, should it also be included?

[rydmike]

Deprecation of ThemeData.scaffoldBackgroundColor

I noticed that the mention of adding a ScaffoldThemeData with a background color and ThemeData.scaffoldTheme in relation to the deprecation of ThemeData.scaffoldBackgroundColor was removed in this edit:

I would like to point out that not having a migration path for providing a custom color for the themed background color of the Scaffold, will severely break pretty much every app, well OK every 2nd app at least.

Deprecating the property is of course already breaking, but what is worse is that just removing it without providing a new themeable property for it, results in that there is no migration path. Since, if you just remove scaffoldBackgroundColor, it will be impossible to theme it like you can now. It will just get a default ColorScheme mapping (probably surface), but that does not help all with all the custom color assignments that exist today to ThemeData.scaffoldBackgroundColor.

Properties like e.g. ThemeData.dialogBackgroundColor do not have this problem, since the dialog background can still be themed to whatever desired color, in the dialog component theme, so deprecation of e.g. ThemeData.dialogBackgroundColor is of course breaking for many too, but it has a clear and simple migration path. The ThemeData.scaffoldBackgroundColor color needs this too.

Proposal

Either

1. Do not deprecate ThemeData.scaffoldBackgroundColor

Or

2. Deprecate it and also add a component theme for it, like originally mentioned.

Option 2 of course opens up opportunities for adding a few more themeable properties to existing Scaffold properties. Some of would be helpful to have there, like e.g. extendBody and extendBodyBehindAppBar to mention a few. Of course, to add them, the Scaffold bool properties will need to be made nullable and fallback via prop value to theme value and to defaults, but it would not break any current behavior.

[flutter-triage-bot]

This issue is assigned to @QuncCccccc but has had no recent status updates. Please consider unassigning this issue if it is not going to be addressed in the near future. This allows people to have a clearer picture of what work is actually planned. Thanks!

[flutter-triage-bot]

This issue is assigned to @QuncCccccc but has had no recent status updates. Please consider unassigning this issue if it is not going to be addressed in the near future. This allows people to have a clearer picture of what work is actually planned. Thanks!

[flutter-triage-bot]

This issue was assigned to @QuncCccccc but has had no status updates in a long time. To remove any ambiguity about whether the issue is being worked on, the assignee was removed.