When to use
Section titled “When to use”- To show several lines of code in developer docs, API key set-up steps and integration examples.
- When the user needs to copy a command or a configuration.
When not to use
Section titled “When not to use”- To copy a single value: use Copy.
- For short code inside text: use inline
code. - To show a key: use Kbd.
Anatomy
Section titled “Anatomy”- Header: an optional
figcaptionwith the title, the language and the copy button. - Scroll region: a focusable, named region; long lines scroll sideways.
- Line number: optional; screen readers skip it, and it is not selected or copied.
- Code line: mono type; can be highlighted.
Behaviour
Section titled “Behaviour”- The code is shown as written; leading and trailing blank lines are removed.
- The copy button writes the whole code to the clipboard, without line numbers, and confirms it.
- There is no syntax colouring;
languageis only written in the header. This is deliberate: a highlighting library adds bundle size and its colours would need contrast checks in every brand and mode, which short code samples in a merchant portal do not justify.
Guidelines
Section titled “Guidelines”- Keep examples short and working.
- Use placeholders instead of real keys or customer data.
- Use
wrapfor long commands; prefer sideways scrolling for code.
Content
Section titled “Content”- The title is a file name or a short phrase that says what it does: “Install”,
config.json. - Explain the code in the text before the CodeBlock, not inside the code.