Create UI-terminology.md

docs/guidelines/language/menu-functions-and-ui-labels/UI-terminology.md

@@ -0,0 +1,244 @@
+---
+sidebar_position: 4
+sidebar_label: UI terminology
+title: UI terminology
+doc-type: 'banner'
+component-tabs: ['']
+no_single_tab: true
+description: 'Using well defined terms helps users understand actions, navigate systems confidently and avoid confusion. Establishing shared vocabulary across teams and products streamlines collaboration, reduces misunderstandings and ensures a cohesive user experience.'
+---
+
+#
+
+## General rules
+
+Always consider the difference between user actions within a desktop environment based on mouse or keyboard usage and mobile devices based on touch gestures.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- click (desktop)
+- tap (mobile device)
+- select (when not sure if desktop or mobile)
+</div>
+</div>
+
+Use clear and precise terms that leave no room for misunderstandings.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- delete (if you want to erase data, e.g. a file)
+- remove (if you want to take data away, e.g. permissions)
+</div>
+</div>
+
+Use "select" for multi-platform applications where the input method varies (tap, click, etc.).
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- Select the checkbox to enable notifications.
+- Select and hold the Shift key to select multiple items.
+</div>
+</div>
+
+## Mouse terminology
+
+This section provides clear definitions for the most frequently used mouse-related terms to ensure consistent communication and avoid misunderstandings.
+
+### Basic actions
+
+* click
+* double-click
+* left-click
+* right-click
+* middle-click (scroll wheel)
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- click
+</div>
+<div className="donts" markdown>
+- press
+</div>
+</div>
+
+### Movement-based actions
+
+* drag
+* drag and drop
+* hover
+* scroll
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- hover
+</div>
+<div className="donts" markdown>
+- mouse over
+</div>
+</div>
+
+## Touchscreen terminology
+
+As touchscreen interfaces rely on direct finger interaction, this section covers the most important touchscreen gestures.
+
+### Basic gestures
+
+| Gesture | When to use |
+|---------|------------|
+| tap | Touch and release quickly |
+| double-tap | Tap twice quickly |
+| tap and hold | Touch and maintain contact with screen |
+| select | Choose an item (any input method or platform) |
+| select and hold | Choose an item and maintain contact with screen |
+
+### Simple movement gestures
+
+* drag
+* flick (fast and short swipe)
+* scroll
+* slide
+* spread
+* swipe
+
+### Multi-finger gestures
+
+* pinch
+* spread (reverse pinch)
+* rotate
+* two-finger scroll
+
+## Keyboard terminology
+
+Use "press" when referring to the physical action of pressing a key.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- Press Enter to confirm
+- Press Spacebar to play or pause
+</div>
+<div className="donts" markdown>
+- Hit Enter
+- Strike Enter
+- Depress Enter
+</div>
+</div>
+
+Capitalize special keys and directions.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- Enter, Tab, Shift, Ctrl, Alt
+- Up Arrow, Down Arrow, Left Arrow, Right Arrow
+</div>
+</div>
+
+Use "type" when asking users to enter text.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- Type admin in the username field.
+</div>
+</div>
+
+## UI element terminology
+
+Use standardized and consistent terminology to describe UI components and input elements.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- checkbox
+</div>
+<div className="donts" markdown>
+- box
+- option box
+- selection box
+- tick box
+</div>
+</div>
+
+Avoid mixing terms within the same products and portfolios.
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- To enable automatic updates, select the checkbox to activate Auto update.
+</div>
+<div className="donts" markdown>
+- To enable automatic updates, select the box to activate Auto update.
+</div>
+</div>
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- Click this image
+</div>
+<div className="donts" markdown>
+- Click this picture
+</div>
+</div>
+
+<div className="dos-and-donts" markdown>
+<div className="dos" markdown>
+- The link opens in a new window.
+- The link opens in a new tab.
+</div>
+<div className="donts" markdown>
+- The link opens in a new browser.
+</div>
+</div>
+
+## UI interaction terminology
+
+Basic interactions form the foundation of how users engage with your applications. Two terms that sound alike, but have different meanings, can cause difficulties for writers. This section highlights the most common words that are often confused.
+
+| Commonly confused terms | Definitions | Examples |
+|-----------|-------------|----------|
+| add vs. create | Add: Insert an item (into a list or collection).<br/><br/>Create: Make a new item from scratch. | Add a sensor to the monitoring list.<br/><br/>Create a new maintenance schedule. |
+| start vs. activate | Start: Begin a process, operation, or activity.<br/><br/>Activate: Enable something so it becomes ready for use or functional. | Start the production line.<br/><br/>Activate the emergency shutdown system. |
+| authenticate vs. authorize | Authenticate: Provide credentials for access.<br/><br/>Authorize: Grant permissions or access. | Authenticate with your employee ID<br/><br/>Authorize access to the control panel. |
+| browse vs. select vs. choose | Browse: Look through files, folders or items to find something.<br/><br/>Select: Choose an item from a list or collection.<br/><br/>Choose: Not recommended. Use "select" instead. | Browse available equipment models.<br/><br/>Select a machine from the list. |
+| edit vs. configure | Edit: Change or adjust existing content (text, notes, values).<br/><br/>Configure: Adjust settings, options or parameters (behavior, rules, preferences). | Edit maintenance notes.<br/><br/>Configure alarm thresholds. |
+| upload vs. import | Upload: Transfer or store data to the cloud.<br/><br/>Import: Transfer and process data or files into the application. | Upload calibrations certificates.<br/><br/>Import sensor data from CSV. |
+| download vs. export | Download: Transfer data from one location to another.<br/><br/>Export: Transfer and process data from one location to another. | Download the inspection report.<br/><br/>Export production data to Excel. |
+| apply vs. save vs. update | Apply: Confirm changes to settings or filters.<br/><br/>Save: Store changes or data.<br/><br/>Update: Upgrade to newer or corrected information. | Apply the new filter settings.<br/><br/>Save the equipment configuration.<br/><br/>Update the sensor framework. |
+| refresh vs. reload vs. reset | Refresh: Retrieve and apply new or updated data.<br/><br/>Reload: Reinitialize whole pages or views. No new data.<br/><br/>Reset: Restore something to its original or default state. | Refresh the dashboard to see current readings.<br/><br/>Reload the monitoring interface.<br/><br/>Reset the machine to factory settings. |
+| renew vs. update | Renew: Extend the validity or duration of something.<br/><br/>Update: Make it current by changing something. | Renew your safety certifications.<br/>Renew your subscription.<br/><br/>Update the firmware to the latest build. |
+| open vs. go to | Open: Display a file, list item or feature.<br/><br/>Go to: Not recommended. Use "open" instead. | Open user management settings. |
+| reject vs. deny | Reject: Decline or not accept something (decision-based, one-time decision).<br/><br/>Deny: Refuse or block something (policy-based decision). | Reject or accept maintenance request. |
+| delete vs. remove | Delete: Permanently erase an item, including its data.<br/><br/>Remove: Take something out of a list or collection without deleting its data. | Delete all obsolete work orders.<br/><br/>Remove the sensor from the active monitoring list. |
+
+## Common opposite and paired terminology
+
+Many actions come in natural pairs or opposites. Using the right pairs help users clearly understand what each action does.
+
+### Common opposites
+
+| Common opposites |
+|--------|----------|
+| Add | Remove |
+| Activate | Deactivate |
+| Block | Unblock / Allow |
+| Create | Delete |
+| Download | Upload |
+| Enable | Disable |
+| Expand | Collapse |
+| Export | Import |
+| Log in | Log out |
+| Open | Close |
+| Minimize | Maximize |
+| Start | Stop |
+| Undo | Redo |
+| Zoom in | Zoom out |
+
+## Dos and Don'ts
+
+* Do maintain the same terms for the same actions across all screens
+* Do use specific and standardized component names
+* Do consider the user environment, e.g. mobile, desktop, touchscreen
+* Don't use unclear or vague terms, e.g. field, instead of text field
+
+## Related
+
+* [Button (component)](../../../components/button/)
+* [Button labels](#)
+* [Search and filter](#)
+* [Logging in and out](./logging-in-and-out.md)