Flutter Minimal Design #

A production-ready Flutter design system that ships the hard parts of spacing, typography, color, and standard components so you can focus on product work instead of recreating UI foundations.

Why This Exists #

• Opinionated design tokens that already follow accessibility constraints (44 px touch targets, readable contrast).
• ScreenUtil-driven scaling that keeps your spacing and typography consistent across devices.
• Drop-in components (screen wrapper, buttons, form fields, rich text) that expose copyWith APIs instead of forcing forks.
• Zero-config color system with optional palette overrides.
• Battle-tested defaults for loading/error states, navigation patterns, and responsive padding.

Table of Contents #

1. Installation
2. Quick Start
3. Design Tokens
   • Spacing Scale
   • Spacing Helpers
   • Size & Radius Tokens
   • Typography
   • Color System
4. Core Components
   • CustomScreen
   • AppAppBar
   • Text System
   • Buttons
   • Form Fields
   • Rich Text
5. Utilities & Extensions
6. Putting It Together
7. Customization Playbook
8. FAQ & Troubleshooting
9. Contributing
10. License

Installation #

Add the package and its peer dependencies to pubspec.yaml:

dependencies:
  flutter_minimal_design: ^1.0.7
  flutter_screenutil: ^5.9.3
  flutter_svg: ^2.2.1

Then fetch packages:

flutter pub get

Quick Start #

1. Wrap your app with ScreenUtilInit #

The design system assumes a 375 × 812 design canvas (iPhone 11/12). ScreenUtil handles scaling.

import 'package:flutter/material.dart';
import 'package:flutter_screenutil/flutter_screenutil.dart';
import 'package:flutter_minimal_design/flutter_minimal_design.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return ScreenUtilInit(
      designSize: const Size(375, 812),
      minTextAdapt: true,
      splitScreenMode: true,
      builder: (context, _) => MaterialApp(
        title: 'Minimal Design Demo',
        debugShowCheckedModeBanner: false,
        home: const HomeScreen(),
      ),
    );
  }
}

2. Use the screen wrapper everywhere #

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    DSTextStyles.initialize(context); // once per app (optional)

    return CustomScreen(
      title: 'Dashboard',
      body: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          CustomAppText('Welcome back', style: DSTextStyles.pageTitle),
          DSVSpace.xlg,
          DSButton.primary(label: 'Get Started', onPressed: () {}),
        ],
      ),
    );
  }
}

Design Tokens #

Spacing Scale #

DSSpacing exposes actual base pixel values. ScreenUtil converts them to responsive logical pixels using .h (height) and .w (width).

Use vertical helpers (DSVSpace.*) between Column children and horizontal helpers (DSHSpace.*) inside Rows.

Spacing Helpers #

Size & Radius Tokens #

Typography #

The text system adapts to your theme font. Call DSTextStyles.initialize(context) once after MaterialApp builds to read ThemeData.textTheme.

Color System #

DSColors ships with a neutral palette that works in light mode out of the box. Override by providing a ColorSource.

Color utilities include gradients, glass effects, accessible contrasts, and string parsing ('#0D9488'.toColor()).

Core Components #

CustomScreen #

The universal scaffold. Handles safe areas, responsive padding, loading/error states, bottom sheets, and navigation. Key properties:

CustomScreen(
  title: 'Profile',
  appBarLeadingWidget: const BackButton(),
  showLeadingBorder: false,
  isLoading: state.isLoading,
  hasError: state.hasError,
  onRetry: () => refetch(),
  body: Padding(
    padding: DSEdgeInsets.container,
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: const [
        CustomAppText('Account', style: DSTextStyles.sectionHeader),
        DSVSpace.md,
        CustomAppText('Edit your information', style: DSTextStyles.body),
      ],
    ),
  ),
);

AppAppBar #

A lean app bar that respects the design tokens. Supports:

