Describe example images with alt text

docs/.vitepress/theme/VitepressAdjustments.css

@@ -118,15 +118,18 @@ body {
     }
 }
 
-html:not(.dark) .VPDoc img[alt=example] {
+html:not(.dark) .VPDoc img[alt=example],
+html:not(.dark) .VPDoc img.example {
     border: 1px solid #888;
 }
 
-html.dark .VPDoc img[alt=example] {
+html.dark .VPDoc img[alt=example],
+html.dark .VPDoc img.example {
     opacity: 0.75;
 }
 
-.VPDoc img[alt=example] {
+.VPDoc img[alt=example],
+.VPDoc img.example {
     box-shadow: 0 13px 27px -5px rgb(50 50 93 / 15%), 0 8px 16px -8px rgb(0 0 0 / 10%), 0 -6px 16px -6px rgb(0 0 0 / 5%);
     margin-bottom: 16px;
     border-radius: 8px;

docs/api-reference/background.md

@@ -52,7 +52,7 @@ container
     });
 ```
 
-![example](/api-reference/background-solid.webp)
+![Fourteen equal-width stripes, each filled edge to edge with one shade of the LightBlue palette: from dark to light (Darken4 to Lighten5), then the four Accent shades.](/api-reference/background-solid.webp){.example}
 
 
 ## Gradient
@@ -80,7 +80,7 @@ The first argument is the angle in degrees, and the second argument is an array
 });
 ```
 
-![example](/api-reference/background-gradient.webp)
+![Three gradients showing the angle convention: 0° runs from left (red) to right (blue), 45° from the top-left corner (green) to the bottom-right corner (yellow), and 90° from top (yellow) to bottom (orange).](/api-reference/background-gradient.webp){.example}
 
 
 ## Rounded Corners
@@ -99,4 +99,4 @@ container
     .Text("Content with rounded corners");
 ```
 
-![example](/api-reference/background-rounded-corners.webp)
+![The grey background follows the rounded corners, and the box is only as wide as its padded text.](/api-reference/background-rounded-corners.webp){.example}

docs/api-reference/border.md

@@ -16,7 +16,7 @@ container
     });
 ```
 
-![example](/api-reference/border-simple.webp)
+![A dark blue border surrounds the padded light blue box, and the wrapped tip text stays inside it.](/api-reference/border-simple.webp){.example}
 
 
 ## Thickness
@@ -68,7 +68,7 @@ container.Border(1, Unit.Millimetre);
 });
 ```
 
-![example](/api-reference/border-thickness-consistent.webp)
+![Three boxes with 1, 3 and 9 point borders: the thicker the border, the more it grows outward as well as inward, so the "Bold" box looks larger than the "Thin" one.](/api-reference/border-thickness-consistent.webp){.example}
 
 
 ### Various thickness
@@ -83,7 +83,7 @@ container
     .Text("Sample text");
 ```
 
-![example](/api-reference/border-thickness-various.webp)
+![Each side has its own thickness: the left edge is the thinnest and the bottom edge the thickest.](/api-reference/border-thickness-various.webp){.example}
 
 
 ## Solid Color
@@ -116,7 +116,7 @@ In the vast majority of cases, borders are applied with a solid color.
 });
 ```
 
-![example](/api-reference/border-color-solid.webp)
+![Three boxes with red, green and blue borders; each shows its colour as a hex code (#F44336, #4CAF50, #2196F3) in the same colour.](/api-reference/border-color-solid.webp){.example}
 
 
 ## Gradient
@@ -153,7 +153,7 @@ The first argument is the angle in degrees, and the second argument is an array
 });
 ```
 
-![example](/api-reference/border-color-gradient.webp)
+![Three gradient borders: 0° runs from red on the left to blue on the right, 45° from green at the top-left to yellow at the bottom-right, and 90° from yellow at the top to orange at the bottom, following the rounded corners.](/api-reference/border-color-gradient.webp){.example}
 
 
 ## Alignment
@@ -200,7 +200,7 @@ However, if the border has rounded corners, the alignment is set to inside by de
 });
 ```
 
-![example](/api-reference/border-alignment.webp)
+![Four boxes with the same content: "Border Inside" keeps the size of the box without a border, "Border Middle" is larger because the border straddles the edge, and "Border Outside" is the largest because the whole border lies outside it.](/api-reference/border-alignment.webp){.example}
 
 
 ## Examples
@@ -222,7 +222,7 @@ container
     .Text("Border with rounded corners"); 
 ```
 
-![example](/api-reference/border-rounded-corners-1.webp)
+![A thin black border follows the rounded corners of the grey box.](/api-reference/border-rounded-corners-1.webp){.example}
 
 
 ### Multiple borders
@@ -247,7 +247,7 @@ container
     .Text("Content");
 ```
 
-![example](/api-reference/border-multiple.webp)
+![Two borders on one box: green bars on the left and right run the full height, and the blue bars on the top and bottom sit between them, inside the first border.](/api-reference/border-multiple.webp){.example}
 
 
 ### Advanced style
@@ -272,4 +272,4 @@ container
     });
 ```
 
-![example](/api-reference/border-rounded-corners-2.webp)
+![A status card: a thick green bar on the left edge, rounded together with the light green box, next to the bold title "Completed" and the line "The invoice has been paid in full."](/api-reference/border-rounded-corners-2.webp){.example}

