flutter-dev

What this skill does

# 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 `Future`s, `async`, `await` for single asynchronous operations
- Use `Stream`s 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
```dart
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
```dart
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:

```dart
// 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):

```dart
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`:

```dart
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:

```dart
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:

```dart
MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.light,
    ),
    textTheme: TextTheme(
      displayLarge: TextStyle(fontSize: