Merge pull request #240 from wpaccessibility/235-fix-code-errors

Fixes issues: #235 and #234

Author: rianrietveld

_posts/2025-08-16-accessible-error-messages-in-forms.md

@@ -9,12 +9,12 @@ excerpt: "When you put care into preventing errors and clearly indicating when s
 date: 2025-08-16
 ---
 
-When you put care into preventing errors and clearly indicating when something goes wrong, users are much more likely to successfully submit a form.
-{: .lead }
+## Summary
 
-In this post, we’ll walk step-by-step through how to prevent errors, indicate them clearly, and offer help with error messages in forms for different types of users.
+{: .lead }
+When you put care into preventing errors and clearly indicating when something goes wrong, users are much more likely to successfully submit a form. In this post, we’ll walk step-by-step through how to prevent errors, indicate them clearly, and offer help with error messages in forms for different types of users.
 
-When designing a form, ask yourself the following questions:
+## When designing a form, ask yourself the following questions
 
 * What do I really need to know?
 * How will I ask for this information?
@@ -28,7 +28,7 @@ When designing a form, ask yourself the following questions:
 
 No one enjoys filling out forms, and all the help you can give is useful. Keep that goal in mind. You want to learn something from your user, or your user wants to tell you something. Make that process as easy as possible.
 
-## What do I really need to know?
+### What do I really need to know?
 
 Handling errors starts with the questions you ask. Some questions are difficult to answer. Is it really essential to know whether someone is male or female? Do you only want to contact them by phone? What if a user's answer to a question isn't an available option, or they don't want to answer a question? They may just give up.
 