docs/api-reference/debug-area.md

@@ -55,4 +55,4 @@ container
     });
 ```
 
-![example](/api-reference/debug-area.webp)
+![DebugArea covers the whole area it wraps with a translucent blue fill and a thin border, including the space the content doesn't use, and shows the label "Grid example" at the top centre.](/api-reference/debug-area.webp){.example}

docs/api-reference/rounded-corners.md

@@ -26,7 +26,7 @@ container
     .Text("Container with consistently rounded corners");
 ```
 
-![example](/api-reference/rounded-corners-consistent.webp)
+![All four corners are rounded with the same radius; the thin black border and the light grey background both follow the curve.](/api-reference/rounded-corners-consistent.webp){.example}
 
 
 ## Various Corner Radius
@@ -45,7 +45,7 @@ container
     .Text("Container with rounded corners");
 ```
 
-![example](/api-reference/rounded-corners-various.webp)
+![Each corner has its own radius, from a barely rounded top-left corner to a wide curve at the bottom-left; the border and the background follow every corner.](/api-reference/rounded-corners-various.webp){.example}
 
 
 ## Image Example
@@ -58,7 +58,7 @@ container
     .Image("Resources/landscape.jpg");
 ```
 
-![example](/api-reference/rounded-corners-image.webp)
+![The photo is clipped to rounded corners, so its edges curve instead of meeting at sharp corners.](/api-reference/rounded-corners-image.webp){.example}
 
 
 ## Complex Example
@@ -112,4 +112,4 @@ container
     });
 ```
 
-![example](/api-reference/rounded-corners-complex.webp)
+![A table with a header row and five rows inside a rounded black border: the outer corners of the header and the last row are clipped to the curve, while the inner cell borders stay straight.](/api-reference/rounded-corners-complex.webp){.example}

docs/api-reference/shadow.md

@@ -18,7 +18,7 @@ container
     .Text("Important content");
 ```
 
-![example](/api-reference/shadow-simple.webp)
+![A soft grey shadow falls below and to the right of the bordered box.](/api-reference/shadow-simple.webp){.example}
 
 
 ## Blur
@@ -52,7 +52,7 @@ Use with caution, especially in large documents or when rendering complex shadow
 });
 ```
 
-![example](/api-reference/shadow-blur.webp)
+![Three squares with increasing blur: the shadow gets wider and softer, spreading evenly on all sides.](/api-reference/shadow-blur.webp){.example}
 
 
 ## Spread
@@ -81,7 +81,7 @@ Positive values cause the shadow to expand, negative values cause it to contract
 });
 ```
 
-![example](/api-reference/shadow-spread.webp)
+![Three squares with increasing spread: from a faint halo to a wide, darker band around the square.](/api-reference/shadow-spread.webp){.example}
 
 
 ## Offset X
@@ -110,7 +110,7 @@ Positive values move the shadow to the right, negative values move it to the lef
 });
 ```
 
-![example](/api-reference/shadow-offset-x.webp)
+![A negative offset moves the shadow to the left, zero keeps it centred, and a positive offset moves it to the right.](/api-reference/shadow-offset-x.webp){.example}
 
 
 ## Offset Y
@@ -139,7 +139,7 @@ Positive values move the shadow downward, negative values move it upward.
 });
 ```
 
-![example](/api-reference/shadow-offset-y.webp)
+![A negative offset moves the shadow up, zero keeps it centred, and a positive offset moves it down.](/api-reference/shadow-offset-y.webp){.example}
 
 
 ## Color
@@ -172,7 +172,7 @@ Gets or sets the color of the shadow.
 });
 ```
 
-![example](/api-reference/shadow-color.webp)
+![Red, green and blue glows around three white squares: the shadow takes the given colour.](/api-reference/shadow-color.webp){.example}
 
 
 ## Without Blur (Fast)
@@ -213,4 +213,4 @@ This approach is faster and results in significantly smaller file sizes, making
 });
 ```
 
-![example](/api-reference/shadow-no-blur.webp)
+![Without blur the shadow is a solid grey copy of the shape, offset down and to the right; on the second square it follows the rounded corners.](/api-reference/shadow-no-blur.webp){.example}

docs/api-reference/text/basics.md

@@ -9,7 +9,7 @@ container
     .Text("Hello, World!");
 ```
 
-![example](/api-reference/text-basic.webp)
+![Without any styling, the text uses the default style: "Sample text" in regular black letters.](/api-reference/text-basic.webp){.example}
 
 ## Customization
 
@@ -42,7 +42,7 @@ The `Text` method returns a descriptor that allows further customization of the
 });
 ```
 
-![example](/api-reference/text-basic-descriptor.webp)
+![Three grey boxes: the first text is blue, the second is bold and underlined, and the third is smaller and centred in its box.](/api-reference/text-basic-descriptor.webp){.example}
 
 
 ## Rich text formatting
@@ -65,7 +65,7 @@ container
     });
 ```
 
-![example](/api-reference/text-rich.webp)
+![One sentence with mixed formatting: "chemical formula" is underlined, "sulfuric acid" has a yellow highlight, and the 2 and 4 in H2SO4 are subscript.](/api-reference/text-rich.webp){.example}
 
 
 ## Typography pattern