flutter_adaptive_design #

An enterprise-grade, zero-overhead Flutter design system package that delivers true platform-native UI for iOS (Apple Human Interface Guidelines) and Android (Material 3) from a single unified API.

🌟 Why flutter_adaptive_design? #

Building apps that feel truly native on both iOS and Android traditionally required messy conditional branches (if (Platform.isIOS)), broken web builds due to dart:io, mismatched font scaling, inconsistent touch targets, and duplicated UI code.

flutter_adaptive_design eliminates all of that by providing:

• 50+ Unified Adaptive Primitives: Write AdaptiveButton, AdaptiveScaffold, AdaptiveTextField, and get pixel-perfect Cupertino or Material 3 components automatically.
• Web & Multiplatform Safe: Conditional OS imports prevent web compile errors.
• Design Tokens: Standardized 8pt spacing grid, platform radii (squircle vs M3), eased motion curves, and semantic colors.
• Semantic Iconography: Native integration with hugeicons, Flutter IconData, and custom SVGs.
• Responsive Multi-Device Engine: Breakpoints, responsive grids, constrained content, master-detail layouts, and responsive scaffolds.
• First-Class Testing Suite: Dedicated testAdaptiveWidget harness to verify Cupertino and Material branches in automated CI/CD pipelines.

📦 Installation #

Add flutter_adaptive_design and hugeicons to your pubspec.yaml:

flutter pub add flutter_adaptive_design hugeicons

Or manually:

dependencies:
  flutter:
    sdk: flutter
  flutter_adaptive_design: ^1.0.0
  hugeicons: ^1.1.7

🚀 Quick Start #

1. Import the Package #

import 'package:flutter_adaptive_design/flutter_adaptive_design.dart';
// Or use the short alias:
// import 'package:flutter_adaptive_design/adaptive.dart';

2. Build Platform-Native Screens #

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

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

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  bool _notificationsEnabled = true;
  final TextEditingController _searchController = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return AdaptiveScaffold(
      appBar: const AdaptiveAppBar(
        title: 'Dashboard',
      ),
      body: SingleChildScrollView(
        padding: AdaptiveSpacing.pagePadding,
        child: Column(
          children: [
            AdaptiveSearchBar(
              controller: _searchController,
              placeholder: 'Search transactions...',
            ),
            const SizedBox(height: AdaptiveSpacing.md),
            AdaptiveCard(
              child: AdaptiveListTile(
                leading: const AdaptiveIcon(AdaptiveIcons.notification),
                title: const Text('Push Notifications'),
                subtitle: const Text('Receive instant alerts'),
                trailing: AdaptiveSwitch(
                  value: _notificationsEnabled,
                  onChanged: (val) => setState(() => _notificationsEnabled = val),
                ),
              ),
            ),
            const SizedBox(height: AdaptiveSpacing.lg),
            AdaptiveButton.label(
              onPressed: () {
                AdaptiveDialog.show(
                  context: context,
                  title: 'Confirm Action',
                  content: 'Do you want to proceed with this transfer?',
                  actions: [
                    AdaptiveDialogAction(
                      label: 'Cancel',
                      onPressed: () => Navigator.pop(context),
                    ),
                    AdaptiveDialogAction(
                      label: 'Confirm',
                      isDefault: true,
                      onPressed: () => Navigator.pop(context),
                    ),
                  ],
                );
              },
              label: 'Make Payment',
            ),
          ],
        ),
      ),
    );
  }
}

🎨 Design Tokens & Foundation #

1. Spacing (AdaptiveSpacing) #

Based on the standard 8pt grid with 4pt sub-grid support:

2. Radius (AdaptiveRadius) #

Provides platform-accurate corner radii:

3. Motion & Curves (AdaptiveMotion) #

Platform-tailored transition curves and micro-durations:

• AdaptiveMotion.micro: 120ms (taps, toggles)
• AdaptiveMotion.transition: 280ms (sheets, dialogs)
• AdaptiveMotion.page: 380ms (navigation transitions)
• AdaptiveMotion.pageCurve: Curves.easeInOut on iOS, Curves.easeInOutCubicEmphasized on Android.

4. Semantic Iconography (AdaptiveIcons & AdaptiveIcon) #

Seamlessly renders stroke-rounded HugeIcons, Flutter IconData, or custom widgets with automatic platform dark/light color resolution:

// Semantic preset:
AdaptiveIcon(AdaptiveIcons.home, size: 24)

// Flutter IconData:
AdaptiveIcon(Icons.star, color: Colors.amber)

// Platform-resolved glyph:
final icon = AdaptiveIcons.resolve(
  material: Icons.arrow_back,
  cupertino: CupertinoIcons.back,
);

🧩 Comprehensive Component Catalog (+96 Components) #

🏗️ Layout & Structure #

🔘 Buttons & Actions #

📝 Forms & Inputs #

💬 Feedback & Overlays #

🏷️ Chips & Tags #

🧭 Navigation & Pickers #

⚡ State & Placeholder Patterns #

📐 Responsive Layout Engine #

🧪 Testing Guide #

flutter_adaptive_design includes a comprehensive testing library via package:flutter_adaptive_design/testing.dart.

Test Both Platforms in One Go #

import 'package:flutter_adaptive_design/flutter_adaptive_design.dart';
import 'package:flutter_adaptive_design/testing.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  group('AdaptiveButton Tests', () {
    // Automatically executes twice: once for Android, once for iOS
    testAdaptiveWidget('renders native primitive per platform', (tester, platform) async {
      await tester.pumpWidget(
        wrapAdaptiveTestWidget(
          AdaptiveButton.label(
            onPressed: () {},
            label: 'Submit',
          ),
        ),
      );

      expect(find.text('Submit'), findsOneWidget);

      if (platform == TargetPlatform.iOS) {
        expect(find.byType(CupertinoButton), findsOneWidget);
      } else {
        expect(find.byType(FilledButton), findsOneWidget);
      }
    });
  });
}

🔄 Live Preview & Platform Switching #

You can dynamically force or preview any platform at runtime (including web demos and release builds):

// Force iOS preview
PlatformUtils.debugOverridePlatform = TargetPlatform.iOS;

// Force Android preview
PlatformUtils.debugOverridePlatform = TargetPlatform.android;

// Reset to device platform
PlatformUtils.debugOverridePlatform = null;

📱 Example Application #

An interactive gallery app showcasing all components with live iOS/Android platform toggling and Light/Dark themes is located in the example/ directory.

To run the example app:

cd example
flutter run

📄 License #

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