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

package/guidelines/writing-about-people.json

@@ -28,19 +28,19 @@
     },
     {
       "type": "guideline",
-      "content": "Use neutral, precise, relevant descriptions.\n\nPerson-first language centers the person, not their qualities, by using those qualities as modifiers: “Design Adobe apps for people who use assistive technology.” But for identity-first language, which some communities and individuals prefer instead, language highlights the disability: “Design Adobe apps for deaf people.” No group unilaterally chooses one over the other, so when you’re writing about someone, ask them how they want to be identified. Avoid euphemisms like “differently abled,” which are regarded as condescending, and descriptors used as nouns, like “the disabled” or “the blind.” These tend to present a group of individuals as a monolith and suggests a lack of individual diversity within the group. Preferred Avoid Disabled person or person with disabilities Differently abled or the disabled Blind person or person who is blind The blind Some phrases in common parlance that imply negativity are based on slurs against people with disabilities, such as “crazy” or “lame.” Never imply that a person is “suffering” from a disability or is a “victim” of a condition. Avoid appropriating terms from the disability community. Preferred Avoid Ridiculous or unpredictable Crazy Inconsiderate Tone-deaf Incompetent or bad Dumb or lame Keyanna has autism.Keyanna is suffering from autism. Placeholder variable Dummy variableAmir uses a wheelchair.Amir is confined to a wheelchair."
+      "content": "Use neutral, precise, relevant descriptions.\n\nPerson-first language centers the person, not their qualities, by using those qualities as modifiers: “Design Adobe apps for people who use assistive technology.” But for identity-first language, which some communities and individuals prefer instead, language highlights the disability: “Design Adobe apps for deaf people.” No group unilaterally chooses one over the other, so when you’re writing about someone, ask them how they want to be identified. Avoid euphemisms like “differently abled,” which are regarded as condescending, and descriptors used as nouns, like “the disabled” or “the blind.” These tend to present a group of individuals as a monolith and suggests a lack of individual diversity within the group. Image: Example of a do guideline. Placeholder variable. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1a388ca91b3dac07b8b9d41e693a811e0a4f3cbd5.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. Dummy variable. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_12215c42c43588b7fd9a9105f6e3f6345bfdb485a.png?width=750&format=png&optimize=medium) Preferred Avoid Disabled person or person with disabilities Differently abled or the disabled Blind person or person who is blind The blind Some phrases in common parlance that imply negativity are based on slurs against people with disabilities, such as “crazy” or “lame.” Never imply that a person is “suffering” from a disability or is a “victim” of a condition. Avoid appropriating terms from the disability community. Preferred Avoid Ridiculous or unpredictable Crazy Inconsiderate Tone-deaf Incompetent or bad Dumb or lame Keyanna has autism. Keyanna is suffering from autism. Placeholder variable Dummy variable Amir uses a wheelchair. Amir is confined to a wheelchair."
     },
     {
       "type": "guideline",
-      "content": "Be clear and avoid stereotypes.\n\nWith imagery and language, avoid implying that a person has to look a certain way, be a certain size, or have a certain cognitive ability to do something. Depict more types of people as typical. Preferred Avoid This tutorial teaches cropping and usually takes 5 minutes.Follow this fast, easy tutorial.This feature works best when you zoom out to 75%.This feature isn’t for the vision-impaired."
+      "content": "Be clear and avoid stereotypes.\n\nWith imagery and language, avoid implying that a person has to look a certain way, be a certain size, or have a certain cognitive ability to do something. Depict more types of people as typical. Image: Example of a do guideline. This tutorial teaches cropping and usually takes 5 minutes. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_124bc820debd47d09f5906d12389717f1a10e28c1.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. Follow this fast, easy tutorial. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_19f42ceaff4d200a149259d1997cfae3e1638808f.png?width=750&format=png&optimize=medium) Preferred Avoid This tutorial teaches cropping and usually takes 5 minutes. Follow this fast, easy tutorial. This feature works best when you zoom out to 75%. This feature isn’t for the vision-impaired."
     },
     {
       "type": "guideline",
-      "content": "Avoid appropriating terms from underrepresented groups.\n\nBe aware of how words that are often associated with physical and mental health are often used as metaphors to describe interactions and product functionality. Preferred Avoid Unavailable or locked or turned off or deactivated Grayed out Coherence check Sanity check Organize or organized OCD"
+      "content": "Avoid appropriating terms from underrepresented groups.\n\nBe aware of how words that are often associated with physical and mental health are often used as metaphors to describe interactions and product functionality. Image: Example of a do guideline. Coherence check. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1b0a570fd23357daed6ee5e264ec5b8326414be6f.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. Sanity check. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_111b67af622d45a34e944d58d16912287e1b2e2ad.png?width=750&format=png&optimize=medium) Preferred Avoid Unavailable or locked or turned off or deactivated Grayed out Coherence check Sanity check Organize or organized OCD"
     },
     {
       "type": "guideline",
-      "content": "Account for machine learning and AI.\n\nEnter metadata with caution. For example, don’t tag a photograph of a child with words like “crazy” or “weird.”"
+      "content": "Account for machine learning and AI.\n\nEnter metadata with caution. For example, don’t tag a photograph of a child with words like “crazy” or “weird.” Image: Example of a don't guideline. UI mockup showing a form with a large placeholder image area, a 'Tags' label, and a text input field containing a single tag chip labeled 'Crazy' with an active text cursor. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_190b76647c472a96e68eb4a2a396895832da538a7.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
@@ -48,11 +48,7 @@
     },
     {
       "type": "guideline",
-      "content": "Choose words carefully and understand historical significance.\n\nAdobe’s Inclusive Engineering Terminology Standard covers a set of established software terms to avoid, such as “whitelist,” “blacklist,” “master,” and “slave.” Don’t use terms assigning good or bad values to racial characteristics, such as “dark pattern.” (Terms like \"dark mode,\" \"light theme,\" or \"black screen\" literally refer to color and brightness and don't assign good or bad values, so continue using them.)"
-    },
-    {
-      "type": "guideline",
-      "content": "Choose words carefully and understand historical significance.\n\nAdobe avoids using software terms such as “whitelist,” “blacklist,” “master,” and “slave.” Don’t use terms assigning value to racial characteristics, such as “dark pattern.” (Terms like \"dark mode,\" \"light theme,\" or \"black screen\" literally refer to color and brightness and don't assign good or bad values, so continue using them.) Preferred Avoid Use this format to provide contextual clarity: ( Result in past participle form ) ( object ) Examples: Shared domains, approved people, targeted sites For coding constructs: Allowlist Whitelist Use this format to provide contextual clarity: ( Result in past participle form ) ( object ) For coding constructs: Blocklist Blacklist Legacy Grandfather clause Futile undertaking or a project destined to fail Death march Primary or main or source (e.g., “ main track ”)“ Master ” descriptors Primary / secondary Master / slave"
+      "content": "Choose words carefully and understand historical significance.\n\nAdobe avoids using software terms such as “whitelist,” “blacklist,” “master,” and “slave.” Don’t use terms assigning value to racial characteristics, such as “dark pattern.” (Terms like \"dark mode,\" \"light theme,\" or \"black screen\" literally refer to color and brightness and don't assign good or bad values, so continue using them.) Image: Example of a do guideline. Legacy. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_18351e9324b727a617022c4fa7a520fa10bf6179b.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. Grandfather clause. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_164ef15d2cd8f0f5b55809dd2abb240ba5b5766db.png?width=750&format=png&optimize=medium) Preferred Avoid Use this format to provide contextual clarity: ( Result in past participle form ) ( object ) Examples: Shared domains, approved people, targeted sites For coding constructs: Allowlist Whitelist Use this format to provide contextual clarity: ( Result in past participle form ) ( object ) For coding constructs: Blocklist Blacklist Legacy Grandfather clause Futile undertaking or a project destined to fail Death march Primary or main or source (e.g., “ main track ”) “ Master ” descriptors Primary / secondary Master / slave"
     },
     {
       "type": "guideline",
@@ -60,34 +56,34 @@
     },
     {
       "type": "guideline",
-      "content": "Use plain language.\n\nSince English isn’t everyone’s first language, it’s best to write using clear, plain language — as well as avoid idioms and phrases that might be complicated for non-English speakers to understand. Plain language is more widely understood and, therefore, avoids alienating people. It especially avoids alienating people in ways that specifically belittle non-English speakers. For example, the conversational and casual phrases “long time no see” and “no can do” were originally used to belittle Native Americans. Preferred Avoid Welcome backLong time no see2-step processWax on, wax offSorry, something went wrongNo can do"
+      "content": "Use plain language.\n\nSince English isn’t everyone’s first language, it’s best to write using clear, plain language — as well as avoid idioms and phrases that might be complicated for non-English speakers to understand. Plain language is more widely understood and, therefore, avoids alienating people. It especially avoids alienating people in ways that specifically belittle non-English speakers. For example, the conversational and casual phrases “long time no see” and “no can do” were originally used to belittle Native Americans. Image: Example of a do guideline. Sorry, something went wrong. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_19592eaedc34900d2aa16d15a70386bb9ccd17148.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. No can do. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_18e9557448586e8ad2d413900937f8932099077ea.png?width=750&format=png&optimize=medium) Preferred Avoid Welcome back Long time no see 2-step process Wax on, wax off Sorry, something went wrong No can do"
     },
     {
       "type": "guideline",
-      "content": "Depict more types of people as typical.\n\nWe must focus on building successful experiences for all users. That means writing and designing in a way that depicts all skin types, names, and cultures as typical. We cannot keep centering white-skinned, Western cultures in our designs. Preferred Avoid Dark brown or beige or tan or peach, etc. Skin or flesh or nude (referring to color swatch) Critics Peanut gallery A broad range of name examples within a product experience (e.g., Ayesha, Ibrahim, Vignesh, Quynh) Only culturally white name examples within a product experience (e.g., John, Bill, Karen, Amy)"
+      "content": "Depict more types of people as typical.\n\nWe must focus on building successful experiences for all users. That means writing and designing in a way that depicts all skin types, names, and cultures as typical. We cannot keep centering white-skinned, Western cultures in our designs. Image: Example of a do guideline. UI mockup titled 'Introducing coediting' (step 1 of 2), showing four overlapping circular avatar photos in different colored rings (purple, blue, yellow, green), with a cursor hovering over the first avatar and a tooltip displaying the name 'Ayesha Wilson,' connected by a curved line indicating a hover interaction. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_173561d2b0362bcca77aeaba6586133cb79fb99c6.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. UI mockup titled 'Introducing coediting' (step 1 of 2), showing four overlapping circular avatar photos in different colored rings (purple, blue, yellow, green), with a cursor hovering over the first avatar and a tooltip displaying the name 'John Smith,' connected by a curved line indicating a hover interaction. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_10a9a65e9b14def281e2185bac817af10dff0ce3a.png?width=750&format=png&optimize=medium) Preferred Avoid Dark brown or beige or tan or peach, etc. Skin or flesh or nude (referring to color swatch) Critics Peanut gallery A broad range of name examples within a product experience (e.g., Ayesha, Ibrahim, Vignesh, Quynh) Only culturally white name examples within a product experience (e.g., John, Bill, Karen, Amy)"
     },
     {
       "type": "guideline",
-      "content": "Be cautious of appropriating terms from underrepresented groups.\n\nHere’s a list of preferred words that are alternatives to common technology industry jargon. Preferred Avoid Native to the operating system or built-in feature Native Meeting Pow wow or circle the wagons Vision statement or strategic statement or value proposition Zen statement or Zen garden Role model or kindred spirit Spirit animal Guide Sherpa Authority or expert Guru or ninja"
+      "content": "Be cautious of appropriating terms from underrepresented groups.\n\nHere’s a list of preferred words that are alternatives to common technology industry jargon. Image: Example of a do guideline. Expert. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1cb3343dbe99abbdf43db13cf6c7bd826bacb904f.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. Guru. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_19045f2f94103c9130a672b9359d61145623e217f.png?width=750&format=png&optimize=medium) Preferred Avoid Native to the operating system or built-in feature Native Meeting Pow wow or circle the wagons Vision statement or strategic statement or value proposition Zen statement or Zen garden Role model or kindred spirit Spirit animal Guide Sherpa Authority or expert Guru or ninja"
     },
     {
       "type": "guideline",
-      "content": "Be clear and avoid gendered language and stereotypes.\n\nRather than “he” or “she,” if you don’t know a person’s pronouns, make the phrase plural and use “they” instead. Use of “they” to describe one person is also accepted, although the syntax remains plural (e.g., “they are” = “that person is”). It’s also best to avoid using roles or stereotypes that have gendered roots (e.g., “businessman\" or “waitress”). Preferred Avoid Server Waitress Businessperson Businessman Flight attendant Stewardess They He/she or (S)he A group of people or a group of women Guys or girls or ladies Parents Moms"
+      "content": "Be clear and avoid gendered language and stereotypes.\n\nRather than “he” or “she,” if you don’t know a person’s pronouns, make the phrase plural and use “they” instead. Use of “they” to describe one person is also accepted, although the syntax remains plural (e.g., “they are” = “that person is”). It’s also best to avoid using roles or stereotypes that have gendered roots (e.g., “businessman\" or “waitress”). Image: Example of a do guideline. They can fill out this form. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_11f4fc44c503c2e74074d1314b59e3ba53534177b.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. He/she can fill out this form. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_14eb1213b292de728d3ae57bcee81ffeb5ca4f012.png?width=750&format=png&optimize=medium) Preferred Avoid Server Waitress Businessperson Businessman Flight attendant Stewardess They He/she or (S)he A group of people or a group of women Guys or girls or ladies Parents Moms"
     },
     {
       "type": "guideline",
-      "content": "Choose words carefully and understand historical significance.\n\nUse gender and sexuality descriptors as modifiers, not nouns (e.g., “transgender woman” rather than “a transgender,” “bisexual person” rather than “a bisexual”). A person’s pronouns are not opinion or preference, even if they may change over time (view Spectrum’s guidelines on pronouns ). All of this helps us emphasize every person’s humanity, and keeps us from alienating people who aren’t cisgender and heterosexual. Preferred Avoid Transgender people or trans people Transgendered people or transgenders or the transgendered or transexuals Trans women Trans-women A transgender man A transman Alejandra, a lesbian woman Alejandra is a lesbian Jing, a non-binary person Jing is a non-binary Saadi is cis Saadi is CIS What are your pronouns?What are your preferred pronouns?Jamal’s pronouns are he/him/his. Jamal prefers he/him pronouns. Wholehearted or impassioned Hysterical"
+      "content": "Choose words carefully and understand historical significance.\n\nUse gender and sexuality descriptors as modifiers, not nouns (e.g., “transgender woman” rather than “a transgender,” “bisexual person” rather than “a bisexual”). A person’s pronouns are not opinion or preference, even if they may change over time (view Spectrum’s guidelines on pronouns). All of this helps us emphasize every person’s humanity, and keeps us from alienating people who aren’t cisgender and heterosexual. Image: Example of a do guideline. What are your pronouns? (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_168e25aded8844c4098a3e13fa36e868c505a615b.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. What are your preferred pronouns? (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1d210ed4b5a99533380b6da0bd2af860b88029994.png?width=750&format=png&optimize=medium) Preferred Avoid Transgender people or trans people Transgendered people or transgenders or the transgendered or transexuals Trans women Trans-women A transgender man A transman Alejandra, a lesbian woman Alejandra is a lesbian Jing, a non-binary person Jing is a non-binary Saadi is cis Saadi is CIS What are your pronouns? What are your preferred pronouns? Jamal’s pronouns are he/him/his. Jamal prefers he/him pronouns. Wholehearted or impassioned Hysterical"
     },
     {
       "type": "guideline",
-      "content": "Be specific and kind.\n\nKnow the difference between sex (male/female) and gender (man/woman). When collecting personal data from users, consider if it is really necessary to ask for a person’s gender. Data collection and forms, while useful to product builders, can feel intrusive when asking about gender. When you really do need the information, allow for both common and custom responses, self-identification, multiple selections, and the option to opt out of responding. Avoid asking proxy questions, for example, asking for someone’s gender when the information that is actually needed is their bike size. Preferred Avoid Prefer to self-describe and Prefer to not respond Other"
+      "content": "Be specific and kind.\n\nKnow the difference between sex (male/female) and gender (man/woman). When collecting personal data from users, consider if it is really necessary to ask for a person’s gender. Data collection and forms, while useful to product builders, can feel intrusive when asking about gender. When you really do need the information, allow for both common and custom responses, self-identification, multiple selections, and the option to opt out of responding. Avoid asking proxy questions, for example, asking for someone’s gender when the information that is actually needed is their bike size. Image: Example of a do guideline. UI mockup of a 'Gender' dropdown field, open to show four options: Man, Woman (currently selected, indicated by a checkmark), Prefer not to answer, and Prefer to self-describe. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_104a2fe5be94e7d900c6368f6cc24d20f85d0012f.png?width=750&format=png&optimize=medium) Image: Example of a don't guideline. UI mockup of a 'Gender' dropdown field, open to show three options: Male, Female (currently selected, indicated by a checkmark), and Other. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_11fde27c76debb0ef7dbc1bd67858fa6c2cf5c569.png?width=750&format=png&optimize=medium) Preferred Avoid Prefer to self-describe and Prefer to not respond Other"
     },
     {
       "type": "guideline",
       "content": "Account for machine learning and AI.\n\nPeople globally identify with many genders and sexualities, so it's important to teach AI exactly that. It wasn’t until June 2018 that the World Health Organization (WHO) declassified being transgender as a mental illness, so even though humans have adjusted this perspective, machine learning and AI can still perpetuate these biases. Don’t use AI or machine learning to guess genders based on image recognition, text analysis, or anything else."
     }
   ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/language-and-inclusivity/writing-about-people",
