using-aria/index.html at gh-pages · w3c/using-aria · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Using ARIA</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
<script type="text/javascript" class='remove'>
  var respecConfig = {
    specStatus: "DISC",
    editors: [
      {
        name: "Steve Faulkner",
        company: "TetraLogical Services Ltd",
        mailto: "sfaulkner@tetralogical.com",
        w3cid: "35007",
      },
      {
        name: "David MacDonald",
        company: "CanAdapt Solutions Inc.",
        mailto: "david@can-adapt.com",
        w3cid: "35466",
      },
      {
        name: "Daniel Montalvo",
        company: "W3C",
        mailto: "dmontalvo@w3.org",
        w3cid: "114058"
      }
    ],
    group: "aria",
    github: "w3c/using-aria",
  };
</script>
<style>
table {
  border-collapse: collapse;
  border: 1px solid #630;
  font: normal 95% arial, Verdana, helvetica, sans-serif;
}

caption {
  font-weight: bold;
}

th,
td {
  text-align: left;
  vertical-align: top;
  padding: 0.3em;
  border: 1px solid #630;
}

td h1 {
  font-size: 85%;
  margin: 0 0 0 0;
}
td p {
  margin: 5px 2px 5px 2px;
}
thead th {
  font-weight: bold;

  text-align: center;
}

/*td span {border: 2px solid #9acd32;display:inline-block;padding:2px;}
span:focus {background:#f5f5f5;border: 2px solid #a0522d;}
td:focus {background:#f5f5f5;border: 2px solid #a0522d;}*/
caption {
  text-align: left;
}

.support {
  color: #090;
  font-size: 1.2em;
}
.partial {
  color: #939393;
  font-size: 1.2em;
}
.nosupport {
  color: #f00;
  font-size: 1.2em;
}

div.example {
  border: 1px dashed #b8860b;
  padding: 5px;
  margin-top: 5px;
  background: #ffffff;
}

sup {
  font-size: 80%;
}
td ul {
  padding-left: 4px;
  list-style-type: none;
}
img {
  border: none;
}
code.block {
  color: #bf3400;
  padding: 10px;
  display: block;
  background: #ebebeb;
  min-width: 20em;
  max-width: 48em;
}
code.blockat {
  color: #bf3400;
  padding: 10px;
  display: block;
  background: #ffffd0;
  min-width: 20em;
  max-width: 48em;
}
mark {
  background-color: #ff9;
}
div,
section,
hr {
  margin-top: 10px;
}
code {
  color: #bf3400 !important;
}

.example {
  margin-left: 30px;
}

div.note {
  padding-top: inherit !important;
  padding-bottom: inherit !important;
}
div.note-title + p {
  margin-top: 0px !important;
}
div.note-title {
  font-weight: bold !important;
}
kbd {
  background-color: #f1f1f1;
  border: 1px solid #666;
  border-radius: 5px;
  color: #333;
  padding: 0px 2px;
  margin: 1px;
  font-weight: bold;
  font-family: Arial, Helvetica, sans-serif;
  min-width: 17px;
  display: inline-block;
}
</style>
</head>

<body>
  <section id="abstract">
  <p role="contentinfo">This document is a practical guide for developers on how to add
      accessibility information to HTML elements using the
      [[[WAI-ARIA-1.2]]] specification , which
      defines a way to make Web content and Web applications more accessible to
      people with disabilities.</p>
  </section>
  <section id="sotd">
    <p class="note">This document is informative only. Resources are for information purposes only, no endorsement implied.</p>
    <p>Using ARIA is a Discontinued Draft. the four rules of ARIA are kept for historical purposes and for easier reference, but there are no plans to continue work on this document. For further guidance on how to include accessibility semantics into web design patterns and widgets using ARIA, see the <a href="https://www.w3.org/WAI/ARIA/apg/">ARIA Authoring Practices Guide (APG)</a>.</p>
  </section>
  <section tabindex="-1" id="intro">
    <h2>Introduction</h2>
    <p>This document is a practical guide for developers on how to add
      accessibility information to HTML elements using the
      [[[WAI-ARIA-1.2]]] specification, which
      defines a way to make Web content and Web applications more accessible to
      people with disabilities. This document demonstrates how to use WAI-ARIA in HTML5, it especially helps with dynamic content and
      advanced user interface controls developed with Ajax, HTML, JavaScript, and
      related technologies.</p>
    <p>This document provides advice for use of ARIA attributes in [[HTML]].    </p>
    <p>For general best-practice information about using ARIA, see the
      <a href="https://www.w3.org/WAI/ARIA/apg/">ARIA Authoring Practices Guide (APG)</a>.</p>
    <p>The following is a longer list of resources that provide relevant information:</p>
    <ul>
      <li>[[[HTML-ARIA]]]</li>
      <li><a href="https://www.w3.org/WAI/ARIA/apg/">ARIA Authoring Practices Guide (APG)</a></li>
      <li>[[[WAI-ARIA-1.2]]]</li>
      <li>[[[HTML]]]</li>
      <li><a href="https://www.html5accessibility.com">HTML5 Accessibility</a></li>
    </ul>
  </section>
  <section role="main" id="NOTES">
  <h2 tabindex="-1" id="notes2">Notes on ARIA Use in HTML</h2>

  <section id="firstrule">
    <h3 tabindex="-1" id="rule1">First Rule of ARIA Use</h3>
    <p>If you <em>can</em> use a native HTML element [[HTML]] or attribute with the semantics and behavior you require <strong>already built in</strong>, instead of re-purposing an element and adding  an ARIA role, state or property to make it accessible<strong>, then do so</strong>.</p>
    <p><strong>Under what circumstances may this not be possible?</strong></p>
    <ul>
      <li>If the feature is available in HTML [[HTML]] but it is not implemented or it is implemented, but <a href="https://www.html5accessibility.com">accessibility support</a> is not.</li>
      <li>If the visual design constraints rule out the use of a particular native element, because the element cannot be styled as required.</li>
      <li>If the feature is <a href="https://www.tpgi.com/aria-in-html-there-goes-the-neighborhood/#html5na">not currently available in HTML</a>.</li>
    </ul></section>
   <section id="secondrule"> <h3 id="second" tabindex="-1">Second Rule of ARIA Use</h3>
    <p>Do not change native  semantics, unless you really have to.</p>
    <p>For example: Developer wants to build a heading that's a tab.</p>
  <p>Do <strong>not</strong> do this:</p>
  <pre class="nohighlight"><code class="block">&lt;<mark>h2</mark> <mark>role=tab</mark>&gt;heading tab&lt;/<mark>h2</mark>&gt;</code>     </pre>
  <p><strong>Do</strong> this:</p>
    <pre class="nohighlight"><code class="block">&lt;div <mark>role=tab</mark>&gt;<mark></mark>&lt;<mark>h2</mark>&gt;heading tab&lt;/<mark>h2</mark>&gt;<mark></mark>&lt;/div&gt;</code></pre>
    <p class="note">If a non-interactive element is used as the basis for an interactive element, developers have to add the semantics using ARIA and the appropriate interaction behavior using scripting. In the case of a button, for example, it is <strong>much better</strong> and easier to <a href="https://www.tpgi.com/html5-accessibility-chops-just-use-a-button/">Just use a (native HTML) button</a>.</p>
    <p class="note">It is OK to use native HTML elements, that have similar semantics to ARIA roles used, for fallback. For example, using HTML <a href="https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element">list elements</a> for the skeleton of an ARIA-enabled, scripted <a href="https://hanshillen.github.io/jqtest/#goto_tree">tree widget</a>.</p></section>
 <section id="3rdrule"> <h3 tabindex="-1" id="third">Third Rule of ARIA Use</h3>
   <p>All interactive ARIA controls must be usable with the keyboard. </p>
   <p>If you create a widget that a user can click or tap or drag or drop or slide or scroll, a user must also be able to navigate to the widget and perform an equivalent action using the keyboard.</p>
   <p>All interactive widgets must be scripted to respond to standard keystrokes or keystroke combinations where applicable.</p>
   <p>For example, if using <code>role=button</code> the element must be able to receive focus and a user must be able to activate the action associated with the element using <strong>both</strong> the <kbd>enter</kbd> (on WIN OS) or <kbd>return</kbd> (MAC OS) and the <kbd>space</kbd> key.</p>
   <p>Refer to the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/">APG Patterns</a> and <a href="https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/">Developing a Keyboard Interface</a> sections of <a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>.</p>

 </section>
 <section id="4thrule">
   <h3 tabindex="-1" id="fourth">Fourth Rule of ARIA Use</h3>
   <p>Do not use <code>role=&quot;presentation&quot;</code> or <code>aria-hidden=&quot;true&quot;</code> on a <strong>focusable</strong> element .</p>
   <p>Using either of these on a <strong>focusable</strong> element will result in some users focusing on 'nothing'.</p>
   <p>Do <strong>not</strong> do this:</p>
   <pre class="nohighlight"><code class="block">&lt;<mark>button</mark> <mark>role=presentation</mark>&gt;press me&lt;/<mark>button</mark>&gt;</code>   </pre>
   <p>Do <strong>not</strong> do this:</p>
  <pre class="nohighlight"><code class="block">&lt;<mark>button</mark> <mark>aria-hidden="true"</mark>&gt;press me&lt;/<mark>button</mark>&gt;</code>   </pre>
<p class="note">Applying <code>aria-hidden</code> to a parent/ancestor of a visible interactive element will also result in the interactive element being hidden, so <strong>don't do this either</strong>:</p>
<pre class="nohighlight"><code class="block">
&lt;<mark>div</mark> <mark>aria-hidden="true"</mark>&gt;
&lt;button&gt;press me&lt;/button&gt;
<mark>&lt;/div></mark></code></pre>
  <p class="note">If an interactive element <strong>cannot be seen or interacted with</strong>, then you can apply <code>aria-hidden</code>, as long as it's not focusable. For example:</p>
 <pre class="nohighlight">
 <code class="block"><mark>button {opacity:0}</mark>

&lt;<mark>button</mark> <mark>tabindex="-1" aria-hidden="true"</mark>&gt;press me&lt;/<mark>button</mark>&gt;</code></pre>

  <p class="note">If an interactive element is hidden using <code>display:none</code> or <code>visibility:hidden</code> (either on the element itself, or any of the element's ancestors),
  it won't be focusable, and it will also be removed from the <a href="https://www.w3.org/TR/accname/#dfn-accessibility-tree">accessibility tree</a>. This makes the
  addition of <code>aria-hidden="true"</code> or explicitly setting <code>tabindex="-1"</code> unnecessary.</p>
 </section>
</section>
<section id="conformance"></section>
</body>
</html>