Material Design 3 for Flutter

🎨 A complete Material Design 3 design system implementation for Flutter

A comprehensive design system toolkit that brings Google's Material Design 3 specifications to Flutter through a carefully architected token system.

🚀 Live Demo & Resources

🌟 Interactive Design System Explorer - Explore all tokens with live examples

📚 Material Design 3 Guidelines - Official specification

📦 Installation

dependencies:
  material_design: ^0.28.1

🎯 Three Ways to Use This Library

✅ The Right Way: Material Design 3 Compliant

Use M3 wrapper classes that enforce design system rules while maintaining const performance.

// Best approach - follows M3 specs with const performance
// Motion example - impossible to mismatch
return AnimatedContainer(
  duration: M3Motion.emphasized.duration, // Always correct pairing   (non-const)
  curve: M3Motion.emphasized.curve,       // Follows M3 specs exactly (non-const)
   // M3EdgeInsets enforces token usage + const
  padding: const M3EdgeInsets.all(M3SpacingToken.space16), // (const)

  // M3ShapeDecoration ensures all properties follow M3
  decoration: M3ShapeDecoration(
    shape: M3Shape.medium,                                         // (const)
    boxShadow: M3Elevation.level3.shadows,                         // (non-const)
    color: M3Elevation.level3.surfaceColor(context),               // (non-const)
  ),

  child: const Text(
    'Perfect M3 Implementation',
    style: Theme.of(context).textTheme.headlineMedium,             // (non-const)
  ),
);

Why this is best:

• ✅ Forces Material Design 3 compliance
• ✅ Type-safe token usage
• ✅ Const performance where possible
• ✅ Impossible to break design system rules

⚠️ The Flexible Way: Trading Compliance for Freedom

Use const tokens directly with Flutter widgets. More flexible but can break M3 guidelines.

// Intermediate approach - flexible but can violate M3
AnimatedContainer(
  duration: M3MotionDuration.long2, // ⚠️ Is this the right duration? (const)
  curve: M3MotionCurve.standard,    // ⚠️ Wrong curve for long2!      (const)
  // Using const tokens but might mix incorrectly
  padding: const EdgeInsets.all(M3Spacings.space16), // (const)

  decoration: ShapeDecoration(
    borderRadius: M3Shape.medium,                    // (const)
    boxShadow: M3ElevationShadows.level3,            // (const)
    color: M3Elevation.level3.surfaceColor(context), // (non-const)
  ),

  child: const Text(
    'Partial M3 Implementation',
    style: M3TextStyle.headlineMedium,               // (const)
  ),
);

Trade-offs:

• ⚠️ Can mix incompatible tokens
• ⚠️ May violate M3 specifications
• ✅ More flexibility for custom designs
• ✅ Still has const performance

❌ The Wrong Way: Worst of Both Worlds

Using token enums with .value - loses const performance AND design system benefits.

// DON'T DO THIS - no benefits, only drawbacks
Container(
  // ❌ Lost const performance
  padding: EdgeInsets.all(M3SpacingToken.space16.value), // (non-const)

  decoration: BoxDecoration(
    // ❌ Still not const
    borderRadius: BorderRadius.circular(M3CornerToken.medium.value), // (non-const)

    // ❌ Can still break M3 rules
    boxShadow: [
      BoxShadow(
        offset: const Offset(0, 2),  // ❌ Random shadow values
        blurRadius: M3SpacingToken.space4.value,  // ❌ Why use spacing for blur?
      ),
    ],
    color: Colors.purple, // ❌ Missing surface tint. Not M3 surface color! (const)
  ),

  child: Text(
    'Worst Implementation',
    // ❌ Mixing approaches inconsistently
    style: TextStyle(fontSize: 17),
  ),
);

Why this is wrong:

• ❌ No const performance (using .value)
• ❌ No design system enforcement
• ❌ Verbose without benefits
• ❌ Easy to misuse tokens

📖 How to Use Each Class

✅ 🎯 Design System Classes (Use These First - M3 Compliant)

Typography & Text

Spacing & Layout

Shape & Borders

Decorations

Elevation & Shadows

Motion & Animation

Responsive Layout

Available Token Enums (Use wrapper classes instead)

🔧 Helper Functions & Utilities

✅ ⚠️ For Maximum Flexibility: Using const Tokens Directly

Spacing & Layout Tokens

Shape & Border Tokens

Motion Tokens

Visual Effect Tokens

Responsive Tokens

⚠️ Token Enums (Avoid Using .value Directly)

❌ Why to Avoid

🎯 Summary

Choose Your Approach

1. Need Material Design 3 compliance? → Use M3 wrapper classes
2. Need flexibility with good performance? → Use const tokens directly
3. Never do this → Don't use .value on token enums

Performance vs Compliance Matrix

📊 Complete Token and Utility Reference

Design Tokens

These are constant values that form the foundation of your design system, ensuring consistency across spacing, colors, typography, and more.

🟢 CONST Design Tokens

Use these with const keyword for best performance:

🔵 NON-CONST Tokens (Enums and Functions)

Use these WITHOUT const keyword - values calculated at runtime:

Utility & Helper Classes

These are classes that help apply design tokens in a type-safe and responsive way.

📚 Further Reading

• Material Design 3 Specification
• Full API Documentation

📄 License

BSD License - see LICENSE file

Building consistent, beautiful Flutter apps with Material Design 3