code

Code shows what people type or copy, such as a command, a flag or a file name, in monospace. By default it sits inside a sentence; it can also stand on its own, as a block.

Set --replicas=0 to stop the service, then check that ctl get volumes lists the volume as detached.

when to use

Inside a sentence, for what people type or copy: a command such as “ctl get volumes”, a flag such as “--replicas=0”, a file name or a setting.
As a block, for a command people copy and run, a few lines of configuration, or a command with its output.

when to use something else

For a key on the keyboard. Use a keycap, such as enter.
For values in monospace that people read rather than type, such as durations, sizes and hashes in a list or a table cell. Use mono text: monospace, with no frame and no colour. A column of framed cyan cells is noise.
For emphasis. Cyan pulls the eye, so keep it for code. To make a word stand out in a sentence, use interface text.

anatomy

Inline:

Frame. A thin border on a darker shade of the canvas, close around the text, with square corners.
Text. Monospace, in cyan.

Block:

Frame. A thin border on the same darker shade, with room around the text and no space outside it. It scrolls sideways.
Text. Monospace, in light grey. Spaces and line breaks are kept as written. Long lines scroll, and never wrap.

variants and states

Inline code sits in running text. It wraps with the sentence, at its spaces, so keep it short.

A block shows several lines exactly as written. It has no maximum height and grows with its content, so show a few lines, not a whole log.

$ ctl rollout status api-7f9c
waiting for rollout to finish: 1 of 3 updated
waiting for rollout to finish: 2 of 3 updated
rollout finished: 3 of 3 updated

A long line scrolls inside the block instead of wrapping.

ctl backup create --volume storage-01 --target https://backup.example.com/v1/archive --keep 14d --verify

Blocks can follow one another.

ctl login https://ops.example.com
ctl get volumes

ctl release create 2.4.1

There is no syntax highlighting, so all the code is in one colour. There are no line numbers, no copy button and no way to wrap long lines either.

behaviour

Inline code, and a block that fits, aren't a tab stop.
A block whose lines run past its edge becomes a tab stop of its own while it overflows: tab reaches it, and the arrow keys scroll it.
The text in both forms can be selected and copied like any other text.

The full keyboard map is on the React page for code.

accessibility

Most screen readers read the text without saying “code”.
A block keeps its line breaks, and screen readers read it line by line.
A block that scrolls has a name of its own, its accessible name, and that name is “code” unless you give it a better one. Name it after what it holds: “install command”.
The cyan of inline code and the light grey of a block both have plenty of contrast on their background.
Symbols are read out as they are. The prompt, the “$” a terminal shows before a command, is read as “dollar”. Leave it out of commands people copy.

content

Show the command exactly as it runs, with real flags. Use made-up names and hosts: “api-7f9c”, “storage-01”, “example.com”.
A command people copy has no prompt. When you show a command with its output, mark the typed line with “$”, so the two read apart.
Inline code is one word, or something just as short, such as a flag. A command longer than a few words gets a block.
Don't put a sentence in code.

do and don't

Set --replicas=0 before the backup.

Inline code for the one thing people type.

don't

scale it down before the backup

A sentence in code isn't code. It is harder to read, and it looks like something to type.

ctl backup create --volume storage-01 --keep 14d

A command people copy goes in a block, without a prompt.