Skip to content

Commit 8f727d5

Browse files
kemister85ArvinJ-Habhinavgandham
authored
DOC-3147: Accessibility: Enhanced image accessibility checks & rules in a11ychecker plugin. (#3794)
* DOC-3147: Accessibility: Enhanced image accessibility checks in a11ychecker plugin. * DOC-3147: Add a11ychecker_alt_text_max_length new option to the release notes. * DOC-3147: Fix lvl heading issues for TOC. * DOC-3147: Update accessibility rules and configuration options for image handling * Update modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc Co-authored-by: CODE:AG <[email protected]> --------- Co-authored-by: Arvin Han <[email protected]> Co-authored-by: CODE:AG <[email protected]>
1 parent bb1d6ab commit 8f727d5

File tree

22 files changed

+1269
-277
lines changed

22 files changed

+1269
-277
lines changed

‎modules/ROOT/examples/live-demos/a11ychecker/index.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@ tinymce.init({
22
selector: 'textarea#a11ychecker',
33
plugins: 'a11ychecker advcode table advlist lists image media anchor link autoresize',
44
toolbar: 'a11ycheck | blocks bold forecolor backcolor | bullist numlist | link image media anchor | table | code',
5+
max_height: 500,
56
a11y_advanced_options: true,
67
a11ychecker_html_version: 'html5',
78
a11ychecker_level: 'aaa',
9+
a11ychecker_allow_decorative_images: true,
10+
a11ychecker_alt_text_max_length: 150,
811
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
912
});

‎modules/ROOT/pages/8.0-release-notes.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,40 @@ The following premium plugin updates were released alongside {productname} {rele
5858

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

61+
=== Accessibility Checker
62+
63+
The {productname} {release-version} release includes an accompanying release of the **Accessibility Checker** premium plugin.
64+
65+
**Accessibility Checker** Premium plugin includes the following improvements.
66+
67+
=== Accessibility: Enhanced image accessibility checks in a11ychecker plugin
68+
// #TINY-10903
69+
70+
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:
71+
72+
* *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.
73+
* *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`.
74+
* *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.
75+
* *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.
76+
77+
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.
78+
79+
=== New `a11ychecker_alt_text_max_length` configuration option for Accessibility Checker alt text length
80+
// #TINY-10903
81+
82+
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:
83+
84+
[source,js]
85+
----
86+
tinymce.init({
87+
selector: 'textarea',
88+
plugins: 'a11ychecker',
89+
a11ychecker_alt_text_max_length: 150 // Set maximum length to 150 characters
90+
});
91+
----
92+
93+
For more information on the Accessibility Checker plugin, see: xref:a11ychecker.adoc[Accessibility Checker].
94+
6195
=== PowerPaste
6296

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

‎modules/ROOT/pages/a11ychecker.adoc‎

Lines changed: 31 additions & 270 deletions
Original file line numberDiff line numberDiff line change
@@ -46,307 +46,68 @@ Each rule has a severity level, which will be one of the following, listed in or
4646
* Warning
4747
* Error
4848

49-
[[D1]]
50-
=== D1 - Usage of paragraphs as headings
49+
[[document-structure-rules]]
50+
=== Document structure rules
5151

52-
*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.
52+
include::partial$a11y-rules/d1.adoc[]
5353

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

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

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

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

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

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

67-
[[D2]]
68-
=== D2 - Sequential headings
66+
[[html-rules]]
67+
=== HTML rules
6968

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

72-
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.
71+
'''
7372

74-
==== {pluginname} rule details - D2
73+
[[image-rules]]
74+
=== Image rules
7575

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

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

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

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

84-
[[D3]]
85-
=== D3 - Adjacent links
84+
'''
8685

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

89-
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.
89+
include::partial$a11y-rules/t1.adoc[]
9090

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

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

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

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

99-
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].
99+
include::partial$a11y-rules/t4c.adoc[]
100100

101-
[[D4O]]
102-
=== D4O - Ordered list structure
103-
104-
*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.
105-
106-
==== {pluginname} rule details - D4O
107-
108-
Notification level (severity):: Error
109-
110-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
111-
112-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
113-
114-
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].
115-
116-
[[D4U]]
117-
=== D4U - Unordered list structure
118-
119-
*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.
120-
121-
==== {pluginname} rule details - D4U
122-
123-
Notification level (severity):: Error
124-
125-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
126-
127-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
128-
129-
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].
130-
131-
[[D5]]
132-
=== D5 - Contrast ratio of the text (D5A, D5B, and D5C)
133-
134-
*Rule description:* this rule checks that the contrast ratio of the text is above the following values:
135-
136-
* When the compliance level is set to AA,
137-
** 4.5:1 for normal text
138-
** 3:1 for large text
139-
* When the compliance level is set to AAA,
140-
** 7:1 for any text
141-
142-
Text with a low contrast ratio is hard to read for users with impaired vision.
143-
144-
[[D5A]]
145-
==== {pluginname} rule details - D5A
146-
147-
Notification level (severity):: Error
148-
149-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level AA
150-
151-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
152-
153-
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].
154-
155-
[[D5B]]
156-
==== {pluginname} rule details - D5B
157-
158-
Notification level (severity):: Error
159-
160-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level AA
161-
162-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
163-
164-
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].
165-
166-
[[D5C]]
167-
==== {pluginname} rule details - D5C
168-
169-
Notification level (severity):: Error
170-
171-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level AAA
172-
173-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
174-
175-
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].
176-
177-
[[H93]]
178-
=== H93 - IDs must be unique
179-
180-
*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.
181-
182-
==== {pluginname} rule details - H93
183-
184-
Notification level (severity):: Error
185-
186-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
187-
188-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
189-
190-
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].
191-
192-
[[I1]]
193-
=== I1 - Image `+alt+` text
194-
195-
*Rule description:* this rule checks that all images have alternative (`+alt+`) text for screen readers and other assistive technologies.
196-
197-
==== {pluginname} rule details - I1
198-
199-
Notification level (severity):: Error
200-
201-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
202-
203-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
204-
205-
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].
206-
207-
include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]
208-
209-
[[I2]]
210-
=== I2 - Image `+alt+` text is not the image filename
211-
212-
*Rule description:* this rule checks that the `+alt+` attribute text of the image is not the same as the filename of the image.
213-
214-
==== {pluginname} rule details - I2
215-
216-
Notification level (severity):: Error
217-
218-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
219-
220-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
221-
222-
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].
223-
224-
include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]
225-
226-
[[I3]]
227-
=== I3 - Image `+alt+` text is not greater than 100 characters
228-
229-
*Rule description:* this rule checks that the `+alt+` attribute text of the image is not more than 100 characters.
230-
231-
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.
232-
233-
==== {pluginname} rule details - I3
234-
235-
Notification level (severity):: Warning
236-
237-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
238-
239-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
240-
241-
WCAG 2.1 specification:: n/a.
242-
243-
244-
[[T1]]
245-
=== T1 - Table caption
246-
247-
*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.
248-
249-
==== {pluginname} rule details - T1
250-
251-
Notification level (severity):: Error
252-
253-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
254-
255-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
256-
257-
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].
258-
259-
[[T2]]
260-
=== T2 - Complex table summary
261-
262-
*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.
263-
264-
[NOTE]
265-
====
266-
This rule only applies to HTML 4 content and is not checked when `+a11ychecker_html_version+` is set to `+html5+`.
267-
====
268-
269-
==== {pluginname} rule details - T2
270-
271-
Notification level (severity):: Warning
272-
273-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
274-
275-
xref:a11ychecker_html_version[HTML version]:: HTML4
276-
277-
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].
278-
279-
[[T3]]
280-
=== T3 - Table caption and summary
281-
282-
*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.
283-
284-
[NOTE]
285-
====
286-
The table `+summary+` attribute was deprecated in HTML 5, both the *what* and *how* information should be moved to the table caption.
287-
====
288-
289-
==== {pluginname} rule details - T3
290-
291-
Notification level (severity):: Error
292-
293-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
294-
295-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
296-
297-
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].
298-
299-
[[T4A]]
300-
=== T4A - Table markup
301-
302-
*Rule description:* this rule checks that all `+tables+` contain both `+tr+` and `+td+` elements.
303-
304-
==== {pluginname} rule details - T4A
305-
306-
Notification level (severity):: Error
307-
308-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
309-
310-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
311-
312-
WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H51.html[H51 - Using table markup to present tabular information].
313-
314-
[[T4B]]
315-
=== T4B - Table headers
316-
317-
*Rule description:* this rule checks that all `+table+` elements contain at least one table header (`+th+`) element.
318-
319-
==== {pluginname} rule details - T4B
320-
321-
Notification level (severity):: Error
322-
323-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
324-
325-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
326-
327-
WCAG 2.1 specification:: https://www.w3.org/WAI/WCAG21/Techniques/html/H51.html[H51 - Using table markup to present tabular information].
328-
329-
[[T4C]]
330-
=== T4C - Table heading scope
331-
332-
*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.
333-
334-
==== {pluginname} rule details - T4C
335-
336-
Notification level (severity):: Error
337-
338-
https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Level AAA
339-
340-
xref:a11ychecker_html_version[HTML version]:: HTML4 and HTML5
341-
342-
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].
101+
'''
343102

344103
== Options
345104

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

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

109+
include::partial$configuration/a11ychecker_alt_text_max_length.adoc[leveloffset=+1]
110+
350111
include::partial$configuration/a11ychecker_allow_decorative_images.adoc[leveloffset=+1]
351112

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

0 commit comments

Comments
 (0)