From ba3306b497c272f9224e8dabfa862750ae0f9cdd Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Wed, 16 Mar 2022 17:44:40 -0400
Subject: [PATCH] improve accessibility in various examples

---
 docs/components/badge.md              |  4 +--
 docs/components/button-group.md       | 22 +++++++-------
 docs/components/button.md             | 14 +++++++--
 docs/components/card.md               |  2 +-
 docs/components/divider.md            | 12 ++------
 docs/components/icon.md               |  2 +-
 docs/components/progress-bar.md       |  8 ++---
 docs/components/progress-ring.md      |  8 ++---
 docs/components/qr-code.md            |  2 +-
 docs/components/radio-button.md       | 42 +++++++++++++++++++++++++--
 docs/components/responsive-media.md   |  2 ++
 docs/components/switch.md             |  2 +-
 docs/components/tooltip.md            |  2 +-
 docs/getting-started/form-controls.md |  2 +-
 14 files changed, 81 insertions(+), 43 deletions(-)

diff --git a/docs/components/badge.md b/docs/components/badge.md
index 93123f6c7..ffbfb4c3f 100644
--- a/docs/components/badge.md
+++ b/docs/components/badge.md
@@ -185,9 +185,7 @@ const App = () => (
 When including badges in menu items, use the `suffix` slot to make sure they're aligned correctly.
 
 ```html preview
-<sl-menu
-  style="max-width: 240px; border: solid 1px var(--sl-panel-border-color); border-radius: var(--sl-border-radius-medium);"
->
+<sl-menu style="max-width: 240px;">
   <sl-menu-label>Messages</sl-menu-label>
   <sl-menu-item>Comments <sl-badge slot="suffix" variant="neutral" pill>4</sl-badge></sl-menu-item>
   <sl-menu-item>Replies <sl-badge slot="suffix" variant="neutral" pill>12</sl-badge></sl-menu-item>
diff --git a/docs/components/button-group.md b/docs/components/button-group.md
index 6b415f88b..17e63b267 100644
--- a/docs/components/button-group.md
+++ b/docs/components/button-group.md
@@ -300,13 +300,15 @@ const App = () => (
 
 ### Split Buttons
 
-Create a split button using a button and a dropdown.
+Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
 
 ```html preview
 <sl-button-group>
   <sl-button variant="primary">Save</sl-button>
   <sl-dropdown placement="bottom-end">
-    <sl-button slot="trigger" variant="primary" caret></sl-button>
+    <sl-button slot="trigger" variant="primary" caret>
+      <sl-visually-hidden>More options</sl-visually-hidden>
+    </sl-button>
     <sl-menu>
       <sl-menu-item>Save</sl-menu-item>
       <sl-menu-item>Save as&hellip;</sl-menu-item>
@@ -384,34 +386,34 @@ Create interactive toolbars with button groups.
 <div class="button-group-toolbar">
   <sl-button-group label="History">
     <sl-tooltip content="Undo">
-      <sl-button><sl-icon name="arrow-counterclockwise"></sl-icon></sl-button>
+      <sl-button><sl-icon name="arrow-counterclockwise" label="Undo"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Redo">
-      <sl-button><sl-icon name="arrow-clockwise"></sl-icon></sl-button>
+      <sl-button><sl-icon name="arrow-clockwise" label="Redo"></sl-icon></sl-button>
     </sl-tooltip>
   </sl-button-group>
 
   <sl-button-group label="Formatting">
     <sl-tooltip content="Bold">
-      <sl-button><sl-icon name="type-bold"></sl-icon></sl-button>
+      <sl-button><sl-icon name="type-bold" label="Bold"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Italic">
-      <sl-button><sl-icon name="type-italic"></sl-icon></sl-button>
+      <sl-button><sl-icon name="type-italic" label="Italic"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Underline">
-      <sl-button><sl-icon name="type-underline"></sl-icon></sl-button>
+      <sl-button><sl-icon name="type-underline" label="Underline"></sl-icon></sl-button>
     </sl-tooltip>
   </sl-button-group>
 
   <sl-button-group label="Alignment">
     <sl-tooltip content="Align Left">
-      <sl-button><sl-icon name="justify-left"></sl-icon></sl-button>
+      <sl-button><sl-icon name="justify-left" label="Align Left"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Align Center">
-      <sl-button><sl-icon name="justify"></sl-icon></sl-button>
+      <sl-button><sl-icon name="justify" label="Align Center"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Align Right">
-      <sl-button><sl-icon name="justify-right"></sl-icon></sl-button>
+      <sl-button><sl-icon name="justify-right" label="Align Right"></sl-icon></sl-button>
     </sl-tooltip>
   </sl-button-group>
 </div>
diff --git a/docs/components/button.md b/docs/components/button.md
index 48d60b79d..8e9c576ed 100644
--- a/docs/components/button.md
+++ b/docs/components/button.md
@@ -139,9 +139,17 @@ const App = () => (
 Use the `circle` attribute to create circular icon buttons.
 
 ```html preview
-<sl-button variant="default" size="small" circle><sl-icon name="gear"></sl-icon></sl-button>
-<sl-button variant="default" size="medium" circle><sl-icon name="gear"></sl-icon></sl-button>
-<sl-button variant="default" size="large" circle><sl-icon name="gear"></sl-icon></sl-button>
+<sl-button variant="default" size="small" circle>
+  <sl-icon name="gear" label="Settings"></sl-icon>
+</sl-button>
+
+<sl-button variant="default" size="medium" circle>
+  <sl-icon name="gear" label="Settings"></sl-icon>
+</sl-button>
+
+<sl-button variant="default" size="large" circle>
+  <sl-icon name="gear" label="Settings"></sl-icon>
+</sl-button>
 ```
 
 ```jsx react
diff --git a/docs/components/card.md b/docs/components/card.md
index 4ecac5433..e3e731216 100644
--- a/docs/components/card.md
+++ b/docs/components/card.md
@@ -131,7 +131,7 @@ Headers can be used to display titles and more.
   <div slot="header">
     Header Title
 
-    <sl-icon-button name="gear"></sl-icon-button>
+    <sl-icon-button name="gear" label="Settings"></sl-icon-button>
   </div>
 
   This card has a header. You can put all sorts of things in it!
diff --git a/docs/components/divider.md b/docs/components/divider.md
index 94ad5bec6..38803224b 100644
--- a/docs/components/divider.md
+++ b/docs/components/divider.md
@@ -107,9 +107,7 @@ const App = () => (
 Use dividers in [menus](/components/menu) to visually group menu items.
 
 ```html preview
-<sl-menu
-  style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);"
->
+<sl-menu style="max-width: 200px;">
   <sl-menu-item value="1">Option 1</sl-menu-item>
   <sl-menu-item value="2">Option 2</sl-menu-item>
   <sl-menu-item value="3">Option 3</sl-menu-item>
@@ -124,13 +122,7 @@ Use dividers in [menus](/components/menu) to visually group menu items.
 import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuItem value="1">Option 1</SlMenuItem>
     <SlMenuItem value="2">Option 2</SlMenuItem>
     <SlMenuItem value="3">Option 3</SlMenuItem>
diff --git a/docs/components/icon.md b/docs/components/icon.md
index 91d482a75..b655ea047 100644
--- a/docs/components/icon.md
+++ b/docs/components/icon.md
@@ -24,7 +24,7 @@ Click or tap on an icon below to copy its name and use it like this.
     </sl-select>
   </div>
   <div class="icon-list"></div>
-  <input type="text" class="icon-copy-input">
+  <input type="text" class="icon-copy-input" aria-hidden="true" tabindex="-1">
 </div>
 
 ## Examples
diff --git a/docs/components/progress-bar.md b/docs/components/progress-bar.md
index 39c4aad3a..7d94339dc 100644
--- a/docs/components/progress-bar.md
+++ b/docs/components/progress-bar.md
@@ -53,8 +53,8 @@ Use the default slot to show a value.
 
 <br />
 
-<sl-button circle><sl-icon name="dash"></sl-icon></sl-button>
-<sl-button circle><sl-icon name="plus"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
 
 <script>
   const progressBar = document.querySelector('.progress-bar-values');
@@ -96,11 +96,11 @@ const App = () => {
       <br />
 
       <SlButton circle onClick={() => adjustValue(-10)}>
-        <SlIcon name="dash" />
+        <SlIcon name="dash" label="Decrease" />
       </SlButton>
 
       <SlButton circle onClick={() => adjustValue(10)}>
-        <SlIcon name="plus" />
+        <SlIcon name="plus" label="Increase" />
       </SlButton>
     </>
   );
diff --git a/docs/components/progress-ring.md b/docs/components/progress-ring.md
index 3bfbd5f35..e14fd8981 100644
--- a/docs/components/progress-ring.md
+++ b/docs/components/progress-ring.md
@@ -95,8 +95,8 @@ Use the default slot to show a label inside the progress ring.
 
 <br />
 
-<sl-button circle><sl-icon name="dash"></sl-icon></sl-button>
-<sl-button circle><sl-icon name="plus"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
 
 <script>
   const progressRing = document.querySelector('.progress-ring-values');
@@ -140,11 +140,11 @@ const App = () => {
       <br />
 
       <SlButton circle onClick={() => adjustValue(-10)}>
-        <SlIcon name="dash" />
+        <SlIcon name="dash" label="Decrease" />
       </SlButton>
 
       <SlButton circle onClick={() => adjustValue(10)}>
-        <SlIcon name="plus" />
+        <SlIcon name="plus" label="Increase" />
       </SlButton>
     </>
   );
diff --git a/docs/components/qr-code.md b/docs/components/qr-code.md
index 587e11a51..968c4d151 100644
--- a/docs/components/qr-code.md
+++ b/docs/components/qr-code.md
@@ -11,7 +11,7 @@ QR codes are useful for providing small pieces of information to users who can q
   <sl-qr-code value="https://shoelace.style/" label="Scan this code to visit Shoelace on the web!"></sl-qr-code>
   <br />
 
-  <sl-input maxlength="255" clearable></sl-input>
+  <sl-input maxlength="255" clearable label="Value"></sl-input>
 </div>
 
 <script>
diff --git a/docs/components/radio-button.md b/docs/components/radio-button.md
index 4c8f43847..a21d138f5 100644
--- a/docs/components/radio-button.md
+++ b/docs/components/radio-button.md
@@ -364,18 +364,54 @@ You can omit button labels and use icons instead. Make sure to set a `label` att
 
 ```html preview
 <sl-radio-group label="Select an option">
-  <sl-radio-button name="a" value="1" checked>
+  <sl-radio-button name="a" value="angry">
+    <sl-icon name="emoji-angry" label="Angry"></sl-icon>
+  </sl-radio-button>
+
+  <sl-radio-button name="a" value="sad">
     <sl-icon name="emoji-frown" label="Sad"></sl-icon>
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="2">
+  <sl-radio-button name="a" value="neutral" checked>
     <sl-icon name="emoji-neutral" label="Neutral"></sl-icon>
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="3">
+  <sl-radio-button name="a" value="happy">
     <sl-icon name="emoji-smile" label="Happy"></sl-icon>
   </sl-radio-button>
+
+  <sl-radio-button name="a" value="laughing">
+    <sl-icon name="emoji-laughing" label="Laughing"></sl-icon>
+  </sl-radio-button>
 </sl-radio-group>
 ```
 
+```jsx react
+import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option">
+    <SlRadioButton name="a" value="angry">
+      <SlIcon name="emoji-angry" label="Angry" />
+    </SlRadioButton>
+
+    <SlRadioButton name="a" value="sad">
+      <SlIcon name="emoji-frown" label="Sad" />
+    </SlRadioButton>
+
+    <SlRadioButton name="a" value="neutral" checked>
+      <SlIcon name="emoji-neutral" label="Neutral" />
+    </SlRadioButton>
+
+    <SlRadioButton name="a" value="happy">
+      <SlIcon name="emoji-smile" label="Happy" />
+    </SlRadioButton>
+
+    <SlRadioButton name="a" value="laughing">
+      <SlIcon name="emoji-laughing" label="Laughing" />
+    </SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
 [component-metadata:sl-radio-button]
diff --git a/docs/components/responsive-media.md b/docs/components/responsive-media.md
index a9b8f27ec..bdb96bad7 100644
--- a/docs/components/responsive-media.md
+++ b/docs/components/responsive-media.md
@@ -63,6 +63,7 @@ The following video is embedded using an `iframe` and maintains a `16:9` aspect
 ```html preview
 <sl-responsive-media aspect-ratio="16:9">
   <iframe
+    title="Video of the kittens"
     src="https://player.vimeo.com/video/1053647?title=0&byline=0&portrait=0"
     frameborder="0"
     allow="autoplay; fullscreen"
@@ -77,6 +78,7 @@ import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
 const App = () => (
   <SlResponsiveMedia aspect-ratio="16:9">
     <iframe
+      title="Video of the kittens"
       src="https://player.vimeo.com/video/1053647?title=0&byline=0&portrait=0"
       frameborder="0"
       allow="autoplay; fullscreen"
diff --git a/docs/components/switch.md b/docs/components/switch.md
index 4ce52264b..77074b544 100644
--- a/docs/components/switch.md
+++ b/docs/components/switch.md
@@ -51,7 +51,7 @@ const App = () => <SlSwitch disabled>Disabled</SlSwitch>;
 Use the available custom properties to make the switch a different size.
 
 ```html preview
-<sl-switch style="--width: 80px; --height: 32px; --thumb-size: 26px;"></sl-switch>
+<sl-switch style="--width: 80px; --height: 32px; --thumb-size: 26px;">Really big</sl-switch>
 ```
 
 ```jsx react
diff --git a/docs/components/tooltip.md b/docs/components/tooltip.md
index 848575256..29792d704 100644
--- a/docs/components/tooltip.md
+++ b/docs/components/tooltip.md
@@ -250,7 +250,7 @@ Tooltips can be controller programmatically by setting the `trigger` attribute t
 <sl-button style="margin-right: 4rem;">Toggle Manually</sl-button>
 
 <sl-tooltip content="This is an avatar" trigger="manual" class="manual-tooltip">
-  <sl-avatar></sl-avatar>
+  <sl-avatar label="User"></sl-avatar>
 </sl-tooltip>
 
 <script>
diff --git a/docs/getting-started/form-controls.md b/docs/getting-started/form-controls.md
index d85bdf3ba..472be6962 100644
--- a/docs/getting-started/form-controls.md
+++ b/docs/getting-started/form-controls.md
@@ -262,7 +262,7 @@ const App = () => {
 The `invalid` attribute reflects the form control's validity, so you can style invalid fields using the `[invalid]` selector. The example below demonstrates how you can give erroneous fields a different appearance. Type something other than "shoelace" to demonstrate this.
 
 ```html preview
-<sl-input class="custom-input" required pattern="shoelace">
+<sl-input class="custom-input" label="Type Something" required pattern="shoelace">
   <small slot="help-text">Please enter "shoelace" to continue</small>
 </sl-input>