Adding migration guide for Material 3 colors (#128429)

Fixes: https://github.com/flutter/flutter/issues/127228

packages/flutter/lib/src/material/color_scheme.dart

@@ -18,6 +18,10 @@ import 'theme_data.dart';
 /// that can be used to configure the color properties of most components.
 /// {@endtemplate}
 ///
+/// ### Colors in Material 3
+///
+/// {@macro flutter.material.colors.colorRoles}
+///
 /// The main accent color groups in the scheme are [primary], [secondary],
 /// and [tertiary].
 ///
@@ -44,10 +48,10 @@ import 'theme_data.dart';
 /// contrast ratio with their matching colors of at least 4.5:1 in order to
 /// be readable.
 ///
-/// The [Theme] has a color scheme, [ThemeData.colorScheme], which can either be
+/// ### Setting Colors in Flutter
-/// passed in as a parameter to the constructor or by using 'brightness' and
+///
-/// 'colorSchemeSeed' parameters (which are used to generate a scheme with
+///{@macro flutter.material.colors.settingColors}
-/// [ColorScheme.fromSeed]).
+//
 @immutable
 class ColorScheme with Diagnosticable {
   /// Create a ColorScheme instance from the given colors.

packages/flutter/lib/src/material/colors.dart

@@ -10,6 +10,83 @@ import 'package:flutter/painting.dart';
 /// darker the color. There are 10 valid indices: 50, 100, 200, ..., 900.
 /// The value of this color should the same the value of index 500 and [shade500].
 ///
+/// ## Updating to [ColorScheme]
+///
+/// The [ColorScheme] is preferred for
+/// representing colors in applications that are configured
+/// for Material 3 (see [ThemeData.useMaterial3]).
+/// For more information on colors in Material 3 see
+/// the spec at <https://m3.material.io/styles/color/the-color-system>.
+///
+///{@template flutter.material.colors.colorRoles}
+/// In Material 3, colors are represented using color roles and
+/// corresponding tokens. Each property in the [ColorScheme] class
+/// represents one color role as defined in the spec above.
+/// {@endtemplate}
+///
+/// ### Material 3 Colors in Flutter
+///
+///{@template flutter.material.colors.settingColors}
+/// Flutter's Material widgets can be assigned colors at the widget level
+/// using widget properties,
+/// or at the app level using theme classes.
+///
+/// For example, you can set the background of the [AppBar] by
+/// setting the [AppBar.backgroundColor] to a specific [Color] value.
+///
+/// To globally set the AppBar background color for your app, you
+/// can set the [ThemeData.appBarTheme] property for your [MaterialApp]
+/// using the [ThemeData] class. You can also override
+/// the default appearance of all the [AppBar]s in a widget subtree by
+/// placing the [AppBarTheme] at the root of the subtree.
+///
+/// Alternatively, you can set the [ThemeData.colorScheme] property
+/// to a custom [ColorScheme]. This creates a unified [ColorScheme] to be
+/// used across the app. The [AppBar.backgroundColor] uses the
+/// [ColorScheme.surface] by default.
+///{@endtemplate}
+///
+/// ### Migrating from [MaterialColor] to [ColorScheme]
+///
+/// In most cases, there are new properties in Flutter widgets that
+/// accept a [ColorScheme] instead of a [MaterialColor].
+///
+/// For example, you may have previously constructed a [ThemeData]
+/// using a primarySwatch:
+///
+/// ```dart
+/// ThemeData(
+///   primarySwatch: Colors.amber,
+/// )
+/// ```
+///
+/// In Material 3, you can use the [ColorScheme] class to
+/// construct a [ThemeData] with the same color palette
+/// by using the [ColorScheme.fromSeed] constructor:
+///
+///  ```dart
+/// ThemeData(
+///   colorScheme: ColorScheme.fromSeed(seedColor: Colors.amber),
+/// )
+/// ```
+///
+/// The [ColorScheme.fromSeed] constructor
+/// will generate a set of tonal palettes,
+/// which are used to create the color scheme.
+///
+/// Alternatively you can use the [ColorScheme.fromSwatch] constructor:
+///
+/// ```dart
+/// ThemeData(
+///  colorScheme: ColorScheme.fromSwatch(primarySwatch: Colors.amber),
+/// )
+/// ```
+///
+/// The [ColorScheme.fromSwatch] constructor will
+/// create the color scheme directly from the specific
+/// color values used in the [MaterialColor].
+///
+///
 /// See also:
 ///
 ///  * [Colors], which defines all of the standard material colors.