flutter-conventions-index
The repo front-door for a Flutter/Dart app — the cross-cutting house rules (feature-first layered MVVM, immutable state with a single write path, Riverpod 3.x for state + DI, typed Result/Failure errors, dumb widgets, injected side effects, complexity limits) plus a routing table that sends each task to its deep-dive skill and a recommended feature build order. Use at the start of any Flutter/Dart work, before writing or reviewing a feature, when deciding which layer or package code belongs in, when unsure which skill governs a task (architecture, state, widgets, persistence, testing, i18n, design), or when onboarding to the conventions.
zakariaf · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add zakariaf/Flutter-Skills --skill flutter-conventions-indexAbout this skill
name: flutter-conventions-index description: The repo front-door for a Flutter/Dart app — the cross-cutting house rules (feature-first layered MVVM, immutable state with a single write path, Riverpod 3.x for state + DI, typed Result/Failure errors, dumb widgets, injected side effects, complexity limits) plus a routing table that sends each task to its deep-dive skill and a recommended feature build order. Use at the start of any Flutter/Dart work, before writing or reviewing a feature, when deciding which layer or package code belongs in, when unsure which skill governs a task (architecture, state, widgets, persistence, testing, i18n, design), or when onboarding to the conventions.
Flutter Conventions — Index
The front door for this Flutter/Dart app. It states the cross-cutting house rules every task obeys, then routes each concern to a focused skill. For any non-trivial task: apply the rules here, then open the specialized skill for depth. This is the only skill that names every other skill in the library.
Assumes a single-package Flutter app by default. Monorepo / pub-workspace guidance is fenced inside the skills that own it (project-structure-and-packages, codegen-and-toolchain) — never required for a small app.
Non-negotiable rules
- Feature-first, layered, downward-only. Group by feature (a folder), then by layer: View → ViewModel → Repository → Service/data. Lower layers never import upward; the dependency graph is a strict DAG. WHY: an acyclic downward graph is the only structural guard against a big ball of mud. (
flutter-architecture,project-structure-and-packages) - Widgets are dumb. No business logic, data access, math, or formatting in a widget — it reads state and renders. WHY: logic in
build()is untestable and rebuilds unpredictably. (widget-composition) - One ViewModel per screen, over immutable state. A single
Notifier/AsyncNotifierowns private mutable state and exposes it as an immutable value with value equality; a transition assigns a new state, never mutates in place. WHY: immutable value + single owner makes every change diffable and testable. (state-management-riverpod) - Riverpod 3.x is state + DI. Modern
Notifier/AsyncNotifier/Future/Streamproviders only; providers are the DI container. Noget_it, nopackage:provider, no legacyStateProvider/StateNotifierProvider/ChangeNotifierProvider. WHY: one composition model, no second DI framework to reconcile. (state-management-riverpod,app-startup-and-bootstrap) - Single write path. A widget or ViewModel never mutates persisted state directly; every mutation is a repository method that persists first, then republishes via a stream. WHY: one durable, observable route means state is never half-written. (
state-management-riverpod,persistence-drift) - Derive, don't store; depend on abstractions. Compute derived values on read instead of caching a second copy; program against interfaces you inject, not concretes. WHY: a duplicated source of truth drifts out of sync; injected seams keep code testable. (
flutter-architecture,service-boundary-and-native) - Immutable models, typed errors. Domain and UI state are
freezed/sealed value types withcopyWithand value equality. Pure functions are total — they return uncertainty, never throw. Recoverable I/O returns a sealedResult<T, F extends Failure>, switched exhaustively; never a swallowedcatch (_) {}. WHY: the compiler enforces every case; failures carry a stable code, not a localized string. (error-handling-typed-results,dart3-idioms-and-coding-standards) - Side effects behind injected interfaces. Every platform/native effect (clock, notifications, share, analytics, storage) is a Dart interface behind a provider, overridden once at the composition root, faked in tests. Read "now" from an injected
Clock, neverDateTime.now(). WHY: a global side effect is a non-deterministic, untestable dependency. (service-boundary-and-native,value-objects-money-and-units) - Async is never silent.
awaiteverything or handle theFutureexplicitly; no fire-and-forget arrow callbacks. GuardBuildContext/mountedafter everyawait; dispose controllers, subscriptions, timers, and sinks. WHY: a droppedFutureswallows errors no lint catches. (async-safety) - Small units, extracted widget classes. Keep to the complexity-limit table owned by
dart3-idioms-and-coding-standards(method ≤30,build()≤80, file ≤300, positional params ≤3, logic nesting ≤3 — widget build trees may nest to ≤5 as the stated exception). ExtractconstStatelessWidgetclasses, never_buildX()methods;consteverywhere legal. WHY: small const subtrees rebuild less and read faster. (dart3-idioms-and-coding-standards,widget-composition,flutter-performance) - Names carry roles.
…Screen/…Notifier/…Repository/…Service/…Failure; Effective-Dart casing verbatim; full words with units in the name; file named after its primary declaration. WHY: a grep or a filename should reveal the layer. (naming-conventions) - RTL and a11y by construction. Use directional (
start/end) geometry only, never hardcoded left/right; every user string comes from an ARB viagen_l10n; label and role every semantic node; never clamp the text scaler or rely on color alone. WHY: correctness properties are cheap to build in and expensive to retrofit. (i18n-rtl-l10n,accessibility-as-code) - Test the shape of the code, not a fixed ratio. Pure core: fast, clock-injected
package:test+ property invariants. Everything else:flutter_test+mocktail,ProviderContainer.test()+overrideWith— fake the repository/services, not theNotifier. One acceptance test anchors the whole app. WHY: tests follow risk; the pure core carries the invariants. (testing-strategy,widget-golden-and-a11y-testing) - **Strict lint