Image Rules

Rules for validating image SEO and performance.

image-alt

Ensures all content images have descriptive alt text.

Checks

All <img> tags have alt attribute
Alt text is not empty
Alt text is descriptive (not just "image" or "photo")

AI Enhancement

When AI is enabled, generates alt text by analyzing images.

Examples

Pass:

<img src="hero.jpg" alt="Developer working on laptop in modern office">

Fail (missing):

<img src="hero.jpg">
<!-- Error: Image missing alt text: hero.jpg -->

Fail (empty):

<img src="hero.jpg" alt="">
<!-- Warning: Image has empty alt text (decorative?) -->

Fail (not descriptive):

<img src="hero.jpg" alt="image">
<!-- Warning: Alt text is not descriptive: "image" -->

Decorative Images

For purely decorative images, use empty alt:

<img src="decorative-divider.svg" alt="" role="presentation">

Configuration

rules: {
  'image-alt': {
    severity: 'error',
  },
}

image-dimensions

Checks images specify width and height to prevent layout shift.

Checks

<img> tags have width attribute
<img> tags have height attribute

Why It Matters

Without dimensions, the browser doesn't know how much space to reserve, causing Cumulative Layout Shift (CLS) when images load.

Examples

Pass:

<img src="photo.jpg" alt="..." width="800" height="600">

Pass (CSS aspect-ratio):

<img src="photo.jpg" alt="..." style="aspect-ratio: 4/3; width: 100%">

Fail:

<img src="photo.jpg" alt="...">
<!-- Warning: Image missing dimensions: photo.jpg -->

Configuration

rules: {
  'image-dimensions': {
    severity: 'warning',
  },
}

image-lazy-load

Recommends lazy loading for below-the-fold images.

Checks

Images not in first viewport have loading="lazy"
Hero/above-fold images should NOT be lazy loaded

Examples

Pass (below fold):

<img src="product.jpg" alt="..." loading="lazy">

Pass (above fold - no lazy):

<img src="hero.jpg" alt="...">
<!-- First image, should load immediately -->

Suggestion:

<img src="gallery-10.jpg" alt="...">
<!-- Info: Consider adding loading="lazy" for below-fold images -->

Configuration

rules: {
  'image-lazy-load': {
    severity: 'info',
  },
}

image-format

Suggests modern image formats for better performance.

Checks

Detects JPEG/PNG images
Suggests WebP or AVIF alternatives

Examples

Suggestion:

<img src="photo.jpg" alt="...">
<!-- Info: Consider using WebP or AVIF format for photo.jpg -->

Pass (modern format):

<img src="photo.webp" alt="...">
<img src="photo.avif" alt="...">

Best Practice (picture element):

<picture>
  <source srcset="photo.avif" type="image/avif">
  <source srcset="photo.webp" type="image/webp">
  <img src="photo.jpg" alt="...">
</picture>

Configuration

rules: {
  'image-format': {
    severity: 'info',
  },
}

Best Practices

Alt Text Guidelines

Image Type	Alt Text
Photos	Describe content: "Woman hiking in mountains"
Icons	Describe function: "Search"
Charts	Summarize data: "Sales increased 25% in Q4"
Decorative	Empty: `alt=""`
Logos	Company name: "Acme Inc logo"

Performance Checklist

All images have alt text
Dimensions specified (prevent CLS)
Below-fold images lazy loaded
Modern formats (WebP/AVIF) where possible
Responsive images with srcset

Example Optimized Image

<picture>
  <source
    srcset="photo-small.webp 400w, photo-large.webp 800w"
    type="image/webp"
    sizes="(max-width: 600px) 400px, 800px"
  >
  <img
    src="photo-large.jpg"
    alt="Developer working on laptop in modern office"
    width="800"
    height="600"
    loading="lazy"
  >
</picture>