Skip to main content

Illustrated Message Guidelines

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

Generally used as a placeholder until other content can be displayed (empty state, error feedback), and occasionally as the content itself (welcome message, success state). The message should explain why the state is present and guide the user to the next step.

  • Title: short, e.g. "No Items", "No Results", "Couldn't Load".
  • Description: elaborates and guides the user, e.g. "Could not find anything for this keyword, try refining your search." Link to documentation if a longer explanation is needed.

Best Practices​

Placement​

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

Layout and Size​

  • Use the default vertical layout if it fits; fall back to horizontal 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 the Icon Library.
  • Only use self-hosted images if absolutely necessary — they make the UI harder to redesign or theme.

Action​

  • The button can be highlighted or neutral depending on its importance.
  • Documentation links should use the Helper Link Button variant.

UI Text​

  • Title: describe the state as briefly as possible.
  • Description: elaborate and guide the user to the next step. No more than 3 sentences.
  • Make generic terms like "item" more specific to suit the context.

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.