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 5422340
Showing 1 changed file with 32 additions and 0 deletions.
32 changes: 32 additions & 0 deletions src/accessibility.html
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,38 @@ <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 the minimal markup for the circumference formula,
with each non-trivial component described.
</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 use it together with an <code class="attribute">intent</code> annotation,
as appropriate.
</p>
</section>
</section>
</section>
</section>
Expand Down

0 comments on commit 5422340

Please sign in to comment.