Claude Cursor Skill

flutter-best-practices

Use when writing, reviewing, refactoring, or planning Flutter/Dart code — screens, features, project structure, state management, folders, widgets, cubits/blocs, repositories, services, or tests.

LLM Mart · 0 points · 17 views 0 listing impressions 0 install-command copies
Download evanca-flutter-ai-rules-skills_flutter-best-practices-ced864a.zip · 16 KB

Install

skills CLI npx skills add https://github.com/evanca/flutter-ai-rules/tree/main/skills/flutter-best-practices
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install evanca-flutter-ai-rules@llmmart
Git git clone https://github.com/evanca/flutter-ai-rules.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole evanca/flutter-ai-rules collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Flutter Best Practices

Standards for building maintainable Flutter apps, distilled from the official Flutter architecture guide and LeanCode's experience shipping 40+ Flutter projects (including a 30-developer banking app). Apply these when writing new code; when touching existing code, prefer consistency with the surrounding codebase and raise conflicts with these standards rather than silently rewriting.

How to use this skill

Read the reference file that matches the task. Read more than one when tasks overlap (e.g. a new feature touches both structure and coding style).

Task Read
Design layers, decide where logic lives, MVVM, repositories/services references/architecture-layers.md
Create/organize a feature, folder structure, state management wiring references/feature-structure.md
Write or review Dart/Flutter code, widgets, tests, lints references/dart-coding-practices.md
Multi-team/multi-package apps, monorepo, navigation, localization, API contracts, E2E tests references/enterprise-scale.md
App localization setup, reusable UI package string ownership, language picker visibility references/localization-package-boundaries.md

For a quick task (small widget fix, one-line review comment), the core rules below may be enough on their own.

Core rules (always apply)

Architecture

  1. Separate UI from data. Two broad layers: UI (views + view models / cubits) and Data (repositories + services). Dependencies point one way: View → ViewModel → Repository → Service. Lower layers never import upper layers. Repositories never depend on each other.
  2. Views hold no business logic. Widgets may contain show/hide conditionals, animation, layout, and simple routing logic — nothing that transforms or decides about data. All data logic lives in the view model (or cubit/bloc), which has no access to BuildContext.
  3. Organize by feature, not by layer. Everything a feature needs — state management, widgets, models — lives under one feature directory. Don't create top-level blocs/, widgets/, models/ buckets that scatter a feature across the tree.
  4. State is immutable and explicit. Model UI state as a sealed/union type (initial / inProgress / failure / ready) so every case is handled exhaustively. One-off effects (snackbars, navigation) are events, not state.
  5. Add layers only when they pay for themselves. Start with view-model → API client. Introduce a repository when you need caching, offline, or merging sources. Introduce a use case only when logic merges multiple repositories, is genuinely complex, or is reused by several view models.

Coding

  1. Prefer intent-revealing widgets over Container. Use Padding, SizedBox, ColoredBox, DecoratedBox, Center — they are const-able and self-describing. Container is fine only when combining several properties at once.
  2. Use modern Dart. Pattern matching (if (x case final v?)), switch expressions with exhaustiveness, records and destructuring, collection if/for/spreads instead of .add() loops, expression bodies for pass-through async functions (no redundant async/await).
  3. Prefix sliver-returning widgets with Sliver so misuse in the wrong scroll context is caught at a glance.
  4. Tests tell a story. Use expressive matchers (isEmpty, throwsA, isA, completion) and minimize dependencies — plain Text/SizedBox over design-system widgets in test fixtures. Test cubits/view models in isolation from the widget tree.
  5. Every // ignore: gets a reason on the same or preceding line. Log errors with dedicated error/stackTrace parameters, never string interpolation.

SDK versions & security

Pin a minimum SDK that includes published security fixes, and keep projects current.

  • Minimum stable SDKs: Dart ≥ 3.13.7, Flutter ≥ 3.47.8. These revoke the compromised eMudhra intermediate CA certificates behind a TLS man-in-the-middle advisory (GHSA-frr6-h895-5pxp).
  • The fix is compiled into the engine, so upgrading the SDK is not enough — Android, Windows, and Linux apps must be rebuilt and redeployed to apply it. iOS, macOS, and web builds are not affected.
  • Set the floor in pubspec.yaml:
    environment:
      sdk: ">=3.13.7 <4.0.0"
      flutter: ">=3.47.8"
    

Workflow checklists

Adding a new feature/screen

  1. Read references/feature-structure.md and mirror the existing project's conventions for the feature directory.
  2. Define the state as a union type first; then the cubit/view model; then the widgets. Constructor-inject dependencies; scope them to the feature's widget subtree.
  3. Data comes in through a repository or typed API client — never fetched inside a widget.
  4. Add unit tests for the cubit/view model logic before wiring UI details.

