diff --git a/docs/guidelines/language/best-practices.md b/docs/guidelines/language/best-practices.md deleted file mode 100644 index 745ed1fb..00000000 --- a/docs/guidelines/language/best-practices.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -sidebar_position: 7 -sidebar_label: Best practices -title: Best practices -doc-type: 'banner' -component-tabs: [''] -no_single_tab: true -description: 'Familiarize yourself with general best practices for UX writing to maintain consistency and clarity across all your content. This section offers overarching guidelines that apply to various aspects of UX writing.' ---- - -# - -## Transitional text to show something is happening - -- Use -ing verbs and ellipses (…) - -- Do not use informal, transitional wording - -- Confirmation messages: Use the same verb as the transitional text - -
-
- -- Updating user roles… -- Submitting log files… -- Saving project… > Project saved -- Training models… > Models trained - -
-
- -- Getting ready… -- Chopping fruit… -- Saving project… > Project uploaded -- Training models… > Training done - -
-
- -## Error messages - -- Add a clear reason for the error - -- Do not blame the user - -- Add clear instructions for the user regarding what to do next to resolve the error - -- Do not over communicate - -- Use … to show an action is required, i.e. fill this in … - -
-
- -- System error: You’re offline. Check your connection and try again. -- File error: We cannot upload this file. Try uploading again. -- Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. - -
-
- -- What did you do!? -- The email address you entered does not match the required format. Please enter your email address using the standard format. - -
-
- -## Empty-state text - -- Empty-state wording tells the user the empty space is intentional and should be there, i.e. not an error - -- Use wording to move the user forward - -- Use wording to help users understand the function of the empty state - -- Do not over communicate - -- Use wording to show users how to resolve the empty state, e.g. with an action, click, etc. - -
-
- -- Allocate users in User management. -- To show rows, select a project. -- To save a project, select Save in Project detail list. - -
-
- -- No allocated users. -- No rows to show. -- No projects saved. - -
-
- -## Restoring behavior of items - -- Be clear on deleting, removing, creating and adding - -- Create goes hand in hand with Delete, it usually means it cannot be restored - -- Add goes hand in hand with Remove, it usually means it can be restored - -- Do not use Delete and Remove as synonym - -
-
- -- Create a chart and delete a chart -- Add a sensor to a chart and remove a sensor from chart - -
-
- -- Create a chart and remove it -- Add a sensor and delete the sensor - -
-
diff --git a/docs/guidelines/language/non-critical-information-messages.mdx b/docs/guidelines/language/non-critical-information-messages.mdx new file mode 100644 index 00000000..3d4d020a --- /dev/null +++ b/docs/guidelines/language/non-critical-information-messages.mdx @@ -0,0 +1,162 @@ +--- +sidebar_position: 99 +Sidebar_lable: Non-critical information messages +title: Non-critical information messages +doc-type: 'banner' +components-tabs: [''] +no_single_tab: true +description: Non-critical information messages come from the system and keep users updated on system status, operational changes, or relevant events and information. + +--- + +# + +## General rules + +### Keep messages short and concise. + +
+
+Pump 3 cycle complete 14:32. +
+
+ +
+
+The operational sequence of Pump 3, located within Zone 2B, activated at 07:34 by admin 049 has completed its cycle (timestamp 14:32). +
+
+ +### Use a professional, informative tone for routine updates and only include relevant information. + +
+
+System backup completed at 21:00. +
+
+ +
+
+Don’t worry! We’ll make sure your backup is complete before your morning coffee on Friday! +
+
+ +### Use clear timestamps for context, clarity, prioritization and record keeping. + +
+
+Motor overload detected at 14:01:15 +
+
+ +
+
+Emergency stop activated at 21:03:27 +
+
+ +
+
+Notification list: +* Motor 3 overheating +* Valve 7 malfunction +
+
+ +
+
+System shutdown initiated 10 minutes ago. +
+
+ +
+
+Lubrication check due for press machine 2 in 3 days. +
+
+ +### Avoid urgency wording as these types of notifications are typically not as critical as warnings. + +
+
+System backup complete. +
+
+ +
+
+System backup completed at 15:00 +
+
+ +
+
+System backup done! Open and check now! +
+
+ +### Avoid adding user actions when possible as these notifications should not impact the user workflow. + +
+
+Sensors calibrated. No further action required. +
+
+ +
+
+Sensors calibrated. Click to check sensors (live link), calibration settings (live link) or manage your sensors (live link). +
+
+ +### Use sentence casing to align with our UX writing guidelines + +
+
+System will be updated within three hours. +
+
+ +
+
+Scheduled maintenance for Line 4 starts at 14:00. +
+
+ +### Use minimal punctuation to keep notifications easy to read and without clutter or cognitive overload. + +
+
+System update on line 4 starts at 14:00. +
+
+ +
+
+Notification: System update! Line: 4 / Starts: 14:00 (2pm). +
+
+ +### Use industrial icons only when absolutely necessary and avoid emojis. + +
+
+Line 3 shift schedule changed. See what's new. +
+
+ +
+
+🔄 Line 3 shift schedule updated. 👉 See what’s new. +
+
+ +## Dos and Don'ts + +* Do use an alternative modal if your notifications are too long and cover multiple points +* Do make sure users understand the notification is not critical +* Don’t add multiple pieces of information into one notification +* Don’t insert multiple user actions into short notifications + +## Related + diff --git a/docs/guidelines/language/progress-updates.mdx b/docs/guidelines/language/progress-updates.mdx new file mode 100644 index 00000000..d716cea6 --- /dev/null +++ b/docs/guidelines/language/progress-updates.mdx @@ -0,0 +1,182 @@ +--- +sidebar_position: 10 +sidebar_label: Progress updates +title: Progress updates +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: While some companies use humorous text like "Chopping the onions…" or "Gathering your dragons…" to give users progress updates, our messages are straightforward and professional, such as "Loading…", "Saving…", or "Processing…" alongside visual indicators. + +--- +# + +## Use sentence case to align with our UX writing guidelines. + +
+
+Downloading assets… +
+
+Downloading Assets… +
+
+ +## Use the present simple progressive (continuous, -ing) verb form to indicate ongoing actions. + +
+
+Loading… +
+
+Downloading… +
+
+Charging… +
+
+Saving… +
+
+Searching… +
+ +
+Been loading… +
+
+To be loading… +
+
+Will be loading… +
+
+ +## Use verbs before nouns to focus on the action and make messages easier to scan. + +
+
+Downloading assets… +
+
+File loading… +
+
+ +## Use horizontal ellipses (…) after the verb without a space. +## Use the Unicode (U+2026) instead of adding three full stops (Mac Option+/Windows ALT+0133). + +
+
+Loading… +
+
+Loading … +
+
+Processing⋰ +
+
+ +## Use ellipses for text with numbers or the object to show a running process. + +
+
+Uploading 5 items… +
+
+Uploading items… +
+
+Processing request… +
+
+Saving settings… +
+
+Saving changes… +
+
+Uploading 1 file +
+
+ +## Avoid ellipses to show time remaining and approximate or unknown times as they're status indicators, not actions. + +
+
+5 minutes remaining +
+
+About 33 minutes remaining +
+
+5 minutes remaining… +
+
+About 33 minutes remaining… +
+
+ +## Change verb form without ellipses when possible in buttons with loading spinners to avoid visual clutter. + +
+
+Download → Downloading → Downloaded +
+
+Download → Downloading… → Downloaded +
+
+ +## Use specific and definitive text to make users aware of what is happening and how long the process takes. + +
+
+Downloading… +
+
+Please wait. +
+
+Thank you for waiting. +
+
+Just a moment. +
+
+ +## Use informative text and actions when multiple processes are happening at the same time. + +
+
+Carrying out tasks… +
+
+Thank you for waiting. +
+
+Just a moment. +
+
+ +## Use transitional text to manage user expectations and reduce frustration for lengthy processes. + +
+
+Processing your request. This usually takes about 1–2 minutes. +
+
+This step takes a bit longer than usual. +
+
+We’re preparing your dashboard. Once it’s ready, you’ll be able to customize your view. +
+
+ +## Dos and Don’ts +* Do use the present simple progressive (continuous, -ing) verb form +* Do use verbs before nouns to focus on the action +* Don’t apologize for how long the progress takes +* Don’t use vague phrases like: "Please wait." + +## Related diff --git a/docs/guidelines/language/time-related-messages.mdx b/docs/guidelines/language/time-related-messages.mdx new file mode 100644 index 00000000..d2369850 --- /dev/null +++ b/docs/guidelines/language/time-related-messages.mdx @@ -0,0 +1,278 @@ +--- +sidebar_position: 98 +sidebar_label: Time-related messages +title: Time-related messages +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: Time-related messages help users understand how long processes take. Use clear, specific time frames and pair them with actionable guidance to support fast, informed user decisions whilst managing user expectations. +--- + +# + +## Rules for known time frames + +### Use a specific time or time frame whenever possible. + +
+
+System update on Monday, August 22, 2025: 06:00–08:00 +
+
+ +
+
+Upcoming system update: 22 August +
+
+ +### Use the user’s time zone when providing any kind of time indication. + +
+
+Failed to synchronize data. Synchronized at 12:45 BST. +
+
+ +
+
+System maintenance scheduled for Wednesday, August 22: 02:00–04:00 BST +
+
+ +### When necessary, add time zones with the UTC in brackets. + +
+
+Failed to synchronize data. Last successful sync: 12:45 BST (UTC+1) +
+
+ +
+
+System maintenance scheduled for Wednesday, August 22, 02:00–04:00 BST (UTC+1). +
+
+ +### Avoid generic time-related terms like later, soon, sometime, etc. + +
+
+Update starts Tuesday, October 1, 2026: 02:00–04:00 +
+
+ +
+
+Update starts soon. +
+
+ +
+
+Update starts later today. +
+
+ +
+
+Update takes a few moments. +
+
+ +
+
+Update takes a while. +
+
+ +### Use "will" to indicate certainty and avoid "may" or "might" which sound uncertain. + +
+
+Update will take a few minutes. +
+
+ +
+
+Update may take a few minutes. +
+
+ +
+
+Update might take a few minutes. +
+
+ +### Avoid adding messages when the process takes less than ten seconds. + +
+
+This process takes a few seconds. +
+
+ +### Use countdowns to alert users to time-sensitive information. + +
+
+Session expiring in 04:25 minutes. +
+
+ +
+
+Automatic logout in 03:45 minutes. +
+
+ +
+
+Meeting starts in 5 minutes. +
+
+ +
+
+Migration starts in 1 hour. +
+
+ +### Use consistent wording from the UI and add specific volumes with progress indicators. + +
+
+Data volume: 45/300 MB +
+
+ +
+
+Saving data...50 of 300 MB saved +
+
+ +
+
+System update: 45% complete +
+
+ +## Rules for unknown time frames + +### Use a realistic time range or an estimated time window if possible. + +
+
+The system update can take a few hours. +
+
+ +
+
+The update will finish within the next 60 minutes. +
+
+ +### Be transparent and use passive voice when you need to be unspecific. + +
+
+Due to the size of the data migration, it is estimated to take between 4-6 hours. +
+
+ +
+
+Data is being fetched from multiple sources, and the completion time varies depending on system conditions. +
+
+ +
+
+Due to the size of the migration, we have no idea when it will finish. +
+
+ +## Rules for expectations and consequences + +### Inform users whether or not they can continue working during a process. + +
+
+The application will not be available during the update. We’ll notify you when it’s ready. +
+
+ +
+
+The application is not available during the update. +
+
+ +
+
+You can continue working until the update begins. +
+
+ +
+
+Installation files are downloaded in the background. +
+
+ +### Clearly communicate any consequences related to user actions (or inaction). + +
+
+You can only postpone this update once. +
+
+ +
+
+An update is scheduled to automatically install tonight. +
+
+ +
+
+The installation will be updated tonight. +
+
+ +
+
+Update must be installed before Friday, September 12, 2026. +
+
+ +
+
+The device will restart during the update. +
+
+ +### Provide clear, actionable choices for next steps and user autonomy. + +
+
+Postpone +Remind me tomorrow +Update now +More information +Stop +Pause +
+
+ +## Dos and Don’ts + +* Do add user actions when possible, e.g. buttons or links +* Don’t leave users wondering if the app is stuck or broken +* Don’t guess unknown time frames + +## Related diff --git a/docs/guidelines/language/toast-messages.mdx b/docs/guidelines/language/toast-messages.mdx new file mode 100644 index 00000000..c8eedfbc --- /dev/null +++ b/docs/guidelines/language/toast-messages.mdx @@ -0,0 +1,220 @@ +--- +sidebar_position: 97 +sidebar_label: Toast messages +title: Toast messages +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: Toast messages briefly inform users about the outcome of an action. Typically displayed near the bottom or top of the interface, they often close automatically without requiring user interaction. +--- + +# + +## Best practice template + +This section focuses on messages that give feedback to user actions and often automatically close. For system event messages with different levels of criticality, please see the status and event section of this guide. + +Although always short, toast messages vary in length and complexity: + +* One-line messages briefly inform users about the outcome of their action. +* Two-line messages have a heading and description to provide more context or details. +* Three-line messages include a heading, a description, and actions. + +| Anatomy | Content | Structure and examples | +|---------|---------|------------------------| +| **1. Heading** | Tell users the exact outcome of their action (for system toast messages, see the status and event section). | Noun + simple past tense verb: + +Data downloaded Asset deleted +Device deleted +Connection restored +Scan cancelled +Asset not offboarded | +| **2. Description** | Provide additional, relevant information. | Heading: Maintenance scheduled +Description: Exchange filer in room 500 on August 10. +Heading: File 4a.ext not uploaded +Description: File 4a.ext exceeds 25 MB | +| **3. Action** | Give users the ability to undo the action or provide a link to further information. | Action verb + noun: +Heading: Asset deleted +Description: Asset 4a_203/22 +Action: Undo + +Heading: Scan scheduled +Description: Scan gateway ANC_GW February 12 +Action: Open schedule + +Heading: Asset not onboarded +Description: Failed to reach Asset 4a +Action: Try again | + +## General rules + +### Use simple past tense verbs to state what happened. + +
+
+Assets uploaded +
+
+ +
+
+Assets have been uploaded +
+
+ +### Use "not" or "failed to" with the verb to signal failure. + +
+
+File not imported +
+
+ +
+
+Failed to import file +
+
+ +
+
+File type not recognized +
+
+ +### Use present progressive verbs for background or ongoing actions. + +
+
+Update application → Updating application… → Application updated +
+
+ +### Use the same verbs and nouns from the dialog and button that initiated the toast message. + +
+
+Upload file → File uploaded +
+
+ +
+
+Upload file → File added +
+
+ +
+
+Connect → Gateway connected +
+
+ +
+
+Connect → Gateway established +
+
+ +### Avoid punctuation as this takes up extra space and adds to visual clutter. + +
+
+Scan finished +
+
+ +
+
+Scan finished. +
+
+ +
+
+Scan not finished! +
+
+ +### Avoid adding additional words or verbs such as "you", "your", "is" or "was". + +
+
+Maintenance scheduled +
+
+ +
+
+Your maintenance was scheduled +
+
+ +
+
+Asset onboarded +
+
+ +
+
+Onboarding for asset was successfully completed +
+
+ +### Avoid generic toast messages, such as "successful", "unsuccessful", "error" and "failure". + +
+
+Connected +
+
+ +
+
+Successful +
+
+ +
+
+Failed to connect +
+
+ +
+
+Failed +
+
+ +### Avoid using "successful" and "successfully" as this adds to the reading load and effort. + +
+
+Connected +
+
+ +
+
+Connection successfully established +
+
+ +
+
+Connection established successfully +
+
+ +## Dos and Don'ts + +* Do add extra time when there is an action option +* Do use consistent wording to help users scan toast messages easier +* Don’t use full sentences or complex verb forms +* Don’t add an action unless absolutely necessary + +## Related + + diff --git a/docs/guidelines/language/tooltips.mdx b/docs/guidelines/language/tooltips.mdx new file mode 100644 index 00000000..bd671b49 --- /dev/null +++ b/docs/guidelines/language/tooltips.mdx @@ -0,0 +1,142 @@ +--- +sidebar_position: 77 +sidebar_label: Tooltips +title: Tooltips +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: Tooltips are small, informative pop-up elements that often appear when a user hovers over or focuses on a user interface element. They provide helpful context or explanations without cluttering the main interface, making them a valuable tool for enhancing usability and guiding users through complex features. +--- + +# + +## General rules + +### Use tooltips to define icons and show control names. + +
+
+Edit +
+
+ +
+
+Delete +
+
+ +
+
+Log out +
+
+ +### Avoid punctuation or periods for tool names or icons. + +
+
+Edit +
+
+ +
+
+Edit. +
+
+ +
+
+Open file +
+
+ +
+
+Open file. +
+
+ +### Use sentence case and a period if the tooltip is a complete sentence or multiple sentences. + +
+
+Add users to project. +
+
+ +
+
+Add new users to project +
+
+ +### Use verbs to start your tooltip and avoid passive voice. + +
+
+Create KPI tables. +
+
+ +
+
+Tables are created. +
+
+ +### Avoid complicated sentence constructions, e.g. no relative clauses. + +
+
+Share with team members. +
+
+ +
+
+Projects can be shared with team members who work with you. +
+
+ +### Use a heading with a short description for longer tooltips. + +
+
+Cycle time input +Set the duration of each production cycle in seconds. +
+
+ +
+
+Log history +View historical logs of machine activity and operator actions. +
+
+ +### Avoid repeating text already visible and readable on the screen. + +
+
+Edit (as icon) Tooltip: Edit +
+
+ +
+
+Edit (as text) Tooltip: Edit +
+
+ +## Dos and Don'ts + +* Do write tooltips to give more context about complex features +* Do write tooltips to support beginners +* Don’t use tooltips to convey lengthy or critical information +* Don’t add irrelevant information; focus on context + +## Related + + diff --git a/docs/guidelines/language/warning-messages.mdx b/docs/guidelines/language/warning-messages.mdx new file mode 100644 index 00000000..71a7e2f3 --- /dev/null +++ b/docs/guidelines/language/warning-messages.mdx @@ -0,0 +1,146 @@ +--- +sidebar_position: 55 +sidebar_label: Warning messages +title: Warning messages +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: Warning messages inform users of potential issues or risks. In industrial environments, warning messages help operators understand, anticipate and prevent problems before they escalate. +--- + +# + +## Best practice template + +We follow this three-step approach when creating our warning messages. This ensures users clearly understand the consequences of their actions. Although not every warning message in a product requires all three steps, aim for this whenever possible. + +| Step | Purpose | Description | Example | +|------|---------|-------------|---------| +| **1. Heading** | What? | Explain why the warning has been triggered. | Reset device | +| **2. Description** | Why? | Provide context to help users understand the consequences of ignoring the warning. | A reset restores the device to its factory settings, deleting all applications and user data. This action cannot be undone. | +| **3. Instructions** | How? | Explain how users can avoid these consequences and find solutions with links, buttons and suggestions. | Reset Cancel + +## General rules + +### Use warning messages only when an action or awareness is genuinely needed. + +
+
+Temperature readings from Zone 3 approaching 30°. Check cooling system and ensure all windows and doors are closed. +
+ +### Use clear, understandable titles and avoid generic warning messages. + +
+
+Temperature approaching 30° +
+ +
+
+Temperature warning +
+ +### Provide specific and clear consequences and solutions. + +
+
+Heading: Leave without saving +Description: You’re about to leave this page. Unsaved changes will be lost. Go back to save changes or exit without saving. +Button: Leave without saving +Button: Go back +
+
+Do you want to leave the page? +Button: Continue +Button: OK +Button: Cancel +
+
+ +### Avoid using words like "may", "might" or "possibly will" when explaining problems. + +
+
+Your changes will be lost if not saved. +
+
+Your changes might be lost if not saved. +
+
+ +### Include links to help pages or troubleshooting steps to avoid the consequences when possible. + +
+
+Heading: Login attempt from unknown device +Description: Review access settings or security guidelines to prevent unauthorized access. +Button: Open guidelines +Button: Open access settings +
+
+ +
+
+Heading: Unauthorized access attempt on Control Panel A +Description: Review access logs and verify user credentials. +Button: Open access logs +
+
+ +### Avoid repeating your message in both the heading and description. + +
+
+Heading: Pressure in Tank B approaching limit +Description: Initiate release protocol to avoid exceeding threshold. +
+
+Heading: Pressure in Tank B approaching limit +Description: Pressure in Tank B approaching limit so initiate release protocol. +
+
+ +### Avoid asking "Are you sure?" as this is vague, has no context, consequences and causes hesitation. + +
+
+This action will delete all sensor data from the last 24 hours. Do you want to proceed and delete? +
+
+Are you sure you want to delete? +
+
+ +### Use clear, urgent wording for irreversible actions. + +
+
+Title: Reset device +Description: A reset restores the device to its factory settings, deleting all applications and user data. This action cannot be undone. +Button: Reset +Button: Cancel +
+
+Press reset to proceed. +
+
+ +### Avoid using all uppercase text as it can be difficult to read and may seem like we’re shouting. + +
+
+WARNING!! FAILURE! IMMEDIATE ACTION REQUIRED!! +
+
+ +## Dos and Don’ts + +* Do be consistent by re-using the verbs of the message and buttons +* Do make sure users understand the warning’s context +* Do give users actions to avoid any negative consequences +* Don’t use "please" with the call to action or options +* Don’t use patronizing questions such as "Are you sure…?" + +## Related + diff --git a/docs/guidelines/language/writing-style-guide-getting-started.md b/docs/guidelines/language/writing-style-guide-getting-started.md index 596cd89c..442c53e3 100644 --- a/docs/guidelines/language/writing-style-guide-getting-started.md +++ b/docs/guidelines/language/writing-style-guide-getting-started.md @@ -36,11 +36,11 @@ Get tips for naming common app functions clearly and effectively. This subchapte ## Best practice -Familiarize yourself with general best practices for UX writing to maintain consistency and clarity across all your content. This section offers overarching guidelines that apply to various aspects of UX writing. [Read more](./best-practices) +Familiarize yourself with general best practices for UX writing to maintain consistency and clarity across all your content. This section offers overarching guidelines that apply to various aspects of UX writing. ## Errors, warnings and notifications -Learn how to write error messages, warnings, and notifications that are helpful and user-friendly. This subchapter provides strategies for communicating issues and alerts in a way that guides users towards solutions. [Read more](./error-messages) +Learn how to write error messages, warnings, and notifications that are helpful and user-friendly. This subchapter provides strategies for communicating issues and alerts in a way that guides users towards solutions. ## Dialogs and buttons