diff --git a/docs/components/3d/overview.mdx b/docs/components/3d/overview.mdx index 238415ab7..2e5d53ffc 100644 --- a/docs/components/3d/overview.mdx +++ b/docs/components/3d/overview.mdx @@ -28,6 +28,16 @@ import 'echarts-gl'; ## Dos and Don’ts -- Do use with data that's best seen and interpreted in multiple dimensions -- Don’t use 3D charts for simple data that can be effectively represented with 2D charts -- Don’t overuse 3D charts as they can make the data harder to interpret +
+
+ +
+
+ +
+
diff --git a/docs/components/application-header/guide.md b/docs/components/application-header/guide.md index 0be56b0b9..aa941e4b1 100644 --- a/docs/components/application-header/guide.md +++ b/docs/components/application-header/guide.md @@ -126,9 +126,19 @@ At breakpoint "sm" the layout changes in the following way: ## Dos and Don’ts -- Do align other slot usages for Siemens applications with our team to keep a consistent look and feel -- Do use the avatar dropdown for actions related to the current logged in user -- Do test layout behavior at all breakpoints to ensure content remains accessible -- Don’t overload the slots with too many elements to avoid losing clarity and hierarchy -- Don’t use the avatar if your application does not support user profiles -- Don’t rely on automatic overflow handling for complex layouts, instead reduce complexity +
+
+ +
+
+ +
+
diff --git a/docs/components/application-menu/guide.md b/docs/components/application-menu/guide.md index 07fc75ca9..6fe20c962 100644 --- a/docs/components/application-menu/guide.md +++ b/docs/components/application-menu/guide.md @@ -44,8 +44,18 @@ The navigation menu is an essential part of your application. It offers a way to The application menu has two states: collapsed and expanded. The appearance of the states varies between screen sizes. ## Dos and Don’ts -- Do use icons in second-level navigation items when it helps users to better understand and recognize them -- Do use a custom tooltip text if the label is so long that it gets truncated or needs additional context -- Don’t mix menu items with and without icons within a second-level navigation category -- Don’t place non-navigational items in the navigation section -- Don’t place navigation items in the bottom section as items in the bottom section must not navigate away from the current context \ No newline at end of file +
+
+ +
+
+ +
+
diff --git a/docs/components/avatar/guide.md b/docs/components/avatar/guide.md index c77016bde..53fb2194e 100644 --- a/docs/components/avatar/guide.md +++ b/docs/components/avatar/guide.md @@ -24,4 +24,10 @@ The avatar is a display-only component with no further interactions. Images prov ![Avatar dos and don‘ts](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=975-13&mode=design&t=SxUA6AcHswBAiIzi-4) -- Don’t use more than 2 characters when using the "Initials" option +
+
+ +
+
diff --git a/docs/components/bar-chart/overview.mdx b/docs/components/bar-chart/overview.mdx index 7082edf15..8a9692d6f 100644 --- a/docs/components/bar-chart/overview.mdx +++ b/docs/components/bar-chart/overview.mdx @@ -24,10 +24,20 @@ Stacked bar charts are typically used to visualize the relationship between the ## Dos and Don’ts -- Do start the Y-axis at zero and label axes clearly -- Do use short and clear category names -- Do include context and additional information when necessary -- Do arrange categories and bars in a logical order -- Don’t use too many bars in one chart -- Don’t overcrowd charts with colors and categories, especially the stacked variant -- Don’t use stacked bars if the total value is not important +
+
+ +
+
+ +
+
diff --git a/docs/components/blind/guide.md b/docs/components/blind/guide.md index d8b17e348..7910f9150 100644 --- a/docs/components/blind/guide.md +++ b/docs/components/blind/guide.md @@ -49,11 +49,21 @@ For all blind variants, a default, hover, active and focused state is available. ## Dos and Don’ts -- Do stay within the recommended number of blinds - between 3 and 7 -- Don’t use multi-line text in the header. The header section has a fixed height for single-line text entries -- Don’t change the position of the chevron icon and the blind's label in the header -- Don’t use a blind if there is only a single category to be displayed -- Don’t use blinds to display hierarchically structured files or objects - rather use a tree for such cases +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/breadcrumb/guide.md b/docs/components/breadcrumb/guide.md index d40fc21ec..9e7f15c38 100644 --- a/docs/components/breadcrumb/guide.md +++ b/docs/components/breadcrumb/guide.md @@ -40,10 +40,20 @@ Interactive items can take one of four states: Default, hover, active and focuse ## Dos and Don’ts -- Do label each item, i.e. use more than icons -- Do use single-line text entries as breadcrumb items have a fixed height -- Don’t use breadcrumbs to display a multistep process (use the [workflow](../workflow) control instead) -- Don’t show multiple breadcrumbs on one screen, e.g. in a content area and in a drawer +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/button/guide.md b/docs/components/button/guide.md index 0617152ed..5fc0db51b 100644 --- a/docs/components/button/guide.md +++ b/docs/components/button/guide.md @@ -49,12 +49,22 @@ Buttons have six states: Default, hover, active, disabled, loading and focused. ## Dos and Don’ts -- Do use short button labels to allow users to quickly scan, understand and remember them (see our [writing style guide](../../guidelines/language/dialogs-and-buttons.md)) -- Do use ellipsis (…) to indicate that an action requires further input or choice from the user, e.g. "Save as…" which opens a list of file types to choose from -- Do use the primary variant for buttons to indicate one primary action in a visual unit, all other secondary actions should use the secondary variant -- Don’t place icons both left and right of the label on the same button -- Don’t use the danger button excessively or repetitively in lists or tables -- Don’t rely on standard buttons when many actions are necessary (use [dropdown buttons](../dropdown-button/index.mdx) or [split buttons](../split-button/index.mdx) instead, or move some functionality to a [pane](../panes/index.mdx) or a [dialog](../modal/index.mdx)) +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/card-list/guide.md b/docs/components/card-list/guide.md index e3ac65d66..812b918d3 100644 --- a/docs/components/card-list/guide.md +++ b/docs/components/card-list/guide.md @@ -43,9 +43,19 @@ The scroll card list style displays the content items from left to right next to ## Dos and Don’ts -- Do keep cards and items within card lists the same size -- Don’t place different types of components within card lists -- Don’t nest card lists within each other +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/card/guide.md b/docs/components/card/guide.md index c262c5457..943925c04 100644 --- a/docs/components/card/guide.md +++ b/docs/components/card/guide.md @@ -83,10 +83,20 @@ Cards have four states: Default, hover, active and focused. ## Dos and Don’ts -- Do group cards in [card lists](../card-list) or [grids](../grid) -- Do keep multiple cards equal in size -- Don’t nest cards inside each other -- Don’t use cards to collect user input +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/category-filter/guide.md b/docs/components/category-filter/guide.md index 914865f5f..9a1b8ae7b 100644 --- a/docs/components/category-filter/guide.md +++ b/docs/components/category-filter/guide.md @@ -45,14 +45,24 @@ Category filter has six states: Default, hover, active, disabled, read-only and ## Dos and Don’ts -- Do use if you have a large amount of content or products organized into different categories -- Do use when catering to a diverse user base with different interests or needs -- Do use if your content or products are organized into distinct categories or topics -- Do use to make it easier for users to refine their search queries and receive more targeted results -- Don’t use if your content is minimal or not organized into distinct categories -- Don’t use if it’s not the primary method of navigation -- Don’t use if it slows down the user experience -- Don’t use if your users are not familiar with the category names +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/checkbox/guide.md b/docs/components/checkbox/guide.md index 5752c2372..64638c160 100644 --- a/docs/components/checkbox/guide.md +++ b/docs/components/checkbox/guide.md @@ -36,9 +36,19 @@ Checkboxes are commonly used when there are multiple options that can be selecte ## Dos and Don’ts -- Do use checkboxes when you have multiple options that can be selected -- Do group related checkboxes together to indicate their relationship -- Do use checkboxes in forms to allow users to select multiple options -- Don’t use a checkbox for binary choices (yes/no, true/false) - use a toggle switch instead -- Don’t use checkboxes for mutually exclusive options - use [radio buttons](../radio) instead -- Don’t use checkboxes for actions that have immediate consequences - use [buttons](../button) or links instead +
+
+ +
+
+ +
+
diff --git a/docs/components/chip/guide.md b/docs/components/chip/guide.md index 444f22384..2f4209b2b 100644 --- a/docs/components/chip/guide.md +++ b/docs/components/chip/guide.md @@ -52,12 +52,22 @@ Chips take a default, hover, focused or active state with a varying background c ## Dos and Don’ts -- Do use chips to tag and categorize so users can easily organize and filter content -- Do ensure proper color contrast between chip background and text/icon with the custom variant to support readability -- Do consider chip spacing for easy tapping or selecting with mobiles and desktops -- Don’t overuse chips as this leads to cluttered and overwhelming interfaces -- Don’t use different styles for chips with the same or similar use -- Don’t use chips without any interaction (we recommend pills instead) +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/content-header/guide.md b/docs/components/content-header/guide.md index 850c01a60..1cf379178 100644 --- a/docs/components/content-header/guide.md +++ b/docs/components/content-header/guide.md @@ -42,10 +42,20 @@ Our content header variants makes it easier to achieve a well-balanced visual hi ## Dos and Don’ts -- Do use to provide quick access to common tasks for the whole content area -- Do place only items in the header slot that don’t take up too much space, such as a status or a counter -- Don’t use a secondary content header as a page title -- Don’t use more than one primary headline in one page +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/custom-field/guide.md b/docs/components/custom-field/guide.md index 7ce79cd27..d3fcb423b 100644 --- a/docs/components/custom-field/guide.md +++ b/docs/components/custom-field/guide.md @@ -34,11 +34,21 @@ The states depend on the component that you use in the custom field. The custom ## Dos and Don’ts -- Do use the custom field when your desired solution is not covered by the already existing form field components -- Do use the custom field in combination with the form component to create complex forms -- Don’t use the custom field for simple form fields, use the form field component instead -- Don’t use the custom field without a form component, it is a wrapper component that is meant to be used in combination with the form component -- Don’t use helper and feedback texts for single fields within a custom field, use the helper and feedback text of the whole custom field instead +
+
+ +
+
+ +
+
## Related diff --git a/docs/components/date-picker/guide.mdx b/docs/components/date-picker/guide.mdx index e8d95ce8e..3d7e2157f 100644 --- a/docs/components/date-picker/guide.mdx +++ b/docs/components/date-picker/guide.mdx @@ -40,22 +40,22 @@ Individual calendar dates within a date picker have five states: Default, hover, ## Dos and Don’ts -
-
- -- Do use date pickers to ensure accurate date selection -- Do provide clear labels when the date picker is used in a form context -- Do ensure the date picker is accessible via keyboard navigation -- Do use range selection for date periods like booking dates or report timeframes -- Do set min and max dates to prevent invalid date selections - +
+
+
    +
  • Do use date pickers to ensure accurate date selection
    • +
  • Do provide clear labels when the date picker is used in a form context
    • +
  • Do ensure the date picker is accessible via keyboard navigation
    • +
  • Do use range selection for date periods like booking dates or report timeframes
    • +
  • Do set min and max dates to prevent invalid date selections
    • +
-
- -- Don’t use date pickers for dates that are far in the past or future, use [date inputs](../input) instead -- Don’t clutter the date picker interface with unnecessary options -- Don’t forget to handle empty or invalid date states in your validation logic - +
+
    +
  • Don’t use date pickers for dates that are far in the past or future, use [date inputs](../input) instead
    • +
  • Don’t clutter the date picker interface with unnecessary options
    • +
  • Don’t forget to handle empty or invalid date states in your validation logic
    • +
diff --git a/docs/components/date-time-picker/guide.mdx b/docs/components/date-time-picker/guide.mdx index 33cc4edae..333ac49c8 100644 --- a/docs/components/date-time-picker/guide.mdx +++ b/docs/components/date-time-picker/guide.mdx @@ -41,22 +41,22 @@ Individual calendar dates within a date time picker have five states: Default, h ## Dos and Don’ts -
-
- -- Do use date time pickers when both date and time information are required -- Do ensure the date time picker is accessible via keyboard navigation -- Do use range selection for time periods like booking appointments or scheduling events -- Do set appropriate min and max dates to prevent invalid selections - +
+
+
    +
  • Do use date time pickers when both date and time information are required
    • +
  • Do ensure the date time picker is accessible via keyboard navigation
    • +
  • Do use range selection for time periods like booking appointments or scheduling events
    • +
  • Do set appropriate min and max dates to prevent invalid selections
    • +
-
- -- Don’t use date time pickers when only a date or only a time is needed (use [date pickers](../date-picker) or [time pickers](../time-picker) instead) -- Don’t forget to validate both date and time inputs in your form logic -- Don’t use date time pickers for dates that are far in the past or future without setting appropriate min and max constraints -- Don’t clutter the interface with unnecessary time precision when approximate times are sufficient - +
+
    +
  • Don’t use date time pickers when only a date or only a time is needed (use [date pickers](../date-picker) or [time pickers](../time-picker) instead)
    • +
  • Don’t forget to validate both date and time inputs in your form logic
    • +
  • Don’t use date time pickers for dates that are far in the past or future without setting appropriate min and max constraints
    • +
  • Don’t clutter the interface with unnecessary time precision when approximate times are sufficient
    • +
diff --git a/docs/components/dropdown-button/guide.md b/docs/components/dropdown-button/guide.md index 261660f4d..3be7e8ff5 100644 --- a/docs/components/dropdown-button/guide.md +++ b/docs/components/dropdown-button/guide.md @@ -34,8 +34,18 @@ Dropdown buttons have five states: Default, hover, active, disabled and focused. ## Dos and Don’ts -- Do use dropdown buttons when selecting an option triggers an action -- Don’t use dropdown buttons when there is a frequent or most-important action (use a standard button or a split button instead) +
+
+
    +
  • Do use dropdown buttons when selecting an option triggers an action
    • +
+
+
+
    +
  • Don’t use dropdown buttons when there is a frequent or most-important action (use a standard button or a split button instead)
    • +
+
+
## Related diff --git a/docs/components/dropdown/guide.md b/docs/components/dropdown/guide.md index bf86f0ec9..0a8d0f042 100644 --- a/docs/components/dropdown/guide.md +++ b/docs/components/dropdown/guide.md @@ -56,12 +56,22 @@ Dropdown items have five states: Default, hover, active, disabled and focused. W ## Dos and Don’ts -- Do structure dropdown items coherently with submenus, quick actions and separators -- Do use dropdowns to showcase related actions -- Do disable items that cannot be used at that moment -- Don’t use global navigation options in a dropdown -- Don’t use too many dropdown items - we recommend a maximum of seven -- Don’t insert the [date picker](../date-dropdown) instead) +
+
+
    +
  • Do structure dropdown items coherently with submenus, quick actions and separators
    • +
  • Do use dropdowns to showcase related actions
    • +
  • Do disable items that cannot be used at that moment
    • +
+
+
+
    +
  • Don’t use global navigation options in a dropdown
    • +
  • Don’t use too many dropdown items - we recommend a maximum of seven
    • +
  • Don’t insert the [date picker](../date-dropdown) instead)
    • +
+
+
## Related diff --git a/docs/components/forms-field/guide.md b/docs/components/forms-field/guide.md index 43ba0237f..ab7745efd 100644 --- a/docs/components/forms-field/guide.md +++ b/docs/components/forms-field/guide.md @@ -43,11 +43,21 @@ When a feedback tooltip is chosen over a message, the field shows a tooltip when ## Dos and Don’ts -- Do use a label for every field -- Do use a counter for fields with a character limit -- Do use helper text to provide additional information or context about the field -- Don’t use helper text as a replacement for clear labels -- Don’t mix different variants of feedback text and tooltips +
+
+
    +
  • Do use a label for every field
    • +
  • Do use a counter for fields with a character limit
    • +
  • Do use helper text to provide additional information or context about the field
    • +
+
+
+
    +
  • Don’t use helper text as a replacement for clear labels
    • +
  • Don’t mix different variants of feedback text and tooltips
    • +
+
+
## Related diff --git a/docs/components/forms-validation/guide.md b/docs/components/forms-validation/guide.md index 849432dc5..d3d8425f1 100644 --- a/docs/components/forms-validation/guide.md +++ b/docs/components/forms-validation/guide.md @@ -67,9 +67,19 @@ Example: When the user completes the shipping address section of an e-commerce c ## Dos and Don’ts -- Do use short and helpful copy for validation -- Do include all relevant information in the validation message, including context -- Don’t show valid feedback on components, only in the input help component +
+
+
    +
  • Do use short and helpful copy for validation
    • +
  • Do include all relevant information in the validation message, including context
    • +
+
+
+
    +
  • Don’t show valid feedback on components, only in the input help component
    • +
+
+
## Related diff --git a/docs/components/gauge-chart/overview.mdx b/docs/components/gauge-chart/overview.mdx index 707b08bd4..991771865 100644 --- a/docs/components/gauge-chart/overview.mdx +++ b/docs/components/gauge-chart/overview.mdx @@ -31,9 +31,19 @@ Arc gauge charts, also known as semi-circular progress bars, are a dynamic way t ## Dos and Don’ts -- Do keep it simple and easy to read, with a clear needle and well-defined ranges -- Do use color coding, e.g. green for good, red for danger, etc. to indicate different ranges -- Do label ranges and the needle value clearly to avoid confusion -- Don’t overcrowd the gauge with too many ranges or labels -- Don’t use gauge charts for visualizing complex data or large datasets -- Don’t use similar colors for adjacent ranges to avoid confusion +
+
+
    +
  • Do keep it simple and easy to read, with a clear needle and well-defined ranges
    • +
  • Do use color coding, e.g. green for good, red for danger, etc. to indicate different ranges
    • +
  • Do label ranges and the needle value clearly to avoid confusion
    • +
+
+
+
    +
  • Don’t overcrowd the gauge with too many ranges or labels
    • +
  • Don’t use gauge charts for visualizing complex data or large datasets
    • +
  • Don’t use similar colors for adjacent ranges to avoid confusion
    • +
+
+
diff --git a/docs/components/grid/guide.md b/docs/components/grid/guide.md index 77fd70e60..b9b372dd9 100644 --- a/docs/components/grid/guide.md +++ b/docs/components/grid/guide.md @@ -47,13 +47,23 @@ Data grid columns, rows and cells have multiple states: Default, hover, active a ![Data grid states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7743-1852&t=pnIkODidZu9oNqXj-4) -## Dos and Don'ts - -- Do only display primary information by default and use [column tool panels](https://www.ag-grid.com/javascript-data-grid/tool-panel-columns/) for secondary information -- Do keep selection and row-click behavior independent to avoid confusion -- Do design responsive layouts that adapt to different screen sizes -- Don’t embed heavily interactive components within grid cells -- Don’t rely solely on color for status, use icons, labels or badges instead +## Dos and Don’ts + +
+
+
    +
  • Do only display primary information by default and use [column tool panels](https://www.ag-grid.com/javascript-data-grid/tool-panel-columns/) for secondary information
    • +
  • Do keep selection and row-click behavior independent to avoid confusion
    • +
  • Do design responsive layouts that adapt to different screen sizes
    • +
+
+
+
    +
  • Don’t embed heavily interactive components within grid cells
    • +
  • Don’t rely solely on color for status, use icons, labels or badges instead
    • +
+
+
## Related diff --git a/docs/components/html-grid/guide.md b/docs/components/html-grid/guide.md index 63f80513c..c47115c1c 100644 --- a/docs/components/html-grid/guide.md +++ b/docs/components/html-grid/guide.md @@ -28,12 +28,22 @@ The HTML table is not a dedicated web component, but rather styling applied to t - **Interaction**: By default, HTML tables do not include interactive features like sorting or selection. However, we can enhance tables with JavaScript to add sorting by clicking column headers and row selection via checkboxes. For more advanced interactions (e.g. filtering, grouping, inline editing), we recommend using [data grids](../grid) instead. - **Overflow**: By default, text wraps within cells. For tables with many columns, enable horizontal scrolling to maintain readability. -## Dos and Don'ts - -- Do display only essential information -- Do design tables to adapt responsively to different screen sizes, e.g. by hiding less critical columns on smaller screens, enabling horizontal scrolling or wrapping content within cells -- Don’t use tables for unstructured or hierarchical data, use [event lists](../event-list) or [trees](../tree) instead -- Don’t rely solely on color for status; also use icons or labels for additional transparency +## Dos and Don’ts + +
+
+
    +
  • Do display only essential information
    • +
  • Do design tables to adapt responsively to different screen sizes, e.g. by hiding less critical columns on smaller screens, enabling horizontal scrolling or wrapping content within cells
    • +
+
+
+
    +
  • Don’t use tables for unstructured or hierarchical data, use [event lists](../event-list) or [trees](../tree) instead
    • +
  • Don’t rely solely on color for status; also use icons or labels for additional transparency
    • +
+
+
## Related diff --git a/docs/components/icon-button/guide.md b/docs/components/icon-button/guide.md index c018530ad..073c25c64 100644 --- a/docs/components/icon-button/guide.md +++ b/docs/components/icon-button/guide.md @@ -21,9 +21,19 @@ All the variants, options and states of the [button](../button) component apply ## Dos and Don’ts -- Do use icons that have a clear meaning for the user, otherwise use text buttons -- Don’t use icon buttons in large numbers, instead use a toolbar -- Don’t stretch icon buttons to span a container’s width +
+
+
    +
  • Do use icons that have a clear meaning for the user, otherwise use text buttons
    • +
+
+
+
    +
  • Don’t use icon buttons in large numbers, instead use a toolbar
    • +
  • Don’t stretch icon buttons to span a container’s width
    • +
+
+
## Related diff --git a/docs/components/input-date-time/guide.mdx b/docs/components/input-date-time/guide.mdx index f3f71d4b4..80da113a1 100644 --- a/docs/components/input-date-time/guide.mdx +++ b/docs/components/input-date-time/guide.mdx @@ -53,21 +53,21 @@ Date time input has five states: Default, hover, disabled, read-only and focused ![Date time input states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7441-86123&t=BStIEA03mmCLaHAL-4) -## Dos and Don'ts - -
-
- -- Do use consistent date and time formats throughout the application to avoid confusion -- Do provide clear instructions on the expected format, such as "Enter the date time in yyyy/mm/dd HH:mm format" -- Do consider localization to adapt date and time formats to local conventions -- Do use separate inputs for start and end date times when defining time ranges - +## Dos and Don’ts + +
+
+
    +
  • Do use consistent date and time formats throughout the application to avoid confusion
    • +
  • Do provide clear instructions on the expected format, such as "Enter the date time in yyyy/mm/dd HH:mm format"
    • +
  • Do consider localization to adapt date and time formats to local conventions
    • +
  • Do use separate inputs for start and end date times when defining time ranges
    • +
-
- -- Don't use date time inputs when only a date or only a time is needed (use [date input](../input-date) or [time input](../input-time) instead) - +
+
    +
  • Don't use date time inputs when only a date or only a time is needed (use [date input](../input-date) or [time input](../input-time) instead)
    • +
diff --git a/docs/components/input-date/guide.md b/docs/components/input-date/guide.md index 8c60039e0..2592f8b52 100644 --- a/docs/components/input-date/guide.md +++ b/docs/components/input-date/guide.md @@ -55,12 +55,22 @@ Date input has five states: Default, hover, disabled, read-only and focused. ## Dos and Don’ts -- Do use consistent date formats throughout the application to avoid confusion -- Do use separate inputs for start and end dates to simplify date ranges -- Do provide clear instructions, such as “Enter the date in yyyy/mm/dd format” -- Do consider localization to adapt date formats to local conventions -- Don’t use ambiguous formats like 09/08/2006 without giving clear context -- Don’t allow free text without validation or formatting guidance +
+
+
    +
  • Do use consistent date formats throughout the application to avoid confusion
    • +
  • Do use separate inputs for start and end dates to simplify date ranges
    • +
  • Do provide clear instructions, such as “Enter the date in yyyy/mm/dd format”
    • +
  • Do consider localization to adapt date formats to local conventions
    • +
+
+
+
    +
  • Don’t use ambiguous formats like 09/08/2006 without giving clear context
    • +
  • Don’t allow free text without validation or formatting guidance
    • +
+
+
## Related diff --git a/docs/components/input-number/guide.md b/docs/components/input-number/guide.md index 9b9e4cae1..864151ede 100644 --- a/docs/components/input-number/guide.md +++ b/docs/components/input-number/guide.md @@ -45,10 +45,18 @@ The number input has five states: default, hover, focused, disabled and read-onl ## Dos and Don’ts -- Do set appropriate min and max values to prevent invalid entries and guide user input -- Do provide clear error messages when the input value is out of the allowed range or does not match the required pattern -- Do consider special cases such as zero, negative numbers and very large numbers to ensure all possible inputs are handled correctly -- Don’t specify patterns that do not align with your use case, e.g. inappropriate intervals between valid values +
+
+
    +
  • Do consider special cases such as zero, negative numbers and very large numbers to ensure all possible inputs are handled correctly
    • +
+
+
+
    +
  • Don’t specify patterns that do not align with your use case, e.g. inappropriate intervals between valid values
    • +
+
+
## Related diff --git a/docs/components/input-time/guide.mdx b/docs/components/input-time/guide.mdx index 844cd2db6..7705e7af9 100644 --- a/docs/components/input-time/guide.mdx +++ b/docs/components/input-time/guide.mdx @@ -33,6 +33,7 @@ Time inputs are typically used in forms, filters and scheduling tools to ensure - **Header**: Hide the header when there is a label on the input, or if the context is conveyed in another way. - **Corners** - **Standalone appearance** + ## Behavior in context - **Interaction**: @@ -55,19 +56,19 @@ 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 -- Do ensure the time picker is accessible via keyboard -- Do consider localization to adapt time formats to local conventions - +
+
+
    +
  • Do use consistent time formats throughout the application to avoid confusion
    • +
  • Do add helper text to clarify the time format being used
    • +
  • Do ensure the time picker is accessible via keyboard
    • +
  • Do consider localization to adapt time formats to local conventions
    • +
-
- -- Don’t use the same input for start and end times, instead separate them - +
+
    +
  • Don’t use the same input for start and end times, instead separate them
    • +
@@ -79,4 +80,4 @@ Time input has five states: Default, hover, disabled, read-only and focused. - [Forms field](../forms-field) - [Validation](../forms-validation) - [Writing guidelines for date and time](../../guidelines/language/formatting/date.mdx) -- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/) \ No newline at end of file +- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/) diff --git a/docs/components/input/guide.md b/docs/components/input/guide.md index 5daa4ae07..e9ddc5a49 100644 --- a/docs/components/input/guide.md +++ b/docs/components/input/guide.md @@ -43,11 +43,13 @@ The input field has five states: default, focused, hover, disabled and read-only ## Dos and Don’ts -- Do use helper text to guide users through the input process -- Do use feedback text to inform users about the status of their input -- Do ensure that the width of the input field is appropriate for the expected content -- Don’t overcrowd the input field with too many elements -- Don’t use placeholders as a substitute for labels +
+
+
    +
  • Do ensure that the width of the input field is appropriate for the expected content
    • +
