Update Overlays documentation for issue #88. #101

kurapativyshnavi · 2025-09-15T16:21:38Z

Completes all tasks listed in issue #88 by adding the "Overlays" documentation content.

rianrietveld · 2025-09-16T07:17:44Z

Hey @kurapativyshnavi
Thank you for your PR.

How is this PR different from #102?

I will review this one for now :-)

rianrietveld

@kurapativyshnavi

Can you please make the adjustments to the text.
The feel of the text is very AI generated now.

Please use shorter and less complicated sentences.
For most of our readers English is not their first language.
Also divide long paragraphs into shorter ones for readability.

rianrietveld · 2025-09-16T07:19:28Z

docs/start/myths/overlays.md

- add more resources from within the WP community.
+# Accessibility Overlays: A Comprehensive Overview
+
+### What are Accessibility Overlays?


Change into an H2.
Please read Accessible heading structure that explains why.

rianrietveld · 2025-09-16T07:19:49Z

docs/start/myths/overlays.md

+
+Accessibility overlays are third-party software widgets or plugins designed to be added to a website to address accessibility issues. Typically, these tools are marketed as a quick and inexpensive way to achieve legal compliance and make a website more accessible. They operate by injecting a layer of JavaScript code into a website, often appearing as a small, floating icon that, when activated, reveals a menu of options such as font adjustments, color contrast changes, or other visual settings.
+
+### The Distinction Between Overlays and Toolbars


Change into an H2.

rianrietveld · 2025-09-16T07:21:08Z

docs/start/myths/overlays.md

+
+While both accessibility overlays and user preference toolbars may offer similar features, their underlying functionality and purpose are fundamentally different. Understanding this distinction is crucial for effective web accessibility.
+
+* **Accessibility Overlays:** These are presented as a comprehensive solution to accessibility challenges. They are designed to act as a "fix" for a website's underlying code by attempting to automatically remediate accessibility issues on the fly. However, they frequently fail to correct fundamental problems with a site’s HTML, ARIA, or CSS. This approach can create new barriers for users of assistive technologies and often provides a false sense of compliance. An overlay is intended to fix the site for the user, but it cannot fix inaccessible source code.


Remove the list * (as this is not a list) :-)

rianrietveld · 2025-09-16T07:21:13Z

docs/start/myths/overlays.md

+
+* **Accessibility Overlays:** These are presented as a comprehensive solution to accessibility challenges. They are designed to act as a "fix" for a website's underlying code by attempting to automatically remediate accessibility issues on the fly. However, they frequently fail to correct fundamental problems with a site’s HTML, ARIA, or CSS. This approach can create new barriers for users of assistive technologies and often provides a false sense of compliance. An overlay is intended to fix the site for the user, but it cannot fix inaccessible source code.
+
+* **User Preference Toolbars:** In contrast, toolbars are client-side applications that do not alter the website's original code. Their purpose is not to "fix" a site but to empower the end-user. They offer personal customization features, allowing individuals to modify their own browsing experience to suit their needs, such as adjusting text size or contrast. These tools are most effective when used on a website that is already built to be accessible, as they complement, rather than substitute for, proper accessibility practices.


Remove the list * (as this is not a list) :-)

rianrietveld · 2025-09-16T07:23:22Z

docs/start/myths/overlays.md

+
+* **User Preference Toolbars:** In contrast, toolbars are client-side applications that do not alter the website's original code. Their purpose is not to "fix" a site but to empower the end-user. They offer personal customization features, allowing individuals to modify their own browsing experience to suit their needs, such as adjusting text size or contrast. These tools are most effective when used on a website that is already built to be accessible, as they complement, rather than substitute for, proper accessibility practices.
+
+### Additional Resources


Change into an H2.

rianrietveld · 2025-09-16T07:25:39Z

docs/start/myths/overlays.md

+#### The Overlays Fact Sheet
+
+A comprehensive, multi-lingual report detailing the issues and risks associated with accessibility overlays:
+* [overlayfactsheet.com](https://overlayfactsheet.com/en/)


Remove the list * (as this is not a list) :-)

rianrietveld · 2025-09-16T07:28:07Z

docs/start/myths/overlays.md

+#### Videos from Accessibility Experts
+
+* **"Overlays Underwhelm"** by Adrian Roselli: A detailed presentation on the shortcomings of overlays.
+    * [https://www.youtube.com/live/RDkqJaBwgKU](https://www.youtube.com/live/RDkqJaBwgKU)


Remove the list * (as this is not a list) :-)

Link "Overlays Underwhelm" and not the URL itself.
This makes the link text meaningful.

Proposed code

