flutter-widgets
/flutter-widgets
Flutter widget design with strict immutability and deterministic builds — screens as Scaffold layout shells, self-connected components that watch one provider, rows and sections that take values and callbacks (ConsumerWidget only for themed colors), state lifted out of widgets, controlled components, pure build methods (no DateTime.now, Random, globals, or I/O), StatefulWidget only for framework-owned objects (TextEditingController, AnimationController, FocusNode, ScrollController) synced from lifted state, extracting widgets instead of helper methods, const constructors, keys, BuildContext ru
- Author
- Dee9975 ↗
- Repository
- cc-skills-flutter ↗
- Licence
- MIT
- Last repository change
- 05.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Flutter widget design with strict immutability and deterministic builds — screens as Scaffold layout shells, self-connected components that watch one provider, rows and sections that take values and callbacks (ConsumerWidget only for themed colors), state lifted out of widgets, controlled components, pure build methods (no DateTime.now, Random, globals, or I/O), StatefulWidget only for framework-owned objects (TextEditingController, AnimationController, FocusNode, ScrollController) synced from lifted state, extracting widgets instead of helper methods, const constructors, keys, BuildContext ru
Original author description
Flutter widget design with strict immutability and deterministic builds — screens as Scaffold layout shells, self-connected components that watch one provider, rows and sections that take values and callbacks (ConsumerWidget only for themed colors), state lifted out of widgets, controlled components, pure build methods (no DateTime.now, Random, globals, or I/O), StatefulWidget only for framework-owned objects (TextEditingController, AnimationController, FocusNode, ScrollController) synced from lifted state, extracting widgets instead of helper methods, const constructors, keys, BuildContext ru
How it works
- The rules
- Controlled widgets
- Controller leaves
- Screens and components
- Composition rules
- Forms
- Keys
- BuildContext
- Animations
- Review checklist
SKILL.md preview
---
name: flutter-widgets
description: "Flutter widget design with strict immutability and deterministic builds — screens as Scaffold layout shells, self-connected components that watch one provider, rows and sections that take values and callbacks (ConsumerWidget only for themed colors), state lifted out of widgets, controlled components, pure build methods (no DateTime.now, Random, globals, or I/O), StatefulWidget only for framework-owned objects (TextEditingController, AnimationController, FocusNode, ScrollController) synced from lifted state, extracting widgets instead of helper methods, const constructors, keys, BuildContext rules, state-driven forms and validation, declarative animations. Use when building, splitting, or reviewing widgets, or when removing setState and widget-owned state."
license: MIT
metadata:
author: Matiss Kalnins
version: "0.5.0"
---
**Persona:** You build widgets as pure, deterministic functions of their inputs. Immutable configuration goes in, a widget tree comes out, and user intent leaves through callbacks. Widgets never own the truth. They receive it.
## The rules
1. **Every widget is immutable and uses a primary constructor**: `class const PriceRow({super.key, required final String label}) extends StatelessWidget { ... }`. Fields are declared `final` in the header, the constructor is `const`, `super.key` comes first, and collections passed in are treated as read-only (never call `add`/`remove`/`sort` on a list you received). `Widget` is already `@immutable`. Make the `must_be_immutable` lint an error (see `dart-lint`).
2. **State lives in providers, not widgets.** State is lifted to the state layer (notifiers, providers) and scoped as high as it's meaningful: app, feature, or route. Widgets either read it from a provider (self-connected components) or get **values in** and **callbacks out** (rows and sections).
3. **Deterministic `build`.** The same constructor arguments and inherited values always produce the same tree. `build` never reads `DateTime.now()`, `Random()`, mutable globals or singletons, `Platform.*`, or any I/O. Anything that varies is passed in as a value (current time, seeded random results, platform flags), usually from the state layer or an InheritedWidget.
4. **StatefulWidget is only for framework-owned mutable objects** that need a lifecycle: `TextEditingController`, `AnimationController`, `ScrollController`, `PageController`, `TabController`, `FocusNode`. They live in a small leaf widget that **syncs from** lifted state in `didUpdateWidget` and **reports to** it through callbacks. The source of truth stays outside.
5. **No meaningful values in `State` fields.** A `State` doesn't store the selected tab, expanded/collapsed flags, form values, loading flags, filters, or pagination. If losing the value on rebuild, rotation, or navigation would change what the user sees, it's lifted state.
## Controlled widgets
```dart
// Bad: the widget owns the truth, so it can't be restored, tested, or shared
class _FilterChipsState extends State<FilterChips> {
final _selected = <Category>{};
void _toggle(Category c) => setState(() => _selected.contains(c) ? _selected.remove(c) : _selected.add(c));
// ...
}
// Good: immutable, controlled, deterministic
class const FilterChips({
super.key,
required final IList<Category> categories,
required final ISet<Category> selected,
required final ValueChanged<Category> onToggle,
}) extends StatelessWidget {
@override
Widget build(BuildContext context) => Wrap(
spacing: spaceMD,
children: [
for (final c in categories)
FilterChip(
label: Text(c.label),
selected: selected.contains(c),
onSelected: (_) => onToggle(c),
),
],
);
}
```
## Controller leaves
The controller is an implementation detail. The lifted value is the truth.
```dart
class const SearchField({
super.key,
required final String query, // owned by the state layer
required final ValueChanged<String> onChanged, // intent goes back up
}) extends StatefulWidget {
@override
State<SearchField> createState() => _SearchFieldState();
}
class _SearchFieldState extends State<SearchField> {
late final TextEditingController _controller = TextEditingController(text: widget.query);
@override
void didUpdateWidget(SearchField oldWidget) {
super.didUpdateWidget(oldWidget);
if (widget.query == _controller.text) return; // guard clause, no else
_controller.value = TextEditingValue(
text: widget.query,
selection: .collapsed(offset: widget.query.length),
);
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) =>
TextField(controller: _controller, onChanged: widget.onChanged);
}
```
- The `State` holds only the controller, never a copy of `query` it could edit on its own.
- Dispose every controller and `FocusNode` in `dispose`, before `super.dispose()`.
- `flutter_hooks` (`useTextEditingController`, `useAnimationController`) is an acceptable way to remove this boilerplate. The same rule applies: hooks hold framework objects only, never lifted state.
## Screens and components
**Screens** (`screens/`) are layout shells: a `Scaffold` + `SafeArea` holding a title and the feature's components. A screen is a `StatelessWidget` unless it takes a route parameter and fetches with it (`PlayerDetailsScreen(playerId)` watches `playerProvider(playerId)`).
```dart
class const LeadersScreen({super.key}) extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final leadersState = ref.watch(leadersProvider);
return Scaffold(
body: SafeArea(
child: Column(
crossAxisAlignment: .stretch,
children: [
const Padding(
padding: .fromLTRB(spaceXL, spaceMD, spaceXL, 0),
child: Text("Leaders", style: AppTextStyles.title1Bold),
),
const LeaderGroupToggle(),
const LeaderCategoryChips(),
// While a new category loads the old list stays visible, so show
// progress in place of the divider. Both are 2 px tall.
switch (leadersState) {
AsyncValue(isLoading: true, hasValue: true) => const LinearProgressIndicator(minHeight: 2),
_ => const Divider(height: 2),
},
const Expanded(child: LeadersList()),
],
),
),
);
}
}
```
**Components** (`components/`) come in two kinds:
- **Self-connected components** are lists, toggles, chips, and switches that own one piece of the screen end to end. They watch their provider, render the error/data/loading states (see `flutter-riverpod`), call notifier methods, retry with `ref.invalidate`, and navigate with `unawaited(context.push(...))`. Examples: `LeadersList`, `LeaderCategoryChips`, `StandingsViewToggle`, `DarkThemeSwitch`.
- **Rows and sections** take values and callbacks (`LeaderRow(rank:, leader:, category:, onTap:)`, `GameDetailsView(landing:, rightRail:)`). They don't watch data providers. Many are still `ConsumerWidget`s, but only to read themed colors (`ref.textSecondary`, see `flutter-theming`).
Watch the narrowest provider, as close as possible to where its value is shown, so a change rebuilds only that component (see `flutter-performance`).
## Composition rules
1. **Extract widgets, not methods.** A `Widget _buildHeader()` method rebuilds with its parent and can't be `const`. A `class _Header extends StatelessWidget` can be.
2. **Use `const` everywhere possible.** Enable the `prefer_const_constructors` lints.
3. **Keep `build` pure and cheap.** No I/O, no `Future`/stream creation, no controller construction.
4. **Pass only what's needed**: `user.name`, not `user`, when that's all the widget shows.
5. **Prefer composition over inheritance.** Wrap widgets. Don't subclass concrete ones.
## Forms
Form values and validation errors are lifted state. Validation is a pure function of that state.
```dart
// state layer
@freezed
class const SignUpForm({final String email = "", final bool submitted = false}) with _$SignUpForm {
String? get emailError => switch ((submitted, email.contains("@"))) {
(true, false) => "Enter a valid email",
_ => null,
};
}
// widget: controlled and deterministic
TextField(
controller: ..., // controller leaf, as above
onChanged: notifier.emailChanged,
decoration: InputDecoration(errorText: form.emailError),
);
FilledButton(onPressed: notifier.submit, child: const Text("Sign up"));
```
Don't keep the truth in `Form`/`GlobalKey<FormState>`/`validator:`, since those store validation state inside the widget tree.
## Keys
- Most widgets don't need keys.
- Give stateful list items that reorder, insert, or remove a `ValueKey(item.id)`, so controller leaves stay attached to the right item.
- Use a `GlobalKey` only to move a subtree while keeping its state. Never create one inside `build`. `UniqueKey()` in `build` rebuilds from scratch every frame, which is almost always a bug.
## BuildContext
- `Scaffold.of(context)` with the context of the widget that creates the Scaffold fails. Use a `Builder`, or extract a child widget.
- Use `MediaQuery.sizeOf(context)` etc. rather than `MediaQuery.of(context)`. Inherited values are inputs too, so read them narrowly.
- Never store a `BuildContext`. Check `context.mounted` after async gaps (async work belongs in the state layer anyway).
## Animations
- Prefer **implicit, declarative** animations (`AnimatedContainer`, `AnimatedOpacity`, `AnimatedSwitcher`, `TweenAnimationBuilder`). The target value is an input, so the widget stays deterministic.
- Explicit `AnimationController`s are controller leaves. They animate toward a value passed in from lifted state, and they don't decide on their own what the end state is.
- Respect `MediaQuery.disableAnimationsOf(context)`.
## Review checklist
- [ ] No `setState` holding meaningful values; only controller leaves are stateful
- [ ] Widgets use primary constructors (`class const X({super.key, required final T field}) extends ...`); received collections are never mutated
- [ ] `build` is deterministic: no `DateTime.now()`, `Random`, globals, or I/O
- [ ] Screens are layout shells; self-connected components own one provider each; rows and sections take values and callbacks
- [ ] Form values and validation errors live in the state layer
- [ ] Every controller/FocusNode disposed; no `_buildX()` helper methods
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Dee9975/cc-skills-flutter | 100 | MIT |
| HoangNguyen0403/agent-skills-standard | 100 | MIT |
Database snapshot: 13.11.2026 · package version 8527e6fcf11c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100flutter-widget-architect
Architects Flutter widget trees and Riverpod or Bloc state so rebuilds are scoped, build() stays pure, and const widgets skip recomposition. Use when someone asks "why is my Flutter screen janky", "should I use Riverpod or Bloc", "my whole page rebuilds when one field changes",… - 100flutter-state-management
State management in Flutter with strict immutability and lifted state — lifting every meaningful value (selection, filters, form drafts, expanded flags, pagination) out of widgets into an owning notifier/bloc/view model scoped to app, feature, or route; deeply immutable state… - 85flutter
Flutter framework for building beautiful, fast user experiences for mobile, web, and desktop from a single codebase. Use when building Flutter apps, working with widgets, state management, navigation, animations, or Material Design components. - 100flutter-expert
Expert in Flutter SDK, Dart, widgets, state management, and cross-platform mobile development. Use when the user mentions mobile, Dart, cross platform, UI, or state management, or when the task involves Flutter Architecture, Widget Fundamentals, State Management Approaches, or Lifecycle Methods. - 90Flutter
Builds, debugs, and ships Flutter apps: widgets, layout constraints, state management, navigation, performance, and store releases. Use when writing Dart widgets or screens; when a RenderFlex overflows, a viewport is given unbounded height, or a RenderBox was not laid out; when… - 100flutter-adding-home-screen-widgets
Adds home screen widgets to a Flutter app for Android and iOS. Use when providing glanceable app information or quick actions on the device home screen.