Alt text checker rules

Every rule the checker on this site applies, in the order it reports them. 36 rules: 6 that stop an image working, 12 that cost the listener something, 17 conventions, and 1 that reports a correct empty alt. Each one has a stable id, which is what a finding links to.

The grade is 100 points minus 60 for each blocker, 18 for each problem and 6 for each convention: A from 90, B from 78, C from 62, D from 45, E below. A mechanical repair (spacing, a redundant opening, a trailing role noun, a missing full stop) is offered only when no blocker is present. The examples below are run through the real checker every time the site is built, and the build fails if one stops doing what it says.

No text at all empty
Stops the image working · alt text, caption, long description
The field is empty and the image has not been marked decorative (or, for a caption or long description, there is nothing to check).
Fires on
(empty)
The checker says: The image has no text alternative at all.
Does not fire on
“A red bicycle leaning on a blue wall.”
The fix
Either describe what the image tells the reader, or mark it decorative and ship alt="". Those are the only two correct answers, and a missing attribute is neither.
Decorative and empty decorative-empty
Correct · alt text
The image is marked decorative and the alt is empty. This is the correct answer, reported as a pass.
Fires on
(empty) — marked decorative
The checker says: Empty is the right value for an image that carries no information.
Does not fire on
(empty)
The fix
Ship alt="" — the attribute present and the value empty. Removing the attribute instead makes some screen readers read the file name aloud.
Decorative but described decorative-described
Stops the image working · alt text
The image is marked decorative and still carries a description.
Fires on
“A gold divider line.” — marked decorative
The checker says: This image is marked as decorative and still carries a description.
Does not fire on
“A gold divider line.”
The fix
Clear the field. A decorative image announced with a description interrupts the sentence around it for no gain — that is the case for alt="" rather than an argument against it.
File name used as text filename
Stops the image working · alt text, caption, long description
The text ends in an image file extension or starts like a camera file name (IMG_, DSC, PXL, Screenshot followed by a number).
Fires on
“IMG_4021.jpg”
The checker says: This is a file name, not a description.
Does not fire on
“A boy flying a red kite on a beach.”
The fix
Say what is in the frame. A listener hearing IMG underscore four thousand and twenty-one learns nothing except that nobody wrote the alt text.
Same as the file name filename-match
Stops the image working · alt text, caption, long description
The text and the file name are the same string, ignoring case.
Fires on
“harbour at dawn” — file name “harbour at dawn”
The checker says: The alt text and the file name are the same string.
Does not fire on
“Fishing boats moored in a harbour at dawn.” — file name “harbour at dawn”
The fix
Describe the picture instead. The file name is already available to anyone who needs it and is not a description of anything.
Placeholder word placeholder
Stops the image working · alt text, caption, long description
The whole text is a placeholder such as "image", "photo", "logo", "alt text", "untitled", "spacer" or "n/a".
Fires on
“image”
The checker says: "image" names the kind of thing, not the thing.
Does not fire on
“A tabby cat asleep on a windowsill.”
The fix
Replace it with what this particular image shows. If it shows nothing worth saying, it is decorative and wants an empty attribute.
Too short to picture too-short
Costs the listener something · alt text, caption, long description
Fewer than 8 characters for alt text, 10 for a caption, 180 for a long description.
Fires on
“Dog.”
The checker says: 4 characters is not enough to picture anything.
Does not fire on
“A dog asleep on a rug.”
The fix
Name the subject and what it is doing. Two of those three clauses is usually the difference between a label and a description.
Past one announcement over-hard
Costs the listener something · alt text, caption, long description
More than 250 characters for alt text, 400 for a caption, 4,000 for a long description.
Fires on
“A crowded vegetable market in the early morning, with traders sitting behind heaps of tomatoes, onions and green chillies on jute sacks, customers bargaining under faded blue tarpaulins, and a delivery cart of cauliflowers waiting at the edge of the lane beside a tea stall. Steam rises from the kettle.”
The checker says: 303 characters is past the point where this is still one announcement.
Does not fire on
“A crowded vegetable market in the early morning, traders behind heaps of tomatoes and onions.”
The fix
Cut the alt down to the one sentence that says why the image is on the page, and move the rest into a long description the page links to.
Past the working guideline over-guideline
Convention · alt text, caption, long description
More than 125 characters for alt text (200 for a caption, 1,500 for a long description), but under the hard limit.
Fires on
“A crowded vegetable market in the early morning, with traders sitting behind heaps of tomatoes, onions and green chillies on jute sacks.”
The checker says: 136 characters, against a working guideline of 125.
Does not fire on
“A crowded vegetable market in the early morning.”
The fix
This is a guideline and not a rule — a chart or a photograph carrying real detail is allowed to run past it. Check that every clause is doing work, then leave it if it is.
Announced twice redundant-prefix
Costs the listener something · alt text
The alt opens with "image of", "photo of", "picture showing" and similar.
Fires on
“Image of a woman reading a map on a train.”
The checker says: "Image of" is announced twice.
Does not fire on
“A woman reading a map on a train.”
The fix
A screen reader says "graphic" or "image" from the element itself before it reads a word of your text, so the listener hears the category, then hears it again. Start at the subject.
Role noun at the end trailing-role
Convention · alt text
The alt ends with a role noun such as "photo", "image" or "banner".
Fires on
“Sunset over the harbour photo”
The checker says: The string ends with "photo", which repeats what the element already announced.
Does not fire on
“Sunset over the harbour.”
The fix
Drop the last word. It reads as a file-library habit rather than a description.
A word repeated repetition
Costs the listener something · alt text, caption, long description
With six or more content words, one of them appears three or more times.
Fires on
“Cheap shoes, red shoes, running shoes and walking boots on sale.”
The checker says: "shoes" appears 3 times in 11 words.
Does not fire on
“Red running shoes on a wooden floor.”
The fix
Say it once. Repetition here is measured as repetition, not matched against a list of forbidden words — the fix is the same either way.
Few words doing all the work low-variety
Convention · alt text, caption, long description
With six or more content words, fewer than 62% of them are different words.
Fires on
“Green hills, green trees, tall hills, tall trees.”
The checker says: The same few words carry most of this string.
Does not fire on
“Green hills under a grey sky after rain.”
The fix
Rewrite it as one plain sentence and see how much of it survives.
Keyword list keyword-list
Costs the listener something · alt text
Four or more comma-separated fragments with no verb between them.
Fires on
“Beach, sunset, palm trees, ocean, holiday”
The checker says: 5 comma-separated fragments and no verb between them.
Does not fire on
“Palm trees stand on a beach at sunset.”
The fix
This reads out as a keyword list, one item at a time, with no sentence to hold them together. Write what is happening in the picture instead; the keywords survive inside the sentence.
Stray whitespace whitespace
Convention · alt text, caption, long description
Leading or trailing spaces, or two spaces in a row.
Fires on
“␠A cat on a mat.␠”
The checker says: There is stray whitespace in the value.
Does not fire on
“A cat on a mat.”
The fix
Trim it and collapse the double spaces. Some assistive technology reads a run of spaces as a pause that was not intended.
Line break or tab newline
Costs the listener something · alt text, caption, long description
The text contains a line break or a tab character.
Fires on
“A cat↵on a mat.”
The checker says: The value contains a line break or a tab.
Does not fire on
“A cat on a mat.”
The fix
Put it on one line. An attribute with a newline in it survives the parser and then behaves differently in every tool that reads it.
Markup or entity markup
Costs the listener something · alt text, caption, long description
The text contains < or >, or an unresolved HTML entity such as &amp;.
Fires on
“A <b>red</b> door.”
The checker says: There is markup or an unresolved HTML entity in the text.
Does not fire on
“A red door.”
The fix
Write the characters themselves. Alt text is read as plain text, so a tag is announced as its own contents and an entity is announced as ampersand a m p.
All capitals all-caps
Costs the listener something · alt text, caption, long description
The whole text is upper case, with at least four capital letters.
Fires on
“RED DOOR IN A WHITE WALL”
The checker says: The whole string is upper case.
Does not fire on
“Red door in a white wall.”
The fix
Use sentence case. Several screen readers treat a long run of capitals as an initialism and spell it out letter by letter.
Title case title-case
Convention · alt text, caption, long description
Four or more words and more than 70% of them start with a capital.
Fires on
“Red Door In A White Wall”
The checker says: Every Word Starts With A Capital.
Does not fire on
“Red door in a white wall.”
The fix
Use sentence case. Title case is a headline convention and this string is not a headline; it is a sentence that will be spoken.
No full stop no-terminal
Convention · alt text, caption, long description
Five or more words and no full stop, question mark or exclamation mark at the end.
Fires on
“A red door in a white wall”
The checker says: The sentence has no full stop at the end.
Does not fire on
“A red door in a white wall.”
The fix
Add one. It is the difference between a pause and the alt text running straight into whatever text follows the image.
Repeated punctuation punct-run
Convention · alt text, caption, long description
Two or more ! or ? in a row, or four or more full stops.
Fires on
“A red door!!”
The checker says: There is a run of repeated punctuation.
Does not fire on
“A red door!”
The fix
Reduce it to one mark. Repeated punctuation is either skipped or announced individually, and neither is what you meant.
Lower-case start lower-start
Convention · alt text, caption, long description
Five or more words and the first letter is lower case.
Fires on
“a red door in a white wall.”
The checker says: The sentence starts in lower case.
Does not fire on
“A red door in a white wall.”
The fix
Capitalise the first letter, so the string reads as a sentence wherever it is displayed as well as spoken.
Same as the caption caption-duplicate
Costs the listener something · alt text, caption, long description
The text and the caption beside the image are the same sentence, ignoring case and punctuation.
Fires on
“Fishing boats at dawn.” — caption “Fishing boats at dawn.”
The checker says: The alt text and the caption beside it are the same sentence.
Does not fire on
“Three fishing boats moored in a grey harbour.” — caption “Fishing boats at dawn.”
The fix
A caption is already read out as page text, so the listener hears it twice in a row. Either empty the alt and let the caption do the work, or make the alt describe what the caption does not.
Linked image with no name linked-empty
Stops the image working · alt text
The image is the whole of a link and its alt is empty.
Fires on
(empty) — inside a link
The checker says: This image is the whole of a link and has no text alternative.
Does not fire on
“DescribePhoto home page” — inside a link
The fix
Describe where the link goes, not what the picture looks like. An empty alt on a linked image leaves the link with no accessible name at all.
Link filler link-filler
Costs the listener something · alt text
A linked image's alt contains "click here", "read more", "learn more" or similar.
Fires on
“Click here” — inside a link
The checker says: The alt text of a linked image reads as generic link filler.
Does not fire on
“The 2026 annual report” — inside a link
The fix
Name the destination. Someone tabbing a list of links hears only these strings, with no surrounding sentence to tell them apart.
Role word inside role-word
Convention · alt text
The alt contains "image", "picture", "photo", "graphic", "icon", "button" or "link" somewhere other than the opening.
Fires on
“A photo frame on a desk.”
The checker says: The word "photo" appears inside the description.
Does not fire on
“A wooden frame on a desk.”
The fix
Check it is there because the picture really contains one, not because the sentence is describing the element. The element announces itself.
Caption names itself caption-prefix
Convention · caption
A caption opens with "photo of", "image of" and similar.
Fires on
“Photo of the new bridge at night.”
The checker says: The caption opens by naming itself as a picture.
Does not fire on
“The new bridge at night.”
The fix
The reader can see it is a picture. Spend the opening words on what is happening instead.
Caption without an end mark caption-fragment
Convention · caption
A caption of five or more words with no end mark.
Fires on
“Crowds gather at the new bridge on opening day”
The checker says: The caption is a sentence without an end mark.
Does not fire on
“Crowds gather at the new bridge on opening day.”
The fix
Finish it. A caption is visible text and is read by everyone, so it is held to the same standard as the paragraph above it.
One long sentence long-one-sentence
Costs the listener something · long description
A long description over 200 characters that is a single sentence.
Fires on
“The bar chart compares monthly rainfall in Chennai and Mumbai across 2025 with Mumbai far ahead from June to September and Chennai ahead only in October and November when the north-east monsoon arrives over the Coromandel coast.”
The checker says: Two hundred characters and one sentence.
Does not fire on
“The bar chart compares monthly rainfall in Chennai and Mumbai across 2025. Mumbai is far ahead from June to September. Chennai is ahead only in October and November, when the north-east monsoon arrives.”
The fix
Split it. A long description is listened to in order and cannot be re-read at a glance, so each sentence should be able to stand on its own.
A sentence over 240 characters long-sentence
Convention · long description
Any sentence in a long description runs past 240 characters.
Fires on
“The chart has two series. The bar chart compares monthly rainfall in Chennai and Mumbai across 2025 with Mumbai far ahead from June to September and Chennai ahead only in October and November when the north-east monsoon arrives over the Coromandel coast, and both series fall away sharply in December when the dry season sets in across the peninsula.”
The checker says: The longest sentence runs to 324 characters.
Does not fire on
“The chart has two series. Mumbai is far ahead from June to September. Chennai is ahead only in October and November, when the north-east monsoon arrives over the Coromandel coast.”
The fix
Break it at the first clause that could be its own statement. Nothing is lost and the listener gets somewhere to breathe.
Detail before the summary long-no-summary
Convention · long description
A long description of two or more sentences whose first sentence does not say what the whole is ("the chart", "the diagram", "overall", "this shows" and similar).
Fires on
“Sales rose 12% in March and stayed high through May. They fell in June after the monsoon began, and recovered only partly by September.”
The checker says: The first sentence goes straight to detail.
Does not fire on
“The chart shows monthly sales for 2026. Sales rose 12% in March and stayed high through May, fell in June and recovered only partly by September.”
The fix
Open with what the whole thing is and what it is for, then go into the parts. Someone listening needs the shape before the numbers.
Says who someone is identity-claim
Costs the listener something · alt text, caption, long description
The text names or ranks a person rather than describing them: "celebrity", "famous", "actor", "politician", "a man named …" and similar identity words. A problem in text you typed; a blocker in a machine suggestion, which may never identify anyone.
Fires on
“A famous actor waving from a balcony.”
The checker says: "famous" says who someone is, not what the picture shows.
Does not fire on
“A man in a white shirt waving from a balcony.”
The fix
Name a person only when you know who it is and the page needs it, and say it as a fact you know (a caption is often the better place). Never guess fame or identity from a face.
A feeling stated as fact emotion-as-fact
Convention · alt text, caption, long description
An emotion word directly before a person noun: "a happy woman", "sad children", "an angry man".
Fires on
“A happy woman holding a basket of mangoes.”
The checker says: "happy woman" states a feeling; a picture shows only an expression.
Does not fire on
“A woman smiling, holding a basket of mangoes.”
The fix
Say what is visible: "woman smiling" rather than "happy woman".
Only colours colour-only
Convention · alt text
Every word of the alt text, apart from small words, is a colour or a colour qualifier.
Fires on
“Blue and orange.”
The checker says: The alt text names only colours.
Does not fire on
“A blue fishing boat with an orange sail.”
The fix
Colours are a detail, not a subject. Say what the picture is of first, then the colour if it matters.
A count from a model unverified-count
Convention · alt text, caption, long description
Only on a machine suggestion: it counts more than three of something ("five people", "12 birds").
Fires on
“Five people sitting on a bench.”
The checker says: The suggestion counts 5 of something.
Does not fire on
“Five people sitting on a bench.”
The fix
Counts above three are where small models are least reliable; check against the picture.
Price or offer in product alt text price-or-offer
Convention · alt text
Only on /product-alt-text: the alt contains a price or a sales phrase ("₹499", "50% off", "sale", "free shipping").
Fires on
“Blue cotton kurta, front view, 50% off.”
The checker says: "50% off" is a price or an offer, not something in the photograph.
Does not fire on
“Blue cotton kurta, front view.”
The fix
Keep prices and offers in the product text, where they can change. Alt text says what the photo shows: the product, its colour, the view.

