flutter-master

name: flutter-master description: | The definitive Flutter mobile app development skill for building production-grade, high-performance Flutter applications. USE THIS SKILL whenever the user mentions Flutter, Dart mobile development, cross-platform mobile apps, or any of these specific topics: Flutter animations (implicit, explicit, physics-based, Rive, Lottie, Hero transitions, CustomPainter, staggered), Flutter performance optimization (widget rebuilds, Impeller, frame budget, jank, isolates, memory leaks, app size), Flutter state management (Riverpod 3.0 (stable), BLoC 9.0+, Provider, Signals, Clean Architecture), Flutter debugging (DevTools, performance profiling, memory leaks, shader warmup), Flutter architecture (Clean Architecture, repository pattern, dependency injection, folder structure), Flutter testing (unit, widget, integration, golden tests, mocking, TDD), Flutter CI/CD (Fastlane, Codemagic, GitHub Actions, flavors, store deployment), Flutter UI (Material Design 3, Cupertino, responsive design, accessibility, i18n, dynamic theming), Flutter navigation (GoRouter, deep linking, nested navigation, route guards), Flutter networking (Dio, Retrofit, offline-first, caching, WebSocket, GraphQL), or building any mobile app with Flutter/Dart. Also trigger for: splash screens, onboarding flows, custom painters, shader effects, gesture-driven interactions, pull-to-refresh, infinite scroll, chat UIs, e-commerce apps, fintech apps, social media apps, health apps built with Flutter. This skill transforms Claude into a Flutter expert that writes performant, bug-free, beautifully animated mobile applications rivaling the best on App Store and Play Store.

Flutter Master

Philosophy: 60fps or nothing. Bug-free by design. Beautiful by default. Target: Flutter 3.38+ / Dart 3.10+ / Impeller-mandatory (iOS) & default (Android) / 2025-2026 era

Reference File Navigator

Use this table to find the right reference for any Flutter task. Read the relevant file BEFORE writing code.

Quick Decision Tree

What kind of Flutter task?
│
├── "Build a new app from scratch"
│   → Read: patterns/app-scaffold.md → references/state-management.md → references/navigation-routing.md
│
├── "Add animations"
│   ├── Simple property change? → AnimatedContainer/AnimatedOpacity (references/animations-mastery.md §2)
│   ├── Need controller? → AnimationController + Transition (references/animations-mastery.md §4)
│   ├── Physics-based? → SpringSimulation (references/animations-mastery.md §7)
│   ├── Designer-created? → Rive or Lottie (references/rive-lottie-integration.md)
│   ├── Custom drawing? → CustomPainter (references/custom-painters-shaders.md)
│   └── Gesture-driven? → references/gesture-interactions.md
│
├── "Fix performance / jank"
│   ├── Too many rebuilds? → references/widget-rebuild-optimization.md
│   ├── Rendering jank? → references/performance-optimization.md
│   ├── Memory issues? → references/memory-isolates-optimization.md
│   ├── App too large? → references/memory-isolates-optimization.md §app-size
│   └── Need to profile? → references/debugging-profiling.md
│
├── "Set up architecture"
│   ├── State management? → references/state-management.md (Riverpod recommended)
│   ├── Navigation? → references/navigation-routing.md (GoRouter recommended)
│   ├── Networking? → references/networking-data.md (Dio + Retrofit recommended)
│   └── Testing strategy? → references/testing-error-handling.md
│
├── "Deploy / CI-CD"
│   → references/ci-cd-deployment.md
│
├── "UI / Theming / Accessibility"
│   ├── Basic Material 3 / Cupertino / responsive → references/platform-adaptive-ui.md
│   ├── Psychology-backed UX decisions → flutter-ui-ux/references/mobile-psychology-flutter.md
│   ├── Touch/thumb ergonomics → flutter-ui-ux/references/thumb-zone-flutter.md
│   ├── Form design → flutter-ui-ux/references/form-mastery-flutter.md
│   ├── Haptics & micro-interactions → flutter-ui-ux/references/haptic-micro-interactions.md
│   ├── Typography & theming → flutter-ui-ux/references/typography-theming-flutter.md
│   ├── Dark mode → flutter-ui-ux/references/dark-mode-flutter.md
│   ├── Conversion optimization → flutter-ui-ux/references/conversion-patterns-flutter.md
│   └── Deep accessibility → flutter-ui-ux/references/accessibility-deep-flutter.md
│
├── "Debug a Flutter bug"
│   ├── Systematic debugging workflow → flutter-debugger/references/flutter-debug-methodology.md
│   ├── Widget rebuilding too much → flutter-debugger/references/widget-tree-debugging.md
│   ├── State not updating → flutter-debugger/references/state-management-debugging.md
│   ├── Animation jank/glitch → flutter-debugger/references/animation-debugging.md
│   ├── Memory leak suspected → flutter-debugger/references/memory-leak-debugging.md
│   ├── iOS/Android specific → flutter-debugger/references/platform-specific-debugging.md
│   ├── Got an error message → flutter-debugger/references/error-patterns-solutions.md
│   ├── Production crash → flutter-debugger/checklists/crash-investigation.md
│   └── Write test to reproduce → flutter-debugger/references/testing-debug-integration.md
│
├── "Which package should I use?"
│   → references/pub-packages-ecosystem.md
│
├── "Build a specialized iOS app"
│   ├── What type of app? → ios-apps/references/ios-app-types-guide.md (START HERE)
│   ├── Fintech/banking? → ios-apps/blueprints/ios-fintech-app.md
│   ├── Social media/content? → ios-apps/blueprints/ios-social-media-app.md
│   ├── Native integration needed? → ios-apps/references/ios-native-integration.md
│   ├── Data/persistence? → ios-apps/references/ios-data-persistence.md
│   └── Ready to launch? → ios-apps/checklists/ios-app-production-checklist.md
│
├── "Build a specialized Android app"
│   ├── What type of app? → android-apps/references/android-app-types-guide.md (START HERE)
│   ├── Fintech/banking? → android-apps/blueprints/android-fintech-app.md
│   ├── E-commerce? → android-apps/blueprints/android-ecommerce-app.md
│   ├── Native integration needed? → android-apps/references/android-native-integration.md
│   ├── Data/persistence? → android-apps/references/android-data-persistence.md
│   └── Ready to launch? → android-apps/checklists/android-app-production-checklist.md
│
└── "Code review / release"
    → checklists/code-review-checklist.md or checklists/pre-release-checklist.md

