[material_ui, cupertino_ui] READMEs

packages/cupertino_ui/README.md

@@ -1,24 +1,138 @@
-# cupertino\_ui
+# cupertino_ui
 
-**Coming soon \- the official Cupertino widget library for Flutter as its own standalone package\!**
+The official Flutter Cupertino library, implementing Apple's [Human Interface
+Guidelines](https://developer.apple.com/design/human-interface-guidelines/) for
+Flutter applications.
 
-`cupertino_ui` will contain the standard collection of high-fidelity visual components that implement the latest iOS design language (buttons, navigation bars, pickers, etc.).
+`cupertino_ui` provides a complete, high-fidelity suite of visual components,
+motion, typography, color system, and theming tools to build authentic
+iOS- and macOS-style user interfaces on all screen sizes.
 
-**Note:** This package will contain the cupertino library previously part of the Flutter framework itself (`package:flutter/cupertino.dart`). It is being decoupled to allow for faster iteration and a more modular ecosystem.
+See also the
+[`material_ui`](https://github.com/flutter/packages/tree/main/packages/material_ui)
+package, which is Flutter's official Material Design library.
 
-## What's (going to be) inside?
+## New to the package?
 
-This package will provide the Cupertino widgets you know and love, including but not limited to:
+Install the package with the following command:
 
-* **Structure:** `CupertinoPageScaffold`, `CupertinoNavigationBar`  
-* **Inputs:** `CupertinoButton`, `CupertinoTextField`, `CupertinoSwitch`  
-* **Dialogs:** `CupertinoAlertDialog`, `CupertinoActionSheet`
+```dart
+flutter add cupertino_ui
+```
 
-Once landed and published, look forward to updates from [iOS26](https://github.com/flutter/flutter/issues/170310)\! 🚀
+See Flutter's main [getting started
+guide](https://flutter.dev/getting-started/) for information about using Flutter
+and `cupertino_ui`.
 
-## Feedback & roadmap
+## Migrating existing code to this package
 
-We are currently migrating the Cupertino library out of the core framework.
+The standalone `cupertino_ui` package was previously built directly into the
+core Flutter framework as `package:flutter/cupertino.dart`. It has been
+decoupled from the [flutter/flutter](https://github.com/flutter/flutter)
+repository into its new home here in `flutter/packages`.
 
-* **Follow the progress:** [Decoupling Github Project](https://github.com/orgs/flutter/projects/220)  
-* **Report bugs:** [Cupertino issues in Flutter](https://github.com/flutter/flutter/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22f%3A%20cupertino%22)
+Follow the steps below to migrate:
+
+### Step 1: Migrate imports
+
+We've included a data driven Dart fix to help users migrate. Simply run the
+following command:
+
+```sh
+dart fix --apply --code=migrate_design_widgets
+```
+
+This performs the equivalent of adding `cupertino_ui` to your project and
+changing imports of `package:flutter/cupertino.dart` to
+`package:cupertino_ui/cupertino_ui.dart`.
+
+### Step 2: Migrate localizations (if needed)
+
+Don't use the `GlobalMaterialLocalizations` or `GlobalCupertinoLocalizations`
+classes from flutter/flutter's `flutter_localizations` package. Instead, use the
+new versions of these classes from `material_ui` and `cupertino_ui`,
+respectively.
+
+### Step 3: Bridge legacy dependencies (if needed)
+
+If your app uses third-party packages or subtrees that still import and rely on
+`package:flutter/cupertino.dart`, use `CupertinoUiCompatibilityBridge` to bridge
+`CupertinoThemeData` and `CupertinoLocalizations` so legacy widgets resolve
+correctly within modern widget trees.
+
+Wrap your app using `CupertinoApp.builder`:
+
+```dart
+import 'package:cupertino_ui/cupertino_ui.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return CupertinoApp(
+      builder: (BuildContext context, Widget? child) {
+        return CupertinoUiCompatibilityBridge(child: child!);
+      },
+      home: const HomeScreen(),
+    );
+  }
+}
+```
+
+You can also wrap individual subtrees that contain legacy package widgets:
+
+```dart
+CupertinoPageScaffold(
+  navigationBar: const CupertinoNavigationBar(
+    middle: Text('Modern Screen'),
+  ),
+  child: CupertinoUiCompatibilityBridge(
+    child: LegacyPackageWidget(),
+  ),
+)
+```
+
+---
+
+## Features
+
+The `cupertino_ui` package contains everything you need to create a
+fully-featured iOS app, such as:
+
+* **App Structure & Navigation**: `CupertinoApp`, `CupertinoPageScaffold`,
+`CupertinoTabScaffold`, `CupertinoTabView`, `CupertinoNavigationBar`,
+`CupertinoSliverNavigationBar`, `CupertinoTabBar`, `CupertinoPageRoute`
+* **Buttons & Controls**: `CupertinoButton`, `CupertinoSegmentedControl`,
+`CupertinoSlidingSegmentedControl`, `CupertinoContextMenu`,
+`CupertinoContextMenuAction`, `CupertinoScrollbar`
+* **Inputs & Selection**: `CupertinoTextField`, `CupertinoTextFormFieldRow`,
+`CupertinoFormSection`, `CupertinoFormRow`, `CupertinoSwitch`,
+`CupertinoSlider`, `CupertinoCheckbox`, `CupertinoRadio`,
+`CupertinoSearchTextField`
+* **Pickers & Dialogs**: `CupertinoPicker`, `CupertinoDatePicker`,
+`CupertinoTimerPicker`, `CupertinoAlertDialog`, `CupertinoActionSheet`,
+`CupertinoActionSheetAction`, `CupertinoPopupSurface`
+* **Display & Feedback**: `CupertinoListSection`, `CupertinoListTile`,
+`CupertinoActivityIndicator`, `CupertinoIcons`, `CupertinoFocusHalo`
+* **Theming & Typography**: `CupertinoTheme`, `CupertinoThemeData`,
+`CupertinoTextThemeData`, `CupertinoColors`, `CupertinoDynamicColor`
+* **Internationalization**: `CupertinoLocalizations` and
+`GlobalCupertinoLocalizations` for multi-locale support
+
+## Changelog
+
+See the
+[Changelog](https://github.com/flutter/packages/blob/main/packages/cupertino_ui/CHANGELOG.md)
+for a list of new features and breaking changes.
+
+## Documentation & Resources
+
+* [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
+* [Flutter Cupertino Widget Catalog](https://docs.flutter.dev/ui/widgets/cupertino)
+* [API Reference](https://pub.dev/documentation/cupertino_ui/latest/)
+* [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22p%3A%20cupertino_ui%22)

packages/cupertino_ui/pending_changelogs/change_2026_08_10_readme.yaml

@@ -0,0 +1,3 @@
+changelog: |
+  - README updated for the full release of cupertino_ui.
+version: patch

packages/material_ui/README.md

@@ -1,25 +1,135 @@
-# material\_ui
+# material_ui
 
-**Coming soon \- the official Material Design widget library for Flutter as its own standalone package\!**
+The official Flutter Material Design library, implementing Google's [Material
+Design](https://m3.material.io/) design system for Flutter applications.
 
-`material_ui` will contain the standard collection of visual components (Buttons, Cards, AppBars, etc.) that implement Google's latest Material Design specification.
+`material_ui` provides a complete, modern suite of visual components, motion,
+typography, color system, and theming tools to build beautiful and accessible
+user interfaces on all screen sizes.
 
-**Note:** This package will contain the material library previously part of the Flutter framework itself (`package:flutter/material.dart`). It is being decoupled to allow for faster iteration and a more modular ecosystem.
+See also the
+[`cupertino_ui`](https://github.com/flutter/packages/tree/main/packages/cupertino_ui)
+package, which is Flutter's official iOS- and macOS-style design library.
 
-## What's (going to be) inside?
+## New to the package?
 
-This package will provide the Material widgets you know and love, including but not limited to:
+Install the package with the following command:
 
-* **Structure:** `Scaffold`, `AppBar`, `Drawer`  
-* **Inputs:** `FloatingActionButton`, `TextField`, `Slider`  
-* **Display:** `Card`, `Chip`, `ListTile`  
-* **Theming:** `ThemeData`, `ColorScheme`
+```dart
+flutter add material_ui
+```
 
-Once landed and published, look forward to updates from [Material 3 Expressive](https://github.com/flutter/flutter/issues/168813)\! 🚀
+See Flutter's main [getting started
+guide](https://flutter.dev/getting-started/) for information about using Flutter
+and `material_ui`.
 
-## Feedback & roadmap
+## Migrating existing code to this package
 
-We are currently migrating the Material library out of the core framework.
+The standalone `material_ui` package was previously built directly into the core
+Flutter framework as `package:flutter/material.dart`. It has been decoupled from
+the [flutter/flutter](https://github.com/flutter/flutter) repository into its
+new home here in `flutter/packages`.
 
-* **Follow the progress:** [Decoupling Github Project](https://github.com/orgs/flutter/projects/220)  
-* **Report bugs:** [Material issues in Flutter](https://github.com/flutter/flutter/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22f%3A%20material%20design%22)
+Follow the steps below to migrate:
+
+### Step 1: Migrate imports
+
+We've included a data driven Dart fix to help users migrate. Simply run the
+following command:
+
+```sh
+dart fix --apply --code=migrate_design_widgets
+```
+
+This performs the equivalent of adding `material_ui` to your project and
+changing imports of `package:flutter/material.dart` to
+`package:material_ui/material_ui.dart`.
+
+### Step 2: Migrate localizations (if needed)
+
+If you are not currently using the `GlobalMaterialLocalizations` or
+`GlobalCupertinoLocalizations` classes from flutter/flutter's
+`flutter_localizations` package, then you are already good to go. For those that
+do need to migrate off of these classes, simply use the new versions of these
+classes from `material_ui` and `cupertino_ui`, respectively.
+
+A typical app can use the following localization delegate from `material_ui` to
+cover all of the localization strings in Flutter, Material, and Cupertino:
+
+```dart
+  localizationDelegates: GlobalMaterialLocalizations.delegates,
+```
+
+### Step 3: Bridge legacy dependencies (if needed)
+
+If your app uses third-party packages or subtrees that still import and rely on
+`package:flutter/material.dart`, use `MaterialUiCompatibilityBridge` to bridge
+`ThemeData` and `MaterialLocalizations` so legacy widgets resolve correctly
+within modern widget trees.
+
+Wrap your app using `MaterialApp.builder`:
+
+```dart
+import 'package:material_ui/material_ui.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      builder: (BuildContext context, Widget? child) {
+        return MaterialUiCompatibilityBridge(child: child!);
+      },
+      home: const HomeScreen(),
+    );
+  }
+}
+```
+
+You can also wrap individual subtrees that contain legacy package widgets:
+
+```dart
+Scaffold(
+  appBar: AppBar(title: const Text('Modern Screen')),
+  body: MaterialUiCompatibilityBridge(
+    child: LegacyPackageWidget(),
+  ),
+)
+```
+
+---
+
+## Features
+
+The `material_ui` packcage contains everything you need to create a
+fully-featured Material app, such as:
+
+* **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`,
+`NavigationBar`, `BottomSheet`, `TabBar`, `SearchAnchor`, `SearchBar`, `Dialog`
+* **Buttons & Interaction**: `ElevatedButton`, `TextButton`, `IconButton`,
+`FloatingActionButton`, `SegmentedButton`, `InkWell`, `MenuBar`
+* **Inputs & Selection**: `TextField`, `Checkbox`, `Radio`, `Switch`, `Slider`,
+`DropdownMenu`, `DatePicker`, `TimePicker`
+* **Display & Feedback**: `Card`, `Chip`, `ListTile`, `Badge`, `Divider`,
+`ProgressIndicator`, `SnackBar`, `Tooltip`, `CarouselView`, `VerticalDivider`
+* **Theming & Color**: `ThemeData`, `ColorScheme`, `TextTheme`, dynamic color
+generation, Material 3 design tokens, typography, and motion easing curves
+* **Internationalization**: `MaterialLocalizations` and
+`GlobalMaterialLocalizations` for multi-locale support
+
+## Changelog
+See the
+[Changelog](https://github.com/flutter/packages/blob/main/packages/material_ui/CHANGELOG.md)
+for a list of new features and breaking changes.
+
+## Documentation & Resources
+
+* [Material Design 3 Specification](https://m3.material.io/)
+* [Flutter Material Widget Catalog](https://docs.flutter.dev/ui/widgets/material)
+* [API Reference](https://pub.dev/documentation/material_ui/latest/)
+* [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22p%3A%20material_ui%22)

packages/material_ui/pending_changelogs/change_2026_08_10_readme.yaml

@@ -0,0 +1,3 @@
+changelog: |
+  - README updated for the full release of material_ui.
+version: patch