randalschwartz 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 material_ui and cupertino_ui 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 |
MaterialState / MaterialStateProperty |
Deprecated in Flutter 3.22 | WidgetState / WidgetStateProperty |
Widget Deprecations |
WillPopScope |
Deprecated in Flutter 3.12+ | PopScope(canPop: ..., onPopInvokedWithResult: ...) |
Widget Deprecations |
FlatButton, RaisedButton, OutlineButton |
Deprecated in Flutter 2.0 | TextButton, ElevatedButton, OutlinedButton |
Widget Deprecations |
TextTheme.headline1...6, bodyText1/2 |
Deprecated in Flutter 3.7+ | displayLarge...small, bodyLarge/Medium |
Widget Deprecations |
ThemeData.accentColor |
Deprecated in Flutter 2.5+ | ColorScheme.secondary |
Widget Deprecations |
Scaffold.of(context).showSnackBar() |
Deprecated in Flutter 2.0 | ScaffoldMessenger.of(context).showSnackBar() |
Widget Deprecations |
package:flutter/material.dart |
Monolithic Flutter SDK | package:material_ui/material_ui.dart |
Material & Cupertino Migration |
package:flutter/cupertino.dart |
Monolithic Flutter SDK | package:cupertino_ui/cupertino_ui.dart |
Material & Cupertino Migration |
BottomNavigationBar |
Legacy M2 Navigation | NavigationBar (Material 3) |
Material 3 Guide |
ToggleButtons |
Legacy M2 Toggle | SegmentedButton<T> (Material 3) |
Material 3 Guide |
PopupMenuButton |
Legacy popup menu | MenuAnchor / SubmenuButton |
Material 3 Guide |
⚡ Subskill Spotlights
Subskill: Standalone material_ui & cupertino_ui 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=migrate_design_widgetsto 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.
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.
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.
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.
📚 Table of Contents & Reference Archive
| Document | Focus Area | Description |
|---|---|---|
material-ui-and-cupertino-ui-migration.md |
Package Decoupling | Complete runbook for migrating from SDK-bundled material/cupertino to standalone material_ui and cupertino_ui. |
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 |
Widget Dictionary | Before/After code snippets for all deprecated Flutter widgets and properties. |
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 |
Upgrade Runbook | 5-phase structured runbook for stepping legacy Flutter apps to modern Flutter. |
🛠️ Recommended Runbooks
1. Migrating to Standalone material_ui & cupertino_ui
- Execute
dart fix --apply --code=migrate_design_widgetsto rewrite imports. - Confirm
pubspec.yamldependencies includematerial_uiandcupertino_ui. - Consult the Material & Cupertino UI Migration Guide 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.
- 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.
- 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:
- 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.
- State the bundled Dart SDK version, major framework milestones, and engine updates.