ui-001 should GuidesAPI docsMarketing Bold all UI element names (buttons, menus, dialogs, panes, tabs, checkboxes, toggles, commands, and so on) when referenced in instructions.
UI elements
These rules cover formatting UI element names, choosing interaction verbs, writing keyboard keys and menu paths, and the standard terms for common elements. Step-by-step structure lives in procedures, and when to show the UI in an image lives in screenshots.
Bold UI element names
Section titled “Bold UI element names”Examples
- ✓ Click Save.
- ✗ Click Save.
Rationale
Bold marks a UI element name so the reader can spot the exact control to act on in a step.
Sentence case for UI labels
Section titled “Sentence case for UI labels”ui-002 should GuidesAPI docsMarketing Use sentence-style capitalization for UI element labels in instructions; match the UI only when the label is consistently cased in mixed or title case.
Examples
- ✓ Go to Access control and select a role.
- ✗ Go to Access Control and select a role.
Rationale
Sentence-cased labels stay consistent with the guide unless the UI itself uses a fixed casing to match.
Omit the element type
Section titled “Omit the element type”ui-003 should GuidesAPI docsMarketing Avoid naming the UI element type (button, dialog box, pane) unless omitting it would reduce clarity.
Examples
- ✓ Click Delete.
- ✗ Click the Delete button.
Rationale
Naming the element type is redundant when the label and bold already identify it, unless it aids clarity.
Drop trailing ellipses from labels
Section titled “Drop trailing ellipses from labels”ui-013 should GuidesAPI docsMarketing Omit trailing ellipses from UI element labels when referencing them in instructions.
Examples
- ✓ Select Export.
- ✗ Select Export….
Rationale
The ellipsis on a label is not part of its name, so instructions leave it off.
Menu paths with greater-than
Section titled “Menu paths with greater-than”ui-010 should GuidesAPI docsMarketing Use a greater-than symbol (>) with spaces on both sides to abbreviate sequential UI selections; do not bold the symbol itself.
Examples
- ✓ Go to File > Settings > Editor.
- ✗ Go to File > Settings > Editor.
Rationale
A spaced greater-than sign compactly shows a menu path, and not bolding it keeps it separate from the labels.
Click, tap, or select
Section titled “Click, tap, or select”ui-004 should GuidesAPI docsMarketing Use click as the primary verb for mouse/pointer interactions, with tap for touchscreen interactions and select for checkboxes, radio buttons, and list items.
Examples
- ✓ Click Deploy. On a touchscreen, tap Deploy.
- ✗ Hit Deploy. On a touchscreen, hit Deploy.
Rationale
Matching the verb to the input keeps instructions accurate across mouse, touch, and selection.
Select and clear checkboxes
Section titled “Select and clear checkboxes”ui-005 should GuidesAPI docsMarketing Use select and clear (not check and uncheck) for checkbox interactions.
Examples
- ✓ Clear the Send analytics checkbox.
- ✗ Uncheck the Send analytics checkbox.
Rationale
Select and clear are input-neutral and unambiguous, while check can be read as verify.
Turn on and turn off
Section titled “Turn on and turn off”ui-006 should GuidesAPI docsMarketing Use turn on and turn off (or switch) for toggle interactions; do not use toggle as a verb.
Examples
- ✓ Turn on Two-factor authentication.
- ✗ Toggle Two-factor authentication.
Rationale
Turn on and turn off describe a toggle’s result plainly, while toggle as a verb does not say which way.
Press keys, type text
Section titled “Press keys, type text”ui-007 should GuidesAPI docsMarketing Use press for keyboard key actions that trigger a function, and enter or type for keyboard input that produces text.
Examples
- ✓ Type your project name, and then press Enter.
- ✗ Press your project name, and then type Enter.
Rationale
Press fits a key that triggers an action, while enter or type fits producing text, so the reader knows what to do.
Spell out modifier keys
Section titled “Spell out modifier keys”ui-008 should GuidesAPI docsMarketing Spell out modifier key names in full (Control, Command, Option, Shift) rather than using abbreviations or symbols.
Examples
- ✓ Press Control+C to stop the server.
- ✗ Press Ctrl+C to stop the server.
Rationale
Full key names are unambiguous across platforms, unlike symbols that vary.
Distinct formatting for keys
Section titled “Distinct formatting for keys”ui-009 should GuidesAPI docsMarketing Format keyboard keys and shortcuts using a distinct visual treatment, such as <kbd> tags or bold, and capitalize key names.
Examples
- ✓ Press
<kbd>Esc</kbd>to close the panel. - ✗ Press esc to close the panel.
Rationale
A distinct visual treatment marks a key so it is not mistaken for ordinary text.
In and on for UI locations
Section titled “In and on for UI locations”ui-014 should GuidesAPI docsMarketing Use the preposition that matches the UI element’s spatial metaphor: in for container elements (dialogs, fields, lists, menus, panes, windows, sections) and on for surface elements (pages, tabs, toolbars, canvases). If an element could reasonably be either, either preposition is acceptable; stay consistent within a document.
Examples
- ✓ In the Settings dialog, select a theme.
- ✗ On the Settings dialog, select a theme.
- ✓ On the Usage tab, review your quota.
- ✗ In the Usage tab, review your quota.
Rationale
The prepositions track how English speakers describe space: you are in a bounded region like a dialog or pane, and on a flat surface like a page or tab. Framing it as that principle lets an author apply it to new UI patterns.
Avoid directional language
Section titled “Avoid directional language”ui-011 should GuidesAPI docsMarketing Avoid directional language (above, below, left-hand side, right-hand side) to orient users to UI elements; use screenshots, icon names, or contextual labels instead.
Examples
- ✓ In the navigation menu, click Billing.
- ✗ In the menu on the left-hand side, click Billing.
Rationale
Above and on the left break when layout reflows or is read linearly, so a name or label is stable.
No slang for UI elements
Section titled “No slang for UI elements”ui-012 should GuidesAPI docsMarketing Do not use slang or informal terms for UI elements (hamburger icon, zippy, expando).
Examples
- ✓ Click the menu icon, and then select Settings.
- ✗ Click the hamburger, and then select Settings.
Rationale
Slang names are not universal and do not translate, so a plain description works for everyone.
Dialog, not pop-up window
Section titled “Dialog, not pop-up window”ui-015 should GuidesAPI docsMarketing Use dialog (not pop-up window or dialog box) for a smaller window that appears in front of the main application window.
Examples
- ✓ In the Confirm delete dialog, click Delete.
- ✗ In the Confirm delete pop-up window, click Delete.
Rationale
Dialog is the precise term for a small window over the main one, while pop-up and dialog box are looser.
Page versus window
Section titled “Page versus window”ui-016 should GuidesAPI docsMarketing Use page (not window) when referring to a web page or a subpage of a console; use window for the full application window in a desktop environment.
Examples
- ✓ On the Billing page, review your invoices.
- ✗ In the Billing window, review your invoices.
Rationale
Page fits web content and window fits a desktop app, so the right term matches what the reader sees.
Navigation menu
Section titled “Navigation menu”ui-017 should GuidesAPI docsMarketing Use navigation menu (not navigation bar, navigation pane, navigation panel, or navigation window) for a control containing a list of navigable items.
Examples
- ✓ In the navigation menu, click APIs.
- ✗ In the navigation pane, click APIs.
Rationale
One consistent term for the navigation control keeps references clear across the docs.
Menu item or command
Section titled “Menu item or command”ui-018 should GuidesAPI docsMarketing When referring to an item in a menu, use menu item or command based on context: prefer menu item in procedural instructions where location matters or when the item isn’t a direct command, and prefer command when emphasizing the action, discussing command-line interfaces, or referring to keyboard shortcuts. Avoid choice and option.
Examples
- ✓ Use the Find command to search the file.
- ✗ Use the Find option to search the file.
Rationale
Menu item and command describe the same thing from different angles, one by location and one by action, so allowing both lets an author pick the word that fits the sentence instead of forcing a single term.