From b547e0e4becb6ffcca91af4b6d0296d05e7b0cca Mon Sep 17 00:00:00 2001 From: Taha Tesser Date: Tue, 31 Oct 2023 21:03:03 +0200 Subject: [PATCH] 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) | --- .../lib/src/material/color_scheme.dart | 110 ++++++++++++++++-- 1 file changed, 102 insertions(+), 8 deletions(-) diff --git a/packages/flutter/lib/src/material/color_scheme.dart b/packages/flutter/lib/src/material/color_scheme.dart index 6e8e80ca59..98d29c3c17 100644 --- a/packages/flutter/lib/src/material/color_scheme.dart +++ b/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 - /// [baseline Material color scheme](https://material.io/design/color/the-color-system.html#color-theme-creation). + /// Create a light ColorScheme based on a purple primary color that 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.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 - /// [baseline Material color scheme](https://material.io/design/color/dark-theme.html#ui-application). + /// Create the dark color scheme that matches the + /// [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.