Skip to content

Commit

Permalink
Adding rh-code-block and rh-blockquote to accessibility docs (#1488)
Browse files Browse the repository at this point in the history 
* Adding rh-code-block and rh-blockquote to accessibility docs

* Warpping WCAG POUR quote in blockquote
  • Loading branch information
@markcaron
markcaron authored Feb 26, 2024
1 parent 5d5c486 commit a0de4f7
Show file tree
Hide file tree
Showing 4 changed files with 130 additions and 99 deletions.
144 changes: 73 additions & 71 deletions docs/accessibility/content.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Content
tags: accessibility
importElements:
- rh-code-block
---

<style>
Expand Down Expand Up @@ -35,23 +37,23 @@ Wherever meaningful images or other non-text elements are used on a page, you mu
### Types of alt text
Images loaded via the `<img>` element typically use the alt attribute for their alternative text:

```
<img src="imagesource.jpg" alt="Description of image">
```
<rh-code-block>
<script type="text/html"><img src="imagesource.jpg" alt="Description of image"></script>
</rh-code-block>

Inline SVGs that compose simple images commonly use a combination of the `role="img"` attribute and a `<title>` element as the first child of the `<svg>` element:

```
<svg role="img">
<rh-code-block>
<script type="text/html"><svg role="img">
<title>Description of image</title>
</svg>
```
</svg></script>
</rh-code-block>

Other non-text elements (e.g., ASCII emoticons) may use ARIA attributes, like `aria-label` or `aria-labelledby`:

```
<span role="img" aria-label="astonished face">:O</span>
```
<rh-code-block>
<script type="text/html"><span role="img" aria-label="astonished face">:O</span></script>
</rh-code-block>

These are not the only means of providing alt text for non-text elements, but they cover many common situations. For less-common cases, view the [WCAG 2.1 documentation](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html).

Expand Down Expand Up @@ -105,40 +107,40 @@ Images acting as buttons or links are functional, and thus serve different purpo

If the above image supplements the text of an article about Red Hat or our products, the appropriate alt text could be something like `"Red Hat, Inc. logo."` But if that image is a link pointing to the corporate homepage, you might want something along the lines of `"Red Hat homepage"` for your alt text:

```
<a href="https://www.redhat.com/">
<rh-code-block>
<script type="text/html"><a href="https://www.redhat.com/">
<img src="logo-redhat.png" alt="Red Hat homepage">
</a>
```
</a></script>
</rh-code-block>

### Grouped images

Grouped images that convey a single meaning (e.g., movie rating stars), can be grouped within an element with a single label (e.g., aria-label) that describes the meaning of the entire group.

```
<div aria-label="2 of 3 attempts left">
<rh-code-block>
<script type="text/html"><div aria-label="2 of 3 attempts left">
<img src="pending.jpg" alt>
<img src="pending.jpg" alt>
<img src="failed.jpg" alt>
</div>
```
</div></script>
</rh-code-block>

Or the first element of the group can have alt text, while the others are hidden:

```
<img src="pending.jpg" alt="2 of 3 attempts left">
<rh-code-block>
<script type="text/html"><img src="pending.jpg" alt="2 of 3 attempts left">
<img src="pending.jpg" alt>
<img src="failed.jpg" alt>
```
<img src="failed.jpg" alt></script>
</rh-code-block>

### Embedded media (and other non-text) titles

Though the techniques may vary, meaningful embedded media objects require text alternatives—just like images do. This applies to `<video>`. `<audio>`, and `<canvas>` elements; objects; applets; ASCII art; and (if you still use them) multimedia embeds like Flash and Silverlight.
A common technique is labeling objects with ARIA attributes:

```
<video src="video.mp4" aria-label="Deploying applications with OpenShift">
```
<rh-code-block>
<script type="text/html"><video src="video.mp4" aria-label="Deploying applications with OpenShift"></script>
</rh-code-block>

## Writing microcopy

Expand All @@ -154,9 +156,9 @@ Best practices for all microcopy:

In addition to the best practices for all microcopy, adhere to the following best practices for links, when possible.

```
<a href="signup.html">Sign-up form</a>
```
<rh-code-block>
<script type="text/html"><a href="signup.html">Sign-up form</a></script>
</rh-code-block>

#### Best practices for links

Expand All @@ -176,9 +178,9 @@ In addition to the best practices for all microcopy, adhere to the following bes

In addition to the best practices for all microcopy, adhere to the following best practices for buttons, when possible.

```
<button>Save draft</button>
```
<rh-code-block>
<script type="text/html"><button>Save draft</button></script>
</rh-code-block>

#### Best practices for buttons

Expand All @@ -190,9 +192,9 @@ In addition to the best practices for all microcopy, adhere to the following bes

In addition to the best practices for all microcopy, adhere to the following best practices for form labels, when possible.

```
<label>First name</label>
```
<rh-code-block>
<script type="text/html"><label>First name</label></script>
</rh-code-block>

#### Best practices for labels

Expand All @@ -207,15 +209,15 @@ In addition to the best practices for all microcopy, adhere to the following bes

Use clear language in headings to describe the content that follows them:

```
<h1>Red Hat Enterprise Linux</h1>
```
<rh-code-block>
<script type="text/html"><h1>Red Hat Enterprise Linux</h1></script>
</rh-code-block>

At Red Hat, we use sentence case for our headings:

```
<h2>How companies are using RHEL</h2>
```
<rh-code-block>
<script type="text/html"><h2>How companies are using RHEL</h2></script>
</rh-code-block>

#### Heading levels

Expand All @@ -239,8 +241,8 @@ Here’s an example of a page outline:

And here’s how that outline would be reflected in a page’s heading structure:

```
<h1>Midwestern Recipes</h1>
<rh-code-block>
<script type="text/html"><h1>Midwestern Recipes</h1>
<h2>Sides</h2>
<h3>Cheese</h3>
<h4>Fried cheese curds</h4>
Expand All @@ -251,35 +253,35 @@ And here’s how that outline would be reflected in a page’s heading structure
<h4>Dream bars</h4>
<h3>Pastries</h3>
<h4>Kringle</h4>
<h4>Dutch letters</h4>
```
<h4>Dutch letters</h4></script>
</rh-code-block>

Note that an `<h1>` is often the first heading on a page:

```
<h1>Midwestern Recipes</h1>
<h2>Navigation</h2>
```
<rh-code-block>
<script type="text/html"><h1>Midwestern Recipes</h1>
<h2>Navigation</h2></script>
</rh-code-block>

But it doesn’t have to be the first heading on a page. This is also acceptable:

```
<h2>Navigation</h2>
<h1>Midwestern Recipes</h1>
```
<rh-code-block>
<script type="text/html"><h2>Navigation</h2>
<h1>Midwestern Recipes</h1></script>
</rh-code-block>

### Page titles

Each web page is required to have a page `<title>` element within its `<head>` that contains meaningful text describing the page’s context and purpose.

```
<html lang="en">
<rh-code-block>
<script type="text/html"><html lang="en">
<head>
<title>Red Hat Ansible Automation Platform</title>
</head>
<body>...</body>
</html>
```
</html></script>
</rh-code-block>

Titles should be specific to each URL and not duplicated across a site. Otherwise, users (particularly assistive tech users) may not be aware when they’ve landed on a new or updated page. When users move to new pages or change contexts of the current page, the page title should change to reflect this.

Expand All @@ -291,9 +293,9 @@ As mentioned in the Headings section, page titles and `<h1>` elements often rela

Non-hidden, non-empty `<iframe>` elements are required to have titles describing their meaning or purpose, similar to alternative text for images.

```
<iframe src="video.html" title="Video: Network automation with Ansible"></iframe>
```
<rh-code-block>
<script type="text/html"><iframe src="video.html" title="Video: Network automation with Ansible"></iframe></script>
</rh-code-block>

Note that, as opposed to a page’s `<title>` element, `<iframe>` tags include title attributes to label them. (Yes, it can be confusing, especially when you consider that there are still more `<title>` elements and title attributes used in other contexts!)

Expand All @@ -319,8 +321,8 @@ Avoid using tables when a simple list (whether [ordered](https://developer.mozil

For example, the following doesn’t need to be a table:

```
<table>
<rh-code-block>
<script type="text/html"><table>
<caption>Groceries</caption>
<tbody>
<tr>
Expand All @@ -336,19 +338,19 @@ For example, the following doesn’t need to be a table:
<td>6</th>
</tr>
</tbody>
</table>
```
</table></script>
</rh-code-block>

Instead, a list would be simpler, easier to understand, and easier to code:

```
<h3 id="groceries">Groceries</h3>
<rh-code-block>
<script type="text/html"><h3 id="groceries">Groceries</h3>
<ul aria-labelledby="groceries">
<li>5 Apples</li>
<li>3 Oranges</li>
<li>6 Lemons</li>
</ul>
```
</ul></script>
</rh-code-block>

In other words, if it doesn’t *need* to be a table, then it probably shouldn’t be a table.

Expand Down Expand Up @@ -392,8 +394,8 @@ All HTML content must be contained within an element that has a `lang` attribute

For pages with multilingual content, each element containing a different language from the one indicated in the `<html>` element should have an appropriate `lang` attribute. For example:

```
<html lang="en">
<rh-code-block>
<script type="text/html"><html lang="en">
<head>...</head>
<body>
<p>Colombian author Gabriel García Márquez wrote that
Expand All @@ -402,8 +404,8 @@ For pages with multilingual content, each element containing a different languag
los seres humanos tenemos tres vidas: pública, privada y
secreta.”</span>)</p>
</body>
</html>
```
</html></script>
</rh-code-block>

The W3C has an [article on language tags](https://www.w3.org/International/articles/language-tags/), which covers both how to use them and where to find a full list of them.

Expand Down
37 changes: 19 additions & 18 deletions docs/accessibility/development.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Development
tags: accessibility
importElements:
- rh-code-block
---

## Overview
Expand Down Expand Up @@ -34,40 +36,39 @@ To make icon fonts accessible, you often have to re-hack what’s already a hack

As with any other image, SVGs that are loaded into your page via an `<img>` tag should include alt attributes. This attribute should be descriptive for meaningful SVGs and null for decorative SVGs. In addition, we recommend adding a role="img" attribute to the `<img>` element for SVGs:

```
<img src="logo.svg" alt="Image description" role="img">
```
<rh-code-block>
<script type="text/html"><img src="logo.svg" alt="Image description" role="img"></script>
</rh-code-block>

Inline `<svg>` elements (i.e., SVGs that are coded directly into the page source) cannot use the alt attribute. You must use some other means to describe or hide these images.
Instead of an alt attribute, an `<svg>` element comprising a simple image can include the role="img" attribute and contain a descriptive `<title>` element as its first child, like in the following example:

```
<svg xmlns="http://www.w3.org/2000/svg" role="img">
<rh-code-block>
<script type="text/html"><svg xmlns="http://www.w3.org/2000/svg" role="img">
<title>Image description</title>
...
</svg>
```
</svg></script>
</rh-code-block>

More complex `<svg>` elements may require additional descriptive information. One way of including this information is via the `<desc>` element:

```
<svg xmlns="http://www.w3.org/2000/svg" role="img">
<rh-code-block>
<script type="text/html"><svg xmlns="http://www.w3.org/2000/svg" role="img">
<title>Basic image description</title>
<desc>More info on the image</desc>
…
</svg>
```
...
</svg></script>
</rh-code-block>

#### Hiding SVGs

You can hide inline `<svg>` elements with an `aria-hidden="true"` attribute.

```
<svg aria-hidden="true">
…
</svg>
```
<rh-code-block>
<script type="text/html"><svg aria-hidden="true">
...
</svg></script>
</rh-code-block>

Carie Fisher explores several patterns (including the above) for embedding accessible SVGs in her 2021 [Smashing Magazine article](https://www.smashingmagazine.com/2021/05/accessible-svg-patterns-comparison/).

Expand Down
Loading

0 comments on commit a0de4f7

Please sign in to comment.