Illustrated Message Guidelines

Illustrated Messages display information about the current state of a content area. The content area can be a page, a dialog, a section on a page, a floating panel, a datagrid, etc.

Generally it’s used as a placeholder until other things can be displayed in the content area, such as empty state (e.g. “no items in the table yet”) or error feedback (e.g. “could not load items in the table”).
Occasionally it can be the content itself, such as a welcome message at the top of a form, or a success state at the end of a workflow.
The message should explain why the state is present, and guide the user to the next step with follow-up actions.

The title of the message should be short (e.g. “No Items”, “No Results”, “Couldn’t Load”), and the description should elaborate and guide the user (e.g. “Could not find anything for this keyword, try refining your search.”).
If the reason for the state needs a longer explanation, link to the documentation.

The illustration can either be an icon from our Icon Library or a custom image provided by the product.

Best Practices

Placement

• Center of containers, such as layout boxes, dialogs, pop-up panels.
  • Exception: if the container is too long and doesn’t fit in the viewport, align the component to the top-center.

Layout and Size

• Use the default vertical layout if it fits. Fall back to horizontal layout if it doesn’t.
• Use the default size if it fits. Fall back to small size if it doesn’t.

Illustration

• Use a relevant icon from our Icon Library.
• Consider contributing to our Icon Library if none of the icons fit your use case.
• Self-hosted images make the UI less centralized, which can be a problem for redesigns or theming, so only use them if you absolutely need them.

Action

• The button can be a highlighted button or a neutral button, depending on its importance.
• Documentation links should be Helper Link Buttons.

UI Text

• Title: describe the point of the state as short as possible
• Description: elaborate on the state, and guide the user to the next step.
  • Shouldn’t be more than 3 sentences.
• Make generic terms like “item” more specific to make more sense in the context of the implementation.
• For more details, refer to the UI Text Guidelines.

Extra Content

• Short-form content (e.g. a short list of key-value pairs) can be displayed after the description and before the follow-up actions.
• Long-form content (e.g. a datagrid) should be displayed outside the Illustrated Message.

Accessibility

• Use alt text for images to make them parseable by screen readers.