role=note fleshed out a little. (#1639)

Language a little less terse. Explicit mention of aria-details to associate a note with another element. Co-authored-by: Brennan Young <brennan.young@laerdal.com> Co-authored-by: Scott O'Hara <scottaohara@users.noreply.github.com> Co-authored-by: James Nurthen <jnurthen@users.noreply.github.com> Co-authored-by: James Craig <cookiecrook@users.noreply.github.com> Co-authored-by: Adam Page <adamfpage@gmail.com>
w3c · Mar 3, 2023 · abbef89 · abbef89
1 parent af84654
commit abbef89
Showing 1 changed file with 26 additions and 1 deletion.
diff --git a/index.html b/index.html
@@ -5925,7 +5925,32 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4>
 		<div class="role" id="note">
 			<rdef>note</rdef>
 			<div class="role-description">
-				<p>A section whose content is parenthetic or ancillary to the main content of the resource.</p>
+				<p>A <rref>section</rref> whose content represents additional information or parenthetical context to the primary content it supplements.</p>
+				<p>A <code>note</code> is content provided by the author of the page or document, it is not to be used for providing reactions or suggestions. For these purposes, please review <rref>comment</rref> and <rref>suggestion</rref>.</p>
+				<p>When used within the normal flow of a page's content, a <code>note</code> has an implicit association with the content that it supplements. The following example demonstrates using a <code>note</code> to call out additional information in the natural reading order of a page:</p>
+				<pre class="example highlight">
+					&lt;p>... the following results outline support for the tested features.&lt;/p>
+					&lt;div role="note">
+					  &lt;p>Please keep in mind that at the time of publishing this page all results were accurate.&lt;/p>
+					  &lt;p>If you find any variations in results, please let us know!&lt;/p>
+					&lt;/div>
+					&lt;p>...&lt;/p>
+				</pre>		
+				<p>In cases where an element with role <rref>note</rref> has been determined to need a programmatic association with the content it supplements, authors can use one of the following mechanisms to associate the elements:</p>
+				<ul>
+					<li>If the <code>note</code> contains structured or interactive content (for example, a link, button, list, table, etc.) use <pref>aria-details</pref>.</li>
+					<li>If the <code>note</code> is brief and consists of static text, use <pref>aria-describedby</pref>.</li>
+				</ul>
+				<pre class="example highlight">
+				  &lt;!-- using aria-details to reference a note containing a link -->
+				  ...
+					&lt;button aria-details="info-note">Get Started&lt;/button>
+					...
+					&lt;div role="note" id="info-note">
+					  &lt;p>Need more information before you get started?&lt;/p> 
+					  &lt;p>Visit our &lt;a href="...">product description page&lt;/a> to get all the information you need.&lt;/p>
+					&lt;/div>
+				</pre>
 			</div>
 			<table class="role-features">
 				<caption>Characteristics:</caption>