Fix image-alt-words to only flag prefix patterns

Changed from word-anywhere matching to prefix-only regex. Now only
flags when words like "image", "photo", "icon" appear at the start
of alt text followed by "of", a separator, or as the entire text.
No longer flags natural usage like "Close icon for closing window"
or "Walmart Photo logo". Bump version to 0.8.5.

Author: ckundo

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accesslint/core",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Pure accessibility rule engine — WCAG audit with zero browser dependencies",
   "type": "module",
   "main": "./dist/index.cjs",

src/rules/text-alternatives/image-alt-words.test.ts

@@ -3,23 +3,55 @@ import { imageAltWords } from "./image-alt-words";
 import { makeDoc } from "../../test-helpers";
 
 describe("text-alternatives/image-alt-words", () => {
-  it("reports alt text containing 'image'", () => {
+  // --- Should flag (prefix patterns) ---
+  it("reports alt starting with 'image of'", () => {
     const doc = makeDoc('<img src="dog.jpg" alt="image of a dog">');
     const violations = imageAltWords.run(doc);
     expect(violations).toHaveLength(1);
     expect(violations[0].ruleId).toBe("text-alternatives/image-alt-words");
   });
 
-  it("reports alt text containing 'photo'", () => {
+  it("reports alt starting with 'photo of'", () => {
     const doc = makeDoc('<img src="team.jpg" alt="photo of team">');
     expect(imageAltWords.run(doc)).toHaveLength(1);
   });
 
-  it("reports alt text containing 'picture'", () => {
+  it("reports alt starting with 'picture of'", () => {
     const doc = makeDoc('<img src="sunset.jpg" alt="picture of sunset">');
     expect(imageAltWords.run(doc)).toHaveLength(1);
   });
 
+  it("reports alt starting with 'graphic of'", () => {
+    const doc = makeDoc('<img src="chart.png" alt="graphic of sales data">');
+    expect(imageAltWords.run(doc)).toHaveLength(1);
+  });
+
+  it("reports alt that is just 'icon'", () => {
+    const doc = makeDoc('<img src="x.png" alt="icon">');
+    expect(imageAltWords.run(doc)).toHaveLength(1);
+  });
+
+  it("reports alt that is just 'image'", () => {
+    const doc = makeDoc('<img src="x.png" alt="image">');
+    expect(imageAltWords.run(doc)).toHaveLength(1);
+  });
+
+  it("reports alt with separator 'photo: sunset'", () => {
+    const doc = makeDoc('<img src="x.jpg" alt="photo: sunset">');
+    expect(imageAltWords.run(doc)).toHaveLength(1);
+  });
+
+  it("reports alt with dash 'icon - search'", () => {
+    const doc = makeDoc('<img src="x.png" alt="icon - search">');
+    expect(imageAltWords.run(doc)).toHaveLength(1);
+  });
+
+  it("reports case-insensitive 'Image Of a dog'", () => {
+    const doc = makeDoc('<img src="x.jpg" alt="Image Of a dog">');
+    expect(imageAltWords.run(doc)).toHaveLength(1);
+  });
+
+  // --- Should NOT flag ---
   it("passes alt text without redundant words", () => {
     const doc = makeDoc('<img src="dog.jpg" alt="Golden retriever playing fetch">');
     expect(imageAltWords.run(doc)).toHaveLength(0);
@@ -30,8 +62,38 @@ describe("text-alternatives/image-alt-words", () => {
     expect(imageAltWords.run(doc)).toHaveLength(0);
   });
 
-  it("does not flag partial word matches", () => {
+  it("does not flag partial word matches like 'Imagination'", () => {
     const doc = makeDoc('<img src="x.jpg" alt="Imagination is key">');
     expect(imageAltWords.run(doc)).toHaveLength(0);
   });
+
+  it("skips 'icon' in middle: 'Close icon for closing window'", () => {
+    const doc = makeDoc('<img src="x.png" alt="Close icon for closing window">');
+    expect(imageAltWords.run(doc)).toHaveLength(0);
+  });
+
+  it("skips 'photo' as brand name: 'Walmart Photo logo'", () => {
+    const doc = makeDoc('<img src="x.png" alt="Walmart Photo logo">');
+    expect(imageAltWords.run(doc)).toHaveLength(0);
+  });
+
+  it("skips 'icon' at end: 'magnifying glass icon'", () => {
+    const doc = makeDoc('<img src="x.png" alt="magnifying glass icon">');
+    expect(imageAltWords.run(doc)).toHaveLength(0);
+  });
+
+  it("skips 'photo' in natural sentence: 'A family taking a photo'", () => {
+    const doc = makeDoc('<img src="x.jpg" alt="A family taking a photo">');
+    expect(imageAltWords.run(doc)).toHaveLength(0);
+  });
+
+  it("skips 'image' not at start: 'Brand image gallery'", () => {
+    const doc = makeDoc('<img src="x.jpg" alt="Brand image gallery">');
+    expect(imageAltWords.run(doc)).toHaveLength(0);
+  });
+
+  it("skips 'icon' followed by a regular word: 'Icon set for navigation'", () => {
+    const doc = makeDoc('<img src="x.png" alt="Icon set for navigation">');
+    expect(imageAltWords.run(doc)).toHaveLength(0);
+  });
 });

src/rules/text-alternatives/image-alt-words.ts

@@ -1,13 +1,23 @@
 import type { Rule } from "../types";
 import { getSelector, getHtmlSnippet } from "../utils/selector";
 
-const REDUNDANT_WORDS = ["image", "picture", "photo", "graphic", "icon", "img"];
+/**
+ * Matches alt text that starts with a self-referential word used as a prefix.
+ * Only flags when the word appears at the start and is followed by a
+ * preposition ("of"), a separator (: - — –), or is the entire alt text.
+ *
+ * Flags:   "image of a dog", "photo: sunset", "icon", "graphic"
+ * Skips:   "Close icon for closing window", "Walmart Photo logo",
+ *          "magnifying glass icon", "A family taking a photo"
+ */
+const REDUNDANT_PREFIX_RE =
+  /^(image|picture|photo|graphic|icon|img)(\s+of\b|\s*[:\u2013\u2014-]|\s*$)/i;
 
 /**
- * Checks if alt text contains self-referential words like "image" or "photo".
- * Screen readers already announce "image"/"graphic" before alt text, so these
- * words are redundant.  Separate from image-redundant-alt because axe-core
- * does not have an equivalent check.
+ * Checks if alt text starts with a self-referential prefix like "image of"
+ * or "photo:". Screen readers already announce "image"/"graphic" before alt
+ * text, so these prefixes are redundant.  Separate from image-redundant-alt
+ * because axe-core does not have an equivalent check.
  */
 export const imageAltWords: Rule = {
   id: "text-alternatives/image-alt-words",
@@ -18,25 +28,26 @@ export const imageAltWords: Rule = {
   fixability: "contextual",
   browserHint: "Screenshot the image to verify the alt text accurately describes it without filler words like 'image of'.",
   description:
-    "Image alt text should not contain words like 'image', 'photo', or 'picture' — screen readers already announce the element type.",
+    "Image alt text should not start with words like 'image of', 'photo of', or 'picture of' — screen readers already announce the element type.",
   guidance:
     "Screen readers already announce 'image' or 'graphic' before reading alt text, so phrases like 'image of', 'photo of', or 'picture of' are redundant. Remove these words and describe what the image shows. For example, change 'image of a dog' to 'golden retriever playing fetch'.",
   run(doc) {
     const violations = [];
     for (const img of doc.querySelectorAll("img[alt]")) {
-      const alt = img.getAttribute("alt")!.toLowerCase();
+      const alt = img.getAttribute("alt")!.trim();
       if (!alt) continue;
 
-      const found = REDUNDANT_WORDS.filter((w) => alt.split(/\s+/).includes(w));
-      if (found.length > 0) {
+      const match = alt.match(REDUNDANT_PREFIX_RE);
+      if (match) {
+        const word = match[1].toLowerCase();
         violations.push({
           ruleId: "text-alternatives/image-alt-words",
           selector: getSelector(img),
           html: getHtmlSnippet(img),
           impact: "minor" as const,
-          message: `Alt text "${img.getAttribute("alt")}" contains redundant word(s): ${found.join(", ")}.`,
-          context: `Current alt: "${img.getAttribute("alt")}", redundant word(s): ${found.join(", ")}`,
-          fix: { type: "suggest", suggestion: "Remove the redundant word(s) from the alt text; screen readers already announce the element as an image" } as const,
+          message: `Alt text "${alt}" starts with redundant prefix "${word}".`,
+          context: `Current alt: "${alt}", redundant prefix: "${word}"`,
+          fix: { type: "suggest", suggestion: "Remove the redundant prefix from the alt text; screen readers already announce the element as an image" } as const,
         });
       }
     }