---

name: flutter-dev description: Expert Flutter and Dart development skill for building beautiful, performant, and maintainable applications. Use when users request Flutter/Dart development tasks including creating apps, widgets, screens, implementing features, debugging, testing, state management, navigation, theming, layouts, or working with Flutter projects. Covers mobile, web, and desktop platforms with modern best practices, Material Design, responsive UI, and code quality standards.

Flutter Development Expert

Expert guidance for Flutter and Dart development following official Flutter team best practices.

Core Development Principles

Code Philosophy

• Apply SOLID principles throughout the codebase
• Write concise, modern, technical Dart code with functional and declarative patterns
• Favor composition over inheritance for building complex widgets and logic
• Prefer immutable data structures, especially for widgets (use StatelessWidget when possible)
• Separate ephemeral state from app state using appropriate state management
• Keep functions short with single purpose (strive for less than 20 lines)
• Use meaningful, descriptive names - avoid abbreviations

Project Structure Assumptions

• Standard Flutter project structure with lib/main.dart as entry point
• Organize by logical layers: Presentation (widgets/screens), Domain (business logic), Data (models/API clients), Core (utilities/extensions)
• For larger projects: organize by feature with presentation/domain/data subfolders per feature

Interaction Guidelines

When generating code:

• Provide explanations for Dart-specific features (null safety, futures, streams)
• If request is ambiguous, ask for clarification on functionality and target platform
• When suggesting new dependencies from pub.dev, explain their benefits
• Use dart format tool for consistent formatting
• Use dart fix tool to automatically fix common errors
• Use the Dart linter with recommended rules to catch issues

Code Quality Standards

Styling Rules

• Line length: 80 characters or fewer
• Naming conventions:
  • PascalCase for classes
  • camelCase for members/variables/functions/enums
  • snake_case for files
• No trailing comments
• Use arrow syntax for simple one-line functions

Error Handling

• Anticipate and handle potential errors - never fail silently
• Use try-catch blocks with appropriate exception types
• Use custom exceptions for code-specific situations
• Proper async/await usage with robust error handling

Documentation

• Add dartdoc comments to all public APIs (classes, constructors, methods, top-level functions)
• Write clear comments for complex/non-obvious code
• Use /// for doc comments
• Start with single-sentence summary ending with period
• Comment why code is written a certain way, not what it does

Dart Best Practices

Type System & Null Safety

• Write soundly null-safe code
• Leverage Dart's null safety features
• Avoid ! operator unless value is guaranteed non-null
• Use pattern matching features where they simplify code
• Use records to return multiple types when defining a class is cumbersome
• Prefer exhaustive switch statements/expressions (no break needed)

Async Programming

• Use Futures, async, await for single asynchronous operations
• Use Streams for sequences of asynchronous events
• Ensure proper error handling in async operations

Class & Library Organization

• Define related classes within the same library file
• For large libraries: export smaller private libraries from single top-level library
• Group related libraries in same folder

Flutter Best Practices

Widget Design

• Widgets (especially StatelessWidget) are immutable
• When UI needs to change, Flutter rebuilds widget tree
• Prefer composing smaller widgets over extending existing ones
• Use small, private Widget classes instead of private helper methods returning widgets
• Break down large build() methods into smaller, reusable private Widget classes
• Use const constructors whenever possible to reduce rebuilds

Performance Optimization

• Use ListView.builder or SliverList for long lists (lazy-loaded)
• Use compute() to run expensive calculations in separate isolate (e.g., JSON parsing)
• Avoid expensive operations (network calls, complex computations) in build() methods
• Use const constructors in build() methods to minimize rebuilds

Responsive Design

• Use LayoutBuilder or MediaQuery for responsive UIs
• Ensure mobile responsive design across different screen sizes
• Test on mobile and web platforms

State Management

Prefer Flutter's built-in solutions unless third-party explicitly requested:

Built-in Solutions (in order of simplicity)

1. ValueNotifier + ValueListenableBuilder - Simple, local state with single value

final ValueNotifier<int> _counter = ValueNotifier<int>(0);

ValueListenableBuilder<int>(
  valueListenable: _counter,
  builder: (context, value, child) => Text('Count: $value'),
);