@@ -40,7 +40,7 @@ Be clear about why you need sensitive personal information, such as an identific
 In the Netherlands there are strict rules about [when to ask for a citizen service number](https://www.rijksoverheid.nl/onderwerpen/privacy-en-persoonsgegevens/vraag-en-antwoord/welke-organisaties-mogen-mijn-burgerservicenummer-bsn-gebruiken#:~:text=Alle%20overheidsorganisaties%20mogen%20gebruik%20maken%20van%20uw%20burgerservicenummer%20(BSN)). Canada has similar rules governing [how you can request Personally Identifying Information (PII)](https://www.priv.gc.ca/en/privacy-topics/privacy-laws-in-canada/the-personal-information-protection-and-electronic-documents-act-pipeda/p_principle/).
 
 
-## How will I ask for this information?
+### How will I ask for this information?
 
 The input mechanism you use to ask for information has a profound impact on your users. Should you design new custom input fields or use recognizable, familiar patterns? Please don’t reinvent the web for something as essential as form fields. As Heydon Pickering explains in his talk [Get Your Priorities Straight](https://www.youtube.com/watch?v=ediHVy0869c): “Real people aren't looking to be delighted. People want to get the task done and get on with their lives".
 
@@ -59,7 +59,7 @@ Don't force the user to enter information (like an email address) more than once
 {: .callout  .info }
 This success criterion was added in [WCAG 2.2: 3.3.7 Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html).
 
-## What information can I provide in advance to help the user?
+### What information can I provide in advance to help the user?
 
 We’ve all been there: you enter a new password, click submit, and *then* you’re told what the password requirements are. You yell at the screen: “Why didn't you tell me that before?”.
 
@@ -68,19 +68,19 @@ The blog post [*Blind people don't visit my website*](https://www.a11y-collectiv
 
 Don’t make users guess — offer clear help in plain language, at the right moment. Tell users in advance which documents they'll need, and which fields are or aren't required. Add descriptions to fields where necessary.
 
-## How do I show which fields are required?
+### How do I show which fields are required?
 
 If you only ask what's really needed, all fields could technically be required — but that’s not always the case. Different types of forms have different needs. For example, if you're creating content in the admin of a website, all of the content fields you might use need to be available; but most of them won't be required.
 
-### What’s the best way to indicate required?
+#### What’s the best way to indicate required?
 
 Many websites use indicators like “required”, “optional”, or an asterisk (\*). But which is clearest?
 
 Do user research for your language. For example in Dutch the word "optioneel" (optional) is hard to understand for people with low literacy, and "niet verplicht" (not required) is a better choice. This may be different for your language.
 
 Prefer **“required”** over an asterisk, because an asterisk assumes prior knowledge of the meaning of that icon. If you do use an asterisk, explain its meaning above the form.
 
-### Should I mark required or non-required fields?
+#### Should I mark required or non-required fields?
 
 Which is better? Indicate required or non-required fields? It depends. Your choice should be based on the form’s function, your CMS or plugin, and user research.
 
@@ -93,7 +93,7 @@ For example: "Please complete all fields. If a field is not required, it will be
 
 Whatever you choose, be consistent within the form and across all forms on your website. Inform users above the form how field requirements are indicated.
 
-## When should I check for errors?
+### When should I check for errors?
 
 Websites commonly check for errors while typing, after the focus moves out of a field, or after the form is submitted. Which approach is most user-friendly?
 
@@ -104,7 +104,7 @@ That leaves two options: check after leaving a field, or after submission. These
 {: .callout  .warning }
 HTML5 form validation is not accessible at this moment (in 2025). The W3C summarizes the options in [Validating Input ](https://www.w3.org/WAI/tutorials/forms/validation/). "If your web browser supports HTML5, it will not allow you to submit the form without entering text into the input field. Instead, it will display a message that is generated by the web browser itself".  Write custom error messages and provide server side generated error messages. The W3C explains the options in [Validating Input ](https://www.w3.org/WAI/tutorials/forms/validation/).
 
-## How do I indicate that an answer is incomplete or filled out incorrectly?
+### How do I indicate that an answer is incomplete or filled out incorrectly?
 
 Use more than color alone to indicate errors. A user with visual impairments or color blindness may not notice a red outline. Color is helpful but always include an error message in text too.
 
@@ -113,7 +113,7 @@ Use more than color alone to indicate errors. A user with visual impairments or
 * Write out the error in text above the form field.
 * Add a summary of all errors above the form to help the user quickly see what needs to be corrected.
 
-## What makes a helpful error message?
+### What makes a helpful error message?
 
 Messages like “This field is required” or “Invalid value” don’t offer much help. Write clear error messages that explain what’s missing or needs changing.
 
@@ -124,7 +124,7 @@ Messages like “This field is required” or “Invalid value” don’t offer
 
 This is far more helpful than a generic message.
 
-## How do I confirm a form was successfully submitted?
+### How do I confirm a form was successfully submitted?
 
 You click "Send" and… nothing happens. Or you're redirected to the homepage. Was the form actually sent? How do you know?
 
@@ -134,7 +134,7 @@ Give users clear confirmation that their form has been submitted and what will h
 A confirmation text could be:  
 Thank you for your registration for our workshop "Knitting socks". A confirmation email has been sent to [email protected] with the time and location of the workshop. If you haven't received an email? [Please contact us](#).
 
-## How can I offer help if a user gets stuck?
+### How can I offer help if a user gets stuck?
 
 If a user gets stuck filling out a complex form, they need to be able to easily request help.
 
@@ -146,7 +146,7 @@ Always offer multiple ways to get in touch on your contact page — not everyone
 A help text could be:  
 Do you need help filling out this form or do you have questions? [Please contact us](#).
 
-## Summary
+## Conclusion
 
 Help your users as much as possible when filling out a form. Don't ask unnecessary questions just to collect for your statistics. Use standard input form fields wherever possible. Make it clear what is required and how to fill out a field. Use clear, timely error messages. And make sure it’s easy to ask for help when needed.
 

_posts/2025-08-27-offer-multiple-ways-to-contact-you.md

@@ -8,10 +8,11 @@ parent: Blog
 excerpt: "It’s better to offer multiple ways to get in touch, so people can choose what suits them. Think about your visitors first, not just what’s easiest for you."
 date: 2025-08-27
 ---
-You want to reach out to customer service, and they say  *“Send us a WhatsApp message.”* What if you don’t use WhatsApp, or cannot make a phone call, or use the chatbox? 
-{: .callout  .lead }
-By offering multiple contact options, you make sure every customer has a way to connect.
-{: .callout  .lead }
+
+## Summary
+
+{: .lead }
+You want to reach out to customer service, and they say  *“Send us a WhatsApp message.”* What if you don’t use WhatsApp, or cannot make a phone call, or use the chatbox? By offering multiple contact options, you make sure every customer has a way to connect.
 
 ## Don’t make getting in touch their problem
 

docs/contribute/github/content-kitchen-sink.md

@@ -7,8 +7,7 @@ has_video: true
 
 # Kitchen sink: options available for content
 
-{: .lead }
-This page lists the options and code available for creating content in this documentation
+This page lists the options and code available for creating content in this documentation.
 
 {: .callout  .info }
 WordPress.org provides a lot of style guides for documentation: [WordPress Style Guides - highlights](https://make.wordpress.org/docs/style-guide/welcome/highlights/). We value most of all: be [kind and professional](docs/contribute/CODE_OF_CONDUCT.md) in your text and please write the text yourself or make sure the reader knows who you are citing.
@@ -36,17 +35,20 @@ In blog posts the H1 is added by the template: [Add a blog post]({{site.baseurl}
 
 ## Summary in a larger text font.
 
-Start the paragraph with the code `{: .lead }`.
+Start the paragraph with an H2 named "Summaty, or introduction and the callout {: .lead }`
+
 
 ```markdown
+## Summary
+
 {: .lead }
 When you put care into preventing errors and clearly indicating when something goes wrong, users are much more likely to successfully submit a form.
 ```
+## Summary
 
 {: .lead  }
 When you put care into preventing errors and clearly indicating when something goes wrong, users are much more likely to successfully submit a form.
 
-
 ## Text
 ```markdown
 This is a paragraph.

docs/topics/core/index.md

@@ -49,7 +49,6 @@ If you’re updating an existing control, button or link decision logic:
         <th>Scenario</th>
         <th>Choice</th>
     </tr>
-    </thead>
     <tr>
         <td>Anchors with null or meaningless HREF values: href=’#’, no href, href=’#something’ where #something does not exist</td>
         <td><code>button</code></td>