**[Overlays Underwhelm](https://www.youtube.com/live/RDkqJaBwgKU)** by Adrian Roselli: A detailed presentation on the shortcomings of overlays.

rianrietveld · 2025-09-16T07:32:12Z

docs/start/myths/overlays.md

+* **"Overlays Underwhelm"** by Adrian Roselli: A detailed presentation on the shortcomings of overlays.
+    * [https://www.youtube.com/live/RDkqJaBwgKU](https://www.youtube.com/live/RDkqJaBwgKU)
+
+* **"There is no spoon"** by Léonie Watson: This well-known talk discusses the importance of designing for people, not for technology, and the limitations of quick-fix solutions.


Same as previous
Remove the lists * (as this is not a list) :-)
Link There is no spoon and not the URL itself.

rianrietveld · 2025-09-16T07:34:02Z

docs/start/myths/overlays.md

+    * [https://www.youtube.com/watch?v=fyRxd072JrA](https://www.youtube.com/watch?v=fyRxd072JrA)
+    (Note: The video you originally linked is about AI and accessibility, but this is Léonie Watson's celebrated talk on this topic.)
+
+#### Resources from the WordPress Community


Change into an H3.

docs/start/myths/overlays.md

fix(docs): update overlays page with simplified text, video embeds, and alert

rianrietveld · 2025-09-17T07:38:58Z

Hi @kurapativyshnavi
We will let someone who is an expert on this topic work futher on this content to make additions, as there is so much more to tell about overlays. Thank you for starting this.

I really appreciate your work on the search option, please concider using your time contributing with code.

Update overlays.md

077038b

rianrietveld added this to WP A11y docs Sep 15, 2025

rianrietveld moved this to PRs to review in WP A11y docs Sep 15, 2025

rianrietveld requested changes Sep 16, 2025

View reviewed changes

Update overlays.md

e12e08a

fix(docs): update overlays page with simplified text, video embeds, and alert

rianrietveld mentioned this pull request Sep 17, 2025

GitHub preview actions doesn't work for a PR from contributors outside the docs team #100

Open

rianrietveld moved this from PRs to review to In Progress in WP A11y docs Sep 18, 2025

rianrietveld removed this from WP A11y docs Sep 18, 2025

rianrietveld assigned rianrietveld and unassigned rianrietveld Sep 18, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update Overlays documentation for issue #88. #101

Update Overlays documentation for issue #88. #101

Uh oh!

kurapativyshnavi commented Sep 15, 2025

Uh oh!

rianrietveld commented Sep 16, 2025 •

edited

Loading

Uh oh!

rianrietveld left a comment

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

rianrietveld Sep 16, 2025

Uh oh!

Uh oh!

rianrietveld commented Sep 17, 2025

Uh oh!

Uh oh!


		Accessibility overlays are third-party software widgets or plugins designed to be added to a website to address accessibility issues. Typically, these tools are marketed as a quick and inexpensive way to achieve legal compliance and make a website more accessible. They operate by injecting a layer of JavaScript code into a website, often appearing as a small, floating icon that, when activated, reveals a menu of options such as font adjustments, color contrast changes, or other visual settings.

		### The Distinction Between Overlays and Toolbars


		While both accessibility overlays and user preference toolbars may offer similar features, their underlying functionality and purpose are fundamentally different. Understanding this distinction is crucial for effective web accessibility.

		* Accessibility Overlays: These are presented as a comprehensive solution to accessibility challenges. They are designed to act as a "fix" for a website's underlying code by attempting to automatically remediate accessibility issues on the fly. However, they frequently fail to correct fundamental problems with a site’s HTML, ARIA, or CSS. This approach can create new barriers for users of assistive technologies and often provides a false sense of compliance. An overlay is intended to fix the site for the user, but it cannot fix inaccessible source code.


		* Accessibility Overlays: These are presented as a comprehensive solution to accessibility challenges. They are designed to act as a "fix" for a website's underlying code by attempting to automatically remediate accessibility issues on the fly. However, they frequently fail to correct fundamental problems with a site’s HTML, ARIA, or CSS. This approach can create new barriers for users of assistive technologies and often provides a false sense of compliance. An overlay is intended to fix the site for the user, but it cannot fix inaccessible source code.

		* User Preference Toolbars: In contrast, toolbars are client-side applications that do not alter the website's original code. Their purpose is not to "fix" a site but to empower the end-user. They offer personal customization features, allowing individuals to modify their own browsing experience to suit their needs, such as adjusting text size or contrast. These tools are most effective when used on a website that is already built to be accessible, as they complement, rather than substitute for, proper accessibility practices.


		* User Preference Toolbars: In contrast, toolbars are client-side applications that do not alter the website's original code. Their purpose is not to "fix" a site but to empower the end-user. They offer personal customization features, allowing individuals to modify their own browsing experience to suit their needs, such as adjusting text size or contrast. These tools are most effective when used on a website that is already built to be accessible, as they complement, rather than substitute for, proper accessibility practices.

		### Additional Resources

Update Overlays documentation for issue #88. #101

Are you sure you want to change the base?

Update Overlays documentation for issue #88. #101

Uh oh!

Conversation

kurapativyshnavi commented Sep 15, 2025

Uh oh!

rianrietveld commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rianrietveld left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rianrietveld commented Sep 17, 2025

Uh oh!

Uh oh!

rianrietveld commented Sep 16, 2025 •

edited

Loading