Bump m3e_design to 0.2.1; add .toM3EThemeData() extension for simplified theme creation, update documentation, and refactor BuildContext extension for fallback handling.

packages/m3e_design/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 0.2.1
+- simplify the M3E Theme extension by add `.toM3EThemeData()` extension method
+
 ## 0.2.0
 - add accessors for getting the M3E theme from ThemeData via Theme.of(context).m3e
 

packages/m3e_design/README.md

@@ -19,7 +19,7 @@ cd apps/gallery
 flutter run -d chrome
 ```
 
-_Last updated: 2025-10-23_
+_Last updated: 2025-10-25_
 
 
 ---
@@ -40,27 +40,73 @@ dependencies:
 
 Minimum SDK: Dart >=3.5.0.
 
-### Quick start: add M3ETheme to ThemeData
+### Quick start: one-liner theme
 ```dart
-final base = ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.teal));
+Widget buildApp() {
-final m3e = M3ETheme.defaults(base.colorScheme);
+  return MaterialApp(
-
+    theme: ColorScheme.fromSeed(seedColor: Colors.teal).toM3EThemeData(),
-return MaterialApp(
+    home: const MyHomePage(),
-  theme: base.copyWith(extensions: [m3e]),
+  );
-  home: const MyHomePage(),
+}
-);
 ```
 
-With dynamic color (Android 12+):
+With dynamic color (Android 12+), setting both light and dark themes:
 ```dart
-DynamicColorBuilder(
+Widget buildDynamicApp() {
-  builder: (lightDynamic, darkDynamic) {
+  return DynamicColorBuilder(
-    final scheme = lightDynamic ?? ColorScheme.fromSeed(seedColor: Colors.teal);
+    builder: (lightDynamic, darkDynamic) {
-    final base = ThemeData(colorScheme: scheme);
+      final light = lightDynamic ?? ColorScheme.fromSeed(seedColor: Colors.teal);
-    final m3e = M3ETheme.defaults(base.colorScheme);
+      final dark = darkDynamic ??
-    return MaterialApp(theme: base.copyWith(extensions: [m3e]), home: const MyHomePage());
+          ColorScheme.fromSeed(seedColor: Colors.teal, brightness: Brightness.dark);
-  },
+      return MaterialApp(
-)
+        theme: light.toM3EThemeData(),
+        darkTheme: dark.toM3EThemeData(),
+        home: const MyHomePage(),
+      );
+    },
+  );
+}
+```
+
+### Alternative approach: withM3ETheme
+The alternative approach is to use the withM3ETheme ThemeExtension, which is a convenience wrapper around the ThemeData constructor.
+``` dart
+Widget build(BuildContext context) {
+  return MaterialApp(
+    theme: withM3ETheme(
+      ThemeData(
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.teal),
+        useMaterial3: true,
+      ),
+    ),
+    home: const MyHomePage(),
+    );
+}
+```
+
+``` dart
+Widget build(BuildContext context) {
+      child: DynamicColorBuilder(
+        builder: (lightDynamic, darkDynamic) {
+          return MaterialApp(
+            theme: withM3ETheme(
+              ThemeData(
+                colorScheme: lightDynamic ?? App._defaultLightColorScheme,
+                useMaterial3: true,
+              ),
+            ),
+            darkTheme: withM3ETheme(
+              ThemeData(
+                colorScheme: darkDynamic ?? App._defaultDarkColorScheme,
+                useMaterial3: true,
+                brightness: Brightness.dark,
+              ),
+            ),
+            home: const MyHomePage(),
+          );
+        },
+      ),
+    }   
 ```
 
 ### Token overview

packages/m3e_design/lib/theme/m3e_theme.dart

@@ -110,3 +110,21 @@ extension M3EThemeAccessors on ThemeData {
     return e ?? M3ETheme.defaults(colorScheme);
   }
 }
+
+// Convenience creation helpers to install M3ETheme with minimal boilerplate.
+extension M3EColorSchemeAccessors on ColorScheme {
+  /// Creates a ThemeData from this ColorScheme and installs the M3ETheme
+  /// extension in one call.
+  ///
+  /// Example:
+  ///   final theme = ColorScheme.fromSeed(seedColor: Colors.teal).toM3EThemeData();
+  ThemeData toM3EThemeData({
+    bool useMaterial3 = true,
+    M3ETheme? override,
+    ThemeData? base,
+  }) {
+    final ThemeData seed =
+        base ?? ThemeData(useMaterial3: useMaterial3, colorScheme: this);
+    return withM3ETheme(seed, override: override);
+  }
+}

packages/m3e_design/lib/utils/build_context_x.dart

@@ -3,5 +3,6 @@ import 'package:flutter/material.dart';
 import '../theme/m3e_theme.dart';
 
 extension BuildContextM3EX on BuildContext {
-  M3ETheme get m3e => Theme.of(this).m3e;
+  M3ETheme get m3e =>
+      Theme.of(this).extension<M3ETheme>() ?? M3ETheme.defaults(Theme.of(this).colorScheme);
 }

packages/m3e_design/pubspec.yaml

@@ -1,6 +1,6 @@
 name: m3e_design
 description: Material 3 Expressive design language for Flutter (tokens, ThemeExtension, motion).
-version: 0.2.0
+version: 0.2.1
 repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/m3e_design
 issue_tracker: https://github.com/EmilyMonestone/material_3_expressive/issues