Skip to main content

All listing images have descriptive alt text

ab-001026 · directory-listing-schema.content-completeness.image-alt-text
Severity: highactive

Why it matters

WCAG 2.2 Success Criterion 1.1.1 requires all non-text content to have a text alternative — a failing grade on this check means your directory is inaccessible to blind users relying on screen readers. Section 508 (2018 Refresh) §502.3.3 extends this requirement to federally procured software. Beyond compliance, empty or generic alt text like alt="image" degrades image search indexing: Google uses alt text as primary signal for image SEO, and directories with poorly alt-tagged listing photos lose discoverability in Google Images where visual search drives significant business referral traffic.

Severity rationale

High because missing alt text is a WCAG 2.2 SC 1.1.1 failure that makes listing images invisible to screen readers, creating an accessibility barrier for blind users on every affected page.

Remediation

Generate descriptive alt text from listing data at render time — never rely on alt="" or omit the attribute entirely for content images. Decorative images are the only valid case for empty alt.

// components/listing/listing-image.tsx
<img
  src={listing.primaryImageUrl}
  alt={`${listing.name} - ${listing.category} in ${listing.city}`}
  width={800}
  height={600}
/>

For galleries, include an index: alt={\${listing.name} photo ${index + 1} of ${total}`}. Validate coverage by querying your rendered HTML for imgtags withalt=""or missingaltattributes — automate this in CI usingaxe-core`.

Detection

  • ID: directory-listing-schema.content-completeness.image-alt-text

  • Severity: high

  • What to look for: Count all listing images displayed in the UI. For each image, examine listing image elements. For each image on a listing page, check if it has an alt attribute with descriptive text (not just "image" or empty).

  • Pass criteria: All listing images have meaningful alt text describing what the image shows — 100% of images must have alt text of at least 5 characters. Report: "X listing images found, all Y have descriptive alt text."

  • Fail criteria: Images have no alt attribute, empty alt, or generic alt like "image".

  • Skip (N/A) when: Listings don't use images.

  • Detail on fail: Example: "5 of 10 listing images have empty alt attributes" or "All images use alt='photo'"

  • Remediation: Add descriptive alt text to all images:

    <img
  src={listing.imageUrl}
  alt={`${listing.name} - storefront photo`}
/>

External references

Taxons

accessibility

History