flutter-pro-skills 0.0.0-stage → 1.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/NOTICE.md +26 -0
- package/README.ar.md +122 -0
- package/README.md +268 -2
- package/install.sh +86 -0
- package/package.json +39 -4
- package/skills/dart-flutter-best-practices/SKILL.md +242 -0
- package/skills/dart-flutter-best-practices/assets/AGENTS-snippet.md +24 -0
- package/skills/dart-flutter-best-practices/assets/analysis_options.yaml +86 -0
- package/skills/dart-flutter-best-practices/references/effective-dart.md +338 -0
- package/skills/dart-flutter-best-practices/scripts/format-dart-hook.sh +48 -0
- package/skills/dart-flutter-review/SKILL.md +342 -0
- package/skills/dart-flutter-review/references/ci.md +212 -0
- package/skills/dart-flutter-review/references/finding-format.md +238 -0
- package/skills/dart-flutter-review/references/review-guide.md +217 -0
- package/skills/dart-flutter-review/references/reviewer-prompts.md +1456 -0
- package/skills/dart-flutter-review/scripts/ci_action.sh +81 -0
- package/skills/dart-flutter-review/scripts/heuristics.py +1135 -0
- package/skills/dart-flutter-review/scripts/review.sh +440 -0
- package/skills/dart-naming/SKILL.md +208 -0
- package/skills/dart-naming/references/naming.md +522 -0
- package/skills/flutter-accessibility/SKILL.md +211 -0
- package/skills/flutter-accessibility/references/placement-by-architecture.md +185 -0
- package/skills/flutter-accessibility/references/review.md +92 -0
- package/skills/flutter-accessibility/references/rules.md +306 -0
- package/skills/flutter-accessibility/references/semantics-and-labels.md +187 -0
- package/skills/flutter-accessibility/references/testing-accessibility.md +152 -0
- package/skills/flutter-accessibility/references/visual-and-input.md +148 -0
- package/skills/flutter-accessibility/scripts/check_accessibility.py +1411 -0
- package/skills/flutter-adaptive-layout/SKILL.md +239 -0
- package/skills/flutter-adaptive-layout/references/input-and-platform.md +221 -0
- package/skills/flutter-adaptive-layout/references/placement-by-architecture.md +86 -0
- package/skills/flutter-adaptive-layout/references/review.md +98 -0
- package/skills/flutter-adaptive-layout/references/rules.md +502 -0
- package/skills/flutter-adaptive-layout/references/size-classes-and-layout.md +326 -0
- package/skills/flutter-adaptive-layout/references/testing-adaptive-layouts.md +158 -0
- package/skills/flutter-adaptive-layout/scripts/check_adaptive.py +1743 -0
- package/skills/flutter-architecture/SKILL.md +276 -0
- package/skills/flutter-architecture/references/anti-patterns/data-and-repositories.md +264 -0
- package/skills/flutter-architecture/references/anti-patterns/dependency-rule.md +314 -0
- package/skills/flutter-architecture/references/anti-patterns/di-and-globals.md +105 -0
- package/skills/flutter-architecture/references/anti-patterns/over-engineering.md +140 -0
- package/skills/flutter-architecture/references/anti-patterns/pattern-specific.md +473 -0
- package/skills/flutter-architecture/references/anti-patterns/presentation.md +411 -0
- package/skills/flutter-architecture/references/anti-patterns/state.md +348 -0
- package/skills/flutter-architecture/references/anti-patterns.md +195 -0
- package/skills/flutter-architecture/references/bloc.md +339 -0
- package/skills/flutter-architecture/references/clean-architecture.md +270 -0
- package/skills/flutter-architecture/references/detect.md +310 -0
- package/skills/flutter-architecture/references/mvc.md +249 -0
- package/skills/flutter-architecture/references/mvn.md +377 -0
- package/skills/flutter-architecture/references/mvvm.md +319 -0
- package/skills/flutter-architecture/references/repository-pattern.md +215 -0
- package/skills/flutter-architecture/references/state-management.md +190 -0
- package/skills/flutter-architecture/scripts/arch_check.py +2546 -0
- package/skills/flutter-design-system/SKILL.md +208 -0
- package/skills/flutter-design-system/references/components-and-placement.md +240 -0
- package/skills/flutter-design-system/references/review.md +92 -0
- package/skills/flutter-design-system/references/rules.md +438 -0
- package/skills/flutter-design-system/references/tokens-and-theming.md +338 -0
- package/skills/flutter-design-system/scripts/check_design_system.py +1517 -0
- package/skills/flutter-error-handling/SKILL.md +190 -0
- package/skills/flutter-error-handling/references/error-flow-by-architecture.md +646 -0
- package/skills/flutter-error-handling/references/global-handlers.md +246 -0
- package/skills/flutter-error-handling/references/result-vs-exceptions.md +302 -0
- package/skills/flutter-error-handling/references/review.md +85 -0
- package/skills/flutter-error-handling/references/rules.md +823 -0
- package/skills/flutter-error-handling/scripts/check_errors.py +2005 -0
- package/skills/flutter-feature-scaffold/SKILL.md +219 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc.dart.tmpl +44 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc_test.dart.tmpl +41 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/event.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/state.dart.tmpl +37 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/view.dart.tmpl +55 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/view_test.dart.tmpl +29 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/data_source.dart.tmpl +28 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/dto.dart.tmpl +24 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/entity.dart.tmpl +18 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/repository.dart.tmpl +6 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl.dart.tmpl +26 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl_test.dart.tmpl +60 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/usecase.dart.tmpl +13 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/usecase_test.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/core/failure.dart.tmpl +24 -0
- package/skills/flutter-feature-scaffold/assets/templates/core/http_client.dart.tmpl +35 -0
- package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit.dart.tmpl +29 -0
- package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit_test.dart.tmpl +41 -0
- package/skills/flutter-feature-scaffold/assets/templates/cubit/view.dart.tmpl +52 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/api_client.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/binding.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/controller.dart.tmpl +34 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/controller_test.dart.tmpl +42 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/state.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/view.dart.tmpl +38 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/entity.dart.tmpl +9 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier.dart.tmpl +25 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier_test.dart.tmpl +56 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/repository.dart.tmpl +5 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl.dart.tmpl +32 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl_test.dart.tmpl +58 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/request.dart.tmpl +10 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/response.dart.tmpl +20 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/source.dart.tmpl +32 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/state.dart.tmpl +28 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase_test.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/view.dart.tmpl +52 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/view_test.dart.tmpl +34 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/widget.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_client.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_model.dart.tmpl +20 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/command.dart.tmpl +66 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository.dart.tmpl +7 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl.dart.tmpl +23 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl_test.dart.tmpl +54 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/result.dart.tmpl +33 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase.dart.tmpl +15 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase_test.dart.tmpl +22 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/view.dart.tmpl +47 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/view_test.dart.tmpl +27 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel.dart.tmpl +32 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel_test.dart.tmpl +64 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/notifier.dart.tmpl +41 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/notifier_test.dart.tmpl +44 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/state.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/view.dart.tmpl +39 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/view_test.dart.tmpl +30 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier.dart.tmpl +23 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier_test.dart.tmpl +55 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/providers.dart.tmpl +24 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/view.dart.tmpl +45 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/view_test.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/list.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/model.dart.tmpl +27 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/repository.dart.tmpl +6 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl.dart.tmpl +25 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl_test.dart.tmpl +59 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/source.dart.tmpl +28 -0
- package/skills/flutter-feature-scaffold/references/profiles.md +145 -0
- package/skills/flutter-feature-scaffold/scripts/scaffold.py +1069 -0
- package/skills/flutter-firebase/SKILL.md +256 -0
- package/skills/flutter-firebase/references/firestore-data.md +178 -0
- package/skills/flutter-firebase/references/placement-by-architecture.md +309 -0
- package/skills/flutter-firebase/references/review.md +109 -0
- package/skills/flutter-firebase/references/rules.md +636 -0
- package/skills/flutter-firebase/references/security-rules-and-app-check.md +226 -0
- package/skills/flutter-firebase/references/setup-messaging-config.md +169 -0
- package/skills/flutter-firebase/references/testing-firebase.md +157 -0
- package/skills/flutter-firebase/scripts/check_firebase.py +2155 -0
- package/skills/flutter-forms/SKILL.md +191 -0
- package/skills/flutter-forms/references/multi-step-and-dirty-state.md +190 -0
- package/skills/flutter-forms/references/placement-by-architecture.md +326 -0
- package/skills/flutter-forms/references/review.md +88 -0
- package/skills/flutter-forms/references/rules.md +238 -0
- package/skills/flutter-forms/references/secure-inputs.md +256 -0
- package/skills/flutter-forms/references/validation-patterns.md +285 -0
- package/skills/flutter-forms/scripts/check_forms.py +1278 -0
- package/skills/flutter-i18n/SKILL.md +241 -0
- package/skills/flutter-i18n/references/formatting.md +174 -0
- package/skills/flutter-i18n/references/gen-l10n-and-arb.md +315 -0
- package/skills/flutter-i18n/references/placement-by-architecture.md +460 -0
- package/skills/flutter-i18n/references/review.md +93 -0
- package/skills/flutter-i18n/references/rtl-and-arabic.md +367 -0
- package/skills/flutter-i18n/scripts/check_i18n.py +1805 -0
- package/skills/flutter-navigation/SKILL.md +199 -0
- package/skills/flutter-navigation/references/deep-links-and-security.md +242 -0
- package/skills/flutter-navigation/references/go-router-patterns.md +361 -0
- package/skills/flutter-navigation/references/placement-by-architecture.md +414 -0
- package/skills/flutter-navigation/references/review.md +102 -0
- package/skills/flutter-navigation/references/rules.md +256 -0
- package/skills/flutter-navigation/scripts/check_navigation.py +1424 -0
- package/skills/flutter-networking/SKILL.md +202 -0
- package/skills/flutter-networking/references/client-setup.md +180 -0
- package/skills/flutter-networking/references/dtos-and-json.md +114 -0
- package/skills/flutter-networking/references/placement-by-architecture.md +147 -0
- package/skills/flutter-networking/references/requests.md +160 -0
- package/skills/flutter-networking/references/review.md +94 -0
- package/skills/flutter-networking/references/rules.md +487 -0
- package/skills/flutter-networking/references/testing-with-fakes.md +137 -0
- package/skills/flutter-networking/scripts/check_networking.py +1607 -0
- package/skills/flutter-performance/SKILL.md +219 -0
- package/skills/flutter-performance/references/diagnosing-jank.md +134 -0
- package/skills/flutter-performance/references/isolates.md +105 -0
- package/skills/flutter-performance/references/lists-images-painting.md +116 -0
- package/skills/flutter-performance/references/rebuild-scope.md +154 -0
- package/skills/flutter-performance/references/review.md +93 -0
- package/skills/flutter-performance/references/rules.md +400 -0
- package/skills/flutter-performance/scripts/check_performance.py +1360 -0
- package/skills/flutter-persistence/SKILL.md +198 -0
- package/skills/flutter-persistence/references/caching-and-offline.md +169 -0
- package/skills/flutter-persistence/references/choosing-storage.md +188 -0
- package/skills/flutter-persistence/references/migrations.md +201 -0
- package/skills/flutter-persistence/references/placement-by-architecture.md +232 -0
- package/skills/flutter-persistence/references/review.md +93 -0
- package/skills/flutter-persistence/references/rules.md +405 -0
- package/skills/flutter-persistence/scripts/check_persistence.py +1690 -0
- package/skills/flutter-platform-integration/SKILL.md +219 -0
- package/skills/flutter-platform-integration/references/channels-and-pigeon.md +194 -0
- package/skills/flutter-platform-integration/references/ffi.md +147 -0
- package/skills/flutter-platform-integration/references/permissions-and-isolates.md +124 -0
- package/skills/flutter-platform-integration/references/placement-by-architecture.md +102 -0
- package/skills/flutter-platform-integration/references/plugins-and-platform-views.md +129 -0
- package/skills/flutter-platform-integration/references/review.md +94 -0
- package/skills/flutter-platform-integration/references/rules.md +557 -0
- package/skills/flutter-platform-integration/references/testing-platform-code.md +125 -0
- package/skills/flutter-platform-integration/scripts/check_platform.py +1824 -0
- package/skills/flutter-release/SKILL.md +219 -0
- package/skills/flutter-release/references/ci-cd.md +156 -0
- package/skills/flutter-release/references/flavors-and-environments.md +127 -0
- package/skills/flutter-release/references/release-checklist.md +79 -0
- package/skills/flutter-release/references/review.md +91 -0
- package/skills/flutter-release/references/rules.md +417 -0
- package/skills/flutter-release/references/signing-and-versioning.md +113 -0
- package/skills/flutter-release/references/store-requirements.md +61 -0
- package/skills/flutter-release/scripts/check_release.py +1930 -0
- package/skills/flutter-secure-defaults/SKILL.md +270 -0
- package/skills/flutter-secure-defaults/references/network-and-auth.md +203 -0
- package/skills/flutter-secure-defaults/references/review.md +103 -0
- package/skills/flutter-secure-defaults/references/rules.md +452 -0
- package/skills/flutter-secure-defaults/references/secrets-and-config.md +136 -0
- package/skills/flutter-secure-defaults/references/secure-defaults-by-layer.md +474 -0
- package/skills/flutter-secure-defaults/references/secure-scaffold-checklist.md +147 -0
- package/skills/flutter-secure-defaults/references/storage-and-privacy.md +161 -0
- package/skills/flutter-secure-defaults/references/webview-and-links.md +153 -0
- package/skills/flutter-secure-defaults/scripts/check_secure_defaults.py +1571 -0
- package/skills/flutter-testing/SKILL.md +197 -0
- package/skills/flutter-testing/references/review.md +71 -0
- package/skills/flutter-testing/references/strategy-by-architecture.md +491 -0
- package/skills/flutter-testing/references/test-smells.md +475 -0
- package/skills/flutter-testing/references/widget-and-golden.md +337 -0
- package/skills/flutter-testing/scripts/test_gaps.py +1268 -0
- package/skills/flutter-ui-practices/SKILL.md +158 -0
- package/skills/flutter-ui-practices/references/flutter-ui.md +282 -0
- package/skills/flutter-ui-practices/references/review.md +89 -0
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dart-flutter-best-practices
|
|
3
|
+
description: Hub for writing idiomatic Dart and Flutter code - Effective Dart, the official lints, the language features your SDK allows and the project's own conventions, verified with `dart format` and `dart analyze`. Use it whenever you write or refactor general Dart code, a package or CLI, ask if code is idiomatic, or set up lints, `analysis_options.yaml` or formatting. When one concern dominates, load that specialist instead - `flutter-feature-scaffold`, `dart-naming`, `flutter-ui-practices`, `flutter-performance` (jank), `flutter-architecture`, `flutter-testing`, `flutter-error-handling`, `flutter-secure-defaults`, `flutter-navigation`, `flutter-forms`, `flutter-i18n`, `flutter-persistence`, `flutter-networking`, `flutter-firebase`, `flutter-platform-integration`, `flutter-design-system`, `flutter-adaptive-layout`, `flutter-accessibility`, `flutter-release`, `dart-flutter-review` (reviews).
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
author: abdelrahman-abied
|
|
7
|
+
version: "1.7.2"
|
|
8
|
+
suite: flutter-pro-skills
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Dart & Flutter best practices (hub)
|
|
12
|
+
|
|
13
|
+
This is the entry point of the `flutter-pro-skills` suite. It holds the rules
|
|
14
|
+
that apply to *all* Dart code, the WRITE workflow, and team setup. It sends
|
|
15
|
+
everything more specific to a sibling skill, so you load only what the task
|
|
16
|
+
touches.
|
|
17
|
+
|
|
18
|
+
The aim is code that reads as if one careful author wrote it. That means it
|
|
19
|
+
agrees with the official guidance, it fits the project it lives in, and it
|
|
20
|
+
avoids the bugs idiomatic Dart rules out by construction (unawaited futures,
|
|
21
|
+
swallowed errors, `late` fields read too early).
|
|
22
|
+
|
|
23
|
+
## Precedence when sources disagree
|
|
24
|
+
|
|
25
|
+
1. **The project's own decisions**: its lint config, its project instructions
|
|
26
|
+
file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/…`,
|
|
27
|
+
`.github/copilot-instructions.md`), its declared architecture, and any
|
|
28
|
+
convention it uses consistently. Effective Dart's first theme is *be
|
|
29
|
+
consistent*. A "correct" rule applied to half a codebase makes it worse. If
|
|
30
|
+
the project disables a lint on purpose, it has decided, so don't argue
|
|
31
|
+
with it file by file.
|
|
32
|
+
2. **The chosen pattern's canonical source**: MVN follows the `mvn` spec by its
|
|
33
|
+
author, Bloc follows bloclibrary.dev, Riverpod follows riverpod.dev, and
|
|
34
|
+
MVVM follows the docs.flutter.dev architecture guide.
|
|
35
|
+
3. **Effective Dart**: the baseline for all Dart code. The full checklist is
|
|
36
|
+
in `references/effective-dart.md`.
|
|
37
|
+
4. **Flutter team guidance for apps**, from docs.flutter.dev and `flutter_lints`.
|
|
38
|
+
5. **The Flutter framework's internal style guide.** It was written for
|
|
39
|
+
contributors to the framework, and several of its rules contradict Effective
|
|
40
|
+
Dart (`kConstant` prefixes, 100-column lines). Follow it only where the
|
|
41
|
+
project already does.
|
|
42
|
+
|
|
43
|
+
Keep each rule at the strength of its source keyword. **DO/DON'T** means
|
|
44
|
+
near-always, **PREFER/AVOID** means unless there's a good reason, and
|
|
45
|
+
**CONSIDER** depends on context. A PREFER deviation is not a bug.
|
|
46
|
+
|
|
47
|
+
## Route to the right skill
|
|
48
|
+
|
|
49
|
+
Load the sibling skill for the part of the task in front of you. If your agent
|
|
50
|
+
doesn't auto-load skills, read the fallback path, which is relative to this
|
|
51
|
+
skill's folder because the suite installs as sibling folders. If a sibling is
|
|
52
|
+
missing, say so and carry on with Effective Dart and this file.
|
|
53
|
+
|
|
54
|
+
| The task involves | Load | Fallback path |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| Naming or renaming anything: classes, methods, booleans, files, providers, blocs, events | `dart-naming` | `../dart-naming/SKILL.md` |
|
|
57
|
+
| Widgets, `State` lifecycle and `dispose`, `BuildContext` across `await`, `build()` cost, lists, theming, accessibility, widget tests | `flutter-ui-practices` | `../flutter-ui-practices/SKILL.md` |
|
|
58
|
+
| Where code belongs: layers, folders, MVVM / MVN / Bloc / Clean Architecture / repositories, state management, anti-patterns | `flutter-architecture` | `../flutter-architecture/SKILL.md` |
|
|
59
|
+
| Creating a new feature, screen or module in the project's own architecture (generates the files, dry run first) | `flutter-feature-scaffold` | `../flutter-feature-scaffold/SKILL.md` |
|
|
60
|
+
| Writing or reviewing tests, what to test per layer, untested code, flaky tests, mocks vs fakes, goldens | `flutter-testing` | `../flutter-testing/SKILL.md` |
|
|
61
|
+
| try/catch, exceptions vs `Result`, failures, error states, "spinner never stops", crash reporting, global handlers | `flutter-error-handling` | `../flutter-error-handling/SKILL.md` |
|
|
62
|
+
| Reviewing, auditing or critiquing code, a diff or a PR | `dart-flutter-review` | `../dart-flutter-review/SKILL.md` |
|
|
63
|
+
| Tokens, credentials, auth, storage, HTTP clients, logging of sensitive data, WebViews, "is this secure", secure defaults while writing | `flutter-secure-defaults` | `../flutter-secure-defaults/SKILL.md` |
|
|
64
|
+
| go_router, deep links, redirects/guards, passing route arguments, url_launcher | `flutter-navigation` | `../flutter-navigation/SKILL.md` |
|
|
65
|
+
| Forms, validation, TextFormField, focus, submit/double-submit, password/OTP inputs | `flutter-forms` | `../flutter-forms/SKILL.md` |
|
|
66
|
+
| Localization, ARB/gen-l10n, plurals, dates/numbers, RTL and Arabic | `flutter-i18n` | `../flutter-i18n/SKILL.md` |
|
|
67
|
+
| Jank, slow scrolling, excess rebuilds, `const`, `RepaintBoundary`, lazy lists and slivers, isolates and `compute`, image decode size, DevTools profiling | `flutter-performance` | `../flutter-performance/SKILL.md` |
|
|
68
|
+
| Local storage and caching: Drift, sqflite, Hive/Isar, shared_preferences, offline-first and sync, migrations | `flutter-persistence` | `../flutter-persistence/SKILL.md` |
|
|
69
|
+
| API calls and the HTTP client: Dio/http/retrofit setup, timeouts, interceptors, DTOs and JSON, pagination, cancellation, retry, WebSockets | `flutter-networking` | `../flutter-networking/SKILL.md` |
|
|
70
|
+
| Firebase: init, Auth, Firestore queries and listeners, security rules, App Check, FCM, Crashlytics, Remote Config, emulators | `flutter-firebase` | `../flutter-firebase/SKILL.md` |
|
|
71
|
+
| Native code: platform channels, Pigeon, FFI, platform views, writing a plugin, runtime permissions, background isolates | `flutter-platform-integration` | `../flutter-platform-integration/SKILL.md` |
|
|
72
|
+
| Design tokens, `ThemeData`/`ColorScheme`, `ThemeExtension`, shared components, dark mode, raw colours or sizes in feature code | `flutter-design-system` | `../flutter-design-system/SKILL.md` |
|
|
73
|
+
| Phones, tablets, foldables, desktop and web from one codebase: size classes and breakpoints, list-detail, navigation bar vs rail, orientation, hover/keyboard input, `dart:io Platform` on web | `flutter-adaptive-layout` | `../flutter-adaptive-layout/SKILL.md` |
|
|
74
|
+
| Accessibility: `Semantics`, labels, tap targets, contrast, text scale, focus order, screen-reader tests | `flutter-accessibility` | `../flutter-accessibility/SKILL.md` |
|
|
75
|
+
| Shipping the app: flavors and environments, signing, versioning, store requirements, CI/CD (GitHub Actions, Codemagic, Fastlane) | `flutter-release` | `../flutter-release/SKILL.md` |
|
|
76
|
+
| Deep security audit: obfuscation, pinning, RASP, attestation, build hardening | `flutter-security-audit` (separate repo, if installed) | `../flutter-security-audit/SKILL.md`; otherwise say it isn't installed |
|
|
77
|
+
|
|
78
|
+
Writing a Flutter feature usually touches several of these. Scaffold it in
|
|
79
|
+
the project's pattern, then use architecture for where the code goes, UI for
|
|
80
|
+
the widgets, naming for the new types, error handling for its failure paths,
|
|
81
|
+
and testing for its tests.
|
|
82
|
+
|
|
83
|
+
## First: read the project
|
|
84
|
+
|
|
85
|
+
Spend a minute on these before you write a line.
|
|
86
|
+
|
|
87
|
+
- **`pubspec.yaml` and the SDK constraint.** The *lower bound* of
|
|
88
|
+
`environment: sdk:` sets the package's language version, and that decides
|
|
89
|
+
which features compile. The installed SDK doesn't decide it. Features gated
|
|
90
|
+
by language version:
|
|
91
|
+
|
|
92
|
+
| Feature | Needs |
|
|
93
|
+
|---|---|
|
|
94
|
+
| Records, patterns, `switch` expressions, class modifiers (`sealed`, `final`, `base`, `interface`) | ≥3.0 |
|
|
95
|
+
| Extension types | ≥3.3 |
|
|
96
|
+
| Digit separators (`1_000_000`) | ≥3.6 |
|
|
97
|
+
| Wildcard `_` parameters and locals; the tall formatter style; `formatter:` options in `analysis_options.yaml` | ≥3.7 |
|
|
98
|
+
| `formatter: trailing_commas: preserve`; null-aware elements (`[?maybeItem]`) | ≥3.8 |
|
|
99
|
+
| Dot shorthands (`.start`, `.new()`, `.all(8)` where the type is known) | ≥3.10 |
|
|
100
|
+
| Private named initializing formals (`Foo({required this._client})`, preferred over `: _client = client`) | ≥3.12 |
|
|
101
|
+
|
|
102
|
+
Also note what kind of package it is (Flutter app, Dart package or CLI) and
|
|
103
|
+
which state-management, DI and routing packages it depends on.
|
|
104
|
+
- **`analysis_options.yaml`.** Check which set is included (`flutter_lints`,
|
|
105
|
+
`lints/recommended`, `very_good_analysis` or custom), which rules are added
|
|
106
|
+
or disabled, the `formatter: page_width`, and the `exclude:` globs.
|
|
107
|
+
Generated code (`*.g.dart`, `*.freezed.dart`) is never yours to edit or judge.
|
|
108
|
+
- **The project instructions file** (see Precedence). Look for a declared
|
|
109
|
+
architecture line such as `Architecture: Clean + MVN`, and for
|
|
110
|
+
team conventions.
|
|
111
|
+
- **Two or three neighbouring files.** Check `var` vs `final` locals (either is
|
|
112
|
+
fine, but pick one), relative vs `package:` imports, feature-first vs
|
|
113
|
+
layer-first folders, role suffixes (`Screen`/`Page`/`View`,
|
|
114
|
+
`Notifier`/`ViewModel`/`Bloc`), and how errors and results are modelled.
|
|
115
|
+
|
|
116
|
+
## WRITE mode: generating or changing code
|
|
117
|
+
|
|
118
|
+
1. **Match before you invent.** New code should look like it belongs: use the
|
|
119
|
+
project's state management, folder structure and suffixes. Match its
|
|
120
|
+
*conventions*, not its *defects*. If the neighbouring code leaks
|
|
121
|
+
controllers or does I/O in widgets, don't copy that. Write the new code
|
|
122
|
+
correctly and mention the existing problem.
|
|
123
|
+
2. **Load the sibling for what you touch** (routing table above). The
|
|
124
|
+
architecture skill decides *where* code goes, and the UI skill covers
|
|
125
|
+
lifecycle and `build()`. The naming skill applies whenever you introduce a
|
|
126
|
+
public name, because names are the one thing tools can't fix later without
|
|
127
|
+
breaking callers.
|
|
128
|
+
**Keep the reading budget small.** Read each needed sibling's SKILL.md,
|
|
129
|
+
not its `references/`: open a reference only when the SKILL.md sends you
|
|
130
|
+
there for the decision in front of you, and then read that section, not
|
|
131
|
+
the file. When `flutter-feature-scaffold` generates the feature, its
|
|
132
|
+
templates already pass every checker in the suite, so you don't need to
|
|
133
|
+
pre-load the performance, design-system, accessibility, networking or
|
|
134
|
+
persistence skills to write it. Check once on what you wrote with
|
|
135
|
+
`bash ../dart-flutter-review/scripts/review.sh <project-root> --diff HEAD --findings-only`
|
|
136
|
+
(every checker, only what is left to fix), and load a sibling only for a
|
|
137
|
+
finding you need to fix.
|
|
138
|
+
3. **Write it idiomatically the first time.** Hold the code to the judgment
|
|
139
|
+
rules below as you write. Default lints don't catch them. Use the newest
|
|
140
|
+
features the SDK constraint allows when they make the code clearer, and
|
|
141
|
+
never use features it doesn't allow.
|
|
142
|
+
4. **Verify with the toolchain, then fix only what you introduced.**
|
|
143
|
+
```bash
|
|
144
|
+
dart format <files you touched> # respects formatter: page_width
|
|
145
|
+
dart analyze <files or dir> # `flutter analyze` is equivalent in a Flutter app
|
|
146
|
+
```
|
|
147
|
+
Fix every error, warning and lint *your change* introduced. Don't reformat
|
|
148
|
+
or "fix" unrelated files: that buries the real change in noise and makes the
|
|
149
|
+
diff hard to review. If a lint must stay, write `// ignore: rule_name`
|
|
150
|
+
followed by the reason. An unexplained ignore is itself a finding. If
|
|
151
|
+
`dart` isn't available, say that you couldn't verify.
|
|
152
|
+
5. **Add the tests your change needs**, even when you extend existing code
|
|
153
|
+
rather than scaffold a feature. That means:
|
|
154
|
+
- a repository or source test over a fake: the success path and each
|
|
155
|
+
error mapping
|
|
156
|
+
- a logic-holder test of its state transitions (pagination: the next page
|
|
157
|
+
appended, a second request dropped while one is in flight)
|
|
158
|
+
- one widget test per screen state
|
|
159
|
+
|
|
160
|
+
**Size the tests to the change:** for a small change (a login, one
|
|
161
|
+
endpoint, one widget), write one focused test per layer you touched. Write
|
|
162
|
+
the full set only for a new feature. Use fakes, not mocks, and no real
|
|
163
|
+
network or delays. The checklist is in
|
|
164
|
+
`flutter-feature-scaffold` (its cross-cutting rules). Load
|
|
165
|
+
`flutter-testing` only for something it doesn't cover.
|
|
166
|
+
6. **Don't over-document.** Add `///` docs to public APIs whose names don't
|
|
167
|
+
say everything. Never write a comment that restates the name
|
|
168
|
+
(`/// The user id.` on `userId`). See *Documentation* in
|
|
169
|
+
`references/effective-dart.md`.
|
|
170
|
+
7. **Never hand-edit generated files.** Change the source and run
|
|
171
|
+
`dart run build_runner build -d` (or tell the user to).
|
|
172
|
+
|
|
173
|
+
## Dart judgment rules (no default lint catches these)
|
|
174
|
+
|
|
175
|
+
Check these by reading. Each maps to a row in `references/effective-dart.md`,
|
|
176
|
+
so grep it for the keyword (`late`, `FutureOr`, `getter`, `catch`) when you
|
|
177
|
+
want the exact guideline and its strength.
|
|
178
|
+
|
|
179
|
+
- Don't use `late` when you need to check whether the field was initialised.
|
|
180
|
+
Use a nullable field instead.
|
|
181
|
+
- Don't store what you can calculate. Use a getter, not a field that must be
|
|
182
|
+
kept in sync.
|
|
183
|
+
- Return `Future<void>`, never plain `void`, from async members that produce no
|
|
184
|
+
value. Avoid `FutureOr<T>` as a return type.
|
|
185
|
+
- Don't return a nullable `Future`, `Stream` or collection. Return an empty
|
|
186
|
+
one instead.
|
|
187
|
+
- Throw `Error` subclasses only for programmer mistakes, and `Exception`s for
|
|
188
|
+
runtime failures. Never catch `Error`. Don't write a bare `catch` without
|
|
189
|
+
`on` unless you rethrow or report the error.
|
|
190
|
+
- Don't create a class with only static members. Use top-level functions and
|
|
191
|
+
constants, or an `abstract final class` as a namespace.
|
|
192
|
+
- Use class modifiers (`final`, `base`, `interface`, `sealed`) to say how a
|
|
193
|
+
public class may be extended or implemented. Model closed sets of variants
|
|
194
|
+
as `sealed` with an exhaustive `switch`.
|
|
195
|
+
- Avoid positional `bool` parameters (`render(true)`); make them named.
|
|
196
|
+
- Override `hashCode` whenever you override `==`. Don't give mutable classes
|
|
197
|
+
value equality.
|
|
198
|
+
- Annotate types on public APIs and on variables without initialisers. Don't
|
|
199
|
+
annotate obvious locals.
|
|
200
|
+
- Every `Future` is awaited, returned, or wrapped in `unawaited(...)` on
|
|
201
|
+
purpose. A dropped future loses its error.
|
|
202
|
+
|
|
203
|
+
## Naming and Flutter UI live in sibling skills
|
|
204
|
+
|
|
205
|
+
- Naming rules (casing, `get`/`k`/`I` prefixes, booleans, callbacks, files, role suffixes) are in `dart-naming`.
|
|
206
|
+
- Widget rules (dispose, `context.mounted`, pure `build()`, widget classes over helper methods, lazy lists, `MediaQuery.sizeOf`) are in `flutter-ui-practices`.
|
|
207
|
+
- Deep dives that widget code often needs: `flutter-performance` (jank and rebuilds), `flutter-design-system` (tokens and themes), `flutter-accessibility` (semantics, targets, contrast), `flutter-persistence` (local storage and caching).
|
|
208
|
+
- Architecture rules (layering, which layer may call which, per-pattern conventions) are in `flutter-architecture`.
|
|
209
|
+
- Review procedure, severity and report format are in `dart-flutter-review`.
|
|
210
|
+
- If one of these isn't installed, apply Effective Dart and say which guidance was unavailable.
|
|
211
|
+
|
|
212
|
+
## Setup for teams
|
|
213
|
+
|
|
214
|
+
Offer these when the user wants a project to follow the conventions every
|
|
215
|
+
time. Don't add them silently.
|
|
216
|
+
|
|
217
|
+
- **Lint set: `assets/analysis_options.yaml`.** This is `flutter_lints` plus the
|
|
218
|
+
Effective Dart rules that aren't on by default, with each rule annotated by
|
|
219
|
+
the guideline it enforces. For a pure Dart package, change the include to
|
|
220
|
+
`package:lints/recommended.yaml` and drop the rules marked `[flutter]`.
|
|
221
|
+
Suggest it when the project has no `analysis_options.yaml` or an empty one.
|
|
222
|
+
`dart-flutter-review` also runs it as an informational EXTRA LINTS pass.
|
|
223
|
+
- **Project instructions: `assets/AGENTS-snippet.md`.** This is a short block
|
|
224
|
+
for `AGENTS.md`. The other agents' files (`CLAUDE.md`, `GEMINI.md`,
|
|
225
|
+
`.cursor/rules/`, `.github/copilot-instructions.md`) can include it or
|
|
226
|
+
copy it. Fill in its `Architecture:` line: reviewers judge the code against
|
|
227
|
+
the declared pattern rather than guessing it.
|
|
228
|
+
- **Format on write: `scripts/format-dart-hook.sh`** (optional). It runs
|
|
229
|
+
`dart format` on one edited `.dart` file and skips generated code. It never
|
|
230
|
+
blocks and always exits 0. It accepts a file path as `$1`, which works for
|
|
231
|
+
any hook system that can pass a path and for git pre-commit, or hook JSON
|
|
232
|
+
`{"tool_input":{"file_path":…}}` on stdin, for example a Claude Code
|
|
233
|
+
post-edit hook. Setup examples are in the script header.
|
|
234
|
+
|
|
235
|
+
## Files in this skill
|
|
236
|
+
|
|
237
|
+
| File | Use it when |
|
|
238
|
+
|---|---|
|
|
239
|
+
| `references/effective-dart.md` | You're writing non-trivial Dart, or you're unsure about a guideline. It has ~150 rows, one per guideline, each tagged with the lint that enforces it or *judgment*. Grep it for a keyword, or `grep -n '^##'` to find a section, rather than reading it whole |
|
|
240
|
+
| `assets/analysis_options.yaml` | Setting up or tightening lints |
|
|
241
|
+
| `assets/AGENTS-snippet.md` | Making every agent in a repo follow these conventions |
|
|
242
|
+
| `scripts/format-dart-hook.sh` | Enforcing formatting automatically |
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
## Dart / Flutter conventions
|
|
2
|
+
|
|
3
|
+
<!-- Paste this block into the repo's AGENTS.md. Agents that read another file
|
|
4
|
+
can include or copy it: CLAUDE.md (a line `@AGENTS.md` imports it),
|
|
5
|
+
GEMINI.md, .cursor/rules/*.mdc, .github/copilot-instructions.md.
|
|
6
|
+
It's loaded on every task, so keep it short; the flutter-pro-skills
|
|
7
|
+
skills carry the detail. Edit the [bracketed] parts and delete the rest. -->
|
|
8
|
+
|
|
9
|
+
- Follow Effective Dart and this repo's `analysis_options.yaml`. When writing or
|
|
10
|
+
reviewing Dart, use the `dart-flutter-best-practices` skill (it routes to
|
|
11
|
+
`dart-naming`, `flutter-ui-practices`, `flutter-architecture` and
|
|
12
|
+
`dart-flutter-review`).
|
|
13
|
+
- Architecture: [Clean + MVN | MVVM (Flutter guide) | Bloc + Clean | Provider | MVC | GetX]
|
|
14
|
+
(see the `flutter-architecture` skill). Reviewers judge the code against this
|
|
15
|
+
declared pattern, not a guessed one.
|
|
16
|
+
- Layout: [feature-first `lib/features/<name>/{domain,data,presentation}` | layer-first].
|
|
17
|
+
Role suffixes: [`XView`, `XNotifier`, `XState`, `XUseCase`, `XRepository`/`XRepositoryImpl`].
|
|
18
|
+
- Locals: [`final` unless reassigned | `var` everywhere]. Imports: [relative inside lib/ | `package:` only].
|
|
19
|
+
- Constants: lowerCamelCase (`defaultPadding`), no `k` prefix. [Delete this line if the repo uses `kFoo`.]
|
|
20
|
+
- Before saying a change is done, run `dart format <changed files>` and
|
|
21
|
+
`flutter analyze` (or `dart analyze`) with zero new issues. Never add
|
|
22
|
+
`// ignore:` without a reason comment.
|
|
23
|
+
- Never edit generated files (`*.g.dart`, `*.freezed.dart`). Change the
|
|
24
|
+
source and run `dart run build_runner build -d`.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Recommended analysis_options.yaml: Effective Dart + Flutter team lints.
|
|
2
|
+
#
|
|
3
|
+
# Base: package:flutter_lints (includes package:lints/recommended + core).
|
|
4
|
+
# For a pure Dart package or CLI, replace the include with
|
|
5
|
+
# include: package:lints/recommended.yaml
|
|
6
|
+
# and drop the Flutter-only rules marked [flutter].
|
|
7
|
+
#
|
|
8
|
+
# Every rule below is stable in the Dart linter registry and maps to an Effective
|
|
9
|
+
# Dart guideline or a Flutter team recommendation. Comments name the guideline.
|
|
10
|
+
# Delete anything your team disagrees with. Consistency matters more than any
|
|
11
|
+
# single rule.
|
|
12
|
+
|
|
13
|
+
include: package:flutter_lints/flutter.yaml
|
|
14
|
+
|
|
15
|
+
formatter:
|
|
16
|
+
page_width: 80 # Effective Dart: PREFER lines 80 characters or fewer (Dart >= 3.7)
|
|
17
|
+
# trailing_commas: preserve # opt-in manual control over splitting (Dart >= 3.8)
|
|
18
|
+
|
|
19
|
+
analyzer:
|
|
20
|
+
exclude:
|
|
21
|
+
- "**/*.g.dart"
|
|
22
|
+
- "**/*.freezed.dart"
|
|
23
|
+
- "**/*.gr.dart"
|
|
24
|
+
- "**/*.mocks.dart"
|
|
25
|
+
- "lib/generated/**"
|
|
26
|
+
language:
|
|
27
|
+
strict-casts: true # no implicit downcasts from dynamic
|
|
28
|
+
strict-inference: true # Effective Dart: DO annotate with dynamic instead of letting inference fail
|
|
29
|
+
strict-raw-types: true # Effective Dart: AVOID writing incomplete generic types
|
|
30
|
+
errors:
|
|
31
|
+
# Promote the bug-catching ones so they can't be ignored.
|
|
32
|
+
use_build_context_synchronously: error
|
|
33
|
+
cancel_subscriptions: warning
|
|
34
|
+
close_sinks: warning
|
|
35
|
+
unawaited_futures: warning
|
|
36
|
+
|
|
37
|
+
linter:
|
|
38
|
+
rules:
|
|
39
|
+
# --- Style: ordering & formatting ---
|
|
40
|
+
- directives_ordering # dart: → package: → relative; exports last; alphabetical
|
|
41
|
+
- prefer_relative_imports # Usage: PREFER relative import paths (within lib/)
|
|
42
|
+
# (incompatible with always_use_package_imports; pick one)
|
|
43
|
+
|
|
44
|
+
# --- Documentation ---
|
|
45
|
+
- comment_references # DO use [square brackets] for in-scope identifiers
|
|
46
|
+
# - public_member_api_docs # PREFER doc comments for public APIs (enable for published packages)
|
|
47
|
+
|
|
48
|
+
# --- Usage ---
|
|
49
|
+
- unnecessary_lambdas # DON'T create a lambda when a tear-off will do
|
|
50
|
+
- prefer_final_locals # DO follow a consistent var/final rule (this picks "final if not reassigned")
|
|
51
|
+
- prefer_final_in_for_each
|
|
52
|
+
- avoid_catching_errors # DON'T explicitly catch Error
|
|
53
|
+
- only_throw_errors # throw Error/Exception subtypes, never strings
|
|
54
|
+
- unawaited_futures # every Future is awaited or explicitly unawaited()
|
|
55
|
+
- avoid_void_async # DO use Future<void> for async members with no value
|
|
56
|
+
- cancel_subscriptions # lifecycle: StreamSubscription must be cancelled
|
|
57
|
+
- close_sinks # lifecycle: sinks/StreamControllers must be closed
|
|
58
|
+
- use_string_buffers # perf: StringBuffer in loops
|
|
59
|
+
- avoid_slow_async_io
|
|
60
|
+
# - avoid_catches_without_on_clauses # AVOID catches without `on` (strict; noisy in app code)
|
|
61
|
+
# - prefer_expression_function_bodies # CONSIDER => for simple members (noisy)
|
|
62
|
+
|
|
63
|
+
# --- Design ---
|
|
64
|
+
- always_declare_return_types # DO annotate return types on function declarations
|
|
65
|
+
- type_annotate_public_apis # DO type annotate fields/top-levels if not obvious
|
|
66
|
+
- omit_local_variable_types # DON'T redundantly type annotate initialized locals
|
|
67
|
+
- avoid_types_on_closure_parameters # DON'T annotate inferred params on function expressions
|
|
68
|
+
- avoid_positional_boolean_parameters # AVOID positional boolean parameters
|
|
69
|
+
- use_to_and_as_if_applicable # PREFER to___() / as___() naming
|
|
70
|
+
- avoid_returning_this # AVOID returning this for fluent interfaces (use cascades)
|
|
71
|
+
- avoid_setters_without_getters # DON'T define a setter without a getter
|
|
72
|
+
- use_setters_to_change_properties
|
|
73
|
+
- avoid_classes_with_only_static_members
|
|
74
|
+
- avoid_equals_and_hash_code_on_mutable_classes
|
|
75
|
+
- avoid_dynamic_calls # AVOID dynamic unless you want to disable static checking
|
|
76
|
+
- prefer_mixin # PREFER pure mixin / pure class over mixin class
|
|
77
|
+
- use_enums
|
|
78
|
+
- avoid_unused_constructor_parameters
|
|
79
|
+
|
|
80
|
+
# --- Flutter [flutter] ---
|
|
81
|
+
- use_colored_box
|
|
82
|
+
- use_decorated_box
|
|
83
|
+
- sized_box_shrink_expand
|
|
84
|
+
- avoid_redundant_argument_values
|
|
85
|
+
# - prefer_const_constructors # removed from flutter_lints 5 as noisy; enable if your team wants it
|
|
86
|
+
# - prefer_const_literals_to_create_immutables
|