From 7156a0f44a867791fd7f129f7d1b17c8a124975d Mon Sep 17 00:00:00 2001 From: Susanne254 Date: Tue, 18 Aug 2026 09:03:57 +0200 Subject: [PATCH] doc:button labels (new) --- .../button-labels.md | 460 ++++++++++++++++++ 1 file changed, 460 insertions(+) create mode 100644 docs/guidelines/language/menu-functions-and-ui-labels/button-labels.md diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/button-labels.md b/docs/guidelines/language/menu-functions-and-ui-labels/button-labels.md new file mode 100644 index 000000000..e5bc8576c --- /dev/null +++ b/docs/guidelines/language/menu-functions-and-ui-labels/button-labels.md @@ -0,0 +1,460 @@ +--- +sidebar_position: 9 +sidebar_label: Button labels +title: 'Button labels' +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'We ensure clear, actionable button instructions by crafting effective prompts and calls to action that enhance user interaction.' +--- + +# + +## General rules + +Aim for one action per button. + +
+
+
    +
  • Button: Acknowledge
    • +
  • Button: Edit
    • +
  • Button: Delete
    • +
+
+
+
    +
  • Button: Acknowledge the error and prepare for restart
    • +
  • Button: Edit or delete
    • +
+
+
+ +In limited cases, two closely related actions can be combined using "and". + +
+
+
    +
  • Button: Save and close
    • +
  • Button: Save and restart
    • +
  • Create and view account
    • +
+
+
+
    +
  • Button: Click here to save & close
    • +
  • Button: Save data to drive and restart
    • +
  • Create / view account
    • +
  • I'd like to create a new user account and view it
    • +
+
+
+ +Don't use more than five words on one button, ideally between 1-3. + +
+
+
    +
  • Button: Go back and edit details
    • +
  • Button: Save and close
    • +
  • Button: Compare and update
    • +
  • Button: Start firmware update
    • +
+
+
+
    +
  • Button: Click here to save and close
    • +
  • Button: Save data to drive and restart
    • +
  • Button: I'd like to create a new user account
    • +
+
+
+ +Don't use 'OK' as a button label. If a legacy system requires 'OK', use all caps. + +
+
+
    +
  • Heading: Error uploading file
    Description: The file could not be uploaded due to a network error.
    Button: Close
    • +
+
+
+
    +
  • Heading: Error uploading file
    Description: The file could not be uploaded due to a network error.
    Button: OK
    • +
+
+
+ +Clearly state specific actions on primary buttons that will occur when clicked, rather than generic terms, such as "Submit", "OK", "Yes", "Dismiss". + +
+
+
    +
  • Heading: Save changes to project
    Buttons: Cancel, Save changes
    • +
+
+
+
    +
  • Heading: Add new device
    Buttons: Cancel, OK
    • +
  • Heading: Remove device
    Buttons: Cancel, Dismiss
    • +
+
+
+ +Ensure the button label text verb and noun match the heading verb and noun making the user's choice easier. Only leave out the noun in extremely space-constrained mobile views where the context is clear and immediate. + +
+
+
    +
  • Heading: Add case
    Buttons: Cancel, Add case
    • +
  • Heading: Create new device
    Buttons: Cancel, Create device
    • +
  • Heading: Remove sensor from dashboard
    Button: Remove sensor
    • +
+
+
+
    +
  • Heading: Browse tags
    Buttons: Cancel, Update tags
    • +
  • Heading: Update list
    Buttons: Delete, Refresh list
    • +
  • Heading: Remove sensor from dashboard
    Button: Remove it
    • +
+
+
+ +When headings are far from the button within the UI or there are multiple steps or pages, always repeat nouns on buttons to lessen the cognitive load (even for space-constrained mobile views). + +
+
+
    +
  • Heading: Create gateway (step 5)
    Buttons: Cancel, Create gateway
    • +
  • Heading: Edit user role 'Administrator'
    Description: Saves all modifications to the 'Administrator' user role
    Buttons: Cancel, Save user role changes
    • +
  • Heading: Configure 'Temperature Sensor 01'
    Description: Confirm all current changes to settings across all tabs for 'Temperature Sensor 01' and activate the new configuration.
    Buttons: Cancel, Apply sensor configuration
    • +
