From 7c9c19a979a56b2c58b03414c1d2251d4b010240 Mon Sep 17 00:00:00 2001 From: Qun Cheng Date: Mon, 9 Dec 2024 15:52:20 -0800 Subject: [PATCH 1/5] Migration guide for m3 token update --- src/content/release/breaking-changes/index.md | 2 + .../material-design-3-token-update.md | 93 +++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 src/content/release/breaking-changes/material-design-3-token-update.md diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 1f98b3fe65a..013b02dbc17 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -35,6 +35,7 @@ release, and listed in alphabetical order: * [`ImageFilter.blur` default tile mode automatic selection][] * [Localized messages are generated into source, not a synthetic package][] +* [Material 3 Tokens Update in Flutter][] * [`.flutter-plugins-dependencies` replaces `.flutter-plugins`][] * [`Color` wide gamut support][] * [Remove invalid parameters for `InputDecoration.collapsed`][] @@ -47,6 +48,7 @@ release, and listed in alphabetical order: [`ImageFilter.blur` default tile mode automatic selection]: /release/breaking-changes/image-filter-blur-tilemode [Localized messages are generated into source, not a synthetic package]: /release/breaking-changes/flutter-generate-i10n-source +[Material 3 Tokens Update in Flutter]: /release/breaking-changes/material-design-3-token-update [`.flutter-plugins-dependencies` replaces `.flutter-plugins`]: /release/breaking-changes/flutter-plugins-configuration [`Color` wide gamut support]: /release/breaking-changes/wide-gamut-framework [Remove invalid parameters for `InputDecoration.collapsed`]: /release/breaking-changes/input-decoration-collapsed diff --git a/src/content/release/breaking-changes/material-design-3-token-update.md b/src/content/release/breaking-changes/material-design-3-token-update.md new file mode 100644 index 00000000000..2a2f1df6562 --- /dev/null +++ b/src/content/release/breaking-changes/material-design-3-token-update.md @@ -0,0 +1,93 @@ +--- +title: Material 3 Tokens Update in Flutter +description: >- + The latest Material Design 3 tokens(v6.1) have been applied to the Flutter + Material library. +--- + +## Summary + +The Material Design tokens updated the mapping of 4 color roles (only in Light +mode) to be more visually appealing while retaining accessible contrast. We did +not identify any breakages in our testing of this change, which applied to the +following color properties: + +* On-primary-container (Primary10 to Primary30) +* On-secondary-container (Secondary10 to Secondary30) +* On-tertiary-container (Tertiary10 to Tertiary30) +* On-error-container (Error10 to Error30) + +Widgets that have been using these roles with their default value might look +different. + +Additionally, the Material 3 tokens also updated the border color of Chips from +`ColorScheme.outline` to `ColorScheme.outlineVariant` to improve visual +hierarchy between chips and buttons. Chips (`Chip`, `ActionChip`, `ChoiceChip`, +`FilterChip`, and `InputChip`) that have been using the chip border tokens may +look different. + +## Migration guide + +The differences in the mappings of the color roles are small. Using +`ColorScheme.copyWith` to revert to the original default colors: + +Code before migration: + +```dart +final ColorScheme colors = ThemeData().colorScheme; +``` + +Code after migration: + +```dart +final ColorScheme colors = ThemeData().colorScheme.copyWith( + onPrimaryContainer: const Color(0xFF21005D), + onSecondaryContainer: const Color(0xFF1D192B), + onTertiaryContainer: const Color(0xFF31111D), + onErrorContainer: const Color(0xFF410E0B), +); +``` + +After applying the token update, the default border color of M3 chips looks +lighter. Take `ActionChip` as an example: + +Code before migration: + +```dart +final Widget chip = ActionChip( + label: const Text('action chip'), + onPressed: () {}, +); +``` + +Code after migration: + +```dart +final Widget chip = ChipTheme( + data: ChipThemeData( + side: BorderSide( + color: Theme.of(context).colorScheme.outline + ), + ), + child: ActionChip( + label: const Text('action chip'), + onPressed: () {} + ) +); +``` + +## Timeline + +Landed in version: 3.26.0-0.0.pre
+In stable release: not yet + +## References + +Relevant PRs: + +* [Update tokens to v5.0.0][] +* [Update tokens to v6.1.0][] +* [Enhance ColorScheme.fromSeed with a new variant parameter][] + +[Update tokens to v5.0.0]: {{site.repo.flutter}}/pull/[153385] +[Update tokens to v6.1.0]: {{site.repo.flutter}}/pull/[153722] From 7ebe9ba89cf9e151627ea48c525156a6402f1c19 Mon Sep 17 00:00:00 2001 From: Qun Cheng Date: Mon, 9 Dec 2024 15:58:49 -0800 Subject: [PATCH 2/5] Remove 'we' and 'our' --- .../breaking-changes/material-design-3-token-update.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/release/breaking-changes/material-design-3-token-update.md b/src/content/release/breaking-changes/material-design-3-token-update.md index 2a2f1df6562..fca77ded8c0 100644 --- a/src/content/release/breaking-changes/material-design-3-token-update.md +++ b/src/content/release/breaking-changes/material-design-3-token-update.md @@ -8,9 +8,9 @@ description: >- ## Summary The Material Design tokens updated the mapping of 4 color roles (only in Light -mode) to be more visually appealing while retaining accessible contrast. We did -not identify any breakages in our testing of this change, which applied to the -following color properties: +mode) to be more visually appealing while retaining accessible contrast. There +are not any breakages identified in Flutter testing of this change, which +applied to the following color properties: * On-primary-container (Primary10 to Primary30) * On-secondary-container (Secondary10 to Secondary30) From 67d64258425292d0f8fe4e4a23f8f51e919b1cd3 Mon Sep 17 00:00:00 2001 From: Qun Cheng Date: Tue, 10 Dec 2024 10:18:17 -0800 Subject: [PATCH 3/5] Fix invalid link --- .../release/breaking-changes/material-design-3-token-update.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/release/breaking-changes/material-design-3-token-update.md b/src/content/release/breaking-changes/material-design-3-token-update.md index fca77ded8c0..7fee1e78a1d 100644 --- a/src/content/release/breaking-changes/material-design-3-token-update.md +++ b/src/content/release/breaking-changes/material-design-3-token-update.md @@ -87,7 +87,6 @@ Relevant PRs: * [Update tokens to v5.0.0][] * [Update tokens to v6.1.0][] -* [Enhance ColorScheme.fromSeed with a new variant parameter][] [Update tokens to v5.0.0]: {{site.repo.flutter}}/pull/[153385] [Update tokens to v6.1.0]: {{site.repo.flutter}}/pull/[153722] From b6b40674752c6440e1ab59631c4720902e4336da Mon Sep 17 00:00:00 2001 From: Qun Cheng Date: Tue, 10 Dec 2024 15:12:07 -0800 Subject: [PATCH 4/5] Add API refrences --- .../material-design-3-token-update.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/content/release/breaking-changes/material-design-3-token-update.md b/src/content/release/breaking-changes/material-design-3-token-update.md index 7fee1e78a1d..e66e2a11c05 100644 --- a/src/content/release/breaking-changes/material-design-3-token-update.md +++ b/src/content/release/breaking-changes/material-design-3-token-update.md @@ -83,10 +83,19 @@ In stable release: not yet ## References +API documentation: + +* [`ColorScheme`][] +* [`ThemeData`][] +* [`Chip`][] + Relevant PRs: * [Update tokens to v5.0.0][] * [Update tokens to v6.1.0][] -[Update tokens to v5.0.0]: {{site.repo.flutter}}/pull/[153385] -[Update tokens to v6.1.0]: {{site.repo.flutter}}/pull/[153722] +[`ColorScheme`]: {{site.api}}/flutter/material/ColorScheme-class.html +[`ThemeData`]: {{site.api}}/flutter/material/ThemeData-class.html +[`Chip`]: {{site.api}}/flutter/material/Chip-class.html +[Update tokens to v5.0.0]: {{site.repo.flutter}}/pull/153385 +[Update tokens to v6.1.0]: {{site.repo.flutter}}/pull/153722 From b74eb2ae7bb6c7f25c38d23fe7b8136de22712bb Mon Sep 17 00:00:00 2001 From: Qun Cheng Date: Tue, 10 Dec 2024 15:32:45 -0800 Subject: [PATCH 5/5] Update wording based on PR comments --- .../material-design-3-token-update.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/content/release/breaking-changes/material-design-3-token-update.md b/src/content/release/breaking-changes/material-design-3-token-update.md index e66e2a11c05..ca57c24f5f0 100644 --- a/src/content/release/breaking-changes/material-design-3-token-update.md +++ b/src/content/release/breaking-changes/material-design-3-token-update.md @@ -8,9 +8,9 @@ description: >- ## Summary The Material Design tokens updated the mapping of 4 color roles (only in Light -mode) to be more visually appealing while retaining accessible contrast. There -are not any breakages identified in Flutter testing of this change, which -applied to the following color properties: +mode) to be more visually appealing while retaining accessible contrast. Testing +identified this change as [non-breaking] in Flutter, but some customers might +notice this small change. The update affected the following color properties: * On-primary-container (Primary10 to Primary30) * On-secondary-container (Secondary10 to Secondary30) @@ -20,7 +20,7 @@ applied to the following color properties: Widgets that have been using these roles with their default value might look different. -Additionally, the Material 3 tokens also updated the border color of Chips from +Additionally, the Material 3 tokens updated the border color of Chips from `ColorScheme.outline` to `ColorScheme.outlineVariant` to improve visual hierarchy between chips and buttons. Chips (`Chip`, `ActionChip`, `ChoiceChip`, `FilterChip`, and `InputChip`) that have been using the chip border tokens may @@ -28,7 +28,7 @@ look different. ## Migration guide -The differences in the mappings of the color roles are small. Using +The differences in the mappings of the color roles are small. Use `ColorScheme.copyWith` to revert to the original default colors: Code before migration: @@ -99,3 +99,4 @@ Relevant PRs: [`Chip`]: {{site.api}}/flutter/material/Chip-class.html [Update tokens to v5.0.0]: {{site.repo.flutter}}/pull/153385 [Update tokens to v6.1.0]: {{site.repo.flutter}}/pull/153722 +[non-breaking]: {{site.repo.flutter}}/flutter/blob/master/docs/contributing/Tree-hygiene.md#1-determine-if-your-change-is-a-breaking-change