Usage
Wells are messages that provide the user with feedback. They can either be Zywave system-generated or user-initiated.
Wells provide a container and give emphasis to text. They should be used to attract the users attention to a message, more than just uncontained text. They are typically always present but in rare cases can animate in.
For more information on when a well is the appropriate delivery system, see messages.
Anatomy
We use the following terminology to refer to the parts of a well:
- Sidebar: Defines the type of well by color: info (blue), warning (yellow), error (red).
- Action (optional): A single action typically associated with the message, such as "View details."
- Icon: Defines the type of well by an icon: info, warning, error.
- Header (optional): Briefly describes the message to the user. The header should be H3 and remain on one line, with a max-width of 65 characters without spaces.
- Close: Allows the user to close a dismissible well.
- Body text: Provides the main content for the well. The body text should be three lines or less, with a max-width of 65 characters per line without spaces.
For detailed documentation on our well anatomy, view the ZUI well design specs.
Types
We differentiate wells by both color and icon. These features allow a user skimming the page to know, at a glance, the importance of the message. We have three types of wells which are each color-coded with a unique icon to help convey the criticality of the message within.
Info well
Gives the user additional information or context that they might find useful.
Warning well
Informs the user of the potentially undesirable outcome of a future action.
Error well
Tells the user that an attempted action or product feature has failed.
For detailed documentation on our well anatomy, view the ZUI well design specs.
Default well (static)
Default wells are best used when the message should be present, regardless of the user's actions.
Dismissible well
Sometimes a well doesn't need to be present on the screen at all times. A dismissible well allows the user to close it. Our recommendation is to use dismissible wells for reminders and minimal-impacting messages that appear frequently, but do not impede the user's workflow.
When a well is dismissed, we recommend the application remember the user's choice and not show the well again after a page refresh or the back button is pressed to get back to the previous page.
The close icon button follows the same state rules as a button. For more information on these states, see buttons.
Banner well
An example where a banner well would be used is when an employee is reviewing forms before sending to an administrator.
A banner well spans across the entire width of the page. It can be used to deliver site-wide messages; messages that appear on more than one page; or messages that appear in a single workflow.
We recommend you always make banner wells static so they don't make the page content jump around.
Behavior
Animated well
A well can be animated to call attention to it, but only after a user takes action to trigger its appearance. Our recommendation is to use animated wells sparingly and only when a message is triggered by the user.
Note: animating a well will push content down on the page, causing a jarring user experience.
Positioning
By default, wells are always either anchored to the top-left of the page or near the content that it's associated with. Whereas, user-initiated wells should appear by the action that triggered it.
Multiple
Multiple wells should be used sparingly and only seen in certain circumstances. For example, a well appears on the screen and a user-initiated well is triggered.
If there are multiple wells on a page, they should be the same width, with the exception of banner wells appearing with default wells.
Best-practices
Adding actions to wells
Wells can include a single action associated with the message. Actions in wells are styled like text links and are the same color as the well sidebar. This contrasts the action against the well message and calls additional attention to it.
To not confuse users, we recommend calling out one action per well.
Well action buttons are styled similar to text links but are the same color as the well sidebar. For more information on these states, see the ZUI well design specs.
Lines of text (default well)
- Use concise language and keep it to one paragraph.
- Use 1-3 lines of text (just right).
- Avoid multi-paragraph wells.
- Avoid using only 1-5 words (too short).
Multiple wells
- Use default wells that are the same length.
- Use of a default well and a banner well on the same page is ok.
- Avoid setting default wells at different lengths.
- Avoid setting a banner well to the same width as a default well when both appear on the same page.
Well actions (number of actions)
Use one action.
Avoid using more than one action.
Well action style
Match the text link action color to the well sidebar color.
Avoid using the primary and secondary ZUI buttons as the action.
Labeling well actions
Use an actionable label such as "View details."
Avoid using a non-actionable label such as "Details."
Banner wells behavior
Use a static banner well.
Avoid animating the banner well.
Positioning of wells
Default info wells appear before or after something.
Do not position a default info well at the very bottom of the page when its association is further up the page.