+
+
+
    +
  • Heading: Initiate new project
    Description: Your new project has been initiated and is now visible in the project portfolio.
    Buttons: Cancel, Initiate
    • +
+
+
+ +Use our [UI terminology](../menu-functions-and-ui-labels/ui-terminology.md) section to clearly explain, differentiate and define what happens when buttons are activated, such as using "add" to insert items and "create" to make new items. + +
+
+
    +
  • Heading: Add calendar entry
    Buttons: Cancel, Add
    • +
  • Heading: Confirm settings
    Buttons: Cancel, Apply
    • +
+
+
+
    +
  • Heading: Add calendar entry
    Buttons: Cancel, Create
    • +
  • Heading: Confirm settings
    Buttons: Cancel, Save
    • +
+
+
+ +Use sentence case for all button labels. + +
+
+
    +
  • Button: Save and close
    • +
  • Button: Add user
    • +
  • Button: Save
    • +
  • Button: Delete account
    • +
+
+
+
    +
  • Button: Save and Close
    • +
  • Button: Add User
    • +
  • Button: SAVE
    • +
  • Button: DELETE Account
    • +
+
+
+ +Use direct, professional and action-oriented wording to be concise and to the point. + +
+
+
    +
  • Button: Apply
    • +
  • Button: Send email
    • +
  • Button: Save
    • +
+
+
+
    +
  • Button: Got it!
    • +
  • Button: Go
    • +
  • Button: Save it
    • +
+
+
+ +## Buttons and punctuation + +Don't use periods (full stops) as button labels are never full sentences. + +
+
+
    +
  • Button: Delete user
    • +
+
+
+
    +
  • Button: Delete user.
    • +
+
+
+ +Don't use exclamation marks in button labels. Instead add urgency to the messaging. + +
+
+
    +
  • Button: Save
    • +
+
+
+
    +
  • Button: Save!
    • +
+
+
+ +Don't use question marks in button labels. Instead show the consequences of the user's actions and avoid questioning their choice. + +
+
+
    +
  • Heading: Delete file
    Description: Deleting files results in immediate removal from the system. This action cannot be undone.
    Buttons: Cancel, Delete
    • +
+
+
+
    +
  • Heading: Delete file?
    Description: Are you sure you want to delete this file?
    Buttons: Cancel, Delete?
    • +
