ui-001 should GuidesAPI docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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 docs 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.