Callouts and Blockquotes
Separate the role of `Callout` and `Blockquote` instead of treating both as generic highlight boxes.
`Callout` and `Blockquote` are both visually emphasized in the reader, but they do different jobs. A callout is usually an author-owned note, warning, or boundary. A blockquote is usually a quotation, excerpt, or content whose original wording matters. Using the wrong structure makes docs look styled rather than well-layered.
When to use Callout
Use `Callout` when you need to warn readers about risk, prerequisites, publication boundaries, version differences, or permission requirements. It is an author-voice prompt, not a quotation. Common themes in current usage include `info`, `warning`, and `error`.
When to use Blockquote
Use `Blockquote` when you are quoting an external source, preserving someone else's wording, or isolating a short excerpt from the main prose. If the content is really your own operational note instead of a quote, do not fake it as a blockquote.
How to avoid overuse
Too many callouts on a page make it hard to see what is actually important. Too many blockquotes weaken the continuity of the main prose. The safer pattern is: body text carries the main explanation, callouts hold a small number of high-value warnings or notes, and blockquotes are reserved for wording worth preserving verbatim in spirit.
Effect on AI and public outputs
Both callouts and blockquotes flow into final render, plain-text exports, and public machine-readable artifacts. They are not just visual decoration. AI systems will read them too. That means callout copy should stay precise, and blockquotes should not be left without enough surrounding context.