Save Points Screen Builder

A powerful, configuration-driven screen generator for Flutter 3 with Material 3 design system. Build production-ready screens in minutes.

---

Overview

Save Points Screen Builder eliminates boilerplate by providing a fluent builder API for common screen patterns. Whether you need authentication flows, product listings, or settings screens—build them declaratively with type safety and modern design out of the box.

// Create a sign-in screen in seconds
SignInScreenBuilder()
  .title('Welcome Back')
  .submitButton(label: 'Sign In', onSubmit: handleSignIn)
  .socialLogin([SocialLoginButton.google(onGoogleSignIn)])
  .build();

---

Table of Contents

• Features
• Installation
• Quick Start
• Screen Types
• Core Concepts
• Design System
• UI Components
• Advanced Usage
• Examples
• Documentation
• Contributing

---

Features

Feature	Description
Material 3 Design	Professional color scheme, typography, and spacing system
Builder Pattern	Fluent, chainable APIs for all 15 screen types
Form Engine	Dynamic form generation with 15+ field types and validators
List Engine	Declarative list/grid layouts with modern card designs
Type Safe	Full null safety and strong typing throughout
Responsive	Adaptive layouts for mobile, tablet, and desktop
Accessible	WCAG AA compliant with proper contrast ratios
Dark Mode	Complete light and dark theme support
15+ Components	Reusable UI components (cards, buttons, badges, etc.)

---

Installation

Add to your pubspec.yaml:

dependencies:
  save_points_screen_builder: ^1.0.2

flutter pub get

---

Quick Start

1. Apply the Theme

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(
      theme: AppTheme.lightTheme,
      darkTheme: AppTheme.darkTheme,
      themeMode: ThemeMode.system,
      home: const HomePage(),
    );
  }
}

2. Build Your First Screen

// Splash Screen
SplashScreenBuilder()
  .headline('My App')
  .subtitle('Welcome')
  .animation(SplashAnimation.fadeIn)
  .duration(const Duration(seconds: 3))
  .onFinish(() => Navigator.pushReplacementNamed(context, '/home'))
  .build();

---

Screen Types

Static Screens

Screen	Description
SplashScreenBuilder	Animated splash with logo and transitions
OnboardingScreenBuilder	Multi-page intro with smooth animations
WelcomeScreenBuilder	Eye-catching landing page
SuccessScreenBuilder	Confirmation with animations
ErrorScreenBuilder	User-friendly error handling

Form Screens

Screen	Description
SignInScreenBuilder	Login with social auth support
SignUpScreenBuilder	Multi-step registration flow
OTPScreenBuilder	Code verification with auto-focus
ForgotPasswordScreenBuilder	Password reset flow
EditProfileScreenBuilder	User profile management

List Screens

Screen	Description
ProductListScreenBuilder	Grid/list with enhanced cards
ShoppingCartScreenBuilder	Cart management with totals
SettingsScreenBuilder	Grouped settings with icons
ProfileScreenBuilder	User stats and information
NotificationsScreenBuilder	Categorized notifications

---

Core Concepts

Screen Configuration

Customize screens globally with ScreenBuilderConfig:

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();

Form Engine

Build forms declaratively with type-safe field configurations:

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

Field Types: text · email · password · phone · number · multiline · search · url · otp · dropdown · checkbox · switchToggle · slider · date · time · datetime

Validators:

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

List Engine

Create lists and grids with flexible layouts:

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

// Simple list
ListLayout.list(spacing: 8)

// Responsive columns
ListLayout.adaptive()

Item Builders:

// Card items
CardItemBuilder<Product>((context, product, index) => 
  Card(child: ProductContent(product))
)

// List tiles
ListTileItemBuilder<Item>((context, item, index) => 
  ListTile(title: Text(item.title))
)

// Grid tiles
GridTileItemBuilder<Product>((context, product, index) => 
  GridTile(child: ProductImage(product))
)

// Full custom
CustomItemBuilder<T>((context, item, index) => 
  YourCustomWidget(item: item)
)

---

Design System

Color Palette

The design system uses a professional Material 3 color scheme:

Type	Purpose
Primary	Main brand color, primary actions
Secondary	Supporting elements, secondary actions
Tertiary	Accents, highlights
Error	Error states, destructive actions
Surface	Cards, sheets, dialogs

Typography Scale

Style	Size	Use Case
Display	57sp	Hero text
Headline	32sp	Page titles
Title	22sp	Section headers
Body	16sp	Content text
Label	14sp	Buttons, captions

Spacing System

Based on 4dp increments: 4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64

Border Radius

Size	Value	Use Case
Small	8dp	Chips, badges
Medium	12dp	Cards, buttons
Large	16dp	Sheets, dialogs
XL	24dp	Full cards

---

UI Components

Cards

SPCard(
  child: YourContent(),
  onTap: () => handleTap(),
)

GlassCard(
  child: YourContent(),
)

Buttons

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

IconButtonWithBackground(
  icon: Icons.favorite,
  onPressed: () {},
)

Text Fields

SPTextField(
  label: 'Email',
  hint: 'Enter your email',
  controller: emailController,
)

SPSearchField(
  onChanged: (query) => search(query),
)

States

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

SPLoadingIndicator()

Lists & Tiles

SPListTile(
  leadingIcon: Icons.settings,
  title: 'Settings',
  subtitle: 'App preferences',
  onTap: () {},
)

SectionDivider(title: 'Account')

Chips & Badges

SPFilterChip(
  label: 'Active',
  selected: isSelected,
  onSelected: (value) => setState(() => isSelected = value),
)

SPBadge(
  label: 'New',
  color: Colors.green,
)

Snackbars

SPSnackBar.showSuccess(context, 'Saved successfully!');
SPSnackBar.showError(context, 'Something went wrong');
SPSnackBar.showInfo(context, 'Processing...');

---

Advanced Usage

Custom Theme

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

Custom Form Fields

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

Custom Item Builders

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

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

---

Examples

The /example folder contains a complete demo app showcasing all 15 screen types.

cd example
flutter run

Demo Features:

• Modern card-based navigation with gradient icons
• Categorized sections (Static, Form, List screens)
• Light and dark theme support
• All screens demonstrate best practices

---

Documentation

Document	Description
Design System Guide	Complete design system documentation
Quick Start Guide	Get started in 5 minutes
Redesign Summary	Overview of UI improvements

Architecture

lib/
├── src/
│   ├── core/              # Base classes & configuration
│   ├── design_system/     # 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

---

What's New in v1.0.2

• Design System — Complete Material 3 theme with 865 lines of code
• UI Components — 15+ reusable components (796 lines)
• Enhanced Forms — Gradient backgrounds, modern styling
• Modern Lists — Redesigned cards and layouts
• Dark Mode — Optimized for both themes
• Accessibility — WCAG AA compliance
• Zero Warnings — Clean, production-ready code

---

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

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

---

Support

• GitHub Issues — Bug reports
• GitHub Discussions — Questions & ideas
• Design System Guide — Complete documentation

---