Remove unused dynamic field lookup and redundant utility methods; clean up pubspec dependency paths and update READMEs with detailed package guides.

2025-10-23 18:12:39 +02:00 · 2025-10-23 18:12:39 +02:00 · 401dd103a6
commit 401dd103a6
parent 80a27714a6
30 changed files with 799 additions and 64 deletions
--- a/packages/app_bar_m3e/README.md
+++ b/packages/app_bar_m3e/README.md
@ -106,3 +106,84 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+A family of Material 3 Expressive app bars:
+- AppBarM3E — small/standard bar for Scaffold.appBar.
+- SliverAppBarM3E — Medium and Large collapsing variants for CustomScrollView.
+
+All variants are powered by m3e_design tokens for consistent color, typography, and shape.
+
+### Installation
+- Monorepo (local path): already configured in this repo. Ensure packages/m3e_design exists.
+- Pub (when published): add to pubspec.yaml
+
+```yaml
+dependencies:
+  app_bar_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.22.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+Scaffold(
+  appBar: const AppBarM3E(
+    titleText: 'Inbox',
+  ),
+  body: ...,
+);
+```
+
+Medium/Large collapsing:
+```dart
+CustomScrollView(
+  slivers: [
+    SliverAppBarM3E(
+      variant: AppBarM3EVariant.large, // or AppBarM3EVariant.medium
+      titleText: 'Gallery',
+      pinned: true,
+    ),
+    // content...
+  ],
+)
+```
+
+### Key parameters
+- titleText: String? — Text title when you don't pass a custom title widget.
+- title: Widget? — Custom title; overrides titleText.
+- leading: Widget? — Leading widget (e.g. Back button).
+- actions: List<Widget> — Trailing actions.
+- centerTitle: bool — Centers the title on platforms that prefer it.
+- backgroundColor / foregroundColor: Color? — Override token-driven colors.
+- density: AppBarM3EDensity — compact/regular.
+- shapeFamily: AppBarM3EShapeFamily — round or square corners.
+- variant (SliverAppBarM3E): medium or large.
+- pinned / floating / snap (Sliver): Standard sliver app bar behaviors.
+
+### Theming with m3e_design
+App bars read the M3ETheme extension from ThemeData. Example:
+```dart
+final base = ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.teal));
+final m3e = M3ETheme.defaults(base.colorScheme);
+final theme = base.copyWith(extensions: [m3e]);
+```
+
+### Accessibility
+- Meets 48×48 dp minimum hit target recommendations via tokens.
+- Proper contrast from token-driven color system.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/app_bar_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/app_bar_m3e/pubspec.yaml
+++ b/packages/app_bar_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/button_group_m3e/README.md
+++ b/packages/button_group_m3e/README.md
@ -116,3 +116,58 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+A layout-only ButtonGroupM3E that propagates size/shape to its child buttons and ensures consistent spacing and overflow behavior for Material 3 Expressive buttons.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design and button_m3e.
+- Pub (when published):
+```yaml
+dependencies:
+  button_group_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+  button_m3e: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+ButtonGroupM3E(
+  size: ButtonM3ESize.md,
+  shapeFamily: ButtonM3EShapeFamily.round,
+  children: [
+    ButtonM3E.filled(onPressed: () {}, label: const Text('One')),
+    ButtonM3E.outlined(onPressed: () {}, label: const Text('Two')),
+    ButtonM3E.text(onPressed: () {}, label: const Text('Three')),
+  ],
+)
+```
+
+### Key parameters
+- children: List<Widget> — Typically ButtonM3E instances.
+- size: ButtonM3ESize — xs | sm | md | lg | xl. Propagated to children when possible.
+- shapeFamily: ButtonM3EShapeFamily — round | square.
+- spacing: double? — Horizontal/vertical gap between children.
+- direction / wrap: Axis or wrap behavior depending on implementation.
+
+### Theming with m3e_design
+Spacing/shape defaults are derived from M3ETheme tokens; you can override explicitly per group or per button.
+
+### Accessibility
+- Maintains minimum tap targets for grouped buttons and preserves focus order.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/button_group_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/button_group_m3e/pubspec.yaml
+++ b/packages/button_group_m3e/pubspec.yaml
@ -11,7 +11,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/button_m3e/README.md
+++ b/packages/button_m3e/README.md
@ -23,3 +23,60 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+Material 3 Expressive buttons with 5 variants (filled, tonal, elevated, outlined, text), sizes XS–XL, round/square shapes, and optional toggle selection.
+
+### Installation
+- Monorepo (local path): already configured in this repo alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  button_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.19.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+ButtonM3E.filled(
+  onPressed: () {},
+  label: const Text('Save'),
+  icon: const Icon(Icons.save),
+  size: ButtonM3ESize.md,
+  shapeFamily: ButtonM3EShapeFamily.round,
+);
+```
+
+### Key parameters
+- onPressed / onLongPress: callbacks for activation/long-press.
+- label: Widget? — Button label; omit for icon-only variants.
+- icon: Widget? — Optional leading icon.
+- isSelected: bool — Toggle selection state (for toggleable styles).
+- variant/style: ButtonM3EVariant — filled | tonal | elevated | outlined | text.
+- size: ButtonM3ESize — xs | sm | md | lg | xl.
+- shapeFamily: ButtonM3EShapeFamily — round or square.
+- tooltip / semanticsLabel: String? — Accessibility hints.
+- enabled: bool — Whether the button is interactive.
+
+### Theming with m3e_design
+Buttons take colors, shapes, and spacing from M3ETheme. Override via properties or ThemeData when needed.
+
+### Accessibility
+- Ensures minimum 48×48 dp tap target size via layout tokens.
+- Focus, hover, and pressed states follow Material 3 guidance.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/button_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/fab_m3e/README.md
+++ b/packages/fab_m3e/README.md
@ -109,3 +109,73 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+Material 3 Expressive Floating Action Buttons:
+- FabM3E (standard)
+- ExtendedFabM3E (icon + label)
+- FabMenuM3E (expandable menu of FAB actions)
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  fab_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.22.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+// Standard FAB
+FabM3E(
+  icon: const Icon(Icons.add),
+  onPressed: () {},
+)
+
+// Extended FAB
+ExtendedFabM3E(
+  icon: const Icon(Icons.add),
+  label: const Text('Add'),
+  onPressed: () {},
+)
+
+// FAB Menu (example)
+FabMenuM3E(
+  children: [
+    FabM3E(icon: const Icon(Icons.edit), onPressed: () {}),
+    FabM3E(icon: const Icon(Icons.share), onPressed: () {}),
+  ],
+)
+```
+
+### Key parameters
+- icon: Widget — Required for FabM3E and ExtendedFabM3E.
+- label: Widget? — Text label for ExtendedFabM3E.
+- onPressed: VoidCallback? — Action callback.
+- tooltip / semanticsLabel: String? — A11y hints.
+- shapeFamily: M3E shape family as exposed by tokens.
+- heroTag: Object? — For hero transitions.
+- mini: bool — Compact FAB sizing.
+
+### Theming with m3e_design
+Colors/elevation/shape are token-driven via M3ETheme.
+
+### Accessibility
+- 56dp standard, 40dp mini; high-contrast focus and pressed states.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/fab_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/fab_m3e/lib/src/fab_m3e_widget.dart
+++ b/packages/fab_m3e/lib/src/fab_m3e_widget.dart
@ -17,5 +17,3 @@ class FabM3EWidget extends StatelessWidget {
    );
  }
 }
