Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior by huycozy · Pull Request #173695 · flutter/flutter

huycozy · 2025-08-13T09:03:13Z

Fix Padding inside FilledButton have a different behavior on web when on Mobile Browser vs Desktop Browser #155768
Description: The issue is not a bug but WAI, it's due to visual density not being the same on each platform by default (see my full explanation at here), see:

flutter/packages/flutter/lib/src/material/theme_data.dart

Lines 3250 to 3255 in f227871

    
             static VisualDensity defaultDensityForPlatform(TargetPlatform platform) { 
        
               return switch (platform) { 
        
                 TargetPlatform.android || TargetPlatform.iOS || TargetPlatform.fuchsia => standard, 
        
                 TargetPlatform.linux || TargetPlatform.macOS || TargetPlatform.windows => compact, 
        
               }; 
        
             }

This is LOCs where visual density impacts the padding:

flutter/packages/flutter/lib/src/material/button_style_button.dart

Lines 501 to 505 in a04fb32

    
           final double dy = densityAdjustment.dy; 
        
           final double dx = math.max(0, densityAdjustment.dx); 
        
           final EdgeInsetsGeometry padding = resolvedPadding! 
        
               .add(EdgeInsets.fromLTRB(dx, dy, dx, dy)) 
        
               .clamp(EdgeInsets.zero, EdgeInsetsGeometry.infinity);

In this PR:

Add Visual density effects section to FilledButton documentation to avoid confusion for users
Improve the documentation for VisualDensity.defaultDensityForPlatform by including detailed information about the specific density for each platform.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

gemini-code-assist

Code Review

This pull request enhances the documentation for FilledButton and ThemeData to clarify platform-specific behaviors related to VisualDensity. The changes are well-executed, adding a new 'Visual density effects' section to FilledButton and improving the documentation for VisualDensity in theme_data.dart. The new documentation is clear, accurate, and will be very helpful for developers to understand why visual density differs across platforms. I've added one minor suggestion to improve the conciseness of a documentation comment.

…rm-specific visual density behavior Signed-off-by: huycozy <[email protected]>

Piinks

LGTM thanks!

