Skip to content

Commit 2c33383

Browse files
ArvinJ-HArvinJ-H
committed
DOC-3147: Update accessibility rules and configuration options for image handling
1 parent 3254b2f commit 2c33383

File tree

5 files changed

+65
-54
lines changed

5 files changed

+65
-54
lines changed

‎modules/ROOT/partials/a11y-rules/i1.adoc‎

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[I1]]
22
==== I1 - Conflicting or incomplete image accessibility
33

4-
*Rule description:* this rule checks that all images have complete and non-conflicting accessibility information. It flags images that are missing required accessibility attributes or are marked both decorative and informative (mixed signals).
4+
*Rule description:* this rule checks that all images have complete and non-conflicting accessibility information. It flags images that send mixed signals about their purpose (both decorative and informative) or have incomplete accessibility information. When `+a11ychecker_allow_decorative_images+` is `+false+`, this rule also flags decorative images as not allowed.
55

66
===== {pluginname} rule details - I1
77

@@ -21,39 +21,51 @@ include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]
2121
.Non-compliant examples
2222
[source,html]
2323
----
24-
<!-- Missing alt attribute -->
25-
<img src="logo.png">
24+
<!-- Mixed signals: has alt text but marked as decorative -->
25+
<img src="logo.jpg" alt="Company Logo" role="presentation">
2626
27-
<!-- Conflicting accessibility information -->
28-
<img src="icon.png" alt="Navigation menu" role="presentation">
27+
<!-- Incomplete: no accessibility information -->
28+
<img src="chart.jpg">
2929
30-
<!-- Empty alt with no role -->
31-
<img src="divider.png" alt="">
30+
<!-- Conflicting: decorative intent with aria-label -->
31+
<img src="icon.jpg" role="presentation" aria-label="Icon">
32+
33+
<!-- Conflicting: empty alt with aria-label -->
34+
<img src="decoration.jpg" alt="" aria-label="Decoration">
35+
36+
<!-- Conflicting: decorative with title (interferes with intent) -->
37+
<img src="spacer.gif" role="presentation" title="Spacer">
3238
33-
<!-- Both title and alt with different information -->
34-
<img src="chart.png" alt="Sales Data" title="Quarter 1 Revenue Chart">
39+
<!-- Invalid: empty role -->
40+
<img src="photo.jpg" alt="Description" role="">
41+
42+
<!-- When decorative not allowed (if a11ychecker_allow_decorative_images = false) -->
43+
<img src="spacer.gif" alt="" role="presentation">
3544
----
3645
37-
These examples show various accessibility issues: missing alt text, conflicting decorative and informative attributes, and inconsistent information between attributes.
46+
These examples show various accessibility issues: mixed signals, incomplete intent, and decorative images when not allowed.
3847
3948
.Compliant examples
4049
[source,html]
4150
----
42-
<!-- Informative image with appropriate alt text -->
43-
<img src="logo.png" alt="Company Name Logo">
51+
<!-- Informative image with meaningful alt text -->
52+
<img src="logo.jpg" alt="Company Logo">
53+
54+
<!-- Decorative image with empty alt -->
55+
<img src="divider.png" alt="">
4456
45-
<!-- Decorative image properly marked -->
46-
<img src="divider.png" alt="" role="presentation">
57+
<!-- Decorative image with role only -->
58+
<img src="spacer.gif" role="presentation">
4759
48-
<!-- Image with consistent alternative text -->
49-
<img src="chart.png" alt="Quarter 1 Revenue Chart">
60+
<!-- Decorative image with both (redundant but valid) -->
61+
<img src="pattern.jpg" alt="" role="presentation">
5062
51-
<!-- Complex image with detailed description -->
52-
<img src="infographic.png"
53-
alt="Annual report highlights"
54-
aria-describedby="infographic-desc">
55-
<p id="infographic-desc">Detailed description of the infographic...</p>
63+
<!-- Informative image with supporting aria-describedby -->
64+
<img src="chart.png"
65+
alt="Sales performance chart"
66+
aria-describedby="chart-desc">
67+
<p id="chart-desc">Detailed breakdown of Q3 sales performance...</p>
5668
----
5769
58-
These examples demonstrate proper accessibility markup for different types of images.
70+
These examples demonstrate proper accessibility markup with clear intent and ARIA compliance.
5971
====

‎modules/ROOT/partials/a11y-rules/i2.adoc‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[I2]]
22
==== I2 - Missing `+alt+` attribute
33

4-
*Rule description:* this rule checks that all `<img>` elements include an `+alt+` attribute, even if other accessible name properties like `+aria-label+`, `+aria-labelledby+`, or `+title+` are present. This ensures images are always programmatically identified.
4+
*Rule description:* this rule checks that all `<img>` elements include an `+alt+` attribute, even if other accessible name properties like `+aria-label+`, `+aria-labelledby+`, or `+title+` are present. The `+alt+` attribute is required for all images, and informative images must have at least one meaningful text alternative.
55

66
===== {pluginname} rule details - I2
77

