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.
Files changed (234) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE.md +26 -0
  3. package/README.ar.md +122 -0
  4. package/README.md +268 -2
  5. package/install.sh +86 -0
  6. package/package.json +39 -4
  7. package/skills/dart-flutter-best-practices/SKILL.md +242 -0
  8. package/skills/dart-flutter-best-practices/assets/AGENTS-snippet.md +24 -0
  9. package/skills/dart-flutter-best-practices/assets/analysis_options.yaml +86 -0
  10. package/skills/dart-flutter-best-practices/references/effective-dart.md +338 -0
  11. package/skills/dart-flutter-best-practices/scripts/format-dart-hook.sh +48 -0
  12. package/skills/dart-flutter-review/SKILL.md +342 -0
  13. package/skills/dart-flutter-review/references/ci.md +212 -0
  14. package/skills/dart-flutter-review/references/finding-format.md +238 -0
  15. package/skills/dart-flutter-review/references/review-guide.md +217 -0
  16. package/skills/dart-flutter-review/references/reviewer-prompts.md +1456 -0
  17. package/skills/dart-flutter-review/scripts/ci_action.sh +81 -0
  18. package/skills/dart-flutter-review/scripts/heuristics.py +1135 -0
  19. package/skills/dart-flutter-review/scripts/review.sh +440 -0
  20. package/skills/dart-naming/SKILL.md +208 -0
  21. package/skills/dart-naming/references/naming.md +522 -0
  22. package/skills/flutter-accessibility/SKILL.md +211 -0
  23. package/skills/flutter-accessibility/references/placement-by-architecture.md +185 -0
  24. package/skills/flutter-accessibility/references/review.md +92 -0
  25. package/skills/flutter-accessibility/references/rules.md +306 -0
  26. package/skills/flutter-accessibility/references/semantics-and-labels.md +187 -0
  27. package/skills/flutter-accessibility/references/testing-accessibility.md +152 -0
  28. package/skills/flutter-accessibility/references/visual-and-input.md +148 -0
  29. package/skills/flutter-accessibility/scripts/check_accessibility.py +1411 -0
  30. package/skills/flutter-adaptive-layout/SKILL.md +239 -0
  31. package/skills/flutter-adaptive-layout/references/input-and-platform.md +221 -0
  32. package/skills/flutter-adaptive-layout/references/placement-by-architecture.md +86 -0
  33. package/skills/flutter-adaptive-layout/references/review.md +98 -0
  34. package/skills/flutter-adaptive-layout/references/rules.md +502 -0
  35. package/skills/flutter-adaptive-layout/references/size-classes-and-layout.md +326 -0
  36. package/skills/flutter-adaptive-layout/references/testing-adaptive-layouts.md +158 -0
  37. package/skills/flutter-adaptive-layout/scripts/check_adaptive.py +1743 -0
  38. package/skills/flutter-architecture/SKILL.md +276 -0
  39. package/skills/flutter-architecture/references/anti-patterns/data-and-repositories.md +264 -0
  40. package/skills/flutter-architecture/references/anti-patterns/dependency-rule.md +314 -0
  41. package/skills/flutter-architecture/references/anti-patterns/di-and-globals.md +105 -0
  42. package/skills/flutter-architecture/references/anti-patterns/over-engineering.md +140 -0
  43. package/skills/flutter-architecture/references/anti-patterns/pattern-specific.md +473 -0
  44. package/skills/flutter-architecture/references/anti-patterns/presentation.md +411 -0
  45. package/skills/flutter-architecture/references/anti-patterns/state.md +348 -0
  46. package/skills/flutter-architecture/references/anti-patterns.md +195 -0
  47. package/skills/flutter-architecture/references/bloc.md +339 -0
  48. package/skills/flutter-architecture/references/clean-architecture.md +270 -0
  49. package/skills/flutter-architecture/references/detect.md +310 -0
  50. package/skills/flutter-architecture/references/mvc.md +249 -0
  51. package/skills/flutter-architecture/references/mvn.md +377 -0
  52. package/skills/flutter-architecture/references/mvvm.md +319 -0
  53. package/skills/flutter-architecture/references/repository-pattern.md +215 -0
  54. package/skills/flutter-architecture/references/state-management.md +190 -0
  55. package/skills/flutter-architecture/scripts/arch_check.py +2546 -0
  56. package/skills/flutter-design-system/SKILL.md +208 -0
  57. package/skills/flutter-design-system/references/components-and-placement.md +240 -0
  58. package/skills/flutter-design-system/references/review.md +92 -0
  59. package/skills/flutter-design-system/references/rules.md +438 -0
  60. package/skills/flutter-design-system/references/tokens-and-theming.md +338 -0
  61. package/skills/flutter-design-system/scripts/check_design_system.py +1517 -0
  62. package/skills/flutter-error-handling/SKILL.md +190 -0
  63. package/skills/flutter-error-handling/references/error-flow-by-architecture.md +646 -0
  64. package/skills/flutter-error-handling/references/global-handlers.md +246 -0
  65. package/skills/flutter-error-handling/references/result-vs-exceptions.md +302 -0
  66. package/skills/flutter-error-handling/references/review.md +85 -0
  67. package/skills/flutter-error-handling/references/rules.md +823 -0
  68. package/skills/flutter-error-handling/scripts/check_errors.py +2005 -0
  69. package/skills/flutter-feature-scaffold/SKILL.md +219 -0
  70. package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc.dart.tmpl +44 -0
  71. package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc_test.dart.tmpl +41 -0
  72. package/skills/flutter-feature-scaffold/assets/templates/bloc/event.dart.tmpl +19 -0
  73. package/skills/flutter-feature-scaffold/assets/templates/bloc/state.dart.tmpl +37 -0
  74. package/skills/flutter-feature-scaffold/assets/templates/bloc/view.dart.tmpl +55 -0
  75. package/skills/flutter-feature-scaffold/assets/templates/bloc/view_test.dart.tmpl +29 -0
  76. package/skills/flutter-feature-scaffold/assets/templates/clean/data_source.dart.tmpl +28 -0
  77. package/skills/flutter-feature-scaffold/assets/templates/clean/dto.dart.tmpl +24 -0
  78. package/skills/flutter-feature-scaffold/assets/templates/clean/entity.dart.tmpl +18 -0
  79. package/skills/flutter-feature-scaffold/assets/templates/clean/repository.dart.tmpl +6 -0
  80. package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl.dart.tmpl +26 -0
  81. package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl_test.dart.tmpl +60 -0
  82. package/skills/flutter-feature-scaffold/assets/templates/clean/usecase.dart.tmpl +13 -0
  83. package/skills/flutter-feature-scaffold/assets/templates/clean/usecase_test.dart.tmpl +21 -0
  84. package/skills/flutter-feature-scaffold/assets/templates/core/failure.dart.tmpl +24 -0
  85. package/skills/flutter-feature-scaffold/assets/templates/core/http_client.dart.tmpl +35 -0
  86. package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit.dart.tmpl +29 -0
  87. package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit_test.dart.tmpl +41 -0
  88. package/skills/flutter-feature-scaffold/assets/templates/cubit/view.dart.tmpl +52 -0
  89. package/skills/flutter-feature-scaffold/assets/templates/getx/api_client.dart.tmpl +21 -0
  90. package/skills/flutter-feature-scaffold/assets/templates/getx/binding.dart.tmpl +19 -0
  91. package/skills/flutter-feature-scaffold/assets/templates/getx/controller.dart.tmpl +34 -0
  92. package/skills/flutter-feature-scaffold/assets/templates/getx/controller_test.dart.tmpl +42 -0
  93. package/skills/flutter-feature-scaffold/assets/templates/getx/state.dart.tmpl +31 -0
  94. package/skills/flutter-feature-scaffold/assets/templates/getx/view.dart.tmpl +38 -0
  95. package/skills/flutter-feature-scaffold/assets/templates/mvn/entity.dart.tmpl +9 -0
  96. package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier.dart.tmpl +25 -0
  97. package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier_test.dart.tmpl +56 -0
  98. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository.dart.tmpl +5 -0
  99. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl.dart.tmpl +32 -0
  100. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl_test.dart.tmpl +58 -0
  101. package/skills/flutter-feature-scaffold/assets/templates/mvn/request.dart.tmpl +10 -0
  102. package/skills/flutter-feature-scaffold/assets/templates/mvn/response.dart.tmpl +20 -0
  103. package/skills/flutter-feature-scaffold/assets/templates/mvn/source.dart.tmpl +32 -0
  104. package/skills/flutter-feature-scaffold/assets/templates/mvn/state.dart.tmpl +28 -0
  105. package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase.dart.tmpl +19 -0
  106. package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase_test.dart.tmpl +21 -0
  107. package/skills/flutter-feature-scaffold/assets/templates/mvn/view.dart.tmpl +52 -0
  108. package/skills/flutter-feature-scaffold/assets/templates/mvn/view_test.dart.tmpl +34 -0
  109. package/skills/flutter-feature-scaffold/assets/templates/mvn/widget.dart.tmpl +19 -0
  110. package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_client.dart.tmpl +31 -0
  111. package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_model.dart.tmpl +20 -0
  112. package/skills/flutter-feature-scaffold/assets/templates/mvvm/command.dart.tmpl +66 -0
  113. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository.dart.tmpl +7 -0
  114. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl.dart.tmpl +23 -0
  115. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl_test.dart.tmpl +54 -0
  116. package/skills/flutter-feature-scaffold/assets/templates/mvvm/result.dart.tmpl +33 -0
  117. package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase.dart.tmpl +15 -0
  118. package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase_test.dart.tmpl +22 -0
  119. package/skills/flutter-feature-scaffold/assets/templates/mvvm/view.dart.tmpl +47 -0
  120. package/skills/flutter-feature-scaffold/assets/templates/mvvm/view_test.dart.tmpl +27 -0
  121. package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel.dart.tmpl +32 -0
  122. package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel_test.dart.tmpl +64 -0
  123. package/skills/flutter-feature-scaffold/assets/templates/provider/notifier.dart.tmpl +41 -0
  124. package/skills/flutter-feature-scaffold/assets/templates/provider/notifier_test.dart.tmpl +44 -0
  125. package/skills/flutter-feature-scaffold/assets/templates/provider/state.dart.tmpl +31 -0
  126. package/skills/flutter-feature-scaffold/assets/templates/provider/view.dart.tmpl +39 -0
  127. package/skills/flutter-feature-scaffold/assets/templates/provider/view_test.dart.tmpl +30 -0
  128. package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier.dart.tmpl +23 -0
  129. package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier_test.dart.tmpl +55 -0
  130. package/skills/flutter-feature-scaffold/assets/templates/riverpod/providers.dart.tmpl +24 -0
  131. package/skills/flutter-feature-scaffold/assets/templates/riverpod/view.dart.tmpl +45 -0
  132. package/skills/flutter-feature-scaffold/assets/templates/riverpod/view_test.dart.tmpl +31 -0
  133. package/skills/flutter-feature-scaffold/assets/templates/shared/list.dart.tmpl +21 -0
  134. package/skills/flutter-feature-scaffold/assets/templates/shared/model.dart.tmpl +27 -0
  135. package/skills/flutter-feature-scaffold/assets/templates/shared/repository.dart.tmpl +6 -0
  136. package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl.dart.tmpl +25 -0
  137. package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl_test.dart.tmpl +59 -0
  138. package/skills/flutter-feature-scaffold/assets/templates/shared/source.dart.tmpl +28 -0
  139. package/skills/flutter-feature-scaffold/references/profiles.md +145 -0
  140. package/skills/flutter-feature-scaffold/scripts/scaffold.py +1069 -0
  141. package/skills/flutter-firebase/SKILL.md +256 -0
  142. package/skills/flutter-firebase/references/firestore-data.md +178 -0
  143. package/skills/flutter-firebase/references/placement-by-architecture.md +309 -0
  144. package/skills/flutter-firebase/references/review.md +109 -0
  145. package/skills/flutter-firebase/references/rules.md +636 -0
  146. package/skills/flutter-firebase/references/security-rules-and-app-check.md +226 -0
  147. package/skills/flutter-firebase/references/setup-messaging-config.md +169 -0
  148. package/skills/flutter-firebase/references/testing-firebase.md +157 -0
  149. package/skills/flutter-firebase/scripts/check_firebase.py +2155 -0
  150. package/skills/flutter-forms/SKILL.md +191 -0
  151. package/skills/flutter-forms/references/multi-step-and-dirty-state.md +190 -0
  152. package/skills/flutter-forms/references/placement-by-architecture.md +326 -0
  153. package/skills/flutter-forms/references/review.md +88 -0
  154. package/skills/flutter-forms/references/rules.md +238 -0
  155. package/skills/flutter-forms/references/secure-inputs.md +256 -0
  156. package/skills/flutter-forms/references/validation-patterns.md +285 -0
  157. package/skills/flutter-forms/scripts/check_forms.py +1278 -0
  158. package/skills/flutter-i18n/SKILL.md +241 -0
  159. package/skills/flutter-i18n/references/formatting.md +174 -0
  160. package/skills/flutter-i18n/references/gen-l10n-and-arb.md +315 -0
  161. package/skills/flutter-i18n/references/placement-by-architecture.md +460 -0
  162. package/skills/flutter-i18n/references/review.md +93 -0
  163. package/skills/flutter-i18n/references/rtl-and-arabic.md +367 -0
  164. package/skills/flutter-i18n/scripts/check_i18n.py +1805 -0
  165. package/skills/flutter-navigation/SKILL.md +199 -0
  166. package/skills/flutter-navigation/references/deep-links-and-security.md +242 -0
  167. package/skills/flutter-navigation/references/go-router-patterns.md +361 -0
  168. package/skills/flutter-navigation/references/placement-by-architecture.md +414 -0
  169. package/skills/flutter-navigation/references/review.md +102 -0
  170. package/skills/flutter-navigation/references/rules.md +256 -0
  171. package/skills/flutter-navigation/scripts/check_navigation.py +1424 -0
  172. package/skills/flutter-networking/SKILL.md +202 -0
  173. package/skills/flutter-networking/references/client-setup.md +180 -0
  174. package/skills/flutter-networking/references/dtos-and-json.md +114 -0
  175. package/skills/flutter-networking/references/placement-by-architecture.md +147 -0
  176. package/skills/flutter-networking/references/requests.md +160 -0
  177. package/skills/flutter-networking/references/review.md +94 -0
  178. package/skills/flutter-networking/references/rules.md +487 -0
  179. package/skills/flutter-networking/references/testing-with-fakes.md +137 -0
  180. package/skills/flutter-networking/scripts/check_networking.py +1607 -0
  181. package/skills/flutter-performance/SKILL.md +219 -0
  182. package/skills/flutter-performance/references/diagnosing-jank.md +134 -0
  183. package/skills/flutter-performance/references/isolates.md +105 -0
  184. package/skills/flutter-performance/references/lists-images-painting.md +116 -0
  185. package/skills/flutter-performance/references/rebuild-scope.md +154 -0
  186. package/skills/flutter-performance/references/review.md +93 -0
  187. package/skills/flutter-performance/references/rules.md +400 -0
  188. package/skills/flutter-performance/scripts/check_performance.py +1360 -0
  189. package/skills/flutter-persistence/SKILL.md +198 -0
  190. package/skills/flutter-persistence/references/caching-and-offline.md +169 -0
  191. package/skills/flutter-persistence/references/choosing-storage.md +188 -0
  192. package/skills/flutter-persistence/references/migrations.md +201 -0
  193. package/skills/flutter-persistence/references/placement-by-architecture.md +232 -0
  194. package/skills/flutter-persistence/references/review.md +93 -0
  195. package/skills/flutter-persistence/references/rules.md +405 -0
  196. package/skills/flutter-persistence/scripts/check_persistence.py +1690 -0
  197. package/skills/flutter-platform-integration/SKILL.md +219 -0
  198. package/skills/flutter-platform-integration/references/channels-and-pigeon.md +194 -0
  199. package/skills/flutter-platform-integration/references/ffi.md +147 -0
  200. package/skills/flutter-platform-integration/references/permissions-and-isolates.md +124 -0
  201. package/skills/flutter-platform-integration/references/placement-by-architecture.md +102 -0
  202. package/skills/flutter-platform-integration/references/plugins-and-platform-views.md +129 -0
  203. package/skills/flutter-platform-integration/references/review.md +94 -0
  204. package/skills/flutter-platform-integration/references/rules.md +557 -0
  205. package/skills/flutter-platform-integration/references/testing-platform-code.md +125 -0
  206. package/skills/flutter-platform-integration/scripts/check_platform.py +1824 -0
  207. package/skills/flutter-release/SKILL.md +219 -0
  208. package/skills/flutter-release/references/ci-cd.md +156 -0
  209. package/skills/flutter-release/references/flavors-and-environments.md +127 -0
  210. package/skills/flutter-release/references/release-checklist.md +79 -0
  211. package/skills/flutter-release/references/review.md +91 -0
  212. package/skills/flutter-release/references/rules.md +417 -0
  213. package/skills/flutter-release/references/signing-and-versioning.md +113 -0
  214. package/skills/flutter-release/references/store-requirements.md +61 -0
  215. package/skills/flutter-release/scripts/check_release.py +1930 -0
  216. package/skills/flutter-secure-defaults/SKILL.md +270 -0
  217. package/skills/flutter-secure-defaults/references/network-and-auth.md +203 -0
  218. package/skills/flutter-secure-defaults/references/review.md +103 -0
  219. package/skills/flutter-secure-defaults/references/rules.md +452 -0
  220. package/skills/flutter-secure-defaults/references/secrets-and-config.md +136 -0
  221. package/skills/flutter-secure-defaults/references/secure-defaults-by-layer.md +474 -0
  222. package/skills/flutter-secure-defaults/references/secure-scaffold-checklist.md +147 -0
  223. package/skills/flutter-secure-defaults/references/storage-and-privacy.md +161 -0
  224. package/skills/flutter-secure-defaults/references/webview-and-links.md +153 -0
  225. package/skills/flutter-secure-defaults/scripts/check_secure_defaults.py +1571 -0
  226. package/skills/flutter-testing/SKILL.md +197 -0
  227. package/skills/flutter-testing/references/review.md +71 -0
  228. package/skills/flutter-testing/references/strategy-by-architecture.md +491 -0
  229. package/skills/flutter-testing/references/test-smells.md +475 -0
  230. package/skills/flutter-testing/references/widget-and-golden.md +337 -0
  231. package/skills/flutter-testing/scripts/test_gaps.py +1268 -0
  232. package/skills/flutter-ui-practices/SKILL.md +158 -0
  233. package/skills/flutter-ui-practices/references/flutter-ui.md +282 -0
  234. package/skills/flutter-ui-practices/references/review.md +89 -0