+
+
## Related diff --git a/docs/components/line-chart/overview.mdx b/docs/components/line-chart/overview.mdx index 792439991..1793eeba8 100644 --- a/docs/components/line-chart/overview.mdx +++ b/docs/components/line-chart/overview.mdx @@ -31,10 +31,20 @@ Advanced line charts are an enhanced version of basic line charts, designed to p ## Dos and Don’ts -- Do start the Y-axis at zero and label axes clearly -- Do use contrasting colors for multiple lines to better distinguish different data series -- Do use consistent intervals on axes -- Do highlight important data points -- Do use visual cues to show gaps in data -- Don’t overcrowd the chart with colors -- Don’t clutter the chart with too many lines, we recommend no more than 7 lines +
+
+
    +
  • Do start the Y-axis at zero and label axes clearly
    • +
  • Do use contrasting colors for multiple lines to better distinguish different data series
    • +
  • Do use consistent intervals on axes
    • +
  • Do highlight important data points
    • +
  • Do use visual cues to show gaps in data
    • +
+
+
+
    +
  • Don’t overcrowd the chart with colors
    • +
  • Don’t clutter the chart with too many lines, we recommend no more than 7 lines
    • +
+
+
diff --git a/docs/components/link-button/guide.md b/docs/components/link-button/guide.md index 09be98abb..2faf21472 100644 --- a/docs/components/link-button/guide.md +++ b/docs/components/link-button/guide.md @@ -41,6 +41,16 @@ Link buttons take five states: Default, hover, active, disabled and focused. On ## Dos and Don’ts -- Do use link buttons for navigation -- Don’t use link buttons to indicate actions -- Don’t place link buttons within a paragraph \ No newline at end of file +
+
+
    +
  • Do use link buttons for navigation
    • +
+
+
+
    +
  • Don’t use link buttons to indicate actions
    • +
  • Don’t place link buttons within a paragraph
    • +
+
+
diff --git a/docs/components/loading-modal/guide.md b/docs/components/loading-modal/guide.md index 79aa7de81..cf68c3d39 100644 --- a/docs/components/loading-modal/guide.md +++ b/docs/components/loading-modal/guide.md @@ -30,18 +30,18 @@ Loading modals have two states: Closed and opened. ## Dos and Don’ts -
-
- -- Do only use if any user interaction needs to be blocked, otherwise use [spinners](../spinner) instead -- Do use if user interaction needs to be blocked and the progress is unknown, otherwise use [progress indicators](../progress-indicator) placed in [custom modals](../modal) instead - +
+
+
    +
  • Do only use if any user interaction needs to be blocked, otherwise use [spinners](../spinner) instead
    • +
  • Do use if user interaction needs to be blocked and the progress is unknown, otherwise use [progress indicators](../progress-indicator) placed in [custom modals](../modal) instead
    • +
-
- -- Don’t block users for long tasks without an alternative -- Don’t show vague messages that leave users unsure what is happening - +
+
    +
  • Don’t block users for long tasks without an alternative
    • +
  • Don’t show vague messages that leave users unsure what is happening
    • +
diff --git a/docs/components/message-modal/guide.md b/docs/components/message-modal/guide.md index 97ec36ead..0af4a8129 100644 --- a/docs/components/message-modal/guide.md +++ b/docs/components/message-modal/guide.md @@ -1,81 +1,81 @@ ---- -doc-type: 'tab-item' ---- - -import { IxButton } from '@siemens/ix-react'; - -# Message modal - usage - -Message modals present short messages, confirmations or important alerts that require a decision or acknowledgment. Use them for confirmations, simple decisions and critical alerts that need user action before proceeding. - -![Message modal](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7349-215&t=WHbXyipgpGwQbVsV-4) - -1. Icon -2. Title -3. Close button -4. Message -5. Cancel action -6. Confirm action - -## Variants - -- **Error:** Use for system failures, validation issues or blocking errors. -- **Info:** Use for neutral information, instructions or notifications. -- **Question:** Use for confirmations requiring user decisions. -- **Success:** Use for completed actions when another action is needed, e.g. download backup or copy generated link. -- **Warning:** Use for potential issues or action consequences, e.g. overwrite files. - -![Message modal variants](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7376-535&t=APgwguIwWKMbj5sA-4) - -## Options - -- **Title:** Use a clear, outcome-oriented title (e.g. "Delete item", see [writing guidelines](/docs/guidelines/language/dialogs-and-buttons)). -- **Message:** Include if you need to provide additional information, e.g. consequences (see [writing guidelines](/docs/guidelines/language/messaging/error-messages)). -- **Confirm action:** Use precise action text, e.g. "Delete", "Confirm", or "Continue". -- **Cancel action:** Use "Cancel" or "Close". We recommend returning to the previous context the user was in. -- **Close on backdrop click:** Enable clicking on the backdrop to close modals for informational messages. Disable for critical decisions that require confirmation. - -Note that the choice of button variant is independent from the modal variant, e.g.: - -| Visual | Content and buttons | -| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| ![Error](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7351-3560&t=WHbXyipgpGwQbVsV-4) | **Title:** A system error occurred
**Variant:** Error
**Buttons:** Subtle primary button "Reload" and primary button "Try again" | -| ![Question delete](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7351-3731&t=WHbXyipgpGwQbVsV-4) | **Title:** Deleting this item cannot be undone
**Variant:** Question
**Buttons:** Primary danger button "Delete" and primary ghost button "Cancel" | -| ![Question discard](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7351-3947&t=WHbXyipgpGwQbVsV-4) | **Title:** Do you want to save your changes before leaving?
**Variant:** Question
**Buttons:** Primary button "Save changes", secondary button "Cancel" and tertiary button "Discard" | - -Since our web component offers a predefined cancel and confirm action use [modals](../modal) if you intend to adapt the button arrangement or variants. - -## Behavior in context - -- **Interaction:** See [custom modal behavior](../modal/guide.md#behavior-in-context). -- **Placement:** Horizontally centered, vertically top-aligned. - -## States - -Message modals have two states: Closed and opened. - -## Dos and Don’ts - -
-
- -- Do use action labels that describe the result (avoid Yes or No) -- Do communicate consequences clearly for destructive actions -- Do keep messages short and scannable - -
-
- -- Don’t use message modals for non-essential information, use [toasts](../toast) instead -- Don’t hide confirm actions behind ambiguous labels - -
-
- -## Related - -- [Custom modal](../modal) -- [Loading modal](../loading-modal) -- [Toast](../toast) -- [Message bar](../messagebar) +--- +doc-type: 'tab-item' +--- + +import { IxButton } from '@siemens/ix-react'; + +# Message modal - usage + +Message modals present short messages, confirmations or important alerts that require a decision or acknowledgment. Use them for confirmations, simple decisions and critical alerts that need user action before proceeding. + +![Message modal](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7349-215&t=WHbXyipgpGwQbVsV-4) + +1. Icon +2. Title +3. Close button +4. Message +5. Cancel action +6. Confirm action + +## Variants + +- **Error:** Use for system failures, validation issues or blocking errors. +- **Info:** Use for neutral information, instructions or notifications. +- **Question:** Use for confirmations requiring user decisions. +- **Success:** Use for completed actions when another action is needed, e.g. download backup or copy generated link. +- **Warning:** Use for potential issues or action consequences, e.g. overwrite files. + +![Message modal variants](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7376-535&t=APgwguIwWKMbj5sA-4) + +## Options + +- **Title:** Use a clear, outcome-oriented title (e.g. "Delete item", see [writing guidelines](/docs/guidelines/language/dialogs-and-buttons)). +- **Message:** Include if you need to provide additional information, e.g. consequences (see [writing guidelines](/docs/guidelines/language/messaging/error-messages)). +- **Confirm action:** Use precise action text, e.g. "Delete", "Confirm", or "Continue". +- **Cancel action:** Use "Cancel" or "Close". We recommend returning to the previous context the user was in. +- **Close on backdrop click:** Enable clicking on the backdrop to close modals for informational messages. Disable for critical decisions that require confirmation. + +Note that the choice of button variant is independent from the modal variant, e.g.: + +| Visual | Content and buttons | +| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| ![Error](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7351-3560&t=WHbXyipgpGwQbVsV-4) | **Title:** A system error occurred
**Variant:** Error
**Buttons:** Subtle primary button "Reload" and primary button "Try again" | +| ![Question delete](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7351-3731&t=WHbXyipgpGwQbVsV-4) | **Title:** Deleting this item cannot be undone
**Variant:** Question
**Buttons:** Primary danger button "Delete" and primary ghost button "Cancel" | +| ![Question discard](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7351-3947&t=WHbXyipgpGwQbVsV-4) | **Title:** Do you want to save your changes before leaving?
**Variant:** Question
**Buttons:** Primary button "Save changes", secondary button "Cancel" and tertiary button "Discard" | + +Since our web component offers a predefined cancel and confirm action use [modals](../modal) if you intend to adapt the button arrangement or variants. + +## Behavior in context + +- **Interaction:** See [custom modal behavior](../modal/guide.md#behavior-in-context). +- **Placement:** Horizontally centered, vertically top-aligned. + +## States + +Message modals have two states: Closed and opened. + +## Dos and Don’ts + +
+
+
    +
  • Do use action labels that describe the result (avoid Yes or No)
    • +
  • Do communicate consequences clearly for destructive actions
    • +
  • Do keep messages short and scannable
    • +
+
+
+
    +
  • Don’t use message modals for non-essential information, use [toasts](../toast) instead
    • +
  • Don’t hide confirm actions behind ambiguous labels
    • +
+
+
+ +## Related + +- [Custom modal](../modal) +- [Loading modal](../loading-modal) +- [Toast](../toast) +- [Message bar](../messagebar) - [Accessibility](../../guidelines/accessibility) \ No newline at end of file diff --git a/docs/components/modal/guide.md b/docs/components/modal/guide.md index ca30888c0..7ea59068b 100644 --- a/docs/components/modal/guide.md +++ b/docs/components/modal/guide.md @@ -1,86 +1,86 @@ ---- -doc-type: 'tab-item' ---- - -# Custom modal - Usage - -Custom modals present rich, contextual content, e.g. forms, complex workflows or nested interactions that require the user's focus. - -Use custom models when a task requires immediate attention and the user returns to the same place after closing the modal. - -![Modal overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7350-2529&t=WHbXyipgpGwQbVsV-4) - -1. Title -2. Close button -3. Modal header -4. Modal content -5. Modal footer - -## Options - -- **Centered**: Center content by default; use top alignment for tall dialogs that expand during interaction. -- **Size**: Choose an appropriate size based on context and device: - - **Fixed max-width (360-840px):** Use as default for most layouts. Note that on narrower screens or viewports, the modal scales down and becomes proportionally narrower to fit the available space. - - **Full width:** Use for data-heavy interfaces on desktop, e.g. large datasets. - - **Full screen:** Since the modal container covers the whole [application](../application) (including [menu](../application-menu) and [header](../application-header)), use for immersive experiences or multi-step workflows. Note that users have no visual connection to the app which is why we recommend establishing it in the title or content. -- **Backdrop**: Use a backdrop to focus attention and prevent background interaction. -- **Animation**: By default, modals fade in. Disable for performance-sensitive contexts. -- **Is non-blocking**: Hides the backdrop. Use to allow interaction with the background content while the modal is open, e.g. to copy data from the page into the modal. -- **Close on backdrop click**: Enable clicking on the backdrop to close modals for informational messages. Disable for critical decisions that require confirmation. -- **Before dismiss**: Add follow-up actions when users try to close modals, e.g. add a confirmation prompt to avoid unintentional discarding of inputs when closing. -- **Modal header:** - - **Title**: Use a short, specific title that describes the task or decision. - - **Icon and icon color:** Repeat icons from the trigger to establish a connection (e.g. if a button with label and icon opens the modal then reuse the same label and icon). Use [iX theme colors](../../styles/colors). - - **Hide close**: We recommend only hiding the close button for critical flows that require an explicit decision. -- **Modal footer:** Place one primary, one secondary and optionally one tertiary [button](../button) on the right side to follow the Z-shape reading pattern in left-to-right languages. - -## Behavior in context - -- **Interaction:** - - Modals are opened by the system (e.g. when another process finishes) or by users (e.g. when clicking buttons). - - Modals are closed: - - When clicking on close or on buttons in the footer (typically cancel or confirm). - - When pressing the Escape key. - - If enabled, when clicking outside the modal (on the backdrop). - - Focus moves into the modal when it opens and returns to the trigger when it closes. -- **Overflow:** - - The modal height increases with content until reaching screen height, then a scrollbar appears. - - We recommend implementing a sticky footer when content overflows. - - Avoid horizontal scrollbars by using a larger modal size and defining adaptive behaviors for different viewports. -- **Placement:** Vertically centered or top-aligned, horizontally centered. -- **Responsiveness:** - - Height: Depends on its content except for `full-screen`. - - Content: Needs to be built responsively to adapt with the container's width. - -## States - -Modals have two states: Closed and opened. - -## Dos and Don’ts - -
-
- -- Do provide at least one visible way to close the modal -- Do provide a clear primary action that describes the result -- Do ensure all controls are accessible by keyboard and screen‑reader -- Do preserve scroll position and page state when closing -- Do return users to the previous state when cancelling, not an unrelated page - -
-
- -- Don’t use modals if a decision should be made (use [message modals](../message-modal) instead) -- Don’t nest modals, e.g. to load more data, instead use [spinners](../spinner) within modal contents) -- Don’t auto close modals for irreversible actions -- Don’t overload the modal with unrelated content - -
-
- -## Related - -- [Message modal](../message-modal) -- [Loading modal](../loading-modal) -- [Forms field](../forms-field) -- [Accessibility](../../guidelines/accessibility) +--- +doc-type: 'tab-item' +--- + +# Custom modal - Usage + +Custom modals present rich, contextual content, e.g. forms, complex workflows or nested interactions that require the user's focus. + +Use custom models when a task requires immediate attention and the user returns to the same place after closing the modal. + +![Modal overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7350-2529&t=WHbXyipgpGwQbVsV-4) + +1. Title +2. Close button +3. Modal header +4. Modal content +5. Modal footer + +## Options + +- **Centered**: Center content by default; use top alignment for tall dialogs that expand during interaction. +- **Size**: Choose an appropriate size based on context and device: + - **Fixed max-width (360-840px):** Use as default for most layouts. Note that on narrower screens or viewports, the modal scales down and becomes proportionally narrower to fit the available space. + - **Full width:** Use for data-heavy interfaces on desktop, e.g. large datasets. + - **Full screen:** Since the modal container covers the whole [application](../application) (including [menu](../application-menu) and [header](../application-header)), use for immersive experiences or multi-step workflows. Note that users have no visual connection to the app which is why we recommend establishing it in the title or content. +- **Backdrop**: Use a backdrop to focus attention and prevent background interaction. +- **Animation**: By default, modals fade in. Disable for performance-sensitive contexts. +- **Is non-blocking**: Hides the backdrop. Use to allow interaction with the background content while the modal is open, e.g. to copy data from the page into the modal. +- **Close on backdrop click**: Enable clicking on the backdrop to close modals for informational messages. Disable for critical decisions that require confirmation. +- **Before dismiss**: Add follow-up actions when users try to close modals, e.g. add a confirmation prompt to avoid unintentional discarding of inputs when closing. +- **Modal header:** + - **Title**: Use a short, specific title that describes the task or decision. + - **Icon and icon color:** Repeat icons from the trigger to establish a connection (e.g. if a button with label and icon opens the modal then reuse the same label and icon). Use [iX theme colors](../../styles/colors). + - **Hide close**: We recommend only hiding the close button for critical flows that require an explicit decision. +- **Modal footer:** Place one primary, one secondary and optionally one tertiary [button](../button) on the right side to follow the Z-shape reading pattern in left-to-right languages. + +## Behavior in context + +- **Interaction:** + - Modals are opened by the system (e.g. when another process finishes) or by users (e.g. when clicking buttons). + - Modals are closed: + - When clicking on close or on buttons in the footer (typically cancel or confirm). + - When pressing the Escape key. + - If enabled, when clicking outside the modal (on the backdrop). + - Focus moves into the modal when it opens and returns to the trigger when it closes. +- **Overflow:** + - The modal height increases with content until reaching screen height, then a scrollbar appears. + - We recommend implementing a sticky footer when content overflows. + - Avoid horizontal scrollbars by using a larger modal size and defining adaptive behaviors for different viewports. +- **Placement:** Vertically centered or top-aligned, horizontally centered. +- **Responsiveness:** + - Height: Depends on its content except for `full-screen`. + - Content: Needs to be built responsively to adapt with the container's width. + +## States + +Modals have two states: Closed and opened. + +## Dos and Don’ts + +
+
+
    +
  • Do provide at least one visible way to close the modal
    • +
  • Do provide a clear primary action that describes the result
    • +
  • Do ensure all controls are accessible by keyboard and screen‑reader
    • +
  • Do preserve scroll position and page state when closing
    • +
  • Do return users to the previous state when cancelling, not an unrelated page
    • +
+
+
+
    +
  • Don’t use modals if a decision should be made (use [message modals](../message-modal) instead)
    • +
  • Don’t nest modals, e.g. to load more data, instead use [spinners](../spinner) within modal contents)
    • +
  • Don’t auto close modals for irreversible actions
    • +
  • Don’t overload the modal with unrelated content
    • +
+
+
+ +## Related + +- [Message modal](../message-modal) +- [Loading modal](../loading-modal) +- [Forms field](../forms-field) +- [Accessibility](../../guidelines/accessibility) diff --git a/docs/components/panes/guide.md b/docs/components/panes/guide.md index 109a59392..b2b91b808 100644 --- a/docs/components/panes/guide.md +++ b/docs/components/panes/guide.md @@ -52,11 +52,21 @@ Panes have two states: collapsed and expanded. The appearance of the states vari ## Dos and Don’ts -- Do use panes to organize your content and guide your users' attention -- Do use panes to display different views within a single screen -- Do use panes to expand/collapse content or hide/reveal content -- Don’t use panes for a small amount of content -- Don’t use panes for content that should stay visible +
+
+
    +
  • Do use panes to organize your content and guide your users' attention
    • +
  • Do use panes to display different views within a single screen
    • +
  • Do use panes to expand/collapse content or hide/reveal content
    • +
+
+
+
    +
  • Don’t use panes for a small amount of content
    • +
  • Don’t use panes for content that should stay visible
    • +
+
+
## Related diff --git a/docs/components/pill/guide.md b/docs/components/pill/guide.md index 4c9b62ece..e5a81a909 100644 --- a/docs/components/pill/guide.md +++ b/docs/components/pill/guide.md @@ -45,11 +45,21 @@ Pills are read-only. ## Dos and Don’ts -- Do use pills to communicate tags and categories -- Do use pills to indicate the status or characteristics of an item -- Don’t overuse pills as this leads to cluttered and overwhelming interfaces -- Don’t use different styles for pills with the same or similar use -- Don’t use pills if users can interact with the component (e.g. click, close) use chips instead +
+
+
    +
  • Do use pills to communicate tags and categories
    • +
  • Do use pills to indicate the status or characteristics of an item
    • +
+
+
+
    +
  • Don’t overuse pills as this leads to cluttered and overwhelming interfaces
    • +
  • Don’t use different styles for pills with the same or similar use
    • +
  • Don’t use pills if users can interact with the component (e.g. click, close) use chips instead
    • +
+
+
## Related diff --git a/docs/components/popover-news/guide.md b/docs/components/popover-news/guide.md index c29bd6aa6..3ac9f13f5 100644 --- a/docs/components/popover-news/guide.md +++ b/docs/components/popover-news/guide.md @@ -26,9 +26,13 @@ Unlike a modal, popover news does not prevent users from navigating and interact ## Dos and Don’ts -- Do use popover news for "nice to know" information -- Don‘t use popover news for essential information a user must read, instead use a [modal](../messagebar) -- Don‘t use popover news for system feedback or messages, instead use a [modal](../toast) +
+
+
    +
  • Do use popover news for "nice to know" information
    • +
+
+
## Related diff --git a/docs/components/progress-indicator/guide.md b/docs/components/progress-indicator/guide.md index a3d445917..e75cdd18e 100644 --- a/docs/components/progress-indicator/guide.md +++ b/docs/components/progress-indicator/guide.md @@ -53,20 +53,20 @@ 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)) -- Do use linear progress indicators in horizontal layouts and circular indicators in compact spaces or centered layouts -- Do keep your slot content short, especially for the centered alignment (use helper texts and labels for lengthier content) - +
+
+
    +
  • 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))
    • +
  • Do use linear progress indicators in horizontal layouts and circular indicators in compact spaces or centered layouts
    • +
  • 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 - +
