-
Notifications
You must be signed in to change notification settings - Fork 48
/
Copy pathindex.html
5152 lines (5133 loc) · 207 KB
/
index.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 lang="en-US">
<head>
<meta charset="utf-8">
<title>ARIA in HTML</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
<script class="remove">
var respecConfig = {
editors: [
{
name: "Steve Faulkner",
company: "TPGi",
companyURL: "https://www.tpgi.com/",
w3cid: "35007",
retiredDate: "2023-04-28"
},
{
name: "Scott O'Hara",
company: "Microsoft",
companyURL: "https://www.microsoft.com/",
w3cid: "103856"
},
{ name: "Patrick H. Lauke",
company: "TetraLogical",
companyURL: "https://tetralogical.com/",
w3cid: '35129'
},
],
previousMaturity: "REC",
perEnd: "2022-09-01",
previousPublishDate: "2021-12-09",
implementationReportURI: "https://w3c.github.io/html-aria/results/implementation-results.html",
github: "w3c/html-aria/",
maxTocLevel: 2,
shortName: "html-aria",
specStatus: "ED",
revisionTypes: ["addition", "correction"],
group: "webapps",
wgPublicList: "public-webapps",
xref: true,
errata: "https://github.com/w3c/html-aria/issues/new/",
};
</script>
<link rel="stylesheet" href="makeup.css">
</head>
<body data-cite="HTML WAI-ARIA INFRA">
<section id="abstract">
<p>
This specification defines the authoring rules (author conformance requirements) for the use
of [[[wai-aria-1.2]]] and [[[dpub-aria-1.0]]] attributes on [[HTML]] elements.
This specification's primary objective is to define requirements for use
with conformance checking tools used by authors (i.e., web developers). These requirements will aid authors
in their development of web content, including custom interfaces and widgets, which make use of ARIA to
complement or extend the features of the host language [[HTML]].
</p>
</section>
<section id="sotd" class="updateable-rec">
<p>
ARIA in HTML is an [[HTML]] specification module. Any HTML features, conformance requirements, or terms that this specification
module makes reference to, but does not explicitly define, are defined by the [[HTML|HTML Standard]].
</p>
<p>
Since this specification become a W3C Recommendation on 09 December 2021,
the following substantive additions and/or corrections have been proposed:
</p>
<ul>
<li>
<a href="https://github.com/w3c/html-aria/pull/525">23 December 2024 - Addition:</a>
Update the <a href="#el-img">`img`</a> element to allow the `math` role.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/533">13 December 2024 - Addition:</a>
Update to include the `image` role as preferred synonym to the `img` role.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/507">13 December 2024 - Addition:</a>
Clarify the allowance for `aria-hidden` when used with the `hidden` attribute.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/489">4 October 2023 - Addition:</a>
Update the button element and input type=button,image,reset,submit elements to allow the `separator` role.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/453">3 October 2023 - Correction:</a>
Update the <a href="#el-img">`img`</a> element allowances to be based on if the element has an accessible name or not.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/462">21 August 2023 - Addition:</a>
Update the <a href="#el-address">`address`</a> and <a href="#el-hgroup">`hgroup`</a> element allowances per their updated mapping to the `group` role.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/455">9 July 2023 - Addition:</a>
Update the <a href="#el-aside">`aside`</a> element to allow the dpub `doc-glossary` role.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/446">5 July 2023 - Addition:</a>
Update the <a href="#el-button">`button`</a>, <a href="#el-input-button">`input type=button`</a>, <a href="#el-input-image">`input type=image`</a>
<a href="#el-input-reset">`input type=reset`</a>, and <a href="#el-input-submit">`input type=submit`</a> elements to align their allowed roles.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/469">29 June 2023 - Addition:</a>
Update the <a href="#el-s">`s`</a> element allowed roles to indicate use of `role=deletion` on the element would be considered redundnat.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/435">31 May 2023 - Correction:</a>
Conditionally revise allowed `aria-*` attributes and roles on <a href="#el-summary">`summary`</a> element.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/410">31 May 2023 - Correction:</a>
Update <a href="#el-li">`li`</a> element role allowances in context to the element's ancestral relationship, or lack of,
to a list element parent.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/401">24 March 2023 - Addition:</a>
The <a href="#el-search">`search`</a> element has been added.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/447">6 March 2023 - Addition:</a>
Disallow `aria-hidden=true` on the `body` element.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/415">13 February 2023 - Addition:</a>
Update `figure` element role allowances to include `doc-example`.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/437">07 November 2022 - Correction:</a>
Revisions to 'any role' term description.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/383">14 July 2022 - Correction:</a>
Disallow roles and `aria-*` attributes on the <a href="#el-datalist">`datalist`</a> element.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/372">16 April 2022 - Correction:</a>
<a href="#att-checked">`aria-checked`</a> is not to be used on elements that support the `checked` attribute.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/402">03 April 2022 - Addition:</a>
Identify <a href="#dfn-naming-prohibited">Naming Prohibited</a> elements.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/404">06 March 2022 - Addition:</a>
Allow `none` and `presentation` roles on <a href="#el-nav">`nav` element</a>.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/403">03 March 2022 - Addition:</a>
Restrict role allowances for <a href="#el-div">`div` element</a> when it is a child of a `dl` element.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/396">12 February 2022 - Addition & Correction:</a>
Allow `combobox` role on <a href="#el-button">`button` element</a>.
Allow `combobox` and `checkbox` roles on <a href="#el-input-button">`input type=button` element</a>.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/391">18 January 2022 - Addition:</a>
Added <a href="#docconformance-deprecated">Requirements for deprecated ARIA role, state and property attributes</a>.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/369">06 January 2022 - Addition:</a>
Change allowances for `doc-biblioentry` and `doc-endnote` roles on the <a href="#el-li">`li` element</a>.
These roles are deprecated in [[[dpub-aria-1.1]]].
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/381">13 December 2021 - Correction:</a>
Allow `radio` role on <a href="#el-img">`img alt="some text"` element</a>.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/353">07 December 2021 - Correction:</a>
Allow only `none` and `presentation` roles for <a href="#el-wbr">`wbr` element</a>.
Allow only `aria-hidden` global attribute for <a href="#el-br">`br`</a> and <a href="#el-wbr">`wbr`</a> elements.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/367">02 December 2021 - Addition:</a>
Allow `group` role on <a href="#el-section">`section` element</a>.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/360">16 November 2021 - Addition:</a>
Allow `link` and `button` roles on <a href="#el-area-no-href">`area` without `href` element</a>.
</li>
<li>
<a href="https://github.com/w3c/html-aria/pull/352">26 October 2021 - Addition:</a>
Allow `aria-hidden` attribute on the <a href="#el-picture">`picture` element</a>.
</li>
</ul>
<p>
Reviewers of the document can identify candidate additions
and/or corrections by their distinctive styling in the document:
</p>
<p class="correction">Candidate corrections are marked in the document.</p>
<p class="addition">Candidate additions are marked in the document.</p>
</section>
<section>
<h2 id="rules-wd">
Author requirements for use of ARIA in HTML
</h2>
<p>
Authors MAY use the ARIA `role` and `aria-*` attributes to change
the exposed meaning (<a data-cite="html/dom.html#semantics-2">semantics</a>) of
[=HTML elements=], in accordance with the requirements defined by
[[wai-aria-1.2|WAI-ARIA]], except where ARIA features conflict with the
<dfn data-cite="wai-aria-1.2#host_general_conflict">strong native semantics</dfn>
or are equal to the
<dfn data-cite="wai-aria-1.2#implicit_semantics">implicit ARIA semantics</dfn>
of a given HTML element. The <a>implicit ARIA semantics</a> for the features
of HTML are defined by the [[html-aam-1.0|HTML Accessibility API Mappings]] specification.
</p>
<p>
Any constraints for the use of ARIA features in HTML defined by this specification
are intended to prevent authors from making assistive technology products report
nonsensical user interface (UI) information that does not represent the actual UI
of the document.
</p>
<p>
Authors MUST NOT use the ARIA `role` and `aria-*` attributes in a manner that conflicts
with the semantics described in the [[[#docconformance]]] and [[[#docconformance-attr]]]
tables. It is NOT RECOMMENDED for authors to set the ARIA `role` and `aria-*` attributes
to values that match the <a>implicit ARIA semantics</a> defined in either table.
Doing so is unnecessary and can potentially lead to unintended consequences.
</p>
</section>
<section class="informative">
<h2>ARIA semantics that extend and diverge from HTML</h2>
<p>
Through the use of ARIA, authors can specify semantics that go beyond the current
capabilities of native HTML. This can be very useful, as it provides authors the opportunity
to create widgets, or expose specific accessible states and properties to native HTML features
which would not be possible by the use of HTML alone.
</p>
<p>
For instance, a `button` element has no native HTML feature to expose a "pressed" state.
ARIA allows authors to extend the semantics of the element by specifying the `aria-pressed`
attribute, allowing for an aural UI that will match the visual presentation of the control.
</p>
<p>
In the following example, a `button` element allows for a user to toggle the state of a
setting within a web application. The `aria-pressed` attribute is used to
augment the `button` element. When in the "pressed" state that information can be
exposed to users of assistive technologies.
</p>
<pre class="HTML example" title="Communicate a button's pressed state with ARIA">
<button aria-pressed=true>...</button>
</pre>
<p>
There are also situations where certain `aria-*` attributes are allowed for use on elements
with specific `role`s, while the equivalent native attribute is currently not valid in HTML itself.
</p>
<p>
For instance, HTML has no direct concept of a disabled hyperlink (`a href` element).
Constructs such as `<a href="..." disabled> ... </a>` are not valid,
and will not be conveyed to assistive technologies.
</p>
<p>
ARIA diverges from HTML in this regard and does allow for an `aria-disabled`
attribute to be specified on an element with an explicit `role=link`. If an author were
to specify an `aria-disabled=true` on an HTML hyperlink, user agents would not functionally
treat the hyperlink any differently (it would still be clickable/operable), however it
would be exposed to assistive technologies as being in the disabled state.
</p>
<p>
Similarly, while native HTML `option` elements that are descendants of a `select` can
only be set as being `selected`, elements with an explicit `option` role can not only
allow the equivalent `aria-selected`, but also the `aria-checked` attribute, supporting
widgets/constructs that go beyond the capabilities of a native `select` element.
</p>
<p>
Unfortunately, in these situations where ARIA and HTML have feature parity, but diverge
in allowances, it can create for a misalignment in support, if not also user experiences.
In situations where ARIA allows a feature not supported by HTML, it will often
be in the author's and ultimately the user's best interest to instead implement as a
fully custom ARIA widget.
</p>
<p>
In the following example, a hyperlink needs to be communicated as being in the disabled
state. HTML does not allow for the use of the `disabled` attribute on a hyperlink,
and using `aria-disabled=true` would communicate the hyperlink as being disabled to
assistive technologies, but would not actually disable the element. The most effective way
to both communicate and actually disable a hyperlink would be to remove the `href` from
the [^a^] element, creating a placeholder. Then, ARIA can be applied to this
placeholder link to communicate the element's intended role and state.
</p>
<pre class="HTML example" title="Communicate a disabled link with ARIA">
<a role=link aria-disabled=true>...</a>
</pre>
</section>
<section class="informative">
<h2>
Author guidance to avoid incorrect use of ARIA
</h2>
<section>
<h3>
Avoid overriding interactive elements with non-interactive roles
</h3>
<p>
ARIA is useful for revising or correcting the role of an element when a different role
is necessary to expose to users. However, it is rarely in the user or author's best interest
to try and use ARIA to override an interactive element, for instance a `button`, with a role
generally exposed by a non-interactive element. For instance, a heading.
</p>
<p>
As an example, the following uses a `role=heading` on a [^button^] element. This is
not allowed, because the `button` element has default functionality that conflicts with user
expectations for the heading role.
</p>
<pre class="example HTML" title="Wrong role">
<button role="heading">search</button>
</pre>
<p>
An author would need to take additional steps to ensure the default functionality and presentation of
the `button` was removed, and even doing so may still not be enough to fully supress the element's
implicit features depending on how the user chooses to engage with the web page. E.g., by turning on
Windows high contrast themes, or viewing the web page in a browser's reader mode.
</p>
</section>
<section>
<h3>
Avoid specifying redundant roles
</h3>
<p>
The following example illustrates a [^button^] element which has also been
provided an explicit `role=button`. Specifying this role is unnecessary, as a "button"
element is already exposed with an implicit `button` role. In practice this particular
instance of redundancy will likely not have unforeseen side effects, other than
unnecessarily making the markup more verbose, and incorrectly signaling to other authors
that this practice is useful. Please review the section [[[#side-effects]]]
for an example of where specifying unnecessary roles can be problematic.
</p>
<pre class="example HTML" title="Redundant role on button">
<!-- Avoid doing this! -->
<button role="button">...</button>
</pre>
<p>
Similarly, the following uses a `role=group` on a [^fieldset^] element, and a `role=Main` on a [^main^] element.
This is unnecessary, because the `fieldset` element is implicitly exposed as a `role=group`, as is the `main` element
implicitly exposed as a `role=main`. Again, in practice this will likely not have any unforeseen side effects to users
of assistive technology, as long as the declaration of the `role` value uses [=ASCII lowercase=].
Please see [[[#case-sensitivity]]] for more information.
</p>
<pre class="HTML example" title="Redundant role on fieldset and main">
<!-- Avoid doing this! -->
<fieldset role="group">...</fieldset>
<!-- or this! -->
<main role="Main">...</main>
</pre>
<p>
The following uses a `role=list` on an [^ul^] element. As the `ul` element has an implicit role of `list`,
explicitly adding the role would generally be considered redundant. However, some user agents suppress a list's
implicit ARIA semantics if the list markers are removed from the visual presentation of the list items.
Generally the redundant declaration of an element's implicit role would not be recommended, but in specific situations
such as this, and where the role is necessary to expose, authors can explicitly add the role.
</p>
<pre class="HTML example" title="Redundant role on list">
<!-- Generally avoid doing this! -->
<ul role="list">...</ul>
</pre>
</section>
<section>
<h3 id="side-effects">
Be cautious of side effects
</h3>
<p>
The following uses a `role=button` on a [^summary^] element. This is
unnecessary and can result in cross-platform issues. For instance,
preventing the element from correctly exposing its state, and forcing
the role of `button`, when it might otherwise be exposed with a
platform or browser specific role.
</p>
<pre class="HTML example" title="Unintended consequences">
<details>
<!-- Avoid doing this! -->
<summary role="button">more information</summary>
...
</details>
</pre>
</section>
<section>
<h3>Adhere to the rules of ARIA</h3>
<p>
[[[wai-aria-1.2]]] defines a number of roles which are not meant to be used
by authors. Many of these roles are categorized as <a data-cite="wai-aria-1.2#isAbstract">Abstract Roles</a>
which are explicitly stated as not to be used by authors. The following example illustrates the invalid use of an
abstract `select` role, where an author likely meant to use the `combobox` role instead.
</p>
<pre class="HTML example" title="Abstract roles are not for authors">
<!-- Do not do this! -->
<div role="select" ...>...</div>
</pre>
<p>
ARIA also defines a <a data-cite="wai-aria-1.2#generic">`generic` role</a> which is meant to provide
feature parity with a number of HTML elements that do not have more specific ARIA semantics of their
own. For instance, HTML's [^div^] and [^span^] elements, among others. ARIA discourages authors from
using the `generic` role as its intended purpose is for use by implementors of user agents.
</p>
<p>
In the following example, rather than using a `generic` role, authors are advised to use a `div` in
place of the `article` element. If changing the HTML element is not possible, specifying a role of
`presentation` or `none` would be acceptable alternaties to remove the implicit role of the `article`.
</p>
<pre class="HTML example" title="Do not specify elements as generic">
<!-- Avoid doing this! -->
<article role="generic" ...>...</article>
</pre>
<p>
Additionally, ARIA specifically mentions in <a data-cite="wai-aria-1.2/#host_general_conflict">Conflicts with Host Language Semantics</a>
that if authors use both native HTML features for exposing states and properties as well as their ARIA counterparts, then
the host language features take priority over the explicit ARIA attributes that are also used.
</p>
<p>
For instance, in the following example an author is using HTML's `input type=checkbox` and has specified an `aria-checked=true`. However,
user agents are meant to ignore the `aria-checked` attribute. Instead user agents would expose the state based on the native features
of the form control.
</p>
<pre class="HTML example" title="The implicit checked state takes precedent over the explicit ARIA attribute">
<!-- Do not do this! -->
<input type="checkbox" checked aria-checked="false">
</pre>
</section>
<section>
<h3>Adhere to the rules of HTML</h3>
<p>
While ARIA can be used to alter the way HTML features are exposed to users of assistive technologies,
these modifications do not change the underlying parsing and allowed content models of HTML. For instance,
a [^div^] allows an author to specify any role on it. However, this does not mean that the element can then be
used in a way that deviates from the rules HTML has defined for the element.
</p>
<p>
For instance, in the following example an author has specified a role of `link` on a `div` element. While
HTML allows for a hyperlink (exposed as a `role=link`) to be a descendant of a `p` element, the HTML parser does not
allow a `div` to be a descendant of a `p` element.
</p>
<pre class="HTML example" title="Revised ARIA semantics with invalid HTML nesting">
<!-- Do not do this! -->
<p>
... <div role=link tabindex=0>...</div> ...
</p>
</pre>
<p>
The HTML parser will modify the above markup to be output as the following:
</p>
<pre class="HTML example" title="Unwanted rendered markup with valid alternative solution">
<!-- The previous example's markup will render as follows -->
<p>...</p>
<div role=link tabindex=0>...</div>
...
<p></p>
<!-- Instead of a div, use a span. Spans are allowed descendants of p elements! -->
<p>
... <span role=link tabindex=0>...</span> ...
</p>
</pre>
<p>
While this specification indicates the allowed ARIA attributes that can be specified on each HTML element,
this example illustrates that even if a role is allowed, the context in which it is used can still result
in potential rendering and accessibility issues.
</p>
</section>
</section>
<section>
<h2 id="docconformance">
Document conformance requirements for use of ARIA attributes in HTML
</h2>
<p>
The following table provides normative per-element document conformance requirements for the
use of ARIA markup in HTML documents. Additionally, it identifies the <a>implicit ARIA semantics</a>
that apply to [=HTML elements=]. The <a>implicit ARIA semantics</a> of these elements are defined
in [[html-aam-1.0|HTML AAM]].
</p>
<p>
Each language feature (element) in a cell in the first column implies the ARIA semantics
(role, states, and properties) given in the cell in the second column of the same row.
The third cell in each row defines the ARIA `role` values and `aria-*` attributes which authors MAY specify
on the element. Where a cell in the third column includes the term <dfn><strong>Any</strong> `role`</dfn>
it indicates that any `role` value <span class="addition correction">MAY be used on the element. However,
it is NOT RECOMMENDED for authors to specify the implicit role of the element, the `generic` role, or a role
<a href="#docconformance-deprecated">deprecated by ARIA</a> on these elements.</span>
If a cell in the third column includes the term <dfn><strong>No `role`</strong></dfn> it indicates
that authors MUST NOT overwrite the implicit ARIA semantics, or native semantics of the HTML element.
</p>
<div class="addition">
<p>
[[wai-aria-1.2|WAI-ARIA]] identifies roles which have
<a data-cite="wai-aria-1.2/#prohibitedattributes">prohibited states and properties</a>.
These roles do not allow certain WAI-ARIA attributes to be specified by authors.
HTML elements which expose these implicit WAI-ARIA roles also prohibit authors from
specifying these WAI-ARIA attributes.
</p>
<p>
Elements which are identified as <dfn>Naming prohibited</dfn> are those which authors MUST NOT specify an
`aria-label` or `aria-labelledby` attribute, unless the element allows for its implicit role to be overwritten
by an explicit WAI-ARIA role which allows naming from authors. For more information see [[[#docconformance-naming]]].
</p>
</div>
<p class="note" id="aria-usage-note">
While setting an ARIA `role` and/or `aria-*` attribute that matches the <span>implicit ARIA semantics</span>
is NOT RECOMMENDED, in some situations explicitly setting these attributes can be helpful – for instance,
for user agents that do not expose implicit ARIA semantics for certain elements.
</p>
<p class="note" id="dpub-usage-note">
While it is conforming to use [[[dpub-aria-1.0]]] `role` values as outlined in the following table, the use of these roles
is not intended for implementation of websites. If using these role for purposes beyond the scope of the digital publishing
industry, further manual testing will be necessary to ensure the intended experience is provided to users.
</p>
<table class="data">
<caption>
Rules of ARIA attribute usage by HTML element
</caption>
<thead>
<tr>
<th>
HTML element
</th>
<th>
<p id="implicit">
Implicit ARIA semantics
<small>(explicitly assigning these in markup is NOT RECOMMENDED)</small>
</p>
</th>
<th>
ARIA role, state and property allowances
</th>
</tr>
</thead>
<tbody>
<tr>
<th id="el-a" tabindex="-1">
[^a^] with [^a/href^]
</th>
<td>
<code>role=<a href="#index-aria-link">link</a></code>
</td>
<td>
<p>
Roles:
<a href="#index-aria-button">`button`</a>,
<a href="#index-aria-checkbox">`checkbox`</a>,
<a href="#index-aria-menuitem">`menuitem`</a>,
<a href="#index-aria-menuitemcheckbox">`menuitemcheckbox`</a>,
<a href="#index-aria-menuitemradio">`menuitemradio`</a>,
<a href="#index-aria-option">`option`</a>,
<a href="#index-aria-radio">`radio`</a>,
<a href="#index-aria-switch">`switch`</a>,
<a href="#index-aria-tab">`tab`</a>
or <a href="#index-aria-treeitem">`treeitem`</a>. (<code><a href="#index-aria-link">link</a></code> is also allowed, but NOT RECOMMENDED.)
</p>
<p>
DPub Roles:
<a data-cite="dpub-aria-1.0#doc-backlink">`doc-backlink`</a>,
<a data-cite="dpub-aria-1.0#doc-biblioref">`doc-biblioref`</a>,
<a data-cite="dpub-aria-1.0#doc-glossref">`doc-glossref`</a>
or <a data-cite="dpub-aria-1.0#doc-noteref">`doc-noteref`</a>
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a> and
any `aria-*` attributes applicable to the allowed roles.
</p>
<p>
It is NOT RECOMMENDED to use `aria-disabled="true"` on an
`a` element with an `href` attribute.
</p>
<div class="note">
If a link needs to be programmatically communicated as "disabled",
<a href="#example-communicate-a-disabled-link-with-aria">remove the `href` attribute</a>.
</div>
</td>
</tr>
<tr>
<th id="el-a-no-href" tabindex="-1">
[^a^] without [^a/href^]
</th>
<td>
<code>role=<a href="#index-aria-generic">generic</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <code><a href="#index-aria-generic">generic</a></code> SHOULD NOT be used.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-abbr" tabindex="-1">
[^abbr^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a> and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-address" tabindex="-1">
[^address^]
</th>
<td>
<code>role=<a href="#index-aria-group">group</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <a href="#index-aria-group">`group`</a> is NOT RECOMMENDED.
</p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-area" tabindex="-1">
[^area^] with [^area/href^]
</th>
<td>
<code>role=<a href="#index-aria-link">link</a></code>
</td>
<td>
<p>
<a><strong class="nosupport">No `role`</strong></a> other than <code><a href="#index-aria-link">link</a></code>, which is NOT RECOMMENDED.
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the
<a href="#index-aria-link">`link`</a> role.
</p>
</td>
</tr>
<tr>
<th id="el-area-no-href" tabindex="-1">
[^area^] without [^area/href^]
</th>
<td>
<code>role=<a href="#index-aria-generic">generic</a></code>
</td>
<td>
<div class="addition">
<p>
Roles:
<a href="#index-aria-button">`button`</a>
or <a href="#index-aria-link">`link`</a>. (<code><a href="#index-aria-generic">generic</a></code> is also allowed, but SHOULD NOT be used.)
</p>
<p><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</div>
</td>
</tr>
<tr>
<th id="el-article" tabindex="-1">
[^article^]
</th>
<td>
<code>role=<a href="#index-aria-article">article</a></code>
</td>
<td>
<p>
Roles:
<a href="#index-aria-application">`application`</a>,
<a href="#index-aria-document">`document`</a>,
<a href="#index-aria-feed">`feed`</a>,
<a href="#index-aria-main">`main`</a>,
<a href="#index-aria-none">`none`</a>,
<a href="#index-aria-presentation">`presentation`</a>
or <a href="#index-aria-region">`region`</a>. (<code><a href="#index-aria-article">article</a></code> is also allowed, but NOT RECOMMENDED.)
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-aside" tabindex="-1">
[^aside^]
</th>
<td>
<code>role=<a href="#index-aria-complementary">complementary</a></code>
</td>
<td>
<p>
Roles:
<a href="#index-aria-feed">`feed`</a>,
<a href="#index-aria-none">`none`</a>,
<a href="#index-aria-note">`note`</a>,
<a href="#index-aria-presentation">`presentation`</a>,
<a href="#index-aria-region">`region`</a>
or <a href="#index-aria-search">`search`</a>. (<code><a href="#index-aria-complementary">complementary</a></code> is also allowed, but NOT RECOMMENDED.)
</p>
<p>
DPub Roles:
<a data-cite="dpub-aria-1.0#doc-dedication">`doc-dedication`</a>,
<a data-cite="dpub-aria-1.0#doc-example">`doc-example`</a>,
<a data-cite="dpub-aria-1.0#doc-footnote">`doc-footnote`</a>,
<span class="proposed addition"><a data-cite="dpub-aria-1.0#doc-glossary">`doc-glossary`</a>,</span>
<a data-cite="dpub-aria-1.0#doc-pullquote">`doc-pullquote`</a>
or <a data-cite="dpub-aria-1.0#doc-tip">`doc-tip`</a>
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-audio" tabindex="-1">
[^audio^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
Role:
<a href="#index-aria-application">`application`</a>
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the
<a href="#index-aria-application">`application`</a> role.
</p>
</td>
</tr>
<tr>
<th id="el-autonomous-custom-element" tabindex="-1">
<a>autonomous custom element</a>
</th>
<td>
<p>
Role exposed from author defined {{ElementInternals}}
</p>
<p>
Otherwise <code>role=<a href="#index-aria-generic">generic</a></code>
</p>
</td>
<td>
<p>
If role defined by `ElementInternals`,
<a><strong class="nosupport">no `role`</strong></a>
</p>
<p>
Otherwise, <a><strong>any `role`</strong></a>, though <code><a href="#index-aria-generic">generic</a></code> SHOULD NOT be used.
</p>
<p class="addition">
<a>Naming Prohibited</a> if exposed as the `generic` role, or if exposed
as another role which prohibits naming.
</p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-b" tabindex="-1">
[^b^]
</th>
<td>
<code>role=<a href="#index-aria-generic">generic</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <code><a href="#index-aria-generic">generic</a></code> SHOULD NOT be used.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-base" tabindex="-1">
[^base^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
<strong class="nosupport"><a>No `role`</a> or `aria-*` attributes</strong>
</p>
</td>
</tr>
<tr>
<th id="el-bdi" tabindex="-1">
[^bdi^]
</th>
<td>
<code>role=<a href="#index-aria-generic">generic</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <code><a href="#index-aria-generic">generic</a></code> SHOULD NOT be used.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-bdo" tabindex="-1">
[^bdo^]
</th>
<td>
<code>role=<a href="#index-aria-generic">generic</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <code><a href="#index-aria-generic">generic</a></code> SHOULD NOT be used.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-blockquote" tabindex="-1">
[^blockquote^]
</th>
<td>
<code>role=<a href="#index-aria-blockquote">`blockquote`</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <code><a href="#index-aria-blockquote">`blockquote`</a></code> is NOT RECOMMENDED.
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-body" tabindex="-1">
[^body^]
</th>
<td>
<code>role=<a href="#index-aria-generic">generic</a></code>
</td>
<td>
<p>
<a><strong class="nosupport">No `role`</strong></a> other than <code><a href="#index-aria-generic">generic</a></code>, which SHOULD NOT be used.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
<span class="addition proposal">
allowed for the `generic` role, with the exception that authors MUST NOT specify `aria-hidden=true` on the `body` element.
</span>
</p>
</td>
</tr>
<tr>
<th id="el-br" tabindex="-1">
[^br^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
Roles:
<a href="#index-aria-none">`none`</a>
or <a href="#index-aria-presentation">`presentation`</a>
</p>
<p class="addition">
Authors MAY specify the <a data-cite="wai-aria-1.2#aria-hidden">`aria-hidden`</a> attribute on the `br` element.
Otherwise, no other allowed `aria-*` attributes.
</p>
</td>
</tr>
<tr>
<th id="el-button" tabindex="-1">
[^button^]
</th>
<td>
<code>role=<a href="#index-aria-button">button</a></code>
</td>
<td>
<p>
Roles:
<a href="#index-aria-checkbox">`checkbox`</a>,
<span class="addition"><a href="#index-aria-combobox">`combobox`</a></span>,
<span class="proposed addition"><a href="#index-aria-gridcell">`gridcell`</a></span>,
<a href="#index-aria-link">`link`</a>,
<a href="#index-aria-menuitem">`menuitem`</a>,
<a href="#index-aria-menuitemcheckbox">`menuitemcheckbox`</a>,
<a href="#index-aria-menuitemradio">`menuitemradio`</a>,
<a href="#index-aria-option">`option`</a>,
<a href="#index-aria-radio">`radio`</a>,
<span class="proposed addition">
<a href="#index-aria-separator">`separator`</a>,
<a href="#index-aria-slider">`slider`</a></span>,
<a href="#index-aria-switch">`switch`</a>,
<a href="#index-aria-tab">`tab`</a>,
or <span class="proposed addition"><a href="#index-aria-treeitem">`treeitem`</a></span>.
(<code><a href="#index-aria-button">button</a></code> is also allowed, but NOT RECOMMENDED.)
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-canvas" tabindex="-1">
[^canvas^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>
</p>
<p>
<a data-cite="wai-aria-1.2#global_states">Global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-caption" tabindex="-1">
[^caption^]
</th>
<td>
<code>role=<a href="#index-aria-caption">`caption`</a></code>
</td>
<td>
<p>
<a><strong class="nosupport">No `role`</strong></a> other than <code><a href="#index-aria-caption">`caption`</a></code>, which is NOT RECOMMENDED.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>.
</p>
</td>
</tr>
<tr>
<th id="el-cite" tabindex="-1">
[^cite^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-code" tabindex="-1">
[^code^]
</th>
<td>
<code>role=<a href="#index-aria-code">`code`</a></code>
</td>
<td>
<p>
<a><strong>Any `role`</strong></a>, though <code><a href="#index-aria-code">`code`</a></code> is NOT RECOMMENDED.
</p>
<p class="addition"><a>Naming Prohibited</a></p>
<p>
Otherwise, <a data-cite="wai-aria-1.2#global_states">global `aria-*` attributes</a>
and any `aria-*` attributes applicable to the allowed roles.
</p>
</td>
</tr>
<tr>
<th id="el-col" tabindex="-1">
[^col^]
</th>
<td>
<a>No corresponding role</a>
</td>
<td>
<p>
<strong class="nosupport"><a>No `role`</a> or `aria-*` attributes</strong>
</p>
</td>