2. ChangeNotifier + ListenableBuilder - Complex/shared state across widgets

class CounterModel extends ChangeNotifier {
  int _count = 0;
  int get count => _count;
  void increment() {
    _count++;
    notifyListeners();
  }
}

ListenableBuilder(
  listenable: counterModel,
  builder: (context, child) => Text('${counterModel.count}'),
);

3. Streams + StreamBuilder - Sequences of asynchronous events
4. Futures + FutureBuilder - Single async operations

Advanced Patterns

• MVVM: Model-View-ViewModel pattern for robust applications
• Dependency Injection: Use manual constructor injection for explicit dependencies
• Provider: Only if explicitly requested for DI beyond manual injection

Navigation

GoRouter (Recommended)

Use go_router for declarative navigation, deep linking, and web support:

// Add dependency
flutter pub add go_router

// Configure router
final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) {
            final String id = state.pathParameters['id']!;
            return DetailScreen(id: id);
          },
        ),
      ],
    ),
  ],
);

// Use in MaterialApp
MaterialApp.router(routerConfig: _router);

• Configure redirect property for authentication flows
• Use for deep-linkable routes

Navigator (Built-in)

Use for short-lived screens not needing deep links (dialogs, temporary views):

Navigator.push(context, MaterialPageRoute(builder: (context) => DetailsScreen()));
Navigator.pop(context);

Package Management

Using pub Tool

• Add dependency: flutter pub add <package_name>
• Add dev dependency: flutter pub add dev:<package_name>
• Add override: flutter pub add override:<package_name>:1.0.0
• Remove dependency: dart pub remove <package_name>

External Packages

• Search pub.dev for suitable, stable packages
• Explain benefits when suggesting new dependencies

Data Handling

JSON Serialization

Use json_serializable and json_annotation:

import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';

@JsonSerializable(fieldRename: FieldRename.snake)
class User {
  final String firstName;
  final String lastName;
  
  User({required this.firstName, required this.lastName});
  
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

Code Generation

• Ensure build_runner is dev dependency
• Run after modifications: dart run build_runner build --delete-conflicting-outputs

Logging

Use dart:developer for structured logging:

import 'dart:developer' as developer;

// Simple messages
developer.log('User logged in successfully.');

// Structured error logging
try {
  // code
} catch (e, s) {
  developer.log(
    'Failed to fetch data',
    name: 'myapp.network',
    level: 1000, // SEVERE
    error: e,
    stackTrace: s,
  );
}

UI & Theming

Material Design 3 & ThemeData

Use ColorScheme.fromSeed() for harmonious palettes:

MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.light,
    ),
    textTheme: TextTheme(
      displayLarge: TextStyle(fontSize: 57, fontWeight: FontWeight.bold),
      bodyMedium: TextStyle(fontSize: 14, height: 1.4),
    ),
  ),
  darkTheme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.dark,
    ),
  ),
  themeMode: ThemeMode.system,
);

Custom Theme Extensions

For custom design tokens beyond standard ThemeData:

@immutable
class MyColors extends ThemeExtension<MyColors> {
  const MyColors({required this.success, required this.danger});
  final Color? success;
  final Color? danger;
  
  @override
  ThemeExtension<MyColors> copyWith({Color? success, Color? danger}) {
    return MyColors(success: success ?? this.success, danger: danger ?? this.danger);
  }
  
  @override
  ThemeExtension<MyColors> lerp(ThemeExtension<MyColors>? other, double t) {
    if (other is! MyColors) return this;
    return MyColors(
      success: Color.lerp(success, other.success, t),
      danger: Color.lerp(danger, other.danger, t),
    );
  }
}

// Register in ThemeData
theme: ThemeData(
  extensions: [MyColors(success: Colors.green, danger: Colors.red)],
),

// Use in widgets
Container(color: Theme.of(context).extension<MyColors>()!.success)

Fonts

Use google_fonts package for custom fonts:

flutter pub add google_fonts

final TextTheme appTextTheme = TextTheme(
  displayLarge: GoogleFonts.oswald(fontSize: 57, fontWeight: FontWeight.bold),
  titleLarge: GoogleFonts.roboto(fontSize: 22, fontWeight: FontWeight.w500),
  b