Accessibility

The document is assembled, so the document is what gets read

A page here is put together out of components. A section supplies its own frame. A component supplies its own headings. A layout supplies the parts every page shares. No single source file contains the finished document, which means no check that reads a single source file can see the finished document either.

Heading order is a property of the assembled page, not of any file. So is a page frame nested inside another page frame, which is what happened on eleven pages here: the section already supplied the frame, the markup inside it supplied a second one, and every file involved was perfectly correct on its own. The contents started twenty four pixels further in than everything else and finished forty eight pixels narrower. Nothing you could open would have told you.

What was rejected, and what it would have cost

A linter reading the source was the obvious option and the wrong one. To know what a page will contain it would have to model what every component does, which means keeping a second description of the site alongside the first and hoping the two never disagree. The day they disagree is the day the check becomes worse than nothing, because it still passes.

A browser driven audit runner inside the build was the serious option. It genuinely catches things a static read cannot, and it was rejected for two reasons. It needs a browser in the build, which is slower and less reliable than reading a file, and slow unreliable checks get switched off. More importantly it produces a score. A score is a thing organisations improve rather than a thing they fix, and the distance between a good score and a page somebody can actually use is exactly where the interesting failures live. A list of named checks that either ran or did not is harder to game because there is nothing to average.

On every build, rather than on a schedule

A nightly run tells you a regression shipped. A run inside the build tells you it did not. That difference matters most for the failures no one would ever report. A contrast failure does not generate a support message. The reader simply does not read the sentence, and quite reasonably assumes it was not important. So the check has to sit before deployment, or it is a record of harm instead of a prevention of it.

What this design cannot see

Reading markup is not the same as seeing a page. Nothing in the built HTML tells you what colour a word ended up, how tall a control is once the browser has laid it out, or whether a line of text overflows its container at a particular width. Those questions are answered somewhere else entirely: the contrast ratios are computed from the design token values, the target sizes are measured in the component library that owns the controls, and the focus rings, the keyboard order and the skip link inside the application are held by the application's own suite, which resolves the stylesheet cascade rather than reading the markup, because a focus outline can be removed by a rule written three files away. Four separate suites hold the claims on this page and none of them holds more than its quarter. If you take one sentence from this section, take that one, because it explains why the list of what is checked is oddly shaped.

There is a second limit and it is harder to admit. A check computes against the surfaces someone listed. A colour placed on a surface that is not in that list is not safe because it passed. It is unmeasured, because no one asked the question. No test finds that for you. It is found the way the first one was found, by someone wondering whether the list was complete.

The exemptions, which are the part worth arguing with

Every check has carve outs written into it, and the carve outs are where a check quietly becomes weaker than its description. Ours are small and they are listed so that you can disagree with them rather than discover them.

The target size rule exempts a link sitting inside a sentence, which the standard permits and which is the difference between a readable paragraph and a paragraph of buttons. The accessible name rule accepts a link that wraps only an image, taking its name from that image instead, because that is what a browser does. It also accepts the wordmark in the header, which is an empty element with the logo applied as a mask and a written label attached, since there is no text there to read.

The illustration rule allows two outcomes and refuses the third. An illustration may be hidden from assistive technology or it may carry a name, and it may not be neither, because an unlabelled graphic that is not hidden is announced as an object with no description, which is worse than either choice made deliberately. That one is the exemption we would defend hardest, and it is also the one most likely to be wrong in some case no one has met yet.

Every result here is a negative one

A passing suite says a specific bad thing did not happen. No page skipped a heading level. No image is missing its attribute. No link is nameless. None of that says the headings are informative, the alternative text is accurate, or the link tells you where it goes. These checks raise the floor and say nothing whatever about the ceiling. The section on where a check passes and a person is still stuck, further down, is about the distance between the two.

The check that was missing until the day this was written

This page has said for some time that heading structure is checked by a test that reads the built pages. Until today no such test existed. The sentence sat in a list beside claims that were true, in the same typeface, and no one noticed that one of them was describing something that had never been written.

It exists now. It walks every heading on every built page in document order and fails the build if any level is more than one deeper than the one before it. It caught something on its first run: the product index went from its heading level one straight to thirteen level threes, because a grid of tiles carried headings with nothing above them to be under. To a reader using headings to move around, that page had thirteen answers and no question.

