@adobe/spectrum-design-data 3.3.0-beta.1 → 3.3.0-beta.2

package/guidelines/writing-for-errors.json

@@ -12,55 +12,55 @@
     },
     {
       "type": "guideline",
-      "content": "Avoid showing a message whenever possible.\n\nThe best error message is no error happening at all. The message — and the error itself — are disruptive to a user’s experience and can stand in the way of them accomplishing their task. Make sure that the system can anticipate and address errors on the back end before showing an error message on the front end. Find ways to avoid the error altogether, like by using in-line validation, visual cues, and disabled states to guide users. Ensure your design is as inclusive as possible by anticipating and accommodating multiple spellings of words in search queries and results. Use the disabled states of components to communicate that next steps are unavailable unless a user takes an action first.Don't create unnecessary error messages as a workaround to unintuitive design."
+      "content": "Avoid showing a message whenever possible.\n\nThe best error message is no error happening at all. The message — and the error itself — are disruptive to a user’s experience and can stand in the way of them accomplishing their task. Make sure that the system can anticipate and address errors on the back end before showing an error message on the front end. Find ways to avoid the error altogether, like by using in-line validation, visual cues, and disabled states to guide users. Ensure your design is as inclusive as possible by anticipating and accommodating multiple spellings of words in search queries and results. Image: Key example of a correct way to avoid showing an error message in an interaction. A text area component, label Description (required), with two buttons in the disabled state, labels Cancel, Submit. (source: https://preview.spectrum.adobe.com/content/media_1e61427ab0002f3e80d26c2e0ac11419704fbec57.png?width=750&format=png&optimize=medium)Use the disabled states of components to communicate that next steps are unavailable unless a user takes an action first.Image: Key example of an unsatisfactory error message design. A text area component, label Description (required), has two buttons in the active state, labels Cancel and Submit. An animation shows a cursor hovering over the text area, not entering any text, and clicking the Submit button. After clicking, a red error icon and a red in-line error message appear, with the message saying Enter your description. (source: https://preview.spectrum.adobe.com/content/media_10ac9c52026aab5dbb320e4e2b9c020ce5bc85123.png?width=750&format=png&optimize=medium)Don't create unnecessary error messages as a workaround to unintuitive design."
     },
     {
       "type": "guideline",
-      "content": "Have the system automatically resolve errors.\n\nError messaging should be a last resort. Try whenever possible to design experiences in a way that the UI doesn’t rely on showing error messages or prompting direct user action to resolve an error. For example, if a user were to input “101” when a field can only accept numbers up to 100 (such as showing percentages), automatically revert the entered value to 100."
+      "content": "Have the system automatically resolve errors.\n\nError messaging should be a last resort. Try whenever possible to design experiences in a way that the UI doesn’t rely on showing error messages or prompting direct user action to resolve an error. For example, if a user were to input “101” when a field can only accept numbers up to 100 (such as showing percentages), automatically revert the entered value to 100. Image: Key example of a design that automatically resolves an error. A user inputs a value of 101 percent into a text field, label Opacity. After the user input, the system automatically changes the value to 100 percent. (source: https://preview.spectrum.adobe.com/content/media_15793c69928d79c629cd0b1aaba24496b0446d332.png?width=750&format=png&optimize=medium)Image: Key example of a design that does not resolve errors on the back end and shows an unnecessary error message. A user inputs a value of 101 percent into a text field, label Opacity. After the user input, the system shows a field error icon and an error message saying Enter a valid percentage. (source: https://preview.spectrum.adobe.com/content/media_1682f75850766460bc478fa21e0520022ec72c8f0.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Choose the message first, then the component.\n\nError messages appear in the wrong UI components all too often. A complex message is usually too long and too complicated for a toast, and a short and straightforward message is far too much for an alert dialog. Errors that are lower in signal or consequence shouldn’t warrant a dialog that blocks the entire experience, and errors that are high priority shouldn’t appear in a toast with a timeout of only a few seconds. Write out what the message should say, free of any UI constraints, to understand how you should say it. Then, determine the right component for the message. Learn which component to use, when."
+      "content": "Choose the message first, then the component.\n\nError messages appear in the wrong UI components all too often. A complex message is usually too long and too complicated for a toast, and a short and straightforward message is far too much for an alert dialog. Errors that are lower in signal or consequence shouldn’t warrant a dialog that blocks the entire experience, and errors that are high priority shouldn’t appear in a toast with a timeout of only a few seconds. Write out what the message should say, free of any UI constraints, to understand how you should say it. Then, determine the right component for the message. Learn which component to use, when. Image: Key example of a correct way to choose a proper design component for an error message. An error alert dialog includes an error icon, and contains a high-signal, complex error message. Dialog title, Unable to share. Dialog description, An error occurred while sharing your project. Please verify the email address and try again. One button, label OK. (source: https://preview.spectrum.adobe.com/content/media_14db46b6962d8ca4b7347739733670c7c2eaf446d.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect way to pair a design component with an error message. An error toast includes a message that is too long and high-signal for the component. Toast text, Unable to share. An error occurred while sharing your project. Please verify the email address and try again. (source: https://preview.spectrum.adobe.com/content/media_122449620310426211b0e58d83482205950e4dfda.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "What happened.\n\nThis should be the first part of the message, like in a headline (if the UI element allows). Be sure to communicate the general outcome of the error. Use plain language and focus on what it means to the user."
+      "content": "What happened.\n\nThis should be the first part of the message, like in a headline (if the UI element allows). Be sure to communicate the general outcome of the error. Use plain language and focus on what it means to the user. Image: Key example of a correct usage. Your files didn’t sync. (source: https://preview.spectrum.adobe.com/content/media_13c953812a0b3a9aa2ebd267bc3109a9951099c76.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. FORBIDDEN This operation has failed to execute. (source: https://preview.spectrum.adobe.com/content/media_171e1d7bb948c9d90dfdd3f6d9ea2aed7ef59bf53.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "The underlying cause.\n\nIt’s helpful to have an explanation of why something happened, if there’s space to include it. Explaining the cause is optional depending on the context; sometimes this can increase a user’s understanding, but sometimes it gets in the way of useful, usable information."
+      "content": "The underlying cause.\n\nIt’s helpful to have an explanation of why something happened, if there’s space to include it. Explaining the cause is optional depending on the context; sometimes this can increase a user’s understanding, but sometimes it gets in the way of useful, usable information. Image: Key example of a correct usage. We're unable to install or update {appName} due to insufficient disk space. (Error code: 189) The installer can't download {appName} because Adobe’s servers aren’t reachable. Check the Adobe status page for an outage and retry the installation later. (Error code: 206) (source: https://preview.spectrum.adobe.com/content/media_1346bfb9352b0bb235d3c474510c36be658c35916.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. We're unable to install or update {appName}. The installer cannot download {appName} because Adobe’s servers aren’t reachable. This may be due to user error, employee error, or something else. Check the Adobe status page for an outage and retry the installation later. (Error code: 206) (source: https://preview.spectrum.adobe.com/content/media_1d8de2015fd403a20b7b6262389e8bac99b420bed.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "How to fix it.\n\nThis part tells the user what they can do about it. If there’s nothing for them to do, then explain what the product is doing. This should be as simple and actionable as possible. Offer a path forward within the error state itself, such as a “Try again” or “Go back” button, or a step-by-step resolution in the error message text. Linking to a help article can be useful, but only if that article is specific and descriptive to the error’s use case. Try to avoid generic, catch-all resolutions like “Contact your IT administrator for details.”"
+      "content": "How to fix it.\n\nThis part tells the user what they can do about it. If there’s nothing for them to do, then explain what the product is doing. This should be as simple and actionable as possible. Offer a path forward within the error state itself, such as a “Try again” or “Go back” button, or a step-by-step resolution in the error message text. Linking to a help article can be useful, but only if that article is specific and descriptive to the error’s use case. Try to avoid generic, catch-all resolutions like “Contact your IT administrator for details.” Image: Unlabeled image (source: https://preview.spectrum.adobe.com/content/media_14dff668c4712cec2e9dd021c4c0d16c27db0f8e5.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Upload your files one more time. (source: https://preview.spectrum.adobe.com/content/media_19b86aa2ae85d836e29ad4a172b58540ade1112a2.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Center the language around user goals, not system constraints.\n\nSometimes it seems like the best way to resolve an error is to explain the constraints of the system to the user. But, most users don’t care about the constraints of the system — they care about accomplishing their goals. Center the language around what the user is trying to accomplish, why that didn’t happen, and how they might resolve the error."
+      "content": "Center the language around user goals, not system constraints.\n\nSometimes it seems like the best way to resolve an error is to explain the constraints of the system to the user. But, most users don’t care about the constraints of the system — they care about accomplishing their goals. Center the language around what the user is trying to accomplish, why that didn’t happen, and how they might resolve the error. Image: Key example of a correct usage. Accept the End User License Agreement terms. (source: https://preview.spectrum.adobe.com/content/media_1194c219d34db23b7e826eeb5375dd15003f17dcd.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. There was a RAISE without a handler. (source: https://preview.spectrum.adobe.com/content/media_18bba303711ef7520bb47f2d61b5bec940ab75dfe.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Use plain language, and avoid jargon.\n\nUsers may not understand server architecture or client-side queries. Know your audience, and write your error messages in plain, usable language so that your user will understand what went wrong and how it’s being resolved. Technical terms are different than jargon. If you’re confident that your audience would be readily familiar with technical terms, and if such terms are relevant to the message, you can include them."
+      "content": "Use plain language, and avoid jargon.\n\nUsers may not understand server architecture or client-side queries. Know your audience, and write your error messages in plain, usable language so that your user will understand what went wrong and how it’s being resolved. Technical terms are different than jargon. If you’re confident that your audience would be readily familiar with technical terms, and if such terms are relevant to the message, you can include them. Image: Key example of a correct usage. Due to a connection error, some results may be unavailable. (source: https://preview.spectrum.adobe.com/content/media_12f51c5567eb92cbc3d65298e8f70db7b10f55e46.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Due to a server-side connectivity failure, some results may be unavailable. (source: https://preview.spectrum.adobe.com/content/media_12e5135ff0e69e83869e5cb69fb18f6914f130c9c.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Don’t blame the user, even if the error is their fault.\n\nSome errors are outside of a user’s control, but they can happen because of a direct user action. While you want to tell a user what happened, don’t sound accusatory or that you’re blaming them — we want them to feel supported and taken care of in any experience."
+      "content": "Don’t blame the user, even if the error is their fault.\n\nSome errors are outside of a user’s control, but they can happen because of a direct user action. While you want to tell a user what happened, don’t sound accusatory or that you’re blaming them — we want them to feel supported and taken care of in any experience. Image: Key example of a correct usage. Your computer appears to be offline. Connect to the internet and try again. (Error code: 206) (source: https://preview.spectrum.adobe.com/content/media_185cc2d41591a04e2e820643856ff6bccc8c33436.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. You went offline. Connect to the internet and try again. (Error code: 206) (source: https://preview.spectrum.adobe.com/content/media_18689b28dae936d0ddabfd37235a3e6efb168403f.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Include error codes only if useful and relevant.\n\nAgain, think about your audience. Include an error code or other technical information if your users would benefit from having it in order to resolve the error. Put error codes at the end of the message so that readers aren’t potentially overwhelmed with information they may not understand at the start. This error message shows the error code as a reference for contacting tech support."
+      "content": "Include error codes only if useful and relevant.\n\nAgain, think about your audience. Include an error code or other technical information if your users would benefit from having it in order to resolve the error. Put error codes at the end of the message so that readers aren’t potentially overwhelmed with information they may not understand at the start. Image: Key example of a correct usage. This profile is currently unavailable. Try reloading the page. (Error code: 10213) (source: https://preview.spectrum.adobe.com/content/media_1efeb1dd17dc343aefc7c5b3ed41bd84aa5d095af.png?width=750&format=png&optimize=medium)This error message shows the error code as a reference for contacting tech support."
     },
     {
       "type": "guideline",
-      "content": "Use positive framing to keep the focus on what users can do.\n\nWhile a user will want to know what went wrong, be as clear as possible about what they can do to fix the error, or provide them with an alternative workaround. Sometimes it’s simple (“try again in a few minutes”) and sometimes the only solution can be time-intensive or potentially frustrating (“contact your IT administrator”). Avoid putting the focus on the problem, what a user can’t do, or what they did incorrectly. Instead, offer context and help people understand what they can do."
+      "content": "Use positive framing to keep the focus on what users can do.\n\nWhile a user will want to know what went wrong, be as clear as possible about what they can do to fix the error, or provide them with an alternative workaround. Sometimes it’s simple (“try again in a few minutes”) and sometimes the only solution can be time-intensive or potentially frustrating (“contact your IT administrator”). Avoid putting the focus on the problem, what a user can’t do, or what they did incorrectly. Instead, offer context and help people understand what they can do. Image: Key example of a correct usage. Enter your system administrator password to continue. Check for an OS prompt and follow the instructions. The installer shut down unexpectedly. Please select Retry to restart the process. (Error code: 305) (source: https://preview.spectrum.adobe.com/content/media_114c76fb236ba270f4e05cd2fe5206add7a0ac0e4.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Enter your system administrator password to continue. The installer shut down unexpectedly. (source: https://preview.spectrum.adobe.com/content/media_10ef359db76235b008fbf15e40252c09ecbf07669.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Create error states that are specific to each case whenever possible.\n\nIt may be tempting to write a catch-all error message to accommodate dozens of similar scenarios, but that will tend to be wordier and less concise. When users need to understand multiple causes of the error — and also figure out which one applies in their scenario — that creates a lot of unnecessary cognitive load in an experience. Creating multiple, more specific error messages takes additional effort, but it ultimately creates a better user experience. Having these can also provide clearer insights and analytics that can help identify and resolve common pain points — and show you how to prevent errors from happening in your product in the first place."
+      "content": "Create error states that are specific to each case whenever possible.\n\nIt may be tempting to write a catch-all error message to accommodate dozens of similar scenarios, but that will tend to be wordier and less concise. When users need to understand multiple causes of the error — and also figure out which one applies in their scenario — that creates a lot of unnecessary cognitive load in an experience. Creating multiple, more specific error messages takes additional effort, but it ultimately creates a better user experience. Having these can also provide clearer insights and analytics that can help identify and resolve common pain points — and show you how to prevent errors from happening in your product in the first place. Image: Key example of a correct usage. Your wifi connection is unstable and affecting download speed. Try switching to an ethernet cable. (source: https://preview.spectrum.adobe.com/content/media_1b322376f77d730247cca8ee098da38582abaa14c.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. There’s an issue wrong with your internet connection. It could be your wifi, router, modem, or ethernet cable. (source: https://preview.spectrum.adobe.com/content/media_1d5417ca0dc7ba9a4c4e19a099d1d5c460a27649e.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "While the error should be specific, use generic language.\n\nGeneric language allows for better localization, and it also reduces the need to write many different versions of messages for similar use cases. It’s usually unnecessary to include specific filenames, usernames, or folders because a user can get that context from elsewhere in the UI."
+      "content": "While the error should be specific, use generic language.\n\nGeneric language allows for better localization, and it also reduces the need to write many different versions of messages for similar use cases. It’s usually unnecessary to include specific filenames, usernames, or folders because a user can get that context from elsewhere in the UI. Image: Key example of a correct usage. Your document could not be saved. Please try again. (source: https://preview.spectrum.adobe.com/content/media_13b3558b2aff04582028409bcf767930ec0709d4d.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Your document “Final-proposal-May-Monthly-Meeting.indd” could not be saved to the library “May Proposals” (source: https://preview.spectrum.adobe.com/content/media_14f412d6e89149021159b01597be0bf50a8509485.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
@@ -72,38 +72,38 @@
     },
     {
       "type": "guideline",
-      "content": "Don’t apologize unless it’s warranted.\n\nApologizing for minor mistakes or when the system is not at fault sounds insincere, and it gets in the way of the important parts of a message. Save “sorry” for serious errors: when there’s data loss or something requires a user to take a major action to resolve the issue."
+      "content": "Don’t apologize unless it’s warranted.\n\nApologizing for minor mistakes or when the system is not at fault sounds insincere, and it gets in the way of the important parts of a message. Save “sorry” for serious errors: when there’s data loss or something requires a user to take a major action to resolve the issue. Image: Key example of a correct usage. We couldn’t post your comment. Try again (source: https://preview.spectrum.adobe.com/content/media_1319eac32780e566dc22113dd76637417489ca5f8.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Oops! So sorry, but we couldn’t post your comment. Try again (source: https://preview.spectrum.adobe.com/content/media_193c73440a77193769e109549cfe9841f62d7cdae.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Use passive voice sparingly.\n\nTry to write in active voice, which is quicker and easier to parse. Passive voice is useful to soften a message that might otherwise come across as blunt or terse, especially when the error was caused through user action or inaction."
+      "content": "Use passive voice sparingly.\n\nTry to write in active voice, which is quicker and easier to parse. Passive voice is useful to soften a message that might otherwise come across as blunt or terse, especially when the error was caused through user action or inaction. Image: Key example of a correct usage. We couldn’t save your changes. Please try again. Your credit card could not be charged. Please add an active card to continue your subscription. (source: https://preview.spectrum.adobe.com/content/media_14cb517f2d37c5e0ae241d7c3789f0c02817a1730.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Your changes could not be saved. Please try again. You didn’t add a new card after your current card expired, so if you want to continue your subscription, add it now. (source: https://preview.spectrum.adobe.com/content/media_1fa2c3cdb04cb5051867e25a51720583a774b1cb0.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Own mistakes, and help users parse complicated actions with “we” and “you”.\n\nWe typically avoid referring to ourselves — meaning “we,” the interface — in UI copy because it adds unnecessary cognitive load. But, directly referring to the interface as \"we\" and to the user as \"you\" in an error message can be a clear and helpful way to answer the questions \"where did this go wrong?\" and \"who needs to take action to fix it?"
+      "content": "Own mistakes, and help users parse complicated actions with “we” and “you”.\n\nWe typically avoid referring to ourselves — meaning “we,” the interface — in UI copy because it adds unnecessary cognitive load. But, directly referring to the interface as \"we\" and to the user as \"you\" in an error message can be a clear and helpful way to answer the questions \"where did this go wrong?\" and \"who needs to take action to fix it?\" Image: Key example of a correct usage. Something went wrong and we couldn’t generate your report. Please try again in a few minutes. (source: https://preview.spectrum.adobe.com/content/media_1e764f83c532512ea7bf6a5ecfebed18f012af61f.png?width=750&format=png&optimize=medium)Image: Key example of an incorrect usage. Experience Cloud encountered an error and this report couldn’t be generated. The user can try again in a few minutes. (source: https://preview.spectrum.adobe.com/content/media_19094c5873c7fb7bc0c4bb1454ee7bcb34e254234.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Alert dialog.\n\nConsequence: High Complication: High Action: High Alert dialogs appear over the interface to show important information that a user needs to acknowledge or make a decision about before moving forward. This is a common error message component for letting someone know about a change or action they took or need to take, but it’s often more disruptive than it needs to be. Use alert dialogs consciously; even if the message is important, they are still highly interruptive to an experience. Alert dialogs are associated with task-level (rather than system-level) errors. Use these for consequential, complicated, timely, actionable errors that block a user from moving forward. Some examples of scenarios where an alert dialog may be appropriate are: A message telling the user that a file can’t be shared because of an invalid email address A user can’t sign on because their account has been compromised A CSV with a list of email addresses for a bulk upload couldn’t be processed because it was formatted incorrectly"
+      "content": "Alert dialog.\n\nConsequence: High Complication: High Action: High Alert dialogs appear over the interface to show important information that a user needs to acknowledge or make a decision about before moving forward. This is a common error message component for letting someone know about a change or action they took or need to take, but it’s often more disruptive than it needs to be. Use alert dialogs consciously; even if the message is important, they are still highly interruptive to an experience. Alert dialogs are associated with task-level (rather than system-level) errors. Use these for consequential, complicated, timely, actionable errors that block a user from moving forward. Some examples of scenarios where an alert dialog may be appropriate are: A message telling the user that a file can’t be shared because of an invalid email address A user can’t sign on because their account has been compromised A CSV with a list of email addresses for a bulk upload couldn’t be processed because it was formatted incorrectly Image: Key example of a red, negative semantic variant alert banner, showing a suitable error message. Text, connection interrupted. (source: https://preview.spectrum.adobe.com/content/media_1c158cc8845c98f858dead28f9e7c7b93dece71e8.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Alert banner.\n\nConsequence: Low Complication: Low Action: High Alert banners show system-level, pressing, and high-signal messages. They’re meant to be noticed and prompt users to take an action. The red (negative) and grey (neutral) semantic variants are both associated with error messages. Use an alert banner for a message that isn’t directly related to an action that a user would have just taken, but is still high-signal and needs attention. It's also ideal for communicating connectivity errors."
+      "content": "Alert banner.\n\nConsequence: Low Complication: Low Action: High Alert banners show system-level, pressing, and high-signal messages. They’re meant to be noticed and prompt users to take an action. The red (negative) and grey (neutral) semantic variants are both associated with error messages. Use an alert banner for a message that isn’t directly related to an action that a user would have just taken, but is still high-signal and needs attention. It's also ideal for communicating connectivity errors. Image: Two key examples of using help text for error messaging with in-line validation. First example, a required text field in an error state, bordered in red and including a red error icon. Text field label, Credit card number. Error message in red text, Enter your credit card number. Second example, a required text field in an error state, bordered in red and including a red error icon. Text field label, Password. Error message in red text, Create a password with at least 8 characters. (source: https://preview.spectrum.adobe.com/content/media_12da76201fe9cdd163460fb5a91930a95a92f894d.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Help text.\n\nConsequence: Low Complication: Low Action: High Help text provides an in-line error message that’s associated with an input, giving more context and guidance to help a user successfully complete an interaction. These kinds of error messages communicate what to input or select, or sometimes how to do it. The message can include information such as hints for what kind of information needs to be input or selected to move forward in a flow, or share specific formatting examples or requirements. Multiple instances of help text showing in-line validation errors can be aggregated into an in-line alert. View the guidelines for writing error messages using help text."
+      "content": "Help text.\n\nConsequence: Low Complication: Low Action: High Help text provides an in-line error message that’s associated with an input, giving more context and guidance to help a user successfully complete an interaction. These kinds of error messages communicate what to input or select, or sometimes how to do it. The message can include information such as hints for what kind of information needs to be input or selected to move forward in a flow, or share specific formatting examples or requirements. Multiple instances of help text showing in-line validation errors can be aggregated into an in-line alert. View the guidelines for writing error messages using help text. Image: Key example of a red, negative semantic variant in-line alert showing a suitable error message. Title, Unable to process payment. Description, There was an error processing your payment. Please check that your credit card information is correct, then try again. (source: https://preview.spectrum.adobe.com/content/media_12788d4422ab1d9b36456574abf80117bd54c208f.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "In-line alert.\n\nConsequence: Any Complication: High Action: High In-line alerts display a non-modal message associated with objects in a view. These are often used in form validation, providing a place to aggregate feedback related to multiple fields into a single message for higher visibility. The red (negative) and orange (notice) semantic variants are for use with error messages. Use in-line alerts to combine multiple input errors into a single error message, or for cases when a dialog would be too interruptive to an experience but an error message still needs to be shown in order for a user to proceed with a task."
+      "content": "In-line alert.\n\nConsequence: Any Complication: High Action: High In-line alerts display a non-modal message associated with objects in a view. These are often used in form validation, providing a place to aggregate feedback related to multiple fields into a single message for higher visibility. The red (negative) and orange (notice) semantic variants are for use with error messages. Use in-line alerts to combine multiple input errors into a single error message, or for cases when a dialog would be too interruptive to an experience but an error message still needs to be shown in order for a user to proceed with a task. Image: Key example of a red, negative semantic variant toast, showing a suitable error message. Text, Unable to delete file. (source: https://preview.spectrum.adobe.com/content/media_12a8a23095f1c806cf0a461becbc1a211ad6cd451.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
       "content": "Toast.\n\nConsequence: Low Complication: Low Action: Low Toasts display brief, temporary notifications. They’re noticeable but don’t disrupt the user experience, and they don’t require an action to be taken in response to the message. The red (negative) semantic variant is associated with an error message. Use toasts to communicate error messages that are contextual or triggered by a user action (e.g., moving an item, taking an action on something in a canvas). Whenever possible, include an in-line action on a toast with an error message so that a user can readily address it."
     }
   ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/writing-for-errors",
