diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/External-links-and-resources.md b/docs/guidelines/language/menu-functions-and-ui-labels/External-links-and-resources.md new file mode 100644 index 00000000..9708839a --- /dev/null +++ b/docs/guidelines/language/menu-functions-and-ui-labels/External-links-and-resources.md @@ -0,0 +1,214 @@ +--- +sidebar_position: 7 +sidebar_label: External links and resources +title: 'External links and resources' +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'External links point users to information outside the application or to other resources. In order to make these links and resources accessible, we add alternative text (ALT-text) to icons and write clear link text.' +--- + +import React from "react"; +import { IxIcon } from "@siemens/ix-react"; +import { iconApplicationScreen } from "@siemens/ix-icons/icons"; +import { iconVideoFile } from "@siemens/ix-icons/icons"; +import { iconPdfDocument } from "@siemens/ix-icons/icons"; +import { iconOpenExternal } from "@siemens/ix-icons/icons"; + +# + +## General rules for external links + +Use brief, meaningful link text to explain the function of the target web page or resource. + +
+
+- SIMATIC S7-1500 firmware updates +- Roles and permissions in the documentation +- Demonstration projects +
+
+- Learn about the latest device firmware updates +- {'https://www.company.com/s7-1500-firmware'} +- Remote access +
+
+ +Pair link text with universal icons, e.g. the open-external or application-screen icons. + +
+
+- Company Digital ID +- Manage your software licenses in one place +
+
+ +Use descriptive link text instead of long, full URLs and remove the prefix {'https://www.'}. + +
+
+- Company homepage +- acronymfinder.com +
+
+- {'https://www.company.com/s9-1600-firmware'}
+- {'https://support.com/us/en/view/107826255'} +
+
+ +Avoid generic link text, e.g. "click here" without context or information regarding what opens. +
+
+- Description: The details regarding the collection and use of Analytics Data are described in Software Analytics Notice contained in the Application Function Manual.

+Link text: Open Application Function Manual +
+
+- Click here +- Read more +
+
+ +Use unique link text for each link destination so assistive technology users can distinguish between links (if all links have the same text, it makes it hard to know where each one leads). + +
+
+- Open Assembly Manual
Open Demonstration Project App
Explore Manual +
+
+- Click here
Click here
Click here +
+
+ +## General rules for resource texts + +Use brief, meaningful resource texts and explain the function and type of the resource. + +
+
+- Generative AI chat privacy information +- Interface module IM 155-5 MF HF Equipment Manual +- Industrial Copilots with Agentic AI +
+
+- example.company.com/downloads/file.pdf +- You can read more in the User Documentation +
+
+ +Pair resource text with icons, e.g. PDF-document or video-file icons. + +
+
+- Data Privacy Organization +- Industrial Copilots with Agentic AI +
+
+ +## Downloading resources + +Pair the download of resources with both file type and size whenever possible. + +
+
+- Download User Manual (54 MB) +
+
+ +## Text alternatives (ALT-text) for icons + +Describe link behavior and type in ALT-texts instead of repeating icon and visible link text. + +
+
+- Link text: Visit our homepage
ALT-text: external +- Resource text: Function Manual
ALT-text: external PDF +- Resource text:
Industrial Copilots with Agentic AI
ALT-text: external video in new tab +
+
+- Link text: Visit our homepage
ALT-text: Visit our homepage. +
+
+ +### Icon legend + +| Icon | ALT-text | +|------|----------| +| | Option 1: external
Option 2: open external link in new tab | +| | Option 1: external application
Option 2: open external application | +| | Option 1: PDF
Option 2: external PDF | +| | video | + +## Language + +Specify the language when the resource language differs from the app language (WCAG 3.1.2). + +
+
+- Application Function Manual (German) +- German web page (German) +
+
+ +## Layout + +Separate external links from body text with lists to avoid disrupting user reading flow. + +
+
+- Our platform integrates with various tools to enhance productivity.
+External resources:
Documentation portal
+GitHub repository
+Support community +
+
+ +Split external links from body text with separate paragraphs for faster scanning and enhanced transparency. + +
+
+- Description: Our new automation system improves efficiency by 40% and reduces downtime through predictive maintenance algorithms.