@@ -0,0 +1,338 @@
1
+ # Tokens and theming
2
+
3
+ ## Contents
4
+
5
+ 1. The token layers
6
+ 2. Colour: ColorScheme first
7
+ 3. Typography: TextTheme
8
+ 4. Spacing, radius, elevation and motion scales
9
+ 5. Material 3 ThemeData and component themes
10
+ 6. ThemeExtension done right
11
+ 7. Dark mode, high contrast and ThemeMode
12
+ 8. Cupertino and adaptive apps
13
+ 9. Fonts: bundle them, don't fetch them
14
+ 10. Remote or user-supplied themes
15
+
16
+ The official guidance for theming lives at docs.flutter.dev (Cookbook ›
17
+ Design › Use themes to share colors and font styles) and in the Material 3
18
+ `ThemeData` API docs. If `flutter/agent-plugins` is installed, follow its
19
+ step-by-step theming recipe for the mechanics; this file adds the token
20
+ structure, the checker's expectations and the architecture rules.
21
+
22
+ ## 1. The token layers
23
+
24
+ A design system that survives a rebrand has three layers. Each one only reads
25
+ from the layer above it.
26
+
27
+ | Layer | What it holds | Where it lives |
28
+ |---|---|---|
29
+ | Reference tokens | raw values: the brand palette, the type ramp, the 4-pt spacing steps | `lib/core/design_system/tokens/` (or a `design_system` package) as `abstract final class` constants |
30
+ | System tokens | roles: `ColorScheme.primary`, `textTheme.titleMedium`, `AppSpacing.md`, `AppColors.success` | `ThemeData` + `ThemeExtension`s, built once in `lib/core/design_system/theme/` |
31
+ | Component tokens | per-component decisions: a card's padding, a chip's radius | component themes (`CardThemeData`, `FilledButtonThemeData`) or the component widget itself |
32
+
33
+ Feature code reads **system tokens** only: `Theme.of(context).colorScheme.x`,
34
+ `Theme.of(context).textTheme.y`, `context.appColors.z`, `AppSpacing.md`. It
35
+ never reads a reference token such as `Palette.blue600`, because then a dark
36
+ theme or a rebrand has to touch every screen.
37
+
38
+ ## 2. Colour: ColorScheme first
39
+
40
+ PREFER `ColorScheme.fromSeed` when the brand gives you one key colour. It
41
+ generates every Material 3 role (tonal palettes, containers, `on*` colours)
42
+ with contrast built in, for both brightnesses.
43
+
44
+ ```dart
45
+ abstract final class AppTheme {
46
+ static const _seed = Color(0xFF3355FF);
47
+
48
+ static ThemeData light() => _build(ColorScheme.fromSeed(seedColor: _seed));
49
+ static ThemeData dark() =>
50
+ _build(ColorScheme.fromSeed(seedColor: _seed, brightness: Brightness.dark));
51
+
52
+ static ThemeData _build(ColorScheme scheme) => ThemeData(
53
+ colorScheme: scheme,
54
+ textTheme: AppTypography.textTheme,
55
+ extensions: [scheme.brightness == Brightness.dark ? AppColors.dark : AppColors.light],
56
+ );
57
+ }
58
+ ```
59
+
60
+ Use an explicit `ColorScheme(...)` (or `fromSeed(...).copyWith(primary: ...)`)
61
+ when the brand fixes exact values. Fill **every** role you rely on, in both
62
+ schemes. A missing `onPrimary` falls back to a generated colour that may not
63
+ meet contrast.
64
+
65
+ Colours that Material has no role for (success, warning, chart series, brand
66
+ gradients) go into a `ThemeExtension` (§6). They don't go into widget code,
67
+ and they don't go into a global `const` that ignores brightness.
68
+
69
+ DO map semantic states to roles in the view:
70
+
71
+ ```dart
72
+ Color severityColor(BuildContext context, Severity s) => switch (s) {
73
+ Severity.info => Theme.of(context).colorScheme.primary,
74
+ Severity.warning => context.appColors.warning,
75
+ Severity.error => Theme.of(context).colorScheme.error,
76
+ };
77
+ ```
78
+
79
+ AVOID `Colors.red` for an error. It ignores dark mode (`colorScheme.error` is
80
+ lighter on dark surfaces) and high contrast. `Colors.transparent` is fine.
81
+ `Colors.black`/`white` are fine for shadows, scrims and text over photos,
82
+ which is why the checker grades them info.
83
+
84
+ ## 3. Typography: TextTheme
85
+
86
+ Define the type ramp once, as a `TextTheme`, and read it with
87
+ `Theme.of(context).textTheme.bodyMedium`. Change colour or weight with
88
+ `copyWith`. Leave the size alone, because the size is the scale.
89
+
90
+ ```dart
91
+ abstract final class AppTypography {
92
+ static const textTheme = TextTheme(
93
+ headlineSmall: TextStyle(fontSize: 24, height: 32 / 24, fontWeight: FontWeight.w600),
94
+ titleMedium: TextStyle(fontSize: 16, height: 24 / 16, fontWeight: FontWeight.w600),
95
+ bodyMedium: TextStyle(fontSize: 14, height: 20 / 14),
96
+ labelSmall: TextStyle(fontSize: 11, height: 16 / 11, letterSpacing: 0.5),
97
+ );
98
+ }
99
+ ```
100
+
101
+ Don't set `color` inside `TextTheme` styles. `ThemeData` applies `onSurface`
102
+ for you, so a hard-coded colour breaks dark mode. Text-scale behaviour
103
+ (`MediaQuery.textScalerOf`, clamping, layouts that survive 200 %) belongs to
104
+ `flutter-accessibility`.
105
+
106
+ ## 4. Spacing, radius, elevation and motion scales
107
+
108
+ Use plain constants when the values don't change with the theme. They're
109
+ const, so `const EdgeInsets.all(AppSpacing.md)` still works:
110
+
111
+ ```dart
112
+ abstract final class AppSpacing {
113
+ static const double xxs = 2;
114
+ static const double xs = 4;
115
+ static const double sm = 8;
116
+ static const double md = 16;
117
+ static const double lg = 24;
118
+ static const double xl = 32;
119
+ }
120
+
121
+ abstract final class AppRadius {
122
+ static const double sm = 4;
123
+ static const double md = 8;
124
+ static const double lg = 16;
125
+ static const BorderRadius card = BorderRadius.all(Radius.circular(md));
126
+ }
127
+
128
+ abstract final class AppMotion {
129
+ static const Duration short = Duration(milliseconds: 150);
130
+ static const Duration medium = Duration(milliseconds: 300);
131
+ static const Curve standard = Curves.easeInOutCubicEmphasized;
132
+ }
133
+ ```
134
+
135
+ PREFER a `ThemeExtension` instead only when the values do vary: by density,
136
+ by form factor, or between brands of a white-label app. You give up `const`,
137
+ but you gain `lerp` and per-theme values.
138
+
139
+ `abstract final class` (Dart 3) can't be instantiated, extended or
140
+ implemented. It's the idiomatic namespace for constants. A private
141
+ constructor in a plain class also works on older SDKs.
142
+
143
+ The checker (DS-003, DS-004) only reports magic numbers when your project
144
+ **has** such a scale: a class with at least three small numeric steps, named
145
+ like spacing, gap, insets or radius, or a ThemeExtension with three or more
146
+ `double` fields. Without a scale, literal padding is a judgement call, not a
147
+ finding. Pill shapes (`BorderRadius.circular(999)`) and hairlines (≤ 2) are
148
+ never reported. Prefer `StadiumBorder()` for the pill.
149
+
150
+ ## 5. Material 3 ThemeData and component themes
151
+
152
+ Material 3 is the default since Flutter 3.16. Style components once, in the
153
+ theme, so every `FilledButton` and `TextField` looks the same without
154
+ per-call styling:
155
+
156
+ ```dart
157
+ ThemeData(
158
+ colorScheme: scheme,
159
+ textTheme: AppTypography.textTheme,
160
+ filledButtonTheme: FilledButtonThemeData(
161
+ style: FilledButton.styleFrom(
162
+ minimumSize: const Size.fromHeight(48),
163
+ shape: const RoundedRectangleBorder(borderRadius: AppRadius.card),
164
+ ),
165
+ ),
166
+ inputDecorationTheme: const InputDecorationTheme(
167
+ border: OutlineInputBorder(borderRadius: AppRadius.card),
168
+ contentPadding: EdgeInsets.symmetric(horizontal: AppSpacing.md, vertical: AppSpacing.sm),
169
+ ),
170
+ cardTheme: const CardThemeData(margin: EdgeInsets.zero, elevation: 0),
171
+ );
172
+ ```
173
+
174
+ - DO build `ThemeData` once (a `static final` or a function called from the
175
+ app widget), not inside a feature widget's `build()`.
176
+ - DO derive local variations from the current theme:
177
+ `Theme(data: Theme.of(context).copyWith(...))`. A fresh `ThemeData(...)` in
178
+ a subtree throws away the scheme, the text theme and every extension below
179
+ it (DS-010).
180
+ - AVOID `primarySwatch` and the other Material 2 parameters in new code. They
181
+ are deprecated or ignored under Material 3.
182
+
183
+ ## 6. ThemeExtension done right
184
+
185
+ ```dart
186
+ @immutable
187
+ class AppColors extends ThemeExtension<AppColors> {
188
+ const AppColors({required this.success, required this.warning, required this.chart});
189
+
190
+ final Color success;
191
+ final Color warning;
192
+ final List<Color> chart;
193
+
194
+ static const light = AppColors(
195
+ success: Color(0xFF2E7D32), warning: Color(0xFFB26A00),
196
+ chart: [Color(0xFF3355FF), Color(0xFF00897B)],
197
+ );
198
+ static const dark = AppColors(
199
+ success: Color(0xFF81C784), warning: Color(0xFFFFCA28),
200
+ chart: [Color(0xFF9FB0FF), Color(0xFF4DB6AC)],
201
+ );
202
+
203
+ @override
204
+ AppColors copyWith({Color? success, Color? warning, List<Color>? chart}) => AppColors(
205
+ success: success ?? this.success,
206
+ warning: warning ?? this.warning,
207
+ chart: chart ?? this.chart,
208
+ );
209
+
210
+ @override
211
+ AppColors lerp(ThemeExtension<AppColors>? other, double t) {
212
+ if (other is! AppColors) return this;
213
+ return AppColors(
214
+ success: Color.lerp(success, other.success, t)!,
215
+ warning: Color.lerp(warning, other.warning, t)!,
216
+ chart: [for (var i = 0; i < chart.length; i++) Color.lerp(chart[i], other.chart[i], t)!],
217
+ );
218
+ }
219
+ }
220
+
221
+ extension AppColorsContext on BuildContext {
222
+ /// Fails loudly in debug if a ThemeData forgot to register AppColors.
223
+ AppColors get appColors {
224
+ final colors = Theme.of(this).extension<AppColors>();
225
+ assert(colors != null, 'AppColors is missing from ThemeData.extensions');
226
+ return colors ?? AppColors.light;
227
+ }
228
+ }
229
+ ```
230
+
231
+ The rules, and the checker IDs that enforce them:
232
+
233
+ - **Register it in every theme** the app passes (`theme`, `darkTheme`,
234
+ `highContrastTheme`, `highContrastDarkTheme`). `extension<T>()` returns
235
+ `null` in a theme without it, and `!` turns that into a crash the first time
236
+ someone opens the app in dark mode (DS-005).
237
+ - **Immutable.** Every field is `final` and the constructor is `const`.
238
+ Theme data is shared and compared by value, so mutating a field changes
239
+ every widget that read it, without a rebuild (DS-007).
240
+ - **`lerp` interpolates every field.** `MaterialApp` animates theme changes
241
+ through `ThemeData.lerp`, which calls your `lerp`. Returning `this` makes
242
+ the colours jump at the end of the animation (DS-006). Use `Color.lerp`,
243
+ `lerpDouble`, `TextStyle.lerp`, `EdgeInsets.lerp` and `BorderRadius.lerp`.
244
+ - **`copyWith` covers every field**, so `Theme.of(context).copyWith(extensions: ...)`
245
+ can override one value.
246
+ - **One getter** (`context.appColors`) so feature code doesn't repeat
247
+ `Theme.of(context).extension<AppColors>()!`. The getter is the single place
248
+ that decides how a missing registration fails.
249
+
250
+ Code generation (`theme_tailor`) is fine. The checker skips `*.tailor.dart`.
251
+
252
+ ## 7. Dark mode, high contrast and ThemeMode
253
+
254
+ ```dart
255
+ MaterialApp.router(
256
+ theme: AppTheme.light(),
257
+ darkTheme: AppTheme.dark(),
258
+ highContrastTheme: AppTheme.lightHighContrast(),
259
+ highContrastDarkTheme: AppTheme.darkHighContrast(),
260
+ themeMode: themeMode, // from settings; see components-and-placement.md §3
261
+ routerConfig: router,
262
+ );
263
+ ```
264
+
265
+ - `themeMode` does nothing without `darkTheme`. Flutter falls back to `theme`
266
+ for both, so a "Dark" setting silently shows the light theme (DS-008).
267
+ - PREFER `ThemeMode.system` as the default, and store the user's override as
268
+ a setting (the persistence layer stores an enum name, not a `ThemeMode`
269
+ index that might change).
270
+ - DON'T branch on brightness in widgets
271
+ (`Theme.of(context).brightness == Brightness.dark ? a : b`). Put both
272
+ values in the theme as a ColorScheme role or an extension field, and read
273
+ one name (DS-009). `MediaQuery.platformBrightnessOf` in a widget is worse:
274
+ it ignores the user's in-app choice. Only the app root, which resolves
275
+ `ThemeMode.system`, may read it.
276
+ - High contrast: build the high-contrast themes with
277
+ `ColorScheme.fromSeed(..., contrastLevel: 1.0)` (Flutter 3.22+) or explicit
278
+ roles. Contrast ratios themselves are checked by `flutter-accessibility`.
279
+
280
+ ## 8. Cupertino and adaptive apps
281
+
282
+ - A `MaterialApp` already adapts some widgets per platform (`Switch.adaptive`,
283
+ scrolling physics, page transitions). For iOS-flavoured Material, set
284
+ `cupertinoOverrideTheme: CupertinoThemeData(...)` on `ThemeData`, so the
285
+ Cupertino widgets inside a Material app pick up your primary colour.
286
+ - A `CupertinoApp` has no `darkTheme`. A `CupertinoThemeData` without
287
+ `brightness` follows the platform, and `CupertinoColors.systemBackground`,
288
+ `label` and the other dynamic colours resolve per brightness by themselves.
289
+ The checker treats `CupertinoColors.*` as semantic, not raw.
290
+ - Adaptive components (`AppSwitch` that renders `CupertinoSwitch` on iOS)
291
+ belong in the design-system layer. Feature code shouldn't check
292
+ `Platform.isIOS` to pick a widget.
293
+
294
+ ## 9. Fonts: bundle them, don't fetch them
295
+
296
+ By default `google_fonts` downloads font files from `fonts.gstatic.com` at
297
+ runtime and caches them. In release builds that means:
298
+ - a request to a third-party server on first launch, which sends the user's
299
+ IP address to Google (a German court has ruled that remotely loaded Google
300
+ Fonts on a website breached the GDPR);
301
+ - the wrong font when the device is offline or the request is blocked;
302
+ - layout shift when the font arrives.
303
+
304
+ DO bundle the `.ttf` files and turn fetching off (DS-012):
305
+
306
+ ```yaml
307
+ flutter:
308
+ assets:
309
+ - google_fonts/ # the downloaded OFL font files
310
+ ```
311
+
312
+ ```dart
313
+ void main() {
314
+ GoogleFonts.config.allowRuntimeFetching = false;
315
+ runApp(const App());
316
+ }
317
+ ```
318
+
319
+ Or skip the package: declare the family under `flutter: fonts:` and use
320
+ `fontFamily: 'Inter'` in the `TextTheme`. Keep the font licence (usually OFL)
321
+ with the assets.
322
+
323
+ ## 10. Remote or user-supplied themes
324
+
325
+ White-label apps and "custom theme" features load colours from a server or
326
+ from user input. Treat that as untrusted input at the data boundary:
327
+
328
+ - Parse into a typed value object (`BrandTheme.fromJson`) in the data layer,
329
+ and validate every field: hex format, a known font family from an
330
+ allow-list, sizes within the scale. On any error, fall back to the bundled
331
+ theme. Never `jsonDecode` theme maps inside widgets.
332
+ - Check contrast of server-supplied colour pairs before you apply them (load
333
+ `flutter-accessibility` for the ratio check). A bad payload shouldn't make
334
+ the login screen unreadable.
335
+ - Never load fonts, images or shaders from URLs inside the theme payload
336
+ unless the host is on an allow-list (see `flutter-secure-defaults` for
337
+ HTTPS and allow-listing).
338
+ - Cache the last good theme. Don't block startup on the network.