material_design 0.7.0

The fastest path to consistent Material Design UIs in Flutter. Build beautiful apps aligned with official metrics and guidelines using a powerful set of ready-to-use design tokens and helper widgets.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.7.0

BREAKING CHANGES

• Tokens: The Material 3 token system has been completely refactored for better organization and clarity.
  • System tokens are now organized under lib/src/m3/tokens/sys/. This includes Color, Elevation, Motion, Shape, Spacing, and Typography.
  • Many token files have been moved, renamed, or consolidated. Please refer to the updated documentation for the new token structure.
  • The M3Theme class has been removed as part of this refactoring.

Features

• Components: Added a new Material 3 Button component (M3CompButton).
• Tokens: Introduced new system tokens for Elevation, Motion, Shape, Spacing, and StateLayerOpacity.

Refactor

• Refactored the entire token system to align more closely with the official Material Design 3 specifications.
• Renamed and moved several internal utilities and classes to a new mt (Material Toolkit) namespace for better internal structure.
• Updated the example application to reflect all the latest changes and new APIs.
• Renamed the "Density" showcase page to "Visual Density" for clarity.

Chores

• Updated .gitignore to exclude new generated files.
• Updated README.md with the latest information.

0.6.2

Major Refactoring: Token System Overhaul

• Shape System: Replaced BoxDecoration with ShapeDecoration across the example app for better semantics. Introduced M3BorderRadius and converted M3Radius from double to Radius constants, providing a more robust and type-safe way to define shapes.
• Motion Tokens: Consolidated motion-related tokens. M3MotionDuration and M3MotionEasing have been merged into a single, more organized m3_motion.dart file under the sys directory, improving clarity and discoverability.
• File Structure: Reorganized the token file structure to better align with the Material Design 3 system. Legacy and unused token files like M3ColorRoles, m3_radius.dart (the old double based one), and m3_examples.dart have been removed to streamline the package.

Breaking Changes

• Removed M3ColorRoles: The static M3ColorRoles class has been removed. Please use the color scheme provided by the M3Theme or Theme.of(context).colorScheme for semantic color access.
• Removed M3Radius (as double): The M3Radius class that provided double values has been replaced by M3BorderRadius (which provides BorderRadius objects) and a new M3Radius class that provides Radius objects.
• Consolidated Motion Tokens: M3MotionDuration and M3MotionEasing are no longer separate files. Import package:material_design/material_design.dart and use the M3MotionDuration and M3MotionEasing classes directly.

Enhancements & Fixes

• Code Cleanup: Performed a general code cleanup, removing obsolete files and refactoring the example app for better readability and consistency.
• Shape Implementation: Consistently replaced BorderRadius.circular() with the new M3BorderRadius constants throughout the example app.
• New md Module: Introduced a new md module for future development, starting with a new barrel file md.dart.

0.6.1

Refinements and Internationalization

• Refactored README: Simplified the documentation to focus on core features and improve clarity.
• Internationalized Example App: All user-facing strings in the accessibility showcase are now in English, making the example more accessible to a global audience.
• Code Cleanup: Minor code cleanup and refactoring in the example app for better readability and maintenance.

0.6.0

New Features

• Complete M3 Theme System: Introduced M3Theme, an integrated theme builder that generates a complete ThemeData from a seed color, with full support for light, dark, and high-contrast modes.
• Comprehensive Accessibility Utilities: Added the M3Accessibility class, providing a suite of tools for building WCAG-compliant UIs, including accessible form fields, focus indicators, contrast checking, and touch target enforcement.
• Adaptive Design System: Implemented the M3Adaptive class with helpers for responsive layouts (M3Adaptive.responsiveLayout), adaptive navigation (M3AdaptiveScaffold), and adaptive components that adjust to different screen sizes and platforms.
• Advanced Token Utilities: Added new utility classes for enhanced token functionality:
  • M3TypeScale: Responsive and accessible typography helpers.
  • M3ColorUtils: Color manipulation and contrast validation.
  • M3ShapeUtils: Responsive and brand-specific shape generation.
  • M3MotionUtils: Contextual animation patterns (fade, slide, scale).

