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_widgets to 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 WillPopScope with PopScope for zero-stutter predictive back gestures on Android 14+ and iOS.
• Wide-Gamut Colors: Replace withOpacity with withValues(alpha: ...) to eliminate 8-bit precision loss and color clipping.
• Unified State Management: Replace MaterialState with universal WidgetState. 👉 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 BottomNavigationBar to NavigationBar, ToggleButtons to SegmentedButton, and M2 buttons to FilledButton. 👉 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

1. Execute dart fix --apply --code=migrate_design_widgets to rewrite imports.
2. Confirm pubspec.yaml dependencies include material_ui and cupertino_ui.
3. Consult the Material & Cupertino UI Migration Guide for localization updates and headless architectures.

2. Migrating Deprecated Widgets & Properties

1. Identify the deprecated widget or property (for example WillPopScope, Color.withOpacity, MaterialStateProperty).
2. Consult the Widget Deprecations Guide.
3. Replace with the modern declarative equivalent (for example PopScope, Color.withValues(alpha: ...), WidgetStateProperty).

3. Migrating to Material 3

1. Review the Material 2 to Material 3 Guide.
2. Configure ThemeData using ColorScheme.fromSeed(seedColor: ...).
3. Replace legacy navigation bars (BottomNavigationBar → NavigationBar) and controls (ToggleButtons → SegmentedButton).

4. Upgrading / Rescuing Legacy Flutter Apps

1. Determine current Flutter and Dart versions from pubspec.yaml environment block.
2. 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"

1. Match the Flutter version in the Flutter to Dart Version Matrix.
2. State the bundled Dart SDK version, major framework milestones, and engine updates.