home / skills / hoangnguyen0403 / agent-skills-standard / idiomatic-flutter

idiomatic-flutter skill

safe

This skill helps you write idiomatic Flutter layouts by enforcing modern patterns, composition, and performance-friendly widget usage.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill idiomatic-flutter

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: Idiomatic Flutter
description: Modern layout and widget composition standards.
metadata:
  labels: [flutter, clean-code, widgets]
  triggers:
    files: ['lib/presentation/**/*.dart']
    keywords: [context.mounted, SizedBox, Gap, composition, shrink]
---

# Idiomatic Flutter

## **Priority: P1 (OPERATIONAL)**

Modern Flutter layout patterns and composition techniques.

- **Async Gaps**: Check `if (context.mounted)` before using `BuildContext` after `await`.
- **Composition**: Extract complex UI into small widgets. Avoid deep nesting or large helper methods.
- **Layout**:
  - Spacing: Use `Gap(n)` or `SizedBox` over `Padding` for simple gaps.
  - Empty UI: Use `const SizedBox.shrink()`.
  - Intrinsic: Avoid `IntrinsicWidth/Height`; use `Stack` + `FractionallySizedBox` for overlays.
- **Optimization**: Use `ColoredBox`/`Padding`/`DecoratedBox` instead of `Container` when possible.
- **Themes**: Use extensions for `Theme.of(context)` access.

## 🚫 Anti-Patterns

- **Missing Mounted Check**: `**No context usage after await**: Always check if (context.mounted).`
- **Helper Methods for UI**: `**No Widget functions**: Use specialized Widget classes for better performance/profiling.`
- **Direct Controller Access**: `**No UI-Logic coupling**: Use BLoC/Signals to decouple UI from State.`

Overview

This skill encapsulates modern Flutter layout and widget composition standards for building robust, maintainable UIs. It highlights defensive async patterns, composition over nesting, layout choices, and lightweight optimizations to improve performance and readability. Use it as a checklist for code reviews, linters, and agent-guided refactors.

How this skill works

The skill inspects Flutter/Dart UI code for common operational patterns and anti-patterns. It flags missing mounted checks after await points, excessive widget helper functions, improper controller coupling, and suboptimal layout or container usage. It also recommends idiomatic replacements like Gap, SizedBox.shrink, ColoredBox, and theme extensions.

When to use it

During code reviews for Flutter UI changes
When refactoring deeply nested or large widget trees
Integrating async operations that touch BuildContext
Optimizing render performance and reducing widget rebuilds
Enforcing team layout and composition standards

Best practices

Always check if (context.mounted) before using BuildContext after await
Prefer small, focused Widget classes over UI-only helper functions
Use Gap or SizedBox for simple spacing; use const SizedBox.shrink() for empty UI
Avoid IntrinsicWidth/Height; use Stack and FractionallySizedBox for overlays and sizing
Favor ColoredBox, Padding, or DecoratedBox instead of Container when only a subset of features is needed
Use Theme extensions and Theme.of(context) thoughtfully to centralize styling

Example use cases

Detect and warn where await is followed by direct context usage without a mounted check
Recommend extracting large build methods into discrete StatelessWidget/StatefulWidget classes
Replace Container instances with ColoredBox/DecoratedBox where possible to reduce layout cost
Suggest Gap or SizedBox replacements for ad-hoc Padding used solely as spacing
Identify direct controller or business-logic access from UI and suggest BLoC/Signal separation

FAQ

Why check context.mounted after await?

BuildContext may become invalid if the widget was disposed while awaiting; checking context.mounted prevents exceptions and stale UI updates.

When should I extract a helper method into a Widget class?

Extract when a UI subtree is reused, complex, or causes deep nesting. Widget classes enable better profiling, faster rebuilds, and clearer responsibilities.

Is Container always a bad choice?

No. Container is convenient but heavier. Use lighter primitives like ColoredBox, Padding, or DecoratedBox when you only need a subset of Container features to reduce layout overhead.