Update CSS width properrty (mdn#43111)

* update examples for background-attachment so you can see the effects of each value.

* update examples for background-attachment so you can see the effects of each value.

* update examples for background-attachment so you can see the effects of each value.

* width prop examples

* revert unrelated update

* anchor size example

* revert

* revert

* Apply suggestions from code review

Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>

* Update files/en-us/web/css/reference/properties/width/index.md

---------

Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>

Author: estelle

files/en-us/web/css/reference/properties/width/index.md

@@ -59,8 +59,6 @@ The specified value of `width` applies to the content area so long as its value
 /* <length> values */
 width: 300px;
 width: 25em;
-width: anchor-size(width);
-width: anchor-size(--my-anchor inline, 120%);
 
 /* <percentage> value */
 width: 75%;
@@ -69,10 +67,15 @@ width: 75%;
 width: max-content;
 width: min-content;
 width: fit-content;
-width: fit-content(20em);
 width: auto;
 width: stretch;
 
+/* function values */
+width: fit-content(20em);
+width: anchor-size(width);
+width: anchor-size(--my-anchor inline, 120%);
+width: calc-size(max-content, size / 2);
+
 /* Global values */
 width: inherit;
 width: initial;
@@ -95,8 +98,12 @@ width: unset;
   - : The intrinsic minimum width.
 - {{cssxref("fit-content")}}
   - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/Reference/Values/max-content), i.e., `min(max-content, max(min-content, stretch))`.
+- {{cssxref("anchor-size()")}}
+  - : Sets the width relative to a dimension of an anchor element. When defining the `width` of an anchor-positioned element, the first parameter defaults to the associated anchor's width. If applied to a non-anchor-positioned element, it sets the width to the fallback value. If no fallback is defined, the declaration is ignored.
+- {{cssxref("calc-size()")}}
+  - : Sets the width to a modified intrinsic size.
 - [`fit-content(<length-percentage>)`](/en-US/docs/Web/CSS/Reference/Values/fit-content_function)
-  - : Uses the fit-content formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, <length-percentage>))`.
+  - : Uses the fit-content formula with the available space replaced by the specified argument, clamping the width according to the formula `min(maximum size, max(minimum size, <length-percentage>))`.
 - `stretch`
   - : Sets the width of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the width of its [containing block](/en-US/docs/Web/CSS/Guides/Display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/Reference/Properties/box-sizing).
 
@@ -119,116 +126,183 @@ Ensure that elements set with a `width` aren't truncated and/or don't obscure ot
 
 ### Default width
 
+This example demonstrates basic usage and the default `auto` value.
+
+#### HTML
+
+We include two paragraphs; one with a class name.
+
+```html
+<p>The MDN community writes really great documentation.</p>
+<p class="has-width">The MDN community writes really great documentation.</p>
+```
+
+#### CSS
+
+We make all paragraphs have a gold background, explicitly setting the second paragraph's `width` to `auto`.
+
 ```css