+
    +
  • 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/radio/guide.md b/docs/components/radio/guide.md index 16bfe11ed..40c6fa6f8 100644 --- a/docs/components/radio/guide.md +++ b/docs/components/radio/guide.md @@ -33,11 +33,21 @@ Radio buttons are presented in groups to signify that only one selection is allo ## Dos and Don’ts -- Do use radio buttons when the user needs to select only one option from a set of options -- Do group related radio buttons together to indicate that only one option can be selected at a time -- Do provide a default (already selected) option when the user first sees the radio button group -- Don’t use radio buttons if the user needs to select multiple options from a set of options - use a checkbox instead -- Don’t use only one radio button in a group, groups should have at least two options +
+
+
    +
  • Do use radio buttons when the user needs to select only one option from a set of options
    • +
  • Do group related radio buttons together to indicate that only one option can be selected at a time
    • +
  • Do provide a default (already selected) option when the user first sees the radio button group
    • +
+
+
+
    +
  • Don’t use radio buttons if the user needs to select multiple options from a set of options - use a checkbox instead
    • +
  • Don’t use only one radio button in a group, groups should have at least two options
    • +
+
+
## Related diff --git a/docs/components/range-field/guide.md b/docs/components/range-field/guide.md index 97bc9acf4..789f40a06 100644 --- a/docs/components/range-field/guide.md +++ b/docs/components/range-field/guide.md @@ -42,13 +42,23 @@ Range fields rely on the states of the paired inputs. Use the same guidance as [ ## Dos and Don’ts -- Do use range fields when start and end values describe one bounded interval -- Do label both inputs clearly so users can scan the order quickly -- Do omit labels on both inputs consistently when the surrounding context already makes the range clear -- Do validate that the end value is not smaller or earlier than the start value -- Don’t use range fields for single values or unrelated inputs -- Don’t use different input types, formats or levels of precision within one range -- Don’t mix date, time and date-time inputs in one range +
+
+
    +
  • Do use range fields when start and end values describe one bounded interval
    • +
  • Do label both inputs clearly so users can scan the order quickly
    • +
  • Do omit labels on both inputs consistently when the surrounding context already makes the range clear
    • +
  • Do validate that the end value is not smaller or earlier than the start value
    • +
+
+
+
    +
  • Don’t use range fields for single values or unrelated inputs
    • +
  • Don’t use different input types, formats or levels of precision within one range
    • +
  • Don’t mix date, time and date-time inputs in one range
    • +
+
+
## Related diff --git a/docs/components/select/guide.md b/docs/components/select/guide.md index f7fcc63ca..23824c3fb 100644 --- a/docs/components/select/guide.md +++ b/docs/components/select/guide.md @@ -59,12 +59,22 @@ The select field has five states: default, hover, focused, disabled and read-onl ## Dos and Don’ts -- Do consider performance when loading an extensive list of items -- Do use the select component when there is a finite list of items available to avoid manual input errors or duplicates -- Do sort items logically, e.g. alphabetically or numerically -- Don’t use selects for binary choices, like yes and no, use [radio buttons](../toggle) instead -- Don’t use selects for navigational or search patterns, use [category filters](../expanding-search) instead -- Don’t combine several data attributes in an item label, use [HTML tables](../html-grid) or [AG Grids](../grid) with a search functionality instead +
+
+
    +
  • Do consider performance when loading an extensive list of items
    • +
  • Do use the select component when there is a finite list of items available to avoid manual input errors or duplicates
    • +
  • Do sort items logically, e.g. alphabetically or numerically
    • +
+
+
+
    +
  • Don’t use selects for binary choices, like yes and no, use [radio buttons](../toggle) instead
    • +
  • Don’t use selects for navigational or search patterns, use [category filters](../expanding-search) instead
    • +
  • Don’t combine several data attributes in an item label, use [HTML tables](../html-grid) or [AG Grids](../grid) with a search functionality instead
    • +
+
+
![Don’t combine data attributes](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3978-800&t=MWpyPDZDK5B531n9-4) diff --git a/docs/components/split-button/guide.md b/docs/components/split-button/guide.md index 9c538bd81..86dc0a123 100644 --- a/docs/components/split-button/guide.md +++ b/docs/components/split-button/guide.md @@ -33,9 +33,19 @@ Split buttons have five states: Default, hover, active, disabled and focused. St ## Dos and Don’ts -- Do use split buttons when there is a frequent or most-important action -- Don’t use split buttons for unrelated actions -- Don’t duplicate the default option in the dropdown +
+
+
    +
  • Do use split buttons when there is a frequent or most-important action
    • +
+
+
+
    +
  • Don’t use split buttons for unrelated actions
    • +
  • Don’t duplicate the default option in the dropdown
    • +
+
+
## Related diff --git a/docs/components/textarea/guide.md b/docs/components/textarea/guide.md index ccf528982..129e0acb4 100644 --- a/docs/components/textarea/guide.md +++ b/docs/components/textarea/guide.md @@ -54,10 +54,20 @@ Textareas have five states: Default, hover, focused, read-only and disabled. ## Dos and Don’ts -- Do ensure the textarea size matches the expected input, e.g. 5 to 10 rows for detailed feedback -- Do use the placeholder to give users an example of the expected input -- Do set minimum and maximum character limits to ensure appropriate input length -- Don’t use the textarea for short, single-line input like name or email address, use an [input field](../input) instead +
+
+
    +
  • Do ensure the textarea size matches the expected input, e.g. 5 to 10 rows for detailed feedback
    • +
  • Do use the placeholder to give users an example of the expected input
    • +
  • Do set minimum and maximum character limits to ensure appropriate input length
    • +
+
+
+
    +
  • Don’t use the textarea for short, single-line input like name or email address, use an [input field](../input) instead
    • +
+
+
## Related diff --git a/docs/components/time-picker/guide.mdx b/docs/components/time-picker/guide.mdx index e59a9ba93..6f0355d20 100644 --- a/docs/components/time-picker/guide.mdx +++ b/docs/components/time-picker/guide.mdx @@ -40,18 +40,18 @@ 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 - +
+
+
    +
  • 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 - +
+
    +
  • Don’t clutter the time picker with unnecessary options
    • +
diff --git a/docs/components/toast/guide.md b/docs/components/toast/guide.md index 80272f33d..aef594918 100644 --- a/docs/components/toast/guide.md +++ b/docs/components/toast/guide.md @@ -42,12 +42,22 @@ Toasts are UI elements where an event causes a small text field to appear on scr ## Dos and Don’ts -- Do use toasts to provide contextual tips and shortcuts for users -- Do use toasts to instantly inform a user about the outcome of an action -- Do include shortcuts to undo an action immediately after it’s taken -- Do stick with a consistent position for toasts within the same app and avoid interchanging their positions -- Don’t use toasts for high-priority or critical alerts that prevent the user from continuing their work (use a [modal](../messagebar) instead) -- Don’t edit or reuse icons or icon colors from the four predefined toast types when creating custom toasts +
+
+
    +
  • Do use toasts to provide contextual tips and shortcuts for users
    • +
  • Do use toasts to instantly inform a user about the outcome of an action
    • +
  • Do include shortcuts to undo an action immediately after it’s taken
    • +
  • Do stick with a consistent position for toasts within the same app and avoid interchanging their positions
    • +
+
+
+
    +
  • Don’t use toasts for high-priority or critical alerts that prevent the user from continuing their work (use a [modal](../messagebar) instead)
    • +
  • Don’t edit or reuse icons or icon colors from the four predefined toast types when creating custom toasts
    • +
+
+
## Related diff --git a/docs/components/toggle-button/guide.md b/docs/components/toggle-button/guide.md index aeef7372b..0df3a18f4 100644 --- a/docs/components/toggle-button/guide.md +++ b/docs/components/toggle-button/guide.md @@ -27,9 +27,19 @@ Toggle buttons have five states: Default, hover, active, disabled, loading and f ## Dos and Don’ts -- Do use toggle buttons when users can switch a setting on or off independently -- Do use toggle buttons when two opposing options don’t follow the on/off metaphor -- Don’t use toggle buttons in button groups where only one option can be selected (use normal [buttons](../button/index.mdx) or [icon buttons](../icon-button/index.mdx) instead) +
+
+
    +
  • Do use toggle buttons when users can switch a setting on or off independently
    • +
  • Do use toggle buttons when two opposing options don’t follow the on/off metaphor
    • +
+
+
+
    +
  • Don’t use toggle buttons in button groups where only one option can be selected (use normal [buttons](../button/index.mdx) or [icon buttons](../icon-button/index.mdx) instead)
    • +
+
+
## Related diff --git a/docs/components/toggle/guide.md b/docs/components/toggle/guide.md index f8e815b88..05188bad0 100644 --- a/docs/components/toggle/guide.md +++ b/docs/components/toggle/guide.md @@ -32,12 +32,22 @@ A toggle is a user interface element that enables users to switch between two st ## Dos and Don’ts -- Do use toggles for single features or options that need to be switched quickly and easily -- Do provide clear labels for toggles to indicate what they control -- Do use toggles consistently throughout the interface for similar actions or settings -- Don’t use toggles for complex multi-state options or settings -- Don’t use toggles for actions that require a confirmation or additional input -- Don’t use toggles for actions that are irreversible or have serious consequences +
+
+
    +
  • Do use toggles for single features or options that need to be switched quickly and easily
    • +
  • Do provide clear labels for toggles to indicate what they control
    • +
  • Do use toggles consistently throughout the interface for similar actions or settings
    • +
+
+
+
    +
  • Don’t use toggles for complex multi-state options or settings
    • +
  • Don’t use toggles for actions that require a confirmation or additional input
    • +
  • Don’t use toggles for actions that are irreversible or have serious consequences
    • +
+
+
## Related diff --git a/docs/guidelines/conversational-design/designing-conversations/acknowledging-users.md b/docs/guidelines/conversational-design/designing-conversations/acknowledging-users.md index bf0e7f890..ed8483672 100644 --- a/docs/guidelines/conversational-design/designing-conversations/acknowledging-users.md +++ b/docs/guidelines/conversational-design/designing-conversations/acknowledging-users.md @@ -27,7 +27,17 @@ Here, although there may be some lag time between the query and the response, th ## Dos and Don’ts -- Do use discourse markers to acknowledge users (see grammar section) -- Do use interim acknowledgments if the query response takes time to load -- Do read out dialogs to test if any acknowledgments are naturally missing -- Don’t forget to balance efficiency with authenticity +
+
+
    +
  • Do use discourse markers to acknowledge users (see grammar section)
    • +
  • Do use interim acknowledgments if the query response takes time to load
    • +
  • Do read out dialogs to test if any acknowledgments are naturally missing
    • +
+
+
+
    +
  • Don’t forget to balance efficiency with authenticity
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md b/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md index 64357e540..7e7901a13 100644 --- a/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md +++ b/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md @@ -30,8 +30,18 @@ Finally, in the face of truly unprofessional and offensive input, the following **Copilot:** As an AI language model, I don’t have personal opinions or feelings, but I am designed to follow ethical guidelines. I **do not** engage in discussions or create content that promotes racism, sexism, or any form of discrimination. If you encounter any inappropriate responses, please let me know, and I'll do my best to address them. ## Dos and Don’ts -- Do consider training your chatbot to filter for a list of offensive terms -- Do consider localization and cultural nuances, such as “master” and “slave” -- Do train your chatbot to move users back on track -- Don’t forget to test and train for offensive user input -- Don’t forget to allow for some harmless non-work interactions +
+
+
    +
  • Do consider training your chatbot to filter for a list of offensive terms
    • +
  • Do consider localization and cultural nuances, such as “master” and “slave”
    • +
  • Do train your chatbot to move users back on track
    • +
+
+
+
    +
  • Don’t forget to test and train for offensive user input
    • +
  • Don’t forget to allow for some harmless non-work interactions
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/confirming-request.md b/docs/guidelines/conversational-design/designing-conversations/confirming-request.md index 787972463..88776c48e 100644 --- a/docs/guidelines/conversational-design/designing-conversations/confirming-request.md +++ b/docs/guidelines/conversational-design/designing-conversations/confirming-request.md @@ -23,7 +23,17 @@ In this interaction we see a simple request for confirmation before completing t ## Dos and Don’ts -- Do make all confirmations clear and transparent before processing tasks -- Do mitigate risks associated with making changes to systems or processes -- Do add warnings and consequences for significant or hazardous changes -- Don’t ask for confirmation more than once +
+
+
    +
  • Do make all confirmations clear and transparent before processing tasks
    • +
  • Do mitigate risks associated with making changes to systems or processes
    • +
  • Do add warnings and consequences for significant or hazardous changes
    • +
+
+
+
    +
  • Don’t ask for confirmation more than once
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md b/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md index 46ee7144d..d246d85c2 100644 --- a/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md +++ b/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md @@ -27,7 +27,17 @@ Here the chatbot offers an apology for not being able to support the user, expla ## Dos and Don’ts -- Do consider adding a time-out feature -- Do consider adding thumbs up and thumbs down icons to get feedback -- Don’t loop back and have the chatbot reintroduce themselves +
+
+
    +
  • Do consider adding a time-out feature
    • +
  • Do consider adding thumbs up and thumbs down icons to get feedback
    • +
+
+
+
    +
  • Don’t loop back and have the chatbot reintroduce themselves
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/funneling-input.md b/docs/guidelines/conversational-design/designing-conversations/funneling-input.md index 9a3d6897a..52d51127a 100644 --- a/docs/guidelines/conversational-design/designing-conversations/funneling-input.md +++ b/docs/guidelines/conversational-design/designing-conversations/funneling-input.md @@ -33,6 +33,16 @@ Presenting options or choices for the user to select from also helps to funnel q ## Dos and Don’ts -- Do train your chatbot to guide users to their point -- Do test your chatbot with vague queries -- Don’t assume users know what to ask for +
+
+
    +
  • Do train your chatbot to guide users to their point
    • +
  • Do test your chatbot with vague queries
    • +
+
+
+
    +
  • Don’t assume users know what to ask for
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/greeting-users.md b/docs/guidelines/conversational-design/designing-conversations/greeting-users.md index c8caa9959..db951bb46 100644 --- a/docs/guidelines/conversational-design/designing-conversations/greeting-users.md +++ b/docs/guidelines/conversational-design/designing-conversations/greeting-users.md @@ -31,7 +31,17 @@ This chatbot is less formal, more conversational and would be found within more ## Dos and Don’ts -- Do keep your greeting short and simple -- Do check every word matches your brand -- Don’t add a list of bullet points explaining what the chatbot can do -- Don’t use slang or idiomatic language in your greeting +
+
+
    +
  • Do keep your greeting short and simple
    • +
  • Do check every word matches your brand
    • +
+
+
+
    +
  • Don’t add a list of bullet points explaining what the chatbot can do
    • +
  • Don’t use slang or idiomatic language in your greeting
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/handing-off-users.md b/docs/guidelines/conversational-design/designing-conversations/handing-off-users.md index aab5ff298..c1d6a45cb 100644 --- a/docs/guidelines/conversational-design/designing-conversations/handing-off-users.md +++ b/docs/guidelines/conversational-design/designing-conversations/handing-off-users.md @@ -19,6 +19,16 @@ Here the chatbot is polite, professional and after a couple of clarifying questi ## Dos and Don’ts -- Do ensure support features are current and live -- Do be transparent when your chatbot is handing users over -- Don’t try more than 3 times to ask for clarification; know when to hand off +
+
+
    +
  • Do ensure support features are current and live
    • +
  • Do be transparent when your chatbot is handing users over
    • +
+
+
+
    +
  • Don’t try more than 3 times to ask for clarification; know when to hand off
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/handling-errors.md b/docs/guidelines/conversational-design/designing-conversations/handling-errors.md index 9d300614e..f09fccaec 100644 --- a/docs/guidelines/conversational-design/designing-conversations/handling-errors.md +++ b/docs/guidelines/conversational-design/designing-conversations/handling-errors.md @@ -22,7 +22,17 @@ Here the chatbot is immediately apologetic and tells the user they cannot comple Here, although it’s clear what the user wants, they can’t give the chatbot the information it needs to fulfill the request. In this situation, the chatbot immediately says they cannot carry out the task, explains why, and then tells the user where to find a solution. We recommend this three-step approach for chatbot responses and for error messages in general. ## Dos and Don’ts -- Do assume your chatbot makes mistakes -- Do try to ‘break’ your chatbot in testing -- Do train your chatbot to tell users immediately if they cannot complete a task -- Don’t forget to add a disclaimer stating that information could be incorrect +
+
+
    +
  • Do assume your chatbot makes mistakes
    • +
  • Do try to ‘break’ your chatbot in testing
    • +
  • Do train your chatbot to tell users immediately if they cannot complete a task
    • +
+
+
+
    +
  • Don’t forget to add a disclaimer stating that information could be incorrect
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/overview.md b/docs/guidelines/conversational-design/designing-conversations/overview.md index fef3d3e69..b12f7cfbb 100644 --- a/docs/guidelines/conversational-design/designing-conversations/overview.md +++ b/docs/guidelines/conversational-design/designing-conversations/overview.md @@ -34,9 +34,19 @@ Use your dialogs to highlight the complex interactions required for your industr 4. You have your own brand voice and tone guidelines ## Dos and Don’ts -- Do create example conversations based on user personas -- Do focus on industrial-relevant communicative functions -- Do offer users an exit or calls to action to support further actions -- Don’t forget to read aloud your dialogs; if it sounds robotic, it is robotic -- Don’t create lengthy monologues, instead keep responses concise and simple +
+
+
    +
  • Do create example conversations based on user personas
    • +
  • Do focus on industrial-relevant communicative functions
    • +
  • Do offer users an exit or calls to action to support further actions
    • +
+
+
+
    +
  • Don’t forget to read aloud your dialogs; if it sounds robotic, it is robotic
    • +
  • Don’t create lengthy monologues, instead keep responses concise and simple
    • +
+
+
diff --git a/docs/guidelines/conversational-design/designing-conversations/troubleshooting.md b/docs/guidelines/conversational-design/designing-conversations/troubleshooting.md index c7878edce..b3ff080e1 100644 --- a/docs/guidelines/conversational-design/designing-conversations/troubleshooting.md +++ b/docs/guidelines/conversational-design/designing-conversations/troubleshooting.md @@ -22,7 +22,18 @@ Here the chatbot says exactly what the problem is, but this response lacks empat Here the chatbot says exactly what the problem is, gives a possible reason for the lack of connection and then provides a solution to move the user forward. ## Dos and Don’ts -- Do provide calls to action when troubleshooting -- Do offer step by step solutions using technical documentation -- Don’t allow your chatbot to offer competitor solutions to their problems -- Don’t allow your chatbot to hallucinate (make up) solutions without concrete resources + +
+
+
    +
  • Do provide calls to action when troubleshooting
    • +
  • Do offer step by step solutions using technical documentation
    • +
+
+
+
    +
  • Don't allow your chatbot to offer competitor solutions to their problems
    • +
  • Don't allow your chatbot to hallucinate (make up) solutions without concrete resources
    • +
+
+
diff --git a/docs/guidelines/conversational-design/essentials/system-presonas.md b/docs/guidelines/conversational-design/essentials/system-presonas.md index 8bff6ba63..805d945d9 100644 --- a/docs/guidelines/conversational-design/essentials/system-presonas.md +++ b/docs/guidelines/conversational-design/essentials/system-presonas.md @@ -163,13 +163,23 @@ There are two persona templates: a basic set of prompts and an exhaustive set of ## Dos and Don’ts -- Do test and retest your chatbot to ensure its responses are in line with your brand -- Do predefine responses with persona prompts to avoid generic responses -- Do create different personas if the bot needs to work with multiple, varied users -- Do base system personas on user research to ensure there is a good level of customer understanding -- Don’t pretend your chatbot is human – it should be clear to your users that they’re talking to a chatbot -- Don’t encourage your chatbot to engage in unnecessary small talk with your users -- Don’t use more than a page of persona prompts – only take what’s vital and relevant from our templates +
+
+
    +
  • Do test and retest your chatbot to ensure its responses are in line with your brand
    • +
  • Do predefine responses with persona prompts to avoid generic responses
    • +
  • Do create different personas if the bot needs to work with multiple, varied users
    • +
  • Do base system personas on user research to ensure there is a good level of customer understanding
    • +
+
+
+
    +
  • Don’t pretend your chatbot is human – it should be clear to your users that they’re talking to a chatbot
    • +
  • Don’t encourage your chatbot to engage in unnecessary small talk with your users
    • +
  • Don’t use more than a page of persona prompts – only take what’s vital and relevant from our templates
    • +
+
+
diff --git a/docs/guidelines/conversational-design/essentials/user-intent.md b/docs/guidelines/conversational-design/essentials/user-intent.md index 96ae79ba1..6f45dbb57 100644 --- a/docs/guidelines/conversational-design/essentials/user-intent.md +++ b/docs/guidelines/conversational-design/essentials/user-intent.md @@ -45,8 +45,18 @@ Here we see that although the intent for maintenance is very explicit, the chatb ## Dos and Don’ts -- Do carry out extensive research on user needs and goals -- Do work with your teams to establish and predict user intent with example dialogs -- Do test your chatbot with explicit and implicit requests to assess evaluation of user intent -- Don’t assume your users will be explicit about what they need -- Don’t assume users are skilled at prompting your chatbot +
+
+
    +
  • Do carry out extensive research on user needs and goals
    • +
  • Do work with your teams to establish and predict user intent with example dialogs
    • +
  • Do test your chatbot with explicit and implicit requests to assess evaluation of user intent
    • +
+
+
+
    +
  • Don’t assume your users will be explicit about what they need
    • +
  • Don’t assume users are skilled at prompting your chatbot
    • +
+
+
diff --git a/docs/guidelines/conversational-design/essentials/wording-terms.mdx b/docs/guidelines/conversational-design/essentials/wording-terms.mdx index 209372d4e..5a00ccc25 100644 --- a/docs/guidelines/conversational-design/essentials/wording-terms.mdx +++ b/docs/guidelines/conversational-design/essentials/wording-terms.mdx @@ -33,13 +33,13 @@ 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. -- What do you want? - +
+
+
    +
  • Well, hello! I’m your friendly chatbot.
    • +
  • Welcome to chatbot. State your issue now.
    • +
  • What do you want?
    • +
@@ -47,32 +47,32 @@ 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… - +
+
+
    +
  • Enter your query here…
    • +
  • Enter a command, question or topic…
    • +
  • Enter a command, question or topic to begin…
    • +
-
- -- Ask me anything… -- Start typing… -- What’s on your mind? - +
+
    +
  • Ask me anything…
    • +
  • Start typing…
    • +
  • What’s on your mind?
    • +
Use alternative placeholder text when your chatbot has a single use case. -
-
- -- Search technical documentation… -- Enter error code… -- Search parts catalog… - +
+
+
    +
  • Search technical documentation…
    • +
  • Enter error code…
    • +
  • Search parts catalog…
    • +
@@ -80,34 +80,34 @@ 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…
    • +
-
- -- Generating response -- Creating response… - +
+
    +
  • Generating response
    • +
  • Creating response…
    • +
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
    • +
-
- -- Stop generating… -- Continue generating… - +
+
    +
  • Stop generating…
    • +
  • Continue generating…
    • +
@@ -115,27 +115,27 @@ 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). - +
+
+
    +
  • Click to start and stop voice recording.
    • +
  • Click to start and stop voice recording (max 2 minutes).
    • +
Use “Recording…” as feedback to show the feature is working. -
-
- -- Recording… - +
+
+
    +
  • Recording…
    • +
-
- -- I’m listening… - +
+
    +
  • I’m listening…
    • +
@@ -143,18 +143,18 @@ 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 () - +
+
+
    +
  • Thumbs up icon ()
    • +
  • Thumbs down icon ()
    • +
-
- -- Helpful -- Not helpful - +
+
    +
  • Helpful
    • +
  • Not helpful
    • +
@@ -162,21 +162,21 @@ 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 -- Last 7 days -- Last 30 days -- Older - +
+
+
    +
  • Today
    • +
  • Yesterday
    • +
  • Last 7 days
    • +
  • Last 30 days
    • +
  • Older
    • +
-
- -- Previous 7 days -- Prior week - +
+
    +
  • Previous 7 days
    • +
  • Prior week
    • +
