Components

The main action control: primary, secondary, ghost, danger, and text.

Do

One primary button in each decision group, labelled with a verb for its result, such as “Save changes”. Every other action in the group is secondary, ghost, or text.

Don’t

The danger variant on an action the reader can undo. Danger marks an action that destroys something.

A small transparent action inside a component, such as Copy or Close.

Do

Use it for an action inside a component: Copy in a code block or command list, close in a dialog or drawer, Full size on a capture, and the project trigger.

Don’t

An action that stands on its own in the page, such as Save or Next. That is a button.

One recipe for Copy, Full size, dialog and drawer close, and the project trigger. Each component sets only its size and place.

Pick several options, or one from a short list.

Do

Checkboxes for options the reader can pick in any combination. Radios for one choice from a short list that stays in view.

Don’t

A label written as a question, such as “Send updates?”, or as a negative, such as “Don’t email me”. Name the option: “Email me updates”.

Pick one option that needs a description.

Do

Use radio cards when the reader chooses by a description, such as plans or deploy modes. Give each card a title and one line on what differs.

Don’t

Radio cards for options that a title alone explains. Use radios.

Turn a setting on or off at once.

Do

Use a switch for a setting that applies the moment it changes. Its label names the setting, such as “Dark mode”, and stays the same when on or off.

Don’t

A switch in a form that applies on submit. Use a checkbox there.

A labelled card that latches on, with a switch inside.

Do

Use it for an on or off option whose label sits inside the control, such as “Wrap lines” in a viewer’s toolbar.

Don’t

A toggle button for an action that runs once, such as Refresh. It stays on until pressed again; an action is a button.

Two to five short options that apply at once.

Do

Use it for two to five short options that apply at once and change how the same content shows, such as a view mode or the System, Light, and Dark choice.

Don’t

A segmented control that switches between panels of content. Use tabs.

The live control glides its thumb between options: 260ms for the leading edge, 300ms for the trailing edge. The theme picker at the top uses the same script, and it does not glide when the page loads a saved choice.

Type a short value or a longer note.

Do

A textarea for an answer longer than one line, and type="search" for a field that filters.

Don’t

A label or an instruction that lives only in the placeholder. It disappears as the reader types.

Choose from a longer list.

Do

Use a select for one choice from more than five options, in a predictable order: alphabetical, numeric, or by frequency of use.

Don’t

A first option that acts as the label, such as “Choose a region”. The label goes above the field.

Label, description, and error text around a field.

Do

Write the error as the fix, such as “Enter a date after today”, and the description as a format or limit, such as “Up to 64 characters”.

Don’t

A description that repeats the label, or an error that only says “Invalid”.

Set a value in a range.

Do

Use a slider for an approximate value in a range, such as volume or opacity, and show the current value as text beside it.

Don’t

A slider for a value the reader must set exactly, such as a port or a price. Use a text input.

Show how far a task has got.

Do

Use it for a task with a known end, such as an import, and name it for the task.

Don’t

A progress bar for a measured value, such as disk usage or a rating. It shows a task moving to its end; use text or a score.

Show a value out of a maximum.

Do

Use it for a value out of a fixed maximum, such as 4/5, and keep one maximum across a list so the rows compare.

Don’t

A score for a percentage or an open-ended count. Write the number as text.

A short status label.

Do

A one- or two-word status or category on an item, such as “Healthy” or “Beta”, with a status tone only when it is a status.

Don’t

A badge that repeats the title, or one on every row with the same value. Badge the exceptions.

A real caveat or status message in the page.

Do

Use an alert for a caveat or status message the reader needs before acting. When action is needed, name it, such as “Reconnect the source to resume sync”.

Don’t

An alert for decoration or routine emphasis. A short status label is a badge; explanations and recovery instructions stay in an alert.

Panels and cards for parallel, comparable content.

Do

Use cards for a few parallel, self-contained items that a reader compares, such as plans or projects.

Don’t

A panel inside a panel, or cards around ordinary prose.

