Image Aspect Ratio Mismatch

Flags images whose width/height attributes declare a different aspect ratio than their CSS box, which stretches or squishes the image.

What it detects

The rule compares two aspect ratios that are both declared in the HTML:

• The ratio from the width/height attributes (e.g. 1200x1500 = 4:5).
• The ratio fixed by the inline CSS: either an explicit width and height in px, or an aspect-ratio property (e.g. 1000x750 / aspect-ratio: 4/3 = 4:3).

When the two differ by more than the tolerance (default 5%) and no object-fit: cover/contain/scale-down/none compensates, the image renders distorted. Images without both attribute dimensions, with only relative CSS units (%, vw), or with height: auto (the recommended responsive pattern) are not flagged.

Solution

When an image’s width/height attributes describe one aspect ratio but CSS forces a different one, the image is stretched or squished. Set the width/height attributes to the image’s true aspect ratio, and let CSS size it with height: auto (or a matching ratio). If cropping is intended, add object-fit: cover so the image fills the box without distortion.

Configuration

[rules."images/aspect-mismatch"]
tolerance = 0.1

Enable / Disable

Disable this rule

[rules]
disable = ["images/aspect-mismatch"]

Disable all Images rules

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

Enable only this rule

[rules]
enable = ["images/aspect-mismatch"]
disable = ["*"]