widget-composition skill by zakariaf

Build every screen from many small, const, single-purpose widget classes. A widget that does one thing rebuilds cheaply, reads clearly, tests in isolation, and can be lifted into a shared component library. The View is dumb: it watches one ViewModel and renders; logic lives in the Notifier, state in immutable value objects, layout in directional structural primitives. Applies to any screen, list, card, or shared component.

Read the reference for the task at hand:

references/rebuild-mechanics.md — why a class beats a method (Element.updateChild), const canonicalization, the full key policy, and .select for narrowed rebuilds.
references/structural-layout.md — edge-to-edge background vs SafeArea content, computed cell sizing, the GridView cross/main-axis trap, directional insets, and IME/resizeToAvoidBottomInset.
references/widget-and-data-selection.md — cheapest-widget table, data-class decision table (drift row vs record vs hand-written vs freezed), and gesture→fallback rules.

Run scripts/check-widget-composition.sh before a PR.

Non-negotiable rules

Extract a Widget class, never a Widget-returning method. Widget _buildHeader() is not a widget — its subtree has no Element of its own, so Element.updateChild never gets to compare old vs. new and short-circuit; it rebuilds with the parent, cannot be const, cannot take a Key, and find.byType cannot reach it in a test.
const everywhere it is legal, every field final. const constructors canonicalize identical widgets to the same object, letting Flutter prune the subtree rebuild. Turn on prefer_const_constructors + prefer_const_constructors_in_immutables. Budget zero minutes hand-tuning const — let dart fix --apply write it; never restructure a tree to make something const-able.
Keep build() small and shallow. Past the complexity limits owned by dart3-idioms-and-coding-standards (build() ≤ 80 lines; widget build nesting ≤ 5 — the deeper-nesting exception that table states for widget trees vs. logic ≤ 3), extract child widget classes. A build() you must scroll to read is too big.
One responsibility per widget. A component renders one thing; it does not also fetch data, format values, read a clock, hold app state, or schedule side effects.
No I/O, formatting, or domain math in build(). build() can run 60×/second — no repository/DAO call, no DateTime.now(), no NumberFormat, no sorting. The Notifier precomputes a ready-to-render UI-state value; the widget only paints it.
The View is dumb and watches exactly one ViewModel. A ConsumerWidget does ref.watch(oneNotifierProvider) and renders; intents go back via ref.read(...notifier). It never reaches a repository or DAO directly and never mutates persisted state.
StatelessWidget/ConsumerWidget by default. Use StatefulWidget/ConsumerStatefulWidget only for genuinely local, ephemeral UI state (AnimationController, TextEditingController, ScrollController, FocusNode). App/domain/session state lives in the Notifier.
Always dispose() controllers created in State. Leaked AnimationController/TextEditingController/ScrollController/FocusNode/subscriptions retain memory and fire after teardown. cancel_subscriptions/close_sinks are errors.
Lists are lazy. Use ListView.builder/SliverList for variable/long lists. Never ListView(children: items.map(...).toList()) for unbounded data — it builds every row eagerly.
Resolve identity, not content, in callbacks. A tap closure captures the stable id (onTap: () => onSelect(item.id)), never a captured content value — a re-tap after an edit must not act on a stale capture.
Every gesture needs a visible, focusable fallback. Any behaviour reachable by touch must also be reachable by a labelled focusable control. A drag-only or long-press-only action is unreachable to switch-access and screen-reader users.
Style from theme/tokens and logical directions. Colors/text styles come from Theme.of(context) or a ThemeExtension, never literal hex. Use EdgeInsetsDirectional/AlignmentDirectional (start/end), never hardcoded left/right, so RTL mirrors by construction.

