wpaccessibility · rianrietveld · Nov 26, 2025 · Nov 26, 2025
diff --git a/docs/topics/code/accessible-name/index.md b/docs/topics/code/accessible-name/index.md
@@ -20,7 +20,7 @@ A proper accessible name for HTML elements is essential for screen reader users
 
 Abdulqudus Abubakre gives an excellent, detailed writeup of the accessible name [Understanding Accessible Names in HTML](https://dev.to/ibn_abubakre/understanding-accessible-names-in-html-562).
 
-{: .info }
+{: .callout .info }
 Note: An `aria-label` attribute on a link or a button overrides all textual content within.   
 For example, the accessible name of the button `<button aria-label="Close">Open</button>` is "Close".
 
@@ -59,7 +59,7 @@ The accessibility tree of Chrome shows the following relevant information: the a
 - Focused: true
 - Expanded: false
 
-{: .info }
+{: .callout .info }
 In this example the accessible name is taken from "Contents". The other options are not specified. An accessible name can be overwritten. Here the different steps for defining an accessible name are shown and sorted in order of the computation. A value for the `aria-label` will overwrite the Contents value.
 
 ![Screenshot accessible name menu in Chrome]({{site.baseurl}}/assets/images/accessible-name-button.png)

diff --git a/docs/topics/content/links/link-text.md b/docs/topics/content/links/link-text.md
@@ -11,7 +11,7 @@ nav_order: 2
 This content will be reviewed, restructured and expanded.
 Related issue on [GitHub #110 Topic Write a meaningful link text](https://github.com/wpaccessibility/wp-a11y-docs/issues/110).  
 
-{: .tip }
+{: .callout .tip }
 **Rule of thumb**: a link text should describe the resource that it links to, so that when the text is read out of context the user will still know what to expect. A link is a promise, not a surprise.
 
 Link text should stand on its own. Some assistive software scans a page for links and presents them to the user as a simple list. In these situations, all the links will be read out of context. So it is important the text used in a link is descriptive and meaningful.
@@ -34,11 +34,11 @@ With these types of links, users have to read the whole sentence to understand t
 <figcaption>Useless, non-descriptive link text in the Apple VoiceOver link list.</figcaption>
 </figure>
 
-{: .dont}
+{: .callout .dont }
 Poor qualify (non-descriptive) link texts:
 If you are interested in our work, [click here](#dummy-link) to subscribe to our newsletter. You can [download](#dummy-link) the manual of the espresso machine, or contact us for more [info](#dummy-link).
 
-{: .do }
+{: .callout .do }
 Helpful (descriptive) link texts:
 [Subscribe to our newsletter](#dummy-link) if you are interested in our work. You can download the [manual as a PDF]((#dummy-link) ) of the espresso machine, or [contact us](#dummy-link) for more info.
 
@@ -61,11 +61,11 @@ Sequences of all capital letters are harder to read for people with dyslexia, sc
 
 Some URLs are highly readable, such as “wordpress.org”. Others are almost impossible to parse as language. In most cases, you should avoid using a URL as the visible link text. If you are explicitly referring to a web address, keep it short: [wordpress.org](https://www.wordpress.org) instead of [https://www.wordpress.org](https://www.wordpress.org).
 
-{: .dont}
+{: .callout .dont }
 Poor quality (non-descriptive) link texts:
 If you are interested in our work, [click here](#dummy-link) to subscribe to our newsletter. You can [download](#dummy-link) the manual of the espresso machine, or contact us for more [info](#dummy-link).
 
-{: .do}
+{: .callout .do }
 Helpful (descriptive) link texts:
 [Subscribe to our newsletter]((#dummy-link)) if you are interested in our work. You can download the [manual as a PDF]((#dummy-link)) of the espresso machine, or [contact us](#dummy-link) for more info.
 

diff --git a/docs/topics/forms/descriptions/connect-description.md b/docs/topics/forms/descriptions/connect-description.md
@@ -49,7 +49,7 @@ For the documentation about descriptions in fieldsets read [Description with a f
 
 ## Examples
 
-{: .dont }
+{: .callout .dont }
 No connection between a form field and its description.
 
 ```html
@@ -66,7 +66,7 @@ No connection between a form field and its description.
 />
 ```
 
-{: .do }
+{: .callout .do }
 Connection between a form field and its description.
 
 ```html

diff --git a/docs/topics/forms/descriptions/location-description.md b/docs/topics/forms/descriptions/location-description.md
@@ -21,7 +21,7 @@ Also check the [description decision tree]({{site.baseurl}}/docs/topics/forms/de
 
 ## Examples
 
-{: .do }
+{: .callout .do }
 Place descriptions in a consistent location, preferably between the label and the form field.
 
 ```html
@@ -38,7 +38,7 @@ Place descriptions in a consistent location, preferably between the label and th
 />
 ```
 
-{: .do }
+{: .callout .do }
 Place all descriptions, including error messages, in a consistent location, preferably between the label and the form field.
 
 ```html
@@ -59,7 +59,7 @@ Place all descriptions, including error messages, in a consistent location, pref
 ```
 
 
-{: .dont }
+{: .callout .dont }
 Avoid placing the description below the form field.
 
 ```html
@@ -78,7 +78,7 @@ Avoid placing the description below the form field.
 ```
 
 
-{: .dont }
+{: .callout .dont }
 Do not place a description above the form field and an error message below it. Be consistent in the location of descriptions.
 
 ```html

diff --git a/docs/topics/forms/fieldsets/fieldset-descriptions.md b/docs/topics/forms/fieldsets/fieldset-descriptions.md
@@ -43,7 +43,7 @@ In HTML, simplified
 
 ## Examples
 
-{: .do }
+{: .callout .do }
 Connect a description to the form field, using aria-describedby.
 
 ```html

diff --git a/docs/topics/forms/input-label/accessible-name.md b/docs/topics/forms/input-label/accessible-name.md
@@ -110,7 +110,7 @@ Visual text or equivalent, like a search icon, should always be visible, so sigh
 
 If you must hide a label or control from vision, use the CSS class [`.screen-reader-text`](https://make.wordpress.org/accessibility/handbook/best-practices/markup/the-css-class-screen-reader-text/) or equivalent.
 
-{: .dont }
+{: .callout .dont }
 Don't use the CSS `display: none`, `visibility: hidden` or the HTML attribute `hidden` on a label, as that also removes the element, and its accessible name, from the accessibility tree.
 
 ```html
@@ -127,7 +127,7 @@ Don't use the CSS `display: none`, `visibility: hidden` or the HTML attribute `h
 <button>Search</button>
 ```
 
-{: .do }
+{: .callout .do }
 Always add a visible hint about how to fill out the form field.  
 <label for="search-text" class="screen-reader-text">Search this website</label>
 <input type="text" name="s" id="search-text">

diff --git a/docs/topics/forms/input-label/text-only.md b/docs/topics/forms/input-label/text-only.md
@@ -40,7 +40,7 @@ The populair [WordPress form plugin Contact Form 7](https://wordpress.org/plugin
 
 ## Examples
 
-{: .do }
+{: .callout .do }
 Place the link to the terms of delivery outside and above the label.  
 [The terms of delivery](#).  
 <input id="alv3" type="checkbox"/>
@@ -56,7 +56,7 @@ Place the link to the terms of delivery outside and above the label.
 
 Note that the reading order is also meaningful: first the link to the terms and after that the checkbox to agree with them.
 
-{: .dont }
+{: .callout .dont }
 Place the link to the terms of delivery inside the label.  
 <input id="alv4" type="checkbox"/>
 <label for="alv4">I agree with [the terms of delivery](#)</label>