@@ -192,33 +192,33 @@ 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 -- Generate new prompts -- Refresh prompts -- Show more prompts -- Attach files -- Upload files -- Share -- Copy -- Expand -- Collapse -- Maximize chat window -- Minimize chat window -- Close chat window - -
-
- -- Clear chat -- Submit -- Give me another -- Show me others -- Import files - +
+
+
    +
  • New chat
    • +
  • Send
    • +
  • Generate new prompts
    • +
  • Refresh prompts
    • +
  • Show more prompts
    • +
  • Attach files
    • +
  • Upload files
    • +
  • Share
    • +
  • Copy
    • +
  • Expand
    • +
  • Collapse
    • +
  • Maximize chat window
    • +
  • Minimize chat window
    • +
  • Close chat window
    • +
+
+
+
    +
  • Clear chat
    • +
  • Submit
    • +
  • Give me another
    • +
  • Show me others
    • +
  • Import files
    • +
@@ -239,17 +239,17 @@ Book webinar Use “sources” as the text label to indicate where the generated information is from. -
-
- -- Sources - +
+
+
    +
  • Sources
    • +
-
- -- Resources -- Sources and references - +
+
    +
  • Resources
    • +
  • Sources and references
    • +
@@ -259,12 +259,12 @@ 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) - +
+
+
    +
  • Responses generated by agent X
    • +
  • Responses generated by: agent X (with agent selection dropdown)
    • +
@@ -272,19 +272,19 @@ 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
    • +
  • Stop
    • +
-
- -- Show more! -- Send? - +
+
    +
  • Show more!
    • +
  • Send?
    • +
@@ -294,42 +294,52 @@ 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… - +
+
+
    +
  • Thinking…
    • +
  • Thinking about the best response…
    • +
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. - +
+
+
    +
  • I’m afraid that I can’t help you right now as I’m assessing the data.
    • +
  • I understand what you mean.
    • +
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. -- Please be patient. -- Bear with me. - +
+
+
    +
  • Please stand by while I process your request.
    • +
  • Please wait while I prepare a response.
    • +
  • Please be patient.
    • +
  • Bear with me.
    • +
+
+
+ +## Dos and Don’ts + +
+
+
    +
  • Do use sentence casing to align with our UX writing guidelines
    • +
  • Do ensure the voice and tone aligns with your product and our iX conversational design principles
    • +
+
+
+
    +
  • Don’t use synonyms to vary the UI wording, be consistent and use the same words repeatedly
    • +
  • Don’t use “Creating…” as the progress indicator as there is no creative process and is misleading
    • +
+
-
- -## Dos and Don’ts  - -- Do use sentence casing to align with our UX writing guidelines -- Do ensure the voice and tone aligns with your product and our iX conversational design principles -- Don’t use synonyms to vary the UI wording, be consistent and use the same words repeatedly -- Don’t use “Creating…” as the progress indicator as there is no creative process and is misleading diff --git a/docs/guidelines/conversational-design/language.md b/docs/guidelines/conversational-design/language.md index f6b40ffe1..9c4a7a903 100644 --- a/docs/guidelines/conversational-design/language.md +++ b/docs/guidelines/conversational-design/language.md @@ -110,7 +110,17 @@ Here the response is more concise, professional and shows the chatbot is aware o ## Dos and Don’ts -- Do use your brand’s voice rules to shape your chatbot voice -- Do work with developers to support data set collection -- Don’t assume your users write correctly or accurately -- Don’t forget to implement new NLP models as they advance \ No newline at end of file +
+
+
    +
  • Do use your brand’s voice rules to shape your chatbot voice
    • +
  • Do work with developers to support data set collection
    • +
+
+
+
    +
  • Don’t assume your users write correctly or accurately
    • +
  • Don’t forget to implement new NLP models as they advance
    • +
+
+
diff --git a/docs/guidelines/conversational-design/resources/chatbot-checklist.md b/docs/guidelines/conversational-design/resources/chatbot-checklist.md index 27e68f71e..58ca0a213 100644 --- a/docs/guidelines/conversational-design/resources/chatbot-checklist.md +++ b/docs/guidelines/conversational-design/resources/chatbot-checklist.md @@ -55,12 +55,23 @@ Follow these steps and answer the questions with your teams to create your indus - How do we assess the chatbot's performance? Consider response time, accuracy, successful/abandoned interactions. ## Dos and Don’ts -- Do work with all stakeholders to ensure transparency -- Do customize chatbot responses for project-specific terminology and processes -- Do consider how your chatbot hands off to humans for complex issues -- Do read and review interactions (with user consent) -- Don’t assume all chatbot interactions are successful -- Don’t forget to retrain, test and update your chatbot + +
+
+
    +
  • Do work with all stakeholders to ensure transparency
    • +
  • Do customize chatbot responses for project-specific terminology and processes
    • +
  • Do consider how your chatbot hands off to humans for complex issues
    • +
  • Do read and review interactions (with user consent)
    • +
+
+
+
    +
  • Don't assume all chatbot interactions are successful
    • +
  • Don't forget to retrain, test and update your chatbot
    • +
+
+
diff --git a/docs/guidelines/language/basics.md b/docs/guidelines/language/basics.md index 1def41618..60224ed03 100644 --- a/docs/guidelines/language/basics.md +++ b/docs/guidelines/language/basics.md @@ -36,24 +36,24 @@ 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 -- X appears when detail view has selected events -- cannot, will not -- you’ll, we’ve - +
+
+
    +
  • their, them, theirs, salesperson
    • +
  • Welcome to this application
    • +
  • X appears when detail view has selected events
    • +
  • cannot, will not
    • +
  • you’ll, we’ve
    • +
-
- -- his, hers, him, salesman -- Hey there! -- X doesn’t appear if detail view has no selected events -- can’t, won’t -- you will, we have - +
+
    +
  • his, hers, him, salesman
    • +
  • Hey there!
    • +
  • X doesn’t appear if detail view has no selected events
    • +
  • can’t, won’t
    • +
  • you will, we have
    • +
@@ -79,58 +79,58 @@ 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 -- Log in -- For more information, see Siemens Industry Online Support. - +
+
+
    +
  • Go to Settings
    • +
  • Press OK
    • +
  • Log in
    • +
  • For more information, see Siemens Industry Online Support.
    • +
-
- -- Go To Settings -- Press OK -- LOG IN -- For more information, see Siemens industry online support. - +
+
    +
  • Go To Settings
    • +
  • Press OK
    • +
  • LOG IN
    • +
  • For more information, see Siemens industry online support.
    • +
## Common UX wording mistakes -
-
- -- time zone -- log file -- log in (as an action) -- login (as a noun) -- equipment -- feedback -- training -- current -- avoid "shall" -- Siemens has -- 34 million / 35 billion -- 34 million - +
+
+
    +
  • time zone
    • +
  • log file
    • +
  • log in (as an action)
    • +
  • login (as a noun)
    • +
  • equipment
    • +
  • feedback
    • +
  • training
    • +
  • current
    • +
  • avoid "shall"
    • +
  • Siemens has
    • +
  • 34 million / 35 billion
    • +
  • 34 million
    • +
-
- -- timezone -- logfile -- login -- log in -- equipments -- feedbacks -- trainings -- actual -- user shall manage users -- Siemens have -- 34’ / 35“ -- 34 millions - +
+
    +
  • timezone
    • +
  • logfile
    • +
  • login
    • +
  • log in
    • +
  • equipments
    • +
  • feedbacks
    • +
  • trainings
    • +
  • actual
    • +
  • user shall manage users
    • +
  • Siemens have
    • +
  • 34’ / 35“
    • +
  • 34 millions
    • +
diff --git a/docs/guidelines/language/dialogs-and-buttons.md b/docs/guidelines/language/dialogs-and-buttons.md index 75b6a2351..929040a9e 100644 --- a/docs/guidelines/language/dialogs-and-buttons.md +++ b/docs/guidelines/language/dialogs-and-buttons.md @@ -24,20 +24,20 @@ 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, 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 -- Title: Edit details / Buttons: Cancel, Edit - +
+
    +
  • Title: Add user / Buttons: Cancel, OK
    • +
  • Title: Are you sure / Buttons: Cancel, Delete
    • +
  • Title: Edit details / Buttons: Cancel, Edit
    • +
@@ -47,15 +47,15 @@ description: 'Discover guidelines for writing dialogs and button labels to ensur - Primary actions can either be positive (Send, Save) or negative (Delete) -
-
- -- Cancel, Save - +
+
+
    +
  • Cancel, Save
    • +
-
- -- Save, Cancel - +
+
    +
  • Save, Cancel
    • +
diff --git a/docs/guidelines/language/formatting/addresses.mdx b/docs/guidelines/language/formatting/addresses.mdx index 91e8e8ed8..8dcbae16b 100644 --- a/docs/guidelines/language/formatting/addresses.mdx +++ b/docs/guidelines/language/formatting/addresses.mdx @@ -12,40 +12,40 @@ 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 - +
+
+
    +
  • Number | Street | State | ZIP code | Country
    • +
-
- -- Address line 1, Address line 2, Address line 3 - +
+
    +
  • Address line 1, Address line 2, Address line 3
    • +
Ensure special and international characters are accepted for international addresses. -
-
- -- 12-142 Elm St -- #8C (unit or suite number) -- Straße (street in German) -- VI (unit for floor in German) -- München (for Munich) - +
+
+
    +
  • 12-142 Elm St
    • +
  • #8C (unit or suite number)
    • +
  • Straße (street in German)
    • +
  • VI (unit for floor in German)
    • +
  • München (for Munich)
    • +
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 - +
+
+
    +
  • John Doe, 123 Maple Street, Springfield, California, 62704, United States
    • +
@@ -53,28 +53,28 @@ 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 -- Thun, Bern - +
+
+
    +
  • Springfield, Illinois
    • +
  • Munich, Bavaria
    • +
  • Thun, Bern
    • +
Use capital letters for abbreviated states without a full stop. -
-
- -- IL - +
+
+
    +
  • IL
    • +
-
- -- Il. - +
+
    +
  • Il.
    • +
@@ -82,20 +82,20 @@ 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) - +
+
+
    +
  • 90210 (US)
    • +
  • SW1A 2AA (UK)
    • +
  • 123-4567 (Japan)
    • +
-
- -- 90 21 0 (US) -- SW1A2AA (UK) -- 1234567 (Japan) - +
+
    +
  • 90 21 0 (US)
    • +
  • SW1A2AA (UK)
    • +
  • 1234567 (Japan)
    • +
@@ -119,34 +119,34 @@ 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 -- Ground floor (UK/Europe) -- First floor (US) -- Floor G (international) - +
+
+
    +
  • Floor 3
    • +
  • 3rd floor
    • +
  • Ground floor (UK/Europe)
    • +
  • First floor (US)
    • +
  • Floor G (international)
    • +
-
- -- Floor 3rd - +
+
    +
  • Floor 3rd
    • +
Use numbers and letters after buildings, suites, apartments, rooms and floors. -
-
- -- Building A -- Building part -- Room segment -- Bldg A -- Suite 3B - +
+
+
    +
  • Building A
    • +
  • Building part
    • +
  • Room segment
    • +
  • Bldg A
    • +
  • Suite 3B
    • +
@@ -154,14 +154,14 @@ 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 -- Zone C -- Area 8 - +
+
+
    +
  • Assembly line 2
    • +
  • Line B
    • +
  • Zone C
    • +
  • Area 8
    • +
@@ -169,35 +169,35 @@ 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° - +
+
+
    +
  • Latitude: 48.14389° | Longitude: 11.57633°
    • +
Use plus (+), minus (-), a comma and a space when adding both in one text field. -
-
- -- +48.14389°, +11.57633° - +
+
+
    +
  • +48.14389°, +11.57633°
    • +
Use the correct degree symbol (Unicode U+00B0). -
-
- -- ° - +
+
+
    +
  • °
    • +
-
- -- o - +
+
    +
  • o
    • +
\ No newline at end of file diff --git a/docs/guidelines/language/formatting/date.mdx b/docs/guidelines/language/formatting/date.mdx index 2150dd98f..78b5ad428 100644 --- a/docs/guidelines/language/formatting/date.mdx +++ b/docs/guidelines/language/formatting/date.mdx @@ -14,46 +14,46 @@ 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 (April 8, 2025)
    • +
  • 14:30:00 (24-hour format)
    • +
-
- -- 2025/04/08 -- 2:30 PM - +
+
    +
  • 2025/04/08
    • +
  • 2:30 PM
    • +
Add tooltips or in-line text to support users and clarify which format is being used. -
-
- -- YYYY-MM-DD -- 24-hour format -- Times are formatted in 24-hour format as HH:MM. For example, 2:30 PM is written as 14:30. -- Dates and times include time zones. For example, April 8, 2025, at 2:30 PM in Berlin is written as 2025-04-08T14:30:00+02:00. - +
+
+
    +
  • YYYY-MM-DD
    • +
  • 24-hour format
    • +
  • Times are formatted in 24-hour format as HH:MM. For example, 2:30 PM is written as 14:30.
    • +
  • Dates and times include time zones. For example, April 8, 2025, at 2:30 PM in Berlin is written as 2025-04-08T14:30:00+02:00.
    • +
Avoid adding unnecessary punctuation to abbreviated dates. -
-
- -- Jan - +
+
+
    +
  • Jan
    • +
-
- -- Jan. - +
+
    +
  • Jan.
    • +
@@ -61,63 +61,63 @@ 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 12, 2025
    • +
-
- -- Monday: January 12th: 2025 - +
+
    +
  • Monday: January 12th: 2025
    • +
Write out dates with the abbreviated form using dashes (hyphens) instead of slashes for better readability. -
-
- -- Dec-26-2025 -- Apr-09-2025 - +
+
+
    +
  • Dec-26-2025
    • +
  • Apr-09-2025
    • +
-
- -- Apr/09/2025 -- Apr 09/2025 - +
+
    +
  • Apr/09/2025
    • +
  • Apr 09/2025
    • +
Write dates in tables using abbreviated months to avoid confusion and the need for further tooltips or explanation. -
-
- -- Apr-09 - +
+
+
    +
  • Apr-09
    • +
-
- -- 04-09 - +
+
    +
  • 04-09
    • +
Avoid using "st" (as in 1st) or "th" (as in 5th) for a cleaner user interface. -
-
- -- Monday, January 12, 2025 - +
+
+
    +
  • Monday, January 12, 2025
    • +
-
- -- Monday, January 12th, 2025 - +
+
    +
  • Monday, January 12th, 2025
    • +
@@ -125,17 +125,17 @@ 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 - +
+
+
    +
  • Monday, Tuesday, Wednesday, etc.
    • +
  • Mon
    • +
-
- -- Mon. - +
+
    +
  • Mon.
    • +
@@ -143,18 +143,18 @@ 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) - +
+
+
    +
  • Week 15 (April 7 – April 13, 2025)
    • +
-
- -- CW 15 (15th week of the year) -- CW 15/2025 (15th calendar week year 2025) -- Calendar week 05 in year 2025 - +
+
    +
  • CW 15 (15th week of the year)
    • +
  • CW 15/2025 (15th calendar week year 2025)
    • +
  • Calendar week 05 in year 2025
    • +
@@ -162,17 +162,17 @@ 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 - +
+
+
    +
  • January, February, March, etc.
    • +
  • Jan
    • +
-
- -- Jan. - +
+
    +
  • Jan.
    • +
@@ -180,16 +180,16 @@ Start all months with a capital letter. Use abbreviations without punctuation wh Use the four-digit format and never abbreviate in industrial applications. -
-
- -- 2023 - +
+
+
    +
  • 2023
    • +
-
- -- ’23 - +
+
    +
  • ’23
    • +
@@ -197,16 +197,16 @@ Use the four-digit format and never abbreviate in industrial applications. Use plural -s when talking about decades. -
-
- -- 1980s - +
+
+
    +
  • 1980s
    • +
-
- -- 1980’s - +
+
    +
  • 1980’s
    • +
@@ -214,16 +214,16 @@ 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.
    • +
-
- -- 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 9340f02c3..cad8f108d 100644 --- a/docs/guidelines/language/formatting/measurements.mdx +++ b/docs/guidelines/language/formatting/measurements.mdx @@ -12,56 +12,56 @@ 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 - +
+
+
    +
  • British Thermal Unit (BTU): 1
    • +
  • Nautical Mile (nmi): 8
    • +
-
- -- BTU: 1 -- nmi: 8 - +
+
    +
  • BTU: 1
    • +
  • nmi: 8
    • +
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 -- 4 in -- 200 g - +
+
+
    +
  • 200 kg
    • +
  • 20 kg
    • +
  • 4 in
    • +
  • 200 g
    • +
-
- -- 200kg -- 20 kgs -- 4 in. -- 200 G - +
+
    +
  • 200kg
    • +
  • 20 kgs
    • +
  • 4 in.
    • +
  • 200 G
    • +
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
    • +
-
- -- 6 Volts -- 6 v - +
+
    +
  • 6 Volts
    • +
  • 6 v
    • +
@@ -77,17 +77,17 @@ 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
    • +
  • A/m
    • +
-
- -- km-h - +
+
    +
  • km-h
    • +
@@ -95,37 +95,37 @@ 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 - +
+
+
    +
  • 2 L
    • +
  • 11 L
    • +
  • 2 l
    • +
-
- -- 11 l - +
+
    +
  • 11 l
    • +
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) -- 1 t -- 1 TB -- 1 THz - +
+
+
    +
  • 120 MB (megabytes)
    • +
  • 120 Mb (megabits)
    • +
  • 1 t
    • +
  • 1 TB
    • +
  • 1 THz
    • +
-
- -- 1 T - +
+
    +
  • 1 T
    • +
@@ -133,48 +133,48 @@ Use upper case "B" to abbreviate byte and lower case "b" to abbreviate bit. Use Use superscript to indicate cubed measurements. -
-
- -- m³ -- cm³ - +
+
+
    +
  • m³
    • +
  • cm³
    • +
-
- -- m3 -- cm3 - +
+
    +
  • m3
    • +
  • cm3
    • +
Use the plain text caret symbol (^) when superscript is not possible in your application. -
-
- -- m^3 - +
+
+
    +
  • m^3
    • +
-
- -- m3 - +
+
    +
  • m3
    • +
Use mcg to abbreviate microgram instead of the Greek letter mu (μ). -
-
- -- 1000 mcg - +
+
+
    +
  • 1000 mcg
    • +
-
- -- 1000 μg - +
+
    +
  • 1000 μg
    • +
@@ -182,32 +182,32 @@ 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 -- 23° C - +
+
    +
  • 23°C
    • +
  • 23° C
    • +
Use the degree symbol (°) before the initial letter of the temperature scale without a space. -
-
- -- 23 °C - +
+
+
    +
  • 23 °C
    • +
-
- -- 23 C° - +
+
    +
  • 23 C°
    • +
@@ -215,20 +215,20 @@ 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 -- 4pt. - +
+
+
    +
  • 45 px
    • +
  • 1280 x 780 px
    • +
  • 4 pt
    • +
+
+
+
    +
  • 45PX
    • +
  • 1280x780px
    • +
  • 4pt.
    • +
diff --git a/docs/guidelines/language/formatting/money.mdx b/docs/guidelines/language/formatting/money.mdx index 4d971d5b7..1d2cca356 100644 --- a/docs/guidelines/language/formatting/money.mdx +++ b/docs/guidelines/language/formatting/money.mdx @@ -13,87 +13,87 @@ 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/£320.00/Three hundred and twenty pounds/320 pounds (mixed styles) - +
+
    +
  • 320£
    • +
  • £320/£320.00/Three hundred and twenty pounds/320 pounds (mixed styles)
    • +
Use decimal points for cents or smaller units within English user interfaces. -
-
- -- €999.50 -- $400,456.50 - +
+
+
    +
  • €999.50
    • +
  • $400,456.50
    • +
-
- -- €999,50 -- $400.456,50 - +
+
    +
  • €999,50
    • +
  • $400.456,50
    • +
Never add a space between the currency symbol and the amount. -
-
- -- $100 - +
+
+
    +
  • $100
    • +
-
- -- $ 100 - +
+
    +
  • $ 100
    • +
Use the ISO currency code before the number without a space. -
-
- -- USD400 - +
+
+
    +
  • USD400
    • +
-
- -- 300USD - +
+
    +
  • 300USD
    • +
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. -- Spare parts cost estimation for 2025 is $125,999. -- The subscription costs $10 per month. - +
+
+
    +
  • Thank you. Your payment of $50 has been processed.
    • +
  • Invest in our new soft sensors for $6,000 to boost your production efficiency.
    • +
  • Spare parts cost estimation for 2025 is $125,999.
    • +
  • The subscription costs $10 per month.
    • +
Write out the full word in formal and legal documents. -
-
- -- The total amount shall not exceed four thousand dollars. - +
+
+
    +
  • 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 0f1acd01c..2630df369 100644 --- a/docs/guidelines/language/formatting/names-titles.mdx +++ b/docs/guidelines/language/formatting/names-titles.mdx @@ -14,18 +14,18 @@ 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 - +
+
+
    +
  • First name
    • +
  • Last name
    • +
-
- -- Surname -- Full name - +
+
    +
  • Surname
    • +
  • Full name
    • +
@@ -33,11 +33,11 @@ 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 - +
+
+
    +
  • Welcome Susanne
    • +
@@ -45,16 +45,16 @@ 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. | Ms. | Mx. | None | Other | Prefer not to say]
    • +
-
- -- [ Mr. | Mrs. | Miss | Ms. ] - +
+
    +
  • [ Mr. | Mrs. | Miss | Ms. ]
    • +
@@ -62,45 +62,45 @@ 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
    • +
-
- -- Mr Smith - +
+
    +
  • Mr Smith
    • +
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. Turner
    • +
  • Mrs. Jennifer Turner
    • +
  • Jennifer
    • +
-
- -- Mrs. Jennifer - +
+
    +
  • Mrs. Jennifer
    • +
Use full stops for all abbreviated professional titles in American English. -
-
- -- Dr. -- Prof. -- Eng. - +
+
+
    +
  • Dr.
    • +
  • Prof.
    • +
  • Eng.
    • +
@@ -108,50 +108,50 @@ 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
    • +
  • Teresa Lopez (Chief Financial Officer)
    • +
  • Teresa Lopez (CFO)
    • +
-
- -- chief financial officer Teresa Lopez - +
+
    +
  • chief financial officer Teresa Lopez
    • +
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. - +
+
+
    +
  • 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. - +
+
    +
  • Call the Manager.
    • +
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.
    • +
-
- -- 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 4ba2ccade..ae11b0795 100644 --- a/docs/guidelines/language/formatting/numbers.mdx +++ b/docs/guidelines/language/formatting/numbers.mdx @@ -14,76 +14,76 @@ 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 - +
+
+
    +
  • Number
    • +
-
- -- Num. - +
+
    +
  • Num.
    • +
Use "No." as an abbreviation for number with a period and without a space. -
-
- -- No.6 - +
+
+
    +
  • No.6
    • +
-
- -- Num.6 - +
+
    +
  • Num.6
    • +
Avoid using the # symbol with numbers. -
-
- -- Number 6 - +
+
+
    +
  • Number 6
    • +
-
- -- #6 - +
+
    +
  • #6
    • +
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 3 new features this month.
    • +
-
- -- We’ve released three new features this month. - +
+
    +
  • We’ve released three new features this month.
    • +
Write numbers with four digits and more with commas to separate thousands, millions, etc. in American English. -
-
- -- 100,000 - +
+
+
    +
  • 100,000
    • +
-
- -- 100.000 - +
+
    +
  • 100.000
    • +
@@ -91,53 +91,53 @@ 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 - +
+
+
    +
  • 10–0
    • +
  • The shipment weighs 50–75kg
    • +
Write out the unit only once in ranges. -
-
- -- The temperature fluctuated between 20–25°C - +
+
+
    +
  • The temperature fluctuated between 20–25°C
    • +