Link text: Efficiency report +
+
+- For more technical details, visit Automation Whitepaper . +
+
+ +## Emails and telephone numbers + +Avoid adding the "mailto" text and for email addresses as this is no longer visible the UI. + +
+
+- {'mailto:name@examples.com'} +
+
+ +Ensure email addresses and phone numbers are clickable. + +
+
+- You can reach us at the following telephone number +1 555-0100 +
+
+- 555 0100 +
+
+ +## Dos and Don'ts + +- Do add link text for transparency +- Do pair link and resource icons with clear texts +- Do use icons to visualize what will open, e.g. external link, PDF, etc. +- Do use ALT-text to explain icons +- Don't include https://, http: or www in URL text +- Don't add links in headings or sub-headings + +## Related + +- [Link button (component)](/docs/components/link-button/guide) +- [Icon library](/docs/icons/icon-library.mdx) +- [Numbers and percentages](/docs/guidelines/language/formatting/numbers) +- Web Content Accessibility Guidelines (WCAG) + - [WCAG 2.4.4 (Link Purpose In Context)](https://www.w3.org/TR/WCAG21/#link-purpose-in-context) + - [WCAG 1.1.1 (Non-text Content)](https://www.w3.org/TR/WCAG21/#non-text-content) + - [WCAG 3.1.2 (Language of Parts)](https://www.w3.org/TR/WCAG21/#language-of-parts) diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/UI-terminology.md b/docs/guidelines/language/menu-functions-and-ui-labels/UI-terminology.md new file mode 100644 index 00000000..1763f242 --- /dev/null +++ b/docs/guidelines/language/menu-functions-and-ui-labels/UI-terminology.md @@ -0,0 +1,229 @@ +--- +sidebar_position: 4 +sidebar_label: UI terminology +title: UI terminology +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'Using well-defined terms help users understand actions, navigate systems confidently and avoid confusion. Establishing shared vocabulary across teams 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. + +
+
+- click (desktop) +- tap (mobile device) +- select (when not sure if desktop or mobile) +
+
+ +Use clear and precise terms that leave no room for misunderstandings. + +
+
+- delete (if you want to erase data, e.g. a file) +- remove (if you want to take data away, e.g. permissions) +
+
+ +Use “select” for multi-platform applications where the input method varies (tap, click, etc.). + +
+
+- Select the checkbox to enable notifications. +- Select and hold the Shift key to select multiple items. +
+
+ +## 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) + +
+
+- click +
+
+- press +
+
+ +### Movement-based actions + +- drag +- drag and drop +- hover +- scroll + +
+
+- hover +
+
+- mouse over +
+
+ +## 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. + +
+
+- Press Enter to confirm +- Press Spacebar to play or pause +
+
+- Hit Enter +- Strike Enter +- Depress Enter +
+
+ +Capitalize special keys and directions. + +
+
+- Enter / Tab / Shift / Ctrl / Alt +- Up Arrow / Down Arrow / Left Arrow / Right Arrow +
+
+ +Use "type" when asking users to enter text. + +
+
+- Type admin in the username field. +
+
+ +## UI element terminology + +Use standardized and consistent terminology to describe UI components and input elements. + +
+
+- checkbox +
+
+- box +- option box +- selection box +- tick box +
+
+ +Avoid mixing terms within the same products and portfolios. + +
+
+- To enable automatic updates, select the checkbox to activate Auto update. +- Click this image +- The link opens in a new window. +- The link opens in a new tab. +
+
+- To enable automatic updates, select the box to activate Auto update. +- Click this picture +- The link opens in a new browser. +
+
+ +## 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).

Create: Make a new item from scratch. | Add a sensor to the monitoring list.

Create a new maintenance schedule. | +| start vs. activate | Start: Begin a process, operation, or activity.

Activate: Enable something so it becomes ready for use or functional. | Start the production line.

Activate the emergency shutdown system. | +| authenticate vs. authorize | Authenticate: Provide credentials for access.

Authorize: Grant permissions or access. | Authenticate with your employee ID.

Authorize access to the control panel. | +| browse vs. select vs. choose | Browse: Look through files, folders or items to find something.

