From 9b5dea13755352d9cf12ca1730460641e4731be0 Mon Sep 17 00:00:00 2001 From: Arvin Han <20640097+ArvinJ-H@users.noreply.github.com> Date: Tue, 15 Jul 2025 14:43:13 +1000 Subject: [PATCH 1/5] DOC-3147: Add I1 url --- modules/ROOT/partials/a11y-rules/i1.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/partials/a11y-rules/i1.adoc b/modules/ROOT/partials/a11y-rules/i1.adoc index 18b4a7242a..102fb964ed 100644 --- a/modules/ROOT/partials/a11y-rules/i1.adoc +++ b/modules/ROOT/partials/a11y-rules/i1.adoc @@ -11,7 +11,9 @@ https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Lev 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]. +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]. +* https://www.w3.org/WAI/WCAG21/Techniques/failures/F38.html[F38 - Using an empty alt attribute on an image that has a text alternative in another attribute]. include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[] From 04c61fb7e669e72a960d3b9228e26beaab0e1b3b Mon Sep 17 00:00:00 2001 From: Arvin Han <20640097+ArvinJ-H@users.noreply.github.com> Date: Fri, 18 Jul 2025 14:37:12 +1000 Subject: [PATCH 2/5] DOC-3147: Update accessibility documentation: Adjust alt text length limit to 150 characters, enhance descriptions for decorative images, and clarify filtering behavior for empty alt attributes. --- modules/ROOT/pages/8.0-release-notes.adoc | 2 +- modules/ROOT/partials/a11y-rules/i3.adoc | 4 ++- .../configuration/a11y_advanced_options.adoc | 2 +- .../a11ychecker_allow_decorative_images.adoc | 28 +++++++++++-------- .../a11ychecker_filter_issue.adoc | 2 +- 5 files changed, 23 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/8.0-release-notes.adoc b/modules/ROOT/pages/8.0-release-notes.adoc index 0d367424fe..4530f834fc 100644 --- a/modules/ROOT/pages/8.0-release-notes.adoc +++ b/modules/ROOT/pages/8.0-release-notes.adoc @@ -133,7 +133,7 @@ The {productname} {release-version} introduces four new image accessibility rule * *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 `` 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. +* *xref:a11ychecker.adoc#I4[I4: Alt Text Length]*: Detects `alt` text that exceeds a configurable maximum length, promoting concise descriptions. The default limit is 150 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. diff --git a/modules/ROOT/partials/a11y-rules/i3.adoc b/modules/ROOT/partials/a11y-rules/i3.adoc index b7bb2b1446..426ef2d760 100644 --- a/modules/ROOT/partials/a11y-rules/i3.adoc +++ b/modules/ROOT/partials/a11y-rules/i3.adoc @@ -11,7 +11,9 @@ https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Lev 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]. +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]. +* https://www.w3.org/WAI/WCAG21/Techniques/failures/F38.html[F38 - Using an empty alt attribute on an image that has a text alternative in another attribute]. include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[] diff --git a/modules/ROOT/partials/configuration/a11y_advanced_options.adoc b/modules/ROOT/partials/configuration/a11y_advanced_options.adoc index de6765c7f7..ca40b0f747 100644 --- a/modules/ROOT/partials/configuration/a11y_advanced_options.adoc +++ b/modules/ROOT/partials/configuration/a11y_advanced_options.adoc @@ -11,7 +11,7 @@ Setting `+a11y_advanced_options+` to `+true+`: * Adds the *Image is decorative* option to the _Insert/Edit Image_ dialog, allowing users to specify that an image is decorative and does not require alternative text for accessibility purposes. * Adds the *Decorative image* button to Image Optimizer's _Alt text_ context toolbar, allowing users to specify that an image is decorative and does not require alternative text for accessibility purposes. -* Adds the *Image is decorative* option to the _Accessibility Checker error_ dialog for images without alternative text or the `+role="presentation"+` attribute. +* Adds the *Image is decorative* option to the _Accessibility Checker error_ dialog for images that need to be marked as decorative. [IMPORTANT] ==== diff --git a/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc b/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc index c669276576..23072b447c 100644 --- a/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc +++ b/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc @@ -3,12 +3,13 @@ This option determines whether the Accessibility Checker should allow decorative images. Decorative images are those that are used purely for visual enhancement and do not convey meaningful content or serve a specific function. -When this option is set to `+true+`, decorative images must have *both*: +When this option is set to `+true+`, decorative images must be marked using one or both of these methods: -* An empty alternative text attribute (`+alt=""+`). -* and the `+role="presentation"+` attribute. +* An empty alternative text attribute (`+alt=""+`), OR +* The `+role="presentation"+` or `+role="none"+` attribute, OR +* Both methods together -This combination explicitly tells assistive technologies to ignore these images, improving the browsing experience for users of screen readers. +Any of these approaches explicitly tells assistive technologies to ignore these images, improving the browsing experience for users of screen readers. === Common Use Cases for Decorative Images @@ -18,11 +19,18 @@ This combination explicitly tells assistive technologies to ignore these images, * Images that are described by adjacent text content * Spacer images used for layout purposes -=== Example of a Decorative Image: +=== Examples of Decorative Images: [source,html] ---- - + + + + + + + + ---- === Example of an Informative Image (non-decorative): @@ -36,10 +44,8 @@ This combination explicitly tells assistive technologies to ignore these images, If `+a11ychecker_allow_decorative_images+` is set to `+true+`, the Accessibility Checker will present an error when: -* An image does not have the alternative text attribute (`+alt+`). -* An image has an empty alternative text attribute but is missing the `+role="presentation"+` attribute. -* An image has alternative text and a conflicting `+role="presentation"+` attribute. -* A potentially meaningful image (like a logo or chart) is marked as decorative. +* An image has conflicting accessibility information (e.g., both meaningful alt text and `+role="presentation"+`). +* An image has incomplete accessibility information (no clear decorative or informative intent). If `+a11ychecker_allow_decorative_images+` is set to `+false+`, the Accessibility Checker will present an error when: @@ -54,7 +60,7 @@ If `+a11ychecker_allow_decorative_images+` is not explicitly set, the value defi *Type:* `+Boolean+` -*Default value:* `+true+` +*Default value:* `+false+` *Possible values:* `+true+`, `+false+` diff --git a/modules/ROOT/partials/configuration/a11ychecker_filter_issue.adoc b/modules/ROOT/partials/configuration/a11ychecker_filter_issue.adoc index b901d701ea..d66f42894b 100644 --- a/modules/ROOT/partials/configuration/a11ychecker_filter_issue.adoc +++ b/modules/ROOT/partials/configuration/a11ychecker_filter_issue.adoc @@ -47,7 +47,7 @@ tinymce.init({ === Example: using `+a11ychecker_filter_issue+` to filter images with empty alternative text from the Accessibility Checker I1 rule -The callback function in the following example will only return `false` for any issues with `'I1'` as the `+'id'+` image elements with an empty `+'alt+'` attribute, otherwise the issue won’t be filtered out. This implementation can be useful as allowing images to have empty alternative text can be another method of applying the `+role="presentation"+` attribute to mark an image as `+decorative+`. +The callback function in the following example will only return `false` for any issues with `'I1'` as the `+'id'+` for image elements with an empty `+'alt+'` attribute, otherwise the issue won't be filtered out. This implementation can be useful when you want to allow images with empty alternative text to be treated as decorative. [source,js] ---- From 683ed6bffe4853f7291c9bd8a49fbe53e8422243 Mon Sep 17 00:00:00 2001 From: "Arvin(Jintao) Han" <20640097+ArvinJ-H@users.noreply.github.com> Date: Fri, 18 Jul 2025 14:41:37 +1000 Subject: [PATCH 3/5] Update modules/ROOT/partials/a11y-rules/i1.adoc Co-authored-by: Karl Kemister-Sheppard --- modules/ROOT/partials/a11y-rules/i1.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/partials/a11y-rules/i1.adoc b/modules/ROOT/partials/a11y-rules/i1.adoc index 102fb964ed..5e30c264db 100644 --- a/modules/ROOT/partials/a11y-rules/i1.adoc +++ b/modules/ROOT/partials/a11y-rules/i1.adoc @@ -12,8 +12,8 @@ https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Lev 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]. -* https://www.w3.org/WAI/WCAG21/Techniques/failures/F38.html[F38 - Using an empty alt attribute on an image that has a text alternative in another attribute]. +* link: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]. +* link:https://www.w3.org/WAI/WCAG21/Techniques/failures/F38.html[F38 - Using an empty alt attribute on an image that has a text alternative in another attribute]. include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[] From 2903b67e53789a67d2efe846729eb2ed40df12bd Mon Sep 17 00:00:00 2001 From: "Arvin(Jintao) Han" <20640097+ArvinJ-H@users.noreply.github.com> Date: Fri, 18 Jul 2025 14:42:51 +1000 Subject: [PATCH 4/5] Update modules/ROOT/partials/a11y-rules/i3.adoc --- modules/ROOT/partials/a11y-rules/i3.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/partials/a11y-rules/i3.adoc b/modules/ROOT/partials/a11y-rules/i3.adoc index 426ef2d760..d6ede8882e 100644 --- a/modules/ROOT/partials/a11y-rules/i3.adoc +++ b/modules/ROOT/partials/a11y-rules/i3.adoc @@ -12,8 +12,8 @@ https://www.w3.org/TR/WCAG21/#conformance[WCAG level]:: Level A ; Level AA ; Lev 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]. -* https://www.w3.org/WAI/WCAG21/Techniques/failures/F38.html[F38 - Using an empty alt attribute on an image that has a text alternative in another attribute]. +* link: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]. +* link:https://www.w3.org/WAI/WCAG21/Techniques/failures/F38.html[F38 - Using an empty alt attribute on an image that has a text alternative in another attribute]. include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[] From 4f5f0d2098b9ce75be6a6c5f0d82523be4ba7723 Mon Sep 17 00:00:00 2001 From: "Arvin(Jintao) Han" <20640097+ArvinJ-H@users.noreply.github.com> Date: Fri, 18 Jul 2025 14:45:16 +1000 Subject: [PATCH 5/5] Apply suggestion from @ArvinJ-H --- .../configuration/a11ychecker_allow_decorative_images.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc b/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc index 23072b447c..4ad544ed0a 100644 --- a/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc +++ b/modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc @@ -31,6 +31,9 @@ Any of these approaches explicitly tells assistive technologies to ignore these + + + ---- === Example of an Informative Image (non-decorative):