Skip to content

Commit

Permalink
add guidance for using aria-description
Browse files Browse the repository at this point in the history
  • Loading branch information
dginev committed Nov 20, 2024
1 parent 5395b72 commit 3e61b73
Showing 1 changed file with 31 additions and 0 deletions.
31 changes: 31 additions & 0 deletions src/accessibility.html
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,37 @@ <h5 id="acc_natural_lang">Natural-language Mathematics</h5>

</section>

<section>
<h5 id="acc_descriptions">Accessible Descriptions</h5>

<p>It is sometimes beneficial to a reader to have additional, auxiliary information for a given
mathematical construct. This is particularly the case in educational materials where
newly introduced syntax benefits from repeated reinforcement. Such information is often
too verbose for more familiar readers, indeed even to the same person after their first reading.
Hence, common AT behavior has been to only vocalize an
<a href="https://www.w3.org/TR/accname-1.2/#dfn-accessible-description">accessible description</a>,
on user request, omitting it by default.</p>
<p>It is appropriate to provide such descriptions using the ARIA 1.3 attribute
<a href="https://www.w3.org/TR/wai-aria-1.3/#aria-description"><code class="attribute">aria-description</code></a>,
which allows for a literal string value to annotate its host element.
As an example, consider an equation which describes the types of all variables.
</p>

<div class="example mathml mmlcore">
<pre>
&lt;mrow aria-description="circumference of a circle"&gt;
&lt;mn&gt;2&lt;/mn&gt;
&lt;mi aria-description="mathematical constant"&gt;π&lt;/mi&gt;
&lt;mi aria-description="radius variable"&gt;r&lt;/mi&gt;
&lt;/mrow&gt;
</pre>
</div>

<p>While <code class="attribute">aria-description</code> has been used on its own for brevity,
it is recommended to treat it as a secondary add-on which follows
a primary <code class="attribute">intent</code> annotation, as appropriate.
</p>
</section>
</section>
</section>
</section>
Expand Down

0 comments on commit 3e61b73

Please sign in to comment.