widget-composition

A helper method's subtree has no Element of its own, so it rebuilds with the parent, cannot be const, cannot take a Key, and cannot be found with find.byType in tests. A widget class gets its own Element boundary, enabling const canonicalization, keyed identity, and isolated testing.

Keep build() under roughly 80 lines with nesting at or below five levels, and extract complex sections into separate widget classes. Move I/O, DateTime.now(), NumberFormat, and domain math into the Notifier, which precomputes ready-to-render UI state the widget only paints.

Use ValueKey(item.id) for rows in reorderable, filterable, or variable-length lists so Element state tracks data identity rather than position. Fixed-order stateless lists need no key, and GlobalKey for identity or lookups is a design smell — lift that state to the ViewModel instead.

In a vertical GridView, crossAxisSpacing is the gap between columns and mainAxisSpacing is the gap between rows, which is counter-intuitive. Swapping them silently exchanges horizontal and vertical gutters, visible only when the design uses unequal spacing.

Read platform accessibility state like bold text, high contrast, and text scale directly from MediaQuery at build time, since it is an InheritedWidget with correct invalidation. Never mirror it into a provider and never clamp textScaler — fix the layout to survive scaling instead.

Use StatefulWidget only for genuinely local, ephemeral UI state such as AnimationController, TextEditingController, ScrollController, or FocusNode. App, domain, and session state belongs in a Notifier, and every controller created in State must be disposed in dispose().