docs(CSS): Allow more usage of multi-keyword display values (mdn#30831

)

* docs(CSS): Mutli-keyword display values no longer experimental

* docs(CSS): Reduce noise in PR

* docs(css): Improvements following reviewer feedback

* Apply suggestions from code review

Co-authored-by: Estelle Weyl <[email protected]>

* docs(css): Improvements following reviewer feedback

* docs(css): Improvements following reviewer feedback

* docs(css): Improvements following reviewer feedback

* docs(css): Improvements following reviewer feedback

* Apply suggestions from code review

Co-authored-by: Estelle Weyl <[email protected]>

* Update files/en-us/web/css/display/multi-keyword_syntax_of_display/index.md

Co-authored-by: Estelle Weyl <[email protected]>

* Update files/en-us/web/css/display/multi-keyword_syntax_of_display/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update files/en-us/web/css/display/multi-keyword_syntax_of_display/index.md

---------

Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

files/en-us/learn/css/css_layout/flexbox/index.md

@@ -59,13 +59,19 @@ section {
 }
 ```
 
-This causes the \<section> element to become a **flex container** and its children to become **flex items**. The result of this should be something like so:
+This causes the `<section>` element to become a **flex container** and its children become **flex items**. This is what it looks like:
 
 ![A two row container that includes a single column in the first row and a 3-column layout in the second row that shows how a webpage can be divided into different layouts depending on the contents](flexbox-example2.png)
 
-So, this single declaration gives us everything we need. Incredible, right? We have our multiple column layout with equal-sized columns, and the columns are all the same height. This is because the default values given to flex items (the children of the flex container) are set up to solve common problems such as this.
+This single declaration gives us everything we need. Incredible, right? We have a multiple column layout with equal-sized columns, and the columns are all the same height. This is because the default values given to flex items (the children of the flex container) are set up to solve common problems such as this.
 
-To be clear, let's reiterate what is happening here. The element we've given a {{cssxref("display")}} value of `flex` to is acting like a block-level element in terms of how it interacts with the rest of the page, but its children are laid out as flex items. The next section will explain in more detail what this means. Note also that you can use a `display` value of `inline-flex` if you wish to lay out an element's children as flex items, but have that element behave like an inline element.
+Let's recap what's happening here. Adding a {{cssxref("display")}} value of `flex` to an element makes it a flex container. The container is displayed as [Block-level content](/en-US/docs/Glossary/Block-level_content) in terms of how it interacts with the rest of the page. When the element is converted to a flex container, its children are converted to (and laid out as) flex items.
+
+You can make the container inline using an [outside `display` value](/en-US/docs/Web/CSS/display#outside) (e.g., `display: inline flex`), which affects how the container itself is laid out in the page.
+The legacy `inline-flex` display value displays the container as inline as well.
+We'll focus on how the the contents of the container behave in this tutorial, but if you want to see the effect of inline versus block layout, you can have a look at the [value comparison](/en-US/docs/Web/CSS/display#display_value_comparison) on the `display` property page.
+
+The next sections explain in more detail what flex items are and what happens inside an element when you make it a flex container.
 
 ## The flex model
 
@@ -331,16 +337,6 @@ button {
 }
 ```
 
-## Cross-browser compatibility
-
-Flexbox support is available in most new browsers: Firefox, Chrome, Opera, Microsoft Edge, and IE 11, newer versions of Android/iOS, etc. However, you should be aware that there are still older browsers in use that don't support Flexbox (or do, but support a really old, out-of-date version of it.)
-
-While you're just learning and experimenting, this doesn't matter too much; however, if you're considering using flexbox in a real website, you need to do testing and make sure that your user experience is still acceptable in as many browsers as possible.
-
-Flexbox is a bit trickier than some CSS features. For example, if a browser is missing a CSS drop shadow, then the site will likely still be usable. Not supporting flexbox features, however, will probably break a layout completely, making it unusable.
-
-We discuss strategies for overcoming cross-browser support issues in our [Cross browser testing](/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing) module.
-
 ## Test your skills!
 
 You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Flexbox](/en-US/docs/Learn/CSS/CSS_layout/Flexbox_skills).

files/en-us/web/css/css_display/index.md

@@ -26,7 +26,8 @@ The **CSS display** module defines how the CSS formatting box tree is generated
 
 ## Guides
 
-- [Adapting to the multi-keyword syntax of display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display)
+- [Using the multi-keyword syntax with CSS display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display)
+  - : Describes the multi-keyword syntax and compares this syntax with legacy single-keyword values.
 
 ### Flow layout (display: block, display: inline)
 
