Radio documentation: updating radio readme

[davewhitley]

Initial commit to update Radio readme. These changes add design documentation.

Description

This PR adds design guideline documentation in addition to the development documentation that existed previously. These guidelines are 'best practices' for the usage of the component, as well as describing the component in more detail.

Screenshots

A preview can be seen here, although it doesn't represent what it will look like in the handbook:

http://simp.ly/p/qzstJq

Feedback

I'd appreciate feedback on:

• the image alt text
• usage of the h1 header
• design guidelines
• finding a way to preview these changes and see what they'll look like in the handbook

Thank you!

[davewhitley]

Thanks for the review @chrisvanpatten. I would love some a11y guidance on the alt text and use of headers.

I wasn't sure about how to write alt text for an image with a visible caption. I know some sites use the same caption text for the alt text, but make sure that it's not read twice.

Sounds like next steps for this would be:

• Update images to be consistent with Joen's new do/don't images
• Determine best way forward for alt text on these images
• Figure out if there should only be a single h1 on the page

[davewhitley]

I just read this to get a better handle on alt text and captions: https://webaim.org/techniques/alttext/

I'm still not sure, but leaving the alt text blank might be a valid approach because of the surrounding text.

Another possibility is describing what is going on in the diagram. So, for example, this image:

the alt text could be:

"A diagram of an interface using checkboxes when only one item can be selected from a list."

[davidakennedy]

I would love some a11y guidance on the alt text and use of headers.

Hi @drw158! Happy to share some guidance. Love that you're thinking about this, and asking great questions. ❤️

First, for the headings:

• Ideally, there should be one h1 on a page. Why? Because screen reader users often scan a page by heading levels, much like sighted users skim a page visually looking for the headlines. Having one h1 helps them know – this is the page title, the topic of the page. An added benefit is SEO. One h1 has some benefits there as well.
• Even though HTML5 supports a document outline that can include multiple h1s in a page, it's not supported by any browser, so it's not practical to rely on.

For the alt attributes:

• What I do in this case is imagine that the images aren't there. Would the content lose any value? In this case, no. As you say, the content covers the same guidelines that the second and third images show. It's fine to use a blank alt attribute on those.

[samikeijonen]

I agree with @davidakennedy in the previous comment.

Although I can't really see the context of the image and surrounding text. If alt is needed it could be like "Post visibility checkboxes: public, private, and password protected."

@drw158 Any change to update the PR?

[davewhitley]

@samikeijonen Can you explain what you mean when you say you can't see the context of the image?

@chrisvanpatten all of your concerns should be fixed

---

I'm not sure where the images should be uploaded. That is the only blocker right now.

[davewhitley]

Image issue has been resolved. Now ready for a final review and merge.

[tofumatt]

This is an improvement so I'm gonna say let's go for it.

[tofumatt]

These are headers, not paragraph text; they should be labelled with header markdown (eg ##### User control), not bold text like this. 😄

Issues were addressed

[chrisvanpatten]

Looks good to me and I'm glad we're using make/design for image uploads!