Migration guide for M3 token update

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`][] <!-- Branch cut starts here, below will be in next stable -->
 * [`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

src/content/release/breaking-changes/material-design-3-token-update.md

@@ -0,0 +1,92 @@
+---
+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. 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)
+* 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<br>
+In stable release: not yet
+
+## References
+
+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]