We are recording that here instead of editing the history, because a statement about testing that is itself untested is precisely the failure this page was written to argue against, and it happened on this page. If you find another sentence here in the same condition, the address below is the one to use.

A button that was present, correct and invisible

The one that started it. The main call to action was painted the same colour as the surface behind it. The element was there. It was the right size, in the right place, with the right label, and the label could not be seen. It was like that on twenty pages for an unknown number of deployments.

It was found by someone opening the site and looking, which is the part worth dwelling on. Looking had already happened many times without finding it, because a person who knows where a button is will see a button there. The check that holds it now compares colours as numbers, and numbers do not know where the button is meant to be.

A grey that measured 4.06 to 1

The muted text colour on this site, against one of its own backgrounds, came out at 4.06 to 1. The minimum is 4.5. It had been reviewed by eye repeatedly and looked entirely reasonable, because it is entirely reasonable looking. There is no version of a screenshot that tells you a colour is four hundredths under a threshold.

The check now computes the ratio for every text colour against every surface it can appear on, in both colour schemes, and fails the build under 4.5 to 1. It is the single most boring test in the repository and it has justified itself more than once.

Two hundred and sixty nine controls too small to hit

In the product, on a phone, two hundred and sixty nine interactive controls were under forty four pixels tall. Not a few of them. Effectively all of them, because the size came from one shared definition and the shared definition was wrong. Every screenshot of the product looked like a normal application, because a mouse pointer is one pixel wide and the person taking the screenshots was using one.

A table column that no keyboard could reach

The comparison tables scroll sideways on a narrow screen. Measured on the pricing page at three hundred and ninety pixels wide, the visible region was four hundred and thirty five pixels across and its contents were seven hundred and four. Something had to be off screen, and the something was the last column, which on a pricing table is the one a buyer is looking for.

A region that scrolls, with nothing focusable inside it and no place of its own in the tab order, cannot be scrolled without a pointer. That is a failure of a Level A criterion, 2.1.1, and it was on forty four pages. The fix is two attributes: a position in the tab order and a name, so that landing on it announces something instead of nothing. The check now refuses any scrolling region that has neither.

Status marks drawn in a colour meant for edges

The roadmap timeline says the state of an item is carried by its mark, then drew the hollow marks in a border colour. Measured against the two surfaces those marks sit on, that is 1.48 to 1 and 1.60 to 1: a hairline you can only find if you already know it is there. The two states drawn that way were not started and decided against, which are exactly the two a reader most needs to tell apart.

The check for this one does not compute a ratio. It enforces the choice: a mark that carries meaning may not take its colour from a border token, because border tokens exist for edges no one needs to see. Writing it that way means a future change to the grey scale cannot quietly undo the fix.

Thirteen headings under nothing

Described above, and it belongs in this list too. The heading order check was written on the day this section was, and immediately found a page that jumped two levels because a grid of tiles had no heading over it.

The pattern, which is the only general thing here

Every defect above was fully visible on screen and completely invisible to review. Not one of them was subtle in the browser. They were subtle to a person, which is a different property, and the difference is that a person arrives already knowing what the page is supposed to say.

The other thing they have in common is less comfortable. Not one of them was reported by someone who could not use the page. That is not a boast about response times. It means no one told us, and the most likely explanation is that the people these failures hurt most had not started using it yet. A defect that is discovered before anyone is harmed by it was still a defect for the whole time it existed.

The suite that holds these is not purely an accessibility suite. It also catches pages nothing links to, links pointing at hosts that do not exist, and page frames inside page frames. They sit together because the method is the same, not because the subject is. The method is that anything a person would have to notice will eventually not be noticed.

Write to hello@consonas.com. Describe what you were trying to do, what happened, and what you were using if you are willing to say. You do not have to explain the standard to us or prove that something is a problem.

You will get a reply from a person. We will tell you honestly whether it is something we can fix quickly, something that will take a while, or something we do not know how to fix yet. If it is the last of those we will say so rather than going quiet, which is the response people report getting most often and the one that is hardest to argue with.

Where we fix something, we will add a test for it, so that it is a defect that happened once rather than a defect that comes back. That is how every item in the enforced list above got there. The same rule governs the rest of the legal and security shelf: a page here describes what the product does today, and a sentence that stops being true is a defect worth reporting.