+
+
+ +Use ellipses (…) sparingly to indicate that an action requires significant further input or a secondary step before it is performed, such as opening a file explorer or a complex configuration dialog. + +Avoid using ellipses for standard actions or simple navigation to keep the interface clean and modern. The ellipsis serves as a signal that the action is not immediate and requires the user to specify details in a new window or modal. + +Note: This is a classic desktop convention (Windows/macOS). In modern web and mobile apps, ellipses are increasingly being removed to reduce visual noise unless the action is a complex, multi-step wizard. See [Punctuation](#). We recommend' removing them in our Siemens applications. + +
+
+
    +
  • Save as…
    • +
  • Browse…
    • +
  • Export to…
    • +
+
+
+
    +
  • Save…
    • +
  • OK…
    • +
  • Close…
    • +
+
+
+ +## Destructive actions + +Clearly label destructive actions on button labels. + +
+
+
    +
  • Heading: Delete account
    Description: This action will permanently delete your account and cannot be undone.
    Button: Cancel, Delete account
    • +
  • Heading: Factory reset device
    Description: Resetting will revert all settings to their original state.
    Button: Factory reset device
    • +
+
+
+
    +
  • Heading: Are you sure you want to delete your account?
    Description: This action will permanently delete your account and cannot be undone.
    Button: Sure
    • +
  • Heading: Factory reset device
    Description: Are you absolutely sure you want to proceed?
    Button: CONFIRM
    • +
+
+
+ +## Dropdown menu options + +Clearly state specific actions in the dropdown list, starting with an active verb. + +
+
+
    +
  • Primary button: Share
    Dropdown list: Email link, Share link, Copy link
    • +
  • Primary button: Manage document
    Dropdown list: Rename, Delete, Share
    • +
+
+
+
    +
  • Primary button: Settings
    Dropdown list: Profile, Notification, Privacy
    • +
  • Primary button: File
    Dropdown list: New, Recent, Changes
    • +
+
+
+ +Keep dropdown list text short, ideally between 1-2 words. + +
+
+
    +
  • Primary button: Manage account
    Dropdown list: Change password, Adjust notifications, Update privacy
    • +
+
+
+
    +
  • Primary button: Manage account
    Dropdown list: Modify your security credentials and password, Review and adjust your notification settings for alerts, Update your privacy settings and data sharing options
    • +
+
+
+ +## Workflow and navigation buttons + +Use specific and matching verbs within workflows with a series of steps to guide users through processes. + +
+
+
    +
  • Buttons: Cancel, Back, Create
    • +
  • Buttons: Cancel, Back, Add
    • +
  • Buttons: Cancel, Back, Apply
    • +
  • Buttons: Cancel, Back, Configure
    • +
  • Buttons: Cancel, Back, Save
    • +
  • Buttons: Cancel, Previous, Remove
    • +
  • Buttons: Cancel, Back, Skip
    • +
  • Buttons: Cancel, Back, Open
    • +
+
+
+
    +
  • Buttons: Next, Next, Next
    • +
+
+
+ +Avoid the generic "Next" button label in workflows unless there are no other alternatives. + +
+
+
    +
  • Heading of workflow: Add new edge device
    Step 1: Device
    Buttons: Cancel, Back, Next
    Step 2: Network interface
    Buttons: Cancel, Back, Next
    Step 3: Proxy
    Buttons: Cancel, Back, Add edge device
    • +
+
+
+ +## Buttons and state changes + +When loading states are displayed within modal, toast or inline messages, use the same button label verb in gerund (-ing) form with an ellipsis (…). + +
+
+
    +
  • Button: Saving…
    • +
  • Button: Loading…
    • +
  • Button: Uploading…
    • +
+
+
+
    +
  • Button: Save
    • +
  • Button: Load
    • +
  • Button: Upload
    • +
+
+
+ +Use the same button label verb in the simple past tense in status messages within modal, toast or inline messages. + +
+
+
    +
  • Request access → Requested
    • +
  • Save changes → Saved
    • +
  • Export data → Exported
    • +
  • Send message → Sent
    • +
  • Approve document → Approved
    • +
+
+
+
    +
  • Request access → Request access
    • +
  • Save changes → Being saving
    • +
  • Export data → Export done
    • +
  • Send message → Send
    • +
  • Approve document → Have approved
    • +
+
+
+ +## Accessibility + +Use aria-labels if the button has no visible label, e.g. icon buttons. See more information on [Text alternatives and labels](../../../guidelines/accessibility/code.md#text-alternatives-and-labels). + +
+
+
    +
  • aria-label: Close dialog
    • +
  • aria-label: Add chart
    • +
  • aria-label: More information
    • +
  • aria-label: Help
    • +
+
+
+ +Do not include the word 'button' in the aria-label. The screen reader announces the component automatically. + +
+
+
    +
  • aria-label: Close button
    • +
  • aria-label: Save button
    • +
+
+
+ +Make sure that the tooltip and aria-label match. See the [Accessibility](../../accessibility/overview.md) guidelines for more details. + +
+
+
    +
  • aria-label: Close dialog
    • +
  • Tooltip: Close dialog
    • +
+
+
+ +## Dos and Don'ts + +
+
+
    +
  • Do ensure button label text matches the heading
    • +
  • Do define actions clearly on button labels
    • +
  • Do add aria-label for icon buttons
    • +
+
+
+
    +
  • Don't ask questions in any part of the button label text
    • +
  • Don't add multiple actions in one button
    • +
+
+
+ +## Related + +- [Button (Component)](../../../components/button/guide.md) +- [Forms and input fields](#) +- [Warnings](../messaging/warning-messages.mdx) +- [UI terminology](../menu-functions-and-ui-labels/ui-terminology.md) +- [External links and resources](../menu-functions-and-ui-labels/external-links-and-resources.md) +- [WCAG: Using aria-label to provide labels for objects](https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA6)