From ceabb2114ba2f7b9f61dd6e3dc1a8da3f0aa4e7d Mon Sep 17 00:00:00 2001
From: Dawid Nowak <dawidrobertnowak@gmail.com>
Date: Wed, 28 Oct 2026 11:52:50 +0100
Subject: [PATCH] Describe example images with alt text

Replace the generic "example" alt text of the example images on the
Background, Border, Debug area, Rounded corners, Shadow, Text basics and
Text style pages with a description of what each image shows.

The example image styling was tied to img[alt=example]; the images now
carry an example class and the stylesheet matches both.
---
 .../.vitepress/theme/VitepressAdjustments.css |  9 +++--
 docs/api-reference/background.md              |  6 +--
 docs/api-reference/border.md                  | 18 ++++-----
 docs/api-reference/debug-area.md              |  2 +-
 docs/api-reference/rounded-corners.md         |  8 ++--
 docs/api-reference/shadow.md                  | 14 +++----
 docs/api-reference/text/basics.md             |  6 +--
 docs/api-reference/text/text-style.md         | 38 +++++++++----------
 8 files changed, 52 insertions(+), 49 deletions(-)

diff --git a/docs/.vitepress/theme/VitepressAdjustments.css b/docs/.vitepress/theme/VitepressAdjustments.css
index b63979f..c6cb316 100644
--- a/docs/.vitepress/theme/VitepressAdjustments.css
+++ b/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;
diff --git a/docs/api-reference/background.md b/docs/api-reference/background.md
index 7a877da..94c0d0d 100644
--- a/docs/api-reference/background.md
+++ b/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)
\ No newline at end of file
+![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}
\ No newline at end of file
diff --git a/docs/api-reference/border.md b/docs/api-reference/border.md
index 77cf5f9..a81f574 100644
--- a/docs/api-reference/border.md
+++ b/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)
\ No newline at end of file
+![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}
\ No newline at end of file
diff --git a/docs/api-reference/debug-area.md b/docs/api-reference/debug-area.md
index 58dcd58..228a1d9 100644
--- a/docs/api-reference/debug-area.md
+++ b/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}
diff --git a/docs/api-reference/rounded-corners.md b/docs/api-reference/rounded-corners.md
index cff2bdb..2053aea 100644
--- a/docs/api-reference/rounded-corners.md
+++ b/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}
diff --git a/docs/api-reference/shadow.md b/docs/api-reference/shadow.md
index cbe4505..922fa56 100644
--- a/docs/api-reference/shadow.md
+++ b/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)
\ No newline at end of file
+![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}
\ No newline at end of file
diff --git a/docs/api-reference/text/basics.md b/docs/api-reference/text/basics.md
index ad4c0db..9592c7b 100644
--- a/docs/api-reference/text/basics.md
+++ b/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
diff --git a/docs/api-reference/text/text-style.md b/docs/api-reference/text/text-style.md
index be35fa1..914e7c9 100644
--- a/docs/api-reference/text/text-style.md
+++ b/docs/api-reference/text/text-style.md
@@ -25,7 +25,7 @@ It's worth noting that different fonts may render text with different visual siz
 });
 ```
 
-![example](/api-reference/text-font-size.webp)
+![Three lines of the same sentence at 16, 24 and 36 points, each one clearly larger than the last.](/api-reference/text-font-size.webp){.example}
 
 
 ## Font Family
@@ -49,7 +49,7 @@ Examples of font families include Lato, Noto Serif and JetBrains Mono. Fonts oth
 });
 ```
 
-![example](/api-reference/text-font-family.webp)
+![The same sentence in three fonts: the default sans-serif Lato, Noto Serif with serifs, and the monospaced JetBrains Mono.](/api-reference/text-font-family.webp){.example}
 
 
 ## Font Fallback
@@ -64,7 +64,7 @@ container
     .FontFamily("Lato", "Noto Sans Arabic");
 ```
 
-![example](/api-reference/text-font-fallback.webp)
+![An English sentence in Lato ends with the Arabic word البرمجة, which is drawn correctly by the fallback font instead of missing-glyph boxes.](/api-reference/text-font-fallback.webp){.example}
 
 It's also useful for displaying emojis, which are not universally supported by all fonts.
 
@@ -74,7 +74,7 @@ container
     .FontFamily("Lato", "Noto Emoji");
 ```
 
-![example](/api-reference/text-font-fallback-emoji.webp)
+![Five emojis drawn inline with the text by the fallback font; they appear as black-and-white outlines, not in colour.](/api-reference/text-font-fallback-emoji.webp){.example}
 
 ::: tip
 Rather than repeating the fallback list on every text element, configure it once in the [default text style](/api-reference/default-text-style) of the page or document.
@@ -100,7 +100,7 @@ It also influences the default color of text decorations, such as underlines.
 });
 ```
 
-![example](/api-reference/text-font-color.webp)
+![Only the words "red", "green" and "blue" take their colours; the rest of the sentence stays black.](/api-reference/text-font-color.webp){.example}
 
 
 ## Background Color
@@ -118,7 +118,7 @@ This color fills the area behind the text or other elements, enhancing contrast
 });
 ```
 