Select: Choose an item from a list or collection.

Choose: Not recommended. Use "select" instead. | Browse available equipment models.

Select a machine from the list. | +| edit vs. configure | Edit: Change or adjust existing content (text, notes, values).

Configure: Adjust settings, options or parameters (behavior, rules, preferences). | Edit maintenance notes.

Configure alarm thresholds. | +| upload vs. import | Upload: Transfer or store data to the cloud.

Import: Transfer and process data or files into the application. | Upload calibrations certificates.

Import sensor data from CSV. | +| download vs. export | Download: Transfer data from one location to another.

Export: Transfer and process data from one location to another. | Download the inspection report.

Export production data to Excel. | +| apply vs. save vs. update | Apply: Confirm changes to settings or filters.

Save: Store changes or data.

Update: Upgrade to newer or corrected information. | Apply the new filter settings.

Save the equipment configuration.

Update the sensor framework. | +| refresh vs. reload vs. reset | Refresh: Retrieve and apply new or updated data.

Reload: Reinitialize whole pages or views. No new data.

Reset: Restore something to its original or default state. | Refresh the dashboard to see current readings.

Reload the monitoring interface.

Reset the machine to factory settings. | +| renew vs. update | Renew: Extend the validity or duration of something.

Update: Make it current by changing something. | Renew your safety certifications.
Renew your subscription.

Update the firmware to the latest build. | +| open vs. go to | Open: Display a file, list item or feature.

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).

Deny: Refuse or block something (policy-based decision). Not recommended. Use “reject” instead. | Reject or accept maintenance request. | +| delete vs. remove | Delete: Permanently erase an item, including its data.