An image or diagram with a caption.

Do

Caption every figure with what it shows. When the prose refers to one figure by number, number them all.

Don’t

A screenshot of code or of a component. Show code as text, so the reader can copy it, and a component live.

A modal task that needs an answer before the page continues.

Do

Use a dialog for a short task the reader must finish or cancel before the page continues, such as confirming a deletion. Title it with that task.

Don’t

A dialog that opens without the reader asking, such as on page load, or one that holds a long form. A long form gets its own page.

A side panel, such as phone navigation.

Do

Use a drawer for navigation or supporting detail that slides in from the side its trigger sits on, such as phone navigation, and open it from a named button.

Don’t

The page’s main task inside a drawer. The drawer holds navigation or detail; the task stays on the page.

Rows of links with current page and current location.

Do

Label a page link with the destination page’s title, and an in-page link with its destination section’s heading.

Don’t

Actions such as Delete or Sign out in a navigation list. Every row is a link to a place; an action is a button.

A sticky list of sections that moves into a drawer on phones.

Do

Use a rail for the sections of a long page, or for a site’s pages. A site’s pages may take a navigation strip of 6 links or fewer instead.

Don’t

A rail beside a strip or a contents list that holds the same links. Each level has one list.

Filter a navigation list as you type.

Do

Use it at the top of a long navigation list, such as a section rail, to filter its rows by name or purpose.

Don’t

A find field used as a site-wide search. It matches only the rows of the list it filters.

The path from the site to this page.

Do

Put the trail above the page’s h1 on every page below the site’s home page, and keep the project switcher in the header.

Don’t

A trail in the site header in place of the project switcher: the header changes from page to page, and the path reads as the page title.

Previous and next pages in a sequence.

Do

Use a pager for pages a reader goes through in order, such as a guide’s chapters or the skills in one group.

Don’t

A pager on pages with no reading order, or one per section on a page with a section rail.

Switch panels about one object, without leaving the page.

Do

Use tabs for panels about one object, such as a monitor’s Overview and History, when the URL does not change.

Don’t

Links with role="tab", or one set that mixes pages and panels. Pages take a navigation strip.

Jump past the header to the content.

Do

A “Skip to content” link on every page with a header or rail before main; the first Tab shows it.

Don’t

Hiding it with display: none, which also takes it out of the Tab order.

Show a key or shortcut in text.

Do

A key or shortcut in running text or shortcut docs, one key per <kbd>.

Don’t

A key style for code or button names. Code takes <code>; a button’s name is plain text.

Source code with an optional header and Copy, and a live example above it.

Do

Use a code block for source with no live result. When the reader should see the result too, use the variant with a live example.

Don’t

The same language label on every block of a page. Put useful setup context above the block instead.

1const threshold = 300 // ms at p952export const name = 'API p95 latency'

import { threshold } from './monitor'

<button class="btn secondary" type="button">Cancel</button><button class="btn" type="button">Save monitor</button>

A shell command on a hue-tinted plate.

Do

Use it for a shell command the reader runs, one command per line.

Don’t

A $ typed into the command. CSS draws the prompt; a typed one is copied with the command.

brew install filipgutica/tap/filip-stack

pnpm install --frozen-lockfilepnpm check

filip-stack apply

A recorded terminal screen with a status line.

Do

Use it to show what a command prints, one tab per capture, with the path and branch in the status line.

Don’t

A capture for a screenshot of a graphical app. Use a figure.

● host-config   3 targets current
● field-guide   synced 2 minutes ago

tokens.css  +12 −4

The ~/name header with project switcher and appearance.

Do

Keep the same header and site links, six at most and in one order, on every page of a personal product site.

Don’t

The site header on an application screen. An application keeps its own navigation.

Mono headings, steps, definitions, facts, and the footer.

Do

Use steps for a sequence the reader follows in order, definitions for terms with short meanings, and facts for short labels and values.

Don’t

The ## mark on an application screen, or on h3 and lower.