Skip to main content
Callouts should tell readers to pay attention. If you overuse them, they become visual noise that readers skip. This is callout fatigue. The fix isn’t simply to use fewer callouts. First, decide whether the content belongs in a callout at all. If readers need information to complete the task, put it in the main content. Use callouts for exceptional context, optional advice, or genuine risk.

​
When callout fatigue happens

Callout fatigue builds gradually. Each callout may make sense on its own, but together they form a wall of styled text that’s hard to scan. It also happens across a site. As more people write pages, the same callout type starts to mean different things in different places. Readers stop knowing what to expect from a callout and start ignoring them. That creates two problems:
  • When something is actually dangerous, people might ignore a warning because it looks like every other callout with less important information.
  • Content outside of the callouts becomes hard to read because callouts create too much distraction.

​
How many callouts to use

There’s no useful universal limit. A page with one unnecessary callout has a problem; a reference page with several focused caveats may not. When a page has several callouts, ask these questions about each one:
  • Would a reader encounter a problem if they didn’t see this?
  • Does this need to be visually separated from the main content, or should it be part of another section?
  • Is this callout compensating for prose that could be clearer?
Callouts are sometimes used to fix problems introduced by other content. Instead of rewriting a paragraph, someone adds a <Note> explaining a caveat. Over time these callouts accumulate. Often, the fix is to revise the main text of a page instead of adding another callout.

​
Main ideas should be in the main content

Putting important information in a callout feels like it makes the information stand out. It can do the opposite: readers who have learned to skip callouts skip that information too. If users need to know something to complete the task, that information belongs in the procedure. Reserve callouts for things that apply to a subset of users, edge cases, or genuine risks. When readers skip past callouts and miss something important, that’s a writing problem, not a reader problem. This is especially common in setup guides:
Example of a poorly used callout
Move the required detail into the procedure:
Better: required information stays in the main path

​
Multiple callouts on the same page

If you find yourself writing several <Warning> callouts on a single page, stop and examine the content itself. Multiple warnings on one page can indicate:
  • The feature has too many dangerous edge cases and the documentation is papering over a product problem.
  • The procedure is too long and should be split into smaller pages.
  • Some of the warnings aren’t actually <Warning> level and should be downgraded or removed.
This applies to every callout type. If a page has many callouts, step back and look at the content itself. Ask two questions: What are readers trying to do, and what do they need to do it correctly? Next up: Site-wide, page-level, and inline signals—how banners, tags, and badges help emphasize information site-wide, at the page-level, and inline.