Remove: Take something out of a list or collection without deleting its data. | Delete all obsolete work orders.

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 understand what each action does. + +### 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/) +- [Search and filter](#) +- [Logging in and out](./logging-in-and-out.md) diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md b/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md new file mode 100644 index 00000000..88903e26 --- /dev/null +++ b/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md @@ -0,0 +1,401 @@ +--- +sidebar_position: 6 +sidebar_label: License management +title: License management +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'Clear license and subscription management writing reduces user confusion, ensures compliance and builds trust with customers. These guidelines help you communicate licensing information accurately and effectively.' +--- + +# + +## General rules + +Use clear and consistent language your users are familiar with. + +
+
+- Your subscription expires in 30 days. Renew now to keep access to all features. +
+
+- Your entitlement terminates in 30 days. Execute renewal procedures to maintain feature provisioning. +
+
+ +Use the same terms throughout workflows, applications and portfolios to avoid confusion. + +
+
+- Activate your license / License activated / View activated licenses +
+
+- Activate your license / License enabled / View dynamic licenses +
+
+ +Use links and key points when referencing terms of use or compliance documents. + +
+
+- By using this software, you agree to our Terms of Use.
Key points: Install maximum 5 devices; commercial use requires a separate license. [View full terms](#) +
+
+- By using this software, you agree to our Terms of Service. +
+
+ +## Grammar and spelling rules + +Use American English spelling “license” (with s) for both nouns and verbs in all global interfaces. + +
+
+- Your license expires in 30 days. +
+
+- Your licence expires in 30 days. +
+
+ +Use “a license” when referring to single licenses in general, and “the license” when referring to specific licenses. + +
+
+- You need a license to access this feature. +- The license you purchased includes 5 users. +
+
+ +Avoid using apostrophes to describe singular (‘s) or plural (s’) license possession. + +
+
+- The license expires on May 1, 2026. +- The status of all licenses can be viewed here. +
+
+- The license’s expiration date is May 1, 2026. +- All licenses’ status can be viewed here. +
+
+ +Use active voice for user actions and passive voice when the actor is unknown or unimportant. + +
+
+- Activate your license now. +- Your license was activated successfully. +
+
+- Your license should be activated by you. +- The license activates. +
+
+ +Use hyphens to connect descriptive words before nouns. + +
+
+- A multi-user license +- The license is multi-user +
+
+- A multi user license +
+
+ +## License types + +Note licenses can be both proper nouns and common nouns (per Product License vs. per product license) depending on the context, e.g. legal contracts often consider license types as proper nouns. When unsure, we recommend using sentence case. + +| License type | Definition | Example | +| --- | --- | --- | +| Demo | Limited-feature version for evaluation purposes. | Notification: Demo mode | +| Free | No-cost version with basic features. | Status indicator: Free license active | +| Trial | Full-featured version with time limit. | Warning: 14 days remaining in trial | +| Promo package | Special promotional bundle or discount offer. | Popup: Get 3 modules for the price of 2 | +| Floating / Concurrent | Shared licenses with multiple users or limited simultaneous users. | Dashboard: 5 of 10 licenses in use | +| Named user | License assigned to a specific individual. | Heading: Licensed to [user name] | +| Backup | Redundant license for failure or continuity. | Status indicator: Backup license available | +| Test | License for testing only. | Watermark: Test environment: Not for production use | +| Token | Credit-based system where features consume tokens. | Balance display: 450 tokens remaining | +| By server | License tied to a specific server installation. | Settings: Licensed for server PROD-01 | +| By product | Separate license required for each product. | Status indicator: Advanced Analytics Module (licensed) | +| Single | One installation or one user only. | Status indicator: Single-user license active | +| Unlimited | No restrictions on users, installations or usage. | Settings: Unlimited license: No restrictions | + +## License states + +| License state | Definition | Example | +| --- | --- | --- | +| About to expire | License is close to its expiration date. | Warning: Expires on February 2 | +| Active | License is valid and in use. | System status: Active | +| Assigned | License has been allocated to a user or system. | User profile: Assigned to [user name] | +| Available | License is ready to be assigned or used. | Status indicator: Available for assignment | +| Compliance status | Indicates whether usage meets license terms. | Balance display: Compliant - 8 of 10 licenses used | +| Expired | License validity period has ended. | Error message: License expired on 15-Jan-2026 | +| Grace period | License has expired but remains functional for limited time. | Alert: Grace period: 5 days remaining | +| Inactive | License exists but is not currently in use. | Status indicator: Inactive | +| Exceeded | More users or instances in use than license allows. | Alert: License limit exceeded: 12 of 10 in use | +| Pending | License activation or approval is in progress. | Status indicator: Pending approval | +| Purchased | License has been bought but not yet activated. | Order summary: Purchased: Awaiting activation | +| Quarantined | License flagged for review or audit. | Alert: Quarantined: Under review | +| Reserved | License held for specific future use or users. | Status indicator: Reserved for [project name] | +| Revoked | License permanently withdrawn or cancelled. | Status indicator: Revoked: No longer valid | +| Suspended | License temporarily disabled due to non-payment or violation. | Warning: Suspended license: Contact administrator | + +## License actions + +| License action | Definition | Example | +| --- | --- | --- | +| Activate | Enable or start using a purchased license. | Button: Activate license | +| Allocate | Distribute licenses from a pool to departments or projects. | Admin panel: Allocate 5 licenses to Engineering team | +| Assign | Designate a license to a specific user or system. | Dropdown action: Assign to user | +| Audit | Review and verify license usage and compliance. | Menu item: Audit licenses | +| Borrow | Temporarily use a license from a shared pool. | Checkout dialog: Borrow license for 24 hours | +| Cancel | Terminate a license order or subscription. | Confirmation dialog: Cancel license subscription | +| Check in | Return a borrowed or checked-out license. | Button: Check in license | +| Check out | Reserve a license for temporary exclusive use. | Button: Check out license | +| Deactivate | Disable or stop using an active license. | Button: Deactivate license | +| Export | Generate a report or file of license information. | Button: Export license data | +| Extend | Prolong the validity period beyond original expiration. | Button: Extend license by 30 days | +| Import | Load license data or keys into the system. | File upload: Import license file | +| Install | Set up and configure a license on a system. | Installation wizard: Install license key | +| Reactivate | Re-enable a previously deactivated license. | Button: Reactivate license | +| Release | Free up a license from a user or system for reassignment. | Button: Release license | +| Renew | Extend the validity period of an existing license. | Notification: Renew license here | +| Reserve | Hold a license for future use or specific purpose. | Button: Reserve license for deployment | +| Revoke | Permanently withdraw or cancel a license. | Admin action: Revoke license | +| Suspend | Temporarily disable a license. | Button: Suspend license | +| Transfer | Move a license from one user or system to another. | User management: Transfer license to... | +| Unassign | Remove a license assignment from a user or system. | User management: Unassign license from… | +| Update | Modify license details or apply new license terms. | Settings: Update license information | +| Upgrade | Switch to a higher-tier license with more features. | Notification: Upgrade to Professional License | +| Validate | Verify that a license is genuine and properly configured. | System settings: Validate license | +| Verify | Confirm license authenticity and compliance. | System settings: Verify license status | + +## Time-related license messaging + +Use clear and specific dates, limits and consequences. + +
+
+- Your license expires on November 30, 2025. +
+
+- Your license will expire soon. +
+
+ +Use prominent and clear expiration warnings. + +
+
+- First notice: Your license expires on November 30, 2025. +- Second notice: Your license expires in 7 days. +- Final notice: Your license expires tomorrow. +
+
+ +Send timely, progressive reminders, especially for expiration and grace periods. + +
+
+- Heading: Your license has expired.
Description: Your license expired on January 1, 2026. To continue using our application renew your subscription.
Buttons: Renew now / Contact sales +- Grace period notice: 7 days +
+
+- License expired. +
+
+ +## License quantities and numbers + +Use “quantity” to refer to how many and “number” to refer to identifiers and codes. + +
+
+- license key number +- product number +- serial number +- Enter your license key number +
+
+- Enter your license key quantity +
+
+ +## License identification and keys + +Use “ID” for identification and tracking and “key” for activation or access. + +
+
+- Enter your license key number. +
+
+- Enter your license key ID. +
+
+ +Use “subscription ID” when referring to the unique identifier number or code for an entire subscription (often a long number or UUID). + +
+
+- Your subscription ID is 1234567890. +
+
+- Your subscription key is 1234567890. +
+
+ +Use “subscription key” when referring to a code or password required to activate or access a subscription. + +
+
+- Copy this subscription key to activate your subscription. +
+
+- Copy this subscription ID to activate your subscription. +
+
+ +Use “license ID” or “ID” for the unique identifier of a specific license within the subscription. + +
+
+- Each license has its own license ID for tracking and management. +
+
+- Each license has its own license key for tracking and management. +
+
+ +Use “license key” when talking about the code or string that unlocks or activates a specific license. + +
+
+- Enter your license key to activate the product. +
+
+- Enter your license ID to activate the product. +
+
+ +## License error messages + +When licenses cannot be found, explain possible causes and provide clear actions to resolve the issue. + +
+
+- Heading: License not found
Description: Failed to find a valid license for this product. This may happen if you’re registered under a different account, or if your license has not been activated yet.
Button: Sign in with different account +
+
+ +When licenses are not available, explain how users can resolve the issue. + +
+
+- Heading: No licenses available
Description: All 10 licenses are currently in use. Ask your administrator to assign a license to you or wait until one becomes available.
Buttons: Request license / View license usage +
+
+ +## Common wording issues + +Use “add-on” to refer to additional features or modules attached to an existing product. + +
+
+- Add the Health package add-on for obsolescence notifications. +
+
+ +Use “upgrade” for when users are moving to a newer or better version of the same product. + +
+
+- Upgrade to the Professional edition for more features. +- Upgrade your license from version 2.0 to version 3.0. +
+
+- Add the next edition as an add-on. +
+
+ +Use “requirement” to refer to what a user needs to run the software. + +
+
+- License requirements: Active subscription and internet connection. +- This feature requires an active maintenance agreement. +
+
+ +Use “entitlement” to refer to what the user is authorized to do. + +
+
+- Your entitlement includes 5 user licenses. +- This feature is not included in your current entitlement. +
+
+- Your requirement includes 5 user licenses. +
+
+ +Use the standard term “activate” and “assign” instead of the non-standard “start”. + +
+
+- Activate license now. +- Assign licenses to your team in your dashboard. +
+
+ +Use “renew” instead of “update” for continuing subscriptions. + +
+
+- Renew your license in one easy step. +
+
+ +Use “manage” instead of “edit” to administer licenses. + +
+
+- Manage your licenses under “License management”. +
+
+ +Use “base” product to talk about a foundation product that other features build on. + +
+
+- The base product includes core functionality. +
+
+ +Use “basic” product when talking about a simplified or entry-level version of your product. + +
+
+- Select either our Basic, Premium or Advanced licenses. +
+
+ +## Dos and Don’ts + +- Do create key license terms initially and record any changes for consistency +- Do use the same license actions consistently across applications and portfolios +- Don’t create new license types or states, instead use standard terms + +## Related + +- [Names and titles](../formatting/names-titles.mdx) +- [Dates](../formatting/date.mdx) +- [Error messages](../messaging/error-messages.mdx) +- [Time and time zones](../formatting/timezones.mdx) +- [UI terminology](#) +- [User management](#) \ No newline at end of file diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md b/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md new file mode 100644 index 00000000..12495124 --- /dev/null +++ b/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md @@ -0,0 +1,304 @@ +--- +sidebar_position: 5 +sidebar_label: User management +title: User management +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'User management involves guiding people through tasks like creating accounts, assigning roles, and managing software access. Clear, consistent language is essential as these actions often carry security, compliance and cost implications.' +--- + +# + +## General terms + +Use the term “role” to refer to a collection of “permissions” and avoid mixing terms across products. + +As the terms “right” and “privilege” are becoming less common due to localization and translation challenges, we recommend avoiding these terms both in the UI and documentation. + +| Term | Definition | +| --- | --- | +| Role | A collection of access rights and permissions. | +| Right | The type of operations permitted for a given user of a certain system resource (uncommon). | +| Privilege | The type of operations permitted for a given user (uncommon). | +| Permissions | Authorization to perform operations associated with a specific shared resource that must be granted by a system administrator to individual user accounts or administrative groups. | +| Credentials | Information that includes identification and proof of identification and is used to gain access to local and network resources. | + +## General rules + +Write user roles in short, clear and descriptive terms and give users access to role descriptions. + +
+
+- Line operator +
+
+- Basic user +
+
+ +Use role names consistently within workflows and across the whole product. + +
+
+- Device administrator / Device administrator / Device administrator +
+
+- Device Admin / Asset Admins / Administrator / Device Manager / Officer for devices +
+
+ +Focus on personas instead of generic and unclear titles when creating roles for your product. + +
+
+- Line operator +- Plant operator +- Service engineer +
+
+- Technician +- Team lead +- Expert user +
+
+ +Avoid mixing location with function when creating roles for your product. + +
+
+- User +
+
+- External user +- Local user +- International user +
+
+ +Avoid creating vague user roles without a clear persona or scope that can be misunderstood. + +
+
+- Production report creator +- Quality report reviewer +- Batch approver (review and release) +
+
+- Read-only user +- Write-only user +
+
+ +Use “read only” as a specific role permission, not a unique role name. + +
+
+- External consultant (read-only) +
+
+- Read-only user +
+
+ +Avoid easily misunderstood permissions such as “view”, be specific about what users can do. + +
+
+- record / log / configure / override +- adjust / review / modify / correct +- monitor / review / inspect +- track / display / observe +
+
+- write +- edit +- read-only +- view +
+
+ +Use sentence case for all user roles. + +
+
+- Service engineer +
+
+- Service Engineer +
+
+ +Avoid jargon or internal terms, instead use language everyone understands. + +
+
+- Plant manager +
+
+- Top tier +
+
+ +Keep role names short, preferably not more than three words. + +
+
+- Safety incident investigator +- Shift handover reporter +
+
+- Gateway and portal maintenance manager for Plant 3 and 5 (read-only permissions) +
+
+ +Avoid using functions or features as roles or permissions, instead focus on persona and tasks. + +
+
+- Shift supervisor – Production floor +
+
+- Dashboard user +
+
+ +## Identity and access + +Although often used interchangeably, the terms “account”, “user” and “profile” have distinct meanings. + +| Word | Definition | Usage and context | +| --- | --- | --- | +| account | A digital key that gives users access to a system or service. | Includes login credentials (username / email and password), permissions and sometimes billing or subscription details.

Use when talking about access, permissions and authentication. | +| user | The person or system working within software using an account. | Represents the person or system / maschine behind the account.

Use when talking about actions and roles in the system. | +| profile | Personalized or system-specific settings and information. | Includes details like name, photo, job title, preferences, language, time zone and other customizable settings.

Use when talking about personal information and preferences. | + +## Common wording pairs + +Many user management words often appear together in familiar, expected combinations (collocates). Use these common pairings to sound professional, while avoiding uncommon and “weird” combinations. + +| Common pairings | Definition | UI text examples | +| --- | --- | --- | +| activate accounts / permissions | Temporarily enable access without deleting information. | Button: Activate account | +| add users / permissions | Include users or permissions in a system. | Confirmation dialog: Add permissions for immediate access. | +| approve users / requests / access | Grant users access to the system following review. | Notification: 5 user requests approved | +| assign users / tasks / roles | Connect users to roles, groups or resources to enable specific permissions. | Toast message: Role assigned | +| authenticate users / identity / credentials | Users prove identity to gain secure access to an application. | Login screen: Authenticate with your ID | +| authorize users / roles / access / actions / requests | Determine what authenticated users are allowed to access or do. | Error message: Not authorized. Check your credentials and try again. | +| block users / profiles / accounts / domains / devices / addresses | Restrict interaction, communication or access. | Administrator action: Block IP address due to suspicious activity | +| create accounts / roles / groups / projects / workspaces / profiles / permissions | Establish something new in the system. | Form heading: Create user account

Form heading: Create new workspace | +| duplicate roles / permissions / configurations / projects | Create a copy that matches the original. | Button: Duplicate configuration | +| edit profiles / permissions / roles / settings / details / properties | Modify existing details and properties. | Form heading: Edit user profile | +| manage accounts / users / permissions / settings | Supervise and control accounts, roles and permissions within systems. | Navigation label: Manage users

Navigation label: User management | +| remove users / permissions / roles / members / access | Detach or revoke access or association while keeping the account active. | Warning message: Removing this role will disable any associated permissions. | +| revoke permissions / access / authorization / licenses | Formally withdraw something that was previously granted, often in access control contexts. | Button: Revoke all permissions for this role | +| verify users / identity / accounts / data | Confirm identity, authenticity and accuracy, often performed by administrators. | User action: Click the link to verify your account. | +| view profiles / details / history | Display and access details without the ability to modify (uncommon permission similar to read-only). | Permission: Can view user profiles | + +## Common wording mistakes + +Avoid using “deny” and “disapprove” with “user” as opposites to “approve”. + +
+
+- Reject access request +
+
+- Admin denied user +- Disapprove user +
+
+ +Avoid using “deauthenticate” as the opposite of authenticate. + +
+
+- Log out +- End session +
+
+- Deauthenticate +- Click to deauthenticate +
+
+ +Avoid using “grant” with “permissions” in casual UI contexts as this has become outdated. + +
+
+- Assign permissions to user +- Give user access to reports +
+
+- Grant permissions to user +
+
+ +Avoid using “read” for viewing UI elements like profiles, permissions and roles. + +
+
+- View user profile +- View role details +
+
+- Read user profile +- Read permissions +
+
+ +Avoid using “write” for editing or modifying UI elements. + +
+
+- Edit permissions +- Modify settings +
+
+- Write permissions +- Write role details +- Write to database +
+
+ +Avoid using “delete” when ending an association; use “delete” only for permanent erasure. + +
+
+- Unassign +- Remove user from team +- Remove role from user +- Delete user account (permanent) +- Delete file (permanent) +
+
+- Delete user from team +- Delete role from user +
+
+ +Avoid using “revoke” with people and users as direct objects. + +
+
+- Revoke all permissions +- Revoke API key +
+
+- Revoke user +- Revoke the employee +
+
+ +## Dos and Don’ts + +- Do ensure role behaviors are transparent and easy to understand +- Do use clear, descriptive role names that reflect user responsibilities +- Do group related permissions logically within roles +- Don’t create excessive numbers of roles because this causes confusion +- Don’t create overlapping roles with unclear differences + +## Related + +- [UI terminology](#) +- [License management](#)