Flutter Conventions

Write and review Flutter/Dart code using the user's conventions. They live in references/flutter-guide.md, organised by topic, and each rule says why it exists.

The guide is the source of truth. Read the sections that match the task before writing code; the user edits it over time, so don't rely on memory of its rules. Where the guide and general Flutter advice disagree, follow the guide. Where the guide is silent, use current Flutter best practice in the same spirit: small widgets, explicit state, theme-driven styling.

When to use

• Writing a new screen, widget, form, route or data fetch in a Flutter app.
• Reviewing or fixing Flutter/Dart code ("does this look right?", "why does this crash?").
• Planning where files go in lib/.
• Explaining a Flutter or Dart concept. Use the guide's React/JS analogies; the user knows React.
• Not for Dart backends or CLI tools beyond the basics in guide sections 1–2, and not for other mobile frameworks (React Native, SwiftUI, Kotlin).

Steps

1. Read the relevant guide sections. Pick by topic from the contents list. Most tasks touch 2–4 sections. Always include section 11 (pitfalls) when writing or reviewing code.
2. Match the project. Read the files near where you're working. Keep the project's existing SDK idioms (dot shorthand or not, import style, folder names) unless they break a guide rule.
3. Do the task.
   • Writing: follow the guide's patterns. Use const constructors, stateless widgets unless state is owned, theme colors and text styles, relative imports for project files, and route constants.
   • Reviewing/fixing: walk the code against the relevant sections and the section 11 checklist. Report real problems only. A style the guide allows (e.g. a private _buildX() helper, ALL-CAPS section comments) is not a finding.
   • Explaining: answer the question first, then show a short example in the guide's style.
4. Check before finishing: every await followed by setState has a mounted check; every controller is disposed; every widget uses its inputs; no route string is repeated.

Output format

• Code: complete, runnable files or clearly marked changed sections, with file paths (lib/pages/coop_page.dart). Keep comments short and about why, the way the guide does.
• Review: a list ordered by impact. For each item: location, the guide rule (e.g. "§6.3 mounted after await"), one sentence on the concrete consequence, then a minimal before/after.
• Explanation: a direct answer, an analogy if it helps (React/JS), and a short code example.

When a guide rule shaped a non-obvious choice, cite it in one line (e.g. "Route names are constants in routes.dart (§9.5), so a typo fails at compile time."). This keeps the user learning the conventions instead of copying output.

References

• references/flutter-guide.md: the full conventions guide (Dart basics, async/HTTP, imports and layout, widgets, theming, state, gestures, forms, routing, dev loop, pitfalls checklist).