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

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.

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

…rm-specific visual density behavior Signed-off-by: huycozy <huy@nevercode.io>

Piinks

LGTM thanks!

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

flutter/flutter@b3fb4c7...2265d94 2025-08-18 matanlurey@users.noreply.github.com Remove `embedded_android_views` (on-device) tests, same as emulator test (flutter/flutter#173814) 2025-08-18 engine-flutter-autoroll@skia.org Roll Skia from 3a17208059ec to 07d71ea4d056 (4 revisions) (flutter/flutter#173942) 2025-08-18 engine-flutter-autoroll@skia.org Roll Skia from 978726c1e725 to 3a17208059ec (2 revisions) (flutter/flutter#173939) 2025-08-18 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from sLmXksm1vZl2VEeA7... to n0EnLlotF2wczlOq_... (flutter/flutter#173936) 2025-08-18 huy@nevercode.io Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior (flutter/flutter#173695) 2025-08-18 engine-flutter-autoroll@skia.org Roll Skia from 88e8c099a086 to 978726c1e725 (3 revisions) (flutter/flutter#173935) 2025-08-18 engine-flutter-autoroll@skia.org 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 bmparr@google.com,stuartmorgan@google.com 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 <huy@nevercode.io>

…#9845) flutter/flutter@b3fb4c7...2265d94 2025-08-18 matanlurey@users.noreply.github.com Remove `embedded_android_views` (on-device) tests, same as emulator test (flutter/flutter#173814) 2025-08-18 engine-flutter-autoroll@skia.org Roll Skia from 3a17208059ec to 07d71ea4d056 (4 revisions) (flutter/flutter#173942) 2025-08-18 engine-flutter-autoroll@skia.org Roll Skia from 978726c1e725 to 3a17208059ec (2 revisions) (flutter/flutter#173939) 2025-08-18 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from sLmXksm1vZl2VEeA7... to n0EnLlotF2wczlOq_... (flutter/flutter#173936) 2025-08-18 huy@nevercode.io Enhance FilledButton and Theme Data's documentation to clarify platform-specific visual density behavior (flutter/flutter#173695) 2025-08-18 engine-flutter-autoroll@skia.org Roll Skia from 88e8c099a086 to 978726c1e725 (3 revisions) (flutter/flutter#173935) 2025-08-18 engine-flutter-autoroll@skia.org 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 bmparr@google.com,stuartmorgan@google.com 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 <huy@nevercode.io>

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

huycozy self-assigned this Aug 13, 2025

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. labels Aug 13, 2025

gemini-code-assist bot reviewed Aug 13, 2025

View reviewed changes

packages/flutter/lib/src/material/theme_data.dart Outdated Show resolved Hide resolved

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

1bbb9a8

…rm-specific visual density behavior Signed-off-by: huycozy <huy@nevercode.io>

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
75 checks passed

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

b1551a19e Enhance FilledButton and Theme Data's documentation to clar…

1ff5f56

…ify 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

b1551a19e Enhance FilledButton and Theme Data's documentation to clar…

5707f58

…ify 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

b1551a19e Enhance FilledButton and Theme Data's documentation to clar…

2001303

…ify 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

Open

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

b1551a19e Enhance FilledButton and Theme Data's documentation to clar…

e587631

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

Uh oh!

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!

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);

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

Uh oh!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

huycozy commented Aug 13, 2025 •

edited

Loading