---
description: Flutter & Dart official best practices from Flutter team. Apply to ALL Flutter/Dart files.
globs: "**/*.dart"
---

# AI Rules for Flutter (Official — from docs.flutter.dev)

You are an expert in Flutter and Dart development. Build beautiful, performant, and maintainable applications following modern best practices.

## Flutter Style Guide
- **SOLID Principles:** Apply throughout the codebase.
- **Concise and Declarative:** Write modern, technical Dart code. Prefer functional and declarative patterns.
- **Composition over Inheritance:** Favor composition for building complex widgets and logic.
- **Immutability:** Prefer immutable data structures. Widgets (especially StatelessWidget) should be immutable.
- **State Management:** Separate ephemeral state and app state.
- **Navigation:** Use GoRouter or auto_route for routing and deep linking.

## Code Quality
- Adhere to maintainable code structure and separation of concerns.
- Avoid abbreviations; use meaningful, descriptive names.
- Line length: 80 characters or fewer.
- Use PascalCase for classes, camelCase for members/variables, snake_case for files.
- Functions: short, single purpose, strive for less than 20 lines.
- Use `logging` package instead of `print`.

## Dart Best Practices
- Follow official Effective Dart guidelines.
- Add doc comments to all public APIs.
- Use async/await for asynchronous operations with robust error handling.
- Write code that is soundly null-safe. Avoid `!` unless guaranteed non-null.
- Use pattern matching features where they simplify code.
- Use records to return multiple types.
- Prefer exhaustive switch statements.
- Use arrow syntax for simple one-line functions.

## Flutter Best Practices
- Use `const` constructors whenever possible to reduce rebuilds.
- Use small, private Widget classes instead of helper methods returning Widget.
- Break down large build() methods into smaller, reusable private Widget classes.
- Use ListView.builder or SliverList for long lists (lazy loading).
- Use compute() for expensive calculations in separate isolate.
- Avoid performing expensive operations in build() methods.

## Application Architecture
- Separation of Concerns: MVC/MVVM with defined Model, View, ViewModel/Controller.
- Logical Layers: Presentation → Domain → Data → Core.
- Feature-based Organization for larger projects.

## State Management (Built-in preferred)
- Streams + StreamBuilder for sequences of async events.
- Futures + FutureBuilder for single async operations.
- ValueNotifier + ValueListenableBuilder for simple local state.
- ChangeNotifier for complex/shared state.
- MVVM when robust solution needed.
- Manual constructor dependency injection to keep dependencies explicit.

## Theming
- Define centralized ThemeData; implement light + dark themes.
- Use ColorScheme.fromSeed() for harmonious palettes.
- Use ThemeExtension for custom design tokens.
- Use google_fonts package for custom fonts.
- Follow 60-30-10 rule for color distribution.

## Testing
- Unit tests (package:test), Widget tests (flutter_test), Integration tests (integration_test).
- Follow Arrange-Act-Assert pattern.
- Prefer fakes/stubs over mocks; use mockito/mocktail if necessary.
- Aim for high test coverage.

## Accessibility
- Text contrast ratio ≥ 4.5:1.
- Test with dynamic text scaling.
- Use Semantics widget for descriptive labels.
- Test with TalkBack (Android) and VoiceOver (iOS).

## Documentation
- Use `///` for doc comments.
- Start with single-sentence summary.
- Comment WHY, not WHAT.
- Include code samples where appropriate.