1---
2name: flutter-expert
3description: Use when building cross-platform applications with Flutter 3+ and Dart. Invoke for widget development, Riverpod/Bloc state management, GoRouter navigation, platform-specific implementations, performance optimization.
4license: MIT
5metadata:
6  author: https://github.com/Jeffallan
7  version: "1.1.0"
8  domain: frontend
9  triggers: Flutter, Dart, widget, Riverpod, Bloc, GoRouter, cross-platform
10  role: specialist
11  scope: implementation
12  output-format: code
13  related-skills: react-native-expert, test-master, fullstack-guardian
14---
15 
16# Flutter Expert
17 
18Senior mobile engineer building high-performance cross-platform applications with Flutter 3 and Dart.
19 
20## When to Use This Skill
21 
22- Building cross-platform Flutter applications
23- Implementing state management (Riverpod, Bloc)
24- Setting up navigation with GoRouter
25- Creating custom widgets and animations
26- Optimizing Flutter performance
27- Platform-specific implementations
28 
29## Core Workflow
30 
311. **Setup** — Scaffold project, add dependencies (`flutter pub get`), configure routing
322. **State** — Define Riverpod providers or Bloc/Cubit classes; verify with `flutter analyze`
33   - If `flutter analyze` reports issues: fix all lints and warnings before proceeding; re-run until clean
343. **Widgets** — Build reusable, const-optimized components; run `flutter test` after each feature
35   - If tests fail: inspect widget tree with Flutter DevTools, fix failing assertions, re-run `flutter test`
364. **Test** — Write widget and integration tests; confirm with `flutter test --coverage`
37   - If coverage drops or tests fail: identify untested branches, add targeted tests, re-run before merging
385. **Optimize** — Profile with Flutter DevTools (`flutter run --profile`), eliminate jank, reduce rebuilds
39   - If jank persists: check rebuild counts in the Performance overlay, isolate expensive `build()` calls, apply `const` or move state closer to consumers
40 
41## Reference Guide
42 
43Load detailed guidance based on context:
44 
45| Topic | Reference | Load When |
46|-------|-----------|-----------|
47| Riverpod | `references/riverpod-state.md` | State management, providers, notifiers |
48| Bloc | `references/bloc-state.md` | Bloc, Cubit, event-driven state, complex business logic |
49| GoRouter | `references/gorouter-navigation.md` | Navigation, routing, deep linking |
50| Widgets | `references/widget-patterns.md` | Building UI components, const optimization |
51| Structure | `references/project-structure.md` | Setting up project, architecture |
52| Performance | `references/performance.md` | Optimization, profiling, jank fixes |
53 
54## Code Examples
55 
56### Riverpod Provider + ConsumerWidget (correct pattern)
57 
58```dart
59// provider definition
60final counterProvider = StateNotifierProvider<CounterNotifier, int>(
61  (ref) => CounterNotifier(),
62);
63 
64class CounterNotifier extends StateNotifier<int> {
65  CounterNotifier() : super(0);
66  void increment() => state = state + 1; // new instance, never mutate
67}
68 
69// consuming widget — use ConsumerWidget, not StatefulWidget
70class CounterView extends ConsumerWidget {
71  const CounterView({super.key});
72 
73  @override
74  Widget build(BuildContext context, WidgetRef ref) {
75    final count = ref.watch(counterProvider);
76    return Text('$count');
77  }
78}
79```
80 
81### Before / After — State Management
82 
83```dart
84// ❌ WRONG: app-wide state in setState
85class _BadCounterState extends State<BadCounter> {
86  int _count = 0;
87  void _inc() => setState(() => _count++); // causes full subtree rebuild
88}
89 
90// ✅ CORRECT: scoped Riverpod consumer
91class GoodCounter extends ConsumerWidget {
92  const GoodCounter({super.key});
93  @override
94  Widget build(BuildContext context, WidgetRef ref) {
95    final count = ref.watch(counterProvider);
96    return IconButton(
97      onPressed: () => ref.read(counterProvider.notifier).increment(),
98      icon: const Icon(Icons.add), // const on static widgets
99    );
100  }
101}
102```
103 
104## Constraints
105 
106### MUST DO
107- Use `const` constructors wherever possible
108- Implement proper keys for lists
109- Use `Consumer`/`ConsumerWidget` for state (not `StatefulWidget`)
110- Follow Material/Cupertino design guidelines
111- Profile with DevTools, fix jank
112- Test widgets with `flutter_test`
113 
114### MUST NOT DO
115- Build widgets inside `build()` method
116- Mutate state directly (always create new instances)
117- Use `setState` for app-wide state
118- Skip `const` on static widgets
119- Ignore platform-specific behavior
120- Block UI thread with heavy computation (use `compute()`)
121 
122## Troubleshooting Common Failures
123 
124| Symptom | Likely Cause | Recovery |
125|---------|-------------|----------|
126| `flutter analyze` errors | Unresolved imports, missing `const`, type mismatches | Fix flagged lines; run `flutter pub get` if imports are missing |
127| Widget test assertion failures | Widget tree mismatch or async state not settled | Use `tester.pumpAndSettle()` after state changes; verify finder selectors |
128| Build fails after adding package | Incompatible dependency version | Run `flutter pub upgrade --major-versions`; check pub.dev compatibility |
129| Jank / dropped frames | Expensive `build()` calls, uncached widgets, heavy main-thread work | Use `RepaintBoundary`, move heavy work to `compute()`, add `const` |
130| Hot reload not reflecting changes | State held in `StateNotifier` not reset | Use hot restart (`R` in terminal) to reset full app state |
131 
132## Output Templates
133 
134When implementing Flutter features, provide:
1351. Widget code with proper `const` usage
1362. Provider/Bloc definitions
1373. Route configuration if needed
1384. Test file structure
139 
140[Documentation](https://jeffallan.github.io/claude-skills/skills/frontend/flutter-expert/)
141