From 4d35121000ff132d3896c52fb6558d3fbefdb654 Mon Sep 17 00:00:00 2001 From: Mike Perrotti Date: Fri, 20 Oct 2023 12:19:06 -0400 Subject: [PATCH 1/5] updates guidelines for ActionList and related components to address latest a11y feedback --- content/components/action-list.mdx | 50 ++++++++++++++++++++ content/components/action-menu.mdx | 17 +++++++ content/components/nav-list.mdx | 8 +++- content/ui-patterns/degraded-experiences.mdx | 13 ++--- content/ui-patterns/loading.mdx | 8 ++-- 5 files changed, 82 insertions(+), 14 deletions(-) diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx index 8b3b980dd..958483f31 100644 --- a/content/components/action-list.mdx +++ b/content/components/action-list.mdx @@ -188,6 +188,29 @@ Action list items can be selected. Single selections are represented with a [`ch 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. Never use a warning when you mean undo. Place danger items at the end of the list. + + + An action list with the first item in an inactive state + An action list with the first item in an inactive state. A cursor is hovering the alert icon in the leading visual slot. + + + Inactive items + Inactive action list item text still need to meet an accessible color contrast. + 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 section for information on the assistive technology user experience. + + ## Examples @@ -252,6 +275,33 @@ A nav list organizes navigation links for the user's current context and indicat ## Accessibility +### Tooltips and dialogs on inactive items + + + +
+ +If an action list item is inactive, it will no longer be an `` or `
+ +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. + + + ### Known accessibility issues (GitHub staff only) diff --git a/content/components/action-menu.mdx b/content/components/action-menu.mdx index 3fcb83e43..8e8c42084 100644 --- 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 + +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 + +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](). + +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 index efc8c542a..fa5c53703 100644 --- 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 **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 `` 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) diff --git a/content/ui-patterns/degraded-experiences.mdx b/content/ui-patterns/degraded-experiences.mdx index c98afcede..0896b0026 100644 --- 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 -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 - -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]() +- [Inactive action menu items]() ### Handling degraded forms diff --git a/content/ui-patterns/loading.mdx b/content/ui-patterns/loading.mdx index 1160d8e2d..fc42f5eb6 100644 --- 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 3 images. 1. Repos, teams, and organizations loading; 2: Repos and teams both failed; 3: All groups succeeded @@ -259,7 +259,7 @@ If non-sequential groups of navigation links are in a loading state, preserve th 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 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 Generic error banner with hidden items @@ -307,7 +307,7 @@ It is ok to show sequential navigation items in a loading state to avoid a layou 3 images: 1. Loading unknown labels; 2. Loading known labels; 3. Success From 7b517b72925d087783e9f9e0004224e4c97bc8ab Mon Sep 17 00:00:00 2001 From: Mike Perrotti Date: Fri, 20 Oct 2023 12:33:06 -0400 Subject: [PATCH 2/5] fixes empty href --- content/components/action-menu.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/action-menu.mdx b/content/components/action-menu.mdx index 8e8c42084..002846dc7 100644 --- a/content/components/action-menu.mdx +++ b/content/components/action-menu.mdx @@ -434,7 +434,7 @@ Here is an overview of [action list](/components/action-menu) items that are com 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](). +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. From fbe794c086617554fb13c0ad89a396bec4615ff4 Mon Sep 17 00:00:00 2001 From: Mike Perrotti Date: Fri, 20 Oct 2023 12:53:38 -0400 Subject: [PATCH 3/5] fixes more empty links --- content/components/action-list.mdx | 24 +++++++++++++------- content/ui-patterns/degraded-experiences.mdx | 4 ++-- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx index 958483f31..a2bad5368 100644 --- a/content/components/action-list.mdx +++ b/content/components/action-list.mdx @@ -201,14 +201,22 @@ Action list items can be selected. Single selections are represented with a [`ch src="https://github.com/primer/design/assets/2313998/0d44f9fc-b219-43d7-8b81-a5baf93ada77" /> - - Inactive items - Inactive action list item text still need to meet an accessible color contrast. - 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 section for information on the assistive technology user experience. + + +### Inactive items + +Inactive action list item text still need to meet an accessible color contrast. + +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. + diff --git a/content/ui-patterns/degraded-experiences.mdx b/content/ui-patterns/degraded-experiences.mdx index 0896b0026..d03320b3c 100644 --- a/content/ui-patterns/degraded-experiences.mdx +++ b/content/ui-patterns/degraded-experiences.mdx @@ -343,8 +343,8 @@ There are two recommended ways an inert button should respond to user input: The action list and action menu components provide an inactive state for their items. See their documentation pages for more information: -- [Inactive action list items]() -- [Inactive action menu items]() +- [Inactive action list items](/components/action-list#inactive-items) +- [Inactive action menu items](/components/action-menu#inactive-items) ### Handling degraded forms From f50c9391fb4c24e39d662150cbfa04ffaa7ba2b8 Mon Sep 17 00:00:00 2001 From: Mike Perrotti Date: Fri, 20 Oct 2023 15:07:02 -0400 Subject: [PATCH 4/5] Update content/components/action-list.mdx Co-authored-by: Alexis Lucio --- content/components/action-list.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx index a2bad5368..dd7ee07ec 100644 --- a/content/components/action-list.mdx +++ b/content/components/action-list.mdx @@ -205,7 +205,7 @@ Action list items can be selected. Single selections are represented with a [`ch ### Inactive items -Inactive action list item text still need to meet an accessible color contrast. +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. From 580637b782f65e9644f4e37ae75c979c71eabd07 Mon Sep 17 00:00:00 2001 From: Mike Perrotti Date: Fri, 20 Oct 2023 15:09:04 -0400 Subject: [PATCH 5/5] adds more context about why tooltips are required for inactive items --- content/components/action-list.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx index a2bad5368..f534f9682 100644 --- a/content/components/action-list.mdx +++ b/content/components/action-list.mdx @@ -298,6 +298,8 @@ A nav list organizes navigation links for the user's current context and indicat If an action list item is inactive, it will no longer be an `` or `