-
- -- The temperature fluctuated between 20°C–25°C - +
+
    +
  • The temperature fluctuated between 20°C–25°C
    • +
Use the minus hyphen for negative numbers which is better aligned than a normal hyphen (Unicode U+2212). -
-
- -- -12 - +
+
+
    +
  • -12
    • +
-
- -- —12 - +
+
    +
  • —12
    • +
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° - +
+
+
    +
  • -12 to -15°C
    • +
  • Min temp (C): -12° / Max temp (C): -15°
    • +
@@ -145,20 +145,20 @@ 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
    • +
  • 2.5 million
    • +
-
- -- 0,5 -- 5.245,15 -- 2,5 million - +
+
    +
  • 0,5
    • +
  • 5.245,15
    • +
  • 2,5 million
    • +
@@ -167,76 +167,75 @@ 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 - +
+
+
    +
  • 34K
    • +
  • 34M
    • +
  • 34B
    • +
-
- -- 34 k -- 34 mil -- 34 bill - +
+
    +
  • 34 k
    • +
  • 34 mil
    • +
  • 34 bill
    • +
Use the singular "million" when talking about a specific number. -
-
- -- 34 million -- Our system processes one million connections. - +
+
+
    +
  • 34 million
    • +
  • Our system processes one million connections.
    • +
-
- -- 34 millions -- Our system processes one millions connections. - +
+
    +
  • 34 millions
    • +
  • Our system processes one millions connections.
    • +
Use the plural "millions" when talking about an unspecific number. -
-
- -- Our goal is to deliver software to millions of happy users worldwide. - +
+
+
    +
  • Our goal is to deliver software to millions of happy users worldwide.
    • +
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 one million users worldwide.
    • +
-
- -- We have over 1,000,000 users worldwide. - +
+
    +
  • We have over 1,000,000 users worldwide.
    • +
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. - -- The success rate of our new implementation is 1,000,000%. -- The project budget is $1,000,000. - +
+
+
    +
  • The temperature can reach 1,000,000°C in the pod.
    • +
  • The cargo ship can carry up to 1,000,000kg.
    • +
  • The success rate of our new implementation is 1,000,000%.
    • +
  • The project budget is $1,000,000.
    • +
@@ -244,31 +243,31 @@ 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%
    • +
-
- -- 10 percent - +
+
    +
  • 10 percent
    • +
Use % after the number and without a space. -
-
- -- 10% - +
+
+
    +
  • 10%
    • +
-
- -- %10 - +
+
    +
  • %10
    • +
@@ -276,29 +275,29 @@ 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 - +
+
+
    +
  • Country code, area code, numbers in groupings of 3 or 4
    • +
  • 0044, 208, 899 7032
    • +
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 - +
+
+
    +
  • +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 4807c199b..fe969c555 100644 --- a/docs/guidelines/language/formatting/software-versions.mdx +++ b/docs/guidelines/language/formatting/software-versions.mdx @@ -13,127 +13,127 @@ 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 - +
+
+
    +
  • Version 2.12.6
    • +
-
- -- ver 2.12.6 - +
+
    +
  • ver 2.12.6
    • +
Use "Version" with a capital V when it starts a sentence. -
-
- -- Version 3.5.1 has three new exciting changes. - +
+
+
    +
  • Version 3.5.1 has three new exciting changes.
    • +
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. - +
+
+
    +
  • Our migration guide for moving from Version 2 to Version 3 is below.
    • +
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.
    • +
-
- -- Our next Version contains three new exciting changes. - +
+
    +
  • Our next Version contains three new exciting changes.
    • +
Use a capital V without spacing between the letter and number to abbreviate versions. -
-
- -- V2.1.0 - +
+
+
    +
  • V2.1.0
    • +
-
- -- v2.1.0 - +
+
    +
  • v2.1.0
    • +
Start the first major release with 1 (not 01). -
-
- -- V1.0.0 - +
+
+
    +
  • V1.0.0
    • +
-
- -- V01.0.0 - +
+
    +
  • V01.0.0
    • +
End versions without a full stop at the end. -
-
- -- V1.0.0 - +
+
+
    +
  • V1.0.0
    • +
-
- -- V1.0.0. - +
+
    +
  • V1.0.0.
    • +
Use single digits without adding extra zeros to make it easier to read. -
-
- -- V3.2.5 - +
+
+
    +
  • V3.2.5
    • +
-
- -- V03.02.05 - +
+
    +
  • V03.02.05
    • +
Add identifiers, such as alpha, before or after version numbers for pre-releases. -
-
- -- V1.0.0-beta -- Beta V5.2 - -
-
- -- V1.0.0-Beta - +
+
+
    +
  • 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 b17476a33..8d4018346 100644 --- a/docs/guidelines/language/formatting/timezones.mdx +++ b/docs/guidelines/language/formatting/timezones.mdx @@ -15,50 +15,50 @@ 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 - +
+
+
    +
  • 11:00
    • +
  • 23:00
    • +
-
- -- 11am -- 11PM - +
+
    +
  • 11am
    • +
  • 11PM
    • +
Use colons (:) to split times between hours, minutes, and seconds. -
-
- -- hh:mm:ss - +
+
+
    +
  • hh:mm:ss
    • +
-
- -- hh.mm.ss - +
+
    +
  • hh.mm.ss
    • +
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 - +
+
+
    +
  • hh:mm:ss.mms
    • +
  • hh:mm:ss.sss (ISO 8601 standard)
    • +
  • 0:00:00.920
    • +
-
- -- 0:00:00:920 - +
+
    +
  • 0:00:00:920
    • +
@@ -66,27 +66,27 @@ 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 - +
+
+
    +
  • Routine maintenance: 08:00–11:00
    • +
-
- -- Packaging line active: 10:00-18:00 - +
+
    +
  • Packaging line active: 10:00-18:00
    • +
Use "from" and "to" for time ranges with separate text or input fields. -
-
- -- From: 14:00 -- To: 15:00 - +
+
+
    +
  • From: 14:00
    • +
  • To: 15:00
    • +
@@ -94,13 +94,13 @@ 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. -- Cooling period: 20 minutes - +
+
+
    +
  • Each shift lasts 8 hrs.
    • +
  • Routine maintenance takes approximately 1 hour 30 minutes.
    • +
  • Cooling period: 20 minutes
    • +
@@ -108,127 +108,127 @@ 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 time zone
    • +
-
- -- Select timezone - +
+
    +
  • Select 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) -- Eastern European Summer Time (UTC+3) - +
+
+
    +
  • British Summer Time (UTC+1)
    • +
  • Central European Summer Time (UTC+2)
    • +
  • Eastern European Summer Time (UTC+3)
    • +
Use abbreviated time zones with or without the UTC offset within the UI to save space. -
-
- -- EST -- EST (UTC +3) - +
+
+
    +
  • EST
    • +
  • EST (UTC +3)
    • +
Give time zones capital letters for each word. -
-
- -- Eastern Standard Time - +
+
+
    +
  • Eastern Standard Time
    • +
-
- -- eastern standard time - +
+
    +
  • eastern standard time
    • +
Give abbreviated time zones capital letters. -
-
- -- EST - +
+
+
    +
  • EST
    • +
-
- -- est - +
+
    +
  • est
    • +
Avoid punctuation when writing time zones. -
-
- -- EST - +
+
+
    +
  • EST
    • +
-
- -- EST. -- E.S.T. - +
+
    +
  • EST.
    • +
  • E.S.T.
    • +
Add a space between the time and the time zone. -
-
- -- 15:23 EST - +
+
+
    +
  • 15:23 EST
    • +
-
- -- 15:23EST - +
+
    +
  • 15:23EST
    • +
Write location and UTC offset in this order: city, country (UTC offset). -
-
- -- Berlin, Germany (UTC+1) - +
+
+
    +
  • Berlin, Germany (UTC+1)
    • +
-
- -- (UTC+1) Berlin, Germany - +
+
    +
  • (UTC+1) Berlin, Germany
    • +
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) -- Deadline (San Francisco): 2025-04-08 17:00 (UTC-07:00)
Your Local Time (Berlin): 2025-04-09 02:00 (UTC+01:00) - +
+
+
    +
  • 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)
    • +
  • Deadline (San Francisco): 2025-04-08 17:00 (UTC-07:00)
    Your Local Time (Berlin): 2025-04-09 02:00 (UTC+01:00)
    • +
@@ -236,42 +236,42 @@ 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 - +
+
+
    +
  • Current temperature: 72°F
    • +
-
- -- Actual temperature: 72°F - +
+
    +
  • Actual temperature: 72°F
    • +
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 - +
+
+
    +
  • Latest firmware update: V2.1.5
    • +
  • Last firmware update before end of life: V2.1.5
    • +
Use "recent" for past events that have just happened. -
-
- -- Recent alerts: 2 warnings - +
+
+
    +
  • Recent alerts: 2 warnings
    • +
-
- -- Recent firmware update: V2.1.5 - +
+
    +
  • 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 7b1b6dcdb..f29dfc646 100644 --- a/docs/guidelines/language/frequent-app-functions.md +++ b/docs/guidelines/language/frequent-app-functions.md @@ -18,13 +18,13 @@ description: 'Get tips for naming common app functions clearly and effectively. - Cockpit -
-
- -- Console -- Dash -- Control panel - +
+
+
    +
  • Console
    • +
  • Dash
    • +
  • Control panel
    • +
@@ -34,12 +34,12 @@ description: 'Get tips for naming common app functions clearly and effectively. - Anomaly detection -
-
- -- Assessment -- Examination - +
+
+
    +
  • Assessment
    • +
  • Examination
    • +
@@ -53,11 +53,11 @@ description: 'Get tips for naming common app functions clearly and effectively. - Remove from watchlist -
-
- -- Watch list - +
+
+
    +
  • Watch list
    • +
@@ -69,12 +69,12 @@ description: 'Get tips for naming common app functions clearly and effectively. - Details -
-
- -- Facts -- Specifics - +
+
+
    +
  • Facts
    • +
  • Specifics
    • +
@@ -120,11 +120,11 @@ description: 'Get tips for naming common app functions clearly and effectively. - Drag files here or select files -
-
- -- Drag and drop here or browse - +
+
+
    +
  • Drag and drop here or browse
    • +
@@ -138,11 +138,11 @@ description: 'Get tips for naming common app functions clearly and effectively. - Write your comments here -
-
- -- Write a comment - +
+
+
    +
  • Write a comment
    • +
@@ -168,13 +168,13 @@ description: 'Get tips for naming common app functions clearly and effectively. - Notify me when X occurs -
-
- -- Error -- Issue -- Problem - +
+
+
    +
  • Error
    • +
  • Issue
    • +
  • Problem
    • +
@@ -204,14 +204,14 @@ description: 'Get tips for naming common app functions clearly and effectively. - Detected -
-
- -- Unacklowedged -- Unack. -- Unackn. -- Unacknl. - +
+
+
    +
  • Unacklowedged
    • +
  • Unack.
    • +
  • Unackn.
    • +
  • Unacknl.
    • +
diff --git a/docs/guidelines/language/grammar-and-vocabulary.md b/docs/guidelines/language/grammar-and-vocabulary.md index 2aa38fe23..1ac3e8644 100644 --- a/docs/guidelines/language/grammar-and-vocabulary.md +++ b/docs/guidelines/language/grammar-and-vocabulary.md @@ -16,41 +16,41 @@ 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 - +
+
+
    +
  • click, browse, upload
    • +
  • file loads, file loaded
    • +
-
- -- clicking, being clicked, was clicking -- file is going to be loaded, file has been loaded - +
+
    +
  • clicking, being clicked, was clicking
    • +
  • file is going to be loaded, file has been loaded
    • +
## Active voice -
-
- -- Configuration file opens. -- Admin provides read-only access. -- Measure performance. -- Click submit. -- Calculate the data. - +
+
+
    +
  • Configuration file opens.
    • +
  • Admin provides read-only access.
    • +
  • Measure performance.
    • +
  • Click submit.
    • +
  • Calculate the data.
    • +
-
- -- The configuration file is opened. -- Read-only access is provided by Admin. -- Performance is measured. -- Submit is clicked by user. -- The data is calculated by application. - +
+
    +
  • The configuration file is opened.
    • +
  • Read-only access is provided by Admin.
    • +
  • Performance is measured.
    • +
  • Submit is clicked by user.
    • +
  • The data is calculated by application.
    • +
@@ -62,18 +62,18 @@ 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 - +
+
+
    +
  • click
    • +
  • hover
    • +
-
- -- press -- mouse over - +
+
    +
  • press
    • +
  • mouse over
    • +
@@ -85,22 +85,22 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri - Avoid cultural references -
-
- -- remove -- calculate -- continue -- mobile device - +
+
+
    +
  • remove
    • +
  • calculate
    • +
  • continue
    • +
  • mobile device
    • +
-
- -- get rid of -- add up -- carry on -- Apple, Android, iOS, smartphone - +
+
    +
  • get rid of
    • +
  • add up
    • +
  • carry on
    • +
  • Apple, Android, iOS, smartphone
    • +
@@ -124,22 +124,22 @@ 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 -- EU -- I/O component, I/O list, I/O module - +
+
+
    +
  • light emitting diodes (LEDs)
    • +
  • APS
    • +
  • EU
    • +
  • I/O component, I/O list, I/O module
    • +
-
- -- Light Emitting Diodes (LEDS) -- A.P.S. -- E.U. -- IO component, i/o list, I-O module - +
+
    +
  • Light Emitting Diodes (LEDS)
    • +
  • A.P.S.
    • +
  • E.U.
    • +
  • IO component, i/o list, I-O module
    • +
@@ -151,19 +151,19 @@ 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 -- Last events - +
+
+
    +
  • Latest update
    • +
  • Latest summary
    • +
  • Recent events
    • +
+
+
+
    +
  • Last update
    • +
  • Last summary
    • +
  • Last events
    • +
diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/external-links-and-resources.md b/docs/guidelines/language/menu-functions-and-ui-labels/external-links-and-resources.md index b9ff9b5b3..70c55d041 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/external-links-and-resources.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/external-links-and-resources.md @@ -21,61 +21,79 @@ import { iconOpenExternal } from "@siemens/ix-icons/icons"; Use brief, meaningful link text to explain the function of the target web page or resource. -
-
-- SIMATIC S7-1500 firmware updates -- Roles and permissions in the documentation -- Demonstration projects +
+
+
    +
  • SIMATIC S7-1500 firmware updates
    • +
  • Roles and permissions in the documentation
    • +
  • Demonstration projects
    • +
-
-- Learn about the latest device firmware updates -- {'https://www.company.com/s7-1500-firmware'} -- Remote access +
+
    +
  • Learn about the latest device firmware updates
    • +
  • {'https://www.company.com/s7-1500-firmware'}
    • +
  • Remote access
    • +
Pair link text with universal icons, e.g. the open-external or application-screen icons. -
-
-- Company Digital ID -- Manage your software licenses in one place +
+
+
    +
  • Company Digital ID
    • +
  • Manage your software licenses in one place
    • +
Use descriptive link text instead of long, full URLs and remove the prefix {'https://www'}. -
-
-- Company homepage -- acronymfinder.com +
+
+
    +
  • Company homepage
    • +
  • acronymfinder.com
    • +
-
-- {'https://www.company.com/s9-1600-firmware'}
-- {'https://support.com/us/en/view/107826255'} +
+
    +
  • {'https://www.company.com/s9-1600-firmware'}
    • +
  • {'https://support.com/us/en/view/107826255'}
    • +
Avoid generic link text, e.g. "click here" without context or information regarding what opens. -
-
-- Description: The details regarding the collection and use of Analytics Data are described in Software Analytics Notice contained in the Application Function Manual.

-Link text: Open Application Function Manual +
+
+
    +
  • Description: The details regarding the collection and use of Analytics Data are described in Software Analytics Notice contained in the Application Function Manual.

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

Link text: Efficiency report +
+
+
    +
  • Description: Our new automation system improves efficiency by 40% and reduces downtime through predictive maintenance algorithms.

    Link text: Efficiency report
    • +
-
-- For more technical details, visit Automation Whitepaper . +
+
    +
  • For more technical details, visit Automation Whitepaper .
    • +
@@ -177,31 +215,41 @@ Split external links from body text with separate paragraphs for faster scanning Avoid adding the "mailto" text and for email addresses as this is no longer visible in the UI. -
-
-- {'mailto:name@examples.com'} +
+
+
    +
  • {'mailto:name@examples.com'}
    • +