@@ -22,21 +22,20 @@ include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]
2222
2323
[source,html]
2424
----
25-
<!-- Missing alt attribute completely -->
26-
<img src="product.jpg">
25+
<!-- No alt attribute at all -->
26+
<img src="chart.jpg">
2727
28-
<!-- Using title instead of alt -->
29-
<img src="icon.png" title="Settings">
28+
<!-- No alt attribute (even with aria-label) -->
29+
<img src="icon.jpg" aria-label="Settings">
3030
31-
<!-- Using aria-label without alt -->
32-
<img src="profile.jpg" aria-label="User profile picture">
31+
<!-- No alt attribute (but has aria-labelledby) -->
32+
<img src="chart.jpg" aria-labelledby="chart-caption">
3333
34-
<!-- Using aria-labelledby without alt -->
35-
<img src="chart.png" aria-labelledby="chart-desc">
36-
<p id="chart-desc">Sales performance chart</p>
34+
<!-- No alt attribute (but has title) -->
35+
<img src="button.jpg" title="Submit">
3736
----
3837
39-
These examples fail because they're missing the required alt attribute, even though some have other accessibility attributes.
38+
These examples fail because they're missing the required `+alt+` attribute. Note: Images with no attributes at all trigger rule I1 for incomplete intent, not I2.
4039
4140
.Compliant examples
4241
@@ -60,5 +59,5 @@ These examples fail because they're missing the required alt attribute, even tho
6059
title="Settings">
6160
----
6261
63-
These examples all include the required alt attribute, properly implementing image accessibility.
62+
These examples all include the required `+alt+` attribute and provide meaningful text alternatives for informative images.
6463
====

‎modules/ROOT/partials/a11y-rules/i3.adoc‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[I3]]
22
==== I3 - Filename used as `+alt+` text
33

4-
*Rule description:* this rule checks that the `+alt+` attribute does not use a filename (e.g., `+photo.jpg+`) as a substitute for meaningful image description. Using filenames as `+alt+` text does not help users understand the image's content.
4+
*Rule description:* this rule checks that the `+alt+` attribute does not use a filename (e.g., `+photo.jpg+`) as a substitute for meaningful image description. Filenames like "IMG_1234.jpg" or "photo.png" don't help users understand the image content.
55

66
===== {pluginname} rule details - I3
77

@@ -21,35 +21,35 @@ include::partial$misc/admon-accessibility-rule-i3-can-also-be-applied.adoc[]
2121
.Non-compliant examples
2222
[source,html]
2323
----
24-
<!-- Using filename as alt text -->
25-
<img src="DSC1234.jpg" alt="DSC1234.jpg">
24+
<!-- Alt text matches filename -->
25+
<img src="sunset.jpg" alt="sunset.jpg">
2626
27-
<!-- Using file path as alt text -->
28-
<img src="/images/team/john-smith.png" alt="john-smith.png">
27+
<!-- Alt text matches filename without extension -->
28+
<img src="photo.png" alt="photo">
2929
30-
<!-- Using generic image name -->
31-
<img src="banner.jpg" alt="banner">
30+
<!-- Generic filename used as alt -->
31+
<img src="DSC_0123.jpg" alt="DSC_0123.jpg">
3232
33-
<!-- Using filename with underscores -->
34-
<img src="company_logo_2023.png" alt="company_logo_2023.png">
33+
<!-- Filename with path used as alt -->
34+
<img src="/images/team/john-smith.png" alt="john-smith.png">
3535
----
3636
37-
These examples use filenames or file paths as alt text, which provides no meaningful information about the image content.
37+
These examples use filenames as alt text, which provides no meaningful information about the image content.
3838
3939
.Compliant examples
4040
[source,html]
4141
----
42-
<!-- Descriptive alt text for a photo -->
43-
<img src="DSC1234.jpg" alt="Students working together in the library">
42+
<!-- Descriptive alt text instead of filename -->
43+
<img src="sunset.jpg" alt="Vibrant orange sunset over ocean waves">
4444
45-
<!-- Meaningful description for a team member -->
46-
<img src="/images/team/john-smith.png" alt="John Smith, Senior Developer">
45+
<!-- Meaningful description instead of generic name -->
46+
<img src="photo.png" alt="Team celebrating product launch">
4747
48-
<!-- Descriptive banner text -->
49-
<img src="banner.jpg" alt="Welcome to our 2023 Conference">
48+
<!-- Descriptive text instead of camera filename -->
49+
<img src="DSC_0123.jpg" alt="Students collaborating in the library">
5050
51-
<!-- Proper company logo description -->
52-
<img src="company_logo_2023.png" alt="TechCorp Logo">
51+
<!-- Meaningful description for a team member -->
52+
<img src="/images/team/john-smith.png" alt="John Smith, Senior Developer">
5353
----
5454
5555
These examples use descriptive alt text that explains what the image shows or represents.

‎modules/ROOT/partials/a11y-rules/i4.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[I4]]
22
==== I4 - Overly long `+alt+` text
33

4-
*Rule description:* this rule checks for `+alt+` text that exceeds the configured character limit (default: 150 characters). Long descriptions may overwhelm screen reader users and should be replaced with concise summaries, with more detail provided in surrounding content if necessary.
4+
*Rule description:* this rule checks for `+alt+` text that exceeds the configured character limit (default: 150 characters). Long descriptions can be difficult for screen reader users to process. Complex images might need detailed descriptions in the surrounding text instead, though some images may require longer descriptions to be fully understood.
55

66
===== {pluginname} rule details - I4
77

‎modules/ROOT/partials/configuration/a11ychecker_allow_decorative_images.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ If `+a11ychecker_allow_decorative_images+` is not explicitly set, the value defi
5454

5555
*Type:* `+Boolean+`
5656

57-
*Default value:* `+false+`
57+
*Default value:* `+true+`
5858

5959
*Possible values:* `+true+`, `+false+`
6060

0 commit comments

Comments
 (0)