save_points_screen_builder 1.0.1

A modular, configuration-driven screen generator for common Flutter application flows with Material 3 support.

Save Points Screen Builder 🚀

A modular, configuration-driven screen generator for Flutter 3 applications with modern Material 3 design system. Build beautiful, production-ready screens with minimal code using the builder pattern.

✨ Features

• 🎨 Modern Material 3 Design System - Professional color scheme, typography, and spacing system
• 🏗️ Builder Pattern API - Fluent, chainable APIs for all screen types
• 📝 Form Engine - Dynamic form generation with enhanced UI components
• 📦 List Engine - Declarative list/grid layouts with modern card designs
• 🎯 Type Safe - Strong typing and null safety throughout
• 🔧 Highly Extensible - Easy to customize and extend with reusable UI components
• 📱 Responsive - Adaptive layouts for mobile, tablet, and desktop
• ♿ Accessible - WCAG AA compliant with proper contrast ratios
• 🌓 Dark Mode - Complete light and dark theme support
• ✨ Modern UI Components - 15+ reusable components (cards, buttons, badges, etc.)

📦 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  save_points_screen_builder: ^1.0.1

Then run:

flutter pub get

🎯 Supported Screen Types

Static Screens (5)

• ✅ Splash Screen - Modern animated splash
• ✅ Onboarding - Multi-page with smooth transitions
• ✅ Welcome Screen - Eye-catching landing page
• ✅ Success Screen - Confirmation with animations
• ✅ Error Screen - User-friendly error handling

Form-Based Screens (5)

• ✅ Sign In - Gradient backgrounds, social login
• ✅ Sign Up - Multi-step registration
• ✅ OTP/Verification - Code input with auto-focus
• ✅ Forgot Password - Password reset flow
• ✅ Edit Profile - User profile management

List-Based Screens (5)

• ✅ Product Lists - Modern grid with enhanced cards
• ✅ Shopping Cart - Item management with totals
• ✅ Settings - Grouped settings with icons
• ✅ Profile - User stats and information
• ✅ Notifications - Categorized notification list

🚀 Quick Start

Setup Theme (Required)

First, apply the modern Material 3 theme:

import 'package:flutter/material.dart';
import 'package:save_points_screen_builder/save_points_screen_builder.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      debugShowCheckedModeBanner: false,
      theme: AppTheme.lightTheme,      // 🎨 Modern light theme
      darkTheme: AppTheme.darkTheme,   // 🌙 Modern dark theme
      themeMode: ThemeMode.system,     // 🔄 Auto-switch based on system
      home: const HomePage(),
    );
  }
}

1. Splash Screen

import 'package:save_points_screen_builder/save_points_screen_builder.dart';

SplashScreenBuilder()
  .headline('My App')
  .subtitle('Welcome')
  .colorScheme(ColorScheme.fromSeed(seedColor: Colors.indigo))
  .animation(SplashAnimation.fadeIn)
  .duration(const Duration(seconds: 3))
  .onFinish(() => Navigator.pushReplacementNamed(context, '/home'))
  .build();

2. Sign In Screen (Modern UI)

SignInScreenBuilder()
  .title('Welcome Back')
  .subtitle('Sign in to continue')
  .submitButton(
    label: 'Sign In',
    onSubmit: (formData) async {
      await authService.signIn(
        email: formData['email'],
        password: formData['password'],
      );
    },
  )
  .onForgotPassword(() => Navigator.pushNamed(context, '/forgot-password'))
  .onSignUp(() => Navigator.pushNamed(context, '/sign-up'))
  .socialLogin([
    SocialLoginButton.google(() => handleGoogleSignIn()),
    SocialLoginButton.apple(() => handleAppleSignIn()),
  ])
  .build();

Features:

• ✨ Gradient background (Primary → Tertiary)
• 📱 Responsive layout (max-width: 480dp on large screens)
• 🎨 Elevated form card with modern shadows
• 🔐 Enhanced password field with show/hide toggle
• 🌐 Social login buttons with modern styling

3. Product List Screen (Enhanced Cards)

ProductListScreenBuilder()
  .title('Products')
  .layout(ListLayout.grid(columns: 2, aspectRatio: 0.7))
  .dataLoader(() async => await api.getProducts())
  .itemBuilder(ProductCardBuilder()) // Uses built-in modern card design
  .onItemTap((product) => Navigator.push(
    context,
    MaterialPageRoute(
      builder: (_) => ProductDetailScreen(product),
    ),
  ))
  .enableRefresh()
  .build();

The ProductCardBuilder() provides:

• 🎨 Gradient placeholders for missing images
• 🏷️ Category badges directly on cards
• ⭐ Star ratings with review counts
• ❤️ Gradient favorite button container (optional)
• 🛒 Gradient add-to-cart button (optional)
• 📦 Modern shadows and border styling

