From f421d513726545316580eb3fc3cbe8dde632b046 Mon Sep 17 00:00:00 2001
From: Estelle Weyl <estelle@weyl.org>
Date: Thu, 23 Mar 2023 23:41:28 -0700
Subject: [PATCH] clarify flex-grow (#25590)

* clarify flex-grow

* spaces

* Apply suggestions from code review

Co-authored-by: dawei-wang <dawei-wang@users.noreply.github.com>

---------

Co-authored-by: dawei-wang <dawei-wang@users.noreply.github.com>
---
 files/en-us/web/css/flex-grow/index.md | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/files/en-us/web/css/flex-grow/index.md b/files/en-us/web/css/flex-grow/index.md
index d615c1dbe72723c..282c93e691c2757 100644
--- a/files/en-us/web/css/flex-grow/index.md
+++ b/files/en-us/web/css/flex-grow/index.md
@@ -7,7 +7,9 @@ browser-compat: css.properties.flex-grow
 
 {{CSSRef}}
 
-The **`flex-grow`** [CSS](/en-US/docs/Web/CSS) property sets the flex grow factor of a flex item's [main size](https://www.w3.org/TR/css-flexbox/#main-size).
+The **`flex-grow`** [CSS](/en-US/docs/Web/CSS) property sets the flex grow factor, which specifies how much of the flex container's remaining space should be assigned to the flex item's [main size](https://www.w3.org/TR/css-flexbox/#main-size).
+
+When the flex-container's main size is larger than the combined main size's of the flex items, the extra space is distributed among the flex items, with each item growth being their growth factor value as a proportion of the sum total of all the container's items' flex grow factors.
 
 {{EmbedInteractiveExample("pages/css/flex-grow.html")}}
 
@@ -55,18 +57,20 @@ The remaining space is the size of the flex container minus the size of all flex
 
 ### Setting flex item grow factor
 
+In this example, there is a total of 8 growth factors distributed among the 6 flex items, meaning each growth factor is 12.5% of the remaining space.
+
 #### HTML
 
 ```html
 <h4>This is a Flex-Grow</h4>
 <h5>A,B,C and F are flex-grow:1 . D and E are flex-grow:2 .</h5>
 <div id="content">
-  <div class="box" style="background-color:red;">A</div>
-  <div class="box" style="background-color:lightblue;">B</div>
-  <div class="box" style="background-color:yellow;">C</div>
-  <div class="box1" style="background-color:brown;">D</div>
-  <div class="box1" style="background-color:lightgreen;">E</div>
-  <div class="box" style="background-color:brown;">F</div>
+  <div class="small" style="background-color:red;">A</div>
+  <div class="small" style="background-color:lightblue;">B</div>
+  <div class="small" style="background-color:yellow;">C</div>
+  <div class="double" style="background-color:brown;">D</div>
+  <div class="double" style="background-color:lightgreen;">E</div>
+  <div class="small" style="background-color:brown;">F</div>
 </div>
 ```
 
@@ -81,12 +85,12 @@ The remaining space is the size of the flex container minus the size of all flex
   align-items: stretch;
 }
 
-.box {
+.small {
   flex-grow: 1;
   border: 3px solid rgba(0, 0, 0, 0.2);
 }
 
-.box1 {
+.double {
   flex-grow: 2;
   border: 3px solid rgba(0, 0, 0, 0.2);
 }
@@ -96,6 +100,8 @@ The remaining space is the size of the flex container minus the size of all flex
 
 {{EmbedLiveSample('Setting flex item grow factor')}}
 
+When the six flex items are distributed along the container's main axis, if the sum of the main content of those flex items is less than the size of the container's main axis, the extra space is distributed among the size flex items, with A, B, C, and F, each getting 12.5% of the remaining space and D and E each getting 25% of the extra space.
+
 ## Specifications
 
 {{Specifications}}