• Custom leading widgets with optional border (default width 1 px using DSSpacing.lg).
• Automatic back navigation via NavigationUtils.defaultBackAction(context).
• Optional trailing widget and brand colors.

AppAppBar(
  title: 'Settings',
  leadingWidget: IconButton(
    icon: const Icon(Icons.close),
    onPressed: () => NavigationUtils.defaultBackAction(context),
  ),
  showLeadingBorder: false,
  endWidget: IconButton(
    icon: const Icon(Icons.more_vert),
    onPressed: () {},
  ),
);

Text System #

Use CustomAppText for quick text rendering. It defaults to DSTextStyles.body and forwards every Text parameter.

CustomAppText(
  'Invite friends',
  style: DSTextStyles.subheader,
  color: DSColors.textPrimary,
  maxLines: 2,
  overflow: TextOverflow.ellipsis,
);

DSTextStyles.initialize(context) is idempotent—call it once after the first frame if you need the ThemeData font family.

Buttons #

DSButton exposes pre-configured constructors: primary, secondary, success, danger, text, warning.

DSButton.primary(
  label: 'Continue',
  onPressed: () {},
);

DSButton.text(
  label: 'Skip for now',
  onPressed: () {},
);

Gradient Buttons - Create stunning gradient buttons with full control:

// Basic gradient button
CustomButton(
  label: 'Gradient Button',
  onPressed: () {},
  useGradient: true,
  gradient: LinearGradient(
    colors: [DSColors.primary, DSColors.secondary],
  ),
  textColor: Colors.white,
)

// Primary button with gradient
DSButton.primary(
  label: 'Continue',
  onPressed: () {},
  useGradient: true,
  gradient: LinearGradient(
    colors: [Color(0xFF1A4220), Color(0xFF2E7D32)],
  ),
)

// Radial gradient
CustomButton(
  label: 'Radial Gradient',
  onPressed: () {},
  useGradient: true,
  gradient: RadialGradient(
    colors: [Colors.orange, Colors.red],
    center: Alignment.center,
    radius: 0.8,
  ),
  textColor: Colors.white,
)

// Gradient with icon
CustomButton(
  label: 'Add to Cart',
  onPressed: () {},
  isIconButton: true,
  iconPath: 'assets/icons/cart.svg',
  iconColor: Colors.white,
  useGradient: true,
  gradient: LinearGradient(
    colors: [DSColors.primary, DSColors.primaryDark],
  ),
  textColor: Colors.white,
)

// Disabled gradient (automatically fades)
CustomButton(
  label: 'Disabled',
  onPressed: () {},
  enabled: false,
  useGradient: true,
  gradient: LinearGradient(
    colors: [Colors.blue, Colors.purple],
  ),
  textColor: Colors.white,
)

CustomButton Properties:

• useGradient - Enable gradient background
• gradient - LinearGradient, RadialGradient, or SweepGradient
• enabled - Automatically handles disabled state (fades gradient to 50% opacity)
• isIconButton - Add SVG icons to buttons
• iconPath, iconColor, iconSpacer - Icon customization
• labelSize, labelFontWeight - Text styling
• maxLines, overflow - Text overflow handling
• width, height, borderRadius, borderColor - Layout control

Reach for CustomButton when you need deep customization (icon buttons, gradients, custom shapes). Base spacing and radii are applied for you.

Form Fields #

DSFormField variants cover email, password, phone, search, number, and text area. All inputs respect DSSize.formFieldHeight (48 px) and the shared padding.

DSFormField.password(
  controller: passwordController,
  labelText: 'Password',
  helperText: 'At least 8 characters',
);

For bespoke layouts use CustomAppTextFormField; you still inherit the DS styles and validators.

Rich Text #

DSRichText + DSTextSpan gives you structured text with mix-and-match styles and clickable links.

DSRichText(
  spans: [
    DSTextSpan.body('By continuing, you agree to our '),
    DSTextSpan.link('Terms', onTap: openTerms),
    DSTextSpan.body(' and '),
    DSTextSpan.link('Privacy Policy', onTap: openPrivacy),
  ],
);

Utilities & Extensions #

• Navigation: NavigationUtils.defaultBackAction(context) pops when possible, otherwise delegates to Navigator.of(context).maybePop().
• Color extensions: DSColors.primary.glass(), .softShadow(), .linearGradientTo(DSColors.secondary), .blend(), .hasGoodContrast(Colors.white).
• Context shortcuts: context.primaryColor, context.secondaryColor, context.textColor, etc.
• Spacing widgets: DSVSpace.*, DSHSpace.*, and DSSizedBox for icons/avatars.

Putting It Together #

class CheckoutScreen extends StatelessWidget {
  const CheckoutScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return CustomScreen(
      title: 'Checkout',
      appBarEndWidget: IconButton(
        icon: const Icon(Icons.help_outline),
        onPressed: () {},
      ),
      body: Padding(
        padding: DSEdgeInsets.container,
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            CustomAppText('Order summary', style: DSTextStyles.sectionHeader),
            DSVSpace.lg,
            Container(
              padding: DSEdgeInsets.card,
              decoration: BoxDecoration(
                color: DSColors.surface,
                borderRadius: DSRadius.lg,
                boxShadow: DSColors.primary.softShadow(),
              ),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  CustomAppText('Pro Plan', style: DSTextStyles.subheader),
                  DSVSpace.sm,
                  DSRichText(
                    spans: [
                      DSTextSpan.caption('Billed at '),
                      DSTextSpan.bold('\$69.00'),
                      DSTextSpan.caption('/year'),
                    ],
                  ),
                ],
              ),
            ),
            const Spacer(),
            DSButton.primary(label: 'Pay now', onPressed: () {}),
          ],
        ),
      ),
    );
  }
}

Customization Playbook #

1. Change the color palette

   class AppColors extends ColorSource {
     @override
     Color get primary => const Color(0xFF0D9488);
     @override
     Color get secondary => const Color(0xFFFF4893);
     // override only what you need
   }
   
   void main() {
     DSColors.setSource(AppColors());
     runApp(const MyApp());
   }
   

2. Adopt a custom font

   MaterialApp(
     theme: ThemeData(fontFamily: 'Cairo'),
     home: Builder(
       builder: (context) {
         DSTextStyles.initialize(context);
         return const HomeScreen();
       },
     ),
   );
   

3. Tune spacing per screen

   CustomScreen(
     padding: DSEdgeInsets.screen.copyWith(top: DSSpacing.xxxlg.vertical),
     body: ...,
   );
   

4. Override button styling globally

   final button = DSButton.primary(
     label: 'Confirm',
     onPressed: () {},
   ).copyWith(
     backgroundColor: DSColors.secondary,
     textStyle: DSTextStyles.button.copyWith(color: DSColors.textOnPrimary),
   );
   

FAQ & Troubleshooting #

Spacing looks wrong on tablets. Make sure every screen sits under ScreenUtilInit. Use enableScroll: true on CustomScreen to keep content responsive.

Fonts didn't change after I set a new family. Call DSTextStyles.initialize(context) after the theme is loaded (e.g. inside the first screen using WidgetsBinding.instance.addPostFrameCallback). The call is safe to execute multiple times but will only initialize once.

Back button pops the app instead of the current route. If you override onBackPressed, call NavigationUtils.defaultBackAction(context) inside your handler to keep the default logic.

Do I need flutter_svg? We rely on flutter_svg for icon buttons and rich illustrations in the example components. If you don't use SVG assets you can omit it, but keep the dependency aligned with the versions above to avoid analyzer warnings.

Contributing #

Pull requests, issues, and feature proposals are welcome. Please see the issue tracker for current priorities. Run flutter analyze and include sample usage when you add new components.

License #

MIT License © Amr Ibrahim

See CHANGELOG.md for detailed release notes.