+  "sourceUrl": "https://spectrum.adobe.com/content/language-and-inclusivity/writing-about-people",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [

package/guidelines/writing-for-errors.json

@@ -12,55 +12,71 @@
     },
     {
       "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. 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."
+      "content": "For error scenarios, content and design are inseparable. It’s crucial to know what you need to say (the message), and how you’re going to say it (the 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. 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)"
+      "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://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://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": "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)"
+      "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://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://spectrum.adobe.com/content/media_1682f75850766460bc478fa21e0520022ec72c8f0.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. 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)"
+      "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://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://spectrum.adobe.com/content/media_122449620310426211b0e58d83482205950e4dfda.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. 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)"
+      "content": "Regardless of the design component or message length, the most comprehensive error messages include three distinct communication parts: What happened The underlying cause (if possible) How to fix it Not every error message you'll write will follow this framework, but many will. Depending on your audience or the situation, it may not be necessary or relevant to communicate the underlying cause. Image: Diagram illustrating through labels the communication parts of an error message. The text of an error dialog, in 3 distinct communication parts. First part, the title, what happened. Text, Your file could not be saved. Second part, the underlying cause, first sentence of the dialog description. Text, There was an error in connecting to the server, so this file was not saved to your cloud documents. Third part, how to fix it or become unblocked, second sentence of the dialog description. Text, Please wait a few seconds and try saving the file again. If the problem continues, let us know. (source: https://spectrum.adobe.com/content/media_1f4851adc9e5f26d3552590fc83cf6adcd5eab90a.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.” 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)"
+      "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://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://spectrum.adobe.com/content/media_171e1d7bb948c9d90dfdd3f6d9ea2aed7ef59bf53.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. 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)"
+      "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://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://spectrum.adobe.com/content/media_1d8de2015fd403a20b7b6262389e8bac99b420bed.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. 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)"
+      "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://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://spectrum.adobe.com/content/media_19b86aa2ae85d836e29ad4a172b58540ade1112a2.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. 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)"
+      "content": "Error messaging, like all in-product content, prioritizes the humans that use interfaces over system technicalities."
     },
     {
       "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. 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."
+      "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://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://spectrum.adobe.com/content/media_18bba303711ef7520bb47f2d61b5bec940ab75dfe.png?width=750&format=png&optimize=medium)"
     },
     {
       "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. 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)"
+      "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://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://spectrum.adobe.com/content/media_12e5135ff0e69e83869e5cb69fb18f6914f130c9c.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. 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)"
+      "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://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://spectrum.adobe.com/content/media_18689b28dae936d0ddabfd37235a3e6efb168403f.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. 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)"
+      "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://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": "Error messages are opportunities to help users confidently move forward. When writing them, think about the most straightforward path to a solution, then clearly describe it."
+    },
+    {
+      "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. 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://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://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. Image: Key example of a correct usage. Your wifi connection is unstable and affecting download speed. Try switching to an ethernet cable. (source: https://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://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. Image: Key example of a correct usage. Your document could not be saved. Please try again. (source: https://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://spectrum.adobe.com/content/media_14f412d6e89149021159b01597be0bf50a8509485.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
@@ -72,38 +88,42 @@
     },
     {
       "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. 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)"
+      "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://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://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. 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://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://spectrum.adobe.com/content/media_1fa2c3cdb04cb5051867e25a51720583a774b1cb0.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. 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)"
+      "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://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://spectrum.adobe.com/content/media_19094c5873c7fb7bc0c4bb1454ee7bcb34e254234.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?\" 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)"
+      "content": "Choose your component based on your error message — not the other way around. Always have the error message ready before determining how to show it. When you have your error message ready, then consider how it will fit within the interaction design. Think about what user or system action triggers the error, how contextually or spatially relevant it is to where a user is in the UI, and what a user may be doing in the moment before the error would appear. Use this framework when deciding which component to use: Low High Consequence How consequential is the error? Low consequence It’s a simple error that can easily be resolved. High consequence It’s a high-stakes error, potentially destructive, and is a big deal to the user. Complication How complicated is the error? Low complication There’s not much we need to explain to the user beyond how it affects their experience right now. High complication The circumstances or points of failure are long or specific, and the user needs to know about it. Action Can the user do anything to resolve the error? Low action The user can’t do anything, or just needs to “try again.” High action The user needs to actively resolve the error, like change a setting or restart an app. Try keeping to one error message per component, to help users more easily parse the information. For multiple errors that can appear at once, like toasts, these will stack based on timing and severity to let users acknowledge each error individually. Spectrum has several different types of components for showing error messages. Here’s how to choose which would be the best for your use case. Image: Key example of an error alert dialog, including an error icon, showing a suitable 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://spectrum.adobe.com/content/media_1463de475bb29f408667e6a85eda1f1de1d047f0a.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 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)"
+      "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://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. 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)"
+      "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://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. 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)"
+      "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://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. 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)"
+      "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://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://preview.spectrum.adobe.com/content/writing-for-errors",
+  "sourceUrl": "https://spectrum.adobe.com/content/writing-for-errors",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [