CSS maintenance: flex-grow property

files/en-us/web/css/flex-grow/index.md

@@ -7,9 +7,9 @@ browser-compat: css.properties.flex-grow
 
 {{CSSRef}}
 
-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).
+The **`flex-grow`** [CSS](/en-US/docs/Web/CSS) property sets the flex grow factor, which specifies how much of the flex container's [**positive free space**](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Controlling_ratios_of_flex_items_along_the_main_axis), if any, should be assigned to the flex item's [main size](/en-US/docs/Learn/CSS/CSS_layout/Flexbox#the_flex_model).
 
-When the flex-container's main size is larger than the combined main sizes 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.
+When the flex-container's main size is larger than the combined main sizes of its flex items, this positive free space can be distributed among the flex items, with each item's growth being their growth factor value as a proportion of the sum total of all the container's flex items' flex grow factors.
 
 {{EmbedInteractiveExample("pages/css/flex-grow.html")}}
 
@@ -33,17 +33,21 @@ The `flex-grow` property is specified as a single `<number>`.
 ### Values
 
 - `<number>`
-  - : See {{cssxref("&lt;number&gt;")}}. Negative values are invalid. Defaults to 0.
+  - : See {{cssxref("&lt;number&gt;")}}. Negative values are invalid. Defaults to 0, which prevents the flex item from growing.
 
 ## Description
 
 This property specifies how much of the remaining space in the flex container should be assigned to the item (the flex grow factor).
 
-The [main size](https://www.w3.org/TR/css-flexbox/#main-size) is either width or height of the item which is dependent on the {{cssxref("flex-direction")}} value.
+The [main size](/en-US/docs/Learn/CSS/CSS_layout/Flexbox#the_flex_model) is either the width or height of the item, depending on the {{cssxref("flex-direction")}} value.
 
-The remaining space is the size of the flex container minus the size of all flex items' sizes together. If all sibling items have the same flex grow factor, then all items will receive the same share of remaining space, otherwise it is distributed according to the ratio defined by the different flex grow factors.
+The remaining space, or positive free space, is the size of the flex container minus the size of all flex items' sizes together. If all sibling items have the same flex grow factor, then all items will receive the same share of remaining space. The common practice is to set `flex-grow: 1`, but setting the flex grow factor for all the flex items to `88`, `100`, or `1.2`, any value greater than `0`, will produce the same result; the value is a ratio.
 
-`flex-grow` is used alongside the other flex properties {{cssxref("flex-shrink")}} and {{cssxref("flex-basis")}}, and normally defined using the {{cssxref("flex")}} shorthand to ensure all values are set.
+If the `flex-grow` values differ, the positive free space is distributed according to the ratio defined by the different flex grow factors. The `flex-grow` factor values of all the sibling flex items are added together. The flex container positive free space, if any, is then divided by that total. Each main-size of each flex item with a `flex-grow` value greater than `0` will grow by this quotient multiplied by its owngrowth factor. 
+
+For example, if four `100px` flex items are in a `700px` container with a `flex-grow` factor of `0`, `1`, `2`, and `3`, respectively, the total main size of the three items is `400px`, meaning there is `300px` of positive free space to be distributed. There are a total of 6 grow factors, meaning each grow factor is equal to `50px` (`(300px / 6 )`, which gets distributed based on the items grow factor, leading to flex items that are `100px`, `150px`, `200px`, and `250px` respectively. 
+
+The `flex-grow` is generally used alongside the other {{cssxref("flex")}} shorthand properties, {{cssxref("flex-shrink")}} and {{cssxref("flex-basis")}}. Using the `flex` shorthand property is recommended to ensure all values are set.
 
 ## Formal definition
 
@@ -57,12 +61,12 @@ 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.
+In this example, there is a total of eight growth factors distributed among the six flex items, meaning each growth factor is `12.5%` of the remaining space.
 
 #### HTML
 
 ```html
-<h4>This is a Flex-Grow</h4>
+<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="small" style="background-color:red;">A</div>
@@ -79,15 +83,14 @@ In this example, there is a total of 8 growth factors distributed among the 6 fl
 ```css
 #content {
   display: flex;
+}
 
-  justify-content: space-around;
-  flex-flow: row wrap;
-  align-items: stretch;
+div > div {
+  border: 3px solid rgb(0 0 0 / 20%);
 }
 
 .small {
   flex-grow: 1;
-  border: 3px solid rgb(0 0 0 / 20%);
 }
 
 .double {
@@ -100,7 +103,7 @@ In this example, there is a total of 8 growth factors distributed among the 6 fl
 
 {{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.
+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
 
@@ -112,6 +115,8 @@ When the six flex items are distributed along the container's main axis, if the
 
 ## See also
 
-- CSS Flexbox Guide: _[Basic Concepts of Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox)_
-- CSS Flexbox Guide: _[Controlling Ratios of flex items along the main axis](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Controlling_ratios_of_flex_items_along_the_main_axis)_
-- [`flex-grow` is weird. Or is it?](https://css-tricks.com/flex-grow-is-weird/) article by Manuel Matuzovic on CSS-Tricks, which illustrates how flex-grow works
+- {{cssxref("flex")}} shorthand
+- [Basic Concepts of Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox)
+- [Controlling Ratios of flex items along the main axis](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Controlling_ratios_of_flex_items_along_the_main_axis)
+- [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module
+- [`flex-grow` is weird. Or is it?](https://css-tricks.com/flex-grow-is-weird/) via CSS-Tricks (2017)