cehfisher / a11y-style-guide

Accessibility (A11Y) Style Guide

A11Y Style Guide

This application is a living style guide or pattern library, generated from KSS documented styles...with an accessibility twist. No matter your level of development or accessibility expertise, there are ways to help contribute to the a11y style guide.

See a live demo of the style guide.

Why did this project start?

We wear a lot of hats as front-end developers. Depending on the client or company you work for, you may be the designer, UX/UI specialist, site-builder, QA tester, and developer all rolled into one. How can we possibly add the accessibility hat on top of all that? What accessible pieces should we even include? Which pieces are easy wins vs. impossible juggernauts? How do we implement inclusive design and development when a project does not have a lot of time or budget to include that piece?

One way we can tackle these issues is by using an accessible component driven approach. By thinking about inclusiveness from the start, we can get a head start on accessibility while still building the required site components.

The A11Y style guide comes with pre-populated accessible components that include helpful links to related tools, articles, and WCAG guidelines to make your site more inclusive. These components also serve as a guide for both HTML markup and SCSS/CSS code, to inform designers, front-end and back-end developers at every stage of the website’s creation.

How do you use this tool?

• As a reference.
• As a base for your own style guide.
• As a base for creating your own accessible components.
• As a base for a new accessible theme.
• Contribute to the style guide and make it better.

Really? What can't you do with it is an easier question?

How can you contribute?

Please see the Contributing Guide for more information.

How did you get here?

Maybe you are a total beginner and wondering where to start? That's cool...welcome! Learning accessibility can feel a bit like drinking out of a firehose, so here are some tips to follow on your journey toward accessibility: Getting Started with Website Accessibility or check out the Resources page. For more information on my past articles, conference talks, or to see some accessible SVGs in action, check out my personal website cariefisher.com

Thanks!

a11y-style-guide's Issues

Link focus component

add button to link focus example. point out bug @dengeist mentioned on Twitter https://codepen.io/dengeist/pen/LyomBb?editors=1100

Updates to Navbar Mobile Icon

Need to include some text with the hamburger icon (ex. Menu). Also need to include some accessibility points.

Open in new window indicator

Create open in new window graphic and theme to show users they are going to an external site. Primarily for resources/guidelines section.

Read more link examples - movie quote attributions are hidden from some users.

In the Read More link examples, the movie quote attributions are visually-hidden. Screen readers announce them,

These attributions are probably of interest to everyone, and hiding them from some users is a bad pattern to encourage in the style guide. It's unrelated to the main purpose of the read-more-links section of the guide.

http://a11y-style-guide.com/style-guide/section-general.html#kssref-general-read-more

e.g. The aria-describedby example has "This is a quote from the 1948 movie The Treasure of the Sierra Madre." wrapped in a p.visually-hidden element.

Suggestion: display the attributions visually. Blockquote tags would serve well here.

Add site favicon

Create a favicon for the site and implement it.

Build footer menu component

Creating a ticket to track progress on footer menu component.

Update button states

Add button states to button section http://a11y-style-guide.com/style-guide/section-general.html#kssref-general-buttons

markdown to html issues

there are still some instances, on the overview page, where the conversion to markdown to HTML is causing some invalid wrapping of elements in <p> tags.

e.g.

<p><h2>How this all got started</h2></p>

I'd assume the fix here would be to instead use markdown to denote the necessary HTML tag?

so do

##How this all got started

rather than

<h2>How this all got started</h2>

but as i'm unfamiliar with the conversion tool, i don't know if that'd actually fix the problem?

Translations to other languages

It would be interesting to translate the guide into other languages, what do you think of the idea? I plan to translate to PT-BR

"visuallyhidden" info in checkbox examples looks confusing

I've had a hard time to understand the purpose of these:

...
<span class="visuallyhidden">The second best Led Zeppelin member is </span>Jimmy Page
...
<span class="visuallyhidden">The third best Led Zeppelin member is </span>John Paul Jones
...
<span class="visuallyhidden">The very best Led Zeppelin member is </span>Robert Plant
...
<span class="visuallyhidden">The forth best Led Zeppelin member is </span>John Bonham