Alt text checker rules

No text at all `empty`

Decorative and empty `decorative-empty`

Decorative but described `decorative-described`

File name used as text `filename`

Same as the file name `filename-match`

Placeholder word `placeholder`

Too short to picture `too-short`

Past one announcement `over-hard`

Past the working guideline `over-guideline`

Announced twice `redundant-prefix`

Role noun at the end `trailing-role`

A word repeated `repetition`

Few words doing all the work `low-variety`

Keyword list `keyword-list`

Stray whitespace `whitespace`

Line break or tab `newline`

Markup or entity `markup`

All capitals `all-caps`

Title case `title-case`

No full stop `no-terminal`

Repeated punctuation `punct-run`

Lower-case start `lower-start`

Same as the caption `caption-duplicate`

Linked image with no name `linked-empty`

Link filler `link-filler`

Role word inside `role-word`

Caption names itself `caption-prefix`

Caption without an end mark `caption-fragment`

One long sentence `long-one-sentence`

A sentence over 240 characters `long-sentence`

Detail before the summary `long-no-summary`

Says who someone is `identity-claim`

A feeling stated as fact `emotion-as-fact`

Only colours `colour-only`

A count from a model `unverified-count`

Price or offer in product alt text `price-or-offer`

Where the rules run

Alt text checker rules

