Updates a11y guidance for inactive ActionList (and related components…

…) items (#644) * updates guidelines for ActionList and related components to address latest a11y feedback * fixes empty href * fixes more empty links * Update content/components/action-list.mdx Co-authored-by: Alexis Lucio <[email protected]> * adds more context about why tooltips are required for inactive items --------- Co-authored-by: Alexis Lucio <[email protected]>
primer · Oct 20, 2023 · a4dff01 · a4dff01
1 parent dd9a704
commit a4dff01
Show file tree

Hide file tree

Showing 5 changed files with 92 additions and 14 deletions.
diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx
@@ -188,6 +188,37 @@ Action list items can be selected. Single selections are represented with a [`ch
         <Box as="p">For destructive or irremediable actions, show a confirmation dialog for extra friction. If the action is not destructive, present the user a way to undo the action instead of asking for confirmation. <a href="https://alistapart.com/article/neveruseawarning/">Never use a warning when you mean undo</a>.</Box>
         <Box as="p">Place danger items at the end of the list.</Box>
     </Box>
+
+<Box justifyContent="center">
+    <img
+        width="464"
+        alt="An action list with the first item in an inactive state"
+        src="https://github.com/primer/design/assets/2313998/05c6199a-a0b1-4a11-beda-73203f38cabf"
+    />
+    <img
+        width="464"
+        alt="An action list with the first item in an inactive state. A cursor is hovering the alert icon in the leading visual slot."
+        src="https://github.com/primer/design/assets/2313998/0d44f9fc-b219-43d7-8b81-a5baf93ada77"
+    />
+</Box>
+<Box sx={{h3: {marginTop: 0}}}>
+
+### Inactive items
+
+Inactive action list item text still needs to meet an accessible color contrast ratio.
+
+If there's a leading visual, replace it with an alert icon.
+
+If there's *not* a leading visual, use an alert icon as the leading visual.
+
+It's required to show a tooltip with context about why the item is inactive. It should be triggered by the leading visual.
+
+Optionally, you may open a dialog when the user clicks the leading visual to show more detailed information about why the item is inactive.
+
+See the [accessibility](#accessibility) section for information on the assistive technology user experience.
+
+</Box>
+
 </Box>
 
 ## Examples
@@ -252,6 +283,35 @@ A nav list organizes navigation links for the user's current context and indicat
 
 ## Accessibility
 
+### Tooltips and dialogs on inactive items
+
+<Box
+  mb={3}
+  display="flex"
+  alignItems="flex-start"
+  justifyContent="space-between"
+  flexDirection={['column', 'column', 'column', 'column', 'row']}
+  sx={{gap: 3}}
+>
+
+<div>
+
+If an action list item is inactive, it will no longer be an `<a>` or `<button>`, so it will not be focusable.
+
+Having a tooltip on the leading visual is the only way to distinguish between the inactive items, and for keyboard-only screen reader users, it's the only way to see these are inactive.
+
+The tooltip and optional dialog should be triggered by a button element that wraps the leading visual.
+
+</div>
+
+<img
+    width="464"
+    alt="An action list with the first item in an inactive state. There is an annotation with HTML markup showing an SVG element wrapped in a button element."
+    src="https://github.com/primer/design/assets/2313998/181c60b1-4dc3-484d-a9d1-eb4fb14e55c2"
+/>
+
+</Box>
+
 ### Known accessibility issues (GitHub staff only)
 
  <AccessibilityLink label="ActionList"/>
diff --git a/content/components/action-menu.mdx b/content/components/action-menu.mdx
@@ -424,6 +424,23 @@ Here is an overview of [action list](/components/action-menu) items that are com
 - **Section header**: To add clarification to a section.
 - **Divider**: To create sections for your selections, actions or submenus.
 
+#### Inactive items
+
+<img
+  width="960"
+  alt="Three examples: 1. An action menu that works just fine; 2. An action menu with some items disabled; 3. An action menu with all items disabled"
+  src="https://github.com/primer/design/assets/2313998/8f3f9bfb-2c0c-4036-a83f-faf17e45ffdb"
+/>
+
+If items in a menu have been affected by a system error such as an outage, they may be put into an inactive state with a message in each item explaining why it's disabled.
+
+If an action menu contains menu items that are very closely related (for example: the action menu for adding a file to a repo) and we can detect that none of the menu items are available, then put the button that triggers the action menu into an [inactive state](/components/button#inactive).
+
+Inactive action menu items follow the same patterns as inactive action list items except:
+- The message explaining why it's unavailable is renderd in the item, not a tooltip. Action menu items don't hide the message in a tooltip because the menu is already hidden until the user opens it.
+  - Hiding the message in a tooltip would require the user to do another interaction, and the UI could feel chaotic with so many layers.
+- No [alert icon](/foundations/icons/alert-16) leading visual is necessary since it would be redundant with the error message
+
 ## Accessibility
 
 See [focus management](/guides/accessibility/focus-management) for more information.

diff --git a/content/components/nav-list.mdx b/content/components/nav-list.mdx
@@ -26,13 +26,17 @@ A nav list organizes navigation links for the user's current context and indicat
 <img
   width="960"
   role="presentation"
-  src="https://user-images.githubusercontent.com/2313998/226925589-4fe71751-5026-4c16-99f2-10c7c83ac4d7.png"
+  src="https://github.com/primer/design/assets/2313998/a3d4180b-239e-40a8-8a11-d7cf40405159"
 />
 
 **Resting:** The default state. The link is not the one currently being shown.
 
 **Current:** Indicates that this link is the current view being shown.
 
+**Inactive:** Indicates that the link href is unavailable due to a system error. See [degraded experience guidelines](/ui-patterns/degraded-experiences#degraded-navigation) for more information.
+
+**Loading:** Indicates that the link href is still being calculated. See [loading guidelines](/ui-patterns/loading#navigation) for more information.
+
 **Expanded sub-items:** The item is expanded to show its sub-items.
 
 **Collapsed sub-items:** The item has sub-items, but they are hidden.
@@ -141,6 +145,8 @@ Nav lists should always be labeled for assistive technologies, even if the label
 
 Nav list items are links, so they should never contain buttons or other clickable elements.
 
+Inactive nav list items are not rendered as `<a>` tags since we don't know the href value. The only focusabe part of the item is the leading visual. See the [action list accessibility guidelines](/components/action-list#tooltips-and-dialogs-on-inactive-items) for more details.
+
 ### Known accessibility issues (GitHub staff only)
 
  <AccessibilityLink label="NavList"/>

diff --git a/content/ui-patterns/degraded-experiences.mdx b/content/ui-patterns/degraded-experiences.mdx
@@ -339,17 +339,12 @@ There are two recommended ways an inert button should respond to user input:
   src="https://github.com/primer/design/assets/2313998/f7837087-a6ff-4572-9ef6-d5dfad158b88"
 />
 
-### Handling action menus with non-functional items
+### Handling action lists and menus with non-functional items
 
-<img
-  width="960"
-  alt="Three examples: 1. An action menu that works just fine; 2. An action menu with some items disabled; 3. An action menu with all items disabled"
-  src="https://github.com/primer/design/assets/2313998/92ab5cea-74a8-43f0-834c-3ef07ac65bfe"
-/>
-
-Show the menu items, but disable them and show a message explaining why they're disabled.
+The action list and action menu components provide an inactive state for their items. See their documentation pages for more information:
 
-If an action menu contains menu items that are very closely related (for example: the action menu for adding a file to a repo) and we can detect that none of the menu items are available, then indicate a problem on the button that triggers the action menu. Use an icon in the button to indicate that something is wrong, and (optionally) show a tooltip on hover or focus.
+- [Inactive action list items](/components/action-list#inactive-items)
+- [Inactive action menu items](/components/action-menu#inactive-items)
 
 ### Handling degraded forms
 

diff --git a/content/ui-patterns/loading.mdx b/content/ui-patterns/loading.mdx
@@ -244,7 +244,7 @@ If sequential groups or navigation links are unable to load, replace both groups
 <img
   width="960"
   alt="3 images. 1. Repos, teams, and organizations loading; 2: Repos and teams both failed; 3: All groups succeeded"
-  src="https://github.com/primer/design/assets/2313998/14cbb97d-ebd2-44ca-b434-56454c9f6d47"
+  src="https://github.com/primer/design/assets/2313998/ee62d85f-b2a8-4766-b42b-3234699d865e"
 />
 
 <Note>
@@ -259,7 +259,7 @@ If non-sequential groups of navigation links are in a loading state, preserve th
 <img
   width="960"
   alt="3 images. 1. Some items in right side-sheet are loading; 2: Some items in right side-sheet failed; 3: All items in right side-sheet succeeded"
-  src="https://github.com/primer/design/assets/2313998/1b619fa0-0870-4356-a5a6-78519a36f539"
+  src="https://github.com/primer/design/assets/2313998/3ab14657-8ab3-45e4-b47a-ef9eee76da4b"
 />
 
 If some links in the right side sheet cannot be loaded, default to showing each [nav list](components/nav-list) item in an inert state. The users should still be able to hover, click, and focus inert items, but they don't link to anywhere. Optionally, a tooltip may be displayed explaining that the navigation item is unavailable. An error banner is not necessary for this case.
@@ -282,7 +282,7 @@ If we don't know specifically which links failed to load (for example, some user
 <img
   width="456"
   alt="Generic error banner with hidden items"
-  src="https://github.com/primer/design/assets/2313998/a6275e1c-72b8-49b0-a9cf-689ec763a000"
+  src="https://github.com/primer/design/assets/2313998/7fd2f27b-baed-4f98-9039-7061d9a5e205"
 />
 
 </Box>
@@ -307,7 +307,7 @@ It is ok to show sequential navigation items in a loading state to avoid a layou
 <img
   width="456"
   alt="3 images: 1. Loading unknown labels; 2. Loading known labels; 3. Success"
-  src="https://github.com/primer/design/assets/2313998/d82dec1a-0eb0-4577-a7d4-091dda395f5d"
+  src="https://github.com/primer/design/assets/2313998/e6011246-7ded-430b-9989-c40777583a28"
 />
 
 </Box>