Skip to content

DOC-3147: Accessibility: Enhanced image accessibility checks & rules in a11ychecker plugin. #3794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kemister85 merged 6 commits into from
Jul 14, 2025
Merged

DOC-3147: Accessibility: Enhanced image accessibility checks & rules in a11ychecker plugin. #3794

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7c6003d
DOC-3147: Accessibility: Enhanced image accessibility checks in a11yc…
kemister85 Jul 8, 2025
69ca525
DOC-3147: Add a11ychecker_alt_text_max_length new option to the relea…
kemister85 Jul 8, 2025
3254b2f
DOC-3147: Fix lvl heading issues for TOC.
kemister85 Jul 11, 2025
2c33383
DOC-3147: Update accessibility rules and configuration options for im…
ArvinJ-H Jul 11, 2025
4f50319
Update modules/ROOT/partials/configuration/a11ychecker_allow_decorati…
kemister85 Jul 14, 2025
62e5bd0
Merge branch 'feature/8.0.0/DOC-3147' into feature/8.0.0/DOC-3147_TIN…
kemister85 Jul 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions modules/ROOT/examples/live-demos/a11ychecker/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,11 @@ tinymce.init({
selector: 'textarea#a11ychecker',
plugins: 'a11ychecker advcode table advlist lists image media anchor link autoresize',
toolbar: 'a11ycheck | blocks bold forecolor backcolor | bullist numlist | link image media anchor | table | code',
max_height: 500,
a11y_advanced_options: true,
a11ychecker_html_version: 'html5',
a11ychecker_level: 'aaa',
a11ychecker_allow_decorative_images: true,
a11ychecker_alt_text_max_length: 150,
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});
34 changes: 34 additions & 0 deletions modules/ROOT/pages/8.0-release-notes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,40 @@ The following premium plugin updates were released alongside {productname} {rele

// For information on the **<Premium plugin name 1>** plugin, see: xref:<plugincode>.adoc[<Premium plugin name 1>].

=== Accessibility Checker

The {productname} {release-version} release includes an accompanying release of the **Accessibility Checker** premium plugin.

**Accessibility Checker** Premium plugin includes the following improvements.

=== Accessibility: Enhanced image accessibility checks in a11ychecker plugin
// #TINY-10903

The {productname} {release-version} introduces four new image accessibility rules (xref:a11ychecker.adoc##image-rules[Image rules]) in the xref:a11ychecker.adoc[a11ychecker] plugin to improve compliance and authoring guidance. These rules help identify common accessibility issues related to image use and provide actionable recommendations:

* *xref:a11ychecker.adoc#I1[I1: Mixed Signals & Decorative Policy]*: Flags images with conflicting accessibility indicators (e.g., `alt` with `role="presentation"`) and ensures decorative images comply with best practices.
* *xref:a11ychecker.adoc#I2[I2: Alt Attribute Requirement]*: Enforces the presence of the `alt` attribute on all `<img>` elements, regardless of other labeling mechanisms like `aria-label`, `aria-labelledby`, or `title`.
* *xref:a11ychecker.adoc#I3[I3: Filename Detection]*: Warns when `alt` text appears to be a filename (e.g., `image123.jpg`), including cases with URL encoding.
* *xref:a11ychecker.adoc#I4[I4: Alt Text Length]*: Detects `alt` text that exceeds a configurable maximum length, promoting concise descriptions. The default limit is 100 characters and can be adjusted using the new xref:a11ychecker.adoc#a11ychecker_alt_text_max_length[`a11ychecker_alt_text_max_length`] setting.

Additional improvements include a rule precedence system to avoid duplicate violations, centralized image intent detection (e.g., decorative, informative, mixed signals, incomplete), and more readable user-facing messages. Technical terminology such as "alternative text" has been replaced with "text description," and repair instructions are now more contextual and user-friendly.

=== New `a11ychecker_alt_text_max_length` configuration option for Accessibility Checker alt text length
// #TINY-10903

A new configuration option, xref:a11ychecker.adoc#a11ychecker_alt_text_max_length[`a11ychecker_alt_text_max_length`], has been added to the Accessibility Checker plugin. This option allows users to configure the maximum allowed length for image alt text descriptions. The default value is 150 characters. For example:

[source,js]
----
tinymce.init({
selector: 'textarea',
plugins: 'a11ychecker',
a11ychecker_alt_text_max_length: 150 // Set maximum length to 150 characters
});
----

For more information on the Accessibility Checker plugin, see: xref:a11ychecker.adoc[Accessibility Checker].

=== PowerPaste

The {productname} {release-version} release includes an accompanying release of the **PowerPaste** premium plugin.
Expand Down
301 changes: 31 additions & 270 deletions modules/ROOT/pages/a11ychecker.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,307 +46,68 @@ Each rule has a severity level, which will be one of the following, listed in or
* Warning
* Error

[[D1]]
=== D1 - Usage of paragraphs as headings
[[document-structure-rules]]
=== Document structure rules

*Rule description:* this rule checks that `+h1+`-`+h6+` tags are used for heading content, not `+p+` tags. Not using correct heading markup will make it difficult for assistive technologies to represent and navigate through your content.
include::partial$a11y-rules/d1.adoc[]

==== {pluginname} rule details - D1
include::partial$a11y-rules/d2.adoc[]

Notification level (severity):: Warning
include::partial$a11y-rules/d3.adoc[]

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
include::partial$a11y-rules/d4o.adoc[]

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
include::partial$a11y-rules/d4u.adoc[]

WCAG 2.1 specifications::
include::partial$a11y-rules/d5.adoc[]

* https://www.w3.org/WAI/WCAG21/Techniques/html/H42.html[H42 - Using h1-h6 to identify headings].
* https://www.w3.org/WAI/WCAG21/Techniques/html/H69.html[H69 - Providing heading elements at the beginning of each section of content].
'''

[[D2]]
=== D2 - Sequential headings
[[html-rules]]
=== HTML rules

*Rule description:* this rule checks that headings tags are used sequentially.
include::partial$a11y-rules/h93.adoc[]

For example: A `+h1+` heading should be followed by a `+h2+` heading, not a `+h3+` heading. Using sequential headings will make it easier for assistive technology to parse your content.
'''

==== {pluginname} rule details - D2
[[image-rules]]
=== Image rules

Notification level (severity):: Error
include::partial$a11y-rules/i1.adoc[]

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
include::partial$a11y-rules/i2.adoc[]

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
include::partial$a11y-rules/i3.adoc[]

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/general/G141.html[G141 - Organizing a page using headings].
include::partial$a11y-rules/i4.adoc[]

[[D3]]
=== D3 - Adjacent links
'''

*Rule description:* this rule checks that links next to other links do not have the same `+href+` attribute.
[[table-rules]]
=== Table rules

For example: If an image link and a text link have the same `+href+` attribute, both elements should be in the same `+a+` element. If an image link and a text link point to the same URL but are two separate elements, it can be confusing for users of screen readers and other assistive technologies.
include::partial$a11y-rules/t1.adoc[]

==== {pluginname} rule details - D3
include::partial$a11y-rules/t2.adoc[]

Notification level (severity):: Error
include::partial$a11y-rules/t3.adoc[]

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
include::partial$a11y-rules/t4a.adoc[]

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
include::partial$a11y-rules/t4b.adoc[]

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H2.html[H2 - Combining adjacent image and text links for the same resource].
include::partial$a11y-rules/t4c.adoc[]

[[D4O]]
=== D4O - Ordered list structure

*Rule description:* this rule checks that an `+ol+` element is used for ordered lists. Do not use paragraphs beginning with numbers or roman numerals instead of an `+ol+` element containing `+li+` items. This is to simplify navigation and parsing of the content for users of assistive technologies.

==== {pluginname} rule details - D4O

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H48.html[H48 - Using ol, ul and dl for lists or groups of links].

[[D4U]]
=== D4U - Unordered list structure

*Rule description:* this rule checks that a `+ul+` element is used for unordered lists. Do not use paragraphs beginning with `+*+` or `+-+` or some similar character instead of an `+ol+` element containing `+li+` items. This is to simplify navigation and parsing of the content for users of assistive technologies.

==== {pluginname} rule details - D4U

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H48.html[H48 - Using ol, ul and dl for lists or groups of links].

[[D5]]
=== D5 - Contrast ratio of the text (D5A, D5B, and D5C)

*Rule description:* this rule checks that the contrast ratio of the text is above the following values:

* When the compliance level is set to AA,
** 4.5:1 for normal text
** 3:1 for large text
* When the compliance level is set to AAA,
** 7:1 for any text

Text with a low contrast ratio is hard to read for users with impaired vision.

[[D5A]]
==== {pluginname} rule details - D5A

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level AA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/general/G145.html[G145 - Ensuring that a contrast ratio of at least 3:1 exists between text (and images of text) and background behind the text].

[[D5B]]
==== {pluginname} rule details - D5B

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level AA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/general/G18.html[G18 - Ensuring that a contrast ratio of at least 4.5:1 exists between text (and images of text) and background behind the text].

[[D5C]]
==== {pluginname} rule details - D5C

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/general/G17.html[G17 - Ensuring that a contrast ratio of at least 7:1 exists between text (and images of text) and background behind the text].

[[H93]]
=== H93 - IDs must be unique

*Rule description:* this rule checks that all `+id+` attributes are unique in the editor. Duplicate `+id+` attributes are known to cause problems for assistive technologies when parsing the content.

==== {pluginname} rule details - H93

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H93.html[H93 - Ensuring that id attributes are unique on a Web page].

[[I1]]
=== I1 - Image `+alt+` text

*Rule description:* this rule checks that all images have alternative (`+alt+`) text for screen readers and other assistive technologies.

==== {pluginname} rule details - I1

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/general/G95.html[G95 - Providing short text alternatives that provide a brief description of the non-text content].

include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]

[[I2]]
=== I2 - Image `+alt+` text is not the image filename

*Rule description:* this rule checks that the `+alt+` attribute text of the image is not the same as the filename of the image.

==== {pluginname} rule details - I2

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/general/G95.html[G95 - Providing short text alternatives that provide a brief description of the non-text content].

include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]

[[I3]]
=== I3 - Image `+alt+` text is not greater than 100 characters

*Rule description:* this rule checks that the `+alt+` attribute text of the image is not more than 100 characters.

An _Image alternative text should be less than 100 characters_ warning dialog presents if the alternative (`+alt+`) text is longer than 100 characters. This dialog also presents the alternative text in an editable field, for immediate repair.

==== {pluginname} rule details - I3

Notification level (severity):: Warning

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: n/a.


[[T1]]
=== T1 - Table caption

*Rule description:* this rule checks that all `+table+` elements have a `+caption+` element describing the data inside the table to simplify parsing and navigation of the content for users of assistive technologies.

==== {pluginname} rule details - T1

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H39.html[H39 - Using caption elements to associate data table captions with data tables].

[[T2]]
=== T2 - Complex table summary

*Rule description:* this rule checks that all complex tables must have a `+summary+` attribute explaining to users of assistive technologies how to navigate through the data inside of the table.

[NOTE]
====
This rule only applies to HTML 4 content and is not checked when `+a11ychecker_html_version+` is set to `+html5+`.
====

==== {pluginname} rule details - T2

Notification level (severity):: Warning

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H73.html[H73 - Using the summary attribute of the table element to give an overview of data tables].

[[T3]]
=== T3 - Table caption and summary

*Rule description:* this rule checks that the table caption and summary does not have the same text content. The caption should explain *what* the table is about while the summary should explain *how* to navigate the data inside of the table.

[NOTE]
====
The table `+summary+` attribute was deprecated in HTML 5, both the *what* and *how* information should be moved to the table caption.
====

==== {pluginname} rule details - T3

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H73.html[H73 - Using the summary attribute of the table element to give an overview of data tables].

[[T4A]]
=== T4A - Table markup

*Rule description:* this rule checks that all `+tables+` contain both `+tr+` and `+td+` elements.

==== {pluginname} rule details - T4A

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H51.html[H51 - Using table markup to present tabular information].

[[T4B]]
=== T4B - Table headers

*Rule description:* this rule checks that all `+table+` elements contain at least one table header (`+th+`) element.

==== {pluginname} rule details - T4B

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H51.html[H51 - Using table markup to present tabular information].

[[T4C]]
=== T4C - Table heading scope

*Rule description:* this rule checks that all table header (`+th+`) elements have a `+scope+` attribute clarifying what scope the heading has inside of the `+table+`. The allowed values are `+row+`, `+col+`, `+rowgroup+`, and `+colgroup+`. This is important for users of assistive technologies to be able to parse table data.

==== {pluginname} rule details - T4C

Notification level (severity):: Error

https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA

xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5

WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H63.html[H63 - Using the scope attribute to associate header cells and data cells in data tables].
'''

== Options

The following configuration options affect the behavior of the {pluginname} plugin.

include::partial$configuration/a11y_advanced_options.adoc[leveloffset=+1]

include::partial$configuration/a11ychecker_alt_text_max_length.adoc[leveloffset=+1]

include::partial$configuration/a11ychecker_allow_decorative_images.adoc[leveloffset=+1]

include::partial$configuration/a11ychecker_filter_issue.adoc[leveloffset=+1]
Expand Down
Loading