Skip to main content
Some components solve one narrow problem like defining a term, formatting a changelog entry, pinning an example beside the content, or giving readers a prompt they can copy. Before adding one of these components, identify what problem it solves. If the only reason you’re about to use a component is because “the page looks plain,” text is probably a better choice than a component.

​
Define a term without sending readers away

A tooltip works for a short definition that helps in the moment:
The sentence still makes sense if someone doesn’t open the tooltip. That’s important because hover interactions are easy to miss and work differently on touch devices. Keep instructions, required context, and links in the page itself. A tooltip should save a quick detour, not conceal part of the task.

​
Give release notes a consistent shape

The <Update> component is built for dated changelog entries:
Its label creates an anchor, and its tags help readers filter the changelog. That behavior is useful on a release-notes page but unnecessary inside an ordinary guide. When a product change affects the current instructions, update the guide rather than inserting a permanent release announcement into it.

​
Trade the table of contents for a side panel

<Panel> replaces the page’s table of contents with content you choose. API reference pages use this space well: a request and response can stay visible beside the field descriptions they support. That tradeoff is less attractive on a long guide. If readers rely on the table of contents to move between sections, replacing it with a tip or promotional card makes the page harder to navigate. Use a panel when the sidebar content supports the entire page and is more useful than section links—not simply because the sidebar is available.

​
Give readers prompts they can actually run

Use <Prompt> when the content is meant to be copied into an AI tool:
A useful prompt says what to inspect and what to return. “Improve this page” leaves both decisions to the tool and gives readers little idea what result to expect. If the text is a shell command or code sample, keep it in a code block. The Prompt component is for instructions to an AI tool, not anything that happens to be copyable.

​
Use visual helpers only when they add information

Tiles combine navigation with a visual preview. They work well for a gallery where the preview helps readers choose, such as themes or component examples. If the image adds nothing beyond the title, use a card or a normal link. Icons help distinguish repeated items, but always pair them with a label. A symbol that feels obvious to your team may mean something different to a reader. Color swatches belong in brand and design-system references where the color value is itself the subject. They aren’t a substitute for explaining status or meaning in text. That’s the end of the components course. When you’re unsure about a component, write the content in plain Markdown first. Add the component only if it makes the result easier to find, follow, or understand.