No text at all empty

Decorative and empty decorative-empty

Decorative but described decorative-described

File name used as text filename

Same as the file name filename-match

Placeholder word placeholder

Too short to picture too-short

Past one announcement over-hard

Past the working guideline over-guideline

Announced twice redundant-prefix

Role noun at the end trailing-role

A word repeated repetition

Few words doing all the work low-variety

Keyword list keyword-list

Stray whitespace whitespace

Line break or tab newline

Markup or entity markup

All capitals all-caps

Title case title-case

No full stop no-terminal

Repeated punctuation punct-run

Lower-case start lower-start

Same as the caption caption-duplicate

Linked image with no name linked-empty

Link filler link-filler

Role word inside role-word

Caption names itself caption-prefix

Caption without an end mark caption-fragment

One long sentence long-one-sentence

A sentence over 240 characters long-sentence

Detail before the summary long-no-summary

Says who someone is identity-claim

A feeling stated as fact emotion-as-fact

Only colours colour-only

A count from a model unverified-count

Price or offer in product alt text price-or-offer

Where the rules run

No text at all `empty`

Decorative and empty `decorative-empty`

Decorative but described `decorative-described`

File name used as text `filename`

Same as the file name `filename-match`

Placeholder word `placeholder`

Too short to picture `too-short`

Past one announcement `over-hard`

Past the working guideline `over-guideline`

Announced twice `redundant-prefix`

Role noun at the end `trailing-role`

A word repeated `repetition`

Few words doing all the work `low-variety`

Keyword list `keyword-list`

Stray whitespace `whitespace`

Line break or tab `newline`

Markup or entity `markup`

All capitals `all-caps`

Title case `title-case`

No full stop `no-terminal`

Repeated punctuation `punct-run`

Lower-case start `lower-start`

Same as the caption `caption-duplicate`

Linked image with no name `linked-empty`

Link filler `link-filler`

Role word inside `role-word`

Caption names itself `caption-prefix`

Caption without an end mark `caption-fragment`

One long sentence `long-one-sentence`

A sentence over 240 characters `long-sentence`

Detail before the summary `long-no-summary`

Says who someone is `identity-claim`

A feeling stated as fact `emotion-as-fact`

Only colours `colour-only`

A count from a model `unverified-count`

Price or offer in product alt text `price-or-offer`