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. Or what starts as a consistent use of callouts expands until the same callout types are used differently across pages, so readers don’t know what to expect from a callout and start ignoring them. That creates several problems:
  • When something is genuinely 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, review what each one is meant to accomplish: Questions to ask for each callout:
  • 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 very important information inside callouts can feel like the right choice because the styling of callouts makes it look significant. But separating information into callouts can have the opposite effect and make the information less visible if readers skip past the callouts. 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 and inline signals — How banners, tags, and badges help emphasize information site-wide, at the page-level, and inline.