Write alt text with the picture open

Alt text is the sentence a screen reader says in place of a picture. It is one attribute, it is usually written last, and it is the piece of a page most likely to be filled with whatever the camera called the file. This page is where you write that sentence and where it gets read back to you honestly.

Say plainly what that means before you open anything: you do the naming. There is no step here where a machine looks at your photograph and proposes the first clause, and no release of this site in which one is hidden behind a button. Recognition needs a vision model, a vision model needs weights, and none are published behind this build — so rather than dress that up, the site is built around the part that is solvable.

The solvable part is the reading. A great deal of what goes wrong in alt text is structural — a redundant opening, a file name nobody replaced, a keyword list, a sentence that runs past what a listener will sit through — and structure is something a program checks reliably. Every finding here names the problem and the edit in the same breath, the grade is nothing but the sum of the findings, and the whole thing re-runs on every keystroke, so there is no button to press and no point at which you have finished and find out you have not.

Between the picture and the writing sits arithmetic. Opening a file here gets you its shape, its tone, its dominant colour families, how much of the frame sits on an edge and how many distinct colours survive a coarse quantisation. None of that is recognition and none of it is dressed as recognition. It is the set of facts a person writing alt text keeps stopping to look at, plus a skeleton with the subject left blank — blank because the subject is the one thing nothing on this page can see.

The file is read where it sits. The browser decodes it, the orientation flag is resolved before anything is measured — a photograph narrated sideways is described with total confidence and total wrongness — and the working copy is scaled down to a thumbnail no longer than 192 pixels for the measurements. Resolution is irrelevant to everything this page does, which is why the megapixel guardrails cost it nothing: a sixty-megapixel photograph and a one-megapixel one are the same thumbnail by the time they are measured.

Then the reading runs, and keeps running. Every keystroke re-grades the field, so there is no button to press and no moment where you have finished and find out you have not. Findings are ordered by what they cost: the ones that stop the image working, then the ones that waste the listener’s time, then the conventions. A grade sits beside them and is nothing more than the sum of what was found — a letter with no findings under it would be a number, and numbers do not get pictures described.

Eight containers decode through machinery your browser already has: JPG, PNG, WebP, GIF, BMP, TIFF, ICO and AVIF. The ninth is the one your phone probably writes. A HEIC has no native decoder in most browsers, so this page carries a WebAssembly one and collects it only at the moment a HEIC turns up — which means the cost lands on the visit that needs it and on no other.

Three container details change what the page says. A format that can hold more than one frame gets a note saying only the first was read, because a description of frame one of an animation is a description of one ninetieth of the file. Transparency is composited onto mid-grey rather than white before anything is measured, so a white logo on an empty background still has edges to count instead of disappearing. And a four-component JPEG — CMYK or YCCK — is converted on the way in, because a description of an inverted decode is a description of a photograph nobody took.

Past roughly 32 megapixels, or 16 on iOS, the page offers a lighter working copy as a question with two reasonable answers rather than as a refusal. Past 100, or 40 on iOS, it declines and says by how much. Since everything here is measured on a thumbnail, agreeing to the lighter copy costs you nothing at all.

Both are limits of what is actually built, not modesty about it.

• It reads scenes, not words. Signs, receipts and screenshots come back as a refusal and a short explanation of why, and the letters are not transcribed here. That boundary is deliberate and it is enforced in the product rather than merely left off the feature list — a page that quietly turned into a text reader would be a worse version of something that already exists elsewhere.
• The checker reads your sentence, not your photograph. It can tell you that a string is too long, repeats itself, opens with a phrase that gets announced twice, or is a file name nobody replaced. It cannot tell you that you wrote 'three people' when there are four, or that the dog is a fox. Nothing on this page has seen the subject, so nothing on this page can mark you wrong about it.

Does this write the alt text for me?

No. This is a checker and a writing surface, not a captioner. Recognising what is in a photograph takes a vision model, a vision model takes weights, and there are none behind this build — so rather than a button that cannot work, you get the measurements, a skeleton with the subject left blank, and a reading of whatever you type. The naming is yours from the first word, and the site is built on the assumption that it should be.

What is the checker catching that I would not catch by reading it?

Catching the seven or eight failures that survive a careful read because they are invisible on the page and only audible through a screen reader. A leading 'Photo of' that gets announced twice. A file name that nobody replaced. Punctuation that runs one sentence into the next. A caption sitting under the image saying the same words. None of those look wrong in a browser; all of them cost a listener something.

Why 125 characters, and why is going over it only a note?

Because it is a working convention rather than a requirement. No success criterion in WCAG names a length at all, and the figure comes from what older screen-reader configurations would read in one pass. A photograph carrying real detail is allowed to run past it, and the checker marks it in amber rather than red for exactly that reason. There is a page on this site about where the number came from.

What happens if I open a screenshot?

The page refuses, and shows you the arithmetic behind the refusal — the proportion of pixels at pure black or white, the edge count and how few distinct colours the image uses. Reading letters back out of an image is a different job and it is not done here. If the file really is a photograph that happens to be very high contrast, you can still write the alt text yourself and the checker will still read it.

Is an empty alt attribute ever the right answer?

Often. A rule, a flourish, a spacer or an image that repeats the sentence beside it should be announced as nothing at all, and the way to say nothing is an attribute that is present with an empty value. Tick the decorative switch and the checker inverts: empty becomes correct and a description becomes the fault it is.

Does anything I type here get sent anywhere?

No, and there is nowhere for it to go — this site is a set of static files with no server behind it and no route that accepts a request. The picture is decoded by the browser, measured, and forgotten when the tab closes. The text stays in the field until you copy it.

Three other routes run the same checker with a different ruleset, because a caption, a long description and an alt attribute are three different jobs that happen to start from one picture. Which ruleset is loaded is the only thing that changes between them; the measurements, the refusal and the grading are shared.

• Alt text checkerPaste alt text you already have and read the findings. No picture required.
• CaptionThe visible line under a picture, read back against the job a caption actually has.
• Long descriptionThe paragraph a chart or a diagram needs when one attribute cannot hold it.

A finding has room for a problem and a fix, and that is all it should have. It has no room for where the 125-character convention came from, or for why a screen reader saying “graphic” before your first word changes what the first word should be, or for the difference between what WCAG 1.1.1 actually requires and what an auditor has been told to look for. Four pages carry that, and the index below says which one answers which question.

They are worth reading in the order they are listed there rather than in the order the findings send you to them. The length page is what most people come for; the one about images that should say nothing at all is the one that changes how people write.

• GuidesFour written pages on the standards, the conventions, and what no checker can judge.
• How long alt text should beWhere 125 characters came from, and the cases that are allowed to break it.
• What a screen reader announcesThe order NVDA, JAWS and VoiceOver read an image in, and what they add themselves.
• When the right alt text is noneThe images that want an empty attribute, and why describing them is worse.
• WCAG 1.1.1 and GIGW, in plain termsWhat the success criterion asks for and what an Indian government audit checks.