-![example](/api-reference/text-font-background.webp)
+![Only the bold word "algorithm" has a pale yellow background that hugs the word; the rest of the sentence wraps to a second line without a background.](/api-reference/text-font-background.webp){.example}
 
 
 ## Font Weight
@@ -156,7 +156,7 @@ Please note that not all fonts support every weight. If the specified weight isn
 });
 ```
 
-![example](/api-reference/text-font-weight.webp)
+![Bold, normal, light and thin weights in one sentence; the thin word is barely visible.](/api-reference/text-font-weight.webp){.example}
 
 :::warning
 QuestPDF does not currently support fonts with variable weights.
@@ -178,7 +178,7 @@ Commonly used for emphasis or to distinguish specific words.
 });
 ```
 
-![example](/api-reference/text-font-italic.webp)
+![The word "important" is slanted while the rest of the sentence stays upright.](/api-reference/text-font-italic.webp){.example}
 
 
 ## Decorations
@@ -205,7 +205,7 @@ It is also possible to customize the decoration position:
 });
 ```
 
-![example](/api-reference/text-decoration-types.webp)
+![A red line below "underline", a green line through "strikethrough", and a blue line above "overline", as far above the tallest letters as the underline is below the baseline.](/api-reference/text-decoration-types.webp){.example}
 
 ### Styles
 
@@ -233,7 +233,7 @@ It is also possible to customize the decoration line style:
 });
 ```
 
-![example](/api-reference/text-decoration-styles.webp)
+![Five underline styles under coloured words: solid, double, wavy, dotted and dashed.](/api-reference/text-decoration-styles.webp){.example}
 
 ### Styling
 
@@ -255,7 +255,7 @@ However, these properties can be customized.
 });
 ```
 
-![example](/api-reference/text-decoration-advanced.webp)
+![A red wavy line under the misspelled word "seriuos", in a different colour from the black text.](/api-reference/text-decoration-advanced.webp){.example}
 
 
 ## Subscript
@@ -272,7 +272,7 @@ Commonly used for chemical formulas or mathematical notations
 });
 ```
 
-![example](/api-reference/text-subscript.webp)
+![The 2 in H2O is smaller and sits below the baseline.](/api-reference/text-subscript.webp){.example}
 
 
 ## Superscript
@@ -289,7 +289,7 @@ Typically used for exponents, footnotes, or ordinal indicators
 });
 ```
 
-![example](/api-reference/text-superscript.webp)
+![The 2 in E = mc2 is smaller and raised above the baseline.](/api-reference/text-superscript.webp){.example}
 
 
 ## Line Height
@@ -318,7 +318,7 @@ The added space is proportional to the text size.
 });
 ```
 
-![example](/api-reference/text-line-height.webp)
+![The same paragraph with three increasing line heights: in the tightest one the lines overlap, and in the widest one there is a full empty line between them.](/api-reference/text-line-height.webp){.example}
 
 
 ## Letter Spacing
@@ -348,7 +348,7 @@ The adjustment is proportional to the text size.
 });
 ```
 
-![example](/api-reference/text-letter-spacing.webp)
+![The same sentence with tighter, normal and wider letter spacing: tight letters touch each other, while wide spacing leaves a visible gap between every letter.](/api-reference/text-letter-spacing.webp){.example}
 
 
 ## Word Spacing
@@ -376,7 +376,7 @@ The adjustment is proportional to the text size.
 });
 ```
 
-![example](/api-reference/text-word-spacing.webp)
+![Negative word spacing removes the gaps between words, normal spacing keeps them, and positive spacing widens them.](/api-reference/text-word-spacing.webp){.example}
 
 
 ## Hyphenation
@@ -404,7 +404,7 @@ A soft hyphen is invisible and is rendered only when the line actually breaks at
 });
 ```
 
-![example](/api-reference/text-hyphenation.webp)
+![Without soft hyphens the long German words move to the next line whole; with them, the words break at the soft hyphens and a hyphen is drawn at each break.](/api-reference/text-hyphenation.webp){.example}
 
 
 ## Font Features
@@ -461,7 +461,7 @@ Let's analyze the `StandardLigatures` font feature, which replaces specific pair
 });
 ```
 
-![example](/api-reference/text-font-features.webp)
+![Without ligatures, "fl" and "fi" are separate letters; with ligatures, each pair is joined into a single glyph.](/api-reference/text-font-features.webp){.example}
 
 
 ## Break Anywhere
@@ -488,4 +488,4 @@ Without this setting, a word longer than the line is still split where it overfl
 });
 ```
 
-![example](/api-reference/text-break-anywhere.webp)
\ No newline at end of file
+![By default the URL breaks only after hyphens, leaving uneven lines; with BreakAnywhere every line is filled and words are split at any character, such as "api-ref" / "erence".](/api-reference/text-break-anywhere.webp){.example}
\ No newline at end of file