Instruction file imported from gskinnerTeam/flutter-hatcha-app (.github/instructions/flutter.instructions.md). Copyright stays with the author.

Dart & Flutter Conventions

Follow Effective Dart and Flutter Architecture Recommendations. The rules below are the subset most relevant to this project, plus project-specific conventions.

Project-Specific Rules

Theming & Styles

• Access design tokens via context.styles, context.colors, or context.textStyles — never use the deprecated $styles global.
• Extend text styles with copyWith — don't create TextStyle() from scratch (loses font family and responsive scaling).
• Use semantic color tokens (context.colors.critical, context.colors.primaryA1) — never hardcode hex colors.
• Use the spacing scale (context.styles.insets.md) — don't use arbitrary pixel values.
• Use the theming skill for full design token reference.

Service Locator

• Import globals from service_locator.dart: $app, $genUi, $gemini, $theme, $palette, $digestService, $dashboardControllers, $toast.
• $styles is deprecated — use context.styles instead.

GoRouter

• Route builders must validate state.extra shape/nullability — avoid force-casting with ! to prevent deep-link/runtime crashes.
• Provide graceful fallback Scaffolds when extras are lost (e.g. hot reload).

GenUI Catalogue Items

• Follow the 5-step file convention: _name, _schema, extension type, example data, CatalogItem.
• Use the catalogue-items skill for full reference.

Effective Dart (Key Rules)

Style

• DO name types and extensions using UpperCamelCase.
• DO name packages, directories, and source files using lowercase_with_underscores.
• DO name other identifiers using lowerCamelCase.
• PREFER lowerCamelCase for constant names.
• DO capitalize acronyms longer than two letters like words.
• DO place dart: imports before package: imports before relative imports.
• DO sort import sections alphabetically.
• DO format code using dart format.

Documentation

• DO use /// doc comments to document members and types.
• PREFER writing doc comments for public APIs.
• DO start doc comments with a single-sentence summary.
• PREFER brevity. AVOID redundancy with surrounding context.
• DO put doc comments before metadata annotations.

Usage

• PREFER relative import paths.
• DON'T explicitly initialize variables to null.
• PREFER string interpolation over concatenation.
• DO use collection literals when possible.
• DON'T use .length to check if a collection is empty.
• DON'T create a lambda when a tear-off will do.
• DO use initializing formals when possible.
• DO use ; instead of {} for empty constructor bodies.
• PREFER async/await over raw futures.
• DO use rethrow to rethrow a caught exception.

Design

• DO use terms consistently. AVOID abbreviations.
• PREFER making declarations private.
• PREFER final fields for read-only properties.
• DO type annotate variables without initializers and return types on function declarations.
• DON'T redundantly type annotate initialized local variables.
• AVOID positional boolean parameters.
• DO override hashCode if you override ==.

Flutter Architecture (Key Rules)

• Separate UI and data layers. Logic classes by responsibility.
• Do not put logic in widgets. Only simple conditionals, animation, layout, and routing logic.
• Use immutable data models. Create new instances for changes — no in-place mutation.
• Use unidirectional data flow. Data flows from data layer → UI layer; interactions flow back.
• Use ChangeNotifier / Listenable for widget state observation.
• Use go_router for navigation. Validate state.extra on every route.
• Use dependency injection via GetIt (service_locator.dart).
• Write unit tests for every service/logic class. Write widget tests for views.