Ensure email addresses and phone numbers are clickable. -
-
-- You can reach us at the following telephone number [+1 555-0100](#). +
+
+
    +
  • You can reach us at the following telephone number [+1 555-0100](#).
    • +
-
-- 555 0100 +
+
    +
  • 555 0100
    • +
-## Dos and Don'ts +## Dos and Don’ts -- Do add link text for transparency -- Do pair link and resource icons with clear texts -- Do use icons to visualize what will open, e.g. external link, PDF, etc. -- Do use ALT-text to explain icons -- Don't include https://, http: or www in URL text -- Don't add links in headings or sub-headings +
+
+
    +
  • Do add link text for transparency
    • +
  • Do pair link and resource icons with clear texts
    • +
  • Do use icons to visualize what will open, e.g. external link, PDF, etc.
    • +
  • Do use ALT-text to explain icons
    • +
+
+
## Related diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md b/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md index 79a8aeba0..44c61bb4c 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/license-management.md @@ -14,32 +14,42 @@ description: 'Clear license and subscription management writing reduces user con Use clear and consistent language your users are familiar with. -
-
-- Your subscription expires in 30 days. Renew now to keep access to all features. +
+
+
    +
  • Your subscription expires in 30 days. Renew now to keep access to all features.
    • +
-
-- Your entitlement terminates in 30 days. Execute renewal procedures to maintain feature provisioning. +
+
    +
  • Your entitlement terminates in 30 days. Execute renewal procedures to maintain feature provisioning.
    • +
Use the same terms throughout workflows, applications and portfolios to avoid confusion. -
-
-- Activate your license / License activated / View activated licenses +
+
+
    +
  • Activate your license / License activated / View activated licenses
    • +
-
-- Activate your license / License enabled / View dynamic licenses +
+
    +
  • Activate your license / License enabled / View dynamic licenses
    • +
Use links when referencing terms of use or compliance documents. -
-
-- By using this software, you agree to our Terms of Use.
-Link text: View full terms +
+
+
    +
  • By using this software, you agree to our Terms of Use.
    + Link text: View full terms
    • +
@@ -47,68 +57,90 @@ Link text: View full terms Use American English spelling “license” (with s) for both nouns and verbs in all global interfaces. -
-
-- Your license expires in 30 days. +
+
+
    +
  • Your license expires in 30 days.
    • +
-
-- Your licence expires in 30 days. +
+
    +
  • Your licence expires in 30 days.
    • +
Use “a license” when referring to single licenses in general, and “the license” when referring to specific licenses. -
-
-- You need a license to access this feature. -- The license you purchased includes 5 users. +
+
+
    +
  • You need a license to access this feature.
    • +
  • The license you purchased includes 5 users.
    • +
Avoid using apostrophes to describe singular (‘s) or plural (s’) license possession. -
-
-- The license expires on May 1, 2026. -- The status of all licenses can be viewed here. +
+
+
    +
  • The license expires on May 1, 2026.
    • +
  • The status of all licenses can be viewed here.
    • +
-
-- The license’s expiration date is May 1, 2026. -- All licenses’ status can be viewed here. +
+
    +
  • The license’s expiration date is May 1, 2026.
    • +
  • All licenses’ status can be viewed here.
    • +
Use active voice for user actions. -
-
-- Activate your license now. +
+
+
    +
  • Activate your license now.
    • +
-
-- Your license should be activated by you. +
+
    +
  • Your license should be activated by you.
    • +
Use passive voice when the actor is unknown or unimportant. -
-
-- Your license was activated successfully. +
+
+
    +
  • Your license was activated successfully.
    • +
-
-- The license activates. +
+
    +
  • The license activates.
    • +
Use hyphens to connect descriptive words before nouns. -
-
-- A multi-user license -- The license is multi-user +
+
+
    +
  • A multi-user license
    • +
  • The license is multi-user
    • +
-
-- A multi user license +
+
    +
  • A multi user license
    • +
@@ -186,34 +218,44 @@ Note licenses can be both proper nouns and common nouns (per Product License vs. Use clear and specific dates, limits and consequences. -
-
-- Your license expires on November 30, 2025. +
+
+
    +
  • Your license expires on November 30, 2025.
    • +
-
-- Your license will expire soon. +
+
    +
  • Your license will expire soon.
    • +
Use prominent and clear expiration warnings. -
-
-- First notice: Your license expires on November 30, 2025. -- Second notice: Your license expires in 7 days. -- Final notice: Your license expires tomorrow. +
+
+
    +
  • First notice: Your license expires on November 30, 2025.
    • +
  • Second notice: Your license expires in 7 days.
    • +
  • Final notice: Your license expires tomorrow.
    • +
Send timely, progressive reminders, especially for expiration and grace periods. -
-
-- Heading: Your license has expired.
Description: Your license expired on January 1, 2026. To continue using our application renew your subscription.
Buttons: Renew now / Contact sales -- Grace period notice: 7 days +
+
+
    +
  • Heading: Your license has expired.
    Description: Your license expired on January 1, 2026. To continue using our application renew your subscription.
    Buttons: Renew now / Contact sales
    • +
  • Grace period notice: 7 days
    • +
-
-- License expired. +
+
    +
  • License expired.
    • +
@@ -221,14 +263,18 @@ Send timely, progressive reminders, especially for expiration and grace periods. Use “quantity” to refer to how many and “number” to refer to identifiers and codes. -
-
-- product number -- serial number -- Enter your license key +
+
+
    +
  • product number
    • +
  • serial number
    • +
  • Enter your license key
    • +
-
-- Enter your license key quantity +
+
    +
  • Enter your license key quantity
    • +
@@ -236,56 +282,76 @@ Use “quantity” to refer to how many and “number” to refer to identifiers Use “ID” for identification and tracking and “key” for activation or access. -
-
-- Enter your license key. +
+
+
    +
  • Enter your license key.
    • +
-
-- Enter your license ID. +
+
    +
  • Enter your license ID.
    • +
Use “subscription ID” when referring to the unique identifier number or code for an entire subscription (often a long number or UUID). -
-
-- Your subscription ID is 1234567890. +
+
+
    +
  • Your subscription ID is 1234567890.
    • +
-
-- Your subscription key is 1234567890. +
+
    +
  • Your subscription key is 1234567890.
    • +
Use “subscription key” when referring to a code or password required to activate or access a subscription. -
-
-- Copy this subscription key to activate your subscription. +
+
+
    +
  • Copy this subscription key to activate your subscription.
    • +
-
-- Copy this subscription ID to activate your subscription. +
+
    +
  • Copy this subscription ID to activate your subscription.
    • +
Use “license ID” or “ID” for the unique identifier of a specific license within the subscription. -
-
-- Each license has its own license ID for tracking and management. +
+
+
    +
  • Each license has its own license ID for tracking and management.
    • +
-
-- Each license has its own license key for tracking and management. +
+
    +
  • Each license has its own license key for tracking and management.
    • +
Use “license key” when talking about the code or string that unlocks or activates a specific license. -
-
-- Enter your license key to activate the product. +
+
+
    +
  • Enter your license key to activate the product.
    • +
-
-- Enter your license ID to activate the product. +
+
    +
  • Enter your license ID to activate the product.
    • +
@@ -293,17 +359,21 @@ Use “license key” when talking about the code or string that unlocks or acti When licenses cannot be found, explain possible causes and provide clear actions to resolve the issue. -
-
-- Heading: License not found
Description: Failed to find a valid license for this product. This may happen if you’re registered under a different account, or if your license has not been activated yet.
Button: Sign in with different account +
+
+
    +
  • Heading: License not found
    Description: Failed to find a valid license for this product. This may happen if you’re registered under a different account, or if your license has not been activated yet.
    Button: Sign in with different account
    • +
When licenses are not available, explain how users can resolve the issue. -
-
-- Heading: No licenses available
Description: All 10 licenses are currently in use. Ask your administrator to assign a license to you or wait until one becomes available.
Buttons: Request license / View license usage +
+
+
    +
  • Heading: No licenses available
    Description: All 10 licenses are currently in use. Ask your administrator to assign a license to you or wait until one becomes available.
    Buttons: Request license / View license usage
    • +
@@ -311,91 +381,123 @@ When licenses are not available, explain how users can resolve the issue. Use “add-on” to refer to additional features or modules attached to an existing product. -
-
-- Add the Health package add-on for obsolescence notifications. +
+
+
    +
  • Add the Health package add-on for obsolescence notifications.
    • +
Use “upgrade” for when users are moving to a better version of the same product. -
-
-- Upgrade to the Professional edition for more features. -- Upgrade your license from Version 2.0 to Version 3.0. +
+
+
    +
  • Upgrade to the Professional edition for more features.
    • +
  • Upgrade your license from Version 2.0 to Version 3.0.
    • +
-
-- Add the next edition as an add-on. +
+
    +
  • Add the next edition as an add-on.
    • +
Use “requirement” to refer to what a user needs to run the software. -
-
-- License requirements: Active subscription and internet connection. -- This feature requires an active maintenance agreement. +
+
+
    +
  • License requirements: Active subscription and internet connection.
    • +
  • This feature requires an active maintenance agreement.
    • +
Use “entitlement” to refer to what the user is authorized to do. -
-
-- Your entitlement includes 5 user licenses. -- This feature is not included in your current entitlement. +
+
+
    +
  • Your entitlement includes 5 user licenses.
    • +
  • This feature is not included in your current entitlement.
    • +
-
-- Your requirement includes 5 user licenses. +
+
    +
  • Your requirement includes 5 user licenses.
    • +
Use the standard term “activate” and “assign” instead of the non-standard “start”. -
-
-- Activate license now. -- Assign licenses to your team in your dashboard. +
+
+
    +
  • Activate license now.
    • +
  • Assign licenses to your team in your dashboard.
    • +
Use “renew” instead of “update” for continuing subscriptions. -
-
-- Renew your license in one easy step. +
+
+
    +
  • Renew your license in one easy step.
    • +
Use “manage” instead of “edit” to administer licenses. -
-
-- Manage your licenses under License management. +
+
+
    +
  • Manage your licenses under License management.
    • +
Use “base” product to talk about a foundation product that other features build on. -
-
-- The base product includes core functionality. +
+
+
    +
  • The base product includes core functionality.
    • +
Use “basic” product when talking about a simplified or entry-level version of your product. -
-
-- Select either our Basic, Premium or Advanced licenses. +
+
+
    +
  • Select either our Basic, Premium or Advanced licenses.
    • +
## Dos and Don’ts -- Do document license terms and record any changes for consistency -- Do use the same license actions consistently across applications and portfolios -- Don’t create new license types or states, instead use standard terms +
+
+
    +
  • Do document license terms and record any changes for consistency
    • +
  • Do use the same license actions consistently across applications and portfolios
    • +
+
+
+
    +
  • Don’t create new license types or states, instead use standard terms
    • +
+
+
## Related diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/logging-in-and-out.md b/docs/guidelines/language/menu-functions-and-ui-labels/logging-in-and-out.md index a3e3b22b9..3ff6e14c6 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/logging-in-and-out.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/logging-in-and-out.md @@ -14,250 +14,326 @@ description: 'Consistent login/logout text reduces confusion, builds trust, and Use “log in” and “log out” as the action verbs instead of “sign in” or “sign out” for consistency. -
-
-- Log out -- Log in to get started -- Log in with Microsoft ID +
+
+
    +
  • Log out
    • +
  • Log in to get started
    • +
  • Log in with Microsoft ID
    • +
-
-- Log off -- Sign out +
+
    +
  • Log off
    • +
  • Sign out
    • +
Use “login” and “logout” as the nouns instead of “signoff” or “logoff” for consistency. -
-
-- Logout -- The login button is located on the top right corner of the screen. -- After logout, you’ll be directed to the homepage. +
+
+
    +
  • Logout
    • +
  • The login button is located on the top right corner of the screen.
    • +
  • After logout, you’ll be directed to the homepage.
    • +
-
-- Logoff +
+
    +
  • Logoff
    • +
Use “create account” instead of “register” for consistency and transparency. -
-
-- Create account -- Register +
+
+
    +
  • Create account
    • +
  • Register
    • +
-
-- Join -- Enroll -- Sign up +
+
    +
  • Join
    • +
  • Enroll
    • +
  • Sign up
    • +
Provide feedback and guidance when there are unexpected errors during login. -
-
-- Unexpected error during login. Open homepage and try again. +
+
+
    +
  • Unexpected error during login. Open homepage and try again.
    • +
-
-- An unexpected error occurred during login. +
+
    +
  • An unexpected error occurred during login.
    • +
Provide clear actions when users need to log in again or have been logged out unexpectedly. -
-
-- Session expired due to inactivity. Log in to continue working. -- Session expired due to inactivity. Log in again to continue working. +
+
+
    +
  • Session expired due to inactivity. Log in to continue working.
    • +
  • Session expired due to inactivity. Log in again to continue working.
    • +
-
-- Your session has expired. +
+
    +
  • Your session has expired.
    • +
Avoid generic “refresh” or “reload” buttons, instead move users forward with concrete actions. -
-
-- Failed to log in. Check your credentials and try again. +
+
+
    +
  • Failed to log in. Check your credentials and try again.
    • +
-
-- Login failed. Refresh page. +
+
    +
  • Login failed. Refresh page.
    • +
Avoid using question prompts to make texts leaner and avoid punctuation issues. -
-
-- Forgot password -- Request new password -- Create account +
+
+
    +
  • Forgot password
    • +
  • Request new password
    • +
  • Create account
    • +
-
-- Forgot your password? -- Don’t have an account? Register now -- Already have an account? +
+
    +
  • Forgot your password?
    • +
  • Don’t have an account? Register now
    • +
  • Already have an account?
    • +
Clearly explain password policy to avoid frustration or user friction. -
-
-- Minimum 12 characters
-Minimum 1 uppercase letter (A-Z)
-Minimum 1 number
-Minimum 1 special character (!@#$%^&*) +
+
+
    +
  • Minimum 12 characters
    + Minimum 1 uppercase letter (A-Z)
    + Minimum 1 number
    + Minimum 1 special character (!@#$%^&*)
    • +
-
-- Ensure you meet the password criteria. +
+
    +
  • Ensure you meet the password criteria.
    • +
Guide users when they add invalid input to support password creation. -
-
-- Matches one of your last 3 passwords -- Uses invalid characters -- Missing a lower case letter -- Contains spaces -- Contains your username +
+
+
    +
  • Matches one of your last 3 passwords
    • +
  • Uses invalid characters
    • +
  • Missing a lower case letter
    • +
  • Contains spaces
    • +
  • Contains your username
    • +
-
-- Wrong password format -- Invalid -- Error -- Try again -- Password error code: 5467 +
+
    +
  • Wrong password format
    • +
  • Invalid
    • +
  • Error
    • +
  • Try again
    • +
  • Password error code: 5467
    • +
Show real-time password strength. -
-
-- Weak -- Fair -- Strong -- Very strong +
+
+
    +
  • Weak
    • +
  • Fair
    • +
  • Strong
    • +
  • Very strong
    • +
-
-- Not strong enough +
+
    +
  • Not strong enough
    • +
Avoid using password or password-related jargon or abbreviations. -
-
-- One-time password +
+
+
    +
  • One-time password
    • +
-
-- OTP +
+
    +
  • OTP
    • +
Use “change password” instead of “update password” for consistency. -
-
-- Change password +
+
+
    +
  • Change password
    • +
-
-- Update password +
+
    +
  • Update password
    • +
Use “email” or “email address” as both are acceptable. -
-
-- Enter a valid email. -- Enter a valid email address. -- Enter your email below to receive a password reset link. -- Incorrect email or password. Check your details and try again. +
+
+
    +
  • Enter a valid email.
    • +
  • Enter a valid email address.
    • +
  • Enter your email below to receive a password reset link.
    • +
  • Incorrect email or password. Check your details and try again.
    • +
Use * consistently to indicate [required fields](../../../components/forms-field/code.mdx#required-indicator) depending on space limitations. -
-
-- First name* +
+
+
    +
  • First name*
    • +
Use “verify” and “verification” when users need to authenticate with their credentials. -
-
-- Verification code -- Verify your account +
+
+
    +
  • Verification code
    • +
  • Verify your account
    • +
-
-- Validate -- Confirm -- Authenticate +
+
    +
  • Validate
    • +
  • Confirm
    • +
  • Authenticate
    • +
Use “first name” and “last name” instead of “surname”, “given name” or “Christian name”. -
-
-- First name / Last name +
+
+
    +
  • First name / Last name
    • +
-
-- Given name / Surname +
+
    +
  • Given name / Surname
    • +
Use “ZIP code” (US English) instead of “postcode” (UK) as we use the American English variation. -
-
-- Enter ZIP code +
+
+
    +
  • Enter ZIP code
    • +
-
-- Enter postcode +
+
    +
  • Enter postcode
    • +
Use generic password error messages to avoid leaking information. -
-
-- Failed to log in. Incorrect username or password. -- Failed to log in. Incorrect user email or password. +
+
+
    +
  • Failed to log in. Incorrect username or password.
    • +
  • Failed to log in. Incorrect user email or password.
    • +
-
-- 1 number was incorrect on this password. Try again. +
+
    +
  • 1 number was incorrect on this password. Try again.
    • +
Use generic password recovery messages to avoid leaking information. -
-
-- If that email address is in our database, we will send you an email to reset your password. -- If your email address is registered, you’ll receive a password reset email. +
+
+
    +
  • If that email address is in our database, we will send you an email to reset your password.
    • +
  • If your email address is registered, you’ll receive a password reset email.
    • +
-
-- Account is locked. +
+
    +
  • Account is locked.
    • +
Use specific authentication terms and use them consistently within workflows to avoid confusion. -
-
-- Code / Authentication code / Code verified +
+
+
    +
  • Code / Authentication code / Code verified
    • +
-
-- Code / Token / Passcode / Digits +
+
    +
  • Code / Token / Passcode / Digits
    • +
diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/onboarding.md b/docs/guidelines/language/menu-functions-and-ui-labels/onboarding.md index 810bcf8cb..bb50d153d 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/onboarding.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/onboarding.md @@ -22,102 +22,128 @@ We follow this three-step approach when writing our onboarding messages. Welcome users in the onboarding component only once with a friendly yet professional tone. -
-
-- Welcome to [application name] -- Welcome [user name] to [application name] +
+
+
    +
  • Welcome to [application name]
    • +
  • Welcome [user name] to [application name]
    • +
-
-- Welcome again to [application name] +
+
    +
  • Welcome again to [application name]
    • +
Use a friendly, professional tone that’s engaging and informative but not casual or informal. -
-
-- Get started -- Getting started +
+
+
    +
  • Get started
    • +
  • Getting started
    • +
-
-- Hey there! Let’s dive in and get you rolling! 🚀 +
+
    +
  • Hey there! Let’s dive in and get you rolling! 🚀
    • +
Avoid using marketing or selling wording, instead address users as a partner and expert. -
-
-- Connecting your mobile device is a piece of cake with our Asset Manager. +
+
+
    +
  • Connecting your mobile device is a piece of cake with our Asset Manager.
    • +
Break onboarding into small, manageable steps with bullet points, pagination or short paragraphs. -
-
-- Set up your notifications:
-   • Select the notifications you want
-   • Set quiet hours to avoid interruptions +
+
+
    +
  • Set up your notifications:
    +   • Select the notifications you want
    +   • Set quiet hours to avoid interruptions
    • +
-
-- Getting started with smart notifications. You can now choose what types of alerts you want, set quiet hours, and customize how you receive notifications so you’re not overwhelmed. +
+
    +
  • Getting started with smart notifications. You can now choose what types of alerts you want, set quiet hours, and customize how you receive notifications so you’re not overwhelmed.
    • +
Use verbs for call-to-actions, providing concrete actions or onboarding steps. -
-
-- Get started -- Start now -- Start tour -- Learn more -- Register -- Create account -- Explore the app -- Onboard devices -- Learn how to onboard assets +
+
+
    +
  • Get started
    • +
  • Start now
    • +
  • Start tour
    • +
  • Learn more
    • +
  • Register
    • +
  • Create account
    • +
  • Explore the app
    • +
  • Onboard devices
    • +
  • Learn how to onboard assets
    • +
Avoid generic call-to-actions when possible to enhance transparency and build confidence. -
-
-- OK -- Click here +
+
+
    +
  • OK
    • +
  • Click here
    • +
Use clear (but not catastrophic) wording to highlight important points for users to remember. -
-
-- Important: Always log out using your profile. Do not simply close the app. -- Make sure you “Save all” before leaving workflows to save your data. -- We recommend creating a backup of your dashboard to avoid risk of data loss. -- Note: You can always find this tour in the “About” tab. +
+
+
    +
  • Important: Always log out using your profile. Do not simply close the app.
    • +
  • Make sure you “Save all” before leaving workflows to save your data.
    • +
  • We recommend creating a backup of your dashboard to avoid risk of data loss.
    • +
  • Note: You can always find this tour in the “About” tab.
    • +
-
-- Failure to save your changes will result in permanent loss of your data. +
+
    +
  • Failure to save your changes will result in permanent loss of your data.
    • +
Provide a clear way for users to dismiss or postpone onboarding without confusion. -
-
-- Close -- Skip -- Skip and don’t show again -- Remind me at next login -
-
-- Confirm -- Proceed -- Continue -- Maybe later +
+
+
    +
  • Close
    • +
  • Skip
    • +
  • Skip and don’t show again
    • +
  • Remind me at next login
    • +
+
+
+
    +
  • Confirm
    • +
  • Proceed
    • +
  • Continue
    • +
  • Maybe later
    • +
diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/search-and-filter.md b/docs/guidelines/language/menu-functions-and-ui-labels/search-and-filter.md index 41a52735d..ee1a5bc72 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/search-and-filter.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/search-and-filter.md @@ -14,28 +14,36 @@ description: 'Industrial applications handle large datasets where users need to Use “Search” as the primary action label and avoid vague, long or technical alternatives. -
-
-- Search -- Search equipment +
+
+
    +
  • Search
    • +
  • Search equipment
    • +
-
-- Go -- Find +
+
    +
  • Go
    • +
  • Find
    • +
Use clear, specific placeholder text that indicates what users can search for in the current context. -
-
-- Search by equipment ID, serial number or location… -- Search parts by name, part number or category… -- Search… +
+
+
    +
  • Search by equipment ID, serial number or location…
    • +
  • Search parts by name, part number or category…
    • +
  • Search…
    • +
-
-- Enter search -- Type here +
+
    +
  • Enter search
    • +
  • Type here
    • +
@@ -43,74 +51,96 @@ Use clear, specific placeholder text that indicates what users can search for in Use “Advanced search” to provide access to additional search options. -
-
-- Advanced search +
+
+
    +
  • Advanced search
    • +
-
-- Additional -- Detailed search +
+
    +
  • Additional
    • +
  • Detailed search
    • +
Use “Filter by” followed by the specific attribute to make filtering options immediately clear. -
-
-- Filter by machine type -- Filter by date range +
+
+
    +
  • Filter by machine type
    • +
  • Filter by date range
    • +
-
-- Filters +
+
    +
  • Filters
    • +
Use prominent, one-click filter options for the most common filtering needs when possible. -
-
-- Quick filters: Active | Needs maintenance | Critical -- Show: All | Active only | Inactive only +
+
+
    +
  • Quick filters: Active | Needs maintenance | Critical
    • +
  • Show: All | Active only | Inactive only
    • +
Use “Apply filters” as the primary action label. -
-
-- Apply filters +
+
+
    +
  • Apply filters
    • +
-
-- Filter -- Set filters -- Find +
+
    +
  • Filter
    • +
  • Set filters
    • +
  • Find
    • +
Use “Clear" or “Clear filters” to remove all active filters at once. -
-
-- Clear -- Clear filters +
+
+
    +
  • Clear
    • +
  • Clear filters
    • +
-
-- Remove all -- Reset -- Clear +
+
    +
  • Remove all
    • +
  • Reset
    • +
  • Clear
    • +
Indicate whether filters will persist across sessions. -
-
-- Filters remain active until you clear them. -- Filters reset when you log out. -- Filters will be saved for your next session. +
+
+
    +
  • Filters remain active until you clear them.
    • +
  • Filters reset when you log out.
    • +
  • Filters will be saved for your next session.
    • +
-
-- Filters may persist. +
+
    +
  • Filters may persist.
    • +
@@ -118,56 +148,72 @@ Indicate whether filters will persist across sessions. Use clear wording when there are no results found. -
-
-- No results. -- No results found for “valve”. -- No matching equipment found. -- No results. Refine search. -- No results. Try adjusting your filters and search terms. +
+
+
    +
  • No results.
    • +
  • No results found for “valve”.
    • +
  • No matching equipment found.
    • +
  • No results. Refine search.
    • +
  • No results. Try adjusting your filters and search terms.
    • +
-
-- Failed -- Nothing found. -- Empty. +
+
    +
  • Failed
    • +
  • Nothing found.
    • +
  • Empty.
    • +
Use specific numbers and clear language to show how many results were found. -
-
-- Showing 47 of 230 machines -- 12 results found for “pressure valve” +
+
+
    +
  • Showing 47 of 230 machines
    • +
  • 12 results found for “pressure valve”
    • +
-
-- 47 items +
+
    +
  • 47 items
    • +
Include both total page count and current position when using pagination. -
-
-- Page 2 of 15 -- Showing 1-50 of 730 results +
+
+
    +
  • Page 2 of 15
    • +
  • Showing 1-50 of 730 results
    • +
-
-- Next -- Previous +
+
    +
  • Next
    • +
  • Previous
    • +
Use “Display X results per page” or “Results per page” to allow users to adjust display quantity. -
-
-- Results per page: 50 -- Display 50 results per page +
+
+
    +
  • Results per page: 50
    • +
  • Display 50 results per page
    • +
-
-- Display: 50 -- 50 +
+
    +
  • Display: 50
    • +
  • 50
    • +
@@ -175,39 +221,51 @@ Use “Display X results per page” or “Results per page” to allow users to Use “Narrow search” or “Adjust filters” when users can narrow existing search results. -
-
-- Narrow search -- Adjust filters +
+
+
    +
  • Narrow search
    • +
  • Adjust filters
    • +
-
-- Refine results -- Modify results +
+
    +
  • Refine results
    • +
  • Modify results
    • +
Use “Expand search” when users can broaden their search. -
-
-- Expand search to all locations -- Show more results +
+
+
    +
  • Expand search to all locations
    • +
  • Show more results
    • +
-
-- Broaden results +
+
    +
  • Broaden results
    • +
Use “Sort by” followed by the sorting criterion to make ordering options clear. -
-
-- Sort by: Date (newest to oldest) -- Sort by: Equipment name (a-z) -- Sort by: Priority (high to low) +
+
+
    +
  • Sort by: Date (newest to oldest)
    • +
  • Sort by: Equipment name (a-z)
    • +
  • Sort by: Priority (high to low)
    • +
-
-- Order by +
+
    +
  • Order by
    • +
@@ -215,43 +273,55 @@ Use “Sort by” followed by the sorting criterion to make ordering options cle Use actionable language when no results are found to guide users forward. -
-
-- Nothing found. Refine search. -- No alarms found in selected period. Expand period. -- No equipment found. Adjust your filters or search terms. -- No alarms found in selected time range. Try expanding the date range. +
+
+
    +
  • Nothing found. Refine search.
    • +
  • No alarms found in selected period. Expand period.
    • +
  • No equipment found. Adjust your filters or search terms.
    • +
  • No alarms found in selected time range. Try expanding the date range.
    • +
-
-- 0 results -- Nothing found -- Your search returned no results +
+
    +
  • 0 results
    • +
  • Nothing found
    • +
  • Your search returned no results
    • +
Use “Did you mean” or “Suggestions” to help users correct spelling errors or find related terms. -
-
-- Did you mean “turbine”? -- No results for “pymp”. Did you mean “pump”? -- Suggestions: motor, engine, generator +
+
+
    +
  • Did you mean “turbine”?
    • +
  • No results for “pymp”. Did you mean “pump”?
    • +
  • Suggestions: motor, engine, generator
    • +
-
-- Try: turbine +
+
    +
  • Try: turbine
    • +
Use specific, actionable error messages when search operations fail. -
-
-- Unable to complete search. Check your connection and try again. -- Search timeout. Narrow your search criteria. +
+
+
    +
  • Unable to complete search. Check your connection and try again.
    • +
  • Search timeout. Narrow your search criteria.
    • +
-
-- Search failed. -- Something went wrong. +
+
    +
  • Search failed.
    • +
  • Something went wrong.
    • +
@@ -259,27 +329,35 @@ Use specific, actionable error messages when search operations fail. Use “Recent searches” or “Search history” to display previously entered search terms. -
-
-- Recent searches +
+
+
    +
  • Recent searches
    • +
-
-- Previous -- History +
+
    +
  • Previous
    • +
  • History
    • +
Use “Save search” or “Save search criteria” to allow users to store frequently used searches. -
-
-- Save search. -- Save search criteria as “Active pumps in Building A” +
+
+
    +
  • Save search.
    • +
  • Save search criteria as “Active pumps in Building A”
    • +
-
-- Save -- Store -- Remember search +
+
    +
  • Save
    • +
  • Store
    • +
  • Remember search
    • +
@@ -287,47 +365,67 @@ Use “Save search” or “Save search criteria” to allow users to store freq Use clear labels for logical operators (AND, OR, NOT) that explain how conditions combine. -
-
-- Status: Active AND Location: Munich -- Type: Pump OR Type: Compressor +
+
+
    +
  • Status: Active AND Location: Munich
    • +
  • Type: Pump OR Type: Compressor
    • +
-
-- Active & Munich +
+
    +
  • Active & Munich
    • +
Provide templates for common conditional searches. -
-
--
Template: Active equipment needing maintenance
-Status: Active AND Maintenance: Due
--
Template: High priority work orders for team A
-Priority: High AND Assigned team: Team A
--
Template: Temperature readings
-Sensor: Temperature AND Value: > 100
+
+
+
    +
  • Template: Active equipment needing maintenance
    + Status: Active AND Maintenance: Due
    • +
  • Template: High priority work orders for team A
    + Priority: High AND Assigned team: Team A
    • +
  • Template: Temperature readings
    + Sensor: Temperature AND Value: > 100
    • +
Tell users when conditions create impossible or contradictory queries. -
-
-- Status cannot be both Active AND Inactive. Refine filter. -- This combination will return no results. Refine filter. +
+
+
    +
  • Status cannot be both Active AND Inactive. Refine filter.
    • +
  • This combination will return no results. Refine filter.
    • +
-
-- Invalid search +
+
    +
  • Invalid search
    • +
## Dos and Don’ts -- Do provide simple examples or templates for common conditional searches to help users get started -- Do offer actionable next steps and helpful suggestions when searches fail or return no results -- Don’t provide unhelpful “Try again” recommendations that provide no guidance on what to do next -- Don’t use generic or vague labels like “Go”, “Find” or “Error” +
+
+
    +
  • Do provide simple examples or templates for common conditional searches to help users get started
    • +
  • Do offer actionable next steps and helpful suggestions when searches fail or return no results
    • +
+
+
+
    +
  • Don’t provide unhelpful “Try again” recommendations that provide no guidance on what to do next
    • +
  • Don’t use generic or vague labels like “Go”, “Find” or “Error”
    • +
+
+
## Related diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/ui-terminology.md b/docs/guidelines/language/menu-functions-and-ui-labels/ui-terminology.md index f290fce45..b13494eb9 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/ui-terminology.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/ui-terminology.md @@ -14,29 +14,35 @@ description: 'Using well-defined terms help users understand actions, navigate s Always consider the difference between user actions within a desktop environment (based on mouse or keyboard usage) and mobile devices based on touch gestures. -
-
-- click (desktop) -- tap (mobile device) -- select (when not sure if desktop or mobile) +
+
+
    +
  • click (desktop)
    • +
  • tap (mobile device)
    • +
  • select (when not sure if desktop or mobile)
    • +
Use clear and precise terms that leave no room for misunderstandings. -
-
-- delete (if you want to erase data, e.g. a file) -- remove (if you want to take data away, e.g. permissions) +
+
+
    +
  • delete (if you want to erase data, e.g. a file)
    • +
  • remove (if you want to take data away, e.g. permissions)
    • +
Use “select” for multi-platform applications where the input method varies (tap, click, etc.). -
-
-- Select the checkbox to enable notifications. -- Select and hold the Shift key to select multiple items. +
+
+
    +
  • Select the checkbox to enable notifications.
    • +
  • Select and hold the Shift key to select multiple items.
    • +
@@ -52,12 +58,16 @@ This section provides clear definitions for the most frequently used mouse-relat - right-click - middle-click (scroll wheel) -
-
-- click +
+
+
    +
  • click
    • +
-
-- press +
+
    +
  • press
    • +
@@ -68,12 +78,16 @@ This section provides clear definitions for the most frequently used mouse-relat - hover - scroll -
-
-- hover +
+
+
    +
  • hover
    • +
-
-- mouse over +
+
    +
  • mouse over
    • +
@@ -111,32 +125,40 @@ As touchscreen interfaces rely on direct finger interaction, this section covers Use "press" when referring to the physical action of pressing a key. -
-
-- Press Enter to confirm -- Press Spacebar to play or pause +
+
+
    +
  • Press Enter to confirm
    • +
  • Press Spacebar to play or pause
    • +
-
-- Hit Enter -- Strike Enter -- Depress Enter +
+
    +
  • Hit Enter
    • +
  • Strike Enter
    • +
  • Depress Enter
    • +
Capitalize special keys and directions. -
-
-- Enter / Tab / Shift / Ctrl / Alt -- Up Arrow / Down Arrow / Left Arrow / Right Arrow +
+
+
    +
  • Enter / Tab / Shift / Ctrl / Alt
    • +
  • Up Arrow / Down Arrow / Left Arrow / Right Arrow
    • +
Use "type" when asking users to enter text. -
-
-- Type admin in the username field. +
+
+
    +
  • Type admin in the username field.
    • +
@@ -144,30 +166,38 @@ Use "type" when asking users to enter text. Use standardized and consistent terminology to describe UI components and input elements. -
-
-- checkbox +
+
+
    +
  • checkbox
    • +
-
-- box -- option box -- selection box -- tick box +
+
    +
  • box
    • +
  • option box
    • +
  • selection box
    • +
  • tick box
    • +
Avoid mixing terms within the same products and portfolios. -
-
-- To enable automatic updates, select the checkbox to activate Auto update. -- Click this image -- The link opens in a new window. +
+
+
    +
  • To enable automatic updates, select the checkbox to activate Auto update.
    • +
  • Click this image
    • +
  • The link opens in a new window.
    • +
-
-- To enable automatic updates, select the box to activate Auto update. -- Click this picture -- The link opens in a new browser. +
+
    +
  • To enable automatic updates, select the box to activate Auto update.
    • +
  • Click this picture
    • +
  • The link opens in a new browser.
    • +
@@ -214,10 +244,20 @@ Many actions come in natural pairs or opposites. Using the right pairs help user ## Dos and Don’ts -- Do maintain the same terms for the same actions across all screens -- Do use specific and standardized component names -- Do consider the user environment, e.g. mobile, desktop, touchscreen -- Don’t use generic, invented or vague terms where terminology already exists +
+
+
    +
  • Do maintain the same terms for the same actions across all screens
    • +
  • Do use specific and standardized component names
    • +
  • Do consider the user environment, e.g. mobile, desktop, touchscreen
    • +
+
+
+
    +
  • Don’t use generic, invented or vague terms where terminology already exists
    • +
+
+
## Related diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md b/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md index f0484fa71..92568a536 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/user-management.md @@ -28,138 +28,182 @@ Use “permissions” instead of “right” and “privilege” as these are be Write user roles in short, clear and descriptive terms and give users access to role descriptions. -
-
-- Line operator +
+
+
    +
  • Line operator
    • +
-
-- Basic user +
+
    +
  • Basic user
    • +
Use role names consistently within workflows and across the whole product. -
-
-- Device administrator / Device administrator / Device administrator +
+
+
    +
  • Device administrator / Device administrator / Device administrator
    • +
-
-- Device Admin / Asset Admins / Administrator / Device Manager / Officer for devices +
+
    +
  • Device Admin / Asset Admins / Administrator / Device Manager / Officer for devices
    • +
Focus on personas instead of generic and unclear titles when creating roles for your product. -
-
-- Line operator -- Plant operator -- Service engineer +
+
+
    +
  • Line operator
    • +
  • Plant operator
    • +
  • Service engineer
    • +
-
-- Technician -- Team lead -- Expert user +
+
    +
  • Technician
    • +
  • Team lead
    • +
  • Expert user
    • +
Avoid mixing location with function when creating roles for your product. -
-
-- User +
+
+
    +
  • User
    • +
-
-- External user -- Local user -- International user +
+
    +
  • External user
    • +
  • Local user
    • +
  • International user
    • +
Avoid creating vague user roles without a clear persona or scope that can be misunderstood. -
-
-- Production report creator -- Quality report reviewer -- Batch approver (review and release) +
+
+
    +
  • Production report creator
    • +
  • Quality report reviewer
    • +
  • Batch approver (review and release)
    • +
-
-- Read-only user -- Write-only user +
+
    +
  • Read-only user
    • +
  • Write-only user
    • +
Use “read only” as a specific role permission, not a unique role name. -
-
-- External consultant (read-only) +
+
+
    +
  • External consultant (read-only)
    • +
-
-- Read-only user +
+
    +
  • Read-only user
    • +
Avoid easily misunderstood permissions such as “view”, be specific about what users can do. -
-
-- record / log / configure / override -- adjust / review / modify / correct -- monitor / review / inspect -- track / display / observe +
+
+
    +
  • record / log / configure / override
    • +
  • adjust / review / modify / correct
    • +
  • monitor / review / inspect
    • +
  • track / display / observe
    • +
-
-- write -- edit -- read-only -- view +
+
    +
  • write
    • +
  • edit
    • +
  • read-only
    • +
  • view
    • +
Use sentence case for all user roles. -
-
-- Service engineer +
+
+
    +
  • Service engineer
    • +
-
-- Service Engineer +
+
    +
  • Service Engineer
    • +
Avoid jargon or internal terms, instead use language everyone understands. -
-
-- Plant manager +
+
+
    +
  • Plant manager
    • +
-
-- Top tier +
+
    +
  • Top tier
    • +
Keep role names short, preferably not more than three words. -
-
-- Safety incident investigator -- Shift handover reporter +
+
+
    +
  • Safety incident investigator
    • +
  • Shift handover reporter
    • +
-
-- Gateway and portal maintenance manager for Plant 3 and 5 (read-only permissions) +
+
    +
  • Gateway and portal maintenance manager for Plant 3 and 5 (read-only permissions)
    • +
Avoid using functions or features as roles or permissions, instead focus on persona and tasks. -
-
-- Shift supervisor – Production floor +
+
+
    +
  • Shift supervisor – Production floor
    • +
-
-- Dashboard user +
+
    +
  • Dashboard user
    • +
@@ -199,104 +243,142 @@ Many user management words often appear together in familiar, expected combinati Avoid using “deny” and “disapprove” with “user” as opposites to “approve”. -
-
-- Reject access request +
+
+
    +
  • Reject access request
    • +
-
-- Admin denied user -- Disapprove user +
+
    +
  • Admin denied user
    • +
  • Disapprove user
    • +
Avoid using “deauthenticate” as the opposite of authenticate. -
-
-- Log out -- End session +
+
+
    +
  • Log out
    • +
  • End session
    • +
-
-- Deauthenticate -- Click to deauthenticate +
+
    +
  • Deauthenticate
    • +
  • Click to deauthenticate
    • +
Avoid using “grant” with “permissions” in casual UI contexts as this has become outdated. -
-
-- Assign permissions to user -- Give user access to reports +
+
+
    +
  • Assign permissions to user
    • +
  • Give user access to reports
    • +
-
-- Grant permissions to user +
+
    +
  • Grant permissions to user
    • +
Avoid using “read” for viewing UI elements like profiles, permissions and roles. -
-
-- View user profile -- View role details +
+
+
    +
  • View user profile
    • +
  • View role details
    • +
-
-- Read user profile -- Read permissions +
+
    +
  • Read user profile
    • +
  • Read permissions
    • +
Avoid using “write” for editing or modifying UI elements. -
-
-- Edit permissions -- Modify settings +
+
+
    +
  • Edit permissions
    • +
  • Modify settings
    • +
-
-- Write permissions -- Write role details -- Write to database +
+
    +
  • Write permissions
    • +
  • Write role details
    • +
  • Write to database
    • +
Avoid using “delete” for simple removals; use “delete” only for permanent erasure. -
-
-- Unassign -- Remove user from team -- Remove role from user -- Delete user account (permanent) -- Delete file (permanent) +
+
+
    +
  • Unassign
    • +
  • Remove user from team
    • +
  • Remove role from user
    • +
  • Delete user account (permanent)
    • +
  • Delete file (permanent)
    • +
-
-- Delete user from team -- Delete role from user +
+
    +
  • Delete user from team
    • +
  • Delete role from user
    • +
Avoid using “revoke” with people and users as direct objects. -
-
-- Revoke all permissions -- Revoke API key +
+
+
    +
  • Revoke all permissions
    • +
  • Revoke API key
    • +
-
-- Revoke user -- Revoke the employee +
+
    +
  • Revoke user
    • +
  • Revoke the employee
    • +
## Dos and Don’ts -- Do ensure role behaviors are transparent and easy to understand -- Do use clear, descriptive role names that reflect user responsibilities -- Do group related permissions logically within roles -- Don’t create excessive amounts of roles because this causes confusion -- Don’t create overlapping roles with unclear differences +
+
+
    +
  • Do ensure role behaviors are transparent and easy to understand
    • +
  • Do use clear, descriptive role names that reflect user responsibilities
    • +
  • Do group related permissions logically within roles
    • +
+
+
+
    +
  • Don’t create excessive amounts of roles because this causes confusion
    • +
  • Don’t create overlapping roles with unclear differences
    • +
+
+
## Related diff --git a/docs/guidelines/language/menu-functions-and-ui-labels/whats-new-announcements.md b/docs/guidelines/language/menu-functions-and-ui-labels/whats-new-announcements.md index 39d1654c6..d8ab0ea81 100644 --- a/docs/guidelines/language/menu-functions-and-ui-labels/whats-new-announcements.md +++ b/docs/guidelines/language/menu-functions-and-ui-labels/whats-new-announcements.md @@ -22,84 +22,110 @@ We follow this three-step approach when creating our updates. They explain what Use the wording “What’s new…” for the heading without a question mark (?) or period. -
-
-- What’s new in October -- What’s new in Version 3.2 -- What’s new this month +
+
+
    +
  • What’s new in October
    • +
  • What’s new in Version 3.2
    • +
  • What’s new this month
    • +
-
-- What’s new this month? +
+
    +
  • What’s new this month?
    • +
Use a contraction in the heading, i.e. “What’s” not “What is”. -
-
-- What’s new in October +
+
+
    +
  • What’s new in October
    • +
-
-- What is new in October +
+
    +
  • What is new in October
    • +
Use paragraphs or bullet points to present or highlight one point at a time instead of italics or bold. -
-
-- What’s new in the dashboard
-  • Edit with new filter options.
-  • Set up zones to itemize your assets. +
+
+
    +
  • What’s new in the dashboard
    +   • Edit with new filter options.
    +   • Set up zones to itemize your assets.
    • +
-
-- What’s new in the dashboard. Now includes customizable widgets, allowing you to tailor your view to your specific needs, new ways to edit your dashboards by moving or adjusting filters to help you with your day, and zones for dashboards such as by plant or groups to itemize your assets more easily. +
+
    +
  • What’s new in the dashboard. Now includes customizable widgets, allowing you to tailor your view to your specific needs, new ways to edit your dashboards by moving or adjusting filters to help you with your day, and zones for dashboards such as by plant or groups to itemize your assets more easily.
    • +
Use a personal and engaging tone without being too informal (avoid emojis or slang). -
-
-- With this new version we bring you new features and improvements to enhance your experience. +
+
+
    +
  • With this new version we bring you new features and improvements to enhance your experience.
    • +
-
-- Yo fam, we’ve been grinding to drop some lit upgrades to level up your vibe! 🚀✨ +
+
    +
  • Yo fam, we’ve been grinding to drop some lit upgrades to level up your vibe! 🚀✨
    • +
Provide a clear way for users to dismiss announcements without confusion. -
-
-- Close -- Skip -- Skip and don’t show again +
+
+
    +
  • Close
    • +
  • Skip
    • +
  • Skip and don’t show again
    • +
-
-- Confirm -- Proceed -- Continue +
+
    +
  • Confirm
    • +
  • Proceed
    • +
  • Continue
    • +
Provide a clear way for users to postpone announcements. -
-
-- Not now -- Remind me at next login +
+
+
    +
  • Not now
    • +
  • Remind me at next login
    • +
-
-- Maybe later +
+
    +
  • Maybe later
    • +
Avoid technical, negative or wordy dismiss actions. -
-
-- Terminate dialog -- No, I don’t want to improve my workflow -- I confirm I understand this announcement and wish to close this notification +
+
+
    +
  • Terminate dialog
    • +
  • No, I don’t want to improve my workflow
    • +
  • I confirm I understand this announcement and wish to close this notification
    • +
diff --git a/docs/guidelines/language/messaging/empty-state-messages.mdx b/docs/guidelines/language/messaging/empty-state-messages.mdx index 9c331111a..251f2b043 100644 --- a/docs/guidelines/language/messaging/empty-state-messages.mdx +++ b/docs/guidelines/language/messaging/empty-state-messages.mdx @@ -20,62 +20,84 @@ We follow this three-step approach when creating our empty-state messages. They Use the template when the error stops users moving forward. -
-
- -
Heading: No zones added
- Description: Add zones to your profile to see them listed here.
- Button: Add zones
+
+
+
    +
  • Heading: No zones added
    + Description: Add zones to your profile to see them listed here.
    + Button: Add zones
    • +
-
- -
Heading: No zones created
- Description: Add region from your dashboard.
- Button: Make sectors
+
+
    +
  • Heading: No zones created
    + Description: Add region from your dashboard.
    + Button: Make sectors
    • +
Use clear action verbs to show users how to fill the empty state. -
-
- - -
Heading: No users added
+
+
+
    +
  • Heading: No users added
    Description: Add users in User management.
    - Button: Open User management
    - + Button: Open User management
+
Use neutral framing of the empty state and avoid making it seem like a user failure. -
-
-- No users added +
+
+
    +
  • No users added
    • +
-
-- You haven’t added any of your users +
+
    +
  • You haven’t added any of your users
    • +
Avoid “yet” or other expectation-related terms in headings. -
-
-- Heading: No users added +
+
+
    +
  • Heading: No users added
    • +
-
-- Heading: No users added yet +
+
    +
  • Heading: No users added yet
    • +
## Dos and Don’ts -- Do make all messages consistent in terms of grammar and punctuation -- Do make sure users understand the space is not an error or a bug -- Do provide an option to fill the empty space with a button or link -- Don’t overcommunicate about the function of the empty state +
+
+
    +
  • Do make all messages consistent in terms of grammar and punctuation
    • +
  • Do make sure users understand the space is not an error or a bug
    • +
  • Do provide an option to fill the empty space with a button or link
    • +
+
+
+
    +
  • Don’t overcommunicate about the function of the empty state
    • +
+
+
## Related diff --git a/docs/guidelines/language/messaging/error-messages.mdx b/docs/guidelines/language/messaging/error-messages.mdx index 8dfba5ce1..d8650119d 100644 --- a/docs/guidelines/language/messaging/error-messages.mdx +++ b/docs/guidelines/language/messaging/error-messages.mdx @@ -27,157 +27,205 @@ Although not every error message in a product requires all three steps, aim for Use the template when the error stops users moving forward. -
-
-- Heading: No data received
-Description: Unable to receive data as sensor is inactive.
-Instructions: Check sensor / Open sensor management +
+
+
    +
  • Heading: No data received
    + Description: Unable to receive data as sensor is inactive.
    + Instructions: Check sensor / Open sensor management
    • +
Avoid generic error messages or codes, instead provide specific data, value and solutions. -
-
-- Failed to export data due to a connection error. +
+
+
    +
  • Failed to export data due to a connection error.
    • +
-
-- Something happened. -- An error occurred. -- Error 172.00046ERR +
+
    +
  • Something happened.
    • +
  • An error occurred.
    • +
  • Error 172.00046ERR
    • +
Give clear reasons for input validation errors to ease user frustration. -
-
-- Value out of range. Enter a number between 1 and 100. -- Number between 1 and 100 required. +
+
+
    +
  • Value out of range. Enter a number between 1 and 100.
    • +
  • Number between 1 and 100 required.
    • +
-
-- Invalid value. +
+
    +
  • Invalid value.
    • +
Avoid repeating your message in both the title and description. -
-
-- Bad request: Sorry, we could not process the request. Please check and try again. +
+
+
    +
  • Bad request: Sorry, we could not process the request. Please check and try again.
    • +
-
-- Bad request. Sorry, bad request. +
+
    +
  • Bad request. Sorry, bad request.
    • +
Avoid blaming the user with “you” and “your” and use passive voice as an exception. -
-
-- Device could not be deleted. -- Failed to delete device. +
+
+
    +
  • Device could not be deleted.
    • +
  • Failed to delete device.
    • +
-
-- You have failed to delete the device. +
+
    +
  • You have failed to delete the device.
    • +
Provide specific and clear solutions to avoid making assumptions about user knowledge. -
-
-- Unsupported file type. Upload supported file types: .pdf and .docx. +
+
+
    +
  • Unsupported file type. Upload supported file types: .pdf and .docx.
    • +
-
-- Unsupported file type. Upload the supported and correct file type. +
+
    +
  • Unsupported file type. Upload the supported and correct file type.
    • +
If the error is our responsibility and fault, use authentic and transparent apologies. -
-
-- We’ve moved this page. Please check the changelog for the new location. +
+
+
    +
  • We’ve moved this page. Please check the changelog for the new location.
    • +
-
-- Sorry you entered the wrong address. +
+
    +
  • Sorry you entered the wrong address.
    • +
Use “please” only for extra or unexpected user actions that correct system-caused disruptions. -
-
-- Heading: Page Not Found
-Description: We could not find what you were looking for.
-Instruction: Please contact the owner of the site that linked you to the original URL and let them know their link is broken. +
+
+
    +
  • Heading: Page Not Found
    + Description: We could not find what you were looking for.
    + Instruction: Please contact the owner of the site that linked you to the original URL and let them know their link is broken.
    • +
Show urgency with wording, e.g. “immediately” if there are consequences from ignoring the error. -
-
-- Update your software version immediately to avoid losing data. +
+
+
    +
  • Update your software version immediately to avoid losing data.
    • +
Use positive framing and avoid negative and alarming words like “wrong” and “catastrophic”. -
-
-- Value out of range. Enter a number between 1 and 100. +
+
+
    +
  • Value out of range. Enter a number between 1 and 100.
    • +
-
-- Wrong number. +
+
    +
  • Wrong number.
    • +
Use softening words, e.g. unfortunately and avoid negative contractions (“do not” instead of “don’t”). -
-
-- Unfortunately, you cannot open this page. +
+
+
    +
  • Unfortunately, you cannot open this page.
    • +
-
-- You don't have access. -- You can't open this page. +
+
    +
  • You don't have access.
    • +
  • You can't open this page.
    • +
Be honest and transparent when you cannot explain the error or how to move the user forward. -
-
-- Something went wrong and we couldn't complete your request. Try again later. +
+
+
    +
  • Something went wrong and we couldn't complete your request. Try again later.
    • +
-
-- Operation stopped for unknown reason. +
+
    +
  • Operation stopped for unknown reason.
    • +
Avoid generic wording telling users to contact their admin or support as this is unhelpful. -
-
-- Open the chat window and paste the error into the input field for support. -- Send error log to administrator. +
+
+
    +
  • Open the chat window and paste the error into the input field for support.
    • +
  • Send error log to administrator.
    • +
-
-- Contact admin to solve this issue. +
+
    +
  • Contact admin to solve this issue.
    • +
Avoid overpromising solutions to errors unless the team is working on the problem. -
-
- - Our team is working overtime to fix this for you and it will be fixed by morning. +
+
+
    +
  • Our team is working overtime to fix this for you and it will be fixed by morning.
    • +
@@ -185,11 +233,21 @@ Avoid overpromising solutions to errors unless the team is working on the proble ## Dos and Don’ts -* Do make all messages consistent in terms of grammar and punctuation -* Do take the blame when the error originates from your app or product -* Do give users a reversible solution whenever possible -* Don’t panic your users with dramatic or urgent language -* Don’t use all upper case characters +
+
+
    +
  • Do make all messages consistent in terms of grammar and punctuation
    • +
  • Do take the blame when the error originates from your app or product
    • +
  • Do give users a reversible solution whenever possible
    • +
+
+
+
    +
  • Don’t panic your users with dramatic or urgent language
    • +
  • Don’t use all upper case characters
    • +
+
+
## Related diff --git a/docs/guidelines/language/messaging/error-pages.md b/docs/guidelines/language/messaging/error-pages.md index f05623820..fae955804 100644 --- a/docs/guidelines/language/messaging/error-pages.md +++ b/docs/guidelines/language/messaging/error-pages.md @@ -27,45 +27,61 @@ We follow these templates when creating our main error pages. Although some of t Use the official code and definition so users can search for code terms and information themselves. -
-
-- 401 Unauthorized +
+
+
    +
  • 401 Unauthorized
    • +
-
-- 401 Unlawful +
+
    +
  • 401 Unlawful
    • +
Use language suitable for all target users, including non-native English speakers. -
-
-- This page is not available right now. Try again later. +
+
+
    +
  • This page is not available right now. Try again later.
    • +
-
-- An unforeseen server-side condition prevented the fruitful processing of your request. This indicates an issue within our infrastructure, not a client-side input error. +
+
    +
  • An unforeseen server-side condition prevented the fruitful processing of your request. This indicates an issue within our infrastructure, not a client-side input error.
    • +
Avoid jokes, memes, emojis or casual wording in error pages for industrial applications. -
-
-- 401 Unauthorized +
+
+
    +
  • 401 Unauthorized
    • +
-
-- Hold on! VIP access only! 🎩✨ +
+
    +
  • Hold on! VIP access only! 🎩✨
    • +
Use sentence casing within the description with minimal punctuation and formatting. -
-
-- There is an error on this page. Try again later. +
+
+
    +
  • There is an error on this page. Try again later.
    • +
-
-- There is an ERROR on this **page**! Try again later. +
+
    +
  • There is an ERROR on this **page**! Try again later.
    • +
diff --git a/docs/guidelines/language/messaging/infotips.mdx b/docs/guidelines/language/messaging/infotips.mdx index 9819596fe..76232e98f 100644 --- a/docs/guidelines/language/messaging/infotips.mdx +++ b/docs/guidelines/language/messaging/infotips.mdx @@ -15,89 +15,117 @@ description: 'Infotips are short, context-sensitive messages that appear near us Use sentence case and end with a period (similar to tooltips). -
-
-- View the current status of the production line. +
+
+
    +
  • View the current status of the production line.
    • +
-
-- VIEW CURRENT STATUS OF PRODUCTION LINE +
+
    +
  • VIEW CURRENT STATUS OF PRODUCTION LINE
    • +
Use infotips to support users with guidance and contextual information. -
-
-- Maximum allowable hydraulic pressure (bar). -- Current motor load in percentage. -- Enables automatic system recalibration. -- Unique identifier for the production batch. +
+
+
    +
  • Maximum allowable hydraulic pressure (bar).
    • +
  • Current motor load in percentage.
    • +
  • Enables automatic system recalibration.
    • +
  • Unique identifier for the production batch.
    • +
Use infotips to help users understand complex terminology. -
-
-- SCADA System
-Supervisory Control and Data Acquisition: A system that monitors and controls industrial processes locally or at remote locations.
-- PLC cycle time
-This indicates the time (in milliseconds) it takes for the Programmable Logic Controller to execute one full scan of its program logic. +
+
+
    +
  • SCADA System
    + Supervisory Control and Data Acquisition: A system that monitors and controls industrial processes locally or at remote locations.
    • +
  • PLC cycle time
    + This indicates the time (in milliseconds) it takes for the Programmable Logic Controller to execute one full scan of its program logic.
    • +
Use infotips to help users understand complex features and workflows. -
-
-- Set thresholds
-Set project thresholds here. Adjust the value to trigger alerts when the temperature exceeds a specified limit (e.g. 80°C).
-- PID controller tuning
-Adjust these parameters (Proportional, Integral, Derivative) to optimize the system's response to errors and achieve stable control. -- Schedule maintenance
-This workflow guides you through planning and assigning preventive maintenance tasks. First, select the asset, then define the task type, and finally set the recurrence schedule. +
+
+
    +
  • Set thresholds
    + Set project thresholds here. Adjust the value to trigger alerts when the temperature exceeds a specified limit (e.g. 80°C).
    • +
  • PID controller tuning
    + Adjust these parameters (Proportional, Integral, Derivative) to optimize the system's response to errors and achieve stable control.
    • +
  • Schedule maintenance
    + This workflow guides you through planning and assigning preventive maintenance tasks. First, select the asset, then define the task type, and finally set the recurrence schedule.
    • +

Use paragraphs to split complex information and use bullet points or lists for clarity. -
-
-- Power meter monitoring
-Area: Production floor
-Present consumption: 120 kW
-Peak: 150 kW
-Button: Open meter list +
+
+
    +
  • Power meter monitoring
    + Area: Production floor
    + Present consumption: 120 kW
    + Peak: 150 kW
    + Button: Open meter list
    • +
Use imperative verbs (commands) for instructions and guidance. -
-
-- Assign a unique identifier to each physical asset for tracking, maintenance scheduling, and inventory management.
-- Define and manage sequences of operations and ingredient quantities for automated production processes. +
+
+
    +
  • Assign a unique identifier to each physical asset for tracking, maintenance scheduling, and inventory management.
    • +
  • Define and manage sequences of operations and ingredient quantities for automated production processes.
    • +
Avoid personal pronouns (you, we, our, etc.). -
-
-- Select a device from the network to begin configuration. +
+
+
    +
  • Select a device from the network to begin configuration.
    • +
-
-- Select one of your devices to begin configuring your factory assets. +
+
    +
  • Select one of your devices to begin configuring your factory assets.
    • +
## Dos and Don’ts -* Do keep infotips short and instructional -* Don’t include critical or legal information -* Don’t copy your user manual into your infotips +
+
+
    +
  • Do keep infotips short and instructional
    • +
+
+
+
    +
  • Don’t include critical or legal information
    • +
  • Don’t copy your user manual into your infotips
    • +
+
+
## Related diff --git a/docs/guidelines/language/messaging/messages-overview.md b/docs/guidelines/language/messaging/messages-overview.md index bbfe40ac1..90be8d968 100644 --- a/docs/guidelines/language/messaging/messages-overview.md +++ b/docs/guidelines/language/messaging/messages-overview.md @@ -29,123 +29,167 @@ First define your use case and message type from the list below, then use this o Use sentence casing for all message descriptions (except toast messages) and add full stops. -
-
- - Create zones from your dashboard. - - You have no new notifications. -
-
- - Add regions from your dashboard +
+
+
    +
  • Create zones from your dashboard.
    • +
  • You have no new notifications.
    • +
+
+
+
    +
  • Add regions from your dashboard
    • +
Avoid overcommunicating by only adding relevant, beneficial information to your messages. -
-
- - We received your error report and will process it within 24 to 48 hours. +
+
+
    +
  • We received your error report and will process it within 24 to 48 hours.
    • +
-
- - The support team has received your bug report but they only work from 9–5 CEST time at the moment and there is a skeleton crew working over the summer. +
+
    +
  • The support team has received your bug report but they only work from 9–5 CEST time at the moment and there is a skeleton crew working over the summer.
    • +
Provide specifics, e.g. objects, values, reasons and solutions, instead of generic messaging. -
-
- - Failed to upload file due to connection error. +
+
+
    +
  • Failed to upload file due to connection error.
    • +
-
- - Something happened. - - An error occurred. +
+
    +
  • Something happened.
    • +
  • An error occurred.
    • +
Use urgent wording to signal serious and irreversible consequences from ignoring messages. -
-
- - Immediate software update required to save data securely. - - Update software now to save data. - - Contact support by 14:00 CET to avoid shutdown. - - Urgent: Order spare part replacement by August 31st for valve 532/a. +
+
+
    +
  • Immediate software update required to save data securely.
    • +
  • Update software now to save data.
    • +
  • Contact support by 14:00 CET to avoid shutdown.
    • +
  • Urgent: Order spare part replacement by August 31st for valve 532/a.
    • +
Use the same key words in your messaging, but do not repeat headings and descriptions. -
-
- - **Heading:** Bad request
- **Description:** We could not process your request. Check and try again. +
+
+
    +
  • **Heading:** Bad request
    + **Description:** We could not process your request. Check and try again.
    • +
-
- - **Heading:** Bad request
- **Description:** Bad request. +
+
    +
  • **Heading:** Bad request
    + **Description:** Bad request.
    • +
Use the same grammar patterns across all your messaging within your product. -
-
- - No assets added. / No dashboards created. / No data downloaded. +
+
+
    +
  • No assets added. / No dashboards created. / No data downloaded.
    • +
-
- - No assets added. / You haven’t added any assets. / You have no assets yet. +
+
    +
  • No assets added. / You haven’t added any assets. / You have no assets yet.
    • +
Avoid asking patronizing “Are you sure…?” questions to your expert users. -
-
- - Deleting this file removes all dependencies. +
+
+
    +
  • Deleting this file removes all dependencies.
    • +
-
- - Are you sure you want to delete this file? +
+
    +
  • Are you sure you want to delete this file?
    • +
Use action labels that match the action of the message without mixing verbs or using synonyms. -
-
- - Close - - Save - - Continue - - Delete -
-
- - OK - - Confirm +
+
+
    +
  • Close
    • +
  • Save
    • +
  • Continue
    • +
  • Delete
    • +
+
+
+
    +
  • OK
    • +
  • Confirm
    • +
Allow users to go back to change actions and avoid “OK” which is often understood as “Yes”. -
-
- - Heading: Unsaved changes
- Description: You are about to leave the page. Unsaved changes will be lost.
- Button: Exit without saving
- Button: Go back -
-
- - Description: Are you sure you want to cancel?
- Button: OK
- Button: Cancel
- Button: Yes +
+
+
    +
  • Heading: Unsaved changes
    + Description: You are about to leave the page. Unsaved changes will be lost.
    + Button: Exit without saving
    + Button: Go back
    • +
+
+
+
    +
  • Description: Are you sure you want to cancel?
    + Button: OK
    + Button: Cancel
    + Button: Yes
    • +
## Dos and Don’ts -- Do first classify what kind of message is required -- Do make a record or changelog of your messages for consistency and changes -- Don’t over communicate with irrelevant or unrelated information -- Don’t repeat the exact same wording in both the heading and description +
+
+
    +
  • Do first classify what kind of message is required
    • +
  • Do make a record or changelog of your messages for consistency and changes
    • +
+
+
+
    +
  • Don’t over communicate with irrelevant or unrelated information
    • +
  • Don’t repeat the exact same wording in both the heading and description
    • +
+
+
## Related diff --git a/docs/guidelines/language/messaging/non-critical-information-messages.mdx b/docs/guidelines/language/messaging/non-critical-information-messages.mdx index a6585cdef..42e3f1a83 100644 --- a/docs/guidelines/language/messaging/non-critical-information-messages.mdx +++ b/docs/guidelines/language/messaging/non-critical-information-messages.mdx @@ -15,106 +15,146 @@ description: Non-critical information messages come from the system and keep use Keep messages short and concise. -
-
-- Pump 3 cycle complete 14:32. +
+
+
    +
  • 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). +
+
    +
  • 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. +
+
+
    +
  • 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!
    • +
Use clear timestamps for context, clarity, prioritization and record keeping. -
-
-- Motor overload detected at 14:01:15 -- Emergency stop activated at 21:03:27 +
+
+
    +
  • 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. +
+
    +
  • 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 complete.
    • +
  • System backup completed at 15:00.
    • +
-
-- System backup done! Open and check now! +
+
    +
  • 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. No further action required.
    • +
-
-- Sensors calibrated. Click to check sensors (live link), calibration settings (live link) or manage your sensors (live link). +
+
    +
  • 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. +
+
+
    +
  • 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. +
+
+
    +
  • System update on line 4 starts at 14:00.
    • +
-
-- Notification: System update! Line: 4 / Starts: 14:00. +
+
    +
  • Notification: System update! Line: 4 / Starts: 14:00.
    • +
Use industrial icons only when absolutely necessary and avoid emojis. -
-
-- Line 3 shift schedule changed. See what's new. +
+
+
    +
  • 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.
    • +
-## Dos and Don'ts +## 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 +
+
+
    +
  • 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 * [Tooltips](./tooltips.mdx) * [Infotips](./infotips.mdx) -* [Toast messages](./toast-messages.mdx) \ No newline at end of file +* [Toast messages](./toast-messages.mdx) diff --git a/docs/guidelines/language/messaging/progress-updates.mdx b/docs/guidelines/language/messaging/progress-updates.mdx index fe9d987f9..e7e7dc29e 100644 --- a/docs/guidelines/language/messaging/progress-updates.mdx +++ b/docs/guidelines/language/messaging/progress-updates.mdx @@ -14,147 +14,200 @@ description: While some companies use humorous text like "Chopping the onions… Use sentence case to align with our UX writing guidelines. -
-
-- Downloading assets… +
+
+
    +
  • Downloading assets…
    • +
-
-- Downloading Assets… +
+
    +
  • Downloading Assets…
    • +
Use the present simple progressive (continuous, -ing) verb form to indicate ongoing actions. -
-
-- Loading… -- Downloading… -- Charging… -- Saving… -- Searching… +
+
+
    +
  • Loading…
    • +
  • Downloading…
    • +
  • Charging…
    • +
  • Saving…
    • +
  • Searching…
    • +
-
-- Been loading… -- To be loading… -- Will be loading… +
+
    +
  • Been loading…
    • +
  • To be loading…
    • +
  • Will be loading…
    • +
Use verbs before nouns to focus on the action and make messages easier to scan. -
-
-- Loading file… +
+
+
    +
  • Loading file…
    • +
-
-- File loading… +
+
    +
  • File loading…
    • +
Use horizontal ellipses (…) after the verb without a space instead of adding three full stops (unicode U+2026, Mac Option+/Windows ALT+0133). -
-
-- Loading… +
+
+
    +
  • Loading…
    • +
-
-- Loading … -- Processing⋰ +
+
    +
  • 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 5 items…
    • +
  • Uploading items…
    • +
  • Processing request…
    • +
  • Saving settings…
    • +
  • Saving changes…
    • +
-
-- Uploading 1 file +
+
    +
  • 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
    • +
-
-- 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
    • +
-
-- Download → Downloading… → Downloaded +
+
    +
  • Download → Downloading… → Downloaded
    • +
Use the correct verb form without using ellipses to show background processes. -
-
-- Download → Downloading → Downloaded +
+
+
    +
  • Download → Downloading → Downloaded
    • +
-
-- 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… +
+
+
    +
  • Downloading…
    • +
-
-- Please wait. -- Thank you for waiting. -- Just a moment. +
+
    +
  • 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… +
+
+
    +
  • Carrying out tasks…
    • +
-
-- Thank you for waiting. -- Just a moment. +
+
    +
  • 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. +
+
+
    +
  • Processing your request. This usually takes about 1–2 minutes.
    • +
  • This step takes a bit longer than usual.
    • +
  • We’re preparing your dashboard. Once it’s ready, you’ll be able to customize your view.
    • +
## Dos and Don’ts -* Do use the present simple progressive (continuous, -ing) verb form -* Do use verbs before nouns to focus on the action -* Don’t apologize for how long the progress takes -* Don’t use vague phrases like: "Please wait." + +
+
+
    +
  • 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 * [Toast messages](./toast-messages.mdx) -* [Time-related messages](./time-related-messages.mdx) \ No newline at end of file +* [Time-related messages](./time-related-messages.mdx) diff --git a/docs/guidelines/language/messaging/time-related-messages.mdx b/docs/guidelines/language/messaging/time-related-messages.mdx index 0f090d7d5..8aa0f8959 100644 --- a/docs/guidelines/language/messaging/time-related-messages.mdx +++ b/docs/guidelines/language/messaging/time-related-messages.mdx @@ -14,98 +14,112 @@ description: Time-related messages help users understand how long processes take Use a specific time or time frame whenever possible. -
-
- - System update on Monday, August 22, 2025: 06:00–08:00 +
+
+
    +
  • System update on Monday, August 22, 2025: 06:00–08:00
    • +
-
- - Upcoming system update: 22 August +
+
    +
  • 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 - +
+
+
    +
  • 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). +
+
+
    +
  • 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 Tuesday, October 1, 2026: 02:00–04:00
    • +
-
- - - Update starts soon. - - Update starts later today. - - Update takes a few moments. - - Update takes a while. - +
+
    +
  • 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 will take a few minutes.
    • +
-
- - - Update may take a few minutes. - - Update might 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. +
+
+
    +
  • 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. - +
+
+
    +
  • Session expiring in 04:25 minutes.
    • +
  • Automatic logout in 03:45 minutes.
    • +
  • Meeting starts in 5 minutes.
    • +
-
- - Migration starts in 1 hour. +
+
    +
  • Migration starts in 1 hour.
    • +
Use consistent wording in 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 - +
+
+
    +
  • Data volume: 45/300 MB
    • +
  • Saving data… 50 of 300 MB saved
    • +
  • System update: 45% complete
    • +
@@ -113,26 +127,28 @@ Use consistent wording in the UI and add specific volumes with progress indicato 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. - +
+
+
    +
  • 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 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. +
+
    +
  • Due to the size of the migration, we have no idea when it will finish.
    • +
@@ -140,51 +156,61 @@ Be transparent and use passive voice when you need to be unspecific. 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. - +
+
+
    +
  • 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. - +
+
+
    +
  • 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 - +
+
+
    +
  • 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 +
+
+
    +
  • 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/messaging/toast-messages.mdx b/docs/guidelines/language/messaging/toast-messages.mdx index 236403cad..91b9f66c4 100644 --- a/docs/guidelines/language/messaging/toast-messages.mdx +++ b/docs/guidelines/language/messaging/toast-messages.mdx @@ -26,122 +26,144 @@ Although always short, toast messages vary in length and complexity: Use simple past tense verbs to state what happened. -
-
- - Assets uploaded +
+
+
    +
  • Assets uploaded
    • +
-
- - Assets have been uploaded +
+
    +
  • Assets have been uploaded
    • +
Use "not" or "failed to" with the verb to signal failure. -
-
- - - File not imported - - Failed to import file - +
+
+
    +
  • File not imported
    • +
  • Failed to import file
    • +
-
- - File type not recognized +
+
    +
  • File type not recognized
    • +
Use present progressive verbs for background or ongoing actions. -
-
- - Update application → Updating application… → Application updated +
+
+
    +
  • 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 - - Connect → Gateway connected - +
+
+
    +
  • Upload file → File uploaded
    • +
  • Connect → Gateway connected
    • +
-
- - - Upload file → File added - - Connect → Gateway established - +
+
    +
  • Upload file → File added
    • +
  • Connect → Gateway established
    • +
Avoid punctuation as this takes up extra space and adds to visual clutter. -
-
- - Scan finished +
+
+
    +
  • Scan finished
    • +
-
- - - Scan finished. - - Scan not finished! - +
+
    +
  • Scan finished.
    • +
  • Scan not finished!
    • +
Avoid adding additional words or verbs such as "you", "your", "is" or "was". -
-
- - - Maintenance scheduled - - Asset onboarded - +
+
+
    +
  • Maintenance scheduled
    • +
  • Asset onboarded
    • +
-
- - - Your maintenance was scheduled - - Onboarding for asset was successfully completed - +
+
    +
  • Your maintenance was scheduled
    • +
  • Onboarding for asset was successfully completed
    • +
Avoid generic toast messages, such as "successful", "unsuccessful", "error" and "failure". -
-
- - - Connected - - Failed to connect - +
+
+
    +
  • Connected
    • +
  • Failed to connect
    • +
-
- - - Successful - - Failed - +
+
    +
  • Successful
    • +
  • Failed
    • +
Avoid using "successful" and "successfully" as this adds to the reading load and effort. -
-
- - Connected +
+
+
    +
  • Connected
    • +
-
- - - Connection successfully established - - Connection established successfully - +
+
    +
  • Connection successfully established
    • +
  • Connection established successfully
    • +
-## Dos and Don'ts +## 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 +
+
+
    +
  • 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/messaging/tooltips.mdx b/docs/guidelines/language/messaging/tooltips.mdx index 619cfb3e4..d642bb620 100644 --- a/docs/guidelines/language/messaging/tooltips.mdx +++ b/docs/guidelines/language/messaging/tooltips.mdx @@ -14,102 +14,144 @@ import { iconEditDocument } from '@siemens/ix-icons/icons'; Use tooltips to define icons and show control names. -
-
- - - Edit - - Delete - - Log out - +
+
+
    +
  • Edit
    • +
  • Delete
    • +
  • Log out
    • +
Avoid punctuation or periods for tool names or icons. -
-
- - - Edit - - Open file - +
+
+
    +
  • Edit
    • +
  • Open file
    • +
-
- - - Edit. - - Open file. - +
+
    +
  • Edit.
    • +
  • Open file.
    • +
Use sentence case and a period if the tooltip is a complete sentence or multiple sentences. -
-
- - Add users to project. +
+
+
    +
  • Add users to project.
    • +
-
- - Add new users to project +
+
    +
  • Add new users to project
    • +
Use verbs to start your tooltip and avoid passive voice. -
-
- - Create KPI tables. +
+
+
    +
  • Create KPI tables.
    • +
-
- - Tables are created. +
+
    +
  • Tables are created.
    • +
Avoid complicated sentence constructions, e.g. no relative clauses. -
-
- - Share with team members. +
+
+
    +
  • Share with team members.
    • +
-
- - Projects can be shared with team members who work with you. +
+
    +
  • Projects can be shared with team members who work with you.
    • +
Use a heading with a short description for longer tooltips. -
-
- - Heading: Cycle time input -
- Description: Set the duration of each production cycle in seconds. -
- - Heading: Log history -
- Description: View historical logs of machine activity and operator actions. +
+
+
    +
  • +
    + Heading: Cycle time input +
    + Description: Set the duration of each production cycle in seconds. +
    +
    +
    • +
  • +
    + Heading: Log history +
    + Description: 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 icon ) +
    + Tooltip: Edit +
    • +
-
- - Edit (as text)
- Tooltip: Edit +
+
    +
  • + Edit (as text)
    + Tooltip: Edit +
    • +
-## Dos and Don'ts +## 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, instead focus on context +
+
+
    +
  • Do write tooltips to give context for complex features
    • +
  • Do write tooltips to support new users
    • +
+
+
+
    +
  • Don’t use tooltips for lengthy updates use [Toast messages](./toast-messages.mdx) instead
    • +
  • Don’t use tooltips for critical blocking feedback use [Message modal](../../../components/message-modal/index.mdx) instead
    • +
+
+
## Related - [Toast messages](./toast-messages.mdx) +- [Message modal](../../../components/message-modal/index.mdx) - [Non-critical information messages](./non-critical-information-messages.mdx) - [Messages overview](./messages-overview.md) diff --git a/docs/guidelines/language/messaging/warning-messages.mdx b/docs/guidelines/language/messaging/warning-messages.mdx index 3c3d6990e..5c3b91383 100644 --- a/docs/guidelines/language/messaging/warning-messages.mdx +++ b/docs/guidelines/language/messaging/warning-messages.mdx @@ -24,123 +24,165 @@ 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. +
+
+
    +
  • 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 approaching 30°
    • +
-
-- Temperature warning +
+
    +
  • 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 +
+
+
    +
  • 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 +
+
    +
  • 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 will be lost if not saved.
    • +
-
-- Your changes might 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: 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 +
+
+
    +
  • 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: 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. +
+
    +
  • 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? +
+
+
    +
  • 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? +
+
    +
  • Are you sure you want to delete?
    • +
Use clear, urgent wording for irreversible actions. -
-
-- Heading: 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 +
+
+
    +
  • Heading: 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. +
+
    +
  • 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!! +
+
+
    +
  • 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…?" +
+
+
    +
  • Do be consistent by re-using the verbs of the message and buttons
    • +
  • Do make sure users understand the warning’s context
    • +
  • Do give users actions to avoid any negative consequences
    • +
+
+
+
    +
  • Don’t use "please" with the call to action or options
    • +
  • Don’t use patronizing questions such as "Are you sure…?"
    • +
+
+
## Related diff --git a/docs/guidelines/language/punctuation.md b/docs/guidelines/language/punctuation.md index 58ec2a9f0..d13778b8d 100644 --- a/docs/guidelines/language/punctuation.md +++ b/docs/guidelines/language/punctuation.md @@ -85,36 +85,36 @@ 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 -- €999.50 -- €2.5 million -- $400,456.50 -- £320 -- 30 mm -- 10 oz -- 10-40% -- No.7 -- Number 7 - -
-
- -- 11 a.m. -- Monday, 12 January 2021 -- €999,50 -- €2,5 million -- $400.456,50 -- 320£ -- 30 mms -- 10 oz. -- 10–40% -- #7 -- Num 7 - +
+
+
    +
  • 11am
    • +
  • Monday, January 12, 2021
    • +
  • €999.50
    • +
  • €2.5 million
    • +
  • $400,456.50
    • +
  • £320
    • +
  • 30 mm
    • +
  • 10 oz
    • +
  • 10-40%
    • +
  • No.7
    • +
  • Number 7
    • +
+
+
+
    +
  • 11 a.m.
    • +
  • Monday, 12 January 2021
    • +
  • €999,50
    • +
  • €2,5 million
    • +
  • $400.456,50
    • +
  • 320£
    • +
  • 30 mms
    • +
  • 10 oz.
    • +
  • 10–40%
    • +
  • #7
    • +
  • Num 7
    • +
@@ -130,22 +130,22 @@ Always consider whether necessary - Add a space before unit of measurement -
-
- -- 50% -- 11am -- Tuesday: no data -- Browse… - +
+
+
    +
  • 50%
    • +
  • 11am
    • +
  • Tuesday: no data
    • +
  • Browse…
    • +
-
- -- 50 % -- 11 am -- Tuesday: no data -- Browse … - +
+
    +
  • 50 %
    • +
  • 11 am
    • +
  • Tuesday: no data
    • +
  • Browse …
    • +
@@ -161,25 +161,21 @@ 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 - - - Write comments - - Respond to comments - - Approve work orders +
+
+
    +
  • Write comments
    • +
  • Respond to comments
    • +
  • Approve work orders
    • +
-
- - #### Activate comments within your smartphone to - - - Write comments - - Respond to comments - - Approve work orders by adding your fingerprint to your user management section in your smartphone. - +
+
    +
  • Write comments
    • +
  • Respond to comments
    • +
  • Approve work orders by adding your fingerprint to your user management section in your smartphone.
    • +