Merge pull request #1704 from equalizedigital/claude/update-gutenberg-rules-VFZ0M

Add role="none" support alongside role="presentation" in image alt checks

Author: SteveJonesDev

includes/classes/Rules/Rule/ImgAltEmptyRule.php

@@ -37,10 +37,11 @@ public static function get_rule(): array {
 			),
 			'why_it_matters'        => esc_html__( 'Screen readers rely on alternative text to describe images to users who cannot see them. If the alt attribute is empty, it signals that the image is decorative and should be skipped. However, if a meaningful image has an empty alt attribute, users with visual impairments will miss important information. Proper use of alternative text improves accessibility and ensures all users can understand the content.', 'accessibility-checker' ),
 			'how_to_fix'            => sprintf(
-			// translators: %1$s is <code>alt=""</code> and %2$s is <code>role="presentation"</code>.
-				esc_html__( 'Review the image to determine if it is decorative. If it is decorative, it is correct to use an empty %1$s attribute and you can dismiss this warning by using the "Ignore" feature in Accessibility Checker or adding %2$s to the image and rescanning the page. If the image conveys information, add descriptive alt text that communicates the image\'s purpose or meaning.', 'accessibility-checker' ),
+			// translators: %1$s is <code>alt=""</code>, %2$s is <code>role="presentation"</code>, and %3$s is <code>role="none"</code>.
+				esc_html__( 'Review the image to determine if it is decorative. If it is decorative, it is correct to use an empty %1$s attribute and you can dismiss this warning by using the "Ignore" feature in Accessibility Checker or adding %2$s or %3$s to the image and rescanning the page. If the image conveys information, add descriptive alt text that communicates the image\'s purpose or meaning.', 'accessibility-checker' ),
 				'<code>alt=""</code>',
 				'<code>role="presentation"</code>',
+				'<code>role="none"</code>',
 			),
 			'references'            => [
 				[

src/pageScanner/checks/img-alt-empty-check.js

@@ -9,17 +9,6 @@ export default {
 		// Check if alt attribute is empty string (not missing, but explicitly empty)
 		const hasEmptyAlt = node.hasAttribute( 'alt' ) && node.getAttribute( 'alt' ) === '';
 
-		// Skip if element has presentation role
-		if (
-			hasEmptyAlt &&
-			(
-				node.getAttribute( 'role' ) === 'presentation' ||
-				node.getAttribute( 'role' ) === 'none'
-			)
-		) {
-			return true;
-		}
-
 		// Skip if aria-hidden is true
 		if ( hasEmptyAlt && node.getAttribute( 'aria-hidden' ) === 'true' ) {
 			return true;

src/pageScanner/checks/img-alt-missing-check.js

@@ -18,13 +18,6 @@ export default {
 		// Get the tag name
 		const tagName = node.tagName.toLowerCase();
 
-		// Handle role="presentation"
-		if ( node.hasAttribute( 'role' ) && node.getAttribute( 'role' ) === 'presentation' ) {
-			// Images with role="presentation" are intentionally hidden from screen readers,
-			// so missing alt text is acceptable in this case
-			return false;
-		}
-
 		// Handle aria-hidden="true"
 		if ( node.hasAttribute( 'aria-hidden' ) && node.getAttribute( 'aria-hidden' ) === 'true' ) {
 			// Images with aria-hidden="true" are not exposed to assistive technologies,

src/pageScanner/checks/linked-image-alt-not-empty.js

@@ -29,10 +29,10 @@ export default {
 		// Check each visible image for non-empty alt text
 		return images.every( ( img ) => {
 			const alt = img.getAttribute( 'alt' );
-			const role = img.getAttribute( 'role' );
+			const roleTokens = ( img.getAttribute( 'role' ) || '' ).toLowerCase().split( /\s+/ );
 			const ariaHidden = img.getAttribute( 'aria-hidden' );
 
-			if ( role === 'presentation' || ariaHidden === 'true' ) {
+			if ( roleTokens.includes( 'presentation' ) || roleTokens.includes( 'none' ) || ariaHidden === 'true' ) {
 				return true;
 			}
 

src/pageScanner/checks/linked-image-alt-present.js

@@ -29,10 +29,10 @@ export default {
 		// Check each visible image for alt attribute
 		return images.every( ( img ) => {
 			const hasAlt = img.hasAttribute( 'alt' );
-			const role = img.getAttribute( 'role' );
+			const roleTokens = ( img.getAttribute( 'role' ) || '' ).toLowerCase().split( /\s+/ );
 			const ariaHidden = img.getAttribute( 'aria-hidden' );
 
-			return hasAlt || role === 'presentation' || ariaHidden === 'true';
+			return hasAlt || roleTokens.includes( 'presentation' ) || roleTokens.includes( 'none' ) || ariaHidden === 'true';
 		} );
 	},
 };

src/pageScanner/rules/img-alt-empty.js

@@ -5,7 +5,7 @@
 
 export default {
 	id: 'img_alt_empty',
-	selector: 'img[alt=""], input[type="image"][alt=""]',
+	selector: 'img[alt=""]:not([role~="none"]):not([role~="presentation"]), input[type="image"][alt=""]:not([role~="none"]):not([role~="presentation"])',
 	excludeHidden: true,
 	tags: [ 'cat.text-alternatives', 'wcag1a', 'wcag111' ],
 	all: [],

src/pageScanner/rules/img-alt-missing.js

@@ -5,7 +5,7 @@
 
 export default {
 	id: 'img_alt_missing',
-	selector: 'img, input[type="image"]',
+	selector: 'img:not([role~="none"]):not([role~="presentation"]), input[type="image"]:not([role~="none"]):not([role~="presentation"])',
 	excludeHidden: true,
 	any: [],
 	all: [],

tests/jest/rules/imgAltEmpty.test.js

@@ -66,6 +66,11 @@ describe( 'Image Alt Empty Validation', () => {
 			html: '<img src="decorative.jpg" alt="" role="none">',
 			shouldPass: true,
 		},
+		{
+			name: 'should pass for img with role="none presentation" (multi-value token)',
+			html: '<img src="decorative.jpg" alt="" role="none presentation">',
+			shouldPass: true,
+		},
 		{
 			name: 'should pass for img without alt attribute',
 			html: '<img src="test.jpg">',

tests/jest/rules/imgAltMissing.test.js

@@ -55,6 +55,16 @@ describe( 'Image Alt Missing Validation', () => {
 			html: '<img src="test.jpg" role="presentation">',
 			shouldPass: true,
 		},
+		{
+			name: 'should pass for img with role="none"',
+			html: '<img src="test.jpg" role="none">',
+			shouldPass: true,
+		},
+		{
+			name: 'should pass for img with role="none presentation" (multi-value token)',
+			html: '<img src="test.jpg" role="none presentation">',
+			shouldPass: true,
+		},
 		{
 			name: 'should pass for img with aria-hidden="true"',
 			html: '<img src="test.jpg" aria-hidden="true">',

tests/jest/rules/imgLinkedAltEmpty.test.js

@@ -61,6 +61,16 @@ describe( 'Linked Image Empty Alternative Text Rule', () => {
 			html: '<a href="page.html"><img src="decorative.jpg" role="presentation" alt=""></a>',
 			shouldPass: true,
 		},
+		{
+			name: 'passes when image has role="none"',
+			html: '<a href="page.html"><img src="decorative.jpg" role="none" alt=""></a>',
+			shouldPass: true,
+		},
+		{
+			name: 'passes when image has role="none presentation" (multi-value token)',
+			html: '<a href="page.html"><img src="decorative.jpg" role="none presentation" alt=""></a>',
+			shouldPass: true,
+		},
 		{
 			name: 'passes when image has aria-hidden="true"',
 			html: '<a href="page.html"><img src="decorative.jpg" aria-hidden="true" alt=""></a>',