Core Principles (ALWAYS Apply)

These rules apply to EVERY Flutter task, regardless of which reference file you read:

1. Const Everything

// ALWAYS: Use const constructors wherever possible
const SizedBox(height: 16),
const EdgeInsets.all(16),
const Text('Hello'),

// Enable these lints in analysis_options.yaml:
// prefer_const_constructors: true
// prefer_const_declarations: true
// prefer_const_literals_to_create_immutables: true

2. Split Widgets, Not Methods

// BAD: Extracting build methods
class MyWidget extends StatelessWidget {
  Widget _buildHeader() => ... // Still rebuilds with parent

  // GOOD: Extract to separate widget class
}

class _Header extends StatelessWidget { // Gets its own Element, independent rebuilds
  const _Header();
  @override
  Widget build(BuildContext context) => ...
}

3. Dispose Everything

@override
void dispose() {
  _animationController.dispose();
  _scrollController.dispose();
  _textController.dispose();
  _focusNode.dispose();
  _subscription.cancel();
  _timer?.cancel();
  super.dispose();
}

4. ListView.builder for Lists

// NEVER: Column(children: items.map((i) => Widget(i)).toList())
// ALWAYS:
ListView.builder(
  itemCount: items.length,
  itemExtent: 72, // Fixed height = O(1) layout
  itemBuilder: (context, index) => ItemWidget(item: items[index]),
)

5. Error Handling with Result Types

// Use sealed classes or fpdart Either for error handling
sealed class Result<T> {
  const Result();
}
class Success<T> extends Result<T> {
  final T data;
  const Success(this.data);
}
class Failure<T> extends Result<T> {
  final AppException error;
  const Failure(this.error);
}

6. Riverpod for State (Recommended)

// Use @riverpod code generation for type-safe providers
@riverpod
class AuthNotifier extends _$AuthNotifier {
  @override
  FutureOr<AuthState> build() async {
    return _checkAuthStatus();
  }
}

7. GoRouter for Navigation

// Type-safe routing with GoRouter
GoRouter(
  routes: [
    GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
    ShellRoute(
      builder: (_, __, child) => ScaffoldWithNav(child: child),
      routes: [...],
    ),
  ],
  redirect: (context, state) => _authRedirect(context, state),
);

8. Profile in Profile Mode

// NEVER profile in debug mode — it's 10x slower
// flutter run --profile
// Check: 16ms frame budget (60Hz) or 8ms (120Hz)

Production Tech Stack (2025-2026 Recommended)

Animation Duration Guidelines (Material Motion)

Always use Curves.easeInOut as default. Use Curves.easeOut for enter, Curves.easeIn for exit.

Frame Budget Reference

If build phase exceeds budget: → references/widget-rebuild-optimization.md If paint phase exceeds budget: → references/performance-optimization.md (RepaintBoundary) If raster thread spikes: → references/debugging-profiling.md

Quick Patterns (Most Common Tasks)

Infinite Scroll with Pull-to-Refresh

RefreshIndicator(
  onRefresh: () => ref.refresh(itemsProvider.future),
  child: ListView.builder(
    controller: _scrollController, // Add scroll listener for pagination
    itemCount: items.length + (hasMore ? 1 : 0),
    itemBuilder: (context, index) {
      if (index == items.length) return const LoadingIndicator();
      return ItemCard(item: items[index]);
    },
  ),
)

Responsive Layout

LayoutBuilder(
  builder: (context, constraints) {
    if (constraints.maxWidth > 1200) return DesktopLayout(child: content);
    if (constraints.maxWidth > 600) return TabletLayout(child: content);
    return MobileLayout(child: content);
  },
)

Auth-Guarded Route

GoRouter(
  redirect: (context, state) {
    final isLoggedIn = ref.read(authProvider).isLoggedIn;
    final isLoginRoute = state.matchedLocation == '/login';
    if (!isLoggedIn && !isLoginRoute) return '/login';
    if (isLoggedIn && isLoginRoute) return '/';
    return null;
  },
)

Debounced Search

@riverpod
class SearchNotifier extends _$SearchNotifier {
  Timer? _debounce;

  @override
  AsyncValue<List<Result>> build() => const AsyncData([]);

  void search(String query) {
    _debounce?.cancel();
    _debounce = Timer(const Duration(milliseconds: 300), () {
      state = const AsyncLoading();
      _performSearch(query);
    });
  }
}

When Multiple References Apply

Some tasks need multiple files. Read them in this order: