forked from w3c/aria-practices
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy patharia-practices.html
5782 lines (5373 loc) · 457 KB
/
aria-practices.html
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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<title>WAI-ARIA Authoring Practices 1.1</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script src="common/script/resolveReferences.js" class="remove"></script>
<script src="common/biblio.js" class="remove"></script>
<script class="remove">
var respecConfig = {
// Embed RDFa data in the output.
doRDFa : '1.1',
includePermalinks : true,
permalinkEdge : true,
permalinkHide : false,
// Specification status (e.g., WD, LC, NOTE, etc.). If in doubt use ED.
specStatus : "ED",
// crEnd: "2012-04-30",
// perEnd: "2013-07-23",
// publishDate: "2013-08-22",
noRecTrack : true,
diffTool : "http://www.aptest.com/standards/htmldiff/htmldiff.pl",
// The specifications short name, as in http://www.w3.org/TR/short-name/
shortName : "wai-aria-practices-1.1",
// If you wish the publication date to be other than today,
// set publishDate.
// publishDate: "2009-08-06",
copyrightStart : "2015",
// If there is a previously published draft, uncomment this
// and set its YYYY-MM-DD date and its maturity status.
//
// previousPublishDate: "",
// previousMaturity: "",
// prevRecURI: "",
// previousDiffURI: "",
// If there a publicly available Editors Draft, this is the link
edDraftURI : "http://w3c.github.io/aria-practices/",
// If this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2012-02-21",
// Editors, add as many as you like.
// “name” is the only required field.
editors : [ {
name : "Matt King",
mailto : "[email protected]",
company : "Facebook",
companyURI : "http://www.facebook.com/",
w3cid: 44582
}, {
name : "James Nurthen",
mailto : "[email protected]",
company : "Oracle Corporation",
companyURI : "http://www.oracle.com/",
w3cid: 37155
}, {
name : "Michiel Bijl",
mailto : "[email protected]",
company : "The Paciello Group",
companyURI : "https://www.paciellogroup.com/",
w3cid: 74040
}, {
name : "Michael Cooper",
url : 'http://www.w3.org/People/cooper/',
mailto : "[email protected]",
company : "W3C",
companyURI : "http://www.w3.org/",
w3cid: 34017
}, {
name : "Joseph Scheuhammer",
company : "Inclusive Design Research Centre, OCAD University",
companyURI : "http://idrc.ocad.ca/",
note : "Previous Editor",
w3cid: 42279
}, {
name : "Lisa Pappas",
company : "SAS",
companyURI : "http://www.sas.com/",
note : "Previous Editor",
w3cid: 41725
}, {
name : "Rich Schwerdtfeger",
company : "IBM Corporation",
companyURI : "http://ibm.com/",
note : "Previous Editor",
w3cid: 2460
}, ],
// Authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// Same format and requirements as editors.
// authors: [
// {
// name: "Your Name",
// url: "http://example.org/",
// company: "Your Company",
// companyURI: "http://example.com/"
// },
// ],
// Spec URLs
ariaSpecURLs : {
"ED" : "http://w3c.github.io/aria/aria/aria.html",
"FPWD" : "http://www.w3.org/TR/wai-aria-1.1/",
"WD" : "http://www.w3.org/TR/wai-aria-1.1/",
"REC" : "http://www.w3.org/TR/wai-aria/"
},
accNameURLs : {
"ED" : "http://w3c.github.io/aria/accname-aam/accname-aam.html",
"WD" : "http://www.w3.org/TR/accname-aam-1.1/",
"FPWD" : "http://www.w3.org/TR/accname-aam-1.1/",
"REC" : "http://www.w3.org/TR/accname-aam-1.1/"
},
coreMappingURLs : {
"ED" : "http://w3c.github.io/aria/core-aam/core-aam.html",
"WD" : "http://www.w3.org/TR/core-aam-1.1/",
"FPWD" : "http://www.w3.org/TR/core-aam-1.1/",
"REC" : "http://www.w3.org/TR/core-aam-1.1/"
},
// alternateFormats: [
// {
// uri: 'aria-practices-diff.html',
// label: "Diff from Previous Recommendation"
// },
// {
// uri: 'aria-practices.ps',
// label: "PostScript version"
// },
// {
// uri: 'aria-practices.pdf',
// label: "PDF version"
// }
// ],
// errata: 'http://www.w3.org/2010/02/rdfa/errata.html',
// name of the WG
wg : "Accessible Rich Internet Applications Working Group",
// URI of the public WG page
wgURI : "http://www.w3.org/WAI/ARIA/",
// Name (without the @w3c.org) of the public mailing
// to which comments are due.
wgPublicList : "public-aria",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI
// from a random document unless you know what you're doing.
// If in doubt ask your friendly neighbourhood Team Contact.
wgPatentURI : "http://www.w3.org/2004/01/pp-impl/83726/status",
maxTocLevel : 4,
localBiblio : biblio,
preProcess : [ linkCrossReferences ]
};
</script>
<link href="common/css/common.css" rel="stylesheet" type="text/css" />
</head>
<body>
<section id="abstract">
<p>
This document provides readers with an understanding of how to use <cite><a href="http://www.w3.org/TR/wai-aria-1.1/"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> 1.1</a></cite> [[WAI-ARIA]] to create accessible rich internet applications.
It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties.
This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers.
</p>
<p>This document is part of the WAI-ARIA suite described in the <a href="http://www.w3.org/WAI/intro/aria.php">WAI-ARIA Overview</a>.</p>
</section>
<section id="sotd"></section>
<section id="intro">
<h2>Introduction</h2>
<p>This section is <em>informative.</em></p>
<p>
The WAI-ARIA Authoring Practices Guide is intended to provide an understanding of how to use WAI-ARIA to create an accessible Rich Internet Application.
It describes recommended WAI-ARIA usage patterns and provides an introduction to the concepts behind them.
</p>
<p>
This guide is one part of a suite of resources that support the WAI-ARIA specification.
The WAI-ARIA suite fills accessibility gaps identified by the [[WAI-ARIA-ROADMAP]].
</p>
<p>
As explained in <a href="#ariaBackground">Background on WAI-ARIA</a>, languages used to create rich and dynamic web sites, e.g., HTML, Javascript, CSS, and SVG, do not natively include all the features required to make sites usable by people who use assistive technologies (AT) or who rely on keyboard navigation.
The W3C Web Accessibility Initiative's (WAI) Accessible Rich Internet Applications working group (ARIA WG) is addressing these deficiencies through several W3C standards efforts, with a focus on the WAI-ARIA specifications.
For an introduction to WAI-ARIA, see the <a href="http://www.w3.org/WAI/intro/aria.php">Accessible Rich Internet Applications Suite (WAI-ARIA) Overview</a>.
</p>
<p>
With the understanding many prefer to learn from examples, the guide begins with a section that demonstrates how to make common widgets accessible with descriptions of expected behaviors supported by working code.
Where it is helpful to do so, the examples refer to detailed explanations of supporting concepts in subsequent sections.
The sections that follow the examples first provide background that helps build understanding of how WAI-ARIA works and how it fits into the larger web technology picture.
Next, the guide covers general steps for building an accessible widget using WAI-ARIA, JavaScript, and CSS, including detailed guidance on how to make rich internet applications keyboard accessible.
The scope then widens to include the full application, addressing the page layout and structural semantics critical to enabling a usable experience with assistive technologies on pages containing both rich applications and rich documents.
It includes guidance on dynamic document management, use of WAI-ARIA Form properties, and the creation of WAI-ARIA-enabled alerts and dialogs.
</p>
</section>
<section class="widget" id="aria_landmark">
<h2>Landmark Roles Design Patterns</h2>
<p>
Landmarks provide a powerful way to identify the organization and structure of a web page.
The structural information conveyed visually to users should be represented programmatically in the markup using landmark roles.
The use of landmark roles supports keyboard navigation to the structure of a web page for screen reader users, and can be used as targets for author supplied "skip links" and browser extensions for enhanced keyboard navigation.
</p>
<p>This section is intended to assist designers, developers and quality assurance staff in defining and understanding the importance of logical, usable, and accessible layout for assistive technologies using HTML5 sectioning elements and ARIA landmark roles.</p>
<section>
<h3>HTML5 Sectioning Elements</h3>
<p>
It is important to understand that many HTML5 sectioning elements by default define ARIA landmarks.
If HTML5 sectioning elements are used without understanding the associated landmark structure, assistive technology users will most likely be confused and less efficient in accessing content and interacting with web pages.
<a href="https://www.w3.org/TR/html-aria/">More information on HTML5 element role mapping</a>.
</p>
<table class="widget-features">
<caption>Default landmark roles for HTML5 sectioning elements</caption>
<thead>
<tr>
<th>HTML5 Element</th>
<th>Default Landmark Role</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aside</code></td>
<td><code>complementary</code></td>
</tr>
<tr>
<td><code>footer</code></td>
<td><code>contentinfo</code> when in context of the <code>body</code> element</td>
</tr>
<tr>
<td><code>header</code></td>
<td><code>banner</code> when in context of the <code>body</code> element</td>
</tr>
<tr>
<td><code>main</code></td>
<td><code>main</code></td>
</tr>
<tr>
<td><code>nav</code></td>
<td><code>navigation</code></td>
</tr>
<tr>
<td><code>section</code></td>
<td><code>region</code> when it has an accessible name using <code>aria-labelledby</code> or <code>aria-label</code></td>
</tr>
</tbody>
</table>
</section>
<section>
<h3>General Principles of Landmark Design</h3>
<p>Due to the complexity of todays web content, if using landmarks, <strong>all content</strong> should reside in a semantically meaningful landmark in order that content is not missed by the user.</p>
<p><strong>Step 1: Identify the logical structure</strong></p>
<ul>
<li>Break the page into perceivable areas of content which designers typically indicate visually using alignment and spacing.</li>
<li>Areas can be further defined into logical sub-areas as needed.</li>
<li>An example of a sub-area is a portlet in a portal application.</li>
</ul>
<p><strong>Step 2: Assign landmark roles to each area</strong></p>
<ul>
<li>Assign landmark roles based on the type of content in the area.</li>
<li><code>banner</code>, <code>main</code>, <code>complementary</code> and <code>contentinfo</code> landmarks should be top level landmarks.</li>
<li>Landmark roles can be nested to identify parent/child relationships of the information being presented.</li>
</ul>
<p><strong>Step 3: Label areas</strong></p>
<ul>
<li>If a specific landmark role is used more than once on a web page, it should have a unique label.</li>
<li>If a landmark is only used once on the page it may not require a label. See Landmark Roles section below. </li>
<li>If an area begins with a heading element (e.g. <code>h1-h6</code>) it can be used as the label for the area using the
<code>aria-labelledby</code> attribute.</li>
<li>If an area requires a label and does not have a heading element, provide a label using the <code>aria-label</code> attribute.</li>
<li>
Do not use the landmark role as part of the label.
For example, a navigation landmark with a label "Site Navigation" will be announced by a screen reader as "Site Navigation Navigation".
The label should simply be "Site".
</li>
</ul>
</section>
<section>
<h3>Landmark Roles</h3>
<section class="widget" id="aria_lh_banner">
<h4 class="widget-name">Banner</h4>
<p>
A <a href="https://www.w3.org/TR/wai-aria-1.1/#banner"><code>banner</code></a> landmark identifies site-oriented content at the beginning of each page within a website.
Site-oriented content typically includes things such as the logo or identity of the site sponsor, and site-specific search tool.
A banner usually appears at the top of the page and typically spans the full width.
</p>
<ul>
<li>Each page may have one <code>banner</code> landmark.</li>
<li>The <code>banner</code> landmark should be a top-level landmark.</li>
<li>When a page contains nested <code>document</code> and/or <code>application</code> roles (e.g. typically through the use of <code>iframe</code> and <code>frame</code> elements), each <code>document</code> or <code>application</code> role may have one <code>banner</code> landmark.</li>
<li>If a page includes more than one <code>banner</code> landmark, each should have a unique label (see Step 3 above).</li>
</ul>
<section class="notoc">
<h5>HTML5 Techniques</h5>
<ul>
<li>The HTML5 <code>header</code> element defines a <code>banner</code> landmark when its context is the <code>body</code> element.</li>
<li>
The HTML5 <code>header</code> element is not considered a <code>banner</code> landmark when it is descendant of any of following elements (see <a href="http://w3c.github.io/aria/html-aam/html-aam.html">HTML Accessibility Mappings</a>):
<ul>
<li><code>article</code></li>
<li><code>aside</code></li>
<li><code>main</code></li>
<li><code>nav</code></li>
<li><code>section</code></li>
</ul>
</li>
</ul>
<h5>ARIA Techniques</h5>
<p>If the HTML5 <code>header</code> element technique is not being used, a <code>role="banner"</code> attribute should be used to define a <code>banner</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/banner.html">Banner Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_complementary">
<h4 class="widget-name">Complementary</h4>
<p>A <a href="https://www.w3.org/TR/wai-aria-1.1/#complementary"><code>complementary</code></a> landmark is a supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.</p>
<ul>
<li><code>complementary</code> landmarks should be top level landmarks (e.g. not contained within any other landmarks).</li>
<li>If the complementary content is not related to the main content, a more general role should be assigned (e.g. <code>region</code>).</li>
<li>If a page includes more than one <code>complementary</code> landmark, each should have a unique label (see Step 3 above).</li>
</ul>
<section class="notoc">
<h5>HTML5 Technique</h5>
<p>Use the HTML5 <code>aside</code> element to define a <code>complementary</code> landmark.</p>
<h5>ARIA Technique</h5>
<p>If the HTML5 <code>aside</code> element technique is not being used, use a <code>role="complementary"</code> attribute to define a <code>complementary</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/complementary.html">Complementary Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_contentinfo">
<h4 class="widget-name">Contentinfo</h4>
<p>A <a href="https://www.w3.org/TR/wai-aria-1.1/#contentinfo"><code>contentinfo</code></a> landmark is a way to identify common information at the bottom of each page within a website, typically called the "footer" of the page, including information such as copyrights and links to privacy and accessibility statements.</p>
<ul>
<li>Each page may have one <code>contentinfo</code> landmark.</li>
<li>The <code>contentinfo</code> landmark should be a top-level landmark.</li>
<li>When a page contains nested <code>document</code> and/or <code>application</code> roles (e.g. typically through the use of <code>iframe</code> and <code>frame</code> elements), each <code>document</code> or <code>application</code> role may have one <code>contentinfo</code> landmark.</li>
<li>If a page includes more than one <code>contentinfo</code> landmark, each should have a unique label (see Step 3 above).</li>
</ul>
<section class="notoc">
<h5>HTML5 Techniques</h5>
<ul>
<li>The HTML5 <code>footer</code> element defines a <code>contentinfo</code> landmark when its context is the <code>body</code> element.</li>
<li>
The HTML5 <code>footer</code> element is not considered a <code>contentinfo</code> landmark when it is descendant of any of following elements (see <a href="http://w3c.github.io/aria/html-aam/html-aam.html">HTML Accessibility Mappings</a>):
<ul>
<li><code>article</code></li>
<li><code>aside</code></li>
<li><code>main</code></li>
<li><code>nav</code></li>
<li><code>section</code></li>
</ul>
</li>
</ul>
<h5>ARIA Technique</h5>
<p>If the HTML5 <code>footer</code> element technique is not being used, a <code>role="contentinfo"</code> attribute should be used to define a <code>contentinfo</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/contentinfo.html">Contentinfo Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_form">
<h4 class="widget-name">Form</h4>
<p>A <a href="https://www.w3.org/TR/wai-aria-1.1/#form"><code>form</code></a> landmark identifies a region that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main or search).</p>
<ul>
<li>Use the <code>search</code> landmark instead of the <code>form</code> landmark when the form is used for search functionality.</li>
<li>A <code>form</code> landmark should have a label to help users understand the purpose of the form.</li>
<li>A label for the <code>form</code> landmark should be visible to all users (e.g. an <code>h1-h6</code> element).</li>
<li>If a page includes more than one <code>form</code> landmark, each should have a unique label (see Step 3 above).</li>
<li>
Whenever possible, controls contained in a <code>form</code> landmark in an HTML document should use native host semantics:
<ul>
<li><code>button</code></li>
<li><code>input</code></li>
<li><code>select</code></li>
<li><code>textarea</code></li>
</ul>
</li>
</ul>
<section class="notoc">
<h5>HTML5 Techniques</h5>
<p>The HTML5 <code>form</code> element that defines a <code>form</code> landmark when it has an accessible name (e.g. <code>aria-labelledby</code>, <code>aria-label</code> or <code>title</code>).</p>
<h5>ARIA Technique</h5>
<p>Use the <code>role="form"</code> to identify a region of the page; do not use it to identify every form field.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/form.html">Form Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_main">
<h4 class="widget-name">Main</h4>
<p>A <a href="https://www.w3.org/TR/wai-aria-1.1/#main"><code>main</code></a> landmark identifies the primary content of the page.</p>
<ul>
<li>Each page should have one <code>main</code> landmark.</li>
<li>The <code>main</code> landmark should be a top-level landmark.</li>
<li>When a page contains nested <code>document</code> and/or <code>application</code> roles (e.g. typically through the use of <code>iframe</code> and <code>frame</code> elements), each <code>document</code> or <code>application</code> role may have one <code>main</code> landmark.</li>
<li>If a page includes more than one <code>main</code> landmark, each should have a unique label (see Step 3 above).</li>
</ul>
<section class="notoc">
<h5>HTML5 Technique</h5>
<p>Use the HTML5 <code>main</code> element to define a <code>main</code> landmark.</p>
<h5>ARIA Technique</h5>
<p>If the HTML5 <code>main</code> element technique is not being used, use a <code>role="main"</code> attribute to define a <code>main</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/main.html">Main Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_navigation">
<h4 class="widget-name">Navigation</h4>
<p><a href="https://www.w3.org/TR/wai-aria-1.1/#navigation"><code>Navigation</code></a> landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation.</p>
<ul>
<li>If a page includes more than one <code>navigation</code> landmark, each should have a unique label (see Step 3 above).</li>
<li>If a <code>navigation</code> landmark has an identical set of links as another <code>navigation</code> landmark on the page, use the same label for each <code>navigation</code> landmark.</li>
</ul>
<section class="notoc">
<h5>HTML5 Technique</h5>
<p>Use the HTML5 <code>nav</code> element to define a <code>navigation</code> landmark.</p>
<h5>ARIA Technique</h5>
<p>If the HTML5 <code>nav</code> element technique is not being used, use a <code>role="navigation"</code> attribute to define a <code>navigation</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/navigation.html">Navigation Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_region">
<h4 class="widget-name">Region</h4>
<p>A <a href="https://www.w3.org/TR/wai-aria-1.1/#region"><code>region</code></a> landmark is a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section.</p>
<ul>
<li>A <code>region</code> landmark must have a label.</li>
<li>If a page includes more than one <code>region</code> landmark, each should have a unique label (see Step 3 above).</li>
<li>The <code>region</code> landmark can be used identify content that named landmarks do not appropriately describe.</li>
</ul>
<section class="notoc">
<h5>HTML5 Technique</h5>
<p>Use the HTML5 <code>section</code> element to define a <code>region</code> landmark.</p>
<h5>ARIA Technique</h5>
<p>If the HTML5 <code>section</code> element technique is not being used, use a <code>role="region"</code> attribute to define a <code>region</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/region.html">Region Landmark Example</a></p>
</section>
</section>
<section id="aria_lh_search">
<h4 class="widget-name">Search</h4>
<p>A <a href="https://www.w3.org/TR/wai-aria-1.1/#search"><code>search</code></a> landmark contains a collection of items and objects that, as a whole, combine to create search functionality.</p>
<ul>
<li>Use the <code>search</code> landmark instead of the <code>form</code> landmark when the form is used for search functionality.</li>
<li>If a page includes more than one <code>search</code> landmark, each should have a unique label (see Step 3 above).</li>
</ul>
<section class="notoc">
<h5>HTML5 Technique</h5>
<p>There is no HTML5 element that defines a <code>search</code> landmark.</p>
<h5>ARIA Technique</h5>
<p>The <code>role="search"</code> attribute defines a <code>search</code> landmark.</p>
</section>
<section class="notoc">
<h5>Examples</h5>
<p><a href="examples/landmarks/search.html">Search Landmark Example</a></p>
</section>
</section>
</section>
</section>
<section id="aria_ex">
<h2>Design Patterns and Widgets</h2>
<p>This section demonstrates how to make common rich internet application widgets and patterns accessible by applying WAI-ARIA roles, states, and properties and implementing keyboard support.</p>
<p class="note">
Although users of Mac OS X are familiar with using the <kbd>Command</kbd> key instead of the <kbd>Control</kbd> key, the <kbd>Command</kbd> key is typically reserved for desktop applications and OS-level integration.
Until device and platform independence can be addressed in WAI-ARIA 2.0, the primary <kbd>Control</kbd> modifier key for WAI-ARIA widget interaction is specified as <kbd>Control</kbd> on all platforms, including Mac OS X.
</p>
<section id="aria_ex_widget">
<h3>Generally Applicable Keyboard Recommendations </h3>
<p>The following keyboard conventions are applicable to many of the patterns described in subsequent sections.</p>
<ul>
<li><kbd>Shift + F10</kbd> opens associated context menu</li>
<li><kbd>Control + C</kbd> Copies to clipboard </li>
<li><kbd>Control + V</kbd> Pastes from clipboard </li>
<li><kbd>Control + X</kbd> Copies to clipboard and cuts </li>
<li><kbd>Control + Z</kbd> undo last action</li>
<li><kbd>Control + Y</kbd> Redo action</li>
</ul>
<p class="note">The following guidance on nested widgets will be moved to another section.</p>
<p>
<strong>Widgets within Widgets</strong>
The general navigation model is for a user to tab to a widget, interact with the controls in that widget and then tab to move focus to the next widget in the tab order.
By extension, when the construct of a widget contains another widget, tab will move focus to the contained widget because it is the next item in the tab order.
This continues down the layers of widgets until the last widget is reached.
For example, if there are two widgets A and B on a page where widget A contains within it Widget A1 and Widget A1 contains within it Widget A2, the focus sequence when pressing the tab key would be A, A1, A2, B.
</p>
</section>
<section class="widget" id="accordion">
<h3>Accordion</h3>
<p class="note">This section has not been updated since it was integrated from the WAI-ARIA Authoring Practices Guide (<abbr title="Authoring Practices Guide">APG</abbr>) version 1.0 -- an APG task force review is pending.</p>
<p>
An accordion component is a collection of expandable panels associated with a common outer container.
Panels consist of a header and an associated content region or panel.
The primary use of an Accordion is to present multiple sections of content on a single page without scrolling, where all of the sections are peers in the application or object hierarchy.
The general look is similar to a tree where each root tree node is an expandable accordion header.
The user navigates and makes the contents of each panel visible (or not) by interacting with the Accordion Header.
Terms for understanding accordions include:
</p>
<dl>
<dt>accordion component:</dt>
<dd>Collection of panels within a common outer pane.</dd>
<dt>accordion header:</dt>
<dd>Label area of an accordion panel. This is where you find the control to expand or collapse the panels.</dd>
<dt>accordion panel:</dt>
<dd>Contents area associated with an accordion header.</dd>
</dl>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li>
<kbd>Tab</kbd> - When focus is on an accordion header, pressing the <kbd>Tab</kbd> key moves focus in the following manner:
<ol>
<li>If interactive glyphs or menus are present in the accordion header, focus moves to each in order. </li>
<li>When the corresponding panel is expanded (its <a href="#aria-expanded" class="state-reference">aria-expanded</a> state is 'true'), then focus moves to the first focusable element in the panel. </li>
<li>If the panel is collapsed (its aria-expanded state is 'false' or missing), OR, when the last interactive element of a panel is reached, the next <kbd>Tab</kbd> key press moves focus as follows:
<ul>
<li>If a subsequent accordion panel is already expanded, focus moves to the first focusable element in this subsequent panel.</li>
<li>If no subsequent accordion panel is expanded, focus moves to the first focusable element outside the accordion component.</li>
</ul>
</li>
</ol>
</li>
<li>
<kbd>Left arrow</kbd>
<ul>
<li>When focus is on the accordion header, a press of up/left arrow keys moves focus to the previous logical accordion header.</li>
<li>When focus reaches the first header, further up/left arrow key presses optionally wrap to the first header.</li>
</ul>
</li>
<li>
<kbd>Right arrow</kbd>
<ul>
<li>When focus is on the accordion header, a press of down/right moves focus to the next logical accordion header.</li>
<li>When focus reaches the last header, further down/right arrow key presses optionally wrap to the first header.</li>
</ul>
</li>
<li>
<kbd>Up arrow</kbd> - behaves the same as left arrow
</li>
<li>
<kbd>Down arrow</kbd> - behaves the same as right arrow
</li>
<li>
<kbd>Control + Up Arrow</kbd> - Moves focus from anywhere in the accordion content to its associated accordion header or tab respectively.
</li>
<li>
<kbd>Control + Page Up</kbd> -
<ul>
<li>When focus is inside of an accordion pane, pressing <kbd>Control + Page Up</kbd> moves focus to the accordion header of the previous accordion pane.</li>
<li>When focus is in the first accordion header content, pressing <kbd>Control + Page Up</kbd> optionally moves focus to the last accordion header.</li>
<li>Focus will simply move to the header and will require <kbd>Enter/Space</kbd> to expand/collapse the accordion pane.</li>
</ul>
</li>
<li>
<kbd>Control + Page Down</kbd> -
<ul>
<li>When focus is inside of an accordion pane, pressing <kbd>Control + Page Down</kbd> moves focus to the header of the accordion pane.</li>
<li>When focus is in the last accordion header content, pressing <kbd>Control + Page Down</kbd> optionally moves focus to the first accordion header.</li>
<li>In the case of an accordion, focus simply moves to the header and requires <kbd>Enter/Space</kbd> to expand/collapse the accordion pane.</li>
</ul>
</li>
<li>
<kbd>End</kbd> - When focus is on the accordion header, an <kbd>End</kbd> key press moves focus to the last accordion header.
</li>
<li>
<kbd>Home</kbd> - When focus is on the accordion header, a <kbd>Home</kbd> key press moves focus to the first accordion header.
</li>
<li>
<kbd>Enter/Space</kbd> - When focus is on an accordion header, pressing <kbd>Enter/Space</kbd> toggles the expansion of the corresponding panel.
<ul>
<li>If collapsed, the panel is expanded, and its aria-expanded state is set to 'true'.</li>
<li>If expanded, the panel is collapsed and its aria-expanded state is set to 'false'.</li>
</ul>
</li>
<li>
<kbd>Shift + Tab</kbd> - Generally the reverse of <kbd>Tab</kbd>.
</li>
<li>
<kbd>Alt + Delete</kbd> -
<ul>
<li>
When deletion is allowed, with focus anywhere within the tab panel or tab, pressing <kbd>Alt + Delete</kbd> will delete the current tab and tab panel from the tabbed interface control.
If additional tabs remain in the tabbed interface, focus goes to the next tab in the tab list.
If no additional tabs remain, then focus moves to the last place that held focus in the previous tab panel.
</li>
<li>
An alternative to providing a keystroke to close a tab is to provide a context menu that is associated with the tab title.
When focus is on the tab, pressing <kbd>Shift + F10</kbd> or pressing the right mouse button will open a context menu with the close choice.
</li>
<li>A warning should be given to the user before allowing the delete to occur.</li>
</ul>
</li>
</ul>
<p>
In Firefox, pressing <kbd>Control + Page Up</kbd> / <kbd>Control + Page Down</kbd> moves between browser tabs.
Firefox also supports <kbd>Control + Tab</kbd> and <kbd>Control + Shift + Tab</kbd> to move between tabs.
Internet Explorer 7 also uses <kbd>Control + Tab</kbd> and <kbd>Control + Shift + Tab</kbd>.
There may be advantages to using <kbd>Control + Page Up</kbd>/<kbd>Page Down</kbd> as the keys to change tabs; it is a recognizable keystroke to at least Firefox users and it is also supported by the Windows operating system to move between panels in a tabbed dialog.
</p>
<p>You should be aware of two issues with using <kbd>Control + Page Up</kbd>/<kbd>Page Down</kbd>:</p>
<ul>
<li>
The first arises when the user is within a tabbed interface control on a Web page.
Here they can not easily switch browser tabs without first moving focus outside of the tabbed interface control.
This may be acceptable.
</li>
<li>
The second arises when the entire web page is a tabbed interface control.
In this case the user could not switch browser tabs unless the control on the web page ignored the <kbd>Control + Page Up</kbd>/<kbd>Page Down</kbd> keypress (and thus letting the browser access it) when the first or last tab was reached.
</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties:</h4>
<ul>
<li>
The accordion component must have a role of <a href="#tablist" class="role-reference">tablist</a> and have <a href="#aria-multiselectable" class="property-reference">aria-multiselectable</a>="true"
This will enable an assistive technology, such as screen reader, to convey that the tablist is an accordion or a multi selectable tablist.
This will also tell the user that the keyboard navigation matches an accordion and not a tablist.
</li>
<li>Contained within the tablist is a set of tab/tabpanel pairs.</li>
<li>Each header tab in the tablist has a role of <a href="#tablist" class="role-reference">tab</a>.</li>
<li>The accordion panel uses the role <a href="#tabpanel" class="role-reference">tabpanel</a> and should have an <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> relationship referencing the corresponding header having a role of <a href="#tablist" class="role-reference">tab</a></li>
<li>The tabpanel is considered a grouping for all content consisting of that tabpanel.</li>
<li>An accordion should manage the expanded/collapsed state of each tab by maintaining its <a href="#aria-expanded" class="state-reference">aria-expanded</a> state.</li>
<li>An accordion should manage the selected state of each tab by maintaining its <code class="state-reference">aria-selected</code> state.</li>
<li>An accordion should convey the visibility of each tabpanel by maintaining its <a href="#aria-hidden" class="state-reference">aria-hidden</a> state.</li>
</ul>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">
Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section.
The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.
</p>
<p><a href="http://www.oaa-accessibility.org/examplep/accordian1/" target="_blank">Open Ajax Alliance Accordion</a></p>
</section>
</section>
<section class="widget" id="alert">
<h3>Alert</h3>
<p>
An <a class="role-reference" href="#alert">alert</a> is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task.
Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound.
It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes.
</p>
<p>
Because an alert is intended to provide important and potentially time-sensitive information without interfering with the user's ability to continue working, authors should ensure alerts do not affect the keyboard focus.
If there is a need to interrupt work flow, consider using an <a href="#alertdialog">alert dialog</a>
</p>
<p>
In most circumstances, authors should avoid making alerts disappear automatically.
An alert that disappears too quickly can lead to failure to meet <a href="http://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-no-exceptions.html">WCAG 2.0 success criterion 2.2.3</a>.
In addition, authors should be careful to avoid overuse of alerts.
Frequent interruptions inhibit usability for people with visual and cognitive disabilities, leading to failures to meet <a href="http://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html">WCAG 2.0 success criterion 2.2.4</a>.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>An alert (WAI-ARIA live region) does not require any keyboard interaction.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>The widget has a role of <a class="role-reference" href="#alert">alert</a>.</p>
</section>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/alert/index.html">Alert role example</a></p>
</section>
</section>
<section class="widget" id="alertdialog">
<h3>Alert Dialog or Message Dialog</h3>
<p class="note">This section has had only minor edits since it was integrated from APG version 1.0 -- a complete APG task force review is pending.</p>
<p>
A dialog with the primary purpose of communicating a message and acquiring a user response to that message.
Examples include action confirmation prompts, warning messages, or help for an invalid form entry.
The dialog should be modal.
Keyboard focus is set on an element in the dialog.
The element that has initial focus will depend on the nature of the information conveyed in the dialog.
Simple message dialogs, as described below, have their initial focus set to the confirmation button (e.g., the OK button).
Detail message dialogs have their initial focus set on the element containing the message.
</p>
<p>A detail message dialog conveys a message that has any one of the following attributes:</p>
<ul>
<li>Is more than one sentence in length;</li>
<li>Contains information where punctuation is an essential part of the message, such as syntax of a required date format;</li>
<li>Contains detail information the user may need to re-use, e.g., a phone number, e-mail address, error number, etc.;</li>
<li>Contains an interactive element, such as a link to a help resource.</li>
</ul>
<p>If the dialog is not a detail message dialog, one can consider it a simple message dialog.</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p><a href="#dialog_modal">See Dialog (Modal)</a>.</p>
<ul>
<li>Content authors make alert dialogs modal by ensuring that, while the alertdialog is shown, keyboard and mouse interactions only operate within the dialog.</li>
<li>The message area of a detail message dialog is focusable and has a <a class="role-reference" href="#document">document</a> role so screen reader users will have complete access to the message content, e.g., the screen reader can read it by character, word, or line.</li>
<li>When the message area of a dialog is focusable and has focus, a visual focus indicator is required, and it is recommended that the indicator encompass the complete message.</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The node containing all elements of the dialog, including the alert message and any dialog buttons, has an <a class="role-reference" href="#alertdialog">alertdialog</a> role.</li>
<li>Message areas have role <a class="role-reference" href="#document">document</a> and tabindex="0".</li>
<li>The Alert dialog has an <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> that references the title of the dialog. If there is not a visible title, use an appropriate <a href="#aria-labelledby" class="property-reference">aria-label</a> instead.</li>
<li>The element with role alertdialog has an <a href="#aria-labelledby" class="property-reference">aria-describedby</a> referring to the message element that has role <a class="role-reference" href="#document">document</a>.</li>
</ul>
</section>
<section class="notoc">
<h4>Example</h4>
<p class="note">
Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section.
The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.
</p>
<p><a href="http://www.oaa-accessibility.org/examplep/alertdialog1/" title="Example 2 - Alert example using a modal ARIA dialog box" target="_blank">Open Ajax Alliance</a></p>
</section>
</section>
<section class="widget" id="autocomplete">
<h3>Auto Complete</h3>
<p class="note">This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.</p>
<p>
A text box and an associated drop-down list of choices where the choices offered are filtered based on the information typed into the box.
Typically, an icon associated with the text box triggers the display of the drop-down list of choices.
An editable auto-complete accepts text entry of choices that are not in the list.
An example of an editable auto-complete is the URL field in the browsers.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li>
With focus in an empty text box, press <kbd>Down Arrow</kbd>, <kbd>Up Arrow</kbd>, <kbd>Alt + Down Arrow</kbd>, or <kbd>Alt + Up Arrow</kbd> to display the entire list of choices.
Focus remains in the text box and no choice is highlighted.
<ul>
<li>Press the <kbd>Down Arrow</kbd> to highlight the first choice in the list.</li>
<li>Press the <kbd>Down Arrow</kbd> and <kbd>Up Arrow</kbd> keys to highlight the desired choice in the list.</li>
<li>
Note that the arrows will wrap through the text box when the top or bottom of the list is reached.
For example, pressing the down arrow when the last choice is highlighted will move focus back to the text box, pressing down again will move focus to the first item in the list.
Likewise, with focus in the text box and the list displayed, pressing up arrow will move focus to the last item in the list.
</li>
<li>When a choice is highlighted using the arrow keys, the highlighted choice is displayed in the text box.</li>
<li>
Press <kbd>Enter</kbd> to select the highlighted choice and close the drop-down list.
This mimics the behavior of the HTML select element.
</li>
</ul>
</li>
<li>
With the drop-down list of choices displayed, move the mouse pointer over an item in the list to highlight it.
The text box value is not modified when the mouse is used to highlight a choice.
Clicking on the highlighted choice will close the drop-down and update the text box with the selected choice.
This mimics the behavior of the HTML select element.
</li>
<li>
With focus in an empty text box, type <strong>any letter</strong>.
If any of the available choices begin with the letter typed, those choices are displayed in a drop down.
If the letter typed does not match any of the available choices the drop-down list is not displayed.
</li>
<li>
With focus in text box with an existing value type <strong>additional letters.</strong>
As the user types letters the list of choices is filtered so that only those that begin with the typed letters are displayed.
<ul>
<li>Until the user presses the arrow keys to highlight a particular choice, only the typed letters are displayed in the text box.</li>
<li>In an editable auto-complete, if no choices match the letter(s) typed, the drop down list closes.</li>
<li>
In a non-editable auto-complete, any letters that do not result in a match from the list are ignored.
The drop down list of choices remains static until the user presses:
<ul>
<li><kbd>Escape</kbd> to clear the text field</li>
<li><kbd>Backspace</kbd> to remove some of the letters previously typed</li>
<li>an additional letter that results in a valid list of choices.</li>
</ul>
</li>
<li>
Navigation through the list of choices and display of the highlighted choice in the text box works as described above.<br>
<em>
Optional: When a choice is highlighted via arrow key navigation, the input cursor is left at the end of the typed entry and the highlighted choice is displayed in the text box with the characters after the input cursor selected.
Typing an additional character will remove the auto-completed portion and append the newly typed character to the end of the previously typed characters.
The list will be filtered based on the additional character(s) typed.
</em>
</li>
</ul>
</li>
<li>With focus in a text box, press <kbd>Escape</kbd>
<ul>
<li>If there is no text in the text box, pressing <kbd>Escape</kbd> closes the drop-down if it is displayed.</li>
<li>
For an editable autocomplete that has text in the text box that was both typed by the user and auto-completed by highlighting a choice using the keyboard, the auto-completed portion of the text is cleared and the user typed characters remain in the text box.
The drop-down list is closed.
To completely clear the text box contents the user must use the backspace key to remove the typed characters.
This is how the Google search box in the Firefox UI works.
<em>Recommend that pressing the <kbd>Escape</kbd> key again completely clears the text box rather than relying on only the backspace key.</em>
</li>
<li>For a non-editable auto-complete that has text in the text box that was both typed by the user and auto-completed by highlighting a choice using the keyboard, pressing <kbd>Escape</kbd> closes the drop-down list and leaves the current choice in the text box.</li>
<li>
For an editable or non-editable auto complete with text in the text box that was typed by the user and the mouse is highlighting a choice in the drop down (keyboard navigation was NOT used), pressing <kbd>Escape</kbd> closes the drop down and leaves the typed text displayed in the text box.
Need to consider if pressing <kbd>Escape</kbd> again should clear the typed text.
The user must press the <kbd>Down</kbd> arrow or <kbd>Alt + Down</kbd> arrow or click the associated icon to invoke the drop-down list of choices again.
</li>
</ul>
</li>
<li>Moving focus out of an empty auto complete field where a value is required should either invoke an error or if a default value was initially assigned, reset the value to the default value.</li>
<li>Moving focus out of an auto complete field that does not contain a valid entry should either invoke an error or if a default value was initially assigned, reset the value to the default value.</li>
</ul>
<p class="note">
It is good practice to limit the number of matching items in the drop down to a reasonable number.
The reasonable number is determined by the task at hand.
A list of the 50 US States is probably reasonable, but a list containing all of the office numbers in a building is probably not appropriate.