Reviewing Flutter code

Check, in order of importance:

  1. Logic in the right layer (rule 1–2)? Any BuildContext in business logic?
  2. State modeled as immutable union types, all cases handled?
  3. Feature self-contained, or does it reach into another feature's internals?
  4. Widget choices (rule 6), modern Dart (rule 7), sliver naming (rule 8)?
  5. Tests present for logic, readable, minimal dependencies?
  6. Unexplained // ignore:, string-interpolated error logs, deprecated patterns still spreading?

Starting a new project

  1. Read references/architecture-layers.md for the layer blueprint and references/feature-structure.md for the folder skeleton.
  2. If more than ~2 teams or clearly separable domains are involved, read references/enterprise-scale.md and consider a Melos monorepo with one package per domain from day one.
  3. Set up strict lints early (leancode_lint or equivalent + custom rules) — retrofitting is far more expensive.

Package palette

Defaults that these standards assume (swap for project-local equivalents when the codebase already uses something else):

  • State: bloc (Cubit) + freezed for union-type states; bloc_presentation for one-off UI events
  • DI: provider scoped to widget subtrees (accepting its lack of compile-time safety as the lesser evil)
  • Boilerplate reduction: flutter_hooks
  • Monorepo: melos
  • Localization: flutter_localizations + intl with .arb files
  • Lints: leancode_lint
  • E2E/UI tests: patrol

The official Flutter guide is state-management-agnostic (MVVM with ChangeNotifier works too); what matters is the layer separation, not the package. See the reference files for rationale and trade-offs.

