Update ColorScheme.light, ColorScheme.dark, ColorScheme.highContrastLight, & ColorScheme.highContrastDark constructors docs for Material 3 (#137149)

fixes [Clarify ColorScheme fromSwatch/fromSeed usage](https://github.com/flutter/flutter/issues/132584)

"This explains how to use `ColorScheme.fromSeed` as a substitute for each `ColorScheme` constructor."

| `ColorScheme.light` (left) to `ColorScheme.fromSeed` (right) | 
| --------------- | 
| ![light](https://github.com/flutter/flutter/assets/48603081/e056e723-5640-4b05-8feb-ca6b517c8682)	|

| `ColorScheme.dark` (left) to `ColorScheme.fromSeed` (right) | 
| --------------- | 
| ![dark](https://github.com/flutter/flutter/assets/48603081/5ff32611-bfb6-49ee-a34e-f935f580e84e)	|

| `ColorScheme.highContrastLight` (left) to `ColorScheme.fromSeed` (right) | 
| --------------- | 
| ![highContrastLight](https://github.com/flutter/flutter/assets/48603081/4b47f2e3-ea8e-4148-85cc-69690e9082c7) |

| `ColorScheme.highContrastDark` (left) to `ColorScheme.fromSeed` (right) | 
| --------------- | 
| ![highContrastDark](https://github.com/flutter/flutter/assets/48603081/3dbd7ec4-c78e-4228-a8ed-673832681563) |

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

@@ -235,8 +235,29 @@ class ColorScheme with Diagnosticable {
     );
   }
 
-  /// Create a ColorScheme based on a purple primary color that matches the
+  /// Create a light ColorScheme based on a purple primary color that matches the
-  /// [baseline Material color scheme](https://material.io/design/color/the-color-system.html#color-theme-creation).
+  /// [baseline Material 2 color scheme](https://material.io/design/color/the-color-system.html#color-theme-creation).
+  ///
+  /// This constructor shouldn't be used to update the Material 3 color scheme.
+  ///
+  /// For Material 3, use [ColorScheme.fromSeed] to create a color scheme
+  /// from a single seed color based on the Material 3 color system.
+  ///
+  /// {@tool snippet}
+  /// This example demonstrates how to create a color scheme similar to [ColorScheme.light]
+  /// using the [ColorScheme.fromSeed] constructor:
+  ///
+  /// ```dart
+  /// colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xff6200ee)).copyWith(
+  ///   primaryContainer: const Color(0xff6200ee),
+  ///   onPrimaryContainer: Colors.white,
+  ///   secondaryContainer: const Color(0xff03dac6),
+  ///   onSecondaryContainer: Colors.black,
+  ///   error: const Color(0xffb00020),
+  ///   onError: Colors.white,
+  /// ),
+  /// ```
+  /// {@end-tool}
   const ColorScheme.light({
     this.brightness = Brightness.light,
     this.primary = const Color(0xff6200ee),
@@ -290,8 +311,34 @@ class ColorScheme with Diagnosticable {
        _inversePrimary = inversePrimary,
        _surfaceTint = surfaceTint;
 
-  /// Create the recommended dark color scheme that matches the
+  /// Create the dark color scheme that matches the
-  /// [baseline Material color scheme](https://material.io/design/color/dark-theme.html#ui-application).
+  /// [baseline Material 2 color scheme](https://material.io/design/color/dark-theme.html#ui-application).
+  ///
+  /// This constructor shouldn't be used to update the Material 3 color scheme.
+  ///
+  /// For Material 3, use [ColorScheme.fromSeed] to create a color scheme
+  /// from a single seed color based on the Material 3 color system.
+  /// Override the `brightness` property of [ColorScheme.fromSeed] to create a
+  /// dark color scheme.
+  ///
+  /// {@tool snippet}
+  /// This example demonstrates how to create a color scheme similar to [ColorScheme.dark]
+  /// using the [ColorScheme.fromSeed] constructor:
+  ///
+  /// ```dart
+  /// colorScheme: ColorScheme.fromSeed(
+  ///   seedColor: const Color(0xffbb86fc),
+  ///   brightness: Brightness.dark,
+  /// ).copyWith(
+  ///   primaryContainer: const Color(0xffbb86fc),
+  ///   onPrimaryContainer: Colors.black,
+  ///   secondaryContainer: const Color(0xff03dac6),
+  ///   onSecondaryContainer: Colors.black,
+  ///   error: const Color(0xffcf6679),
+  ///   onError: Colors.black,
+  /// ),
+  /// ```
+  /// {@end-tool}
   const ColorScheme.dark({
     this.brightness = Brightness.dark,
     this.primary = const Color(0xffbb86fc),
@@ -346,7 +393,28 @@ class ColorScheme with Diagnosticable {
        _surfaceTint = surfaceTint;
 
   /// Create a high contrast ColorScheme based on a purple primary color that
-  /// matches the [baseline Material color scheme](https://material.io/design/color/the-color-system.html#color-theme-creation).
+  /// matches the [baseline Material 2 color scheme](https://material.io/design/color/the-color-system.html#color-theme-creation).
+  ///
+  /// This constructor shouldn't be used to update the Material 3 color scheme.
+  ///
+  /// For Material 3, use [ColorScheme.fromSeed] to create a color scheme
+  /// from a single seed color based on the Material 3 color system.
+  ///
+  /// {@tool snippet}
+  /// This example demonstrates how to create a color scheme similar to [ColorScheme.highContrastLight]
+  /// using the [ColorScheme.fromSeed] constructor:
+  ///
+  /// ```dart
+  /// colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xff0000ba)).copyWith(
+  ///   primaryContainer: const Color(0xff0000ba),
+  ///   onPrimaryContainer: Colors.white,
+  ///   secondaryContainer: const Color(0xff66fff9),
+  ///   onSecondaryContainer: Colors.black,
+  ///   error: const Color(0xff790000),
+  ///   onError: Colors.white,
+  /// ),
+  /// ```
+  /// {@end-tool}
   const ColorScheme.highContrastLight({
     this.brightness = Brightness.light,
     this.primary = const Color(0xff0000ba),
@@ -401,7 +469,33 @@ class ColorScheme with Diagnosticable {
        _surfaceTint = surfaceTint;
 
   /// Create a high contrast ColorScheme based on the dark
-  /// [baseline Material color scheme](https://material.io/design/color/dark-theme.html#ui-application).
+  /// [baseline Material 2 color scheme](https://material.io/design/color/dark-theme.html#ui-application).
+  ///
+  /// This constructor shouldn't be used to update the Material 3 color scheme.
+  ///
+  /// For Material 3, use [ColorScheme.fromSeed] to create a color scheme
+  /// from a single seed color based on the Material 3 color system.
+  /// Override the `brightness` property of [ColorScheme.fromSeed] to create a
+  /// dark color scheme.
+  ///
+  /// {@tool snippet}
+  /// This example demonstrates how to create a color scheme similar to [ColorScheme.highContrastDark]
+  /// using the [ColorScheme.fromSeed] constructor:
+  ///
+  /// ```dart
+  /// colorScheme: ColorScheme.fromSeed(
+  ///   seedColor: const Color(0xffefb7ff),
+  ///   brightness: Brightness.dark,
+  /// ).copyWith(
+  ///   primaryContainer: const Color(0xffefb7ff),
+  ///   onPrimaryContainer: Colors.black,
+  ///   secondaryContainer: const Color(0xff66fff9),
+  ///   onSecondaryContainer: Colors.black,
+  ///   error: const Color(0xff9b374d),
+  ///   onError: Colors.white,
+  /// ),
+  /// ```
+  /// {@end-tool}
   const ColorScheme.highContrastDark({
     this.brightness = Brightness.dark,
     this.primary = const Color(0xffefb7ff),
@@ -458,10 +552,10 @@ class ColorScheme with Diagnosticable {
   /// Creates a color scheme from a [MaterialColor] swatch.
   ///
   /// In Material 3, this constructor is ignored by [ThemeData] when creating
-  /// its default color scheme. Instead, [ThemeData] uses [ ColorScheme.fromSeed]
+  /// its default color scheme. Instead, [ThemeData] uses [ColorScheme.fromSeed]
   /// to create its default color scheme. This constructor shouldn't be used
   /// to update the Material 3 color scheme. It will be phased out gradually;
-  /// see https://github.com/flutter/flutter/issues/91772 for more details.
+  /// see https://github.com/flutter/flutter/issues/120064 for more details.
   ///
   /// If [ThemeData.useMaterial3] is false, then this constructor is used by
   /// [ThemeData] to create its default color scheme.