Provide a helpful error message when ColorScheme.brightness doesn't match ThemeData.brightness (#137611)

fixes [Unexpected behaviour with ColorScheme.fromSeed and Brightness.dark](https://github.com/flutter/flutter/issues/127523)

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

@@ -388,7 +388,12 @@ class ThemeData with Diagnosticable {
       : InkSplash.splashFactory;
 
     // COLOR
-    assert(colorScheme?.brightness == null || brightness == null || colorScheme!.brightness == brightness);
+    assert(
+      colorScheme?.brightness == null || brightness == null || colorScheme!.brightness == brightness,
+      'ThemeData.brightness does not match ColorScheme.brightness. '
+      'Either override ColorScheme.brightness or ThemeData.brightness to '
+      'match the other.'
+    );
     assert(colorSchemeSeed == null || colorScheme == null);
     assert(colorSchemeSeed == null || primarySwatch == null);
     assert(colorSchemeSeed == null || primaryColor == null);

packages/flutter/test/material/theme_data_test.dart

@@ -1284,6 +1284,102 @@ void main() {
     // Ensure they are all there.
     expect(propertyNames, expectedPropertyNames);
   });
+
+  testWidgetsWithLeakTracking(
+    'ThemeData.brightness not matching ColorScheme.brightness throws a helpful error message', (WidgetTester tester) async {
+      AssertionError? error;
+
+      // Test `ColorScheme.light()` and `ThemeData.brightness == Brightness.dark`.
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: ThemeData(
+              colorScheme: const ColorScheme.light(),
+              brightness: Brightness.dark,
+            ),
+            home: const Placeholder(),
+          ),
+        );
+      } on AssertionError catch (e) {
+        error = e;
+      } finally {
+        expect(error, isNotNull);
+        expect(error?.message, contains(
+          'ThemeData.brightness does not match ColorScheme.brightness. '
+          'Either override ColorScheme.brightness or ThemeData.brightness to '
+          'match the other.'
+        ));
+      }
+
+      // Test `ColorScheme.dark()` and `ThemeData.brightness == Brightness.light`.
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: ThemeData(
+              colorScheme: const ColorScheme.dark(),
+              brightness: Brightness.light,
+            ),
+            home: const Placeholder(),
+          ),
+        );
+      } on AssertionError catch (e) {
+        error = e;
+      } finally {
+        expect(error, isNotNull);
+        expect(error?.message, contains(
+          'ThemeData.brightness does not match ColorScheme.brightness. '
+          'Either override ColorScheme.brightness or ThemeData.brightness to '
+          'match the other.'
+        ));
+      }
+
+      // Test `ColorScheme.fromSeed()` and `ThemeData.brightness == Brightness.dark`.
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: ThemeData(
+              colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xffff0000)),
+              brightness: Brightness.dark,
+            ),
+            home: const Placeholder(),
+          ),
+        );
+      } on AssertionError catch (e) {
+        error = e;
+      } finally {
+        expect(error, isNotNull);
+        expect(error?.message, contains(
+          'ThemeData.brightness does not match ColorScheme.brightness. '
+          'Either override ColorScheme.brightness or ThemeData.brightness to '
+          'match the other.'
+        ));
+      }
+
+      // Test `ColorScheme.fromSeed()` using `Brightness.dark` and `ThemeData.brightness == Brightness.light`.
+      try {
+        await tester.pumpWidget(
+          MaterialApp(
+            theme: ThemeData(
+              colorScheme: ColorScheme.fromSeed(
+                seedColor: const Color(0xffff0000),
+                brightness: Brightness.dark,
+              ),
+              brightness: Brightness.light,
+            ),
+            home: const Placeholder(),
+          ),
+        );
+      } on AssertionError catch (e) {
+        error = e;
+      } finally {
+        expect(error, isNotNull);
+        expect(error?.message, contains(
+          'ThemeData.brightness does not match ColorScheme.brightness. '
+          'Either override ColorScheme.brightness or ThemeData.brightness to '
+          'match the other.'
+        ));
+      }
+  });
 }
 
 @immutable