recursal/MDN huggingface dataset:
ARIA: math role
===============

The `math` role indicates that the content represents a mathematical expression.

Description
-----------

Content with the role `math` is intended to be marked up in an accessible format such as MathML, or with another type of textual representation, which can be converted to an accessible format by the browser or a polyfill library.

 Unfortunately, browser support for MathML is not universal. While using an image of a mathematical expression is not optimal, if you do use image, use the `math` role.
 Make sure any images of math are labeled by an `alt` attribute that describes the mathematical expression as it would be spoken.

If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use `aria-label` to provide a string that represents the expression. If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use `aria-labelledby`. Otherwise, use `aria-label` to name the expression, e.g., `aria-label="Pythagorean Theorem"`.

Examples
--------

If you use image or non-semantic HTML to create an equation, use the `math` role.

a2 + b2 = c2
The above pythagorean theorem is written accessibly as:


```html
<div role="math" aria-label="a^{2} + b^{2} = c^{2}">
  a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup>
</div>
```


Had an image been used, the `alt` attribute would be used along with the `math` role:


```html
<img src="pythagorean\_theorem.gif" alt="a^{2} + b^{2} = c^{2}" role="math" />
```

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # math |

See Also
--------

* MathML on MDN and the `<math>` element (not HTML)
* The MathML specification
ARIA: window role
=================

The `window` role defines a browser or app window.

**Note:** The `window` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors.

Description
-----------

The `window` role, an abstract role, is a superclass for roles defining a browser or app window. The sub-class roles, currently only the `dialog` role, have a window-like GUI, or graphical user interface, whether it's a full native window or just a section of a document styled to look like a window, where `role="dialog"` would be appropriate.

Best Practices
--------------

Do not use.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # window |

See Also
--------

* ARIA: `roletype` role
* ARIA: `dialog` role
ARIA: term role
===============

The `term` role can be used for a word or phrase with an optional corresponding `definition`.

Description
-----------

The `term` role can be used for a word or phrase with an optional corresponding `definition`. It is equivalent in semantics to the HTML `<dfn>` element and the definition term (`<dt>`) element within a definition list (`<dl>` ).

The `term` role is used to explicitly identify a word or phrase for which a definition has been provided by the author or is expected to be provided by the user. If there is an existing definition, or a form or form control to enter a definition, authors SHOULD set `aria-details` to point to the related element.

Don't use the `role="term"` on interactive elements like links because it can interfere with assistive technology users ability to interact with the element. Also, the term itself is the accessible name, so do not use `aria-label` or `aria-labelledby`.

**Warning:** The accessible name should be the term itself, so DO NOT use `aria-label` or `aria-labelledby`.

### Associated WAI-ARIA roles, states, and properties

None.

### Keyboard interactions

None.

### Required JavaScript features

None.

Examples
--------


```html
<p>
  <span role="term">Mansplaining</span>,
  <span role="definition"
 >a portmanteau of "man" and "explain", is the patronizing act of explaining
    without being asked to do so, to someone already learned on the topic, often
    after someone has already explained it</span
 >.
</p>
```


Including better semantics, the above could also be written:


```html
<p>
  <dfn role="term">Mansplaining</dfn>,
  <span role="definition"
 >a portmanteau of "man" and "explain", is the patronizing act of explaining
    without being asked to do so, to someone already learned on the topic, often
    after someone has already explained it</span
 >.
</p>
```


or without any ARIA (but possibly not how you want it presented)


```html
<dl>
  <dt>Mansplaining</dt>
  <dd>
    A portmanteau of "man" and "explain", is the patronizing act of explaining
    without being asked to do so, to someone already learned on the topic, often
    after someone has already explained it.
  </dd>
</dl>
```

Accessibility concerns
----------------------

Don't use the `role="term"` on interactive elements such as links as it can interfere with the assistive technology user's ability to interact with the element.

Best Practices
--------------

Allow the term itself to define the accessible name. Do not use `aria-label` or `aria-labelledby`.

### Prefer HTML

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # term |

See Also
--------

* ARIA: `definition` role.
* The HTML `<dfn>` element
ARIA: command role
==================

The `command` role defines a widget that performs an action but does not receive input data.

**Note:** The `command` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors.