@@ -68,3 +69,8 @@ The **CSS display** module defines how the CSS formatting box tree is generated
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module
+- [CSS grid layout](Web/CSS/CSS_grid_layout) module

files/en-us/web/css/css_flexible_box_layout/basic_concepts_of_flexbox/index.md

@@ -61,7 +61,9 @@ After a while, thinking about start and end rather than left and right becomes n
 
 ## The flex container
 
-An area of a document laid out using flexbox is called a **flex container**. To create a flex container, we set the value of the area's container's {{cssxref("display")}} property to `flex` or `inline-flex`. As soon as we do this the direct children of that container become **flex items**. As with all properties in CSS, some initial values are defined, so when creating a flex container all of the contained flex items will behave in the following way.
+An area of a document that is laid out using flexbox is called a **flex container**. To create a flex container, set the area's {{cssxref("display")}} property to `flex`. When we do this, the direct children of that container become **flex items**. You can explicitly control whether the container itself is displayed inline or in block formatting context using `inline flex` or `inline-flex` for inline flex containers or `block flex` or `flex` for block level flex containers.
+
+As with all properties in CSS, some initial values are defined, so the contents of a new flex container will behave in the following way:
 
 - Items display in a row (the `flex-direction` property's default is `row`).
 - The items start from the start edge of the main axis.

files/en-us/web/css/css_flexible_box_layout/index.md

@@ -65,6 +65,8 @@ The properties `align-content`, `align-self`, `align-items` and `justify-content
 
 ## See also
 
+- [CSS display](/en-US/docs/Web/CSS/CSS_display) module
+- [Using the multi-keyword syntax with CSS display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display)
 - Glossary terms:
   - {{Glossary("Flexbox")}}
   - {{Glossary("Flex Container")}}

files/en-us/web/css/css_grid_layout/index.md

@@ -151,6 +151,8 @@ The example below shows a three-column track grid with new rows created at a min
   - [Grid axis](/en-US/docs/Glossary/Grid_Axis)
   - [Grid row](/en-US/docs/Glossary/Grid_Row)
   - [Grid column](/en-US/docs/Glossary/Grid_Column)
+- [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module
+- [CSS display](/en-US/docs/Web/CSS/CSS_display) module
 - [Grid by Example](https://gridbyexample.com/) - A collection of usage examples and video tutorials
 - [CSS Grid Reference - Codrops](https://tympanus.net/codrops/css_reference/grid/)
 - [CSS Grid Inspector - Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_grid_layouts/index.html)

files/en-us/web/css/display-outside/index.md

@@ -18,7 +18,8 @@ Valid `<display-outside>` values:
 - `inline`
   - : The element generates one or more inline element boxes that do not generate line breaks before or after themselves. In normal flow, the next element will be on the same line if there is space.
 
-> **Note:** Browsers that support the two value syntax, on finding the outer value only, such as when `display: block` or `display: inline` is specified, will set the inner value to `flow`. This will result in expected behavior; for example if you specify an element to be block, you would expect that the children of that element would participate in block and inline normal flow layout.
+> **Note:** When browsers encounter a display property with only an **outer** `display` value (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).
+> This is backwards-compatible with single-keyword syntax.
 
 ## Formal syntax
 

files/en-us/web/css/display/index.md

@@ -31,14 +31,14 @@ display: none;
 display: contents;
 
 /* multi-keyword syntax */
+display: block flex;
 display: block flow;
+display: block flow-root;
+display: block grid;
+display: inline flex;
 display: inline flow;
 display: inline flow-root;
-display: block flex;
-display: inline flex;
-display: block grid;
 display: inline grid;
-display: block flow-root;
 
 /* other values */
 display: table;
@@ -70,8 +70,18 @@ The keyword values can be grouped into six value categories.
     - `inline`
       - : The element generates one or more inline boxes that do not generate line breaks before or after themselves. In normal flow, the next element will be on the same line if there is space.
 
-> **Note:** Browsers that support the multi-keyword syntax, on finding the outer value only, such as when `display: block` or `display: inline` is specified, will set the inner value to `flow`.
-> This will result in expected behavior; for example, if you specify an element to be block, you would expect that the children of that element would participate in block and inline normal flow layout.
+> **Note:** When browsers that support multi-keyword syntax encounter a display property that only has an **outer** value (e.g., `display: block` or `display: inline`), the inner value is set to `flow` (e.g., `display: block flow` and `display: inline flow`).
+
+> **Note:** To be sure layouts work on older browsers, you may use single-value syntax, for example `display: inline flex` could have the following fallback
+>
+> ```css
+> .container {
+>   display: inline-flex;
+>   display: inline flex;
+> }
+> ```
+>
+> See [Using the multi-keyword syntax with CSS display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display) for more information.
 
 ### Inside
 
@@ -98,8 +108,7 @@ The keyword values can be grouped into six value categories.
     - `ruby` {{Experimental_Inline}}
       - : The element behaves like an inline-level element and lays out its content according to the ruby formatting model. It behaves like the corresponding HTML {{HTMLElement("ruby")}} elements.
 
-> **Note:** Browsers that support the multi-keyword syntax, on finding the inner value only, such as when `display: flex` or `display: grid` is specified, will set their outer value to `block`.
-> This will result in expected behavior; for example, if you specify an element to be `display: grid`, you would expect that the box created on the grid container would be a block-level box.
+> **Note:** When browsers that support multi-keyword syntax encounter a display property that only has an **inner** value (e.g., `display: flex` or `display: grid`), the outer value is set to `block` (e.g., `display: block flex` and `display: block grid`).
 
 ### List Item
 
@@ -190,27 +199,28 @@ This can be used together with {{CSSxRef("list-style-type")}} and {{CSSxRef("lis
 
         It is equivalent to `inline grid`.
 
-### Which syntax should you use now?
+### Which syntax should you use?
 
-The Level 3 specification details two values for the `display` property — enabling the specification of the outer and inner display type explicitly — but this is not yet well-supported by browsers.
+The [CSS display module](/en-US/docs/Web/CSS/CSS_display) describes a multi-keyword syntax for values you can use with the `display` property to explicitly define **outer** and **inner** display.
+The single keyword values (precomposed `<display-legacy>` values) are supported for backward-compatibility.
 
-The precomposed `<display-legacy>` methods allow the same results with single keyword values, and should be favoured by developers until the two keyword values are better supported. For example, using two values you might specify an inline flex container as follows:
+For example, using two values you can specify an inline flex container as follows:
 
 ```css
 .container {
   display: inline flex;
 }
 ```
 
-This can currently be specified using a single value.
+This can also be specified using the legacy single value:
 
 ```css
 .container {
   display: inline-flex;
 }
 ```
 
-For more information on these changes to the specification, see the article [Adapting to the new multi-keyword syntax of display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display).
+For more information on these changes, see the [Using the multi-keyword syntax with CSS display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display) guide.
 
 ### Global
 
@@ -225,7 +235,9 @@ display: unset;
 
 The individual pages for the different types of value that `display` can have set on it feature multiple examples of those values in action — see the [Syntax](#syntax) section. In addition, see the following material, which covers the various values of display in depth.
 
-- [Adapting to the new multi-keyword syntax of display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display)
+### Multi-keyword values
+
+- [Using the multi-keyword syntax with CSS display](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display)
 
 ### CSS Flow Layout (display: block, display: inline)
 
@@ -319,8 +331,6 @@ In this example we have two block-level container elements, each one with three
 
 We've included {{cssxref("padding")}} and {{cssxref("background-color")}} on the containers and their children, so that it is easier to see the effect the display values are having.
 
-> **Note:** We've not included any of the modern multi-keyword syntax, as support for that is still fairly limited.
-
 #### HTML
 
 ```html
@@ -342,12 +352,16 @@ We've included {{cssxref("padding")}} and {{cssxref("background-color")}} on the
     <option selected>block</option>
     <option>inline</option>
     <option>inline-block</option>
+    <option>inline flow-root</option>
     <option>none</option>
     <option>flex</option>
     <option>inline-flex</option>
+    <option>inline flex</option>
     <option>grid</option>
     <option>inline-grid</option>
+    <option>inline grid</option>
     <option>table</option>
+    <option>block table</option>
     <option>list-item</option>
   </select>
 </div>
@@ -405,7 +419,14 @@ updateDisplay();
 
 {{EmbedLiveSample('display_value_comparison','100%', 440)}}
 
-> **Note:** You can find more examples in the pages for each separate display data type, linked above.
+Note that some multi-keyword values are added for illustration which have the following equivalents:
+
+- `inline-block` = `inline flow-root`
+- `inline-flex` = `inline flex`
+- `inline-grid` = `inline grid`
+- `table` = `block table`
+
+You can find more examples in the pages for each separate display data type under [Grouped values](#grouped_values)
 
 ## Specifications