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,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.
|