Files (flutter-ai-rules)
  • references
    • architecture-layers.md 5.6 KB
      Loading…
    • dart-coding-practices.md 5.5 KB
      Loading…
    • enterprise-scale.md 6.2 KB
      Loading…
    • feature-structure.md 6.5 KB
      Loading…
    • localization-package-boundaries.md 3 KB
      Loading…
  • SKILL.md 7.2 KB
    ---
    name: flutter-best-practices
    description: "Use when writing, reviewing, refactoring, or planning Flutter/Dart code — screens, features, project structure, state management, folders, widgets, cubits/blocs, repositories, services, or tests."
    license: MIT
    ---
    
    # Flutter Best Practices
    
    Standards for building maintainable Flutter apps, distilled from the official
    Flutter architecture guide and LeanCode's experience shipping 40+ Flutter
    projects (including a 30-developer banking app). Apply these when writing new
    code; when touching existing code, prefer consistency with the surrounding
    codebase and raise conflicts with these standards rather than silently
    rewriting.
    
    ## How to use this skill
    
    Read the reference file that matches the task. Read more than one when tasks
    overlap (e.g. a new feature touches both structure and coding style).
    
    | Task | Read |
    |---|---|
    | Design layers, decide where logic lives, MVVM, repositories/services | [references/architecture-layers.md](references/architecture-layers.md) |
    | Create/organize a feature, folder structure, state management wiring | [references/feature-structure.md](references/feature-structure.md) |
    | Write or review Dart/Flutter code, widgets, tests, lints | [references/dart-coding-practices.md](references/dart-coding-practices.md) |
    | Multi-team/multi-package apps, monorepo, navigation, localization, API contracts, E2E tests | [references/enterprise-scale.md](references/enterprise-scale.md) |
    | App localization setup, reusable UI package string ownership, language picker visibility | [references/localization-package-boundaries.md](references/localization-package-boundaries.md) |
    
    For a quick task (small widget fix, one-line review comment), the core rules
    below may be enough on their own.
    
    ## Core rules (always apply)
    
    ### Architecture
    
    1. **Separate UI from data.** Two broad layers: UI (views + view models /
       cubits) and Data (repositories + services). Dependencies point one way:
       `View → ViewModel → Repository → Service`. Lower layers never import upper
       layers. Repositories never depend on each other.
    2. **Views hold no business logic.** Widgets may contain show/hide
       conditionals, animation, layout, and simple routing logic — nothing that
       transforms or decides about data. All data logic lives in the view model
       (or cubit/bloc), which has no access to `BuildContext`.
    3. **Organize by feature, not by layer.** Everything a feature needs — state
       management, widgets, models — lives under one feature directory. Don't
       create top-level `blocs/`, `widgets/`, `models/` buckets that scatter a
       feature across the tree.
    4. **State is immutable and explicit.** Model UI state as a sealed/union type
       (initial / inProgress / failure / ready) so every case is handled
       exhaustively. One-off effects (snackbars, navigation) are events, not
       state.
    5. **Add layers only when they pay for themselves.** Start with
       view-model → API client. Introduce a repository when you need caching,
       offline, or merging sources. Introduce a use case only when logic merges
       multiple repositories, is genuinely complex, or is reused by several view
       models.
    
    ### Coding
    
    6. **Prefer intent-revealing widgets over `Container`.** Use `Padding`,
       `SizedBox`, `ColoredBox`, `DecoratedBox`, `Center` — they are const-able
       and self-describing. `Container` is fine only when combining several
       properties at once.
    7. **Use modern Dart.** Pattern matching (`if (x case final v?)`), switch
       expressions with exhaustiveness, records and destructuring, collection
       `if`/`for`/spreads instead of `.add()` loops, expression bodies for
       pass-through async functions (no redundant `async`/`await`).
    8. **Prefix sliver-returning widgets with `Sliver`** so misuse in the wrong
       scroll context is caught at a glance.
    9. **Tests tell a story.** Use expressive matchers (`isEmpty`, `throwsA`,
       `isA`, `completion`) and minimize dependencies — plain `Text`/`SizedBox`
       over design-system widgets in test fixtures. Test cubits/view models in
       isolation from the widget tree.
    10. **Every `// ignore:` gets a reason** on the same or preceding line. Log
        errors with dedicated `error`/`stackTrace` parameters, never string
        interpolation.
    
    ## SDK versions & security
    
    Pin a minimum SDK that includes published security fixes, and keep projects
    current.
    
    - **Minimum stable SDKs: Dart ≥ 3.13.7, Flutter ≥ 3.47.8.** These revoke the
      compromised eMudhra intermediate CA certificates behind a TLS
      man-in-the-middle advisory
      ([GHSA-frr6-h895-5pxp](https://github.com/dart-lang/sdk/security/advisories/GHSA-frr6-h895-5pxp)).
    - The fix is compiled into the engine, so **upgrading the SDK is not enough** —
      Android, Windows, and Linux apps must be **rebuilt and redeployed** to apply
      it. iOS, macOS, and web builds are not affected.
    - Set the floor in `pubspec.yaml`:
      ```yaml
      environment:
        sdk: ">=3.13.7 <4.0.0"
        flutter: ">=3.47.8"
      ```
    
    ## Workflow checklists
    
    ### Adding a new feature/screen
    
    1. Read [references/feature-structure.md](references/feature-structure.md)
       and mirror the existing project's conventions for the feature directory.
    2. Define the state as a union type first; then the cubit/view model; then
       the widgets. Constructor-inject dependencies; scope them to the feature's
       widget subtree.
    3. Data comes in through a repository or typed API client — never fetched
       inside a widget.
    4. Add unit tests for the cubit/view model logic before wiring UI details.
    
    ### Reviewing Flutter code
    
    Check, in order of importance:
    
    1. Logic in the right layer (rule 1–2)? Any `BuildContext` in business logic?
    2. State modeled as immutable union types, all cases handled?
    3. Feature self-contained, or does it reach into another feature's internals?
    4. Widget choices (rule 6), modern Dart (rule 7), sliver naming (rule 8)?
    5. Tests present for logic, readable, minimal dependencies?
    6. Unexplained `// ignore:`, string-interpolated error logs, deprecated
       patterns still spreading?
    
    ### Starting a new project
    
    1. Read [references/architecture-layers.md](references/architecture-layers.md)
       for the layer blueprint and
       [references/feature-structure.md](references/feature-structure.md) for the
       folder skeleton.
    2. If more than ~2 teams or clearly separable domains are involved, read
       [references/enterprise-scale.md](references/enterprise-scale.md) and
       consider a Melos monorepo with one package per domain from day one.
    3. Set up strict lints early (`leancode_lint` or equivalent + custom rules) —
       retrofitting is far more expensive.
    
    ## Package palette
    
    Defaults that these standards assume (swap for project-local equivalents when
    the codebase already uses something else):
    
    - **State:** `bloc` (Cubit) + `freezed` for union-type states;
      `bloc_presentation` for one-off UI events
    - **DI:** `provider` scoped to widget subtrees (accepting its lack of
      compile-time safety as the lesser evil)
    - **Boilerplate reduction:** `flutter_hooks`
    - **Monorepo:** `melos`
    - **Localization:** `flutter_localizations` + `intl` with `.arb` files
    - **Lints:** `leancode_lint`
    - **E2E/UI tests:** `patrol`
    
    The official Flutter guide is state-management-agnostic (MVVM with
    ChangeNotifier works too); what matters is the layer separation, not the
    package. See the reference files for rationale and trade-offs.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.