+  "sourceUrl": "https://preview.spectrum.adobe.com/content/writing-for-errors",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [

package/guidelines/writing-for-onboarding.json

@@ -40,70 +40,70 @@
     },
     {
       "type": "guideline",
-      "content": "Use lightweight language for learning.\n\nPeople are unlikely to engage with educational topics if they sound stuffy or unappealing. Adobe research has shown that people tend to think of educational content as either only geared toward beginners and/or too “heavy,” requiring a lot of brainpower and investment. Writing in a lightweight way to talk about the activity of learning can help bridge these two and create a more inclusive experience for different levels of expertise with a product. Words and phrases like the following are too heavy: learning, course, class, training, lesson, teaching, instruction, education, homework, exercise Words and phrases like these still accurately portray the content and its intent, but are lighter in tone: tutorial, try it out, explore, practice, do {something}, guided, guidance, session, video, developing skills, going deeper, show how, walk through, grow/develop skills Frame educational content in a lightweight way using language like “try” and “shows you how.”Avoid using heavy words such as “course.”"
+      "content": "Use lightweight language for learning.\n\nPeople are unlikely to engage with educational topics if they sound stuffy or unappealing. Adobe research has shown that people tend to think of educational content as either only geared toward beginners and/or too “heavy,” requiring a lot of brainpower and investment. Writing in a lightweight way to talk about the activity of learning can help bridge these two and create a more inclusive experience for different levels of expertise with a product. Words and phrases like the following are too heavy: learning, course, class, training, lesson, teaching, instruction, education, homework, exercise Words and phrases like these still accurately portray the content and its intent, but are lighter in tone: tutorial, try it out, explore, practice, do {something}, guided, guidance, session, video, developing skills, going deeper, show how, walk through, grow/develop skills Image: Key example of how to use lightweight language for learning. Title, Try editing your clips. Description, This session shows you how to start editing videos. Button with label, Take in-app tutorial. (source: https://preview.spectrum.adobe.com/content/media_14e452fcbbbd3563b9644c922d19cb2bcbdfcfab1.png?width=750&format=png&optimize=medium)Frame educational content in a lightweight way using language like “try” and “shows you how.”Image: Key example showing how heavy or complex language is not helpful for learning. Title, Learn After Effects with our free course. Description, Take After Effects step by step in our series of short videos. Button with label, Open in browser. (source: https://preview.spectrum.adobe.com/content/media_19c2b3db3fa228d6a97b5c68d1d627e2ff9beeea3.png?width=750&format=png&optimize=medium)Avoid using heavy words such as “course.”"
     },
     {
       "type": "guideline",
-      "content": "Use jargon with caution.\n\n“Jargon” is words or expressions that specific technical or professional groups use that would be difficult for others to understand. When introducing new words and expressions, it’s important to do so in an inclusive way that makes people feel empowered, not lost. Jargon can be used in a product, but it must be taught judiciously and carefully. Avoid jargon that doesn’t pertain to a product or its industry Jargon is acceptable so long as it’s relevant. For example, a brand-new Photoshop user would likely want to learn jargon common in the photography industry in addition to the names of tools and parts of the app. Don't assume that they already know these things. Avoid buzzwords that a common reader wouldn’t understand, and don’t create new jargon. Use one piece of jargon per sentence It’s sometimes necessary to use jargon to communicate a technical detail. A good way to use technical terms while avoiding a heavy tone is to only use one of those terms per sentence. Explain, then name When you do need to use jargon — for example, “crop tool” (the name of a tool in Photoshop), “aperture” (a photography term), or “Learn” (the name for Adobe’s collection of educational videos and in-app tutorials) — define upon first reference, then give the name. Define jargon like “Learn,” then explain what it’s called.Don’t speak abstractly about jargon, especially without explaining why it’s important."
+      "content": "Use jargon with caution.\n\n“Jargon” is words or expressions that specific technical or professional groups use that would be difficult for others to understand. When introducing new words and expressions, it’s important to do so in an inclusive way that makes people feel empowered, not lost. Jargon can be used in a product, but it must be taught judiciously and carefully. Avoid jargon that doesn’t pertain to a product or its industry Jargon is acceptable so long as it’s relevant. For example, a brand-new Photoshop user would likely want to learn jargon common in the photography industry in addition to the names of tools and parts of the app. Don't assume that they already know these things. Avoid buzzwords that a common reader wouldn’t understand, and don’t create new jargon. Use one piece of jargon per sentence It’s sometimes necessary to use jargon to communicate a technical detail. A good way to use technical terms while avoiding a heavy tone is to only use one of those terms per sentence. Explain, then name When you do need to use jargon — for example, “crop tool” (the name of a tool in Photoshop), “aperture” (a photography term), or “Learn” (the name for Adobe’s collection of educational videos and in-app tutorials) — define upon first reference, then give the name. Image: Key example of how to avoid using jargon. Title, Find new ways to hone your skills. Description, Our collection of videos and in-app tutorials, called Learn, is for all experience levels. (source: https://preview.spectrum.adobe.com/content/media_1febbb522d00c09149d6f65af66cf365eb60431fa.png?width=750&format=png&optimize=medium)Define jargon like “Learn,” then explain what it’s called.Image: Key example of how speaking abstractly isn't helpful for encouraging people to learn. Title, Let's develop your skills. Start learning today. Description, Find tutorials for all our apps, track your progress, and revisit completed courses. (source: https://preview.spectrum.adobe.com/content/media_1b128ccf024124644fb0546188ecbe853364747ea.png?width=750&format=png&optimize=medium)Don’t speak abstractly about jargon, especially without explaining why it’s important."
     },
     {
       "type": "guideline",
-      "content": "Avoid directly referring to the interface.\n\nUnless it’s absolutely necessary for user comprehension, don’t directly refer to interface elements. Directly referencing the UI is not accessible, and doing so also creates issues for scalability and future-proofing in a product. After all, the UI doesn’t look and act the same to all people. For example, Adobe uses the word “Learn” by itself to refer to a concept, content, and location — not “Learn tab” or “Learn section.” We ensure that our translation team has enough context about what the associated UI element is with the string so that it can be properly translated. We avoid saying things such as: tab, panel, menu, page, section (e.g., Learn tab, Learn panel, Learn menu, Learn page, Learn section) Instead, we use “Learn” by itself as a standalone proper noun: Go to Learn, find it in Learn, Learn has more tutorials Use as a standalone proper noun to refer to a UI element, place, and/or collection of content.Don’t refer to UI elements, such as “tab.”"
+      "content": "Avoid directly referring to the interface.\n\nUnless it’s absolutely necessary for user comprehension, don’t directly refer to interface elements. Directly referencing the UI is not accessible, and doing so also creates issues for scalability and future-proofing in a product. After all, the UI doesn’t look and act the same to all people. For example, Adobe uses the word “Learn” by itself to refer to a concept, content, and location — not “Learn tab” or “Learn section.” We ensure that our translation team has enough context about what the associated UI element is with the string so that it can be properly translated. We avoid saying things such as: tab, panel, menu, page, section (e.g., Learn tab, Learn panel, Learn menu, Learn page, Learn section) Instead, we use “Learn” by itself as a standalone proper noun: Go to Learn, find it in Learn, Learn has more tutorials Image: Key example of how to avoid directly referring to the interface. Title, Want more tutorials? Description, Find our collection of free tutorials in Learn. Button with label, Go to Learn. (source: https://preview.spectrum.adobe.com/content/media_1d03307c27f2350ded601bab9eab99153ce7e8ac3.png?width=750&format=png&optimize=medium)Use as a standalone proper noun to refer to a UI element, place, and/or collection of content.Image: Key example of directly referring to the interface, which is not accessible. Title, Go to more tutorials. Description, Find our collection of free tutorials in the Learn tab. Button with label, Open Learn tab. (source: https://preview.spectrum.adobe.com/content/media_13eadd7bfe3b5abc07a11de5f89c70505fc3f51ba.png?width=750&format=png&optimize=medium)Don’t refer to UI elements, such as “tab.”"
     },
     {
       "type": "guideline",
-      "content": "Frame educational content as personalized and specific.\n\nEven if it may not be possible to personalize onboarding, a user still needs to feel like they're being shown content that matches their interests and skills — not a random assortment of topics. Try to feature specific material that would be directly relevant to someone, rather than describing everything available in a collection of educational content. Avoid catch-all words and phrases such as: collection, complete set, playlist, all tutorials Imply personalization with additive language like: this tutorial and others, this and many more videos, this and other subjects, advanced, beginner Highlight relevant content or a unique angle before mentioning there’s more available.Don’t speak generically about collections of assorted content."
+      "content": "Frame educational content as personalized and specific.\n\nEven if it may not be possible to personalize onboarding, a user still needs to feel like they're being shown content that matches their interests and skills — not a random assortment of topics. Try to feature specific material that would be directly relevant to someone, rather than describing everything available in a collection of educational content. Avoid catch-all words and phrases such as: collection, complete set, playlist, all tutorials Imply personalization with additive language like: this tutorial and others, this and many more videos, this and other subjects, advanced, beginner Image: Key example of how to frame educational content as personalized and specific. Title, Today's practice: titles and graphics. Description, Try this hands-on tutorial and many more in Learn. Button with label, Take in-app tutorial. (source: https://preview.spectrum.adobe.com/content/media_10d4ecab26690ddfeef9bf8460c6e5e772389dcca.png?width=750&format=png&optimize=medium)Highlight relevant content or a unique angle before mentioning there’s more available.Image: Key example of how framing educational content as non-personal and broad is not ideal. Title, Go to more tutorials. Description, Find our collection of free tutorials on the web. Button with label, Open in browser. (source: https://preview.spectrum.adobe.com/content/media_1810cab1ad5fb2495ffa8627c6ec6b8c153ae8ddf.png?width=750&format=png&optimize=medium)Don’t speak generically about collections of assorted content."
     },
     {
       "type": "guideline",
-      "content": "Set positive expectations.\n\nUsing a button label of “Open in browser” sets the expectation that linked content will not be shown in the same view, in-app. But, research has shown that going to a browser window from an app — as well as that button label phrasing — is demotivating and reduces engagement. When it’s necessary to send someone away from an app, tell them as much without explicitly talking about the medium of where the content will appear. When someone completes a tour or tutorial, prioritize the next actions that will take them back to the home view to try more tutorials on another subject, or to the next one in the series. Avoid explicit web- or browser-based language such as: open in browser, view on the web, view online Instead, try subtler approaches: go to, play video, check it out, find out more, back to Learn, back to in-app tutorials, all tutorials on {subject} Use “go to” to imply that a user will be leaving their current experience.Don’t use “open in browser” as a call-to-action."
+      "content": "Set positive expectations.\n\nUsing a button label of “Open in browser” sets the expectation that linked content will not be shown in the same view, in-app. But, research has shown that going to a browser window from an app — as well as that button label phrasing — is demotivating and reduces engagement. When it’s necessary to send someone away from an app, tell them as much without explicitly talking about the medium of where the content will appear. When someone completes a tour or tutorial, prioritize the next actions that will take them back to the home view to try more tutorials on another subject, or to the next one in the series. Avoid explicit web- or browser-based language such as: open in browser, view on the web, view online Instead, try subtler approaches: go to, play video, check it out, find out more, back to Learn, back to in-app tutorials, all tutorials on {subject} Image: Key example of how to use language to set positive expectations. Title, Looking for more on color? Description, View all color tutorials to keep developing your skills. Button with label, Go to color tutorials. (source: https://preview.spectrum.adobe.com/content/media_1d8939376ce3abc75c2394e2f7aa59eef5d7965e6.png?width=750&format=png&optimize=medium)Use “go to” to imply that a user will be leaving their current experience.Image: Key example of language that sets ambiguous or unpredictable expectations. Title, Learn Photoshop with our free course. Description, Take Photoshop step by step in our series of short videos. Button with label, Open in browser. (source: https://preview.spectrum.adobe.com/content/media_19138757aa0443e0f482229b92d02c38621d4057b.png?width=750&format=png&optimize=medium)Don’t use “open in browser” as a call-to-action."
     },
     {
       "type": "guideline",
-      "content": "Prioritize in-app learning.\n\nIf possible, avoid highlighting any experiences in a “home” screen that would take anyone out of the product. Building in-app experiences increases the likelihood that someone will find value and therefore return again and again. Use words that call out an in-app experience such as: in-app, inside the app, in-app tutorial, alongside your work in the app, right here, without leaving the app Emphasize what someone can do without leaving their current experience.Don’t hide the fact that a tutorial is in-app."
+      "content": "Prioritize in-app learning.\n\nIf possible, avoid highlighting any experiences in a “home” screen that would take anyone out of the product. Building in-app experiences increases the likelihood that someone will find value and therefore return again and again. Use words that call out an in-app experience such as: in-app, inside the app, in-app tutorial, alongside your work in the app, right here, without leaving the app Image: Key example of how to use language to prioritize in-app learning. Title, Start with the shape tools. Description, This session gives instructions alongside your work in the app. Button with label, Take in-app tutorial. (source: https://preview.spectrum.adobe.com/content/media_126bf69477d555f0df6638883ba768dab4c1ee4d3.png?width=750&format=png&optimize=medium)Emphasize what someone can do without leaving their current experience.Image: Key example of language that doesn't talk about learning something in-app. Title, First up: Using the shape tools. Description, This speedy series teaches you how to use Illustrator. Button with label, Make an icon. (source: https://preview.spectrum.adobe.com/content/media_131da33b9238f97638d8f18f3c20f572698153049.png?width=750&format=png&optimize=medium)Don’t hide the fact that a tutorial is in-app."
     },
     {
       "type": "guideline",
-      "content": "Banner.\n\nA banner shows a top or highly-ranked suggestion for someone. It includes bounded, actionable content that can be a hybrid of instructional and marketing language. A banner explains why someone should explore the suggested content and what they should expect from it. Use banners to drive people to experiences that correlate to either confirmed or hypothesized “a-ha” moments, or to just generally inform or educate about an onboarding experience."
+      "content": "Banner.\n\nA banner shows a top or highly-ranked suggestion for someone. It includes bounded, actionable content that can be a hybrid of instructional and marketing language. A banner explains why someone should explore the suggested content and what they should expect from it. Use banners to drive people to experiences that correlate to either confirmed or hypothesized “a-ha” moments, or to just generally inform or educate about an onboarding experience. Image: Two examples of banners. Example 1, an illustration of a video player, in editing mode on a video frame of a person on a skateboard, on a purple background with an abstract design. Banner title, Try editing your clips. Description, This session shows you how to start editing videos. Button with label, Take in-app tutorial. Example 2, an illustration of a woman with dark hair wearing a red dress and multicolor flowers on her head, on a yellow background with abstract brushstrokes. Banner title, Introducing Adobe Fresco. Description, The world's largest brush collection that delivers a natural painting and drawing experience. Button with label, Learn more. (source: https://preview.spectrum.adobe.com/content/media_1ee4ef6654684998cf68510cfa766b29d180d4b11.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Card.\n\nA card directs people to content experiences which may be related to the current view. It presents onboarding content that is contextual and useful, but may not be as crucial to provoking an “a-ha” moment as what may be shown in a banner. Use cards to promote other beneficial experiences that are lower in hierarchy than banner destinations, or to just generally inform or educate about an onboarding experience."
+      "content": "Card.\n\nA card directs people to content experiences which may be related to the current view. It presents onboarding content that is contextual and useful, but may not be as crucial to provoking an “a-ha” moment as what may be shown in a banner. Use cards to promote other beneficial experiences that are lower in hierarchy than banner destinations, or to just generally inform or educate about an onboarding experience. Image: Example of a card for Adobe Illustrator. An illustration of an astronaut in bright colors, with the Illustrator logo. Title, Get started with Illustrator. Description, Learn the basic tools and techniques for using Adobe Illustrator. 10 tutorials. 170 minutes. (source: https://preview.spectrum.adobe.com/content/media_1ccc04d745480caeddfcda703860a84cd5912d5e6.png?width=750&format=png&optimize=medium)Image: Example of a card for a tutorial. An illustration of brightly colored plants and grass. Meta text, How to use. Title, Brush tool. Status, tutorial completed. (source: https://preview.spectrum.adobe.com/content/media_1240990ffe2a4a95007ffb94567ef42b609038bd1.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Coach marks are temporary messages that engage users to interact with the UI. They can be chained into a sequence to form a tour or tutorial. Use coach marks to educate about new or unfamiliar experiences that may be unique to the interface, or to guide users to other places in a product."
+      "content": "Coach marks are temporary messages that engage users to interact with the UI. They can be chained into a sequence to form a tour or tutorial. Use coach marks to educate about new or unfamiliar experiences that may be unique to the interface, or to guide users to other places in a product. Image: Example of a coach mark with an indicator. Title, Everything's in one spot. Coach mark 1 of 4. Description, In Files, you can view and organize your cloud documents and synced files. Button with label, Next. (source: https://preview.spectrum.adobe.com/content/media_1c909b4fb8042f8612968cdddaecb3686c4258b50.png?width=750&format=png&optimize=medium)Image: Example of a coach mark with an illustration showing an interaction. Title, Pan camera. Coach mark 4 of 8. Description, Switch to the Hand tool then click and drag in the canvas to move your camera up, down, left, and right. Two buttons, Skip tour and Next. (source: https://preview.spectrum.adobe.com/content/media_14c6233dbeeffdf83798ddfd047b4fe4aee5ff002.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Empty state.\n\nAn empty state describes what people can do to add things to a view. Someone would see an empty state when they’ve either never added anything to this view, or if they’ve deleted all of what used to be there. Use an empty state to remind users how to add objects or data, and to reinforce or echo one of the more detailed onboarding mechanisms listed here."
+      "content": "Empty state.\n\nAn empty state describes what people can do to add things to a view. Someone would see an empty state when they’ve either never added anything to this view, or if they’ve deleted all of what used to be there. Use an empty state to remind users how to add objects or data, and to reinforce or echo one of the more detailed onboarding mechanisms listed here. Image: Key example of an empty state. An illustration of the Adobe Creative Cloud logo connected to icons of tasks and objects such as editing, writing, photos, shapes, and videos. Title, Work smarter with Creative Cloud Libraries. Description, Share, reuse, and manage everything you need for a project. Group together images, colors, fonts, and more. Link, title Learn more about libraries. Two buttons, labels Create new library and Follow public libraries. (source: https://preview.spectrum.adobe.com/content/media_13f615ceecd788e26ed9958a8ff393b69c1bbc8b7.png?width=750&format=png&optimize=medium)Image: Key example of an empty state. An illustration showing the action of dragging and dropping photos, documents, and files. Title, Drag and drop your file. Description, Select a file from your computer or search Adobe stock. In-line links in the description, Select and file and search Adobe Stock. (source: https://preview.spectrum.adobe.com/content/media_161a649d3549d3dec6733493ff40516a6932acc9a.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Modal.\n\nThere are two different kinds of modals. An informational modal is a popover window similar to a dialog that contains brief copy and an optional image or two. A rich modal is a popover window that contains a more in-depth content experience, such as an image carousel, video, or GIF. Use an informational model to let people know about a positive, minor change, such as a feature redesign. Use a rich modal to consolidate suggested content into one spot, to help people get to know a subject more deeply, or to show someone why they may want to try any minor benefits that may feel optional to the basic experience or workflow."
+      "content": "Modal.\n\nThere are two different kinds of modals. An informational modal is a popover window similar to a dialog that contains brief copy and an optional image or two. A rich modal is a popover window that contains a more in-depth content experience, such as an image carousel, video, or GIF. Use an informational model to let people know about a positive, minor change, such as a feature redesign. Use a rich modal to consolidate suggested content into one spot, to help people get to know a subject more deeply, or to show someone why they may want to try any minor benefits that may feel optional to the basic experience or workflow. Image: Example of a modal showing new features in Photoshop CC. Title, What’s new. 6 topics, Overview, Content-aware fill, Symmetry mode, Frame tool, Multiple undo mode, Live blending mode. Call-to-action button, label Next. Selected topic, Content-aware fill. Description, Heal images and adapt content more effectively by changing the source, rotation, scale, and more with the new content-aware fill workspace. (source: https://preview.spectrum.adobe.com/content/media_194c7c6c3c9d799b7ea27b68a8098e76e79a810a6.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Tooltip.\n\nA tooltip gives contextual help or information about a specific component on hover or focus. These can be text-only or rich content (accompanied by an animated GIF, related information, and/or calls-to-action to learn more). Use tooltips to encourage discovery and learning through UI interaction. They can also be used as lightweight catch-alls for information when no other onboarding technique may be appropriate for the message."
+      "content": "Tooltip.\n\nA tooltip gives contextual help or information about a specific component on hover or focus. These can be text-only or rich content (accompanied by an animated GIF, related information, and/or calls-to-action to learn more). Use tooltips to encourage discovery and learning through UI interaction. They can also be used as lightweight catch-alls for information when no other onboarding technique may be appropriate for the message. Image: Example of a tooltip. Four icons, a file folder with a plus sign, a cloud with an arrow pointing to it, a bulleted list, and four squares. Tooltip indicating the file folder with a plus sign icon, label Create new folder. (source: https://preview.spectrum.adobe.com/content/media_173a0f92ea8245369d997f8043075ba85dbd3c4b4.png?width=750&format=png&optimize=medium)Image: Example of a tooltip. Four icons, a file folder with a plus sign, a cloud with an arrow pointing to it, a bulleted list, and four squares. Tooltip indicating the bulleted list icon, label List view. (source: https://preview.spectrum.adobe.com/content/media_1e7c5f4021be79cdbed3a929581696d3d70672597.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Tour.\n\nA tour is a type of tutorial that introduces the UI. It can take the form of a series of coach marks or a video. Tours differ from other tutorials in that they are specifically used for orienting a user to the interface and helping them understand a basic workflow. Use a tour to show where things are in an experience. Use another onboarding method to show how to do something."
+      "content": "Tour.\n\nA tour is a type of tutorial that introduces the UI. It can take the form of a series of coach marks or a video. Tours differ from other tutorials in that they are specifically used for orienting a user to the interface and helping them understand a basic workflow. Use a tour to show where things are in an experience. Use another onboarding method to show how to do something. Image: Example of a tour showing the parts of a menu and how to navigate it in an app. 3 sections, Main section, 2 items, Home, Apps. 2nd section, label Storage, 2 items, Document Cloud, Creative Cloud. 3rd section, label Shared, 3 items, Send and Track, Reviews, Signatures. Coach mark with indicator showing the Apps menu item. Title, Apps. Step 2 of 6 in tour. Description, Browse the Apps page to download or learn more about the apps in your Creative Cloud plan. Two buttons, labels Skip tour, Next. (source: https://preview.spectrum.adobe.com/content/media_163a43661be0d772b8bfb17020f886bfee5817fc4.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Triggered element.\n\nA triggered element is content that surfaces in response to an action. This usually takes the form of a toast or other dismissible pop-up, but it needs to explain where the content can be found again once dismissed. Use triggered elements to respond to repeated actions or activity such as frequent (or infrequent) usage of a feature."
+      "content": "Triggered element.\n\nA triggered element is content that surfaces in response to an action. This usually takes the form of a toast or other dismissible pop-up, but it needs to explain where the content can be found again once dismissed. Use triggered elements to respond to repeated actions or activity such as frequent (or infrequent) usage of a feature. Image: Example of a neutral toast acting as a triggered element. Text, Saved to Tips Guide. Actions, View, close. (source: https://preview.spectrum.adobe.com/content/media_1035962ec619cfef5266a650474eab047506fa73c.png?width=750&format=png&optimize=medium)Image: Example of a confirmation toast acting as a triggered element. Text, Copied to clipboard. Action, close. (source: https://preview.spectrum.adobe.com/content/media_11ef1ba936efc26bc51e9a30a465f1603c702eb96.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Tutorial.\n\nA tutorial provides practical information about a specific subject, tool, or technique. It builds on other onboarding experiences through written or video instructions. Use tutorials to help people reach a specific outcome after they’ve become familiar with where things are in a product."
+      "content": "Tutorial.\n\nA tutorial provides practical information about a specific subject, tool, or technique. It builds on other onboarding experiences through written or video instructions. Use tutorials to help people reach a specific outcome after they’ve become familiar with where things are in a product. Image: Example of a tutorial for Adobe Photoshop. Title, Get started with Photoshop. 10 chapters. Get to know Photoshop, 21 minutes. Change the image size, 17 minutes. Work with layers, 20 minutes. Adjust the image quality, 16 minutes. Make selections, 14 minutes. Retouch images, 10 minutes. Use color, 10 minutes. Add text and shapes, 17 minutes. Combine images, 15 minutes. Apply filters, 7 minutes. Selected chapter, Get to know Photoshop. First step, an image of a bright red ladybug sitting on a flower. Title, 1. Open images. Description, Open images and create new images. (source: https://preview.spectrum.adobe.com/content/media_1f6ae2a6a782798a07793b62bef1d4bf96ec37f7a.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Video demo.\n\nA video demo shows a person completing a task. Use video demos to inspire people by portraying the experience of a workflow or product."
+      "content": "Video demo.\n\nA video demo shows a person completing a task. Use video demos to inspire people by portraying the experience of a workflow or product. Image: Example of a video demo for Lightroom mobile. Video player with Play button on a frame of a person in a forest touching a plant. Information about the demo, Category, Photography. Other platforms, Lighroom desktop. Information, Languages: Deutsch and 8 more. Title, Overview and key features. Description, Lightroom on mobile lets you craft and share pro-quality images from your smartphone or tablet using simple yet powerful tools built with Adobe Photoshop technology. Perfect your shots in a tap with more than 40 presets. Experiment with color, adjust clarity, and add vignettes. You can even connect to other Adobe apps like Photoshop Fix to retouch and refine your work. Link, Learn more. (source: https://preview.spectrum.adobe.com/content/media_1063626fabfede1034ea750e61f5083249f7f902e.png?width=750&format=png&optimize=medium)"
     }
   ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/writing-for-onboarding",
