Structure messaging guidelines for a design system

Messaging guidelines within a design system are one of the most important things which define how the system communicates with the user by showing updates, errors, feedbacks & warnings.

Design systems are not just for visual references and code snippets, they define how the system will communicate with the user and vice versa. They also define consistency and help users of the design system to pick the correct mode of communication.

In this article, we’ll take a look at some tips on how to write and present messaging guidelines to help users of the design system to pick the correct mode of communication.

Type of guidelines

Open-ended guidelines can be generic and universal when you don’t require guidelines to be very specific and to be used by users according to the scenario while maintaining basic rules.

Strict & thorough
This type of guideline should be very detailed and specific, constructing it will require time as compared to open-ended guidelines. It has to be made sure that the user doesn’t interpret the components according to the scenario, the user should be able to apply the specified component according to the scenario.

We’ll be talking about Strict Guidelines in this article.


Identify your user, are they — designers, developers, quality analysts and keep them in mind while designing the guidelines as this will make a huge difference. Designers would be familiar with an interaction but developers won’t be, developers would be familiar with a certain technical error but designers won’t be. So make sure the guidelines are well defined and thought through.

Establish Principles

Source : Google Material Design

Let users know a high-level picture of the component’s functions and behavior, this gives a quick picture to users that if the component fits in the scenario before going through the whole guidelines for that component.

Explain user how these guidelines will help to choose correct messaging component

Users may not always know which component will fit the scenario or might get confused between two components. To mitigate this problem, different ways of representation can be used to help the user make a decision. It can be an infographic, a table, a high-level visual representation of all the components at once, or a combination of all of them. If making this is difficult, start making use cases for users, and then it will be easier to decide a way to explain.

Lighting Design System, visuals explaining how to choose a type of message
Lighting Design System, with the combination of the above visual representation and this table, user can choose a messaging component for the required scenario

States, types of messages

Users should be aware of all the types of messages within a message component. Each component comes with several states like error state, success state, informative state (do note that these individual states can be defined further like dismissable error or form error, we can talk about this in another article). States should have an urgency or priority queue with defined behavior so that users can choose when and what state to use based on urgency.

Source : Adobe Spectrum Design System

Each state has a specific use case which can be shown as an example, don’t assume the user to interpret on their own. Being specific helps the user to make a decision efficiently with less cognitive load.

Source : Carbon Design System

Messaging Components

There are different messaging components for each use case, few examples are Modal/Dialog, Toast, Popover, Inline message, and so on. These components should be well explained and defined, you can also add use cases/usage, behaviors for more detailed information.

Source : Carbon Design System


Where and how to place a component representation with context. The same type of message component can have different placements and have different use and meaning.

For example

  • A toast message placed on the top center means an informational and conformational toast that requires the user’s attention.
Source : Atlassian — Jira
  • A toast aligned near a field means a contextual toast which requires action.
Source : Gmail, when user send a mail this toast appears at a low priority position e.i bottom left

So, be very specific on details for placement guidelines and also include what that placement means.


Components messaging must allow the users to understand what is going on. It should follow the writing styles and the defined messaging principles. Each type component requires a specific type of content. You can further write detailed content guidelines while defining states of messages and use cases.

Source : Lighting Design System, Inline messaging

Few Extra things

Apart from visual specifications and anatomy of component, you can include examples for

  • Usage of messaging component, Do’s and Don’ts (This helps users to cater to many scenarios without even going through the document)
  • Animation guidelines with usage detail

Thank you for reading! I hope this article was helpful.

Cheers 😄




UX Designer

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Developer and designer: staying on the same page during the product creation.

How to insert motion graphic templates

No Longer Just For The Gamers — A Case Study On Discord

IronHack pre-work 1/3: Design Thinking

Lasting Lifestyles: Research Through Design

Cognitive Dissonance Theory

Cognitive Dissonance Theory

A meme that changes in dark mode: transparency magic

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


UX Designer

More from Medium

Patterns & Flows: Completing To-Dos with TeuxDeux

Tab Indexing for Complex Sites

Designing APIs