All Images Have Descriptive Alt Text

Issue No: 42

Category: Image Analysis

Issue type: Issue

Priority: CRITICAL

Description

This audit verifies that image elements include meaningful alt text so screen readers and search engines can understand image purpose. Missing or non-descriptive alt text harms accessibility and weakens image context signals.

How do we capture it

1. Fetch the final page URL using HTTP GET and store final status and raw HTML.
2. Parse raw HTML without JavaScript execution.
3. Extract all <img> elements and capture src, alt, aria-label, role, and nearby context where needed for diagnostics.
4. Classify each image into one of these groups:
   • descriptive alt present,
   • empty alt (alt="") for decorative intent,
   • missing alt attribute,
   • non-descriptive alt (for example generic placeholders such as "image", "photo", "img", filename-only strings).
5. Store the imagesWithoutAlt field as image URLs where alt attribute is missing.
6. Store additional diagnostics for non-descriptive alt values that exist but are low quality.
7. Compute page-level coverage metrics for descriptive alt usage.
8. Trigger issue when required alt coverage fails thresholds or missing-alt count is non-zero for meaningful images.
9. Persist representative failing URLs and alt values for remediation.
10. Store parsing/fetch errors to avoid silent false negatives.

Constraint: The crawler evaluates only raw HTML attributes. It does not infer alt text from rendered DOM, OCR, or JavaScript-generated content.

What to store

Field	Type	Comment
total_images_detected	INT DEFAULT 0	Total count of <img> elements evaluated.
images_with_alt	INT DEFAULT 0	Count of images with an explicit alt attribute present.
images_without_alt	INT DEFAULT 0	Count of images where alt attribute is missing.
images_empty_alt	INT DEFAULT 0	Count of images with empty alt used for decorative intent.
images_with_descriptive_alt	INT DEFAULT 0	Count of images with meaningful descriptive alt text.
images_with_non_descriptive_alt	INT DEFAULT 0	Count of images with low-quality alt text (generic or filename-only).
descriptive_alt_ratio	DECIMAL(5,2)	Percentage of images with descriptive alt text.
imagesWithoutAlt	TEXT[]	List of image URLs missing alt attribute (required diagnostic field).
non_descriptive_alt_samples	TEXT[]	Samples of low-quality alt values for remediation guidance.
alt_text_issue_triggered	BOOLEAN DEFAULT FALSE	Final boolean indicating alt-text compliance failure.
trigger_reason	TEXT	Primary reason code for why the issue fired.
capture_error_detail	TEXT	Fetch or parse diagnostics for troubleshooting.

Condition for trigger

Trigger this issue when images are missing alt text or alt text quality is materially insufficient.

• Trigger Rule 1: Missing Alt Attribute Detected

  • Target Field: alt_text_issue_triggered
  • Evaluation Logic: images_without_alt > 0
  • Severity: CRITICAL
  • Diagnostic Message: "Some images are missing alt attributes. Screen readers and crawlers may miss image meaning."

• Trigger Rule 2: Non-Descriptive Alt Dominates

  • Target Field: alt_text_issue_triggered
  • Evaluation Logic: images_with_non_descriptive_alt > 0 AND descriptive_alt_ratio < 80.00
  • Severity: WARNING
  • Diagnostic Message: "Alt text quality is weak; many image descriptions are generic or non-informative."

• Trigger Rule 3: Severe Accessibility Gap

  • Target Field: alt_text_issue_triggered
  • Evaluation Logic: images_without_alt >= 5
  • Severity: CRITICAL
  • Diagnostic Message: "A high number of images are missing alt text, creating a major accessibility and SEO risk."

• Trigger Rule 4: Final Issue State

  • Target Field: alt_text_issue_triggered
  • Evaluation Logic: alt_text_issue_triggered = TRUE
  • Severity: CRITICAL
  • Diagnostic Message: "Image alt-text compliance failed; update missing or non-descriptive alt values."

Sources

• W3C WAI: Images Tutorial (Alt text): https://www.w3.org/WAI/tutorials/images/
• W3C WCAG 2.2 Understanding 1.1.1 Non-text Content: https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html
• MDN: <img> element and alt attribute: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img
• Google Search Central: Image SEO best practices: https://developers.google.com/search/docs/appearance/google-images

Long description

Alt text is essential for accessibility and contributes to image understanding in search systems. For users of assistive technologies, alt text communicates the meaning or function of visual content that is otherwise inaccessible.

From an SEO perspective, descriptive alt text helps search engines interpret image context and improve relevance for image discovery. Missing or generic alt text reduces semantic clarity and can degrade both accessibility outcomes and image search performance.

Common failure scenarios checked by the crawler:

• <img> tags missing alt entirely.
• Placeholder alt values like "image", "photo", or repeated boilerplate.
• Alt text copied directly from filename tokens with no descriptive meaning.
• CMS workflows that do not enforce alt input on upload.
• Decorative images incorrectly receiving noisy alt text instead of empty alt.

How to Fix

1. Add alt attributes to all meaningful images and describe purpose, not just appearance.
2. Use empty alt (alt="") only for purely decorative images.
3. Avoid generic placeholders and filename-based alt values.
4. Enforce alt-text requirements in CMS/editor workflows.
5. Re-crawl and confirm imagesWithoutAlt is empty and descriptive coverage is improved.