-
-String _pascal(String s) => s.split('_').map((p) => p.isEmpty ? '' : (p[0].toUpperCase() + p.substring(1))).join();
--- a/packages/fab_m3e/pubspec.yaml
+++ b/packages/fab_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/icon_button_m3e/README.md
+++ b/packages/icon_button_m3e/README.md
@ -108,3 +108,51 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+Material 3 Expressive IconButtonM3E with multiple sizes, variants (filled/tonal/outlined/standard), round/square shapes, optional toggle selection, and accessible 48×48dp hit targets.
+
+### Installation
+- Monorepo (local path): already part of this repo.
+- Pub (when published):
+```yaml
+dependencies:
+  icon_button_m3e: ^0.1.1
+```
+
+Minimum SDK: Dart >=3.9.2; Flutter >=1.17.0.
+
+### Dependencies
+- flutter
+
+### Quick start
+```dart
+IconButtonM3E.filled(
+  icon: const Icon(Icons.favorite),
+  onPressed: () {},
+  size: IconButtonM3ESize.md,
+  shapeFamily: IconButtonM3EShapeFamily.round,
+)
+```
+
+### Key parameters
+- icon: Widget — Required.
+- onPressed / onLongPress: callbacks for activation.
+- isSelected: bool — Toggle state for selectable variants.
+- variant: IconButtonM3EVariant — filled | tonal | outlined | standard.
+- size: IconButtonM3ESize — xs | sm | md | lg.
+- shapeFamily: IconButtonM3EShapeFamily — round | square.
+- tooltip / semanticsLabel: String? — A11y hints.
+
+### Accessibility
+- Ensures minimum 48×48 dp touch target; focus and hover visuals included.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/icon_button_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/loading_indicator_m3e/README.md
+++ b/packages/loading_indicator_m3e/README.md
@ -72,3 +72,52 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+Morphing polygon LoadingIndicatorM3E with Default and Contained variants, aligned with Material 3 Expressive motion and color tokens.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  loading_indicator_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.22.0.
+
+### Dependencies
+- flutter
+- m3e_design
+- material_new_shapes
+
+### Quick start
+```dart
+// Default (indeterminate)
+const LoadingIndicatorM3E()
+
+// Contained variant (e.g., inside a container)
+const LoadingIndicatorContainedM3E(width: 48, height: 48)
+```
+
+### Key parameters
+- size / width / height: dimensions of the indicator.
+- color: Color? — Override the token-driven color.
+- semanticsLabel: String? — Describe what is loading for screen readers.
+
+### Theming with m3e_design
+Colors and easing come from tokens in M3ETheme; motion aligns with Material 3 Expressive guidelines.
+
+### Accessibility
+- Provide semanticsLabel to announce loading; avoid infinite animations for long periods.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/loading_indicator_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/loading_indicator_m3e/pubspec.yaml
+++ b/packages/loading_indicator_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design
  material_new_shapes: ^1.0.0

 dev_dependencies:
--- a/packages/m3e_collection/README.md
+++ b/packages/m3e_collection/README.md
@ -43,3 +43,41 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+A convenience package that re-exports all Material 3 Expressive components and design tokens so you can depend on one package and import everything you need.
+
+### Installation
+- Monorepo (local path): already configured in this repo.
+- Pub (when published):
+```yaml
+dependencies:
+  m3e_collection: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0.
+
+### Dependencies (via this collection)
+- m3e_design, icon_button_m3e, split_button_m3e, button_group_m3e, app_bar_m3e, button_m3e, fab_m3e,
+  loading_indicator_m3e, progress_indicator_m3e, navigation_bar_m3e, navigation_rail_m3e, slider_m3e, toolbar_m3e.
+
+### Quick start
+```dart
+import 'package:m3e_collection/m3e_collection.dart';
+
+// Use any M3E widget, e.g. a filled button
+ButtonM3E.filled(label: const Text('Continue'), onPressed: () {})
+```
+
+### Notes
+- Keep versions of individual packages aligned; this collection pins compatible versions.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/m3e_collection
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/m3e_collection/pubspec.yaml
+++ b/packages/m3e_collection/pubspec.yaml
@ -13,29 +13,16 @@ dependencies:
  material_new_shapes: ^1.0.0
  expressive_refresh: ^0.1.2
  m3e_design:
-    path: ../m3e_design
  icon_button_m3e:
-    path: ../icon_button_m3e
  split_button_m3e:
-    path: ../split_button_m3e
  button_group_m3e:
-    path: ../button_group_m3e
  app_bar_m3e:
-    path: ../app_bar_m3e
  button_m3e:
-    path: ../button_m3e
  fab_m3e:
-    path: ../fab_m3e
  loading_indicator_m3e:
-    path: ../loading_indicator_m3e
  progress_indicator_m3e:
-    path: ../progress_indicator_m3e
  navigation_bar_m3e:
-    path: ../navigation_bar_m3e
  navigation_rail_m3e:
-    path: ../navigation_rail_m3e
  slider_m3e:
-    path: ../slider_m3e
  toolbar_m3e:
-    path: ../toolbar_m3e

--- a/packages/m3e_design/README.md
+++ b/packages/m3e_design/README.md
@ -20,3 +20,60 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+The design language core for Material 3 Expressive:
+- M3ETheme ThemeExtension providing tokens for color, typography, shapes, spacing, elevation, and motion.
+- Utilities to derive expressive surfaces (e.g., surfaceContainer levels) and harmonize with dynamic colors.
+
+### Installation
+```yaml
+dependencies:
+  m3e_design: ^0.1.0
+  dynamic_color: ^1.8.1
+```
+
+Minimum SDK: Dart >=3.5.0.
+
+### Quick start: add M3ETheme to ThemeData
+```dart
+final base = ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.teal));
+final m3e = M3ETheme.defaults(base.colorScheme);
+
+return MaterialApp(
+  theme: base.copyWith(extensions: [m3e]),
+  home: const MyHomePage(),
+);
+```
+
+With dynamic color (Android 12+):
+```dart
+DynamicColorBuilder(
+  builder: (lightDynamic, darkDynamic) {
+    final scheme = lightDynamic ?? ColorScheme.fromSeed(seedColor: Colors.teal);
+    final base = ThemeData(colorScheme: scheme);
+    final m3e = M3ETheme.defaults(base.colorScheme);
+    return MaterialApp(theme: base.copyWith(extensions: [m3e]), home: const MyHomePage());
+  },
+)
+```
+
+### Token overview
+- Colors: surface, onSurface, container tiers, primary/secondary/tertiary, outline, inverse, etc.
+- Typography: headline/title/label/body scales incl. emphasized variants.
+- Shapes: round/square families, radii by size category.
+- Spacing: xs→xl ramps for consistent paddings.
+- Motion: durations/easings for expressive transitions.
+
+### Used by
+All sibling packages in this monorepo use M3E tokens for consistent UI.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/m3e_design
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/m3e_design/lib/tokens/color_tokens.dart
+++ b/packages/m3e_design/lib/tokens/color_tokens.dart
@ -174,33 +174,6 @@ class M3EColors {
    Color _surfaceDim() => _blend(s.surface, s.onSurface, 0.05);
    Color _surfaceBright() => _blend(s.surface, s.primary, 0.04);

-    Function(Invocation invocation)? _tryGet<T>(
-        ColorScheme scheme, String getter) {
-      try {
-        final dyn = scheme as dynamic;
-        final v =
-            dyn.__noSuchMethod__ == null ? null : null; // keep analyzer happy
-        return (dyn as dynamic)
-            .noSuchMethod; // never executed, trick to silence lints in try
-      } catch (_) {
-        // ignored
-      }
-      // Fallback path using mirrors is not available; we'll use a switch below.
-      return null;
-    }
-
-    // Read new fields via dynamic with try-catch (avoids hard SDK requirement)
-    Color _getOr(Color? c, Color Function() orElse) => c ?? orElse();
-
-    Color? _readColor(String name) {
-      try {
-        final dyn = s as dynamic;
-        return dyn.toJson != null ? null : (dyn as dynamic)[name] as Color?;
-      } catch (_) {
-        return null;
-      }
-    }
-
    // While dynamic lookup above is intentionally conservative, we can directly
    // access when fields exist in the current SDK, otherwise compute.
    Color surfaceDim = (() {
--- a/packages/navigation_bar_m3e/README.md
+++ b/packages/navigation_bar_m3e/README.md
@ -93,3 +93,60 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+NavigationBarM3E with M3E tokens for colors and shapes, badges, and adaptive layout behavior.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  navigation_bar_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.22.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+int index = 0;
+
+NavigationBarM3E(
+  selectedIndex: index,
+  onDestinationSelected: (i) => setState(() => index = i),
+  destinations: const [
+    NavigationDestinationM3E(icon: Icon(Icons.home), label: 'Home'),
+    NavigationDestinationM3E(icon: Icon(Icons.search), label: 'Search'),
+    NavigationDestinationM3E(icon: Icon(Icons.person), label: 'Profile'),
+  ],
+)
+```
+
+### Key parameters
+- destinations: List<NavigationDestinationM3E> — Destinations to render.
+- selectedIndex: int — Current selection.
+- onDestinationSelected: ValueChanged<int> — Selection callback.
+- badgeBuilder / badgeCount: Optional badges per destination.
+- backgroundColor / indicatorColor: Color? — Override token-driven colors.
+- height / labelBehavior: Layout tweaks.
+
+### Theming with m3e_design
+Colors/shape/typography adapt from the active M3ETheme extension.
+
+### Accessibility
+- Labels visible or via semantics; badges have semantics descriptions.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/navigation_bar_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/navigation_bar_m3e/pubspec.yaml
+++ b/packages/navigation_bar_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/navigation_rail_m3e/README.md
+++ b/packages/navigation_rail_m3e/README.md
@ -66,3 +66,64 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+NavigationRailM3E with collapsed/expanded states, standard/modal presentation, badges, sections, and slots for FAB/menu. Integrates tightly with M3E tokens.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design, fab_m3e, icon_button_m3e, button_m3e.
+- Pub (when published):
+```yaml
+dependencies:
+  navigation_rail_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+  fab_m3e: ^0.1.0
+  icon_button_m3e: ^0.1.1
+  button_m3e: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.0.0.
+
+### Dependencies
+- flutter
+- m3e_design, fab_m3e, icon_button_m3e, button_m3e
+
+### Quick start
+```dart
+NavigationRailM3E(
+  selectedIndex: 0,
+  onDestinationSelected: (i) {},
+  expanded: true,
+  modal: false,
+  leading: const FabM3E(icon: Icon(Icons.add)),
+  destinations: const [
+    NavigationRailDestinationM3E(icon: Icon(Icons.inbox), label: 'Inbox'),
+    NavigationRailDestinationM3E(icon: Icon(Icons.send), label: 'Sent'),
+  ],
+)
+```
+
+### Key parameters
+- expanded: bool — Expanded vs collapsed rail.
+- modal: bool — Modal overlay vs standard inline rail.
+- destinations: List<NavigationRailDestinationM3E> — Items to render.
+- selectedIndex: int; onDestinationSelected: ValueChanged<int> — Selection handling.
+- leading / trailing: Widget? — Header/footer area.
+- fab / menu slots: Widgets for actions and menus.
+- badgeBuilder / badgeCount: Optional per-item badges.
+
+### Theming with m3e_design
+Rail colors, indicator style, and typography adapt from M3ETheme.
+
+### Accessibility
+- Keyboard navigation, focus order, and semantics supported.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/navigation_rail_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/navigation_rail_m3e/lib/src/rail_item.dart
+++ b/packages/navigation_rail_m3e/lib/src/rail_item.dart
@ -36,7 +36,6 @@ class RailItem extends StatelessWidget {
  Widget build(BuildContext context) {
    final theme = Theme.of(context).extension<NavigationRailM3ETheme>() ??
        const NavigationRailM3ETheme();
-    final tokens = NavigationRailTokensAdapter(context);
    final height = destination.short ? theme.itemShortHeight : theme.itemHeight;

    final Widget button = RailItemButtonM3E(
--- a/packages/navigation_rail_m3e/pubspec.yaml
+++ b/packages/navigation_rail_m3e/pubspec.yaml
@ -11,18 +11,11 @@ environment:
 dependencies:
  flutter:
    sdk: flutter
-  # Integrates with your design system tokens.
  m3e_design:
-    path: ../m3e_design
-  # FAB components used by the rail (FabM3E and ExtendedFabM3E).
  fab_m3e:
-    path: ../fab_m3e
-  # Icon button used by the rail's menu control.
  icon_button_m3e:
-    path: ../icon_button_m3e
-  # Buttons used by rail items in expanded state.
  button_m3e:
-    path: ../button_m3e
+

 dev_dependencies:
  flutter_test:
--- a/packages/progress_indicator_m3e/README.md
+++ b/packages/progress_indicator_m3e/README.md
@ -30,3 +30,51 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+Material 3 Expressive progress indicators with token-aligned colors and shapes, providing circular and linear variants with determinate and indeterminate modes.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  progress_indicator_m3e: ^0.3.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.3.0; Flutter >=3.19.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+// Indeterminate
+const CircularProgressIndicatorM3E()
+
+// Determinate
+const LinearProgressIndicatorM3E(value: 0.6)
+```
+
+### Key parameters
+- value: double? — 0.0..1.0 for determinate; null for indeterminate.
+- semanticsLabel: String? — Describe progress for screen readers.
+- backgroundColor / color: Color? — Override token colors.
+
+### Theming with m3e_design
+Colors, track heights, and indicator shapes are driven by M3E tokens.
+
+### Accessibility
+- Always provide semanticsLabel when indeterminate; ensure sufficient contrast.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/progress_indicator_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/progress_indicator_m3e/pubspec.yaml
+++ b/packages/progress_indicator_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/slider_m3e/README.md
+++ b/packages/slider_m3e/README.md
@ -85,3 +85,66 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+SliderM3E and RangeSliderM3E that follow Material 3 Expressive tokens for colors, shapes, and density.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  slider_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.22.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+// Single-value slider
+SliderM3E(
+  value: value,
+  onChanged: (v) => setState(() => value = v),
+  min: 0,
+  max: 100,
+  divisions: 10,
+  label: '$value',
+)
+
+// Range slider
+RangeSliderM3E(
+  values: range,
+  onChanged: (r) => setState(() => range = r),
+  min: 0,
+  max: 100,
+)
+```
+
+### Key parameters
+- value: double — Current slider value (SliderM3E).
+- values: RangeValues — Current range (RangeSliderM3E).
+- onChanged: ValueChanged<double/RangeValues> — Callback for value changes.
+- min / max / divisions: Configure value domain and discrete steps.
+- label: String? — Optional value label.
+- activeColor / inactiveColor / thumbColor: Color? overrides.
+
+### Theming with m3e_design
+Track shape, thickness, and colors follow M3E tokens; respects density.
+
+### Accessibility
+- Ensure sufficient contrast; provide semantics via labels when necessary.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/slider_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/slider_m3e/lib/src/slider_m3e_widget.dart
+++ b/packages/slider_m3e/lib/src/slider_m3e_widget.dart
@ -17,5 +17,3 @@ class SliderM3EWidget extends StatelessWidget {
    );
  }
 }
-
-String _pascal(String s) => s.split('_').map((p) => p.isEmpty ? '' : (p[0].toUpperCase() + p.substring(1))).join();
--- a/packages/slider_m3e/pubspec.yaml
+++ b/packages/slider_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/split_button_m3e/README.md
+++ b/packages/split_button_m3e/README.md
@ -149,3 +149,59 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+SplitButtonM3E: a two-part button with a primary action and a dropdown menu, with sizes, variants, shapes, and accessible minimum hit targets. Keyboard navigation supported.
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design.
+- Pub (when published):
+```yaml
+dependencies:
+  split_button_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.9.2; Flutter >=1.17.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+SplitButtonM3E(
+  label: const Text('Share'),
+  primaryAction: () { /* do default share */ },
+  menuItems: const [
+    SplitButtonItemM3E(label: Text('Copy link'), value: 'copy'),
+    SplitButtonItemM3E(label: Text('Email'), value: 'email'),
+  ],
+  onSelected: (value) {
+    // handle from menu
+  },
+)
+```
+
+### Key parameters
+- label: Widget — Visible label next to the caret.
+- primaryAction: VoidCallback — Action when the main segment is tapped.
+- menuItems: List<SplitButtonItemM3E> — Menu options.
+- onSelected: ValueChanged<T> — Callback when a menu item is chosen.
+- variant/style: filled | tonal | elevated | outlined.
+- size: xs | sm | md | lg | xl.
+- shapeFamily: round | square.
+- isExpanded: bool — Whether to take full width when allowed.
+
+### Accessibility
+- Both segments meet 48×48dp minimum size; keyboard and screen reader friendly.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/split_button_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/split_button_m3e/pubspec.yaml
+++ b/packages/split_button_m3e/pubspec.yaml
@ -12,7 +12,6 @@ dependencies:
  flutter:
    sdk: flutter
  m3e_design:
-    path: ../m3e_design

 dev_dependencies:
  flutter_test:
--- a/packages/toolbar_m3e/README.md
+++ b/packages/toolbar_m3e/README.md
@ -94,3 +94,56 @@ flutter run -d chrome
 ```

 _Last updated: 2025-10-23_
