Add deprecation breaking change for app bar color

src/content/release/breaking-changes/appbar-theme-color.md

@@ -0,0 +1,118 @@
+---
+title: AppBar theme color parameter deprecation
+description: >-
+  The color parameter in AppBarTheme and AppBarThemeData has been
+  deprecated in favor of backgroundColor for better API consistency.
+---
+
+## Summary
+
+The `color` parameter in `AppBarTheme` and `AppBarThemeData` constructors
+and their `copyWith` methods hasve been deprecated. Use `backgroundColor`
+instead. This change affects how AppBar themes are configured and may
+cause deprecation warnings in existing code.
+
+## Background
+
+The AppBar theming system had two parameters that controlled the same
+property: `color` and `backgroundColor`. This duplication created confusion
+and inconsistency in the API. To improve clarity and consistency, the
+`color` parameter has been deprecated in favor of `backgroundColor`.
+
+The deprecation affects the following classes and methods:
+
+- `AppBarTheme` constructor
+- `AppBarTheme.copyWith` method
+- `AppBarThemeData` constructor
+- `AppBarThemeData.copyWith` method
+
+When using the deprecated `color` parameter, you'll see warnings like:
+
+```
+'color' is deprecated and shouldn't be used. Use backgroundColor instead.
+This feature was deprecated after v3.33.0-0.2.pre.
+```
+
+The classes also include assertion checks to prevent using both parameters
+simultaneously:
+
+```
+The color and backgroundColor parameters mean the same thing. Only specify one.
+```
+
+## Migration guide
+
+Replace all uses of the `color` parameter with `backgroundColor` in
+`AppBarTheme` and `AppBarThemeData` constructors and `copyWith` methods.
+
+Code before migration:
+
+```dart
+// AppBarTheme constructor
+AppBarTheme(
+  color: Colors.blue,
+  elevation: 4.0,
+)
+
+// AppBarTheme copyWith
+theme.copyWith(
+  color: Colors.red,
+  elevation: 2.0,
+)
+
+// AppBarThemeData constructor
+AppBarThemeData(
+  color: Colors.green,
+  elevation: 4.0,
+)
+
+// AppBarThemeData copyWith
+themeData.copyWith(
+  color: Colors.purple,
+  elevation: 2.0,
+)
+```
+
+Code after migration:
+
+```dart
+// AppBarTheme constructor
+AppBarTheme(
+  backgroundColor: Colors.blue,
+  elevation: 4.0,
+)
+
+// AppBarTheme copyWith
+theme.copyWith(
+  backgroundColor: Colors.red,
+  elevation: 2.0,
+)
+
+// AppBarThemeData constructor
+AppBarThemeData(
+  backgroundColor: Colors.green,
+  elevation: 4.0,
+)
+
+// AppBarThemeData copyWith
+themeData.copyWith(
+  backgroundColor: Colors.purple,
+  elevation: 2.0,
+)
+```
+
+## Timeline
+
+Landed in version: 3.33.0-0.2.pre<br>
+In stable release: Not yet
+
+## References
+
+API documentation:
+
+- [`AppBarTheme`](https://main-api.flutter.dev/flutter/material/AppBarTheme-class.html)
+- [`AppBarThemeData`](https://main-api.flutter.dev/flutter/material/AppBarThemeData-class.html)
+
+Relevant PRs:
+
+- [AppBar theme color parameter deprecation #170624]({{site.github}}/flutter/flutter/pull/170624)

src/content/release/breaking-changes/index.md

@@ -50,6 +50,7 @@ They're sorted by release and listed in alphabetical order:
 * [Component theme normalization updates][]
 
 [Redesigned the Radio Widget]: /release/breaking-changes/radio-api-redesign
+[Deprecate app bar color]: /release/breaking-changes/appbar-theme-color
 [Removed semantics elevation and thickness]: /release/breaking-changes/remove-semantics-elevation-and-thickness
 [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus
 [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json