They seem like showing content only to screen-readers to be even more helpful, at least that's what I assume after finding other visuallyhidden elements in other examples as well. Still, the usage in the above examples is not clear to me. Feels like we are providing poll results of some sort?

Create misc resource page

I'm adding resources to the toggle sections on each component, but there are times where the resources do not apply directly to a particular component. need an extra section to link these.

Build main menu component

Creating a ticket to track progress on main menu component. There are many variations of a "main menu" but wanted to give some more complex examples that are still accessible. I like this project and could be a reference for this component https://adobe-accessibility.github.io/Accessible-Mega-Menu/

Create accessible progress bar

Issue

Create an accessible progress bar example using <progress> MDN page on progressbar role .

Sidebar collapse button does not have hover states

When hovering via mouse, over the collapse button, there's no visual indication that the element can be interacted with.

Add more image examples

Add more image examples to image component, including images with text, complex images, etc. See https://www.w3.org/WAI/tutorials/images/ as reference

Updates to pagination

Need to make this more mobile friendly. Also need some accessibility points.

Build video component

Creating a ticket to track progress on video component.

Add `aria-current` to breadcrumb and pagination widgets

Hi 👋🏼

For both the breadcrumb and pagination widget you can add aria-current="page" to the link that points to, well, the current page. This will tell AT that the focused link (when it has aria-current) points to the current page.

You can apply this to all navigation types that have a “current” state.

Related links:

• Breadcrumbs in the ARIA Authoring Practices
• aria-current in the ARIA spec
• Using aria-current by Léonie Watson

Build audio component

Creating a ticket to track progress on audio component.

Ranking system

in the SG there are many examples available for each component, to show real-world scenarios we often find ourselves in as developers. however, we do sometimes have full control of the markup/styling so it would be nice to "rank" the examples from in terms of accessibility. i realize this task is difficult for many reasons, but it would be nice to show users of the SG the best options so they can make an informed choice on markup/styling.

Build accessible accordion pattern

Need to build an accordion pattern that is also accessible. Might want to borrow some ideas from @scottaohara's base accessible accordions https://github.com/scottaohara/accessible_accordions

mobile navigation

Make navigating on mobile devices easier (via @codepo8 @theMadness on Twitter)

duplicate ids

post-shortlink and copy-button appear multiple times across the styleguide.

it'd be best to update any JS using these hooks to instead use classes, and where necessary generate unique IDs for these elements.

Table advice needs some work.

The summary attribute of the table element is obsolete in HTML5. (Screen reader support for this attribute has been spotty.)
Similarly, the thead, tfoot, and tbody elements provide no accessibility functionality.
Reference: http://webaim.org/techniques/tables/data

Build teaser block component

Build component showing multiple links, one on the photo and one on the title of a teaser post. See http://john.foliot.ca/aria-hidden/ for an example.

Font size examples

