diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx index 8b3b980dd..9bb87294e 100644 --- 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 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 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. + + + ## 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 + + + +
+ +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..002846dc7 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](/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 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..d03320b3c 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](/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 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