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.

ArvinJ-H · ArvinJ-H · commit 04c61fb7e669 · 2025-07-18T14:37:12.000+10:00
diff --git 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 `<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.
+* *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
@@ -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
@@ -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
@@ -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]
 ----
-<img src="decorative-border.png" role="presentation" alt="" />
+<!-- Using empty alt attribute -->
+<img src="decorative-border.png" alt="" />
+
+<!-- Using role="presentation" -->
+<img src="spacer.gif" role="presentation" />
+
+<!-- Using both approaches -->
+<img src="pattern.png" role="presentation" alt="" />
 ----
 
 === 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
@@ -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]
 ----