Using rem vs pt vs vw examples of what is best for browser resizing (ex. https://madebymike.com.au/writing/fluid-type-calc-examples)

Build tabs component

Creating a ticket to track progress on tabs component.

Skip nav component

we are using a skip to content button on this site, but need to do a quick write-up of the pieces some one else might need to replicate this.

Create accessible cards

Create a card component that is also accessible. Similar functionality here https://www.magmutual.com/learning-center

Document KSS node setup and workflow (CMS agnostic)

The current docs at https://github.com/cehfisher/a11y-style-guide/blob/master/README.md do not seem to work outside of a Drupal theme context. Need to update to not depend on Drupal.

Build ARIA labels component

Creating a ticket to track progress on ARIA labels component.

Add good vs bad screen reader videos with examples

First off, awesome work on this! While browsing through last night, I had an idea to add videos to each of the examples. I was thinking of demoing the different screen readers with good & bad examples to really drive home and connect the "why".

I'm totally willing to do this! But I'm not sure where you would like the videos to be hosted or if you'd be willing to take this change :)

a[role="button"] needs to implement behavior

In the buttons section you recommend to either use a <button> element or to use <a role="button">. What is missing is that if you use the second form, you also need to implement button behavior, namely trigger a click event when pressing the spacebar. See MDN for more information.

Note that the second form goes against the first rule of ARIA:

If you can use a native HTML element or attribute with the semantics and behaviour you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so. — Notes on Using ARIA in HTML

In my opinion, the advice should be a bit different:

• If you need a button, use a <button> element
• Just because you want a link to look like a button, it does not need to have the role "button".
  • It is nice if your visual semantics (does it look like a button) and ARIA semantics (does it have the role "button") match up, but not too imporant.
• Remember that <button> defaults to type="submit", so you may want to add type="button" in order to avoid accidentally submitting forms.
• If something navigates to a different URL, it is a link, not a button.

Create issue template

Per the contributing guidelines you've created a placeholder for, once those are squared away might i suggest the next step would be to create a preformatted issue template?

e.g. creating a .github folder with an issue template markdown file within:
.github > issue_template.md

Color contrast for checkboxes and radio button

Hi, nice guide, really.

I have a little remark about checkboxes and radio buttons on this page → http://a11y-style-guide.com/style-guide/section-forms.html : I think they should be more contrasted when unckeched/unselected. The light grey may be difficult to see, on white background.

Build ARIA landmark roles component

Creating a ticket to track progress on ARIA landmark roles component.

Accessible slideshow/carousel

Issue

We need to find and add a slider example that is accessible. For those times you absolutely need one.

Build accessible alert message pattern

Nice low hanging pattern for anyone looking to contribute. Need to create an "alert" or "error message" type pattern featuring accessible colors.
Example pattern to grow from: https://standards.usa.gov/components/alerts/

Jump to top button

The style guide can get vertically long, need a jump to top button

Add localisation support

Would be awesome to have localisation support to translate the guide to other languages. I would love to translate the guide to Finnish to be used with my co-workers, and I could just fork this repo and do it, but would be pretty great to be able to switch between languages in the guide. :)

Visual focus on radio buttons and checkboxes

Check :focus visual feedback on radio btns & checkboxes (in FF / Win8.1) (reported by Arnaud Delafosse)

Build table component

Creating a ticket to track progress on table component.

Build list component

Creating a ticket to track progress on list component.

read more should use aria-describedby instead of aria-labelledby

Hi, thank you for putting this together.
On the read-more links, you suggest using aria-labelledby to provide unique link text for a read more element. This is not wrong, however the aria-labelledby attribute will replace the text node with the content from the heading. So, instead of hearing "link read more", you would hear "link storms hit east coast". That's not terrible.

Another option is to use aria-describedby. This will not replace the text node, but will add the heading text as additional information. So you would hear "link read more {short pause} Storms hit east coast".

Read more example update/testing

One item to note: Describedby (at least with JAWS/NVDA and Firefox) only gets read when you tab to the element. The describedby text isn't read if you arrow through the text for example 3 (via Rachel Olivero Drupal slack).

Pagination Arrow Updates

Per mention in this commit, the arrows are being read aloud by VO.

likely want to revise these to be SVGs that we can set to aria-hidden, so they will not be read aloud, or update to CSS generated triangles or background images?

Create new teaser card pattern

Noticed missing a teaser image with body text and link pattern that most sites seem to have. Most sites have redundant links, which is a WCAG warning...but also just annoying to users of screen readers.

Accordions are not focusable with the keyboard

Accordions (such as the "WCAG 2.0 Guidelines" one on this page: https://cehfisher.github.io/a11y-style-guide/style-guide/section-general.html) are not focusable using just the keyboard.

In addition, they have no keyboard event listeners (currently only tied to the mouse) and no aria-expanded attributes on them.

Updates to basic navbar

Need to update this component to include hamburger collapse on mobile devices.

Should teach input type=image for graphical buttons

Right now, the only advice for graphical buttons is:

If the button only contains an <img> element, make sure to set its alt attribute. If it only contains an icon use aria-label.

... which is correct if you decide to make a graphical button this way, but buttons should only contain phrasing content (MDN). A quick mention & demo of <input type="image"> might be better advice.