Accessibility Terms to Know Before You Pin a Contrast Issue

You spot a pale gray label on a white button and you want to flag it. If your comment says "this is hard to read," the developer reading it has to guess what you measured and what you want. If it says "contrast ratio looks under 4.5:1 on the Submit button label," they can check it and fix it. The difference is vocabulary. These are the terms a reviewer and a developer share on an accessibility pass, with a note on when each one matters.

The measurement terms you will cite most

Contrast ratio. A number comparing the luminance of text against its background, written as a ratio like 4.5:1. WCAG asks for at least 4.5:1 for normal text and 3:1 for large text. This is the term to use whenever color is the problem. Pin the exact element, name the ratio you suspect is too low, and say which text it applies to. "Low contrast" alone forces the developer to re-measure everything on the screen.

Target size. How big a tappable or clickable control is, measured in CSS pixels. WCAG's guidance is a minimum of 24 by 24 pixels, with exceptions. This matters most on phone layouts, where two links sit a few pixels apart and a thumb cannot land on one without hitting the other. Capture the phone view, drop a pin between the two controls, and say they are too close to tap reliably.

Focus order. The sequence in which keyboard focus moves through a page when you press Tab. It should follow the visible reading order. When it jumps from the header to a footer link and back up to a form, that is a focus order bug. You can only catch it by tabbing through yourself, so note the actual order you observed, not just "keyboard navigation is broken."

The structure terms a developer acts on

Landmark. A region of the page with a defined role: banner, navigation, main, contentinfo. Screen reader users jump between landmarks instead of scrolling. If a page has no main landmark, a screen reader user has no fast way to skip past the nav to the content. You will not see landmarks on screen, but you can flag the symptom: "no visible skip link, and the nav repeats before content on every page."

Alt text. The text alternative on an image, read aloud by a screen reader and shown when the image fails to load. A decorative image should have empty alt text so it is skipped; an informative image needs a description. When you flag a missing or wrong alt text, say which the image is, because the fix differs.

Accessible name. The label a control exposes to assistive technology, which may differ from its visible text. An icon-only button with no accessible name reads as "button" and nothing else. If you find a control that works by sight but gives no hint of its purpose, that is the term: the accessible name is missing or unhelpful.

Why a captured still carries these terms better than a note

Every one of these findings points at a specific spot: a button, a pair of links, a nav region. A written note describing the spot in words makes the developer hunt for it. A screenshot with a numbered pin on the exact element removes the hunt. Crop the still to the control in question, pin it, and type the term plus the measurement you suspect. That is the whole finding, and the person fixing it can act on it without a reply.

This is where capturing the pass as you go beats writing it up afterward. As you tab through the page or shrink it to a phone width, capture the screen at each problem, mark it, and keep moving. You can run the whole thing in a browser tab with an accessibility review captured in one pass, no install and no extension, and the output is a link the developer opens to see each pinned finding in order. For a worked example of the capture flow, see how to walk an accessibility pass end to end.

The terms that stop a fix before it starts

Two habits waste a developer's time even when your terms are right. The first is pinning a problem without the measurement: "contrast too low" with no ratio, so they have to re-check. The second is describing a layout in words the developer cannot map to code. A shared vocabulary for pointing at a specific button or region saves that round trip, and the common ways these reviews stall are worth reading before you send one: see the accessibility findings that a developer cannot act on.

If a signed-in owner wants the finding tracked, the same review can go to a repository as a GitHub issue with the screenshots attached. The reviewer link stays free to try, with unlimited reviews and no password. After seven days a review goes read-only for you, though the link you sent keeps working and comments keep flowing; Pro at $5 a month or $50 a year keeps everything editable and reopens read-only reviews instantly.

Before your next pass, pick the three terms above you reach for most and write them exactly, with a number, on the pin. Start a review, capture the first issue, and name it precisely enough that the developer never has to ask what you meant.

Send us feedback

Stuck, or want to do something it won't let you? Tell us what you're trying to do and we'll reply by email as soon as we can. This isn't a live chat.

Powered by AcornReply