Description
-----------

A command is form of widget that performs an action but does not receive input data. It is a superclass for the widget roles `button`, `link`, and `menuitem`

Best Practices
--------------

Do not use.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # command |

See Also
--------

* ARIA: `widget` role
* ARIA: `button` role
* ARIA: `link` role
* ARIA: `menuitem` role
ARIA: select role
=================

The **`select` role**, an abstract role, is superclass role for form widgets that allows the user to make selections from a set of choices.

**Note:** The `select` role is an abstract role. It is included here for completeness of documentation. It **should not be used** by web authors.

Description
-----------

The structural `select` role, an abstract role, is superclass role for four form widgets, `listbox`, `menu`, `radiogroup`, and `tree`, which allow users to make selections from a set of choices.

Best Practices
--------------

Do not use.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # select |

See Also
--------

* ARIA: `composite` role
* ARIA: `group` role
* ARIA: `listbox` role
* ARIA: `menu` role
* ARIA: `radiogroup` role
* ARIA: `tree` role
ARIA: generic role
==================

The `generic` role creates a nameless container element which has no semantic meaning on its own.

**Note:** The `generic` role is the implicit role of generic elements used by user agents. It is included here for completeness of documentation. It should not be used by web authors.

Description
-----------

While ARIA is primarily used to express semantics, there are some elements that shouldn't expose a semantic name to assistive technologies. The `generic` role indicates an element's role is equivalent to that of the non-semantic `<div>` and `<span>` elements.

The `generic` role is intended for use as the implicit role of generic elements in host languages for use by user agents only; not for use by developers. Instead, to remove implicit accessibility semantics, use `presentation` or `none`, the `<div>` and `<span>` elements that have no semantic meaning, or semantic container roles such as `group` to semantically group descendants in a named container.

Like an element with role `presentation`, an element with `role="generic"` can provide a limited number of accessible states and properties for its descendants, such as `aria-live` attributes. However, unlike elements with role `presentation`, `generic` elements are exposed in accessibility APIs so that assistive technologies can gather certain properties such as layout and bounds.

Because the generic role is nameless, the `aria-labelledby` and `aria-label` attributes are prohibited. Because the role is generic, the `aria-roledescription` and `aria-brailleroledescription` attributes are also prohibited.

**Note:** The element with `role="generic"` should not have an accessible name or role description.

### Associated WAI-ARIA roles, states, and properties

None. If a global ARIA state and property is set, `generic` or `none` will be ignored, and the implicit role of the element will be used.

Examples
--------

This role is for use by user agents and not by developers. As such, no appropriate example exists.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # generic |

See Also
--------

* HTML `<div>` and `<span>` elements
* `presentation` roles such as
* `group` role
ARIA: status role
=================

The `status` role defines a live region containing advisory information for the user that is not important enough to be an `alert`.

Description
-----------

A `status` is a type of live region providing advisory information that is not important enough to justify an alert, which would immediately interrupt the announcement of a user's current activity. It is often, but not necessarily, presented as a status bar.

Do not give focus to the status when its content updates. Live regions are meant to inform users of dynamic updates that have occurred in other areas of the current web page, but which do not necessitate interrupting the user's current activity with a change in context. If a situation requires that focus needs to be moved, then using a `status`, or other live region, are likely not appropriate.

Elements with the role status have an implicit `aria-live` value of `polite` and an implicit `aria-atomic` value of `true`.

### Associated WAI-ARIA roles, states, and properties

`aria-atomic`

Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `status` have an implicit aria-atomic value of `true`.

`aria-live`

Defines when assistive technology should inform the user of updates to content. Elements with the role `status` have an implicit aria-live value of `polite`, meaning screen readers will announce changes inside the log when the user is idle.

`aria-label` or `aria-labelledby`

Some screen readers announce the name of a status element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a status element with text that is not displayed when a screen reader reads the content. Naming a status is not required so if nothing is appropriate both these attributes can be omitted.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # status |

See Also
--------

* ARIA: `alert` role
* ARIA: `log` role
* ARIA: `marquee` role
* ARIA: `timer` role
* ARIA live regions
ARIA: timer role
================

