Progressive steps
A hierarchical display of information to inform users of the tasks being performed.
Did this page help you?
Your feedback helps us improve our documentation.
Building blocks
A. Header - optional
When displaying a list of steps, the header should succinctly describe the main task or workflow. In a chat interface, a header may not be necessary as the context is established through the conversation.
B. Main steps
Display status related to individual tasks or actions being performed as steps using the steps component.
C. Sub-steps - optional
If the main step has sub-steps, display them in a tree view leveraging the status indicators component.
D. Status hub - optional
If there is more than one status within sub-steps, display a status hub to the right of the step. The status hub uses the status indicator component.
E. Step details - optional
Step details can be indicated via popover or description text. Use a popover to provide supplemental information about the step. Use description text to display details that are necessary for the user’s context. For example, estimated completion time for a step, or additional details about a step status.
F. Input request - optional
When gathering additional information from users to generate an output, display the input requests in a dialog with form fields. To avoid blocking the user, include the ability for them to skip the input if desired. However, if the input is required, exclude the skip button, and add form field error text if a user attempts to bypass the form.
Key UX concepts
Progressive steps
A step is a unit of work the assistant performs to answer a request, such as querying a data source or provisioning a resource. Status is the state of a step while the request is being answered: not-started, in progress, success, error, or stopped. Showing both tells users what the assistant is doing while it works, and what it did once it stops.
Step types
Sequential steps advance in a fixed order, where each step consumes the output of the step before it, shown with steps. For example, an investigation that reads a request, then scans stack templates, then queries deployment history using what the scan found.
Non-sequential steps run at the same time, where no step waits on another, shown with a list. For example, querying the same metric across four regions at once.
A step can contain sub-steps, and the same dependency question applies inside the group. For substeps, see tree view
Provide transparency
Provide clear and informative status indicator updates throughout the process to maintain user transparency and trust. This helps users understand what the system is doing and builds confidence in the generative AI capabilities.
Enhance trust and confidence
Clear and contextual error or warning messages help users understand any issues that arise during the process, and enable them to take follow-up actions. This transparency helps build trust in the generative AI system's capabilities.
Balance transparency and cognitive load
Status updates and loading indicators should be kept concise and unobtrusive. Provide users the ability to view more details about steps within the process through the use of popovers, links, or expandable sections. This allows users to control the level of information they receive.
Enhance trust and confidence
Clear and contextual status and warning messages help users understand any issues that arise during the process, and enable them to take follow-up actions. Status updates and loading indicators should be kept concise and unobtrusive, with more details about each step available through popovers, links, or expandable sections. This allows users to control the level of information they receive, and helps build trust in the generative AI system's capabilities. When a step requires information from the user before it can continue, collect it within the conversation by following the guidelines for in-flow user input.
States
Latency periods
Generative AI can vary in response times. The progressive steps experience should adjust the loading states and indicators based on the expected latency, providing different visual cues for loading experiences above and below 10 seconds.
Under 10 seconds
Default: Display a loading status on the last step. Avoid displaying a loading state for under one second as this can seem jarring to users and can cause flickering in the UI.
Sub-steps: Display sub-steps with corresponding status to inform users of the overall progress when applicable. For example, display a list of nodes being checked when troubleshooting an EKS issue.
- Evaluated
Above 10 seconds
Indeterminate loading state: Display the current step in a loading state along with an estimated wait time. This helps communicate the anticipated timeline and set appropriate user expectations.
- This step may take up to 15 seconds to complete.
Determinate loading state: If a wait time is determinate, display a progress bar with the time remaining as suggested in feedback mechanisms. This helps keep users informed about the processes unfolding over a longer period of time and builds trust.
- Less than 20 seconds remaining
Error
A. Step error
When a step has an error, provide clear and concise error details along with the failed status. Offer a retry option whenever it's appropriate for the user to attempt the action again.
B. Sub-step error
If there is more than 1 error status within sub-steps, such as an error and warning, display the status hub to the right of the main step.
C. Error details
When an error or warning message has lots of details corresponding to it, provide them in a popover. This will help prevent overwhelming users with information displayed at once.
Output
When presenting the final output to the user, include an expandable section detailing the steps taken to generate the output. This should be collapsed by default.
The latency regression comes from the connection pool change in v3.8.2. Raise the maximum connections back to 50 to recover it.
General guidelines
Do
- Enable access to details
Enable users to view more details about each step of the process through popovers, links, sub-steps, or expandable sections. This gives users the ability to dig deeper into the troubleshooting details. - Limit input requests
Limit the number of input requests to 3, if possible. This helps avoid overwhelming the user and maintains a streamlined troubleshooting experience. - Change the status to pending when a sub-step is loading
When a sub-step is loading, change the status of the main step to pending to indicate that the step is in progress, and move the loading status to the sub-step rather than leaving it on the main step. - Prioritize the most urgent status
The status of the main step corresponds to the most critical status in the sub-step. For example, If there is an error, warning, and success status in the sub-steps, the main step will have an error status.
Don't
- Avoid displaying a loading state for under one second
Displaying a loading state for under one second can seem jarring to users and can cause flickering in the UI. For example, If the model supports streaming and has a rapid processing stage, don’t display the loading text in chat bubble, instead start streaming the response directly. - Don’t have more than 4 levels of sub-steps
Keeping the number of sub-steps limited to 4 levels or less helps maintain a manageable view for the user.
Writing guidelines
General writing guidelines
Use sentence case, but continue to capitalize proper nouns and brand names correctly in context.
Use end punctuation, except in headers and buttons. Don’t use exclamation points.
Use present-tense verbs and active voice.
Don't use please, thank you, ellipsis (...), ampersand (&), e.g., i.e., or etc. in writing.
Avoid directional language.
For example: use previous not above, use following not below.
Use device-independent language.
For example: use choose or select not click.
Component-specific guidelines Header Summary
Summarize progress in the header, matched to the kind of work.
Sequential steps: Use the format: [percentage] · [number] of [total] steps
For example: 40% · 2 of 5 steps
Independent steps: Use the format: [number] done · [number] running · [number] queued
For example: 3 done · 2 running · 1 queued
Add a segment for failed and stopped steps only when there are any, in the same order every time: done · running · queued · failed · stopped. Omit the zero counts rather than showing 0 failed
For example: 4 done · 1 failed · 1 stopped
When a run ends without finishing, say so in the summary. A percentage alone reads as progress that is still happening. Append the reason:
40% · 2 of 5 steps · stopped, or 40% · 2 of 5 steps · failed.
Don't count a stopped or failed step as done. The counts have to add up to the number of steps shown, or the summary contradicts the list underneath it.
Don't use a step position for concurrent work. Independent steps have no step number to be on.
Error
Step error: When a step has an error, provide clear and concise error details along with the failed status. Offer a retry option whenever it's appropriate for the user to attempt the action again.
Sub-step error: If there is more than 1 status within a sub-steps, such as an error and warning, display the status hub to the right of the main step.
Error details: When an error or warning message has lots of details corresponding to it, provide them in a popover. This will help overwhelming users with information displayed at once.
Independent step error: When a step in an independent run fails, keep the other steps running, show the failed step's error on its own row with its own retry, and don't imply the run is blocked.
Loading text
Follow the writing guidelines for loading and refreshing pattern.
Status indicator
Follow guidelines for status indicator component.
Related patterns and components
Status indicator
A status indicator communicates the state of a resource—either in its entirety or a particular facet of a resource—in a compact form that is easily embedded in a card, table, list, or header view.
Expandable section
With expandable selection, users can expand or collapse a section.
Steps
Display a list of tasks.
Did this page help you?
Your feedback helps us improve our documentation.