Flutter UI System
Philosophy: Flutter owns every pixel. Const-first. Theme-driven. GPU-animated. State-scoped.
🔧 Runtime Scripts
| Script |
Purpose |
Usage |
scripts/flutter_ui_audit.py |
Audit: missing const, dispose leaks, deprecated APIs |
python scripts/flutter_ui_audit.py <path> |
🔴 MANDATORY: Read Reference Files First
⛔ DO NOT code until relevant files are read:
| File |
Content |
Priority |
| flutter-design-thinking.md |
Anti-memorization, forces context analysis |
⬜ CRITICAL FIRST |
| flutter-state-ui.md |
Riverpod + Provider rules Claude MUST enforce |
⬜ CRITICAL |
| flutter-navigation.md |
GoRouter, PopScope, back logic, deep links |
⬜ CRITICAL |
| flutter-animations.md |
Implicit, explicit, Hero, page transitions, physics |
⬜ CRITICAL |
| flutter-performance.md |
const, RepaintBoundary, 60fps, shader warmup |
⬜ CRITICAL |
| flutter-theme-system.md |
Material 3, ColorScheme, TextTheme, ThemeExtension |
⬜ Read |
| flutter-layout-system.md |
Responsive, LayoutBuilder, MediaQuery, Slivers |
⬜ Read |
| flutter-custom-paint.md |
Canvas, CustomPainter, pixel-perfect rendering |
⬜ Read |
🧠 flutter-design-thinking.md FIRST — prevents AI from applying memorized patterns.
⚠️ ASK BEFORE ASSUMING
| Aspect |
Ask |
| State manager |
"Riverpod, Provider, BLoC, or vanilla?" |
| Navigation |
"GoRouter, auto_route, or Navigator 1.0?" |
| Design system |
"Material 3, Cupertino, or custom?" |
| Platforms |
"Mobile only, or tablet/desktop adaptive?" |
| Flutter version |
"3.12+? (PopScope vs WillPopScope)" |
⛔ ANTI-PATTERNS
Performance
| ❌ NEVER |
✅ ALWAYS |
ListView with static children for long lists |
ListView.builder |
setState in animation loop |
AnimatedBuilder |
Opacity(opacity: 0) to hide |
Visibility or conditional render |
IntrinsicHeight/IntrinsicWidth in lists |
Fixed heights or SliverFixedExtentList |
Missing const on StatelessWidget |
const MyWidget({super.key}) always |
Column + ListView without Expanded |
Wrap ListView in Expanded |
Hardcoded Color(0xFF...) in widgets |
Theme.of(context).colorScheme.primary |
Hardcoded fontSize |
Theme.of(context).textTheme.bodyLarge |
Animation
| ❌ NEVER |
✅ ALWAYS |
Animate width/height |
Animate Transform (scale/translate) |
AnimationController without dispose() |
Dispose in dispose() method |
addListener(() => setState((){})) |
AnimatedBuilder |
Missing RepaintBoundary on complex painters |
Wrap CustomPaint in RepaintBoundary |
| Hero tag collision |
Unique data-driven tags |
| No easing curve |
Curves.easeInOut minimum |
Navigation
| ❌ NEVER |
✅ ALWAYS |
WillPopScope (Flutter 3.12+ deprecated) |
PopScope with canPop + onPopInvokedWithResult |
Navigator.push in GoRouter app |
context.go() / context.push() |
| Hardcoded route strings everywhere |
Centralized route constants |
| No route guard for auth screens |
GoRouter redirect callback |
| Back button does nothing at root |
PopScope(canPop: false) + exit dialog |
State
| ❌ NEVER |
✅ ALWAYS |
ref.read() in build() (Riverpod) |
ref.watch() in build() |
Provider defined inside build() |
Top-level final myProvider = ... |
context.read<T>() in build() (Provider) |
context.watch<T>() in build() |
BuildContext in ChangeNotifier |
Pass data, not context |
notifyListeners() before mutation |
Mutate first, then notifyListeners() |
.when() without error handler |
Always when(data:, loading:, error:) |
Consumer<T> wrapping entire screen |
Selector<T, R> on smallest widget |
🗺️ Navigation: go() vs push() vs replace()
| Method |
Back Stack |
Use When |
context.go('/path') |
Replaces stack |
Tab switching, auth redirect |
context.push('/path') |
Adds to stack |
Drill-down navigation |
context.replace('/path') |
Replaces current, no pop |
Login → Home after auth |
context.pop() |
Removes current |
Back button, close modal |
context.pop(result) |
Removes + returns data |
Form submit, picker result |
🎬 Animation Selection
WHAT ARE YOU ANIMATING?
├── Simple property change → AnimatedContainer, AnimatedOpacity, TweenAnimationBuilder
├── Complex sequence/stagger → AnimationController + CurvedAnimation + AnimatedBuilder
├── Shared element (cross-screen) → Hero widget + unique tag
├── Page enter/exit → GoRouter CustomTransitionPage or pageBuilder
├── Spring/bounce/momentum → SpringSimulation, BouncingScrollPhysics
└── Vector/sprite → Rive or Lottie package
GPU-safe: transform, opacity → smooth
CPU-bound: width, height, margin, padding → jank
📊 State Manager Auto-Detect
Scan imports before writing any state code:
| Import Found |
Use |
flutter_riverpod |
Riverpod rules |
provider package |
Provider rules |
| Neither |
Ask user → recommend Riverpod for new projects |
⚡ Performance Quick Reference
class MyCard extends StatelessWidget {
const MyCard({super.key});
@override
Widget build(BuildContext context) => const Padding(
padding: EdgeInsets.all(16),
child: Text('Hello'),
);
}
RepaintBoundary(child: AnimatedWidget(...))
ListView.builder(itemCount: n, itemBuilder: (ctx, i) => Item(items[i]))
final name = ref.watch(userProvider.select((u) => u.name));
🧠 CHECKPOINT (Fill Before Any Flutter Work)
🧠 FLUTTER CHECKPOINT:
State: [ Riverpod / Provider / BLoC / Vanilla ]
Navigation: [ GoRouter / auto_route / Navigator 1.0 ]
Design: [ Material 3 / Cupertino / Custom ]
Platforms: [ Mobile / Tablet / Desktop / Web ]
Files Read: [ List files read ]
3 Rules I Will Apply:
1. _______________
2. _______________
3. _______________
Anti-Patterns I Will Avoid:
1. _______________
2. _______________
🔴 Can't fill checkpoint? → Read the skill files.
📋 Checklists
Per Screen
-
ConsumerWidget if Riverpod? const constructor?
- Touch targets ≥ 48dp?
- Loading + error states defined?
- Back navigation tested (PopScope or GoRouter canPop)?
- No hardcoded colors or font sizes?
Per Animation
- Animating
transform/opacity, not width/height?
-
AnimationController.dispose() called?
- Duration ≥ 150ms with easing curve?
-
RepaintBoundary on complex painters?
Pre-Release
- Run audit script — fix all 🔴 findings
-
flutter analyze — no missing const warnings
- Android back button tested — no stuck screens
- Dark mode tested — all colors from Theme
- Tablet layout tested — no overflow
- All
.when() handle error state
📚 Reference Files
| File |
Use When |
| flutter-design-thinking.md |
FIRST — prevents AI defaults |
| flutter-state-ui.md |
Riverpod + Provider rules, patterns, migration |
| flutter-navigation.md |
GoRouter, back logic, deep links, tabs |
| flutter-animations.md |
Implicit, explicit, Hero, transitions, physics |
| flutter-theme-system.md |
Material 3, ColorScheme, TextTheme |
| flutter-layout-system.md |
Responsive, LayoutBuilder, Slivers |
| flutter-performance.md |
const, RepaintBoundary, DevTools |
| flutter-custom-paint.md |
Canvas, CustomPainter, pixel-perfect |
Pixel-perfect = every spacing, color, and type choice is intentional and theme-driven. Own the pixels through your design system, not magic numbers.