Breaking Changes

• Token Architecture Refactor: The entire token system has been restructured to follow the official Material Design 3 hierarchy:
  • Reference Tokens (Ref): Foundational values (e.g., M3RefPalette, M3RefDuration).
  • System Tokens (Sys): Semantic roles (e.g., M3SysColor).
  • Component Tokens (Comp): Component-specific values (e.g., M3CompButton).
• The old token structure is now considered legacy and will be deprecated in a future version.

Enhancements & Fixes

• Example App Overhaul: The example app has been completely reorganized into Foundations, Styles, and Components sections to provide a comprehensive showcase of all new features and the new token architecture.
• Documentation: Massively updated README.md and added ENHANCED_FEATURES.md to document the new capabilities.
• Code Quality: Refactored numerous widgets and classes for better organization, consistency, and adherence to M3 specifications.

0.5.1

• BREAKING: Renamed M3Margins to M3Margin and M3Spacers to M3Spacer for better naming consistency.
• DOCS: Updated README.md to reflect the new class names and provide clearer examples.
• CHORE: Updated the example app to use the new M3Margin and M3Spacer classes.

0.5.0

• BREAKING: Token classes are now abstract class instead of abstract final class to allow for extension.
• BREAKING: Change dart version from 3.8.1 to >=2.17.0 <4.0.0 to allow for extension.
• BREAKING: The equatable dependency has been removed.
• FEAT: Added M3Margins and M3Spacers classes for more semantic layout spacing.
• FEAT: Added new radius and shape tokens (largeIncreased, extraLargeIncreased, extraExtraLarge).
• FEAT: The example app has been revamped to better demonstrate the updated tokens, including a new LaunchURLText widget.
• CHORE: Lowered the minimum Dart SDK requirement from 3.8.1 to 2.17.0 for wider project compatibility.
• CHORE: As restrições do SDK do Flutter e do Dart foram atualizadas.
• CHORE: very_good_analysis has been commented out in analysis_options.yaml.
• DOCS: README.md has been updated with the latest changes.

0.4.1

• BREAKING: Renamed M3Opacity to M3StateLayerOpacity to better reflect its purpose.
• feat: Added LaunchURLText widget to the example app for styled URL links.
• feat: Added M3StateLayerOpacityButtonExample to demonstrate state layer opacity on a custom button.
• refactor: Updated the example app to consistently use Theme.of(context).textTheme for typography.
• docs: Updated README.md with the latest changes and examples.

0.4.0

• BREAKING: M3Motion has been refactored into M3MotionDuration and M3MotionEasing to better align with the Material Design 3 specifications.
• BREAKING: M3Density has been removed and replaced with M3VisualDensity, which uses Flutter's native VisualDensity class.
• FEAT: Added new icon sizes: dense, medium, large, and extraLarge to M3IconSize.
• FEAT: The M3Shadow implementation has been revised, including a new fromElevation method.
• FEAT: Added the url_launcher dependency for opening URLs.
• FIX: The Z-Index section on the example page has been reworked for a better visual demonstration.
• CHORE: Various formatting and code cleanup improvements in the example app.

0.3.0

• Breaking Change: Renamed all tokens from Material* to M3* (e.g., MaterialTonalColor to M3TonalColor) to align with Material Design 3 naming conventions and avoid conflicts with Flutter's Material class.
• Breaking Change: Reorganized the file structure by moving all token files to lib/src/m3/tokens/ and renaming them with the m3_ prefix (e.g., motion.dart to m3_motion.dart). This improves clarity and consistency.
• Feat: Implemented a responsive layout in the example app using NavigationRail and NavigationDrawer to showcase the M3Breakpoint token.
• Fix: Updated the copyright year in the LICENSE file.
• Chore: Updated pubspec.yaml by removing the homepage field and adding issue_tracker.