Custom Product Cards:

// If you need custom styling
ListScreenBuilder<Product>()
  .itemBuilder(
    CustomItemBuilder<Product>(
      (context, product, index) => Card(
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Image.network(product.imageUrl),
            Padding(
              padding: EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(product.name, style: TextStyle(fontWeight: FontWeight.bold)),
                  Text('\$${product.price.toStringAsFixed(2)}'),
                ],
              ),
            ),
          ],
        ),
      ),
    ),
  )
  .build();

4. Using Modern UI Components

import 'package:save_points_screen_builder/save_points_screen_builder.dart';

// Modern Card
ModernCard(
  child: YourContent(),
  onTap: () => print('Tapped!'),
)

// Gradient Button
GradientButton(
  label: 'Get Started',
  icon: Icons.rocket_launch,
  onPressed: () {},
)

// Empty State
EmptyState(
  icon: Icons.inbox_outlined,
  title: 'No items found',
  subtitle: 'Start by adding your first item',
  action: FilledButton(
    onPressed: () {},
    child: Text('Add Item'),
  ),
)

// Modern List Tile
ModernListTile(
  leadingIcon: Icons.settings,
  title: 'Settings',
  subtitle: 'App preferences',
  onTap: () {},
)

📖 Documentation

📚 Complete Documentation

• Design System Guide - Complete design system documentation (500+ lines)
• Quick Start Guide - Get started in 5 minutes
• Redesign Summary - Overview of all UI improvements

Architecture Overview

The package follows clean architecture principles with clear separation of concerns:

save_points_screen_builder/
├── lib/
│   ├── src/
│   │   ├── core/              # Base classes & configuration
│   │   ├── design_system/     # 🎨 Modern theme & UI components
│   │   ├── form_engine/       # Form field configs & validators
│   │   ├── list_engine/       # List layouts & item builders
│   │   ├── screens/
│   │   │   ├── static/        # Static screen builders
│   │   │   ├── forms/         # Form-based screen builders
│   │   │   └── lists/         # List-based screen builders
│   │   └── utils/             # Theme extensions & animations
│   └── save_points_screen_builder.dart    # Main export file

Core Concepts

1. ScreenBuilderConfig

Global configuration for customizing screens:

final config = ScreenBuilderConfig(
  seedColor: Colors.blue,
  fontFamily: 'Roboto',
  spacing: 8.0,
  borderRadius: 12.0,
  useSafeArea: true,
  pagePadding: EdgeInsets.all(16.0),
);

SignInScreenBuilder()
  .configuration(config)
  .build();

2. Form Engine

Dynamic form generation from field configurations:

FormFieldConfig.email(
  id: 'email',
  label: 'Email Address',
  hint: 'Enter your email',
  required: true,
  validator: Validators.combine([
    Validators.required(),
    Validators.email(),
  ]),
)

Available Field Types:

• text, email, password, phone, number
• multiline, search, url, otp
• dropdown, checkbox, switchToggle, slider
• date, time, datetime

Built-in Validators:

• required() - Field cannot be empty
• email() - Valid email format
• phone() - Valid phone format
• url() - Valid URL format
• minLength(int) - Minimum character length
• maxLength(int) - Maximum character length
• password() - Password strength validation
• numeric() - Numeric value only
• pattern(RegExp) - Custom regex pattern
• match(getValue, fieldName) - Match another field
• otp(length) - OTP code validation
• combine(validators) - Combine multiple validators

3. List Engine

Declarative list building with multiple layouts:

ListLayout.grid(
  columns: 2,
  aspectRatio: 0.75,
  crossAxisSpacing: 16,
  mainAxisSpacing: 16,
)

ListLayout.list(spacing: 8)

ListLayout.adaptive() // Responsive columns based on screen size

Item Builders:

All item builders accept a single WidgetBuilder function that returns the complete widget:

// Card-based list items
CardItemBuilder<Product>(
  (context, product, index) => Card(
    child: Column(
      children: [
        Image.network(product.imageUrl),
        Text(product.name),
        Text(product.description),
        Text(product.priceFormatted),
      ],
    ),
  ),
)

// List tile items
ListTileItemBuilder<Item>(
  (context, item, index) => ListTile(
    leading: Icon(item.icon),
    title: Text(item.title),
    trailing: Icon(Icons.chevron_right),
    onTap: () => handleTap(item),
  ),
)

// Grid tile items
GridTileItemBuilder<Product>(
  (context, product, index) => GridTile(
    child: Column(
      children: [
        Image.network(product.imageUrl),
        Text(product.name),
      ],
    ),
  ),
)

// Custom items - Full flexibility
CustomItemBuilder<T>(
  (context, item, index) => YourCustomWidget(
    item: item,
    index: index,
  ),
)

🎨 Design System

Modern Material 3 Theme

The package includes a complete, production-ready Material 3 design system:

Color System:

• Professional color palette (Primary, Secondary, Tertiary)
• Semantic colors (Error, Success, Warning, Info)
• Complete light and dark themes
• WCAG AA compliant contrast ratios

Typography:

• 13 text styles from Display (57sp) to Label (11sp)
• Optimized line heights and letter spacing
• Clear visual hierarchy

Spacing System:

• 4dp base spacing (4, 8, 12, 16, 20, 24, 32, 40, 48, 64dp)
• Predefined padding constants
• Consistent spacing throughout

Components:

• Border radius system (8dp, 12dp, 16dp, 24dp)
• Shadow system (Small, Medium, Large)
• Modern UI components library

Available UI Components

// Cards
ModernCard()          // Elevated card with shadow
GlassCard()          // Glass morphism effect

// Buttons
GradientButton()     // Gradient with loading state
IconButtonWithBackground()

// Text Fields
ModernTextField()    // Enhanced input field
ModernSearchField()  // Search with clear button

// Chips & Badges
ModernFilterChip()   // Filter with selection
ModernBadge()        // Badge for labels

// States
EmptyState()         // Beautiful empty state
ModernLoadingIndicator()

// Lists
ModernListTile()     // Enhanced list tile
SectionDivider()     // Section divider

// Avatars
ModernAvatar()       // Avatar with gradient

// Snackbars
ModernSnackBar.showSuccess()
ModernSnackBar.showError()
ModernSnackBar.showInfo()

Theme Customization

You can still customize the theme if needed:

ScreenBuilderConfig(
  colorScheme: ColorScheme.fromSeed(
    seedColor: Colors.indigo,
    brightness: Brightness.dark,
  ),
  textTheme: GoogleFonts.poppinsTextTheme(),
  appBarConfig: AppBarConfig(
    centerTitle: true,
    elevation: 0,
  ),
)

Custom Field Types

FormFieldConfig(
  id: 'custom',
  type: FormFieldType.custom,
  customBuilder: (context, config, controller) {
    return YourCustomFieldWidget(
      controller: controller,
      config: config,
    );
  },
)

Custom Item Builders

Create custom item builders by extending ItemBuilderBase:

class MyCustomItemBuilder<T> extends ItemBuilderBase<T> {
  @override
  Widget build(BuildContext context, T item, int index) {
    return MyCustomWidget(
      item: item,
      index: index,
      onTap: () => handleTap(item),
    );
  }
}

// Usage
ListScreenBuilder<MyItem>()
  .itemBuilder(MyCustomItemBuilder())
  .build();

Or use the simpler CustomItemBuilder:

ListScreenBuilder<MyItem>()
  .itemBuilder(
    CustomItemBuilder<MyItem>(
      (context, item, index) => Container(
        padding: EdgeInsets.all(16),
        child: Row(
          children: [
            CircleAvatar(child: Text(item.initial)),
            SizedBox(width: 16),
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(item.title, style: TextStyle(fontWeight: FontWeight.bold)),
                  Text(item.subtitle),
                ],
              ),
            ),
            Icon(Icons.chevron_right),
          ],
        ),
      ),
    ),
  )
  .build();

📱 Examples

Check out the /example folder for a complete demo app showcasing all 15 screen types with modern UI.

Example App Features:

• 🎨 Modern home screen with categorized navigation
• 📱 15 fully functional screen examples
• 🌓 Light and dark theme support
• 📊 All screens demonstrate best practices

Run the example:

cd example
flutter run

The example app now features:

• Modern card-based navigation with gradient icons
• Categorized sections (Static, Form, List screens)
• Count badges showing number of screens per category
• Large scrollable app bar with smooth animations
• Professional typography and spacing throughout

🎯 What's New in v1.0.1

🎨 Complete UI/UX Redesign

• ✨ Modern Material 3 design system (865 lines of theme code)
• 🧩 15+ reusable UI components (796 lines)
• 📱 Enhanced form screens with gradient backgrounds
• 🛍️ Redesigned list screens with modern cards
• 🏠 Modern home screen with categorized navigation
• 🌓 Optimized dark mode support
• ♿ WCAG AA accessibility compliance

📚 Documentation

• Complete design system guide (500+ lines)
• Quick start guide for developers
• Comprehensive UI redesign summary
• Best practices and usage examples

🔧 Code Quality

• ✅ Zero compiler warnings or errors
• 🎯 Type-safe implementation
• 📦 Clean architecture with separation of concerns
• 🧪 Production-ready code

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ using Flutter 3 and Material 3 design principles.

Special thanks to the Flutter community for inspiration and support.

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: See UI_DESIGN_SYSTEM.md for complete design guide
• 💬 Discussions: GitHub Discussions

---

Version: 1.0.1
Status: ✅ Production Ready
Last Updated: February 2026

Made with Flutter 💙 and Material 3 🎨