+  "sourceUrl": "https://preview.spectrum.adobe.com/content/writing-for-onboarding",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [

package/guidelines/writing-for-readability.json

@@ -8,15 +8,15 @@
     { "type": "purpose", "content": "Writing for readability" },
     {
       "type": "guideline",
-      "content": "Choose words consciously.\n\nMost common nouns and actions have synonyms that can add unnecessary complexity. Use words that would be at a 6th-grade reading level. Preferred Avoid BuyPurchaseHelpAssistAboutApproximatelyLikeSuch as"
+      "content": "Choose words consciously.\n\nMost common nouns and actions have synonyms that can add unnecessary complexity. Use words that would be at a 6th-grade reading level. Image: An example showing the correct usage. Help. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_1844b8b156b2f87131aae2d756bceb3ffe1cf0837.png?width=750&format=png&optimize=medium)Image: An example showing the incorrect usage. Assist. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_16067fca3f35f7faad8d77ba7015cfde586c2a7fc.png?width=750&format=png&optimize=medium) Preferred Avoid BuyPurchaseHelpAssistAboutApproximatelyLikeSuch as"
     },
     {
       "type": "guideline",
-      "content": "Avoid internal jargon without explaining what it means.\n\nPut yourself in the mindset of someone who's new to our products, and new to the industry where our products are used. Do they understand the jargon we use every day? Are we giving enough context for them to understand? Preferred Avoid Creative Cloud FilesCC FilesXD cloud documents, a new way to collaborate on any deviceIntroducing XD cloud docs!Please accept the Terms of Service before continuing.There was a RAISE without a handler."
+      "content": "Avoid internal jargon without explaining what it means.\n\nPut yourself in the mindset of someone who's new to our products, and new to the industry where our products are used. Do they understand the jargon we use every day? Are we giving enough context for them to understand? Image: An example showing the correct usage. Please accept the Terms of Service before continuing. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_1af0b6d0d56faae5d7362957f0a00ef3c496364fe.png?width=750&format=png&optimize=medium)Image: An example showing the incorrect usage. There was a RAISE without a handler. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_184c1f97b56242ff6177372a5393d55756084dc77.png?width=750&format=png&optimize=medium) Preferred Avoid Creative Cloud FilesCC FilesXD cloud documents, a new way to collaborate on any deviceIntroducing XD cloud docs!Please accept the Terms of Service before continuing.There was a RAISE without a handler."
     },
     {
       "type": "guideline",
-      "content": "Avoid colloquial language and slang.\n\nSlang and colloquialisms don’t make sense to all generations. Avoid ageism by using plain, clear language. Preferred Avoid Select any that applyChoose whatever blows your hair backAgree to terms and conditionsIt be like that sometimesLearn moreGet the deetz"
+      "content": "Avoid colloquial language and slang.\n\nSlang and colloquialisms don’t make sense to all generations. Avoid ageism by using plain, clear language. Image: An example showing the correct usage. Learn more. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_11fde3bc1f3c1c5efff6dc951b5f248247ccd60de.png?width=750&format=png&optimize=medium)Image: An example showing the incorrect usage. Get the deetz. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_1d554b7ba72764b3114ab6b0e3007bf466ae485ca.png?width=750&format=png&optimize=medium) Preferred Avoid Select any that applyChoose whatever blows your hair backAgree to terms and conditionsIt be like that sometimesLearn moreGet the deetz"
     },
     {
       "type": "guideline",
@@ -35,7 +35,7 @@
       "content": "Localization.\n\nExplain branded or technical terms before using them. When using an uncommon abbreviation or acronym, write out the full term on first use and follow it with the shortened version in parentheses. You can also use <abbr> or <acronym> in HTML. Avoid using homonyms (e.g., “bow before the king” vs. “put a bow on it”), or make their meaning clear via context."
     }
   ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/language-and-inclusivity/writing-for-readability",
+  "sourceUrl": "https://preview.spectrum.adobe.com/content/language-and-inclusivity/writing-for-readability",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spectrum-design-data",
-  "version": "3.3.0-beta.1",
+  "version": "3.3.0-beta.2",
   "description": "Spectrum design tokens in cascade format — the canonical source of truth for @adobe/spectrum-tokens",
   "type": "module",
   "repository": {