degraded-experiences

33 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Graceful degradation definition and blast analogy

Graceful degradation is about reducing the effect of a blast (availability incident), not preventing the blast or reducing the blast radius. The blast still happens and affects all experiences it did before, but with a reduced effect. It involves communicating clearly that a problem exists and guiding users around that problem as much as possible.

Primary experiences definition

Primary experiences are experiences that are essential for the page to be useful to the user. In case of availability incidents, if any primary experiences cannot be provided to users, then it makes sense to show an error page instead. For example, on the issue page, the issue title and description are primary experiences.

Secondary experiences definition

Secondary experiences are experiences that are not essential for the page to be useful to the user. They enrich the page to make it more useful to some users for certain workflows. In case of availability incidents, if any secondary experiences cannot be provided to users, it makes sense to show the page without them as the page is still likely useful to most users. For example, on the issue page, the unread notifications indicator and counters for projects, issues, and PRs in the repository navigation bar are secondary experiences.

Render page without hiding errors versus showing error page

If there is an outage that does not affect the primary experiences of the page, render a degraded page to reduce disruptions. Do not attempt to render a page that will not be useful to the user. Only show a full error page when primary experiences cannot be provided.

Global system notification banner placement and variant

If there is a critical system error that will degrade user experience, show a banner at the top of the page above the global navigation. Default to using the 'warning' variant of the banner. The banner should explain what is wrong and, if possible, link to a page with more detailed information such as the GitHub status page.

Replacing UI with error message for unavailable content

Do not show a generic empty state when a user created content that is now temporarily unavailable, as it may cause users to think they suffered data loss. Instead, explain that the content is unavailable or remove the entire section from the page including the section heading. For example, on an organization page, if repositories cannot be loaded, show an unavailable message rather than an empty state that might suggest the repositories were deleted.

Limit degraded experiences to 5 or fewer outage messages

As a general guideline, limit pages to 5 or fewer outage messages. A page with too many error messages could communicate an unnecessarily reactionary and negative tone.

Inline content replacement with warning icon and message

Smaller parts of the UI that cannot be accurately rendered but are too important to exclude entirely can be replaced with a short error message. Show a warning icon before the message to help differentiate it from non-degraded content. The message may be colored with 'fg.warning' to draw attention to it, but be mindful that too many warning-colored messages could make the page feel broken instead of degraded.

Blankslate for large unavailable content areas

If the affected area is large enough, replace the affected UI with a blankslate component that explains why the expected UI is not there.

Blankslate leading visual for degraded content

For a blankslate used to notify users of unavailable data, use the alert icon as the leading visual. Default to using 'fgColor-muted' as the fill color. Using 'fgColor-attention' could be too harsh and over-emphasize the error.

Blankslate primary and secondary text for degraded content

For a blankslate used to notify users of unavailable data, the primary text may optionally be used for a title that succinctly describes the error. The secondary text should describe what is wrong and how (or if) the user can do anything to get around the issue.

Blankslate secondary action for degraded content

For a blankslate used to notify users of unavailable data, use the secondary action for any action or link to places with more information. Primary actions are not recommended for degraded content blankslates; theoretically a primary action may be appropriate only if it initiates an action that will resolve the problem.

Handling non-critical dialogs when content is unavailable

If the content of a non-critical dialog cannot be rendered, prevent the dialog from being opened. For non-critical dialogs that appear on hover, remove the hover interaction. For non-critical dialogs that appear on click, remove the button that triggers the dialog. For example, if a user's profile data is unavailable, do not show a hovercard when their avatar is hovered.

Handling critical dialogs when content is unavailable

If a dialog is a core part of a workflow and its content cannot be rendered, replace the content of the dialog with a message explaining why the expected UI is not there. If using a dialog component that supports error states, follow the component's guidelines for rendering error messages. If not using a component that supports error states, replace the content with a blankslate component explaining why the expected UI is not there.

Be cautious removing UI without explanation

Be mindful when choosing to remove affected UI without explanation, as this could cause confusion for users about whether that part of the UI is hidden due to an error or if it has been permanently removed. However, it is acceptable to remove UI that is not critical to core workflows and render the rest of the page without that UI, such as unavailable activity indicators.

UI critical to workflows should not be removed

Do not remove UI that is critical to core workflows when it is unavailable, including: the comment box on issues and pull requests, the 'Request changes' button in the pull request 'Changes' tab, and submit buttons on forms.

Handling unavailable counts

When the data required to calculate a count is unavailable, default to hiding the number. If the count is shown inside of an interactive element, a tooltip may be displayed on focus and hover to explain the missing count.

Handling unavailable activity indicators

When the data is unavailable to determine whether to show an activity indicator (most commonly used for notification badges), default to hiding the indicator.

Handling unavailable dynamic navigation links

When a dynamic link in the navigation is not yet available, fall back to not rendering it. If the page is in a state where it is not sure if a link is available, put the navigation item in a loading state.

Never suppress global navigation header

Never suppress rendering of the global navigation header. Rendering a page without a global navigation header could make a user feel stuck. Instead, suppress rendering of individual navigation items affected by a system error. Most links in the global navigation header are static and will not need to be degraded.

Handling side sheet lazy-loaded navigation content

Left and right global navigation side sheets lazy-load some of their content when the nav is first opened, such as repos and teams. If the user can see a loading state before a failure, inform them that there was a failure. If the user does not see a loading state before a failure, skip rendering the affected links. Provide specific details in the error message about which groups could not be loaded, or show a generic error message if details are unknown.

Degraded side sheet group actions

If the data to render the 'Show more' link or button at the bottom of a nav list group is unavailable, do not render it. If the data to render the search button in a nav list group is unavailable, do not render it.

Handling unavailable page navigation links

If the data required to render a page navigation link is unavailable, do not render the navigation link. If data required to render notification badges or counts is not available, do not render the badge.

Decision tree for non-functional buttons

For non-functional buttons, ask: Could removing the button be disorienting? If no, do not render the button. If yes: Does it respond to a hover or click? If yes, use an inactive button. If no, use a disabled button.

Default approach for non-functional buttons

Default to removing non-functional buttons from the UI. Do not remove buttons that are critical to a user's workflow—it may be disorienting.

Inactive button for critical non-functional buttons

If a button is too critical to be omitted and responds to user input by showing more information about why it is non-functional, use an inactive button.

Action list and menu items with non-functional states

The action list and action menu components provide an inactive state for their items. Refer to the inactive action list items and inactive action menu items documentation for more information on handling non-functional items.

CLI error messaging

It is confusing and frustrating when a command silently fails. If a command fails, immediately return an error message or wait for a timeout to expire and then return an error message.

Accessibility: never disable interactive controls for availability issues

Never disable an interactive control that is non-functional due to availability issues.

Accessibility: tooltip usage restrictions

Tooltips with error information should not be used on non-focusable elements. Tooltips may only be used on focusable elements.

Don't attempt to render UI with missing critical information

Do not attempt to render UI that is missing critical information, such as a table with 'undefined of undefined' text. Instead, replace the affected content with an appropriate error message or component.

Avoid making pages feel overly negative with too many warnings

Be mindful that rendering too many error messages in warning color on a page could be jarring and make the page feel broken instead of degraded.

Communicate problems clearly rather than concealing them

Do not try to conceal or downplay that something is wrong. Communicate that there is a problem and guide users around that problem as much as possible.

Give your agent this brain