SKILL.md
Flutter SDK Changelog & Widget Migration Guide (Flutter 1.0 to Modern Flutter)
This skill provides an authoritative, structured reference for Flutter framework releases, widget deprecations, API replacements, Material 3 design migrations, the decoupling of standalone materialui and cupertinoui packages, and legacy Flutter codebase rescue runbooks.
🎯 Fast Flutter Widget & API Replacement Matrix
| Deprecated / Obsolete API | Introduced / Deprecated In | Modern Replacement | Reference |
|---|---|---|---|
Color.withOpacity(o) |
Deprecated in Flutter 3.22 | Color.withValues(alpha: o) |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
MaterialState / MaterialStateProperty |
Deprecated in Flutter 3.22 | WidgetState / WidgetStateProperty |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
WillPopScope |
Deprecated in Flutter 3.12+ | PopScope(canPop: ..., onPopInvokedWithResult: ...) |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
FlatButton, RaisedButton, OutlineButton |
Deprecated in Flutter 2.0 | TextButton, ElevatedButton, OutlinedButton |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
TextTheme.headline1...6, bodyText1/2 |
Deprecated in Flutter 3.7+ | displayLarge...small, bodyLarge/Medium |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
ThemeData.accentColor |
Deprecated in Flutter 2.5+ | ColorScheme.secondary |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
Scaffold.of(context).showSnackBar() |
Deprecated in Flutter 2.0 | ScaffoldMessenger.of(context).showSnackBar() |
[Widget Deprecations](references/widget-deprecations-and-replacements.md) |
package:flutter/material.dart |
Monolithic Flutter SDK | package:materialui/materialui.dart |
[Material & Cupertino Migration](references/material-ui-and-cupertino-ui-migration.md) |
package:flutter/cupertino.dart |
Monolithic Flutter SDK | package:cupertinoui/cupertinoui.dart |
[Material & Cupertino Migration](references/material-ui-and-cupertino-ui-migration.md) |
BottomNavigationBar |
Legacy M2 Navigation | NavigationBar (Material 3) |
[Material 3 Guide](references/material-2-to-material-3-guide.md) |
ToggleButtons |
Legacy M2 Toggle | SegmentedButton<T> (Material 3) |
[Material 3 Guide](references/material-2-to-material-3-guide.md) |
PopupMenuButton |
Legacy popup menu | MenuAnchor / SubmenuButton |
[Material 3 Guide](references/material-2-to-material-3-guide.md) |
⚡ Subskill Spotlights
Subskill: Standalone materialui & cupertinoui Package Migration
- Decoupled Architecture: Transition from monolithic framework design libraries to standalone pub packages with independent release cadences.
- Automated Fix: Run
dart fix --apply --code=migratedesignwidgetsto update imports and dependencies automatically. - Headless Core Support: Construct purely custom design systems directly against
package:flutter/widgets.dart.
👉 Read the full [Material & Cupertino UI Migration Guide](references/material-ui-and-cupertino-ui-migration.md).
Subskill: Widget Deprecations & Modernization
- Predictive Back Navigation: Replace
WillPopScopewithPopScopefor zero-stutter predictive back gestures on Android 14+ and iOS. - Wide-Gamut Colors: Replace
withOpacitywithwithValues(alpha: ...)to eliminate 8-bit precision loss and color clipping. - Unified State Management: Replace
MaterialStatewith universalWidgetState.
👉 Read the full [Widget Deprecations & Replacements Guide](references/widget-deprecations-and-replacements.md).
Subskill: Material 2 to Material 3 Migration
- Seed-Based Theming: Generate tonal palettes with
ColorScheme.fromSeed(seedColor: ...). - Component Modernization: Migrate from
BottomNavigationBartoNavigationBar,ToggleButtonstoSegmentedButton, and M2 buttons toFilledButton.
👉 Read the full [Material 2 to Material 3 Guide](references/material-2-to-material-3-guide.md).
Subskill: Rescuing Legacy Flutter Apps (Flutter 1.x / 2.x to Modern 3.x)
- 5-Phase Upgrade Pipeline: Baseline toolchain check → null safety bridge → widget deprecation fixes → Material 3 update → modern state & routing.
👉 Read the full [Legacy Flutter App Rescue Runbook](references/rescuing-legacy-flutter-apps.md).
📚 Table of Contents & Reference Archive
| Document | Focus Area | Description |
|---|---|---|
[material-ui-and-cupertino-ui-migration.md](references/material-ui-and-cupertino-ui-migration.md) |
Package Decoupling | Complete runbook for migrating from SDK-bundled material/cupertino to standalone materialui and cupertinoui. |
[flutter-to-dart-version-matrix.md](references/flutter-to-dart-version-matrix.md) |
Version Mapping | Full mapping of Flutter 1.0–3.27+ to bundled Dart SDKs and engine milestones. |
[widget-deprecations-and-replacements.md](references/widget-deprecations-and-replacements.md) |
Widget Dictionary | Before/After code snippets for all deprecated Flutter widgets and properties. |
[material-2-to-material-3-guide.md](references/material-2-to-material-3-guide.md) |
UI & Theming | Comprehensive Material 3 migration guide, dynamic color schemes, and new components. |
[rescuing-legacy-flutter-apps.md](references/rescuing-legacy-flutter-apps.md) |
Upgrade Runbook | 5-phase structured runbook for stepping legacy Flutter apps to modern Flutter. |
🛠️ Recommended Runbooks
1. Migrating to Standalone materialui & cupertinoui
- Execute
dart fix --apply --code=migratedesignwidgetsto rewrite imports. - Confirm
pubspec.yamldependencies includematerialuiandcupertinoui. - Consult the [Material & Cupertino UI Migration Guide](references/material-ui-and-cupertino-ui-migration.md) for localization updates and headless architectures.
2. Migrating Deprecated Widgets & Properties
- Identify the deprecated widget or property (for example
WillPopScope,Color.withOpacity,MaterialStateProperty). - Consult the [Widget Deprecations Guide](references/widget-deprecations-and-replacements.md).
- Replace with the modern declarative equivalent (for example
PopScope,Color.withValues(alpha: ...),WidgetStateProperty).
3. Migrating to Material 3
- Review the [Material 2 to Material 3 Guide](references/material-2-to-material-3-guide.md).
- Configure
ThemeDatausingColorScheme.fromSeed(seedColor: ...). - Replace legacy navigation bars (
BottomNavigationBar→NavigationBar) and controls (ToggleButtons→SegmentedButton).
4. Upgrading / Rescuing Legacy Flutter Apps
- Determine current Flutter and Dart versions from
pubspec.yamlenvironment block. - Follow the 5-phase pipeline in the [Legacy Flutter App Rescue Runbook](references/rescuing-legacy-flutter-apps.md):
- Check toolchain → Sound Null Safety bridge → Widget deprecations → Material 3 theme → Modern routing & reactive state.
5. Answering "What's New in Flutter X.Y"
- Match the Flutter version in the [Flutter to Dart Version Matrix](references/flutter-to-dart-version-matrix.md).
- State the bundled Dart SDK version, major framework milestones, and engine updates.