-p.gold {
+p {
   background: gold;
 }
+p.has-width {
+  width: auto;
+}
 ```
 
+#### Results
+
+{{EmbedLiveSample("Default width", 600, 100)}}
+
+As `width` defaults to `auto`, both paragraphs are the same width.
+
+### Using length units
+
+This example demonstrates length width values.
+
+#### HTML
+
+We include two {{htmlelement("div")}} elements with some text.
+
 ```html
-<p class="gold">The MDN community writes really great documentation.</p>
+<div class="px_length">Width measured in px</div>
+<div class="em_length">Width measured in em</div>
 ```
 
-{{EmbedLiveSample('Default_width', '500px', '64px')}}
+#### CSS
 
-### Example using pixels and ems
+The `px_length` element is set to `200px` while the `em_length` element is set to be `20em` wide. Both elements also have different {{cssxref("background-color")}}, {{cssxref("color")}}, and {{cssxref("border")}} values to enable differentiating between the two when rendered.
 
 ```css
 .px_length {
   width: 200px;
+
   background-color: red;
   color: white;
   border: 1px solid black;
 }
 
 .em_length {
   width: 20em;
+
   background-color: white;
   color: red;
   border: 1px solid black;
 }
 ```
 
+#### Results
+
+{{EmbedLiveSample("Using length units", 600, 60)}}
+
+The `px_length` element will always be 200px wide. The rendered width of the `em_length` element depends on the font size.
+
+### Using percentages
+
+This example demonstrates using percentage values.
+
+#### HTML
+
+We include one {{htmlelement("div")}} element with some text.
+
 ```html
-<div class="px_length">Width measured in px</div>
-<div class="em_length">Width measured in em</div>
+<div class="percent">Width in percentage</div>
 ```
 
-{{EmbedLiveSample('Example using pixels and ems', '500px', '64px')}}
+#### CSS
 
-### Example with percentage
+We set the `width` of the element to be `20%` of the width of its parent container.
 
 ```css
 .percent {
   width: 20%;
+
   background-color: silver;
   border: 1px solid red;
 }
 ```
 
-```html
-<div class="percent">Width in percentage</div>
-```
+#### Results
 
-{{EmbedLiveSample('Example using percentage', '500px', '64px')}}
+{{EmbedLiveSample("Using percentages", 600, 60)}}
 
-### Example using "max-content"
+### Using intrinsic sizes
 
-```css
-p.max-green {
-  background: lightgreen;
-  width: max-content;
-}
-```
+This example compares `max-content` and `min-content`, and introduces `calc-size`.
+
+#### HTML
+
+We include three paragraphs with the same content; just their class names differ.
 
 ```html
 <p class="max-green">The MDN community writes really great documentation.</p>
+<p class="min-blue">The MDN community writes really great documentation.</p>
+<p class="min-pink">The MDN community writes really great documentation.</p>
 ```
 
-{{EmbedLiveSample('Example using "max-content"', '500px', '64px')}}
+#### CSS
 
-### Example using "min-content"
+We set one paragraph's `width` to `max-content`, the second to `min-content`, and the third to be twice the size of the `min-content` by using the `calc-size()` function. Each is given a different {{cssxref("background-color")}} and {{cssxref("border-style")}} to enable differentiating between the two.
 
 ```css
+p.max-green {
+  width: max-content;
+
+  background-color: lightgreen;
+  border-style: dotted;
+}
+
 p.min-blue {
-  background: lightblue;
   width: min-content;
+
+  background-color: lightblue;
+  border-style: dashed;
+}
+
+p.min-pink {
+  width: calc-size(min-content, size * 2);
+
+  background-color: pink;
+  border-style: solid;
 }
 ```
 
-```html
-<p class="min-blue">The MDN community writes really great documentation.</p>
+```css hidden
+@supports not (width: calc-size(min-content, size * 2)) {
+  body::after {
+    content: "Your browser doesn't support the calc-size() function yet.";
+    background-color: wheat;
+    display: block;
+    text-align: center;
+    padding: 1em;
+  }
+}
 ```
 
-{{EmbedLiveSample('Example using "min-content"', '500px', '155px')}}
+#### Results
+
+{{EmbedLiveSample("Using intrinsic sizes", 600, 230)}}
+
+The `max-content` example is as wide as the text. The `min-content` example is as wide as the widest word. The `calc-size()` example is set to be twice as wide as the `min-content`.
 
-### Stretch width to fill the containing block
+### Using the stretch keyword
+
+This example demonstrates the `stretch` value within a [flex](/en-US/docs/Web/CSS/Guides/Flexible_box_layout) container.
 
 #### HTML
 
+We include a parent container with two child elements.
+
 ```html
 <div class="parent">
   <div class="child">text</div>
-</div>
-
-<div class="parent">
   <div class="child stretch">stretch</div>
 </div>
 ```
 
 #### CSS
 
-```css hidden
-@supports not (width: stretch) {
-  .parent {
-    display: none !important;
-  }
-
-  body::after {
-    content: "Your browser doesn't support the `stretch` value yet.";
-  }
-}
-```
+We use the {{cssxref("display")}} property to make the parent a flex container, and set the second child's `width` the `stretch`.
 
 ```css
 .parent {
@@ -247,9 +321,83 @@ p.min-blue {
 }
 ```
 
+```css hidden
+@supports not (width: stretch) {
+  body::after {
+    content: "Your browser doesn't support the stretch value yet.";
+    background-color: wheat;
+    display: block;
+    text-align: center;
+    padding: 1em;
+  }
+}
+```
+
 #### Result
 
-{{EmbedLiveSample('Stretch width to fill the containing block', 'auto', 250)}}
+{{EmbedLiveSample("Using the stretch keyword", "auto", 100)}}
+
+By default, flex items are as wide as their content. The `stretch` value makes the element as wide as the available space allows, with the element's margin box otherwise clamped to the width of its containing block.
+
+### Using the anchor-size() function
+
+This example demonstrates using the `anchor-size()` function to define the width of an anchor-positioned element; we defined its width as a multiple of its anchor's height.
+
+#### HTML
+
+We specify two {{htmlelement("div")}} elements: one `anchor` element and one `infobox` element that we'll position relative to the anchor.
+
+```html
+<div class="anchor">⚓︎</div>
+
+<div class="infobox">
+  <p>Infobox.</p>
+</div>
+```
+
+#### CSS
+
+We declare the `anchor` `<div>` as an anchor element by giving it an {{cssxref("anchor-name")}}. The positioned element has its {{cssxref("position")}} property set to `absolute`, and is associated with the anchor element via its {{cssxref("position-anchor")}} property. We also set absolute {{cssxref("height")}} and {{cssxref("width")}} dimensions on the anchor and define the width of the anchor-positioned element to be the width of the anchor using the `anchor-size()` function as the value of the `width` property. As a bonus, we also use the `anchor-size()` function to define the infobox's {{cssxref("left")}} position, making the gap between the anchor and the infobox one quarter of the height of the anchor.
+
+```css hidden
+.anchor {
+  anchor-name: --my-anchor;
+  width: 120px;
+  height: 60px;
+
+  font-size: 2rem;
+  background-color: lightpink;
+  text-align: center;
+  align-content: center;
+  outline: 1px solid black;
+}
+
+.infobox {
+  position-anchor: --my-anchor;
+  position: absolute;
+  position-area: right;
+  width: anchor-size(width);
+
+  left: calc( anchor-size(height) / 4 )
+
+  align-content: center;
+  color: darkblue;
+  background-color: azure;
+  outline: 1px solid #dddddd;
+}
+```
+
+```css hidden
+body {
+  padding: 5em;
+}
+```
+
+#### Results
+
+{{EmbedLiveSample("Using the anchor-size() function", "auto", 200)}}
+
+Note how the infobox's width is always the same as the anchor element's width.
 
 ## Specifications
 
@@ -265,7 +413,8 @@ p.min-blue {
 - {{cssxref("box-sizing")}}
 - {{cssxref("min-width")}}, {{cssxref("max-width")}}
 - {{cssxref("block-size")}}, {{cssxref("inline-size")}}
-- {{cssxref("anchor-size()")}}
 - SVG {{SVGAttr("width")}} attribute
 - [Introduction to the CSS box model](/en-US/docs/Web/CSS/Guides/Box_model/Introduction) guide
 - [CSS box model](/en-US/docs/Web/CSS/Guides/Box_model) module
+- [CSS anchor positioning](/en-US/docs/Web/CSS/Guides/Anchor_positioning) module
+- [CSS values and units](/en-US/docs/Web/CSS/Guides/Values_and_units) module