Notes and Warnings

Updated on Apr 3, 2026

Notes and warnings break the natural text flow, and it is a best practice to visually separate notes and warnings from the rest of the text.

General

The visual separation between the notes and warnings, and the general content allows the users to point their attention to the information and easily identify it for skipping if they want to focus on the main flow.
This style guide recommends three types of supplementary content if necessary: Note, Tip, and Important.

Use notes and warnings sparsely. Too many of them on the page, especially showing two or more consecutive notes, lead to visual clutter and may overwhelm the user causing higher bounce rates and personal dissatisfaction.

Types and Content

Each note type is expected to render a specific type of information.

Note

A note indicates neutral or positive information that emphasizes or supplements important points of the main text.

A note supplies information that may apply only in special cases. For example, memory limitations, equipment configurations, or details that apply to specific versions of a program.
To visualize a note, don't place any prefix at the beginning of the entry:
```
> This is a note.
```

Tip

A tip is a note that helps users apply the techniques and procedures described in the text to their specific needs.

A tip suggests alternative methods that may not be obvious and helps users understand the benefits and capabilities of the product.
A tip is not essential to the basic understanding of the text.
To visualize a tip, use the tip prefix at the beginning of the entry:
```
>tip This is a tip.
```

Important

A block of important information provides details that are essential to the completion of a task.

While users can disregard information in a note and still complete a task, they are not advised to disregard an important block.
To visualize an important note, use the caution prefix at the beginning of the entry:
```
>caution This is an important note.
```