docs(conversational design): updates figma images (#1459)

Co-authored-by: matthiashader <[email protected]> Co-authored-by: tokyojen <[email protected]>
siemens · Sep 9, 2024 · 1e16bce · 1e16bce
1 parent f2622bd
commit 1e16bce
Show file tree

Hide file tree

Showing 15 changed files with 76 additions and 137 deletions.
diff --git a/packages/core/component-doc.json b/packages/core/component-doc.json
@@ -734,8 +734,13 @@
           },
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "Supported layouts e.g ['sm', 'md']",
-          "docsTags": [],
+          "docs": "Supported layouts",
+          "docsTags": [
+            {
+              "name": "example",
+              "text": "['sm', 'md']"
+            }
+          ],
           "default": "['sm', 'md', 'lg']",
           "values": [
             {

diff --git a/packages/core/src/components.d.ts b/packages/core/src/components.d.ts
@@ -184,7 +184,8 @@ export namespace Components {
          */
         "applicationName": string;
         /**
-          * Supported layouts e.g ['sm', 'md']
+          * Supported layouts
+          * @example ['sm', 'md']
          */
         "breakpoints": Breakpoint[];
         /**
@@ -4234,7 +4235,8 @@ declare namespace LocalJSX {
          */
         "applicationName"?: string;
         /**
-          * Supported layouts e.g ['sm', 'md']
+          * Supported layouts
+          * @example ['sm', 'md']
          */
         "breakpoints"?: Breakpoint[];
         /**

diff --git a/packages/core/src/components/basic-navigation/basic-navigation.tsx b/packages/core/src/components/basic-navigation/basic-navigation.tsx
@@ -57,7 +57,8 @@ export class BasicNavigation {
   }
 
   /**
-   * Supported layouts e.g ['sm', 'md']
+   * Supported layouts
+   * @example ['sm', 'md']
    */
   @Prop() breakpoints: Breakpoint[] = ['sm', 'md', 'lg'];
   @Watch('breakpoints')

diff --git a/...ation/docs/conversational-design/designing-conversations/acknowledging-users.md b/...ation/docs/conversational-design/designing-conversations/acknowledging-users.md
@@ -8,19 +8,15 @@ title: Acknowledging users
 In conversations, humans like to be acknowledged to shows the other person is listening and understands the situation. When a chatbot acknowledges user input, it prompts users to continue interacting, boosts the overall user experience, and makes interactions more authentic. 
 ## Examples 
 
-**User:** Can you provide more details about our pricing plans?  
-**Chatbot:** Certainly! We have three pricing tiers: Basic, Premium, and Enterprise.
+![Acknowledging users example 1](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4329&t=etx1DcSbA7VDx5xD-4) 
 
-**User:** Is there a trial period for your software?  
-**Chatbot:** Of course! You can try our software free for 14 days.
+![Acknowledging users example 2](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4401&t=etx1DcSbA7VDx5xD-4)
 
-**User:** Can I customize the dashboard layout?  
-**Chatbot:** Absolutely! You can rearrange widgets and choose your preferred layout.
+![Acknowledging users example 3](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4404&t=etx1DcSbA7VDx5xD-4)
 
 In all these examples, the chatbot acknowledges the input and then continues with its response, building user confidence that the chatbot understood their query correctly. 
 
-**User:** Can you create a maintenance schedule in August for all ball valves within the refinery located in Hamburg?   
-**Chatbot:** Sure. Give me a moment. 
+![Acknowledging users example 4](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4407&t=etx1DcSbA7VDx5xD-4)
 
 Here, although there may be some lag time between the query and the response, the chatbot acknowledges the request and then signals they are working on the task. 
 

diff --git a/...tion/docs/conversational-design/designing-conversations/ad-hoc-conversations.md b/...tion/docs/conversational-design/designing-conversations/ad-hoc-conversations.md
@@ -9,16 +9,15 @@ Even in industrial scenarios, users test and play with chatbots. Some ad hoc int
 
 ## Examples 
 
-**Chatbot:** I apologize, I’m not able to assist you with that request. How else can I help you? 
+![Apology example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4359&t=etx1DcSbA7VDx5xD-4)
 
 Universally, chatbots start with an apology before anything else, even if it was the user that added inappropriate or offensive input. 
 
-**Chatbot:** I apologize if my previous response caused offense. I'm here to assist you with any other questions or tasks regarding your online portal. How can I assist you today? 
+![Extended apology example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4368&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot seeks to move the user back on course and reminds them of their use case. 
 
-**User:** What’s the weather today?   
-**Chatbot:** Certainly! Let’s check the weather today for you. 
+![Ad hoc question example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4370&t=etx1DcSbA7VDx5xD-4)
 
 Other ad hoc conversations, such as talking about the weather or saying hello help build a bond between user and chatbot. Although we do not recommend training your chatbot to tell jokes with users in industrial settings, a certain number of ad hoc conversations are beneficial.  
 

diff --git a/...tation/docs/conversational-design/designing-conversations/confirming-request.md b/...tation/docs/conversational-design/designing-conversations/confirming-request.md
@@ -8,23 +8,14 @@ title: Confirming requests
 Chatbots in industrial applications are sometimes required to carry out long-lasting and consequential changes to systems. Changing a system incorrectly can lead to substantial issues within a plant or a factory, such as not connecting a device properly, resetting a password without informing users, or onboarding new roles or user permissions incorrectly. To mitigate these risks, chatbots should always confirm user requests. 
 ## Examples 
 
-**Chatbot:** Do you want me to implement this?   
-**User:** Yes.  
-**Chatbot:** Shall I continue?  
-**User:** Yes.   
-**Chatbot:** Can I implement now with changes effective immediately?   
-**User:** Yes.   
-**Chatbot:** Are you sure? Changing user permissions may lead to accessibility issues.   
-**User:** Yes
+![Confirming requests negative example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4332&t=etx1DcSbA7VDx5xD-4)
 
 This interaction is frustrating and inefficient. It seems as if the chatbot does not trust the request and therefore the user. This would break trust between human and machine and result in a negative user experience. We recommend asking for confirmation only once and, if necessary, giving warnings or alerting users to possible consequences at the same time. 
 
-**User:** Change [email protected] from general user to admin.   
-**Chatbot:** Sure. Changing from general user to admin means they can edit other user roles and permissions for all factories. Shall I continue?   
-**User:** Yes  
-**Chatbot:** Ok, [email protected] is now an admin. Can I assist you with anything else? 
+![Confirming requests positive example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4396&t=etx1DcSbA7VDx5xD-4)
 
 In this interaction we see a simple request for confirmation before completing the task. The chatbot clarifies the user knows the consequences and then fulfills the task. In these types of interactions, asking for confirmation has similar advantages to acknowledging users; it further removes doubt and builds user confidence that the chatbot has correctly comprehended the query and is able to respond accurately.  
+
 ## Dos and Don’ts
 
 -	Do make all confirmations clear and transparent before processing tasks  

diff --git a/...tion/docs/conversational-design/designing-conversations/ending-conversations.md b/...tion/docs/conversational-design/designing-conversations/ending-conversations.md
@@ -9,16 +9,15 @@ title: Ending conversations
 As with any human to human interaction, there’s always an ending to give participants closure and end on a positive note. This is the same for every chatbot interaction, including industrial chatbots. Although it seems an easy communicative function, ending interactions well can achieve multiple goals that help users, chatbot teams and chatbots. It’s an opportunity to get useful feedback to train your chatbot, create a clear signal that the interaction is complete, and set the tone for the next interaction interactions. 
 ## Examples
 
-**Chatbot:** I’ll be here if you need anything else.
+![Ending conversations: Short example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4361&t=etx1DcSbA7VDx5xD-4)
 
 This is a simple, effective end showing the supportive nature of the chatbot. 
 
-**User:** Thanks for that. Much appreciated.   
-**Chatbot:** Glad that helped. I’ll be here if you need anything else. 
+![Ending conversations: Longer example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4365&t=etx1DcSbA7VDx5xD-4)
 
 This is a more empathetic ending, highlighting the successful support given and the support it will continue to provide the user. 
 
-**Chatbot:** Sorry if my previous response didn’t meet your expectations. As an AI language model, I’m continuously improving to provide better responses. If there’s anything else you’d like help with, feel free to ask.
+![Ending conversations: Example with apology](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4363&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot offers an apology for not being able to support the user, explains why, and then closes with a more positive note to try to compensate for its failure. While this is a negative end to the interaction, providing a clear reason for its limitations and then offering to make amends with the next query, helps soften the disappointment. 
 

diff --git a/...mentation/docs/conversational-design/designing-conversations/funneling-input.md b/...mentation/docs/conversational-design/designing-conversations/funneling-input.md
@@ -7,27 +7,21 @@ title: Funneling input
 Sometimes users need to be guided to give more information to get the most accurate and appropriate response. This involves funneling user input by giving them options and asking questions. However, asking too many questions to get to the user’s real intent can be time-consuming and frustrating. After a few attempts, chatbots should be trained to either admit defeat gracefully or hand them off to someone that can help. 
 ## Examples 
 
-**User:** I’m having some problems with this asset.   
-**Chatbot:** Could you please provide more details about your problem?
+![Funneling example for context 1](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4341&t=etx1DcSbA7VDx5xD-4)
 
-**User:** I need to check a product license.  
-**Chatbot:** What product license are you looking for?
+![Funneling example for context 2](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4381&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot asks simple questions related to the user's query to gain some context to better help them. 
 
-**User:** The tank is not responding.   
-**Chatbot:** Just to confirm, are you referring to a software or a hardware issue?
-
-**User:** The tank is not responding.  
-**Chatbot:** Did you mean Tank 2 currently in batch mode when you mentioned 'Tank'?
+![Funneling example for clarification 1](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4384&t=etx1DcSbA7VDx5xD-4)
+
+![Funneling example for clarification 2](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4387&t=etx1DcSbA7VDx5xD-4)
 
 The chatbot needed to verify the user queries in both these examples and sought clarification before trying to give them an appropriate response.  
 
-**User:** The portal is not updating to the new version.  
-**Chatbot:** Would you like to see the update manual or get troubleshooting assistance?
+![Funneling example with choices 1](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4390&t=etx1DcSbA7VDx5xD-4)
 
-**User:** I want to do some engineering.   
-**Chatbot:** Please choose one of the following categories: PLC engineering or HMI engineering.
+![Funneling example with choices 2](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4393&t=etx1DcSbA7VDx5xD-4)
 
 Presenting options or choices for the user to select from also helps to funnel queries and show users what the chatbot can do for them. We recommend limiting the options to two or three to not overload the user. 
 

diff --git a/...umentation/docs/conversational-design/designing-conversations/greeting-users.md b/...umentation/docs/conversational-design/designing-conversations/greeting-users.md
@@ -8,21 +8,22 @@ title: Greeting users
 Greeting users is a key communicative function as this introduces your chatbot to your users, establishes its voice, and can be used to clarify your chatbot’s abilities and constraints. 
 ## Examples
 
-**Chatbot:** Hello, I’m your Industrial Chatbot. How can I assist you today? 
+![Greeting users with a simple introduction](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4327&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot uses “Hello” instead of “Hi” or another greeting to establish a more professional tone. It also uses contractions (I’m instead of I am) to show that, although it’s a professional industrial chatbot, they’re not overly formal. The greeting then ends with a clear and common prompt for the user. 
 
-**Chatbot:** Hello, I’m your Industrial Chatbot and can support you with PLC engineering. How can I assist you today?
+![Greeting users with an extended introduction](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4410&t=etx1DcSbA7VDx5xD-4) 
 
-In this example, the greeting adds some information about its use case to set user expectations and limit their queries. 
+In this example, the greeting adds some information about its use case to set user expectations and limit their queries.
 
-**Chatbot:** Hello, I’m your Industrial Chatbot and can support PLC engineering. If you need support with programming, hardware or troubleshooting, feel free to ask. 
+![Greeting users with extended use case introduction](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4412&t=etx1DcSbA7VDx5xD-4) 
 
 This example goes even further to establish what it can do and how it can help. It isn’t too lengthy, it’s not a monologue or a list of points that would overwhelm users and perfectly narrows down its abilities. 
 
-**Chatbot:** Hi! I’m your Industrial Chatbot. What do you need? 
+![Greeting users with an informal introduction](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4414&t=etx1DcSbA7VDx5xD-4)
 
 This chatbot is less formal, more conversational and would be found within more generic chatbots. We do not recommend this style of greeting for our industrial applications that are embedded in working environments that are often demanding and dangerous. 
+
 ## Dos and Don’ts
 
 - Do keep your greeting short and simple  

diff --git a/...ntation/docs/conversational-design/designing-conversations/handing-off-users.md b/...ntation/docs/conversational-design/designing-conversations/handing-off-users.md
@@ -9,14 +9,7 @@ Chatbots must hand off their users whenever they’ve failed to clarify what the
 
 ## Examples
 
-**User:** We’re getting numerous temperature threshold alarms after our software update.  
-**Chatbot:** Just to confirm, have you acknowledged the alarms?   
-**User:** Yes but they are being raised again as soon as I acknowledge them. This happened straight after the software update.   
-**Chatbot:** Which software update did you complete?  
-**User:** v7.03  
-**Chatbot:** I apologize, but I’m not able to solve this for you. Would you like me to transfer you to the Remote Expert Center?   
-**User:** Yes.   
-**Chatbot:** Thank you. Please wait a moment as I hand you over to a REC agent. 
+![Handing off to human assistance example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4347&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot is polite, professional and after a couple of clarifying questions, they admit to being unable to help and hand them off the best person to support them with their issue. They also make it clear they are being handed off to a human. 
 

diff --git a/...mentation/docs/conversational-design/designing-conversations/handling-errors.md b/...mentation/docs/conversational-design/designing-conversations/handling-errors.md
@@ -9,15 +9,11 @@ When talking about chatbots and the mistakes they make, it’s always talked abo
 
 ## Examples 
 
-**User:** Can you automate my night shift task assignments?  
-**Chatbot:** I apologize. Unfortunately, I cannot complete that task. 
+![Handling errors example apology](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4344&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot is immediately apologetic and tells the user they cannot complete the task. It’s efficient but lacks empathy and fails to give the user any kind of alternative support. 
 
-**User:** Hi, I need to order replacement parts for our assembly line.   
-**Chatbot:** Sure, I’m happy to assist you! Could you please provide the part numbers?   
-**User:** I don’t have them, but they’re for the filtering machine.   
-**Chatbot:** I’m sorry, but I can’t look up parts without specific part numbers. Please check our online purchasing portal or contact our customer service for personalized assistance. 
+![Handling errors example apology and explanation](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4376&t=etx1DcSbA7VDx5xD-4)
 
 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

diff --git a/...mentation/docs/conversational-design/designing-conversations/troubleshooting.md b/...mentation/docs/conversational-design/designing-conversations/troubleshooting.md
@@ -10,13 +10,11 @@ For many industrial applications, chatbots are these to support users with their
 
 ## Examples
 
-**User:** Why is there a remote connection issue?   
-**Chatbot:** The connection is not available right now. 
+![Unhelpful troubleshooting example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4356&t=etx1DcSbA7VDx5xD-4)
 
 Here the chatbot says exactly what the problem is, but this response lacks empathy and is unhelpful in moving the user forward. 
 
-**User:** Why is there a remote connection issue?   
-**Chatbot:** The connection is not available right now. It’s possible the server is offline. Try to reconnect again now and if it does not connect, try again in 15 minutes. 
+![Helpful troubleshooting example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3218-4373&t=etx1DcSbA7VDx5xD-4) 
 
 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.