Skip to content

Add design migration guide - #13821

Merged
sfshaza2 merged 1 commit into
flutter:mainfrom
Piinks:designMigrationGuide
Aug 28, 2026
Merged

sfshaza2 merged 1 commit into
flutter:mainfrom
Piinks:designMigrationGuide

Conversation

@Piinks

@Piinks Piinks commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Adds the migration guide for migrating to material_ui and cupertino_ui
I believe we'll be adding more docs, or a dedicated page on the site, but it would be great to have a place to point for now that isn't just the latest the release blog. :)
We'll be making a bigger call to action to migrate in the Fall release after we deprecate the original libraries. This should be good in the meantime for our early adopters. I already incorporated the early feedback we have received from them.

Fixes flutter/flutter#191448
Related to flutter/flutter#191067

Presubmit checklist

  • If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.
  • If this PR is not meant to land until a future stable release, mark it as draft with an explanation.
  • This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).
  • This PR uses semantic line breaks
    of 80 characters or fewer.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds documentation for migrating to the standalone material_ui and cupertino_ui packages, which decouple Flutter's design systems from the core SDK. The documentation covers automated and manual migration steps, the compatibility bridge, and localization changes. Feedback on the documentation suggests improving the code example for the compatibility bridge by safely handling a potentially null child widget instead of using a force-unwrap operator, which could lead to runtime exceptions.

@flutter-website-bot

Copy link
Copy Markdown
Collaborator

@flutter-website-bot

Copy link
Copy Markdown
Collaborator

@sfshaza2 sfshaza2 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great, @Piinks!!! I'm lgtm'ing it, though the bot has one issue and I defer to you on addressing that (or not). Also, does localization code require special handling?

@Piinks

Piinks commented Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

Also, does localization code require special handling?

Do you mean beyond what is already here? This should cover it.

@sfshaza2
sfshaza2 merged commit a2a7087 into flutter:main Aug 28, 2026
14 checks passed
sfshaza2 pushed a commit that referenced this pull request Aug 31, 2026
Adds the migration guide for migrating to material_ui and cupertino_ui
I believe we'll be adding more docs, or a dedicated page on the site,
but it would be great to have a place to point for now that isn't just
the latest the release blog. :)
We'll be making a bigger call to action to migrate in the Fall release
after we deprecate the original libraries. This should be good in the
meantime for our early adopters. I already incorporated the early
feedback we have received from them.

Fixes flutter/flutter#191448
Related to flutter/flutter#191067

## Presubmit checklist

- [x] If you are unwilling, or unable, to sign the CLA, even for a
_tiny_, one-word PR, please file an issue instead of a PR.
- [ ] If this PR is not meant to land until a future stable release,
mark it as draft with an explanation.
- [x] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style)—for example, it doesn't
use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person
pronouns).
- [x] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
  of 80 characters or fewer.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[material_ui] MaterialUiCompatibilityBridge cannot cover API-signature coupling, only context lookups

3 participants