+
+
+---
+
+## Detailed Guide
+
+### What this package provides
+ToolbarM3E with token-driven size, density, color, shape, and overflow handling (e.g., automatic menu when there isn’t enough space).
+
+### Installation
+- Monorepo (local path): already configured alongside m3e_design and button/icon packages.
+- Pub (when published):
+```yaml
+dependencies:
+  toolbar_m3e: ^0.1.0
+  m3e_design: ^0.1.0
+```
+
+Minimum SDK: Dart >=3.5.0; Flutter >=3.22.0.
+
+### Dependencies
+- flutter
+- m3e_design
+
+### Quick start
+```dart
+ToolbarM3E(
+  actions: [
+    ToolbarActionM3E(icon: Icons.copy, onPressed: () {}),
+    ToolbarActionM3E(icon: Icons.paste, onPressed: () {}),
+    ToolbarActionM3E(icon: Icons.delete_outline, onPressed: () {}),
+  ],
+  overflowBehavior: ToolbarOverflowBehaviorM3E.menu,
+)
+```
+
+### Key parameters
+- actions: List<ToolbarActionM3E> — Items shown on the toolbar.
+- overflowBehavior: menu | wrap | clip — How to handle overflow.
+- density: compact | regular — Affects height and spacing.
+- backgroundColor / foregroundColor: Color? overrides.
+- shapeFamily: round | square.
+
+### Theming with m3e_design
+Toolbar colors, shape, and spacing come from M3ETheme tokens; density adjusts measurements.
+
+### Accessibility
+- Buttons maintain 48×48dp minimum; provide tooltips/semantics for each action.
+
+### Links
+- Repository: https://github.com/EmilyMoonstone/material_3_expressive/tree/main/packages/toolbar_m3e
+- Issue tracker: https://github.com/EmilyMonestone/material_3_expressive/issues
+- Changelog: ./CHANGELOG.md
--- a/packages/toolbar_m3e/lib/src/toolbar_m3e_widget.dart
+++ b/packages/toolbar_m3e/lib/src/toolbar_m3e_widget.dart
@ -13,9 +13,8 @@ class ToolbarM3EWidget extends StatelessWidget {
        color: m3e.colors.surfaceStrong,
        borderRadius: m3e.shapes.square.md,
      ),
-      child: Text('Toolbar placeholder', style: m3e.typography.base.titleMedium),
+      child:
+          Text('Toolbar placeholder', style: m3e.typography.base.titleMedium),
    );
  }
 }
-
-String _pascal(String s) => s.split('_').map((p) => p.isEmpty ? '' : (p[0].toUpperCase() + p.substring(1))).join();