Was there a migration guide for ColorScheme.background when it was deprecated? If not, we should probably make one, as this change might break folks and they won't know how to readily fix it.

Yes, the migration guide is included in the breaking change page: https://docs.flutter.dev/release/breaking-changes/new-color-scheme-roles :)

NOTE: Not sure were to put this, but I came from this issue: #149158

I think a lot of apps using material have a background color with a different surface color above it. Take for example an app with a scaffold and then on top of it a card, that would break badly.

I found out the description of the surface color is the following:

/// The background color for widgets like [Card].
final Color surface;

I think there is one missing piece, before we had surface and onSurface. But now there is no replacement, I believe that apps using it are now stuck, unless they create a color extension to get that functionality back.

I think background -> surface doesn't make sense because they are two different colors.
The same thing goes on onBackground -> onSurface

I attached the docs above that are still saying, I copied them from 3.22.0, surface is the background color for cards.

NOTE: Not sure were to put this, but I came from this issue: #149158

I think a lot of apps using material have a background color with a different surface color above it. Take for example an app with a scaffold and then on top of it a card, that would break badly.

I think there is one missing piece, before we had surface and onSurface. But now there is no replacement, I believe that apps using it are now stuck, unless they create a color extension to get that functionality back.

I think background -> surface doesn't make sense because they are two different colors. The same thing goes on onBackground -> onSurface

I attached the docs above that are still saying, I copied them from 3.22.0, surface is the background color for cards.

Thanks a lot for your suggestions! We are replacing surface and onSurface with background and onBackground because the latest Material Design 3 has deprecated these colors. And currently there should be no M3 widgets use background and onBackground as the defaults. The surface and onSurface should be able to replace them well if we use the M3 dynamic colors(ColorScheme.fromSeed or ColorScheme.fromImageProvider) because these two are basically duplicated.

I found out the description of the surface color is the following:

/// The background color for widgets like [Card].
final Color surface;

Thanks for pointing this out! This doc should be updated based on the new ColorScheme change because after we added more tone-based surface color roles(like surfaceContainer/-Low/-Lowest/-High/-Highest), surfaceContainerLow becomes the default for Card and we can see some contrast from the scaffold background. Sorry for the confusion!

auto label is removed for flutter/flutter/149772, due to - The status or check suite Windows build_tests_4_7 has failed. Please fix the issues identified (or deflake) before re-applying this label.

Got a surprise on 3.24 like @YazeedAlKhalaf mentioned, we are not using M3 design guidelines strictly, rather using a different background and surface. Anyway, for anyone coming here because of the surprise after update, please set your scaffoldBackgroundColor in main ThemeData to revert to your original look:

final _m3Theme = ThemeData(
    useMaterial3: true,
    scaffoldBackgroundColor: Color(0xFFFAFAFA), // Or a color from scheme you don't generally use, as that helps you keep dart and light modes in check
  );

Flutter upgrades generally bring these surprises which require some work to fix, and have to generally go through the changelog every time to see what broke and why, even the migration pages only work if you know how to find them. The doc mentioned above is not part of the breaking-changes landing page here.