docs(button-group): document aria-current attribute usage

Addresses #1045

docs/product/components/button-groups.html

@@ -2,7 +2,7 @@
 layout: page
 title: Button groups
 figma: https://www.figma.com/file/9p5HuZwl9KXP9HpBZuvBoT/Button-Groups
-description: Button groups are a collection of buttons. This component is used in our questions view, and is frequently used in conjunction with other form elements such as search fields and sorting dropdowns. If the content you’re interacting with is a simple paring down or filter of the current view, it’s appropriate to use the <code class="stacks-code">.s-btn-group</code> component. Add the class <code class="stacks-code">.is-selected</code> to show the currently-selected button.
+description: Button groups are a collection of buttons. This component is used in our questions view, and is frequently used in conjunction with other form elements such as search fields and sorting dropdowns. If the content you’re interacting with is a simple paring down or filter of the current view, it’s appropriate to use the <code class="stacks-code">.s-btn-group</code> component. Add the class <code class="stacks-code">.is-selected</code> and the <code class="stacks-code">aria-current</code> attribute with the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current#values">appropriate value</a> to show the currently selected button.
 ---
 <section class="stacks-section">
     {% header "h2", "Classes" %}
@@ -28,6 +28,33 @@
     </div>
 </section>
 
+
+{% header "h2", "Accessibility" %}
+<p class="stacks-copy">
+    When used as navigation or a filter, button groups should include the <code class="stacks-code">aria-label</code> attribute with the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current#values"></a>appropriate value</a>.
+</p>
+
+<section class="stacks-section">
+    <div class="overflow-x-auto mb32" tabindex="0">
+        <table class="wmn4 s-table s-table__bx-simple">
+            <thead>
+                <tr>
+                    <th scope="col" class="s-table--cell3">Item</th>
+                    <th scope="col" class="s-table--cell3">Applied to</th>
+                    <th scope="col">Description</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><code class="stacks-code">aria-current="[value]"</code></td>
+                    <td><code class="stacks-code">.s-btn.is-selected</code></td>
+                    <td>When using a button group for navigation or filtering, include the <code class="stacks-code">aria-current</code> attribute with the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current#values">appropriate value</a> to the selected button. Most commonly used values are <code class="stacks-code">page</code>, <code class="stacks-code">step</code>, and <code class="stacks-code">true</code>.</td>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+</section>
+
 <section class="stacks-section">
     {% header "h2", "Example" %}
     <div class="stacks-preview">
@@ -36,7 +63,7 @@
     <button class="s-btn s-btn__muted s-btn__outlined" role="button">Newest</button>
     <button class="s-btn s-btn__muted s-btn__outlined" role="button">Frequent</button>
     <form class="s-btn-group--container">
-        <button class="s-btn s-btn__muted s-btn__outlined is-selected" role="button">Votes</button>
+        <button class="s-btn s-btn__muted s-btn__outlined is-selected" role="button" aria-current="true">Votes</button>
     </form>
     <button class="s-btn s-btn__muted s-btn__outlined" role="button">Active</button>
     <form class="s-btn-group--container">
@@ -49,7 +76,7 @@
                 <button class="s-btn s-btn__muted s-btn__outlined js-btn-group-item" role="button">Newest</button>
                 <button class="s-btn s-btn__muted s-btn__outlined js-btn-group-item" role="button">Frequent</button>
                 <form class="s-btn-group--container">
-                    <button class="s-btn s-btn__muted s-btn__outlined is-selected js-btn-group-item" role="button">Votes</button>
+                    <button class="s-btn s-btn__muted s-btn__outlined is-selected js-btn-group-item" role="button" aria-current="true">Votes</button>
                 </form>
                 <button class="s-btn s-btn__muted s-btn__outlined js-btn-group-item" role="button">Active</button>
                 <form class="s-btn-group--container">
@@ -80,7 +107,7 @@
             <span class="s-btn--number">37</span>
         </span>
     </button>
-    <button class="s-btn s-btn__muted s-btn__outlined is-selected" role="button">
+    <button class="s-btn s-btn__muted s-btn__outlined is-selected" role="button" aria-current="true">
         All
         <span class="s-btn--badge">
             <span class="s-btn--number">234</span>