The A11Y Project Checklist(a11yproject.com)
a11yproject.com
The A11Y Project Checklist
https://www.a11yproject.com/checklist/
53 comments
Thank you for saying this! I see stuff like this a lot here on HN and I almost never know what it means. A16z? Fuck if I know what that is.
It reminds me of the terrible sports video game naming - NBA2k22. I get Y2K was fewer characters than fully typing out "year 2000," so it kind of made sense. But 2k22 is the same number of characters as "2022". What is being saved here? It just creates confusion without adding anything useful.
It reminds me of the terrible sports video game naming - NBA2k22. I get Y2K was fewer characters than fully typing out "year 2000," so it kind of made sense. But 2k22 is the same number of characters as "2022". What is being saved here? It just creates confusion without adding anything useful.
It's called 2k in common parlance now, doesn't make sense from a branding perspective to change it
2K Games is the publisher.
I'm so bloody glad I'm not the only one!
To some extent it's just a name, and it's used across the industry. Similarly, "accessibility" doesn't scream "allow people with disabilities to use your product as well" - at some point, you just have to assume people either know what something means, or will figure it out as they go.
(In fact, "a11y" might even be better in that regard, in that it's clearly not a regular word, and thus might cause you to wonder what it means, whereas "accessibility" might lead you to make incorrect assumptions about what they're doing.)
(In fact, "a11y" might even be better in that regard, in that it's clearly not a regular word, and thus might cause you to wonder what it means, whereas "accessibility" might lead you to make incorrect assumptions about what they're doing.)
It's good advice for any abbreviation to define or provide the expanded form the first time it's used; The A11y Project does this in the top heading on its home page, "a11y stands for accessibility." It might be helpful for the project to include that explanation on every page, even if it's just in the footer.
"a11y" is useful as a hashtag, is shorter and easier to spell. A11y is a good search term; content containing "a11y" will be about digital accessibility. Content containing "accessibility" could be about DNS issues, account authorization, or a number of other topics even before search "helpfully" expands the search to include "accessible," "access," and other terms.
"a11y" is useful as a hashtag, is shorter and easier to spell. A11y is a good search term; content containing "a11y" will be about digital accessibility. Content containing "accessibility" could be about DNS issues, account authorization, or a number of other topics even before search "helpfully" expands the search to include "accessible," "access," and other terms.
Something similar happens nowadays in Spanish, where people use an X as a gender-neutral suffix. Ruining the experience for the visually impaired users that use screen readers. The irony of being 'inclusive' with the non-binary while being exclusive with the visually impaired
> in Spanish, where people use an X as a gender-neutral suffix
I very strongly doubt that this is "happening nowadays" since people speaking a language generally don't switch to using unpronouncable words in their daily affairs.
I very strongly doubt that this is "happening nowadays" since people speaking a language generally don't switch to using unpronouncable words in their daily affairs.
How much of that is non-Spanish speaking Americans imposing American ideas on the world?
And a screen reader would have no idea how to parse it without a special case... I've seen stuff tagged with this a lot and every so often someone mentions this issue and I've yet to find an explanation other than if you already know about it it's easier to search for.
I appreciate the advice nonetheless but it's just such an odd choice for making it discoverable.
I appreciate the advice nonetheless but it's just such an odd choice for making it discoverable.
Why would a screen reader have any more trouble with it than someone reading it normally? I usually read it as "ay-one-one-why" or "ally", is that how a screen reader would interpret it?
Right, it would read it as "ay-one-one-why". And if you're trying to dictate it, you'd have to say "ay-one-one-why".
I don't want to distract from the main point, which is that you should make your websites accessible and that doing so mostly involves not letting some UI designer use a cool trick that lets them do some cute effect that has the side effect of breaking the experience when using accessibility tools. Because they're usually written by people without a need for accessibility tools they don't even notice what they're doing. This is extremely important educational work.
And 'a11y' is less horizontal width, so someone who needs to zoom in really far to read text would probably appreciate it, or someone who can still type but doesn't do dictation has to hit fewer keys. But what other situation does it help with? It's jargon,
You have to just kind of know that there are 11 characters between the 'a' and the 'y' in accessibility? If the goal is to educate people who don't need accessibility tools themselves it should not be a challenge for people who aren't in the know to find the information. I appreciate the effort and recognize that it caught on. I just don't get why, it seems like it is throwing a needless barrier in the way of the target audience finding the resources.
I still try to follow the ideas presented, I just don't understand making it require jargon to find.
I don't want to distract from the main point, which is that you should make your websites accessible and that doing so mostly involves not letting some UI designer use a cool trick that lets them do some cute effect that has the side effect of breaking the experience when using accessibility tools. Because they're usually written by people without a need for accessibility tools they don't even notice what they're doing. This is extremely important educational work.
And 'a11y' is less horizontal width, so someone who needs to zoom in really far to read text would probably appreciate it, or someone who can still type but doesn't do dictation has to hit fewer keys. But what other situation does it help with? It's jargon,
You have to just kind of know that there are 11 characters between the 'a' and the 'y' in accessibility? If the goal is to educate people who don't need accessibility tools themselves it should not be a challenge for people who aren't in the know to find the information. I appreciate the effort and recognize that it caught on. I just don't get why, it seems like it is throwing a needless barrier in the way of the target audience finding the resources.
I still try to follow the ideas presented, I just don't understand making it require jargon to find.
I use a screen reader and it says "A eleven Y." (As in the letters being said out loud.) It's really not confusing.
This looks like a great resource. Human checklists are not perfect but they tend to be better than automated checks for this sort of thing.
But there is a common form of accessibility guideline that I have a problem with, and this one illustrates it well: "Avoid using the autofocus attribute." The problem here is it quietly pits users with special accessibility needs against the rest - "Just don't use feature X." OK, but what should I do instead for the rest of my users who benefited from feature X? What if I'm making a search engine landing page and I want to automatically focus the input on page load (and automatically bring up their keyboard if touchscreen)? Is there some other approach that achieves the same UX as the autofocus attribute but without creating accessibility problems?
According to MDN, "When autofocus is assigned, screen-readers 'teleport' their user to the form control without warning them beforehand." OK, but really? Why? Why don't they offer the user the option to not do that?
But there is a common form of accessibility guideline that I have a problem with, and this one illustrates it well: "Avoid using the autofocus attribute." The problem here is it quietly pits users with special accessibility needs against the rest - "Just don't use feature X." OK, but what should I do instead for the rest of my users who benefited from feature X? What if I'm making a search engine landing page and I want to automatically focus the input on page load (and automatically bring up their keyboard if touchscreen)? Is there some other approach that achieves the same UX as the autofocus attribute but without creating accessibility problems?
According to MDN, "When autofocus is assigned, screen-readers 'teleport' their user to the form control without warning them beforehand." OK, but really? Why? Why don't they offer the user the option to not do that?
I agree with the comment, but:
> Why? Why don't they offer the user the option to not do that?
A screen-reader doesn't replace the browser - it just responds to changes in focus by reading out a description of the currently focused item. It should be the browser that offers an option to disable autofocus. Firefox does seem to have an option in about:config called "browser.autofocus" which I assume does this exact thing.
> Why? Why don't they offer the user the option to not do that?
A screen-reader doesn't replace the browser - it just responds to changes in focus by reading out a description of the currently focused item. It should be the browser that offers an option to disable autofocus. Firefox does seem to have an option in about:config called "browser.autofocus" which I assume does this exact thing.
The screen reader could still choose to ignore the automatic focus and read the whole page instead.
How? The accessibility APIs in question just tell the screen reader when the focus changes, it doesn't say why it changed. I'm sure theres a hacky way to make it work for specific browsers, but it's the wrong place to solve the issue.
Checklists are not a place for nuance. A search engine landing page is a place where using autofocus in the search field is perfectly appropriate; autofocusing a search field that's in the header of every page is not.
I agree, autofocusing a search field that's in the header of every page is not generally appropriate, but that's not specifically about accessibility. It would be annoying for anyone on a mobile device (keyboard pops up on every page), and the focus ring and/or blinking cursor would be distracting.
What about cases where it is appropriate to autofocus the search input (as it's the primary action on the page) but where there also might (sometimes) be an important text notice above the search input? Sighted users would see the notice fine, while screenreader users would be 'teleported' (MDN's word) straight past it, missing the notice.
What about cases where it is appropriate to autofocus the search input (as it's the primary action on the page) but where there also might (sometimes) be an important text notice above the search input? Sighted users would see the notice fine, while screenreader users would be 'teleported' (MDN's word) straight past it, missing the notice.
I believe it's up to screen reader developers to come up with innovative ways of making the web as it currently exists more usable, rather than requiring the millions of websites out there to accommodate the technology's current limitations. In this case, perhaps screen readers need to somehow intelligently read nearby text when a control immediately receives focus on page load.
No. Browsers already parse the page to produce an accessibility tree that's provided through the operating system's accessibility API. Screen readers attempting to supplement what's provided through that API by re-parsing the page should be a last resort and is bound to be error-prone.
Designers and developers need to learn that what they make will be, and should be, experienced in ways different than how they do. Content is experienced linearly, not always in two dimensions, and semantics can make programmatically explicit what is only implied visually (like heading text being bigger and bolder).
The prevalence of smartphones and responsive design have helped somewhat to expand people's understanding of how using digital experiences can vary. There's a lot more that can be learned.
Aside from not using autofocus on the input field at all, another existing option is to programmatically associate the preceding block of text by giving the block a unique id and referencing it from the input using an aria-describedby attribute; after a screen reader reads the input's accessible name, it will read the associated description.
Designers and developers need to learn that what they make will be, and should be, experienced in ways different than how they do. Content is experienced linearly, not always in two dimensions, and semantics can make programmatically explicit what is only implied visually (like heading text being bigger and bolder).
The prevalence of smartphones and responsive design have helped somewhat to expand people's understanding of how using digital experiences can vary. There's a lot more that can be learned.
Aside from not using autofocus on the input field at all, another existing option is to programmatically associate the preceding block of text by giving the block a unique id and referencing it from the input using an aria-describedby attribute; after a screen reader reads the input's accessible name, it will read the associated description.
> while screenreader users would be 'teleported' (MDN's word) straight past it, missing the notice.
Autofocus in that case seems like reasonable and expected behavior. Isn't it up to the tools (e.g. screen reader, etc) to accommodate the expected behavior, rather than for the reasonable and expected behavior to change?
Autofocus in that case seems like reasonable and expected behavior. Isn't it up to the tools (e.g. screen reader, etc) to accommodate the expected behavior, rather than for the reasonable and expected behavior to change?
No. It is reasonable and expected that some users experience page content linearly so designers and developers have to create experiences that takes that into account. That includes not skipping important content. If it's important, don't skip it. If it's not important, maybe it's okay to skip it but there should be means for users to explore and discover what's on the page (like give the preceding block of text a heading that indicates what that section of content is about).
Hmm. "All users should experience the page linearly because some do" is not really an argument that works.
A sighted user with a cursor or touchscreen can be as non-linear as the size of the viewport and the layout allows.
All designers should design the linear experience as well as the non-linear experience because the linear is all some users will have. Responsive design is a move in that direction, a smartphone portrait display is much narrower than a laptop display so the content tends to be in a more linear layout. Experiences through voice assistants are also linear.
All designers should design the linear experience as well as the non-linear experience because the linear is all some users will have. Responsive design is a move in that direction, a smartphone portrait display is much narrower than a laptop display so the content tends to be in a more linear layout. Experiences through voice assistants are also linear.
Let's just step back and state our terms. Are we agreeing that website placing the cursor in a search box is an example of autofocus?
I believe it is reasonable to do this if there is no other purpose for the page.
If I understand correctly, it is your contention this is unreasonable because it will skip all of the other information about the page for screen readers.
My question is why screen readers cannot, or should not, handle this special case? Isn't there an argument that it helps users with hand-eye coordination problems? I am absolutely for a11y, but when there is a trade-off in degraded experience for the majority, I'd like to hear arguments why the interpretive tools used by the minority cannot handle that interpretation.
I believe it is reasonable to do this if there is no other purpose for the page.
If I understand correctly, it is your contention this is unreasonable because it will skip all of the other information about the page for screen readers.
My question is why screen readers cannot, or should not, handle this special case? Isn't there an argument that it helps users with hand-eye coordination problems? I am absolutely for a11y, but when there is a trade-off in degraded experience for the majority, I'd like to hear arguments why the interpretive tools used by the minority cannot handle that interpretation.
I have no particular disability at the moment and I’m struggling to think of anything that autofocus adds to my browsing experience and not struggling to think of times it’s annoyed me.
On the other hand, I am endlessly annoyed when e.g. Ebay / Amazon do not auto focus the search box on page load. Anything else I'm going to click and probably 50% of the time I want to search. Just auto-focus please.
> it quietly pits users with special accessibility needs against the rest
Not just that; it pits users with one accessibility need against users with another. (Or I guess, not "pits" so much, sometimes needs just conflict.) For example, for someone with motor impairments, having to control the mouse (or pressing Tab a lot) to focus an input field rather than being able to use their keyboard right away is not a great experience.
Not just that; it pits users with one accessibility need against users with another. (Or I guess, not "pits" so much, sometimes needs just conflict.) For example, for someone with motor impairments, having to control the mouse (or pressing Tab a lot) to focus an input field rather than being able to use their keyboard right away is not a great experience.
I don't remember which site has autofocus for the username and I absolutely HATE IT, specially because it did that after a small delay - probably loading all js and crap - so it would change the focus from the PASSWORD field to the user field.
The work of the project is great and I'm grateful for the tools they produce, which I have used. But bit surprised to see some of the low hanging fruit from their own list not being applied in the project's own site. Just a few things I spotted in couple of minutes:
The colour contrast of the title section fails all tests. The title itself is so big that it requires scanning the full width of the monitor regardless of font scaling; and the introductory paragraph (and header navigation) is placed over the top of the title, obscuring it. I also thought uppercase text-transform was best avoided. The checkboxes themselves move when you open/close the details/summary blocks which is disorientating. You can't tab onto the citation links (maybe up for debate).
I take this topic seriously, so this isn't just flippant. Unfortunately if you want others to take these things seriously too, you need to practice what you preach.
The colour contrast of the title section fails all tests. The title itself is so big that it requires scanning the full width of the monitor regardless of font scaling; and the introductory paragraph (and header navigation) is placed over the top of the title, obscuring it. I also thought uppercase text-transform was best avoided. The checkboxes themselves move when you open/close the details/summary blocks which is disorientating. You can't tab onto the citation links (maybe up for debate).
I take this topic seriously, so this isn't just flippant. Unfortunately if you want others to take these things seriously too, you need to practice what you preach.
> The colour contrast of the title section fails all tests.
It doesn't. The background color is --color-blue: #3b4bbf and the SVG's fill color is --color-blue-tint: #d4d8f2, a 5.1:1 contrast ratio.
Having the top-level page titles replicated as such giant SVGs is probably overdoing it but the user also has the page title in the browser tab and the word "Checklist" underlined in the main navigation to locate themselves (the actual h1 heading for the page is visually hidden contains "Checklist."
I didn't find a viewport size/shape that had the overlapping you're describing, maybe their design has a problem they didn't find and you could report it to them [0].
> I also thought uppercase text-transform was best avoided
Do you mean on "Check your WCAG compliance?" Making all the text on a page or full sentences all uppercase can make it hard to read, I don't think you have to pretend `text-transform: uppercase` doesn't exist. It's definitely better to use the property to make text uppercase as a design choice vs. actually writing the text using all capital letters, at least some of the time browsers and assistive technologies can treat them differently.
I think the A11y Project in particular tries to reach designers and developers who often think "accessibility" means making sites plain, boring, and/or ugly. Therefore, they've adopted a design that is more capital "D" Designed on their top-level pages; that may mean not making everything maximally accessible 100% of the time. Additionally, people will always disagree about design choices.
[0] https://github.com/a11yproject/a11yproject.com/
It doesn't. The background color is --color-blue: #3b4bbf and the SVG's fill color is --color-blue-tint: #d4d8f2, a 5.1:1 contrast ratio.
Having the top-level page titles replicated as such giant SVGs is probably overdoing it but the user also has the page title in the browser tab and the word "Checklist" underlined in the main navigation to locate themselves (the actual h1 heading for the page is visually hidden contains "Checklist."
I didn't find a viewport size/shape that had the overlapping you're describing, maybe their design has a problem they didn't find and you could report it to them [0].
> I also thought uppercase text-transform was best avoided
Do you mean on "Check your WCAG compliance?" Making all the text on a page or full sentences all uppercase can make it hard to read, I don't think you have to pretend `text-transform: uppercase` doesn't exist. It's definitely better to use the property to make text uppercase as a design choice vs. actually writing the text using all capital letters, at least some of the time browsers and assistive technologies can treat them differently.
I think the A11y Project in particular tries to reach designers and developers who often think "accessibility" means making sites plain, boring, and/or ugly. Therefore, they've adopted a design that is more capital "D" Designed on their top-level pages; that may mean not making everything maximally accessible 100% of the time. Additionally, people will always disagree about design choices.
[0] https://github.com/a11yproject/a11yproject.com/
Agreed. Contrast with an accessibility website that actually practices what it preaches: https://webaim.org/
How is A-11-y any more accessible a word than accessibility? The "replace-the-middle-with-numbers" shortening scheme makes absolutely no sense, is confusing for anyone that doesn't already know, and saving space is absolutely not an issue in this post-paper era. Just why? Who thought this was a good idea?
FWIW, at least one prominent accessibility advocate in the blind community agrees: https://mosen.org/make-accessibility-discussion-more-accessi...
Who thought this was a good idea? Probably people who had to type “accessibility” out a dozen times a day. Also marketing minded people who know a memorable title keeps people thinking about the topic longer.
Side note, numeronyms have been around for a long time. This isn’t something we just invented for a11y.
Also side note: I personally love “a11y” because it makes me think of “ally”, which is what we would all be to people with special needs if we religiously adopted a11y.
Side note, numeronyms have been around for a long time. This isn’t something we just invented for a11y.
Also side note: I personally love “a11y” because it makes me think of “ally”, which is what we would all be to people with special needs if we religiously adopted a11y.
The voice in my head that narrates whatever I read pronounced it "ally" from the start- it didn't read it as "A-eleven-why" until someone mentioned it, so if nothing else it had the desired effect on me!
I've had to work on a11y efforts. One challenge I see is that some websites/apps are not overly usable for people that don't have disabilities. Also, many of the calls on what needs to happen or not are subjective when getting an audit and go far beyond this list guidelines. Then on top of that if you are big enough, or get in someones crosshairs, you face the threat of the DOJ making an example of your company based on a number of standards (beyond this checklist) that are nebulous.
> if you are big enough, or get in someones crosshairs, you face the threat of the DOJ making an example of your company based on a number of standards (beyond this checklist) that are nebulous.
Nonsense. This checklist relates all its items with WCAG criteria; basically all legal requirements directly cite WCAG or have requirements based on them. Even though meeting all WCAG criteria does not guarantee that every person in the world can use the content, no entity is going to get sued for that.
Also, the checklist is preceded by "Does this checklist guarantee my site is accessible? No. However, addressing the issues called out in this checklist will help improve the experience for everyone who uses your site."
Nonsense. This checklist relates all its items with WCAG criteria; basically all legal requirements directly cite WCAG or have requirements based on them. Even though meeting all WCAG criteria does not guarantee that every person in the world can use the content, no entity is going to get sued for that.
Also, the checklist is preceded by "Does this checklist guarantee my site is accessible? No. However, addressing the issues called out in this checklist will help improve the experience for everyone who uses your site."
Is there an automatic scanner that reports problems like Google’s Lighthouse?
I use https://wave.webaim.org/extension/ with good results
Most accessibility problems require human review to identify.
Google Lighthouse uses a subset of the checks included in axe-core. axe-core is a good resource for adding accessibility checks to e2e testing. The WAVE extension already mentioned is good for getting feedback about a page in the browser, the axe DeveTools extension is also good, the paid version can guide more manuals checks, simplifying the process.
Google Lighthouse uses a subset of the checks included in axe-core. axe-core is a good resource for adding accessibility checks to e2e testing. The WAVE extension already mentioned is good for getting feedback about a page in the browser, the axe DeveTools extension is also good, the paid version can guide more manuals checks, simplifying the process.
I wrote Evaluatory [1] for this, which started mainly as an axe-core wrapper (which is what Lighthouse uses as well) with a visual results page. Now it contains more tools and checks as well.
[1] https://darekkay.com/evaluatory/
[1] https://darekkay.com/evaluatory/
Looks like a fit for a project I have. Is there a simple way to configure for authenticated pages?
Basic Auth should work out-of-the-box, though I haven't tested it. If you need any advanced authentication, Playwright [0] - which I use for fetching the pages - shoud have you covered. You can pass any custom playwright options via `playwrightOptions` in the Evaluatory config file.
[0] https://playwright.dev/
[0] https://playwright.dev/
It's a good thing you're looking for an automated solution, because with that attitude you're not going to find any accessibility problems on your own :P
https://www.w3.org/WAI/ER/tools/
https://www.w3.org/WAI/ER/tools/
you can use the WAVE extension that will check things for you automatically
What an ugly design for such a page
looks fucking awesome imo. It's an all-text page that someone clearly spent some time on the typography and layout for. Simple layout, easy to navigate, super fast. What are you looking for instead?
Looks fucking disgusting IMO. It's an all-text page that has been vomited on by a "designer" and is now unreadable. Text is great. This page is not accessible to me; honestly it feels like my eyes are being assaulted by this garish abomination.
(I typed this out before checking: rendering is just broken for latest FF on Win10. The color palette is entirely different from what's intended, and looks like a very crappy dark mode. The site looks much nicer in Edge. Edit: probably depends on your browser's preferred color scheme: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pref....)
Here are some specific design flaws. This is not exhaustive, and I'm trying to stick to the more objective issues:
- On the title section, the "Check your WCAG compliance" text box with the same background color as the div behind it, placed above the massive "CHECKLIST" text, combined with the disjointed placement of the Table of Contents immediately makes the page look like it has some broken rendering going on.
- Wildly inconsistent margins between different sections of content. Nothing is well-aligned on a grid between regions of the page.
- The light grey <p> text on the grey background is low-contrast, and hard to read as a result.
- The blue background of the <code> blocks is jarring, as it looks similar to selected/highlighted text.
- Far, far too much padding and line spacing. Very little content fits into view at once on a 720p screen.
It is one of the worst designed websites I've seen in a while.
Here are some specific design flaws. This is not exhaustive, and I'm trying to stick to the more objective issues:
- On the title section, the "Check your WCAG compliance" text box with the same background color as the div behind it, placed above the massive "CHECKLIST" text, combined with the disjointed placement of the Table of Contents immediately makes the page look like it has some broken rendering going on.
- Wildly inconsistent margins between different sections of content. Nothing is well-aligned on a grid between regions of the page.
- The light grey <p> text on the grey background is low-contrast, and hard to read as a result.
- The blue background of the <code> blocks is jarring, as it looks similar to selected/highlighted text.
- Far, far too much padding and line spacing. Very little content fits into view at once on a 720p screen.
It is one of the worst designed websites I've seen in a while.
However I didn't know we had a team doing that. why? because they called themselves "a11y". I thought it was an analytics team, or and inside joke name. I would see a11y requests, commits and infra changes, but I didn't twig what it was for.
I had seen the team lead talk about accessibility in meetings, and I knew that it was very close to their heart, they'd even given conference talks about it.
It was only when the team lead changed roles, and I had a catchup with them and asked them what the team name meant. They looked at me and said "its like i8n, you know what that is, you fiddle with it all the time" When I looked blank they said: "you know changing locales and stuff" you mean in Internationalization? Then the penny dropped.
a11y == accessibility.
the irony of having the least accessible name, for improving accessibility.