From e78b434e8f08145aa188fcbfe71092cb987eebaf Mon Sep 17 00:00:00 2001
From: Bruno Leroux <bruno.leroux@gmail.com>
Date: Thu, 22 May 2025 11:32:20 +0200
Subject: [PATCH] Update ButtonStyle documentation (#168062)

## Description

This PR updates `ButtonStyle.minimumSize` and `ButtonStyle.fixedSize`
documentation.

It updates the documentation in order to describe the current behavior
as it might be surprising.
I have considered changing the behavior related to
`ButtonStyle.minimumSize` but while experimenting I noticed that several
widgets in the framework (and several tests) use
`ButtonStyle.minimumSize` with the expectation that the given size is
adjusted based on the ambient visual density (and there are probably
several similar usages outside of the framework in Google and non-Google
apps).

## Related Issue

ButtonStyle.minimumSize : Fixes [minimumSize not respected properly when
visual density is not
standard](https://github.com/flutter/flutter/issues/123528)
ButtonStyle.fixedSize : Fixes [Button behaves differently in Web/Desktop
and Mobile](https://github.com/flutter/flutter/issues/85729)

## Tests

Documentation only

---------

Co-authored-by: Kate Lovett <katelovett@google.com>
---
 .../flutter/lib/src/material/button_style.dart   | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/packages/flutter/lib/src/material/button_style.dart b/packages/flutter/lib/src/material/button_style.dart
index 333dffb9d3e..7bcac2fa73c 100644
--- a/packages/flutter/lib/src/material/button_style.dart
+++ b/packages/flutter/lib/src/material/button_style.dart
@@ -249,12 +249,23 @@ class ButtonStyle with Diagnosticable {
   /// See [ThemeData.visualDensity] for more details.
   final MaterialStateProperty<EdgeInsetsGeometry?>? padding;
 
-  /// The minimum size of the button itself.
+  /// The minimum size of the button itself before applying [visualDensity].
   ///
   /// The size of the rectangle the button lies within may be larger
   /// per [tapTargetSize].
   ///
   /// This value must be less than or equal to [maximumSize].
+  ///
+  /// The minimum size is adjusted automatically based on [visualDensity].
+  ///
+  /// When visual density is [VisualDensity.compact], the minimum size is
+  /// reduced by 8 pixels on both dimensions.
+  ///
+  /// When visual density is [VisualDensity.comfortable], the minimum size is
+  /// [minimumSize] reduced by 4 pixels on both dimensions.
+  ///
+  /// When visual density is [VisualDensity.standard], the minimum size is
+  /// [minimumSize].
   final MaterialStateProperty<Size?>? minimumSize;
 
   /// The button's size.
@@ -263,6 +274,9 @@ class ButtonStyle with Diagnosticable {
   /// and [maximumSize]. Fixed size dimensions whose value is
   /// [double.infinity] are ignored.
   ///
+  /// The size of the rectangle the button lies within may be larger
+  /// per [tapTargetSize].
+  ///
   /// To specify buttons with a fixed width and the default height use
   /// `fixedSize: Size.fromWidth(320)`. Similarly, to specify a fixed
   /// height and the default width use `fixedSize: Size.fromHeight(100)`.