The **`timer`** role indicates to assistive technologies that an element is a numerical counter listing the amount of elapsed time from a starting point or the remaining time until an end point. Assistive technologies will not announce updates to a timer as it has an implicit aria-live value of `off`.


```html
<div role="timer" id="eggtimer">0</div>
```


This defines this `div` element as a timer with no remaining time.

Description
-----------

The `timer` role indicates to assistive technologies that this part of the web content is a live region containing a timer listing the time remaining or elapsed time. A timer's inner text should be an updating current time measurement. While the value does not necessarily need to be machine parsable, it should continuously update at regular intervals unless the timer is paused or reaches its end-point.

Along with `alert`, `log`, `marquee`, and `status` the `timer` role is a live region and can be modified by live region attributes.

### Associated WAI-ARIA roles, states, and properties

`aria-label` or `aria-labelledby`

Some screen readers announce the name of a timer element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a timer element with text that is not displayed when a screen reader reads the content. Naming a timer is not required so if nothing is appropriate both these attributes can be omitted.

`aria-live`

Elements with the role `timer` have an implicit aria-live value of `off`.

Accessibility concerns
----------------------

If a time limit needs to be in place, for example, for security reasons, the user should have the option to turn it off or extend it. This restriction does not apply if the time limit is due to a live event, such as an auction or a game, or if the time to complete the form is essential for a valid submission.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # timer |

See also
--------

* ARIA: `alert` role
* ARIA: `log` role
* ARIA: `marquee` role
* ARIA: `status` role
* ARIA live regions
* `timer` example on Codepen by Heydon Pickering
ARIA: mark role
===============

The `mark` role denotes content which is marked or highlighted for reference or notation purposes, due to the content's relevance in the enclosing context.

Description
-----------

The `mark` role semantically denotes HTML elements containing text that is marked/highlighted for reference purposes. This is semantically equivalent to the HTML `<mark>` element. If possible, you should use this element instead.

Example uses for `mark` are the exact same as the `<mark>` element. They include highlighting text in a quotation which is of special interest but is not marked in the original source material, comparable to using a highlighter pen to mark passages of a print article and indicating portions of the content that are relevant to the user's current activity, such as highlighting text matches found by a search feature.

Don't use `mark` for purely decorative styling such as syntax highlighting.

The `mark` element should not be given an accessible name; both `aria-label` and `aria-labelledby` attributes are prohibited on `mark`.

Examples
--------

In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`.


```html
<p>
  The last half of the song is a slow-rising crescendo that peaks at the
  <span role="mark" aria-details="thread-1">end of the guitar solo</span>,
  before fading away sharply.
</p>

<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2022-03-30T19:29">March 30 2022, 19:29</time></p>
</div>
```


The related comment is marked up using an HTML structure wrapped with a `<div>` containing `role="comment"`.

To associate the comment with the text being commented, we need to wrap the commented text with an element containing the `aria-details` attribute, the value of which should be the ID of the comment.

Best practices
--------------

### Prefer HTML

Using the `<mark>` element will automatically communicate a node has a role of `mark`. If at all possible, prefer using it instead.

Specifications
--------------

Will be part of WAI-ARIA 1.3, which is still being drafted.

See also
--------

* HTML `<mark>` element
* ARIA annotations
ARIA: comment role
==================

The `comment` role semantically denotes a comment/reaction to some content on the page, or to a previous comment.

**Note:** The comment role is proposed in WAI-ARIA 1.3 (Most recent ARIA draft), which is still being drafted.

Examples
--------

In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`.

The related comment is marked up using an HTML structure wrapped with a `<div>` containing `role="comment"`.


```html
<p>
  The last half of the song is a slow-rising crescendo that peaks at the
  <span role="mark" aria-details="thread-1">end of the guitar solo</span>,
  before fading away sharply.
</p>

<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p>
</div>
```


To associate the comment with the text being commented, we need to wrap the commented text with an element containing the `aria-details` attribute, the value of which should be the ID of the comment.

### Multiple comments

Since `aria-details` can now accept multiple IDs, we can associate multiple comments with the same annotation, like so:


```html
<p>
  The last half of the song is a slow-rising crescendo that peaks at the
  <mark aria-details="thread-1 thread-2">end of the guitar solo</mark>, before
  fading away sharply.
</p>

<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p>
</div>

<div role="comment" id="thread-2" data-author="chris">
  <h3>Marcus said</h3>
  <p class="comment-text">
    The guitar solo could do with a touch more chorus, and a slightly lower
    volume.
  </p>
  <p><time datetime="2019-03-29T15:35">March 29 2019, 15:35</time></p>
</div>
```

### Nested comments

Nested comments are also possible with ARIA annotations — nest the comments inside one another, like so:


```html
<div role="comment" id="thread-1" data-author="chris">
  <h3>Chris said</h3>
  <p class="comment-text">I really think this moment could use more cowbell.</p>
  <p><time datetime="2021-03-30T19:29">March 30 2021, 19:29</time></p>

  <div role="comment" data-author="marcus">
    <h3>Marcus replied</h3>
    <p class="comment-text">
      I don't know about that. I think the cowbell could distract from the solo.
    </p>
    <p><time datetime="2021-03-30T21:02">March 30 2021, 21:02</time></p>
  </div>
</div>
```

Accessibility concerns
----------------------

None

Specifications
--------------

Will be part of WAI-ARIA 1.3, which is still being drafted.

See also
--------

* ARIA annotations
ARIA: composite role
====================

The `composite` abstract role indicates a widget that may contain navigable descendants or owned children.

**Note:** The `composite` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors.

Description
-----------

`Composite` is an abstract role used for the ontology. Don't use this role in content. Instead, use the composite subclasses of `grid`, `select`, `spinbutton`, and `tablist`

Best Practices
--------------

Do not use.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # composite |

See Also
--------

* ARIA: `widget` role
* ARIA: `grid` role
* ARIA: `select` role
* ARIA: `spinbutton` role
* ARIA: `tablist` role
ARIA: note role
===============

A `note` role suggests a section whose content is parenthetic or ancillary to the main content.

Description
-----------

The `note` role can be added to parenthetic or ancillary content if no other native element or other role fits the purpose.

### Associated WAI-ARIA roles, states, and properties

`aria-label` or `aria-labelledby` (optional)

Naming a note is optional, but can help screen reader users understand its context and purpose. The name can be provided using `aria-labelledby` if a visible label is present, otherwise with `aria-label`.

Examples
--------


```html
<h1>Madam C. J. Walker</h1>
<p>
  Madam C.J. Walker was an African American entrepreneur, philanthropist, and
  political and social activist.
</p>
<h2>Early Life</h2>
…
<h2>Career</h2>
…
<p role="note" class="hilitebox">
  At the height of the depression, Madam C. J. Walker trained 20,000 women to
  sell hair pomade door-to-door
</p>
<h2>Activism and Philanthropy</h2>
…
```


In the above Wikipedia style entry for Madam C.J. Walker, the `hilitebox` with role `note` could have been a `<blockquote>` if it contained a quote or `<figcaption>` in a `<figure>` if there was an associated image. In this case, as neither of those made sense, the `note` role was added to add semantics to the parenthetic content.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # note |

See Also
--------

* Document structure roles
ARIA: structure role
====================

The `structure` role is for document structural elements.

**Note:** The `structure` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors.

Description
-----------

`Structure` is a superclass abstract role for document structures, like as `document`,
 `rowgroup`, and `sectionhead`, that support the accessibility of dynamic web content by helping assistive technologies determine active content versus static document content. Some subclass roles, like
 `section` role, are in turn superclasses of other roles.

The `structure` role is the superclass for all document structure roles, which are used to provide a structural description for a section of content. Most structure roles should no longer be used as browsers now support semantic HTML element with the same meaning. The structure roles without HTML equivalents, such as the `presentation` role which means content is presentational only, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available.

Best Practices
--------------

Do not use `role="structure"`. Do use HTML and subclass structure roles.

Specifications
--------------

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # structure |

See Also
--------

* ARIA: `roletype` role
* ARIA: `generic` role
* ARIA: `presentation` role
* ARIA: `range` role
* ARIA: `section` role
* ARIA: `sectionhead` role
ARIA: none role
===============

The `none` role is a synonym for the `presentation` role; they both remove an element's implicit ARIA semantics from being exposed to the accessibility tree.

See the `presentation` role for more information.