Image audit rules: alt text, formats and lazy loading

Audit rules for images: alt text, file size, WebP and AVIF, srcset, lazy loading, and the width and height attributes that prevent layout shift.

Images rules cover the two things images most often break: page weight and layout. Weight is file size, format and whether the right size is served to the right screen; layout is the width and height attributes that reserve space before an image arrives. The category also carries the markup checks (alt attributes, picture fallbacks and figure captions) that decide whether an image means anything to a reader who cannot see it.

Run only these rules

squirrel audit https://example.com --rule-include images

A few image checks live in Performance instead: a lazy-loaded hero image, the hero’s fetch priority and preload, and eager images in hidden carousel slides. Run both with --rule-include images,perf.

Where to start

These carry the highest severity and weight in the category.

Oversized image files: the 200KB and 1MB thresholds: One unoptimised photo can outweigh every other asset on the page. squirrel measures the images the crawl fetched and reports the heavy ones.
<picture> without an <img>: the fallback that is required: A picture element with no img child renders nothing at all. squirrel checks every picture on the page for its required fallback.
Broken images: empty and placeholder src attributes: An img with an empty or placeholder src renders as a broken icon. squirrel collects image sources across the crawl and flags the malformed ones.
loading=lazy: which images need it and which must not: Images below the fold that load eagerly compete with the ones the visitor can see. squirrel treats the first few images as above the fold.
Missing alt attribute: what an empty alt means: An image with no alt attribute has no name for a screen reader. An empty alt is the correct way to say decorative, and squirrel accepts it.

Rules

Rule	What it flags	Severity	Scope
<picture> without an <img>: the fallback that is required	A picture element with no img child renders nothing at all. squirrel checks every picture on the page for its required fallback.	error	Per-page
Broken images: empty and placeholder src attributes	An img with an empty or placeholder src renders as a broken icon. squirrel collects image sources across the crawl and flags the malformed ones.	error	Site-wide
figure and figcaption: captions that are associated	A caption in a plain div is text near an image; a figcaption is the image’s caption. squirrel checks figures for captions and notes standalone images.	info	Per-page
Image aspect ratio mismatch: attributes versus the CSS box	When width and height describe one ratio and CSS forces another, the image stretches. squirrel compares the two and allows for object-fit.	warning	Per-page
Image optimization signals: CDNs and modern formats	squirrel reads image URLs for the marks of an optimization pipeline: a known image CDN, a modern format, or a format parameter in the query.	info	Per-page
Image width and height attributes: preventing layout shift	An image with no width and height reserves no space, so the page jumps when it loads. squirrel checks both attributes on every image.	warning	Per-page
IMG_1234.jpg: image filenames that describe nothing	A filename straight off a camera or a hash tells nobody what the picture is. squirrel matches image filenames against a list of generic patterns.	info	Per-page
Large inline SVG: when to move it to an external file	Inline SVG cannot be cached separately from the HTML, so a big one is paid for on every page view. squirrel measures inline SVG size per page.	info	Per-page
Lazy loading: how much of the page defers its load	A page-wide count of images and iframes using loading=lazy. squirrel reports the mix rather than judging individual images.	info	Per-page
loading=lazy: which images need it and which must not	Images below the fold that load eagerly compete with the ones the visitor can see. squirrel treats the first few images as above the fold.	warning	Per-page
Missing alt attribute: what an empty alt means	An image with no alt attribute has no name for a screen reader. An empty alt is the correct way to say decorative, and squirrel accepts it.	warning	Per-page
Oversized image files: the 200KB and 1MB thresholds	One unoptimised photo can outweigh every other asset on the page. squirrel measures the images the crawl fetched and reports the heavy ones.	error	Site-wide
srcset: serving the right image size for the screen	Without srcset every visitor downloads the same file, sized for the largest screen. squirrel counts responsive images against fixed-size ones.	info	Per-page
Thumbnails without srcset: small images serving large files	A 60 by 60 avatar that loads a 2000 pixel photo wastes almost all of it. squirrel reads each image’s real pixel size and flags small images that serve far more pixels than they display.	warning	Per-page
WebP and AVIF: converting from JPEG and PNG	WebP and AVIF encode the same picture in far fewer bytes than JPEG or PNG. squirrel counts modern and legacy formats per page.	info	Per-page

Key terms

Alt text: The alt attribute that gives an image a text alternative for screen readers, failed loads and search engines.
Broken link: A link whose target answers with an error, does not resolve, or is malformed.
Cumulative Layout Shift (CLS): A score for how much visible content moves unexpectedly while the page is in use; good is 0.1 or less.
HTTP status code: The three-digit code a server returns with every response; 2xx success, 3xx redirect, 4xx client error, 5xx server error.
Image width and height attributes: Declared width and height on <img> that let the browser reserve space before the file loads, preventing layout shift.
Lazy loading: Deferring off-screen images and iframes with loading=“lazy” so they load as the visitor scrolls.
Modern image formats: WebP and AVIF, which encode the same image in fewer bytes than JPEG or PNG.
Page weight: The total bytes a page downloads across HTML, CSS, JavaScript, images and fonts.
Responsive images: Serving differently sized image files with srcset, sizes and <picture> so each device downloads one that fits.
WCAG: The W3C’s Web Content Accessibility Guidelines, organised as testable success criteria at levels A, AA and AAA; 2.2 is current.

Performance covers the rest of page weight and the hero image’s loading hints. Accessibility checks the alt text on image buttons and embedded objects, and alt text that adds nothing, such as “photo of”. Links checks link targets, where Images checks image sources.

Learn more

Core Web Vitals guide, for how image size and dimensions feed LCP and CLS
Core Web Vitals checker
Sample report, with the Images section on a real site

Disable all Images rules

[rules]
disable = ["images/*"]

Edit this page