[material_ui, cupertino_ui] READMEs - #12428
Conversation
|
It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging. If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix? Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group. |
There was a problem hiding this comment.
Code Review
This pull request updates the README files for both cupertino_ui and material_ui to document their full release, including migration guides, features, and resources, along with adding corresponding pending changelog entries. The review feedback suggests updating the issue tracker links in both READMEs to use the correct package-specific labels (p: cupertino_ui and p: material_ui) instead of the broader framework labels.
| * [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+is%3Aopen+label%3A%22p%3A%20cupertino%22) |
There was a problem hiding this comment.
The issue tracker query uses the label p: cupertino, but the package name is cupertino_ui. In the flutter/flutter repository, issues for packages are typically labeled with p: <package_name>.
Please update the label to p: cupertino_ui (or keep f: cupertino if you intend to reference the broader framework Cupertino issues).
| * [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A%20cupertino%22) | |
| * [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A%20cupertino_ui%22) |
There was a problem hiding this comment.
Yeah, I will be updating the labels on Wednesday .. f: cupertino to p: cupertino_ui and the same for material
There was a problem hiding this comment.
I will change these urls to new value so they're ready for tomorrow.
| * [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+is%3Aopen+label%3A%22p%3A%20material%20design%22) |
There was a problem hiding this comment.
The issue tracker query uses the label p: material design, but the package name is material_ui. In the flutter/flutter repository, issues for packages are typically labeled with p: <package_name>.
Please update the label to p: material_ui (or keep f: material design if you intend to reference the broader framework Material issues).
| * [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A%20material%20design%22) | |
| * [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A%20material_ui%22) |
|
|
||
| ## Getting Started | ||
|
|
||
| See Flutter's main [getting started guide](https://flutter.dev/getting-started/) |
There was a problem hiding this comment.
Does this getting started page need to be updated?
There was a problem hiding this comment.
I didn't see anything obviously out of date, but we should probably grep the whole website for "material" and "cupertino" and make sure it all still makes sense. For now guides that tell you to flutter create will give you the old libraries until we update that.
| * [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+is%3Aopen+label%3A%22p%3A%20cupertino%22) |
There was a problem hiding this comment.
Yeah, I will be updating the labels on Wednesday .. f: cupertino to p: cupertino_ui and the same for material
| @@ -0,0 +1,3 @@ | |||
| changelog: | | |||
| - README updated for the full release of cupertino_ui. | |||
| version: patch | |||
There was a problem hiding this comment.
Do we want this to be the major 1.0 change?
There was a problem hiding this comment.
Ideally I wanted to see these READMEs live on Pub before the release to make sure they're good to go. I say let's aim to land this now, but if it ends up delayed until tomorrow, then maybe I'll just change that to promote and close the other PR.
|
|
||
| ## Getting Started | ||
|
|
||
| See Flutter's main [getting started guide](https://flutter.dev/getting-started/) |
| * [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+is%3Aopen+label%3A%22p%3A%20material%20design%22) |
| @@ -0,0 +1,3 @@ | |||
| changelog: | | |||
| - README updated for the full release of material_ui. | |||
| version: patch | |||
| theme: ThemeData( | ||
| colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6750A4)), | ||
| ), |
There was a problem hiding this comment.
Nit: I think no need to add this. By default, MaterialApp will provide a m3 theme data.
| `BottomSheet`, `TabBar`, `SearchAnchor`, `SearchBar` | ||
| * **Buttons & Interaction**: `ElevatedButton`, `FilledButton`, `OutlinedButton`, | ||
| `TextButton`, `IconButton`, `FloatingActionButton`, `SegmentedButton`, | ||
| `ToggleButtons`, `PopupMenuButton`, `InkWell` |
There was a problem hiding this comment.
| `ToggleButtons`, `PopupMenuButton`, `InkWell` | |
| `PopupMenuButton`, `InkWell` |
Maybe don't recommend ToggleButtons because it should be replaced by SegmentedButton
|
|
||
| `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 systems, and theming tools to build beautiful and accessible |
|
|
||
| * **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) | ||
| ### Step 2: Migrate localization |
There was a problem hiding this comment.
| ### Step 2: Migrate localization | |
| ### Step 2: Migrate localizations (if used) |
| 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. |
There was a problem hiding this comment.
Could be clearer, such that if you don't explicitly use these, you don't have anything to do
| `material_ui` contains the full set of Flutter Material widgets and services: | ||
|
|
||
| * **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`, | ||
| `SliverAppBar`, `Drawer`, `NavigationDrawer`, `NavigationBar`, `NavigationRail`, |
There was a problem hiding this comment.
Drawer is legacy, don't recommend
| `Switch`, `Slider`, `RangeSlider`, `DropdownMenu`, `DatePicker`, `TimePicker`, | ||
| `InputDecoration` | ||
| * **Display & Feedback**: `Card`, `Chip`, `ListTile`, `Badge`, `Divider`, | ||
| `DataTable`, `PaginatedDataTable`, `ProgressIndicator`, `SnackBar`, `Tooltip`, |
There was a problem hiding this comment.
DataTable/PaginatedDataTable are legacy, don't recommend
| * **Inputs & Selection**: `TextField`, `TextFormField`, `Checkbox`, `Radio`, | ||
| `Switch`, `Slider`, `RangeSlider`, `DropdownMenu`, `DatePicker`, `TimePicker`, | ||
| `InputDecoration` | ||
| * **Display & Feedback**: `Card`, `Chip`, `ListTile`, `Badge`, `Divider`, |
| * **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`, | ||
| `SliverAppBar`, `Drawer`, `NavigationDrawer`, `NavigationBar`, `NavigationRail`, | ||
| `BottomSheet`, `TabBar`, `SearchAnchor`, `SearchBar` | ||
| * **Buttons & Interaction**: `ElevatedButton`, `FilledButton`, `OutlinedButton`, |
There was a problem hiding this comment.
can add MenuAnchor and MenuBar
|
|
||
| ### Step 3: Bridge legacy dependencies (if needed) | ||
|
|
||
| If your app uses third-party packages or subtrees that still import and rely on |
There was a problem hiding this comment.
is there a way to check this automatically?
|
|
||
| `material_ui` contains the full set of Flutter Material widgets and services: | ||
|
|
||
| * **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`, |
|
|
||
| * **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`, | ||
| `SliverAppBar`, `Drawer`, `NavigationDrawer`, `NavigationBar`, `NavigationRail`, | ||
| `BottomSheet`, `TabBar`, `SearchAnchor`, `SearchBar` |
There was a problem hiding this comment.
can add AlertDialog, Dialog, showDialog. Could match cupertino, which has a Pickers & dialogs header, and also add the missing showDatePicker, showDateRangePicker, showTimePicker
|
|
||
| ## Features & Included Components | ||
|
|
||
| `material_ui` contains the full set of Flutter Material widgets and services: |
There was a problem hiding this comment.
| `material_ui` contains the full set of Flutter Material widgets and services: | |
| `material_ui` contains the following Flutter Material components and styles: |
Not full technically, since some things are implemented elsewhere, like the color system, and symbols
| See Flutter's main [getting started guide](https://flutter.dev/getting-started/) | ||
| for information about using Flutter and `material_ui`. | ||
|
|
||
| ## Features & Included Components |
There was a problem hiding this comment.
| ## Features & Included Components | |
| ## Features |
|
|
||
| `material_ui` contains the full set of Flutter Material widgets and services: | ||
|
|
||
| * **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`, |
There was a problem hiding this comment.
For organizing these, there's a quite few different groups floating around, in the catalog, in https://docs.flutter.dev/ui/widgets/material, in https://m3.material.io/components and https://m3.material.io/styles...
To start to simplify looking for components and styles, I would opt for adopting https://m3.material.io/components and https://m3.material.io/styles structure, that is
Styles
Color: ...
Typography: ...
...
Components
Buttons: ...
Date & time pickers: ...
...
There was a problem hiding this comment.
To start to simplify looking for components and styles,
The read me is not meant to be a full directory. I don't expect users to come to the read me to find out what is where. It's a sampling. The API docs are the indexable source of truth. We are going to be adding dart doc categories so folks can see right in the API docs what widgets reflect Material 2, 3, expressive, etc along with these categories of buttons, pickers etc.
There was a problem hiding this comment.
Yeah I meant this as just a quick summary for now, and I want the maintenance to be low for keeping it up to date. I will make it clear that this is not an exhaustive list and I'll curate it a bit with your suggestions @guidezpl. I expect this README will be revamped in the future with M3E.
| 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, |
There was a problem hiding this comment.
| `cupertino_ui` provides a complete, high-fidelity suite of visual components, | |
| The `cupertino_ui` package provides a complete, high-fidelity suite of visual components, |
Same problem in the material_ui.
| * [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) | ||
| * [Decoupling GitHub Project](https://github.com/orgs/flutter/projects/220) |
There was a problem hiding this comment.
I doubt why we need to include this line
| ## Migrating existing code to this package | ||
|
|
||
| This package will provide the Cupertino widgets you know and love, including but not limited to: | ||
| `cupertino_ui` was previously built directly into the core Flutter framework as |
There was a problem hiding this comment.
| `cupertino_ui` was previously built directly into the core Flutter framework as | |
| The standalone `cupertino_ui` package was previously built directly into the core Flutter framework as |
| ## New to the package? | ||
|
|
||
| This package will provide the Cupertino widgets you know and love, including but not limited to: | ||
| 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`. | ||
|
|
||
| * **Structure:** `CupertinoPageScaffold`, `CupertinoNavigationBar` | ||
| * **Inputs:** `CupertinoButton`, `CupertinoTextField`, `CupertinoSwitch` | ||
| * **Dialogs:** `CupertinoAlertDialog`, `CupertinoActionSheet` | ||
| ## Migrating existing code to this package |
There was a problem hiding this comment.
I was suggesting something like this:
| ## New to the package? | |
| This package will provide the Cupertino widgets you know and love, including but not limited to: | |
| 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`. | |
| * **Structure:** `CupertinoPageScaffold`, `CupertinoNavigationBar` | |
| * **Inputs:** `CupertinoButton`, `CupertinoTextField`, `CupertinoSwitch` | |
| * **Dialogs:** `CupertinoAlertDialog`, `CupertinoActionSheet` | |
| ## Migrating existing code to this package | |
| ## New to the package? | |
| Run `flutter add cupertino_ui`. | |
| See Flutter's main [getting started guide](https://flutter.dev/getting-started/)Collapse comment | |
| for information about using Flutter and `cupertino_ui`. | |
| ## Migrating existing code to this package | |
| 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`. |
So basically I think the README should primarily for new developers, while migration is for the more niche cases.
If this doesn't make sense, we can delete the "New to the package?" section.
There was a problem hiding this comment.
Ohh got it now, no I think you're right.
| ## Getting Started | ||
|
|
||
| See Flutter's main [getting started guide](https://flutter.dev/getting-started/) | ||
| for information about using Flutter and `cupertino_ui`. |
There was a problem hiding this comment.
This duplicates with the "New to the package" section and should be removed.
| --- | ||
|
|
||
| ## Getting Started | ||
|
|
||
| See Flutter's main [getting started guide](https://flutter.dev/getting-started/) | ||
| for information about using Flutter and `material_ui`. |
There was a problem hiding this comment.
Same, remove this section.
Piinks
left a comment
There was a problem hiding this comment.
LGTM as well! 🎉 We could always land this and then the other promote PR, and they'll both get rolled up in the batch release.
|
|
||
| ### Step 2: Migrate localizations (if needed) | ||
|
|
||
| If you are not currently using the GlobalMaterialLocalizations` or |
There was a problem hiding this comment.
| If you are not currently using the GlobalMaterialLocalizations` or | |
| If you are not currently using the `GlobalMaterialLocalizations` or |
Missing a "`" :)
|
I'll plan to merge this PR when it goes green and use #12425 for the version promotion when we're ready. |
…r#191074) flutter/packages@94485f1...a3e763e 2026-08-13 engine-flutter-autoroll@skia.org Manual roll Flutter from 27b0988 to c243752 (179 revisions) (flutter/packages#12453) 2026-08-12 katelovett@google.com [material_ui] Undo relaxed constraints (flutter/packages#12451) 2026-08-12 fluttergithubbot@gmail.com Sync release-cupertino_ui-1.0.0 to main (flutter/packages#12450) 2026-08-12 fluttergithubbot@gmail.com Sync release-material_ui-1.0.0 to main (flutter/packages#12448) 2026-08-12 happytoday83@naver.com [camera_android_camerax] Fix leaked thread per capture in `takePicture` (flutter/packages#12361) 2026-08-12 jmccandless@google.com [material_ui, cupertino_ui] Prepare to release 1.0.0 (flutter/packages#12425) 2026-08-12 jmccandless@google.com [material_ui, cupertino_ui] READMEs (flutter/packages#12428) 2026-08-12 47866232+chunhtai@users.noreply.github.com [ci] presubmit flags pending changelog with version promote on post 1… (flutter/packages#12435) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC flutter-ecosystem@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
This PR updates the material_ui and cupertino_ui READMEs for 1.0.0.
I've kept these pretty minimal and similar to each other. I included a migration guide, which I imagine we will remove after code deletion in flutter/flutter. Feel free to take these in another direction @QuncCccccc @dkwingsmt if you guys have other ideas!