0.2.6

• Feat: Added MaterialDensity token to control UI density.
• Refactor: Replaced MaterialColorScheme.create with ColorScheme.fromSeed to align with Flutter's core API.
• Refactor: Refined motion tokens by separating them into MotionEasing and MotionDuration for more granular control.
• Example: Added a new DensityPage to the example app to showcase the MaterialDensity token.
• Example: Updated the example app to use the new motion tokens and ColorScheme.fromSeed.

0.2.5

• Refactor: The MaterialMotionToken has been renamed to MotionScheme to better align with the Material Design 3 specifications.
• Feature: Introduced MotionDurations and MotionEasings classes to provide more granular control over animation durations and easing curves.
• Example: Simplified the elevation page logic and updated the motion page to use the new MotionScheme.

0.2.4

• Refactor: Renamed MaterialSurface to MaterialTonalColor and its method getTintedColor to fromElevation for better alignment with Material Design 3 terminology, where tonal colors are applied based on surface elevation.
• Refactor: Renamed MaterialColorSchemes to MaterialColorScheme to maintain consistency with Flutter's ColorScheme.
• Feat: Added detailed comments to MaterialBreakpoint explaining the different breakpoint values based on the Material Design 3 guidelines.
• Feat: Added allLevels to MaterialElevation, providing a convenient list of all elevation levels.
• Fix: Ignored .vscode/ and .env files in .gitignore to avoid committing editor-specific settings and environment variables.
• Example: Updated the example app to use MaterialTonalColor.fromElevation and other related changes.

0.2.3

• Docs: Added detailed examples to README.md for MaterialBorder, MaterialOpacity, MaterialBreakpoint, MaterialIconSize, and MaterialZIndex.
• Example: Added a new MotionPage to the example app to showcase all MaterialMotion tokens.
• Example: Updated the OtherTokensPage in the example app to include showcases for MaterialBreakpoint, MaterialIconSize, and MaterialZIndex.
• Refactor: Renamed MotionToken to MaterialMotionToken for better clarity and consistency.
• Fix: Removed MaterialBorder.none as it was redundant (equivalent to 0).

0.2.2

Changed

• Docs README.md with clearer instructions and updated usage examples.

0.2.1

Changed

• Renamed MaterialColorSchemes to MaterialColorScheme.
• Removed static schemes lightScheme and darkScheme; use the create() method instead.

0.2.0

Added

• MaterialSurface Utility: Introduced a new utility class with a getTintedColor() method to easily apply Material 3 surface tint based on elevation. This encapsulates the ElevationOverlay logic into a clean, reusable token.

0.1.0

Added

• Complete Material 3 Token System:
  • MaterialColorSchemes: Light and dark color schemes generated from a seed color.
  • MaterialTypeScale: Full set of 15 M3 text styles (Display, Headline, Title, Body, Label).
  • MaterialShape: ShapeBorder tokens for all M3 corner radius levels.
  • MaterialShadow: BoxShadow tokens aligned with the 6 elevation levels of M3.
  • MaterialBorder: Tokens for border widths.
• Style Guide Example: The example app was completely rewritten to serve as a visual style guide for all tokens.
• Barrel Files: Added barrel files for easy token import by category (color, typography, geometry, etc.).

Changed

• Refactored MaterialOpacity: Aligned with M3 state layer values (Hover, Focus, Press, Drag) and disabled opacities.
• Refactored MaterialRadius: Values adjusted to match the M3 corner radius token scale.
• Refactored MaterialIconSize: Simplified to focus on the default 24dp size, with guidance for contextual usage.
• Refactored motion.dart: Fixed asTween return type to Animatable<T> to ensure proper typing.

0.0.1

Added

• Introduced MaterialElevation tokens for consistent elevation styling.