…y platform-specific visual density behavior (flutter/flutter#173695)

flutter/flutter@b3fb4c7...2265d94 2025-08-18 [email protected] Remove `embedded_android_views` (on-device) tests, same as emulator test (flutter/flutter#173814) 2025-08-18 [email protected] Roll Skia from 3a17208059ec to 07d71ea4d056 (4 revisions) (flutter/flutter#173942) 2025-08-18 [email protected] Roll Skia from 978726c1e725 to 3a17208059ec (2 revisions) (flutter/flutter#173939) 2025-08-18 [email protected] Roll Fuchsia Linux SDK from sLmXksm1vZl2VEeA7... to n0EnLlotF2wczlOq_... (flutter/flutter#173936) 2025-08-18 [email protected] Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior (flutter/flutter#173695) 2025-08-18 [email protected] Roll Skia from 88e8c099a086 to 978726c1e725 (3 revisions) (flutter/flutter#173935) 2025-08-18 [email protected] Roll Dart SDK from a874859559e6 to 502455ee300b (1 revision) (flutter/flutter#173934) 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 Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: 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

…rm-specific visual density behavior (flutter#173695) - Fix flutter#155768 - Description: The issue is not a bug but WAI, it's due to visual density not being the same on each platform by default (see my full explanation at [here](flutter#155768 (comment))), see: https://github.com/flutter/flutter/blob/f22787193bcca7c1455f29e1ed4fd15215a736d5/packages/flutter/lib/src/material/theme_data.dart#L3250-L3255 - This is LOCs where visual density impacts the padding: https://github.com/flutter/flutter/blob/a04fb324be734cf18811c30c06baf9bf07b3bab3/packages/flutter/lib/src/material/button_style_button.dart#L501-L505 In this PR: - Add `Visual density effects` section to FilledButton documentation to avoid confusion for users - Improve the documentation for `VisualDensity.defaultDensityForPlatform` by including detailed information about the specific density for each platform. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md Signed-off-by: huycozy <[email protected]>

flutter/flutter@b3fb4c7...2265d94 2025-08-18 [email protected] Remove `embedded_android_views` (on-device) tests, same as emulator test (flutter/flutter#173814) 2025-08-18 [email protected] Roll Skia from 3a17208059ec to 07d71ea4d056 (4 revisions) (flutter/flutter#173942) 2025-08-18 [email protected] Roll Skia from 978726c1e725 to 3a17208059ec (2 revisions) (flutter/flutter#173939) 2025-08-18 [email protected] Roll Fuchsia Linux SDK from sLmXksm1vZl2VEeA7... to n0EnLlotF2wczlOq_... (flutter/flutter#173936) 2025-08-18 [email protected] Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior (flutter/flutter#173695) 2025-08-18 [email protected] Roll Skia from 88e8c099a086 to 978726c1e725 (3 revisions) (flutter/flutter#173935) 2025-08-18 [email protected] Roll Dart SDK from a874859559e6 to 502455ee300b (1 revision) (flutter/flutter#173934) 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 Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: 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

…rm-specific visual density behavior (flutter#173695) - Fix flutter#155768 - Description: The issue is not a bug but WAI, it's due to visual density not being the same on each platform by default (see my full explanation at [here](flutter#155768 (comment))), see: https://github.com/flutter/flutter/blob/f22787193bcca7c1455f29e1ed4fd15215a736d5/packages/flutter/lib/src/material/theme_data.dart#L3250-L3255 - This is LOCs where visual density impacts the padding: https://github.com/flutter/flutter/blob/a04fb324be734cf18811c30c06baf9bf07b3bab3/packages/flutter/lib/src/material/button_style_button.dart#L501-L505 In this PR: - Add `Visual density effects` section to FilledButton documentation to avoid confusion for users - Improve the documentation for `VisualDensity.defaultDensityForPlatform` by including detailed information about the specific density for each platform. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md Signed-off-by: huycozy <[email protected]>

…y platform-specific visual density behavior (flutter/flutter#173695)

…rm-specific visual density behavior (flutter#173695) - Fix flutter#155768 - Description: The issue is not a bug but WAI, it's due to visual density not being the same on each platform by default (see my full explanation at [here](flutter#155768 (comment))), see: https://github.com/flutter/flutter/blob/f22787193bcca7c1455f29e1ed4fd15215a736d5/packages/flutter/lib/src/material/theme_data.dart#L3250-L3255 - This is LOCs where visual density impacts the padding: https://github.com/flutter/flutter/blob/a04fb324be734cf18811c30c06baf9bf07b3bab3/packages/flutter/lib/src/material/button_style_button.dart#L501-L505 In this PR: - Add `Visual density effects` section to FilledButton documentation to avoid confusion for users - Improve the documentation for `VisualDensity.defaultDensityForPlatform` by including detailed information about the specific density for each platform. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md Signed-off-by: huycozy <[email protected]>

flutter/flutter@b3fb4c7...2265d94 2025-08-18 [email protected] Remove `embedded_android_views` (on-device) tests, same as emulator test (flutter/flutter#173814) 2025-08-18 [email protected] Roll Skia from 3a17208059ec to 07d71ea4d056 (4 revisions) (flutter/flutter#173942) 2025-08-18 [email protected] Roll Skia from 978726c1e725 to 3a17208059ec (2 revisions) (flutter/flutter#173939) 2025-08-18 [email protected] Roll Fuchsia Linux SDK from sLmXksm1vZl2VEeA7... to n0EnLlotF2wczlOq_... (flutter/flutter#173936) 2025-08-18 [email protected] Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior (flutter/flutter#173695) 2025-08-18 [email protected] Roll Skia from 88e8c099a086 to 978726c1e725 (3 revisions) (flutter/flutter#173935) 2025-08-18 [email protected] Roll Dart SDK from a874859559e6 to 502455ee300b (1 revision) (flutter/flutter#173934) 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 Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: 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

huycozy self-assigned this Aug 13, 2025

github-actions Bot added framework flutter/packages/flutter repository. See also f: labels. p: material_ui material_ui package in flutter/packages labels Aug 13, 2025

gemini-code-assist Bot reviewed Aug 13, 2025

View reviewed changes

Comment thread packages/flutter/lib/src/material/theme_data.dart Outdated

Enhance FilledButton and Theme Data's documentation to clarify platfo…

1bbb9a8

…rm-specific visual density behavior Signed-off-by: huycozy <[email protected]>

huycozy force-pushed the improve-filled-button-docs-for-indensity branch from 232ee2c to 1bbb9a8 Compare August 13, 2025 09:21

huycozy marked this pull request as ready for review August 13, 2025 09:48

huycozy requested a review from Piinks August 13, 2025 09:50

Piinks approved these changes Aug 15, 2025

View reviewed changes

huycozy added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 18, 2025

auto-submit Bot added this pull request to the merge queue Aug 18, 2025

Merged via the queue into flutter:master with commit b1551a1 Aug 18, 2025

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Aug 18, 2025

huycozy deleted the improve-filled-button-docs-for-indensity branch August 18, 2025 04:04

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 18, 2025

b1551a1 Enhance FilledButton and Theme Data's documentation to clarif…

1ff5f56

…y platform-specific visual density behavior (flutter/flutter#173695)

engine-flutter-autoroll mentioned this pull request Aug 18, 2025

Roll Flutter from b3fb4c786d80 to 660c234bb02e (5 revisions) flutter/packages#9842

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 18, 2025

b1551a1 Enhance FilledButton and Theme Data's documentation to clarif…

5707f58

…y platform-specific visual density behavior (flutter/flutter#173695)

engine-flutter-autoroll mentioned this pull request Aug 18, 2025

Roll Flutter from b3fb4c786d80 to 78df185e5a8d (6 revisions) flutter/packages#9844

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 18, 2025

b1551a1 Enhance FilledButton and Theme Data's documentation to clarif…

2001303

…y platform-specific visual density behavior (flutter/flutter#173695)

engine-flutter-autoroll mentioned this pull request Aug 18, 2025

Roll Flutter from b3fb4c786d80 to 2265d94c6b0b (7 revisions) flutter/packages#9845

Merged

Piinks mentioned this pull request Aug 29, 2025

Flutter Notable Commits - 2025 #161460

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 12, 2025

b1551a1 Enhance FilledButton and Theme Data's documentation to clarif…

e587631

…y platform-specific visual density behavior (flutter/flutter#173695)

Navigation Menu

Repository navigation

Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior - #173695

Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior#173695
auto-submit[bot] merged 1 commit into
flutter:masterfrom
huycozy:improve-filled-button-docs-for-indensity

huycozy commented Aug 13, 2025 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Piinks left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	static VisualDensity defaultDensityForPlatform(TargetPlatform platform) {
	return switch (platform) {
	TargetPlatform.android \|\| TargetPlatform.iOS \|\| TargetPlatform.fuchsia => standard,
	TargetPlatform.linux \|\| TargetPlatform.macOS \|\| TargetPlatform.windows => compact,
	};
	}

	final double dy = densityAdjustment.dy;
	final double dx = math.max(0, densityAdjustment.dx);
	final EdgeInsetsGeometry padding = resolvedPadding!
	.add(EdgeInsets.fromLTRB(dx, dy, dx, dy))
	.clamp(EdgeInsets.zero, EdgeInsetsGeometry.infinity);

Conversation

huycozy commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

huycozy commented Aug 13, 2025 •

edited

Loading