From a10c508603ead31d60f2a9359dfc12fcda57f349 Mon Sep 17 00:00:00 2001 From: Susanne254 Date: Wed, 14 Jan 2026 15:04:35 +0100 Subject: [PATCH 1/6] docs:new error pages link removed --- .../language/writing-style-guide-getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guidelines/language/writing-style-guide-getting-started.md b/docs/guidelines/language/writing-style-guide-getting-started.md index 596cd89c7..442c53e34 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 From c0e8c8ac9b1d18cf4d30114fe97d731e019d548b Mon Sep 17 00:00:00 2001 From: Susanne254 Date: Thu, 15 Jan 2026 09:56:11 +0100 Subject: [PATCH 2/6] doc: new messages and progress updates --- .../non-critical-information-messages.mdx | 162 ++++++++++ docs/guidelines/language/progress-updates.mdx | 176 +++++++++++ .../language/time-related-messages.mdx | 278 ++++++++++++++++++ docs/guidelines/language/toast-messages.mdx | 200 +++++++++++++ docs/guidelines/language/tooltips.mdx | 142 +++++++++ docs/guidelines/language/warning-messages.mdx | 146 +++++++++ 6 files changed, 1104 insertions(+) create mode 100644 docs/guidelines/language/non-critical-information-messages.mdx create mode 100644 docs/guidelines/language/progress-updates.mdx create mode 100644 docs/guidelines/language/time-related-messages.mdx create mode 100644 docs/guidelines/language/toast-messages.mdx create mode 100644 docs/guidelines/language/tooltips.mdx create mode 100644 docs/guidelines/language/warning-messages.mdx 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 000000000..593ff54e4 --- /dev/null +++ b/docs/guidelines/language/non-critical-information-messages.mdx @@ -0,0 +1,162 @@ +--- +sidebar_position: 3 +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 000000000..964e2fdf6 --- /dev/null +++ b/docs/guidelines/language/progress-updates.mdx @@ -0,0 +1,176 @@ +--- +sidebar_position: +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. +
+
+ +## Related diff --git a/docs/guidelines/language/time-related-messages.mdx b/docs/guidelines/language/time-related-messages.mdx new file mode 100644 index 000000000..f7fef90b9 --- /dev/null +++ b/docs/guidelines/language/time-related-messages.mdx @@ -0,0 +1,278 @@ +--- +sidebar_position: 8 +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 000000000..8a0f18b7f --- /dev/null +++ b/docs/guidelines/language/toast-messages.mdx @@ -0,0 +1,200 @@ +--- +sidebar_position: 5 +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 000000000..34b8c3efc --- /dev/null +++ b/docs/guidelines/language/tooltips.mdx @@ -0,0 +1,142 @@ +--- +sidebar_position: 6 +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 000000000..5578c8f72 --- /dev/null +++ b/docs/guidelines/language/warning-messages.mdx @@ -0,0 +1,146 @@ +--- +sidebar_position: 2 +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 + From 1409be04902c392cd9440324f23b4d089479dba9 Mon Sep 17 00:00:00 2001 From: Susanne254 Date: Thu, 15 Jan 2026 14:15:46 +0100 Subject: [PATCH 3/6] doc/formatting corrected --- docs/guidelines/language/best-practices.md | 106 ------------------ docs/guidelines/language/progress-updates.mdx | 2 +- .../language/time-related-messages.mdx | 8 +- docs/guidelines/language/toast-messages.mdx | 26 ++++- docs/guidelines/language/tooltips.mdx | 4 +- docs/guidelines/language/warning-messages.mdx | 10 +- 6 files changed, 35 insertions(+), 121 deletions(-) delete mode 100644 docs/guidelines/language/best-practices.md diff --git a/docs/guidelines/language/best-practices.md b/docs/guidelines/language/best-practices.md deleted file mode 100644 index 4dee4bc63..000000000 --- a/docs/guidelines/language/best-practices.md +++ /dev/null @@ -1,106 +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.' ---- - -import DoAndDont from '@site/src/components/DoAndDont'; - -# - -## 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/progress-updates.mdx b/docs/guidelines/language/progress-updates.mdx index 964e2fdf6..7b5dcf80b 100644 --- a/docs/guidelines/language/progress-updates.mdx +++ b/docs/guidelines/language/progress-updates.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: +sidebar_position: 10 sidebar_label: Progress updates title: Progress updates doc-type: 'banner' diff --git a/docs/guidelines/language/time-related-messages.mdx b/docs/guidelines/language/time-related-messages.mdx index f7fef90b9..63c2a7f47 100644 --- a/docs/guidelines/language/time-related-messages.mdx +++ b/docs/guidelines/language/time-related-messages.mdx @@ -26,7 +26,7 @@ Upcoming system update: 22 August -### Use the user's time zone when providing any kind of time indication. +### Use the user’s time zone when providing any kind of time indication.
@@ -269,10 +269,10 @@ Pause
-## Dos and Don'ts +## 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 +* 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 index 8a0f18b7f..9c9ce73e4 100644 --- a/docs/guidelines/language/toast-messages.mdx +++ b/docs/guidelines/language/toast-messages.mdx @@ -22,9 +22,29 @@ Although always short, toast messages vary in length and complexity: | 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 | +| **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 diff --git a/docs/guidelines/language/tooltips.mdx b/docs/guidelines/language/tooltips.mdx index 34b8c3efc..9410157c3 100644 --- a/docs/guidelines/language/tooltips.mdx +++ b/docs/guidelines/language/tooltips.mdx @@ -134,8 +134,8 @@ Edit (as text) Tooltip: Edit * 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 +* 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 index 5578c8f72..942a36d55 100644 --- a/docs/guidelines/language/warning-messages.mdx +++ b/docs/guidelines/language/warning-messages.mdx @@ -126,7 +126,7 @@ Press reset to proceed. -### Avoid using all uppercase text as it can be difficult to read and may seem like we're shouting. +### Avoid using all uppercase text as it can be difficult to read and may seem like we’re shouting.
@@ -134,13 +134,13 @@ WARNING!! FAILURE! IMMEDIATE ACTION REQUIRED!!
-## Dos and Don'ts +## 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 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…?" +* Don’t use "please" with the call to action or options +* Don’t use patronizing questions such as "Are you sure…?" ## Related From ef5ecc9b4efbc1d1bb7b84456ad4838c061504e4 Mon Sep 17 00:00:00 2001 From: Susanne254 Date: Mon, 19 Jan 2026 10:55:38 +0100 Subject: [PATCH 4/6] doc/improved formatting formatting does and don'ts for progress updates added --- .../language/non-critical-information-messages.mdx | 10 +++++----- docs/guidelines/language/progress-updates.mdx | 14 ++++++++++---- docs/guidelines/language/time-related-messages.mdx | 4 ++-- docs/guidelines/language/toast-messages.mdx | 6 +++--- docs/guidelines/language/tooltips.mdx | 2 +- docs/guidelines/language/warning-messages.mdx | 4 ++-- 6 files changed, 23 insertions(+), 17 deletions(-) diff --git a/docs/guidelines/language/non-critical-information-messages.mdx b/docs/guidelines/language/non-critical-information-messages.mdx index 593ff54e4..3d4d020a3 100644 --- a/docs/guidelines/language/non-critical-information-messages.mdx +++ b/docs/guidelines/language/non-critical-information-messages.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 99 Sidebar_lable: Non-critical information messages title: Non-critical information messages doc-type: 'banner' @@ -37,7 +37,7 @@ System backup completed at 21:00.
-Don't worry! We'll make sure your backup is complete before your morning coffee on Friday! +Don’t worry! We’ll make sure your backup is complete before your morning coffee on Friday!
@@ -147,7 +147,7 @@ Line 3 shift schedule changed. See what's new.
-🔄 Line 3 shift schedule updated. 👉 See what's new. +🔄 Line 3 shift schedule updated. 👉 See what’s new.
@@ -155,8 +155,8 @@ Line 3 shift schedule changed. See what's new. * 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 +* 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 index 7b5dcf80b..d716cea63 100644 --- a/docs/guidelines/language/progress-updates.mdx +++ b/docs/guidelines/language/progress-updates.mdx @@ -14,10 +14,10 @@ description: While some companies use humorous text like "Chopping the onions…
-Downloading assets... +Downloading assets…
-Downloading Assets... +Downloading Assets…
@@ -55,7 +55,7 @@ Will be loading…
-Downloading assets... +Downloading assets…
File loading… @@ -169,8 +169,14 @@ 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. +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 index 63c2a7f47..d23698500 100644 --- a/docs/guidelines/language/time-related-messages.mdx +++ b/docs/guidelines/language/time-related-messages.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 98 sidebar_label: Time-related messages title: Time-related messages doc-type: 'banner' @@ -202,7 +202,7 @@ Due to the size of the migration, we have no idea when it will finish.
-The application will not be available during the update. We'll notify you when it's ready. +The application will not be available during the update. We’ll notify you when it’s ready.
diff --git a/docs/guidelines/language/toast-messages.mdx b/docs/guidelines/language/toast-messages.mdx index 9c9ce73e4..c8eedfbc9 100644 --- a/docs/guidelines/language/toast-messages.mdx +++ b/docs/guidelines/language/toast-messages.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 97 sidebar_label: Toast messages title: Toast messages doc-type: 'banner' @@ -212,8 +212,8 @@ Connection established successfully * 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 +* 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 index 9410157c3..bd671b49d 100644 --- a/docs/guidelines/language/tooltips.mdx +++ b/docs/guidelines/language/tooltips.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 77 sidebar_label: Tooltips title: Tooltips doc-type: 'banner' diff --git a/docs/guidelines/language/warning-messages.mdx b/docs/guidelines/language/warning-messages.mdx index 942a36d55..eda09fd8f 100644 --- a/docs/guidelines/language/warning-messages.mdx +++ b/docs/guidelines/language/warning-messages.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 55 sidebar_label: Warning messages title: Warning messages doc-type: 'banner' @@ -46,7 +46,7 @@ Temperature warning
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. +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
From c90263bb5aea3e8d8ac075ded3eec51bd3516279 Mon Sep 17 00:00:00 2001 From: varun srinivasa Date: Thu, 22 Jan 2026 15:46:18 +0530 Subject: [PATCH 5/6] updated warning message content --- .env.production | 1 + .gemini/styleguide.md | 18 ++- docs/components/input-time/guide.mdx | 6 +- docs/components/progress-indicator/guide.md | 6 +- docs/components/time-picker/guide.mdx | 6 +- .../essentials/wording-terms.mdx | 82 ++++++------ docs/guidelines/language/basics.md | 18 +-- docs/guidelines/language/best-practices.md | 120 ++++++++++++++++++ .../language/dialogs-and-buttons.md | 12 +- docs/guidelines/language/error-messages.md | 16 +-- .../language/formatting/addresses.mdx | 58 ++++----- docs/guidelines/language/formatting/date.mdx | 76 +++++------ .../language/formatting/measurements.mdx | 72 +++++------ docs/guidelines/language/formatting/money.mdx | 32 ++--- .../language/formatting/names-titles.mdx | 50 ++++---- .../language/formatting/numbers.mdx | 104 +++++++-------- .../language/formatting/software-versions.mdx | 50 ++++---- .../language/formatting/timezones.mdx | 96 +++++++------- .../language/frequent-app-functions.md | 32 ++--- .../language/grammar-and-vocabulary.md | 36 +++--- .../language/main-menu-functions.md | 24 ++-- docs/guidelines/language/punctuation.md | 18 +-- docs/home/installation/angular.md | 12 ++ docs/home/migration/4_0_0/index.md | 10 +- docs/home/overview.md | 2 +- docs/home/support/faq.md | 58 ++++++++- docs/icons/developing-with-icons.md | 20 +++ docusaurus.config.ts | 2 +- package.json | 4 +- pnpm-lock.yaml | 22 ++-- src/components/Accordion/index.tsx | 1 + src/components/GuidingPrinciples/index.tsx | 10 +- src/scss/components/_dosAndDonts.scss | 9 +- 33 files changed, 656 insertions(+), 427 deletions(-) create mode 100644 docs/guidelines/language/best-practices.md diff --git a/.env.production b/.env.production index 8974c1fdf..877f80d15 100644 --- a/.env.production +++ b/.env.production @@ -1,4 +1,5 @@ DOCS_BRANCH='main' DOCS_BRANCH_TYPE='branch' # Check if the branch is a pull request DOCS_PR_NUMBER='' + BRAND_VERSION=1.0.0 \ No newline at end of file diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 02a4cf42c..8f60291ab 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -11,8 +11,12 @@ Typical structure: 1. Basic -2. Further examples +2. (Further examples) 3. API for {component} + - Properties + - Events (optional) + - Slots (optional) +Note that the headings should be like that. ## Guidelines for guide.md files @@ -30,6 +34,8 @@ Typical structure: - Apostrophe: Always use the symbol ’ (U+2019, "right single quotation mark"), not ' - Use sentence case always: Start with a big letter and then only proper nouns are capitalized. +- Avoid oxford comma whenever possible, e.g. before "and" and "or". For complex sentences where it's needed for understanding, try to simplify it. +- Ellipses: always use the symbol … (Unicode U+2026 instead of adding three full stops. Mac Option+/Windows ALT+0133). ### File structure @@ -70,6 +76,16 @@ Note that **not** all sections need to be filled out, e.g. if there are no varia - Naming of options: Stick to spelling of code section but avoid technical jargon, e.g. if code is "i18nPlainText", in description write "Plain text" - The option name and the colon is bold, e.g. "**Label:**" +#### Behavior in context section + +- Often have following bullet points: + - Interaction + - Overflow + - Alignment + - Responsiveness + - Placement +- Title is "Behavior in context" (not "Behavior") + #### Dos and Don’ts section - The title is "Dos and Don’ts" diff --git a/docs/components/input-time/guide.mdx b/docs/components/input-time/guide.mdx index 293403503..e944f26c8 100644 --- a/docs/components/input-time/guide.mdx +++ b/docs/components/input-time/guide.mdx @@ -56,8 +56,8 @@ Time input has five states: Default, hover, disabled, read-only and focused. ## Dos and Don’ts -
-
+
+
- Do use consistent time formats throughout the application to avoid confusion - Do add helper text to clarify the time format being used @@ -65,7 +65,7 @@ Time input has five states: Default, hover, disabled, read-only and focused. - Do consider localization to adapt time formats to local conventions
-
+
- Don’t use the same input for start and end times, instead separate them diff --git a/docs/components/progress-indicator/guide.md b/docs/components/progress-indicator/guide.md index e8dfd014a..d6eab7e69 100644 --- a/docs/components/progress-indicator/guide.md +++ b/docs/components/progress-indicator/guide.md @@ -52,8 +52,8 @@ For more information about writing effective helper texts or labels, see our [UX ## Dos and Don’ts -
-
+
+
- Do use progress indicators consistently for similar processes - Do use progress indicators for determinate processes where progress can be measured (otherwise use [spinners](../spinner/index.mdx)) @@ -61,7 +61,7 @@ For more information about writing effective helper texts or labels, see our [UX - Do keep your slot content short, especially for the centered alignment (use helper texts and labels for lengthier content)
-
+
- Don't use progress indicators for operations shorter than one second - Don't only indicate progress completion with the indicator without clear task messages, e.g. success toasts or displaying the loaded content diff --git a/docs/components/time-picker/guide.mdx b/docs/components/time-picker/guide.mdx index d6da7ad9f..aa4415747 100644 --- a/docs/components/time-picker/guide.mdx +++ b/docs/components/time-picker/guide.mdx @@ -40,15 +40,15 @@ An individual time item of a time picker has five states: Default, hover, active ## Dos and Don’ts -
-
+
+
- Do use the time picker to ensure accurate time selection (we recommend to use [time inputs](../input-time) for that reason) - Do provide clear instructions and labels for users - Do ensure the time picker is accessible via keyboard
-
+
- Don’t clutter the time picker with unnecessary options diff --git a/docs/guidelines/conversational-design/essentials/wording-terms.mdx b/docs/guidelines/conversational-design/essentials/wording-terms.mdx index cd55f13c9..9ba430d17 100644 --- a/docs/guidelines/conversational-design/essentials/wording-terms.mdx +++ b/docs/guidelines/conversational-design/essentials/wording-terms.mdx @@ -29,8 +29,8 @@ Use any of the five messages depending on your product and use case. - **With username:** Hello Felix, how can I help you today? - **With product and username:** Hello Sara, I'm  [Copilot name]. How can I help you today? -
-
+
+
- Well, hello! I’m your friendly chatbot. - Welcome to chatbot. State your issue now. @@ -43,15 +43,15 @@ Use any of the five messages depending on your product and use case. Use these universal, non-specific options to encourage solution and technology-focused input. Avoid generic, open placeholders that encourage off-topic queries. -
-
+
+
- Enter your query here… - Enter a command, question or topic… - Enter a command, question or topic to begin…
-
+
- Ask me anything… - Start typing… @@ -62,8 +62,8 @@ Use these universal, non-specific options to encourage solution and technology-f Use alternative placeholder text when your chatbot has a single use case. -
-
+
+
- Search technical documentation… - Enter error code… @@ -76,13 +76,13 @@ Use alternative placeholder text when your chatbot has a single use case. Always use “generate” as the main progress indicator verb with ellipses (...). -
-
+
+
- Generating…
-
+
- Generating response - Creating response… @@ -92,14 +92,14 @@ Always use “generate” as the main progress indicator verb with ellipses (... Use “generate” to match the action verb to stop the chatbot responding or ask the chatbot to continue responding without ellipses. -
-
+
+
- Stop generating - Continue generating
-
+
- Stop generating… - Continue generating… @@ -111,8 +111,8 @@ Use “generate” to match the action verb to stop the chatbot responding or as Use a tooltip on hover to clarify any recording limitations and tell users how to stop recording. -
-
+
+
- Click to start and stop voice recording. - Click to start and stop voice recording (max 2 minutes). @@ -122,13 +122,13 @@ Use a tooltip on hover to clarify any recording limitations and tell users how t Use “Recording…” as feedback to show the feature is working. -
-
+
+
- Recording…
-
+
- I’m listening… @@ -139,14 +139,14 @@ Use “Recording…” as feedback to show the feature is working. Use thumbs up and down icons to request feedback. -
-
+
+
- Thumbs up icon () - Thumbs down icon ()
-
+
- Helpful - Not helpful @@ -158,8 +158,8 @@ Use thumbs up and down icons to request feedback. Use “last” instead of “previous” and “prior” for time-related terminology in chat history. -
-
+
+
- Today - Yesterday @@ -168,7 +168,7 @@ Use “last” instead of “previous” and “prior” for time-related termin - Older
-
+
- Previous 7 days - Prior week @@ -188,8 +188,8 @@ Use “last” instead of “previous” and “prior” for time-related termin Use the following action wording for consistency within all our chatbots. -
-
+
+
- New chat - Send @@ -207,7 +207,7 @@ Use the following action wording for consistency within all our chatbots. - Close chat window
-
+
- Clear chat - Submit @@ -235,13 +235,13 @@ Book webinar Use “sources” as the text label to indicate where the generated information is from. -
-
+
+
- Sources
-
+
- Resources - Sources and references @@ -255,8 +255,8 @@ Avoid mixing terms (resources, sources) and instead label the source format, e.g Use clear wording to differentiate between multiple bots when displaying output. -
-
+
+
- Responses generated by agent X - Responses generated by: agent X (with agent selection dropdown) @@ -268,15 +268,15 @@ Use clear wording to differentiate between multiple bots when displaying output. Avoid punctuation, such as exclamation marks for buttons, hover text, titles and tags. -
-
+
+
- Show more - Send - Stop
-
+
- Show more! - Send? @@ -290,8 +290,8 @@ Most problematic wording involves the bot expressing itself as a human with huma Use “generating” not “thinking” as chatbots don’t perform cognitive processes. -
-
+
+
- Thinking… - Thinking about the best response… @@ -301,8 +301,8 @@ Use “generating” not “thinking” as chatbots don’t perform cognitive pr Avoid prompting emotional language like “I’m afraid…” in industrial chatbots. -
-
+
+
- I’m afraid that I can’t help you right now as I’m assessing the data. - I understand what you mean. @@ -312,8 +312,8 @@ Avoid prompting emotional language like “I’m afraid…” in industrial chat Avoid technical, robotic phrases like “Please stand by…” as these are outdated, passive and unhelpful. -
-
+
+
- Please stand by while I process your request. - Please wait while I prepare a response. diff --git a/docs/guidelines/language/basics.md b/docs/guidelines/language/basics.md index 2184d0ef6..1def41618 100644 --- a/docs/guidelines/language/basics.md +++ b/docs/guidelines/language/basics.md @@ -36,8 +36,8 @@ description: "Dive into the fundamental principles of UX writing, where you'll l - Avoid using negative contractions as they can appear too informal -
-
+
+
- their, them, theirs, salesperson - Welcome to this application @@ -46,7 +46,7 @@ description: "Dive into the fundamental principles of UX writing, where you'll l - you’ll, we’ve
-
+
- his, hers, him, salesman - Hey there! @@ -79,8 +79,8 @@ description: "Dive into the fundamental principles of UX writing, where you'll l - Capitalize named app functions and UI elements: Go to Settings, Allocate users in User management, Press OK -
-
+
+
- Go to Settings - Press OK @@ -88,7 +88,7 @@ description: "Dive into the fundamental principles of UX writing, where you'll l - For more information, see Siemens Industry Online Support.
-
+
- Go To Settings - Press OK @@ -100,8 +100,8 @@ description: "Dive into the fundamental principles of UX writing, where you'll l ## Common UX wording mistakes -
-
+
+
- time zone - log file @@ -117,7 +117,7 @@ description: "Dive into the fundamental principles of UX writing, where you'll l - 34 million
-
+
- timezone - logfile diff --git a/docs/guidelines/language/best-practices.md b/docs/guidelines/language/best-practices.md new file mode 100644 index 000000000..745ed1fb1 --- /dev/null +++ b/docs/guidelines/language/best-practices.md @@ -0,0 +1,120 @@ +--- +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/dialogs-and-buttons.md b/docs/guidelines/language/dialogs-and-buttons.md index 7e11b7a73..75b6a2351 100644 --- a/docs/guidelines/language/dialogs-and-buttons.md +++ b/docs/guidelines/language/dialogs-and-buttons.md @@ -24,15 +24,15 @@ description: 'Discover guidelines for writing dialogs and button labels to ensur - Only use ‘OK’ as an option if you cannot find an appropriate verb -
-
+
+
- Title: Add user / Buttons: Cancel, Add - Title: Delete file / Buttons: Cancel, Delete - Title: Edit details / Buttons: Cancel, Save
-
+
- Title: Add user / Buttons: Cancel, OK - Title: Are you sure / Buttons: Cancel, Delete @@ -47,13 +47,13 @@ description: 'Discover guidelines for writing dialogs and button labels to ensur - Primary actions can either be positive (Send, Save) or negative (Delete) -
-
+
+
- Cancel, Save
-
+
- Save, Cancel diff --git a/docs/guidelines/language/error-messages.md b/docs/guidelines/language/error-messages.md index d4ff0bffb..a19bda734 100644 --- a/docs/guidelines/language/error-messages.md +++ b/docs/guidelines/language/error-messages.md @@ -44,15 +44,15 @@ description: 'Learn how to write error messages, warnings, and notifications tha - An error message alerts user of a problem that exists and must be addressed -
-
+
+
- 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. @@ -71,8 +71,8 @@ description: 'Learn how to write error messages, warnings, and notifications tha - A warning message alerts users of a condition that may cause a problem in the future -
-
+
+
- Title: You have not saved all documents - Explanation: You have to save all documents @@ -85,14 +85,14 @@ description: 'Learn how to write error messages, warnings, and notifications tha - Notifications are informative and no actions are required from the user -
-
+
+
- Access Point 2 is connected. - Changes are saved automatically.
-
+
- Access Point connection failed. Try again. - No rows to show. diff --git a/docs/guidelines/language/formatting/addresses.mdx b/docs/guidelines/language/formatting/addresses.mdx index c585bf1b9..91e8e8ed8 100644 --- a/docs/guidelines/language/formatting/addresses.mdx +++ b/docs/guidelines/language/formatting/addresses.mdx @@ -12,13 +12,13 @@ description: In industrial applications, writing addresses clearly and consisten Use specific text field labels for different parts of the address. -
-
+
+
- Number | Street | State | ZIP code | Country
-
+
- Address line 1, Address line 2, Address line 3 @@ -27,8 +27,8 @@ Use specific text field labels for different parts of the address. Ensure special and international characters are accepted for international addresses. -
-
+
+
- 12-142 Elm St - #8C (unit or suite number) @@ -41,8 +41,8 @@ Ensure special and international characters are accepted for international addre Use commas to separate names, streets, states and countries to prevent errors when there is only one text field. -
-
+
+
- John Doe, 123 Maple Street, Springfield, California, 62704, United States @@ -53,8 +53,8 @@ Use commas to separate names, streets, states and countries to prevent errors wh Use a comma between cities and states and other regions, e.g. cities within Cantons. -
-
+
+
- Springfield, Illinois - Munich, Bavaria @@ -65,13 +65,13 @@ Use a comma between cities and states and other regions, e.g. cities within Cant Use capital letters for abbreviated states without a full stop. -
-
+
+
- IL
-
+
- Il. @@ -82,15 +82,15 @@ Use capital letters for abbreviated states without a full stop. Use the correct regional format for ZIP codes, including any necessary spaces or hyphens. -
-
+
+
- 90210 (US) - SW1A 2AA (UK) - 123-4567 (Japan)
-
+
- 90 21 0 (US) - SW1A2AA (UK) @@ -119,8 +119,8 @@ Use common abbreviations for street types without full stops to avoid visual clu Add floor numbers either before or after the word and note different international floor counting systems. -
-
+
+
- Floor 3 - 3rd floor @@ -129,7 +129,7 @@ Add floor numbers either before or after the word and note different internation - Floor G (international)
-
+
- Floor 3rd @@ -138,8 +138,8 @@ Add floor numbers either before or after the word and note different internation Use numbers and letters after buildings, suites, apartments, rooms and floors. -
-
+
+
- Building A - Building part @@ -154,8 +154,8 @@ Use numbers and letters after buildings, suites, apartments, rooms and floors. Use "Line" or add a description, e.g. "Assembly line" and use "Zone" or "Area" for larger facilities. -
-
+
+
- Assembly line 2 - Line B @@ -169,8 +169,8 @@ Use "Line" or add a description, e.g. "Assembly line" and use "Zone" or "Area" f Use clear labels when possible with "Latitude" first, then "Longitude". -
-
+
+
- Latitude: 48.14389° | Longitude: 11.57633° @@ -179,8 +179,8 @@ Use clear labels when possible with "Latitude" first, then "Longitude". Use plus (+), minus (-), a comma and a space when adding both in one text field. -
-
+
+
- +48.14389°, +11.57633° @@ -189,13 +189,13 @@ Use plus (+), minus (-), a comma and a space when adding both in one text field. Use the correct degree symbol (Unicode U+00B0). -
-
+
+
- °
-
+
- o diff --git a/docs/guidelines/language/formatting/date.mdx b/docs/guidelines/language/formatting/date.mdx index 0130364e9..2150dd98f 100644 --- a/docs/guidelines/language/formatting/date.mdx +++ b/docs/guidelines/language/formatting/date.mdx @@ -14,14 +14,14 @@ description: Accurate dates and times are essential in industrial settings, serv Use the ISO 8601 date and time format standards when backend localization is not possible. -
-
+
+
- 2025-04-08 (April 8, 2025) - 14:30:00 (24-hour format)
-
+
- 2025/04/08 - 2:30 PM @@ -31,8 +31,8 @@ Use the ISO 8601 date and time format standards when backend localization is not Add tooltips or in-line text to support users and clarify which format is being used. -
-
+
+
- YYYY-MM-DD - 24-hour format @@ -44,13 +44,13 @@ Add tooltips or in-line text to support users and clarify which format is being Avoid adding unnecessary punctuation to abbreviated dates. -
-
+
+
- Jan
-
+
- Jan. @@ -61,13 +61,13 @@ Avoid adding unnecessary punctuation to abbreviated dates. Write out full dates using commas to separate elements within longer texts and paragraphs. -
-
+
+
- Monday, January 12, 2025
-
+
- Monday: January 12th: 2025 @@ -76,14 +76,14 @@ Write out full dates using commas to separate elements within longer texts and p Write out dates with the abbreviated form using dashes (hyphens) instead of slashes for better readability. -
-
+
+
- Dec-26-2025 - Apr-09-2025
-
+
- Apr/09/2025 - Apr 09/2025 @@ -93,13 +93,13 @@ Write out dates with the abbreviated form using dashes (hyphens) instead of slas Write dates in tables using abbreviated months to avoid confusion and the need for further tooltips or explanation. -
-
+
+
- Apr-09
-
+
- 04-09 @@ -108,13 +108,13 @@ Write dates in tables using abbreviated months to avoid confusion and the need f Avoid using "st" (as in 1st) or "th" (as in 5th) for a cleaner user interface. -
-
+
+
- Monday, January 12, 2025
-
+
- Monday, January 12th, 2025 @@ -125,14 +125,14 @@ Avoid using "st" (as in 1st) or "th" (as in 5th) for a cleaner user interface. Start all days with a capital letter. Use three-letter abbreviations without punctuation when there isn’t enough space. -
-
+
+
- Monday, Tuesday, Wednesday, etc. - Mon
-
+
- Mon. @@ -143,13 +143,13 @@ Start all days with a capital letter. Use three-letter abbreviations without pun Avoid calendar weeks (CW) whenever possible as these are very specific to certain regions. -
-
+
+
- Week 15 (April 7 – April 13, 2025)
-
+
- CW 15 (15th week of the year) - CW 15/2025 (15th calendar week year 2025) @@ -162,14 +162,14 @@ Avoid calendar weeks (CW) whenever possible as these are very specific to certai Start all months with a capital letter. Use abbreviations without punctuation when there isn’t enough space. -
-
+
+
- January, February, March, etc. - Jan
-
+
- Jan. @@ -180,13 +180,13 @@ Start all months with a capital letter. Use abbreviations without punctuation wh Use the four-digit format and never abbreviate in industrial applications. -
-
+
+
- 2023
-
+
- ’23 @@ -197,13 +197,13 @@ Use the four-digit format and never abbreviate in industrial applications. Use plural -s when talking about decades. -
-
+
+
- 1980s
-
+
- 1980’s @@ -214,13 +214,13 @@ Use plural -s when talking about decades. Use "th" and "nd" to reference centuries with ordinal numbers (sequencing) without using superscript. -
-
+
+
- Welcome to the 21st century of industrial innovation! Our app uses AI to deliver efficiency in your operations.
-
+
- Welcome to the 21st century of industrial innovation! Our app uses AI to deliver efficiency in your operations. diff --git a/docs/guidelines/language/formatting/measurements.mdx b/docs/guidelines/language/formatting/measurements.mdx index 412a6608e..dcea5104d 100644 --- a/docs/guidelines/language/formatting/measurements.mdx +++ b/docs/guidelines/language/formatting/measurements.mdx @@ -12,14 +12,14 @@ description: In industrial settings, accurate measurements are vital for ensurin Use the same measurement format and style throughout your user interface and consider localization conflicts. Write out measurement abbreviations in full if there is any chance users will not understand. -
-
+
+
- British Thermal Unit (BTU): 1 - Nautical Mile (nmi): 8
-
+
- BTU: 1 - nmi: 8 @@ -29,8 +29,8 @@ Use the same measurement format and style throughout your user interface and con Avoid line breaks between the value and the unit by using a protected (non-breaking) space. Use the singular when talking about a specific number and in abbreviations. Use lower case as the default for most unit abbreviations. -
-
+
+
- 200 kg - 20 kg @@ -38,7 +38,7 @@ Avoid line breaks between the value and the unit by using a protected (non-break - 200 g
-
+
- 200kg - 20 kgs @@ -50,14 +50,14 @@ Avoid line breaks between the value and the unit by using a protected (non-break Use upper case for unit abbreviations named after people and lower case when the abbreviation is written out in full. -
-
+
+
- 6 volts - 6 V
-
+
- 6 Volts - 6 v @@ -77,14 +77,14 @@ Use upper case for unit abbreviations named after people and lower case when the Use a slash to show how compound units are divided for clarity. -
-
+
+
- km/h - A/m
-
+
- km-h @@ -95,15 +95,15 @@ Use a slash to show how compound units are divided for clarity. Use "L" (liter) instead of lower case "l" only if there is any doubt users will confuse it with "1". -
-
+
+
- 2 L - 11 L - 2 l
-
+
- 11 l @@ -112,8 +112,8 @@ Use "L" (liter) instead of lower case "l" only if there is any doubt users will Use upper case "B" to abbreviate byte and lower case "b" to abbreviate bit. Use M for mega, G for giga and T for tera to distinguish from m (milli), g (gram) and t (ton). -
-
+
+
- 120 MB (megabytes) - 120 Mb (megabits) @@ -122,7 +122,7 @@ Use upper case "B" to abbreviate byte and lower case "b" to abbreviate bit. Use - 1 THz
-
+
- 1 T @@ -133,14 +133,14 @@ Use upper case "B" to abbreviate byte and lower case "b" to abbreviate bit. Use Use superscript to indicate cubed measurements. -
-
+
+
- m³ - cm³
-
+
- m3 - cm3 @@ -150,13 +150,13 @@ Use superscript to indicate cubed measurements. Use the plain text caret symbol (^) when superscript is not possible in your application. -
-
+
+
- m^3
-
+
- m3 @@ -165,13 +165,13 @@ Use the plain text caret symbol (^) when superscript is not possible in your app Use mcg to abbreviate microgram instead of the Greek letter mu (μ). -
-
+
+
- 1000 mcg
-
+
- 1000 μg @@ -182,13 +182,13 @@ Use mcg to abbreviate microgram instead of the Greek letter mu (μ). Use a non-breaking space (Ctrl + Shift + Space) between the number and the degree symbol. -
-
+
+
- 23 °C
-
+
- 23°C - 23° C @@ -198,13 +198,13 @@ Use a non-breaking space (Ctrl + Shift + Space) between the number and the degre Use the degree symbol (°) before the initial letter of the temperature scale without a space. -
-
+
+
- 23 °C
-
+
- 23 C° @@ -215,15 +215,15 @@ Use the degree symbol (°) before the initial letter of the temperature scale wi Use "px" in lower case to abbreviate pixels with a space for readability without periods after px, pt and dpi (dots per inch). -
-
+
+
- 45 px - 1280 x 780 px - 4 pt
-
+
- 45PX - 1280x780px diff --git a/docs/guidelines/language/formatting/money.mdx b/docs/guidelines/language/formatting/money.mdx index cd5072283..4d971d5b7 100644 --- a/docs/guidelines/language/formatting/money.mdx +++ b/docs/guidelines/language/formatting/money.mdx @@ -13,13 +13,13 @@ description: 'Understanding money and currency is important for designing user i Place the currency symbol before the amount in English and use the same formatting style throughout. -
-
+
+
- £320
-
+
- 320£ - £320/£320.00/Three hundred and twenty pounds/320 pounds (mixed styles) @@ -29,14 +29,14 @@ Place the currency symbol before the amount in English and use the same formatti Use decimal points for cents or smaller units within English user interfaces. -
-
+
+
- €999.50 - $400,456.50
-
+
- €999,50 - $400.456,50 @@ -46,13 +46,13 @@ Use decimal points for cents or smaller units within English user interfaces. Never add a space between the currency symbol and the amount. -
-
+
+
- $100
-
+
- $ 100 @@ -61,13 +61,13 @@ Never add a space between the currency symbol and the amount. Use the ISO currency code before the number without a space. -
-
+
+
- USD400
-
+
- 300USD @@ -76,8 +76,8 @@ Use the ISO currency code before the number without a space. Use numbers and currency symbols within the UI when talking about marketing and pricing. -
-
+
+
- Thank you. Your payment of $50 has been processed. - Invest in our new soft sensors for $6,000 to boost your production efficiency. @@ -89,8 +89,8 @@ Use numbers and currency symbols within the UI when talking about marketing and Write out the full word in formal and legal documents. -
-
+
+
- The total amount shall not exceed four thousand dollars. diff --git a/docs/guidelines/language/formatting/names-titles.mdx b/docs/guidelines/language/formatting/names-titles.mdx index ada7a6617..0f1acd01c 100644 --- a/docs/guidelines/language/formatting/names-titles.mdx +++ b/docs/guidelines/language/formatting/names-titles.mdx @@ -14,14 +14,14 @@ description: Accurate and consistent use of names and titles is essential for ma Use "First name" and "Last name" in forms and ensure text fields accept names with only one letter. -
-
+
+
- First name - Last name
-
+
- Surname - Full name @@ -33,8 +33,8 @@ Use "First name" and "Last name" in forms and ensure text fields accept names wi Use first names to welcome users to applications. -
-
+
+
- Welcome Susanne @@ -45,13 +45,13 @@ Use first names to welcome users to applications. Avoid gendered titles unless absolutely necessary for your application. Use "Title", not "Honorific", to describe words such as Mr. and Mrs. Note that not all cultures have equivalents to some titles used in the United States, such as Ms. -
-
+
+
- [ Mr. | Ms. | Mx. | None | Other | Prefer not to say]
-
+
- [ Mr. | Mrs. | Miss | Ms. ] @@ -62,13 +62,13 @@ Avoid gendered titles unless absolutely necessary for your application. Use "Tit Use full stops for all abbreviated titles in American English. -
-
+
+
- Mr. Smith
-
+
- Mr Smith @@ -77,15 +77,15 @@ Use full stops for all abbreviated titles in American English. Use titles with full names or surnames but do not use titles when addressing users with only their first name. -
-
+
+
- Mrs. Turner - Mrs. Jennifer Turner - Jennifer
-
+
- Mrs. Jennifer @@ -94,8 +94,8 @@ Use titles with full names or surnames but do not use titles when addressing use Use full stops for all abbreviated professional titles in American English. -
-
+
+
- Dr. - Prof. @@ -108,15 +108,15 @@ Use full stops for all abbreviated professional titles in American English. Use capital letters for corporate titles especially with the name and use capital letters for corporate title acronyms. -
-
+
+
- Chief Financial Officer Teresa Lopez - Teresa Lopez (Chief Financial Officer) - Teresa Lopez (CFO)
-
+
- chief financial officer Teresa Lopez @@ -125,15 +125,15 @@ Use capital letters for corporate titles especially with the name and use capita Use lower case when titles are used generically (without a name) and separate titles from names with a comma. -
-
+
+
- The chief financial officer for the company will hold a press conference tomorrow. - The project manager needs to schedule maintenance. - Carol Jones, Chairwoman of the Supervisory Board, spoke at the press conference yesterday.
-
+
- Call the Manager. @@ -142,13 +142,13 @@ Use lower case when titles are used generically (without a name) and separate ti Always capitalize Managing Board and use lower case for "member". -
-
+
+
- John Smith is a member of the Managing Board.
-
+
- John Smith is a member of the managing board. diff --git a/docs/guidelines/language/formatting/numbers.mdx b/docs/guidelines/language/formatting/numbers.mdx index d6060cbfa..62418a06a 100644 --- a/docs/guidelines/language/formatting/numbers.mdx +++ b/docs/guidelines/language/formatting/numbers.mdx @@ -14,13 +14,13 @@ description: In industrial settings, numbers and percentages are key to tracking Write "Number" or "number" when there is enough space within the user interface. -
-
+
+
- Number
-
+
- Num. @@ -29,13 +29,13 @@ Write "Number" or "number" when there is enough space within the user interface. Use "No." as an abbreviation for number with a period and without a space. -
-
+
+
- No.6
-
+
- Num.6 @@ -44,13 +44,13 @@ Use "No." as an abbreviation for number with a period and without a space. Avoid using the # symbol with numbers. -
-
+
+
- Number 6
-
+
- #6 @@ -59,13 +59,13 @@ Avoid using the # symbol with numbers. Write numbers as digits, such as "9" instead of "nine", in industrial user interfaces. -
-
+
+
- We’ve released 3 new features this month.
-
+
- We’ve released three new features this month. @@ -74,13 +74,13 @@ Write numbers as digits, such as "9" instead of "nine", in industrial user inter Write numbers with four digits and more with commas to separate thousands, millions, etc. in American English. -
-
+
+
- 100,000
-
+
- 100.000 @@ -91,8 +91,8 @@ Write numbers with four digits and more with commas to separate thousands, milli Use en dashes (–) instead of hyphens (-) for ranges. -
-
+
+
- 10–0 - The shipment weighs 50–75kg @@ -102,13 +102,13 @@ Use en dashes (–) instead of hyphens (-) for ranges. Write out the unit only once in ranges. -
-
+
+
- The temperature fluctuated between 20–25°C
-
+
- The temperature fluctuated between 20°C–25°C @@ -117,13 +117,13 @@ Write out the unit only once in ranges. Use the minus hyphen for negative numbers which is better aligned than a normal hyphen (Unicode U+2212). -
-
+
+
- -12
-
+
- —12 @@ -132,8 +132,8 @@ Use the minus hyphen for negative numbers which is better aligned than a normal Use either "to" or separate text fields for ranges with minus numbers for readability. -
-
+
+
- -12 to -15°C - Min temp (C): -12° / Max temp (C): -15° @@ -145,15 +145,15 @@ Use either "to" or separate text fields for ranges with minus numbers for readab Write decimals using a period (.) to separate the whole number from the fractional part in American English. -
-
+
+
- 0.5 - 5,245.15 - 2.5 million
-
+
- 0,5 - 5.245,15 @@ -167,15 +167,15 @@ Write decimals using a period (.) to separate the whole number from the fraction Use "K" as an abbreviation for thousand, "M" for million, and "B" for billion without a period or space. Consider variations in other languages and never use abbreviations when there is doubt. -
-
+
+
- 34K - 34M - 34B
-
+
- 34 k - 34 mil @@ -186,14 +186,14 @@ Use "K" as an abbreviation for thousand, "M" for million, and "B" for billion wi Use the singular "million" when talking about a specific number. -
-
+
+
- 34 million - Our system processes one million connections.
-
+
- 34 millions - Our system processes one millions connections. @@ -203,8 +203,8 @@ Use the singular "million" when talking about a specific number. Use the plural "millions" when talking about an unspecific number. -
-
+
+
- Our goal is to deliver software to millions of happy users worldwide. @@ -213,13 +213,13 @@ Use the plural "millions" when talking about an unspecific number. Write out numbers in the millions and billions ("one million" instead of "1,000,000") in longer texts and paragraphs. -
-
+
+
- We have over one million users worldwide.
-
+
- We have over 1,000,000 users worldwide. @@ -228,8 +228,8 @@ Write out numbers in the millions and billions ("one million" instead of "1,000, Use numerals for numbers in the millions for dates, addresses, units of measurement, currencies and percentages. -
-
+
+
- The temperature can reach 1,000,000°C in the pod. - The cargo ship can carry up to 1,000,000kg. @@ -244,13 +244,13 @@ Use numerals for numbers in the millions for dates, addresses, units of measurem Use the % symbol instead of writing out "percentage" within the user interface to save space. -
-
+
+
- 10%
-
+
- 10 percent @@ -259,13 +259,13 @@ Use the % symbol instead of writing out "percentage" within the user interface t Use % after the number and without a space. -
-
+
+
- 10%
-
+
- %10 @@ -276,8 +276,8 @@ Use % after the number and without a space. Separate phone numbers into groups for clarity when backend localization or separate fields are not possible. -
-
+
+
- Country code, area code, numbers in groupings of 3 or 4 - 0044, 208, 899 7032 @@ -287,15 +287,15 @@ Separate phone numbers into groups for clarity when backend localization or sepa Use the plus symbol (+) or "00" before the country code and show extension numbers with a hyphen. -
-
+
+
- +49 123 456 7890 - 0049 123 456 7890 - 0123 456 7890-12
-
+
- 0123 456 7890 12 diff --git a/docs/guidelines/language/formatting/software-versions.mdx b/docs/guidelines/language/formatting/software-versions.mdx index 248fb179b..4807c199b 100644 --- a/docs/guidelines/language/formatting/software-versions.mdx +++ b/docs/guidelines/language/formatting/software-versions.mdx @@ -13,13 +13,13 @@ description: 'Consistency in writing about versions builds trust and helps users Write "version" in full without abbreviating when there is enough space within the user interface. -
-
+
+
- Version 2.12.6
-
+
- ver 2.12.6 @@ -28,8 +28,8 @@ Write "version" in full without abbreviating when there is enough space within t Use "Version" with a capital V when it starts a sentence. -
-
+
+
- Version 3.5.1 has three new exciting changes. @@ -38,8 +38,8 @@ Use "Version" with a capital V when it starts a sentence. Use "Version" with a capital V when referring to a named release or is used as a label. -
-
+
+
- Our migration guide for moving from Version 2 to Version 3 is below. @@ -48,13 +48,13 @@ Use "Version" with a capital V when referring to a named release or is used as a Use "version" with a lower case "v" when talking about unspecified versions as it is not a proper noun. -
-
+
+
- Our next version contains three new exciting changes.
-
+
- Our next Version contains three new exciting changes. @@ -63,13 +63,13 @@ Use "version" with a lower case "v" when talking about unspecified versions as i Use a capital V without spacing between the letter and number to abbreviate versions. -
-
+
+
- V2.1.0
-
+
- v2.1.0 @@ -78,13 +78,13 @@ Use a capital V without spacing between the letter and number to abbreviate vers Start the first major release with 1 (not 01). -
-
+
+
- V1.0.0
-
+
- V01.0.0 @@ -93,13 +93,13 @@ Start the first major release with 1 (not 01). End versions without a full stop at the end. -
-
+
+
- V1.0.0
-
+
- V1.0.0. @@ -108,13 +108,13 @@ End versions without a full stop at the end. Use single digits without adding extra zeros to make it easier to read. -
-
+
+
- V3.2.5
-
+
- V03.02.05 @@ -123,14 +123,14 @@ Use single digits without adding extra zeros to make it easier to read. Add identifiers, such as alpha, before or after version numbers for pre-releases. -
-
+
+
- V1.0.0-beta - Beta V5.2
-
+
- V1.0.0-Beta diff --git a/docs/guidelines/language/formatting/timezones.mdx b/docs/guidelines/language/formatting/timezones.mdx index 5d383fb2e..b17476a33 100644 --- a/docs/guidelines/language/formatting/timezones.mdx +++ b/docs/guidelines/language/formatting/timezones.mdx @@ -15,14 +15,14 @@ description: Time and time-related guidelines help prevent misunderstandings and Use the 24-hour clock system (the ISO 8601 time standards) when backend localization is not possible. -
-
+
+
- 11:00 - 23:00
-
+
- 11am - 11PM @@ -32,13 +32,13 @@ Use the 24-hour clock system (the ISO 8601 time standards) when backend localiza Use colons (:) to split times between hours, minutes, and seconds. -
-
+
+
- hh:mm:ss
-
+
- hh.mm.ss @@ -47,15 +47,15 @@ Use colons (:) to split times between hours, minutes, and seconds. Use periods (.) to add milliseconds and nanoseconds, not a colon (:) according to ISO standards. -
-
+
+
- hh:mm:ss.mms - hh:mm:ss.sss (ISO 8601 standard) - 0:00:00.920
-
+
- 0:00:00:920 @@ -66,13 +66,13 @@ Use periods (.) to add milliseconds and nanoseconds, not a colon (:) according t Use an en (–) dash to represent time ranges and intervals without spacing on either side of the dash. -
-
+
+
- Routine maintenance: 08:00–11:00
-
+
- Packaging line active: 10:00-18:00 @@ -81,8 +81,8 @@ Use an en (–) dash to represent time ranges and intervals without spacing on e Use "from" and "to" for time ranges with separate text or input fields. -
-
+
+
- From: 14:00 - To: 15:00 @@ -94,8 +94,8 @@ Use "from" and "to" for time ranges with separate text or input fields. Use numerals to write about durations with the full or abbreviated time unit (depending on space in the UI). -
-
+
+
- Each shift lasts 8 hrs. - Routine maintenance takes approximately 1 hour 30 minutes. @@ -108,13 +108,13 @@ Use numerals to write about durations with the full or abbreviated time unit (de Write "time zone" as two words, not one word "timezone". -
-
+
+
- Select time zone
-
+
- Select timezone @@ -123,8 +123,8 @@ Write "time zone" as two words, not one word "timezone". When writing out the full time zone, add the UTC offset in brackets afterwards. -
-
+
+
- British Summer Time (UTC+1) - Central European Summer Time (UTC+2) @@ -135,8 +135,8 @@ When writing out the full time zone, add the UTC offset in brackets afterwards. Use abbreviated time zones with or without the UTC offset within the UI to save space. -
-
+
+
- EST - EST (UTC +3) @@ -146,13 +146,13 @@ Use abbreviated time zones with or without the UTC offset within the UI to save Give time zones capital letters for each word. -
-
+
+
- Eastern Standard Time
-
+
- eastern standard time @@ -161,13 +161,13 @@ Give time zones capital letters for each word. Give abbreviated time zones capital letters. -
-
+
+
- EST
-
+
- est @@ -176,13 +176,13 @@ Give abbreviated time zones capital letters. Avoid punctuation when writing time zones. -
-
+
+
- EST
-
+
- EST. - E.S.T. @@ -192,13 +192,13 @@ Avoid punctuation when writing time zones. Add a space between the time and the time zone. -
-
+
+
- 15:23 EST
-
+
- 15:23EST @@ -207,13 +207,13 @@ Add a space between the time and the time zone. Write location and UTC offset in this order: city, country (UTC offset). -
-
+
+
- Berlin, Germany (UTC+1)
-
+
- (UTC+1) Berlin, Germany @@ -222,8 +222,8 @@ Write location and UTC offset in this order: city, country (UTC offset). Present multiple time zones clearly by using either "Local time" or "Your local time" for emphasis. -
-
+
+
- Meeting time: 2025-04-08 14:00 (Berlin, UTC+01:00)
Your local time: 2025-04-08 21:00 (Tokyo, UTC+09:00) - Support hours (New York): 09:00 - 17:00 (UTC-04:00)
Your local time (Sydney): 23:00 - 07:00 (UTC+10:00) @@ -236,13 +236,13 @@ Present multiple time zones clearly by using either "Local time" or "Your local Use "current" for active, ongoing states and avoid "actual" when referring to time. -
-
+
+
- Current temperature: 72°F
-
+
- Actual temperature: 72°F @@ -251,8 +251,8 @@ Use "current" for active, ongoing states and avoid "actual" when referring to ti Use "latest" for the newest updates or versions and "last" for final items in a sequence. -
-
+
+
- Latest firmware update: V2.1.5 - Last firmware update before end of life: V2.1.5 @@ -262,13 +262,13 @@ Use "latest" for the newest updates or versions and "last" for final items in a Use "recent" for past events that have just happened. -
-
+
+
- Recent alerts: 2 warnings
-
+
- Recent firmware update: V2.1.5 diff --git a/docs/guidelines/language/frequent-app-functions.md b/docs/guidelines/language/frequent-app-functions.md index a3e0551d4..f6464c886 100644 --- a/docs/guidelines/language/frequent-app-functions.md +++ b/docs/guidelines/language/frequent-app-functions.md @@ -18,8 +18,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Cockpit -
-
+
+
- Console - Dash @@ -34,8 +34,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Anomaly detection -
-
+
+
- Assessment - Examination @@ -53,8 +53,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Remove from watchlist -
-
+
+
- Watch list @@ -69,8 +69,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Details -
-
+
+
- Facts - Specifics @@ -120,8 +120,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Drag files here or select files -
-
+
+
- Drag and drop here or browse @@ -138,8 +138,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Write your comments here -
-
+
+
- Write a comment @@ -168,8 +168,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Notify me when X occurs -
-
+
+
- Error - Issue @@ -204,8 +204,8 @@ description: 'Get tips for naming common app functions clearly and effectively. - Detected -
-
+
+
- Unacklowedged - Unack. diff --git a/docs/guidelines/language/grammar-and-vocabulary.md b/docs/guidelines/language/grammar-and-vocabulary.md index fb0a22ab5..2aa38fe23 100644 --- a/docs/guidelines/language/grammar-and-vocabulary.md +++ b/docs/guidelines/language/grammar-and-vocabulary.md @@ -16,14 +16,14 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Only use simple verb forms in the past or future when necessary -
-
+
+
- click, browse, upload - file loads, file loaded
-
+
- clicking, being clicked, was clicking - file is going to be loaded, file has been loaded @@ -33,8 +33,8 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri ## Active voice -
-
+
+
- Configuration file opens. - Admin provides read-only access. @@ -43,7 +43,7 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Calculate the data.
-
+
- The configuration file is opened. - Read-only access is provided by Admin. @@ -62,14 +62,14 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Basic terminology: checkbox, drop-down, field, icon, menu, link, radio button, window -
-
+
+
- click - hover
-
+
- press - mouse over @@ -85,8 +85,8 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Avoid cultural references -
-
+
+
- remove - calculate @@ -94,7 +94,7 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - mobile device
-
+
- get rid of - add up @@ -124,8 +124,8 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Never make up your own acronyms: https://www.acronymfinder.com/ -
-
+
+
- light emitting diodes (LEDs) - APS @@ -133,7 +133,7 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - I/O component, I/O list, I/O module
-
+
- Light Emitting Diodes (LEDS) - A.P.S. @@ -151,15 +151,15 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Recent is more time focused and is similar to latest. It means that it happened a short time ago. -
-
+
+
- Latest update - Latest summary - Recent events
-
+
- Last update - Last summary diff --git a/docs/guidelines/language/main-menu-functions.md b/docs/guidelines/language/main-menu-functions.md index 8f8e7720a..3e82e92f9 100644 --- a/docs/guidelines/language/main-menu-functions.md +++ b/docs/guidelines/language/main-menu-functions.md @@ -18,8 +18,8 @@ description: 'Explore best practices for writing main menu functions to ensure i - Forgot password? -
-
+
+
- Sign in / Sign up - Login (as it is a noun, not a verb) @@ -49,8 +49,8 @@ description: 'Explore best practices for writing main menu functions to ensure i - Edit account -
-
+
+
- id / identification - E-mail @@ -106,8 +106,8 @@ description: 'Explore best practices for writing main menu functions to ensure i - Expired licenses -
-
+
+
- licence @@ -140,8 +140,8 @@ description: 'Explore best practices for writing main menu functions to ensure i - © Siemens AG 20XX -
-
+
+
- V1 @@ -158,8 +158,8 @@ description: 'Explore best practices for writing main menu functions to ensure i - FAQ -
-
+
+
- Documentation - User manual @@ -175,8 +175,8 @@ description: 'Explore best practices for writing main menu functions to ensure i - KPIs -
-
+
+
- KPI's settings - KPIS settings diff --git a/docs/guidelines/language/punctuation.md b/docs/guidelines/language/punctuation.md index a731fc770..58ec2a9f0 100644 --- a/docs/guidelines/language/punctuation.md +++ b/docs/guidelines/language/punctuation.md @@ -85,8 +85,8 @@ Always consider whether necessary - Numbers: Use No. as an abbreviation for number, no spacing between abbreviated No. and number: No.8 -
-
+
+
- 11am - Monday, January 12, 2021 @@ -101,7 +101,7 @@ Always consider whether necessary - Number 7
-
+
- 11 a.m. - Monday, 12 January 2021 @@ -130,8 +130,8 @@ Always consider whether necessary - Add a space before unit of measurement -
-
+
+
- 50% - 11am @@ -139,7 +139,7 @@ Always consider whether necessary - Browse…
-
+
- 50 % - 11 am @@ -161,9 +161,9 @@ Always consider whether necessary - Make lists parallel, i.e. all items / bullets have the same look, length, feel, punctuation, capitalization -
+
-
+
#### Activate comments within your smartphone to @@ -173,7 +173,7 @@ Always consider whether necessary
-
+
#### Activate comments within your smartphone to diff --git a/docs/home/installation/angular.md b/docs/home/installation/angular.md index cfd16a5fd..61e49f890 100644 --- a/docs/home/installation/angular.md +++ b/docs/home/installation/angular.md @@ -76,6 +76,18 @@ import { IxButton, IxDropdown, IxDropdownItem, IxDropdownTriggerDirective } from }) export default class StandaloneExample {} ``` +:::info +When using iX form components in an Angular standalone setup, we recommend importing the appropriate value accessor directives from `@siemens/ix-angular/standalone` and include them in your component’s imports array (refer to preview examples). This prevents `No value accessor` errors. + +Available value accessors: +- `IxTextValueAccessorDirective` - For `ix-input`, `ix-number-input`, `ix-textarea` +- `IxSelectValueAccessorDirective` - For `ix-select` +- `IxRadioValueAccessorDirective` - For `ix-radio` +- `IxBooleanValueAccessorDirective` - For `ix-checkbox`, `ix-toggle` +- `IxDateValueAccessorDirective` - For `ix-date-input` +- `IxTimeValueAccessorDirective` - For `ix-time-input` + +::: ### Module setup (legacy) diff --git a/docs/home/migration/4_0_0/index.md b/docs/home/migration/4_0_0/index.md index 10ce58f53..57113af95 100644 --- a/docs/home/migration/4_0_0/index.md +++ b/docs/home/migration/4_0_0/index.md @@ -174,6 +174,14 @@ For buttons **without an explicitly set variant**, the default is used. As defau We recommend to visually review your changes. Ensure that `subtle-*` variants are not mixed with the default variant. +### ix-flip-tile + +- Renamed `state` to `variant`. +- Renamed `FlipTileState` to `FlipTileVariant`. + +### ix-message-bar + +- Renamed `dismissible` to `persistent` and changed default to false. ### ix-pane @@ -266,4 +274,4 @@ If you have used the `filled` variant of following components on `color-2` or `c If you’re using our Figma library, make sure to update to the latest published version. You can review all design-related changes in the Figma library’s release notes. -Check out the [Breaking Changes guide](https://github.com/siemens/ix/blob/release-4.0.0/BREAKING_CHANGES/v4.md) and if you have further questions or migration problems [contact us](./../support/contact-us). \ No newline at end of file +Check out the [Breaking Changes guide](https://github.com/siemens/ix/blob/release-4.0.0/BREAKING_CHANGES/v4.md) and if you have further questions or migration problems [contact us](./../support/contact-us). diff --git a/docs/home/overview.md b/docs/home/overview.md index e4e27249d..c52952efd 100644 --- a/docs/home/overview.md +++ b/docs/home/overview.md @@ -16,7 +16,7 @@ import './card-with-icon.css'; Our Figma library contains all tokens, components and blueprints ready for app design. -- **Access:** The primary library is maintained in the Siemens AG Global Figma account. Siemens employees with a Figma license can search for "iX Design System". +- **Access:** We maintain the primary library in the [Siemens AG Global Figma account](https://siemens-ix.code.siemens.io/ix-brand-theme/). Siemens employees with a Figma license can search for "iX Design System". - **Guest access and classic theme:** Guest access and the classic (open-source) library are available upon request — please [contact us](support/contact-us). - **Brand and variables:** The library includes Siemens brand assets and Figma variables for easy theming. See [Designing with themes](../styles/theming/usage-designers.md) for details. diff --git a/docs/home/support/faq.md b/docs/home/support/faq.md index fdede61fd..590eb9545 100644 --- a/docs/home/support/faq.md +++ b/docs/home/support/faq.md @@ -55,10 +55,62 @@ We want everyone to contribute to our design system and play a part in its devel For more information, see our [GitHub Contributing Guide](https://github.com/siemens/ix/blob/main/CONTRIBUTING.md) which has guidance on bug reporting, workflow issues and suggesting enhancements. - + Absolutely! Please add requests for the future in [Github](https://github.com/siemens/ix) or [Siemens Xcelerator Community](https://community.siemens.com/c/ix/30). + +iX components receive a `hydrated` class when they’re fully initialized. Use the `componentOnReady()` method to wait for hydration: + +```javascript +const button = document.querySelector('ix-button'); +if (button) { + button.componentOnReady().then(() => { + console.log('Button is ready'); + // Your initialization code here + }); +} +``` + +For multiple components: + +```javascript +const button = document.querySelector('ix-button'); +const input = document.querySelector('ix-input'); + +const elements = [button, input].filter(Boolean); + +if (elements.length > 0) { + Promise.all(elements.map(el => el.componentOnReady())).then(() => { + console.log('All components are ready'); + }); +} +``` +:::info +The `appload` event mentioned in Stencil documentation is not available in iX. Use `componentOnReady()` instead. +::: + +Learn more in the [Stencil documentation](https://stenciljs.com/docs/api#componentonready). + + + +Flash of Undefined Custom Elements (FOUCE) occurs when custom elements briefly appear unstyled before hydration. Use the `hydrated` class to prevent this: + +```css +/* Hide specific components until hydrated */ +ix-button:not(.hydrated), +ix-icon:not(.hydrated), +ix-input:not(.hydrated) { + visibility: hidden; +} + +/* Or hide all ix-elements */ +*[class*="ix-"]:not(.hydrated) { + visibility: hidden; +} +``` + +
## Customization and framework Support
@@ -72,7 +124,7 @@ Users are free to utilize open-source libraries at their discretion. However, cu -Our design system is built with plain Web Components and is, therefore, framework agnostic. For better integration, we provide support for some of the most popular web development frameworks in Angular, React and Vue. You can find more information about our frameworks [here](/docs/home/getting-started/developers#development-frameworks). +Our design system is built with plain Web Components and is, therefore, framework agnostic. For better integration, we provide support for some of the most popular web development frameworks in Angular, React and Vue. You can find more information about our frameworks [here](/docs/home/overview#development-frameworks). @@ -84,7 +136,7 @@ Our codebase is openly and freely accessible for anyone to view, modify and dist
-[Here](/docs/home/getting-started/designers#figma-library) you will find information on how to get Figma and how to access the most important Industrial Experience libraries. Remember, the Siemens brand library contains Siemens-specific brand elements and is only accessible to Siemens employees and business partners. For the classic theme, we don’t have updated Figma files, but you can use the code components. +[Here](/docs/home/overview#figma-library) you will find information on how to get Figma and how to access the most important Industrial Experience libraries. Remember, the Siemens brand library contains Siemens-specific brand elements and is only accessible to Siemens employees and business partners. For the classic theme, we don’t have updated Figma files, but you can use the code components. diff --git a/docs/icons/developing-with-icons.md b/docs/icons/developing-with-icons.md index e96265f92..a650cd000 100644 --- a/docs/icons/developing-with-icons.md +++ b/docs/icons/developing-with-icons.md @@ -35,6 +35,26 @@ Provide all iX icons as asset folder via `angular.json`. ], ``` +To avoid unwanted console warnings, we recommend you also configure the domain of the asset path using the `meta`-tag: + +```html + + + + + + + +``` + +Or using the `setAssetPath`-function: + +```ts +import { setAssetPath } from '@siemens/ix-icons/components'; + +setAssetPath('/svg'); +``` + It is also possible to import individual icons without an asset folder via [addIcons](#reference-icons-by-name). Then you can reference iX icons by name anywhere in your application. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 7afb9bf66..134cd42e1 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -103,7 +103,7 @@ const config: Config = { customFields: { withBrandTheme, - playgroundVersion: '^4.0.0' + playgroundVersion: '^4.2.0' }, presets: [ diff --git a/package.json b/package.json index d9e093518..ab76c6d9e 100644 --- a/package.json +++ b/package.json @@ -23,9 +23,9 @@ "@docusaurus/plugin-client-redirects": "^3.7.0", "@docusaurus/preset-classic": "3.7.0", "@mdx-js/react": "^3.0.0", - "@siemens/ix": "0.0.0-pr-2198-20251023082407", + "@siemens/ix": "^4.2.0", "@siemens/ix-icons": "^3.2.0", - "@siemens/ix-react": "0.0.0-pr-2198-20251023082407", + "@siemens/ix-react": "^4.2.0", "@stackblitz/sdk": "^1.11.0", "prism-react-renderer": "^2.3.0", "prismjs": "^1.30.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1220f77ae..71ebcbe08 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -24,14 +24,14 @@ importers: specifier: ^3.0.0 version: 3.1.0(@types/react@18.3.22)(react@18.3.1) '@siemens/ix': - specifier: 0.0.0-pr-2198-20251023082407 - version: 0.0.0-pr-2198-20251023082407(@siemens/ix-icons@3.2.0) + specifier: ^4.2.0 + version: 4.2.0(@siemens/ix-icons@3.2.0) '@siemens/ix-icons': specifier: ^3.2.0 version: 3.2.0 '@siemens/ix-react': - specifier: 0.0.0-pr-2198-20251023082407 - version: 0.0.0-pr-2198-20251023082407(@siemens/ix-icons@3.2.0)(@stencil/core@4.31.0)(@types/react@18.3.22)(react-dom@18.3.1(react@18.3.1))(react@18.3.1) + specifier: ^4.2.0 + version: 4.2.0(@siemens/ix-icons@3.2.0)(@stencil/core@4.31.0)(@types/react@18.3.22)(react-dom@18.3.1(react@18.3.1))(react@18.3.1) '@stackblitz/sdk': specifier: ^1.11.0 version: 1.11.0 @@ -1913,15 +1913,15 @@ packages: resolution: {integrity: sha512-4cdEqCHlDILVCDCld1Ycy04/5d8ICCpRxE7Y3l2GBTo9EydI5ZUkVG243Y9wp/kZazTK9c4wvPZ5d6lCqS57tg==} engines: {node: '>=22.19.x', pnpm: '>=10.x.x'} - '@siemens/ix-react@0.0.0-pr-2198-20251023082407': - resolution: {integrity: sha512-ilaf5ON5LYJk89I8QPXLi6K/fZwQ9S923bAWzivo1suQZWFSj1r/rbPSZpf2+nhInrIgIsq3a6+hnptniLzdag==} + '@siemens/ix-react@4.2.0': + resolution: {integrity: sha512-bmEBm1faATBhY3MBkwnQqRiaKMnyc0CnsVJHB959k1vTScqi6xvmP0e6EBKD+oV5Xb57E3tH/WQBdH7ryLGbqg==} peerDependencies: '@siemens/ix-icons': ^3.2.0 react: ^18 || ^19 react-dom: ^18 || ^19 - '@siemens/ix@0.0.0-pr-2198-20251023082407': - resolution: {integrity: sha512-U9NKd9afBOszj9yORv0FQq6+ynn7mXAMDMiDhh+mosBgoeoSdnFJOsuWe9SqA4wpOkSUgpieyrvjowF/ESbo+A==} + '@siemens/ix@4.2.0': + resolution: {integrity: sha512-FvgKqBdbV1feAf8jI2nBR1/saO4ulsNRYXVmS2qgXzH7Jp1pmdbVlf0hUSQlY8tuk0XWYUPmjdW6kLeyO57o/A==} peerDependencies: '@siemens/ix-icons': ^3.2.0 @@ -8767,9 +8767,9 @@ snapshots: '@siemens/ix-icons@3.2.0': {} - '@siemens/ix-react@0.0.0-pr-2198-20251023082407(@siemens/ix-icons@3.2.0)(@stencil/core@4.31.0)(@types/react@18.3.22)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)': + '@siemens/ix-react@4.2.0(@siemens/ix-icons@3.2.0)(@stencil/core@4.31.0)(@types/react@18.3.22)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)': dependencies: - '@siemens/ix': 0.0.0-pr-2198-20251023082407(@siemens/ix-icons@3.2.0) + '@siemens/ix': 4.2.0(@siemens/ix-icons@3.2.0) '@siemens/ix-icons': 3.2.0 '@stencil/react-output-target': 1.2.0(@stencil/core@4.31.0)(@types/react@18.3.22)(react-dom@18.3.1(react@18.3.1))(react@18.3.1) react: 18.3.1 @@ -8779,7 +8779,7 @@ snapshots: - '@stencil/core' - '@types/react' - '@siemens/ix@0.0.0-pr-2198-20251023082407(@siemens/ix-icons@3.2.0)': + '@siemens/ix@4.2.0(@siemens/ix-icons@3.2.0)': dependencies: '@floating-ui/dom': 1.7.0 '@siemens/ix-icons': 3.2.0 diff --git a/src/components/Accordion/index.tsx b/src/components/Accordion/index.tsx index b50c8adc8..1804ecce7 100644 --- a/src/components/Accordion/index.tsx +++ b/src/components/Accordion/index.tsx @@ -21,6 +21,7 @@ export default function Accordion( }> ) { const [expanded, setExpanded] = useState(false); + const panelId = `accordion-${props.id || uniqueId++}-panel`; function onHeaderKeyDown(e: React.KeyboardEvent) { diff --git a/src/components/GuidingPrinciples/index.tsx b/src/components/GuidingPrinciples/index.tsx index 03f04984a..ee78acdb7 100644 --- a/src/components/GuidingPrinciples/index.tsx +++ b/src/components/GuidingPrinciples/index.tsx @@ -131,7 +131,7 @@ function DevelopmentFrameworks(){
React @@ -139,7 +139,7 @@ function DevelopmentFrameworks(){ Angular @@ -147,7 +147,7 @@ function DevelopmentFrameworks(){ Web Components @@ -155,7 +155,7 @@ function DevelopmentFrameworks(){ Vue @@ -163,7 +163,7 @@ function DevelopmentFrameworks(){ Blazor diff --git a/src/scss/components/_dosAndDonts.scss b/src/scss/components/_dosAndDonts.scss index 4bb5e5973..52abad0f1 100644 --- a/src/scss/components/_dosAndDonts.scss +++ b/src/scss/components/_dosAndDonts.scss @@ -29,18 +29,17 @@ gap: 1rem; li { - display: flex; - align-items: flex-start; - gap: 0.75rem; position: relative; + padding-left: calc(24px + 0.75rem); margin-top: 0 !important; &::before { content: ''; - min-width: 24px; + position: absolute; + left: 0; + top: 0; width: 24px; height: 24px; - display: inline-block; background-size: 24px 24px; background-repeat: no-repeat; background-position: center; From c91132ffbeebd5894e0d8c9108efed442950e46a Mon Sep 17 00:00:00 2001 From: varun srinivasa Date: Fri, 23 Jan 2026 09:00:38 +0530 Subject: [PATCH 6/6] updated warning messages and removed bestpractices --- docs/guidelines/language/best-practices.md | 120 ------------------ docs/guidelines/language/warning-messages.mdx | 28 ++-- 2 files changed, 14 insertions(+), 134 deletions(-) delete mode 100644 docs/guidelines/language/best-practices.md diff --git a/docs/guidelines/language/best-practices.md b/docs/guidelines/language/best-practices.md deleted file mode 100644 index 745ed1fb1..000000000 --- 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/warning-messages.mdx b/docs/guidelines/language/warning-messages.mdx index eda09fd8f..71a7e2f3b 100644 --- a/docs/guidelines/language/warning-messages.mdx +++ b/docs/guidelines/language/warning-messages.mdx @@ -24,15 +24,15 @@ We follow this three-step approach when creating our warning messages. This ensu ### 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°
@@ -43,14 +43,14 @@ 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 @@ -60,19 +60,19 @@ 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 @@ -80,8 +80,8 @@ Button: Open access settings
-
-
+
+
Heading: Unauthorized access attempt on Control Panel A Description: Review access logs and verify user credentials. Button: Open access logs