# All listing images have descriptive alt text

- **Pattern:** `ab-001026` (`directory-listing-schema.content-completeness.image-alt-text`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001026
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001026)

## 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.

```tsx
// 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 `img` tags with `alt=""` or missing `alt` attributes — automate this in CI using `axe-core`.

## Detection

- **ID:** `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:

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

## External references

- wcag 1.1.1
- section-508 502.3.3

Taxons: accessibility

HTML version: https://auditbuffet.com/patterns/ab-001026