// WRONG — helper method: rebuilds with parent, no const, no key, no isolation, untestable
Widget _buildProductCard(Product

Keep build() lean — the Notifier precomputes

ref.watch(p.select((s) => s.field)) rebuilds only when that field changes — the Riverpod equivalent of a leaf const. See state-management-riverpod for the watch/read/listen split and flutter-performance for .select and const-subtree scoping.

Composition guidance

Split a screen into sections (header, body, footer) as separate widget classes; split a row into its parts when a part is reused or complex.
Pass data down, callbacks up. A component receives what it shows and exposes onX callbacks; it never reaches into a parent or a provider it does not own.
Read MediaQuery/Theme in the leaf that needs it, not at the top of a big build() — reading at the top rebuilds the whole subtree on every metrics change.
Prefer the cheapest widget: SizedBox over Container for spacing; ColoredBox/DecoratedBox over Container for a single effect; Align/Center over Row+Spacer. See references/widget-and-data-selection.md.
Hoist unchanging subtrees into const locals so they survive rebuilds.
A shared component is domain-blind and provider-free. It takes primitives, localized labels, immutable view-data, and callbacks through its constructor — never a domain entity, a repository, or a ref. The dependency arrow is one-way: features import the shared library, never the reverse.

Keys

Keys matter in exactly one situation: the framework must decide whether an Element (and its State) can be reused for a new Widget at the same position in a child list. The classic bug is stale State bleeding into a reused slot after a list reorders.

Situation	Key
A row in a reorderable / filterable / variable list	`ValueKey(item.id)` — stable identity survives the move
A fixed-order, fixed-length list; leaf stateless widgets	none — a key changes nothing
Swapping two widgets of the same type and needing to preserve state	a `ValueKey` distinguishing them
A widget that suddenly "wants" a `GlobalKey`	stop — that is a design smell, not a fix

Never add GlobalKey for identity or lookups — it forces a global registry lookup and enables cross-tree reparenting, machinery most apps do not need. Full mechanism in references/rebuild-mechanics.md.

Data classes for view-data

Do not hand-roll a data class where a generator already emits one. The decision rule:

Shape	Use
Persisted row	the drift-generated row class directly — it has `==`, `hashCode`, `copyWith` already
Ephemeral multi-return inside one layer	a record — `(int row, int col)`; never crosses a layer boundary
Hand-authored domain value / UI-state	`@immutable`+`const`+`final` for a trivial value; `freezed` for non-trivial value types, unions, or `copyWith` churn — `dart3-idioms-and-coding-standards` owns the threshold
A joined shape no generator emits	hand-written `@immutable` class

Do not add equatable for one ==; Object.hash(...) is five lines. Full table and rationale in references/widget-and-data-selection.md. See dart3-idioms-and-coding-standards for value-type and record rules.

Structural layout

The window is edge-to-edge; the targets are inset — never the same question. Paint the background full-bleed behind the system bars, then wrap the interactive content in SafeArea and add margins inside it.

Compute cell size from the viewport; never hardcode a tile dimension and never assert a minimum one (a size floor fires exactly where large text needs the room most — the real constraint is that the label fits). The GridView axis trap is silent: in a vertical grid, crossAxisSpacing is the column gap and mainAxisSpacing is the row gap.

Full treatment — computed sizing math, IME behaviour, MediaQuery.viewInsets, and when to use a Column+grid instead of a spanning cell — in references/structural-layout.md. See accessibility-as-code for reading a11y state from MediaQuery and never clamping textScaler, and design-system-structure for token/theme structure.

Anti-patterns

Widget _buildXxx() helper methods for any non-trivial UI — no Element boundary, no const, no key, untestable. Make a class.
God-widget: a 300-line build() with the whole screen inline.
Repository/DAO/SharedPreferences call in build() or initState() — route through the Notifier and a single write path.
DateTime.now() in a widget — a widget never reads a wall clock; the Notifier precomputes time-derived values from Clock injected via clockProvider (see state-management-riverpod).
Creating controllers in build() (recreated every frame) instead of in State + dispose().
setState() to refresh app/session data that belongs in a Notifier — setState is only for local ephemeral UI.
ListView(children: hugeList.map(...).toList()) — builds every row eagerly. Use .builder.
Container for everything (over-wrapping) — use the specific, cheaper widget.
GlobalKey/ObjectKey for identity — delete; use ValueKey(id) where a list reorders.
Hardcoded hex / left-right padding / literal user strings — use theme tokens, EdgeInsetsDirectional, and ARB localization.
A gesture with no visible fallback, or clamping textScaler to force a layout to fit — fix the layout, not the scale.
A shared-library widget importing a domain type or reading a provider — it can no longer be reasoned about or tested in isolation.

Definition of done

flutter-architecture — the layer DAG and the dumb-View contract this widget sits inside; widget-composition is the deep dive on building those Views.
flutter-performance — const subtrees, .select rebuild scoping, RepaintBoundary, dispose discipline, measuring in profile mode.
state-management-riverpod — the one-Notifier-per-feature ViewModel this View watches, and the watch/read/listen split.
design-system-structure — how tokens/theme/components are structured and consumed (the source of the styles this skill reads).
accessibility-as-code — reading a11y state from MediaQuery, Semantics roles/labels, sort keys, never clamping textScaler.
i18n-rtl-l10n — owns the directional-geometry (EdgeInsetsDirectional/AlignmentDirectional) and ARB-localization rules the strings and insets these widgets render must follow.
dart3-idioms-and-coding-standards — the complexity-limit table these rules cite; which construct each data class earns; records intra-layer only; immutable value types.
adaptive-layout — responsive breakpoints, tablet/foldable master-detail, and NavigationRail-vs-BottomNav by width (the responsiveness layer around these structural primitives).
forms-and-input — Form/TextFormField validation, focus traversal, and keyboard-action wiring for the input fields these screens compose.
widget-golden-and-a11y-testing — pumping an extracted widget class and asserting layout/overflow/golden across device and scale.
custom-canvas-and-gestures — the one exception where pixels live on a CustomPainter instead of a widget tree.

References

Flutter — Performance best practices (const constructors, minimize rebuilds, lazy builders)
Flutter — UI layer case study / dumb views
Flutter API — StatelessWidget · ListView.builder · EdgeInsetsDirectional · SafeArea
Riverpod — Reading a provider / ConsumerWidget, select
Dart — Effective Dart: Style · Linter rules