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

package/guidelines/using-icons.json

@@ -8,100 +8,89 @@
     { "type": "purpose", "content": "Using icons" },
     {
       "type": "guideline",
-      "content": "Workflow icons are graphical metaphors or symbols that users interact with to navigate and manipulate objects. They maintain a consistent size and style within each platform to ensure visual harmony and usability. While consistency is key, it is now fairly common to combine different icon scales to support hierarchy and context."
-    },
-    {
-      "type": "guideline",
-      "content": "UI icons are atomic pieces — like arrows, crosses, or chevrons — that are part of a component. They aren’t metaphorical per se, but they’re an indication of how users interact with a component (for example, what happens when you click on a disclosure chevron or drag handle in a panel). Unlike workflow icons, UI icons come in assorted sizes."
-    },
-    {
-      "type": "guideline",
-      "content": "Status badges are indicators that communicate a variety of statuses or states, such as presence, validity, completeness, and more. Premium badges indicate that a feature is only available to paying customers."
-    },
-    {
-      "type": "guideline",
-      "content": "Spectrum 2 workflow icons come in two sizes per platform, but with one stroke weight: 1.5 px."
+      "content": "Only use approved icons.\n\nThe library currently only includes a subset of icons, and are for mock-up purposes only. If you need to create a mock-up with an icon that isn't available yet, just use a placeholder icon. Don't use unapproved icons in your work (for example, downloaded from Noun Project, or icons you've created yourself). If you have a question about icons, or would like to reach out to the Icons team directly, email icons@adobe.com or post in #icons on Slack."
     },
     {
       "type": "guideline",
-      "content": "The primary size for Desktop/Web is a canvas of 20 px with the icon being \\~18 px. There’s a secondary size for UI areas — like a layers panel, lists, or cards — which require smaller versions and come in a 16 px canvas with the icon being \\~14 px."
-    },
-    {
-      "type": "guideline",
-      "content": "The equivalent for Mobile is the primary size of the canvas at 24 px with the icon being \\~22 px. The secondary size canvas is 20 px with the icon being \\~18px."
-    },
-    {
-      "type": "guideline",
-      "content": "In Spectrum components, workflow icons scale up or down slightly when they’re used. For example: a 20 px icon in a medium-sized component will be slightly larger in a large-sized component, and smaller in a small-sized component. UI icons come in their respective size range, since Spectrum components treat these differently."
+      "content": "Workflow icons are graphical metaphors or symbols that users interact with to navigate and manipulate objects. They maintain a consistent size and style within each platform to ensure visual harmony and usability. While consistency is key, it is now fairly common to combine different icon scales to support hierarchy and context."
     },
     {
       "type": "guideline",
-      "content": "“S2” is the prefix for Spectrum 2 icons."
+      "content": "UI icons are atomic pieces — like arrows, crosses, or chevrons — that are part of a component. They aren't metaphorical per se, but they're an indication of how users interact with a component (for example, what happens when you click on a disclosure chevron or drag handle in a panel). Unlike workflow icons, UI icons come in assorted sizes."
     },
     {
       "type": "guideline",
-      "content": "Here’s a breakdown of each part of the icon naming convention:"
+      "content": "Badges (status and premium).\n\nStatus badges are indicators that communicate a variety of statuses or states, such as presence, validity, completeness, and more. Premium badges indicate that a feature is only available to paying customers."
     },
     {
       "type": "guideline",
-      "content": "An example of the naming convention for Spectrum 2 (S2) icons."
+      "content": "Cursors and HUD.\n\nThe cursor style has also been updated to match the look and feel of the Spectrum 2 icons."
     },
     {
       "type": "guideline",
-      "content": "Keeping one stroke weight consistent within a size range helps to balance out and contrast the visual weight. For Web and Desktop platforms, icons are designed at a 20 px canvas as default with a 1.5 px stroke, resulting in a 1.64 px stroke when sized up to 24 px for mobile. This helps keep a unified look, and it builds icons efficiently since it’s not necessary to redraw them for each platform."
+      "content": "Workflow icon sizes.\n\nSpectrum 2 workflow icons come in two sizes per platform, but with one stroke weight: 1.5 px. The primary size for Desktop/Web is a canvas of 20 px with the icon being ~18 px. There's a secondary size for UI areas — like a layers panel, lists, or cards — which require smaller versions and come in a 16 px canvas with the icon being ~14 px. The equivalent for Mobile is the primary size of the canvas at 24 px with the icon being ~22 px. The secondary size canvas is 20 px with the icon being ~18px."
     },
     {
       "type": "guideline",
-      "content": "All icons with angles get a 1.5 px rounding treatment to achieve a rounder appearance. Inner corners are slightly rounded, and all stroke ends have rounded end caps. By default, the corner radius can be decreased in case a metaphor requires pointy edges."
+      "content": "T-shirt sizes.\n\nIn Spectrum components, workflow icons scale up or down slightly when they're used. For example: a 20 px icon in a medium-sized component will be slightly larger in a large-sized component, and smaller in a small-sized component. UI icons come in their respective size range, since Spectrum components treat these differently."
     },
     {
       "type": "guideline",
-      "content": "Icon designs include a safe area to ensure there’s flexibility for finding the best positioning and balance in a layout. The main shape should be centered, and modifier placement is primarily at the bottom right corner of the canvas. Notification dots appear at the top right corner (these are mostly added programmatically)."
+      "content": "S2\" is the prefix for Spectrum 2 icons. Here's a breakdown of each part of the icon naming convention: Prefix identifies it as part of a larger group of assets. Type is the type of the asset: Icon, Ani-Icon, Ani-Illu, Illu, Cur, or Mock-Icon. Icon name is in Pascal case: there are no empty spaces or individual characters allowed. When names use multiple words, it utilizes a hierarchy to determine the word sequence. Icon canvas size is stated in pixel at @1x. Icon State indicator: normal state is \"_N\", selected state is \"_S\", and Dark UI theme adds a \"D\". Filetype suffix indicates the asset format, like SVG or PDF. An example of the naming convention for Spectrum 2 (S2) icons."
     },
     {
       "type": "guideline",
-      "content": "The intersections of badge/modifier placement."
+      "content": "Stroke border (weight).\n\nKeeping one stroke weight consistent within a size range helps to balance out and contrast the visual weight. For Web and Desktop platforms, icons are designed at a 20 px canvas as default with a 1.5 px stroke, resulting in a 1.64 px stroke when sized up to 24 px for mobile. This helps keep a unified look, and it builds icons efficiently since it's not necessary to redraw them for each platform."
     },
     {
       "type": "guideline",
-      "content": "The vertical spacing between icons and text is adjusted to create balance."
+      "content": "Corner radius and shape rounding.\n\nAll icons with angles get a 1.5 px rounding treatment to achieve a rounder appearance. Inner corners are slightly rounded, and all stroke ends have rounded end caps. By default, the corner radius can be decreased in case a metaphor requires pointy edges."
     },
     {
       "type": "guideline",
-      "content": "For example: in a medium-sized component, shifting the text box 1 px up and the icon box 1 px down inside a button better balances out the appearance and refines the relationship with text in Adobe Clean Medium."
+      "content": "Icon and badges placement.\n\nIcon designs include a safe area to ensure there's flexibility for finding the best positioning and balance in a layout. The main shape should be centered, and modifier placement is primarily at the bottom right corner of the canvas. Notification dots appear at the top right corner (these are mostly added programmatically). The intersections of badge/modifier placement."
     },
     {
       "type": "guideline",
-      "content": "An example of icon and text alignment in a button."
+      "content": "The vertical spacing between icons and text is adjusted to create balance. For example: in a medium-sized component, shifting the text box 1 px up and the icon box 1 px down inside a button better balances out the appearance and refines the relationship with text in Adobe Clean Medium. An example of icon and text alignment in a button.An example of a quiet action button with a 16 px icon."
     },
     {
       "type": "guideline",
-      "content": "An example of a quiet action button with a 16 px icon."
+      "content": "Advantages to the new SVG structure.\n\nOne SVG asset serves all states in all UI color themes Stable and easy creation and export workflows in Illustrator Streamlined SVG code for smaller file size Minimal effort to update any Spectrum color changes Allows for app-specific custom colors (a variable illustration accent color could be matched to the app color) Will become easier to add special colors for an app (for example, the brand red color used in Acrobat) Example of SVG code. The highlighted sections show that two dynamic colors will be changed programmatically, and that there's a white exclamation mark which should always be displayed in white."
     },
     {
-      "type": "guideline",
-      "content": "The new SVG native format for icons allows for automatic tinting to match different states (hover, selected, etc.) and can programmatically switch depending on UI brightness or color theme. It’s not about tinting the whole SVG in one color, but tinting single elements inside the SVG. To do this, the new SVGs use named CSS variables to set color values for every element. There will be Spectrum tokens for this, so automatic tinting will work out-of-the-box in any product using Spectrum CSS."
+      "type": "do-dont",
+      "content": "Don't resize icons",
+      "dont": "All icons are crafted with a specific stroke weight, size, and canvas to match a larger icon set. Resizing or scaling them can change the appearance, creating inconsistency within a product. Ask for more sizes by submitting a request to the Icons team."
     },
     {
-      "type": "guideline",
-      "content": "For other apps, it will be easier to add the needed color information to their own CSS. Transparencies will be used to achieve tints of the primary icon color, making it easy to use at least the gray tone when it’s not possible to work with CSS variables."
+      "type": "do-dont",
+      "content": "Don't create your own icons",
+      "dont": "The Icons team works carefully to ensure that icon metaphors and style are consistent across Adobe products. When different product teams each decide to choose their own metaphors or build their own icons, this becomes a complex issue in Adobe's large product portfolio — and it shows our customers that we don't speak with a single brand voice. If you need a new icon for Spectrum 2, request it."
     },
     {
       "type": "guideline",
-      "content": "Example of SVG code. The highlighted sections show that two dynamic colors will be changed programmatically, and that there's a white exclamation mark which should always be displayed in white."
+      "content": "Semantic colors have specific meanings in the design system. Choose icons with metaphors that visually align with their corresponding semantic color. Ensure that any semantic color usage in icons is consistent with Spectrum's usage. If you're using icons to convey \"Success,\" \"Alert,\" \"Information,\" or \"Caution\" meanings (such as in an in-line alert ), use the appropriate colors."
     },
     {
       "type": "guideline",
-      "content": "If you diverge from Spectrum colors, you’ll need to make sure that your design has enough contrast between the icon and the background. Use subtle fills in light and dark themes to maintain legibility without overpowering the UI. Make sure that the icons remain legible and distinguishable across varied backgrounds and themes."
+      "content": "Meeting contrast requirements.\n\nUsing the available Spectrum 2 colors with Spectrum 2 icons will ensure that your design is both visually appealing and meets the WCAG minimum contrast ratio of 3:1 for non-text contrast. If you diverge from Spectrum colors, you'll need to make sure that your design has enough contrast between the icon and the background. Use subtle fills in light and dark themes to maintain legibility without overpowering the UI. Make sure that the icons remain legible and distinguishable across varied backgrounds and themes. The Stark plugin for Figma can help you check your contrast ratio. Consider three color combinations: A dark icon on a color background A light icon on a color background Tinted icons on a color background"
     },
     {
       "type": "guideline",
-      "content": "The library currently only includes a subset of icons, and are for mock-up purposes only. If you need to create a mock-up with an icon that isn’t available yet, just use a placeholder icon. Don’t use unapproved icons in your work (for example, downloaded from Noun Project, or icons you’ve created yourself)."
+      "content": "Meeting contrast requirements.\n\nUsing the available Spectrum 2 colors with Spectrum 2 icons will ensure that your design is both visually appealing and meets the WCAG minimum contrast ratio of 3:1 for non-text contrast. If you diverge from Spectrum colors, you'll need to make sure that your design has enough contrast between the icon and the background. Use subtle fills in light and dark themes to maintain legibility without overpowering the UI. Make sure that the icons remain legible and distinguishable across varied backgrounds and themes. Consider three color combinations: A dark icon on a color background A light icon on a color background Tinted icons on a color background"
     }
   ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/using-icons/",
-  "lastUpdated": "2026-02-02",
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/icons-and-illustrations/using-icons",
+  "lastUpdated": "2026-08-14",
   "status": "published",
-  "tags": ["designing"],
-  "related": [{ "ref": "icon-fundamentals" }, { "ref": "illustrations" }]
+  "tags": [
+    "icons",
+    "Workfront",
+    "Icon Finder",
+    "Noun Project",
+    "naming convention",
+    "UI icons",
+    "workflow icons"
+  ]
 }

package/guidelines/visual-language-containers.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/visual-language-containers.json",
+  "name": "visual-language-containers",
+  "title": "Containers",
+  "category": "designing",
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "In Spectrum 2, containers have more defined rules to help guide in the creation of custom containers for product-specific contexts. Containers are used across Spectrum 2 interfaces in multiple ways, but the commonality they share is that they group related concepts together into distinct areas. Some usages of containers have more detailed guidelines. For example, a card uses a container and inherits its properties, but it can only represent a distinct object (such as an individual asset or product). A block of marketing material containing multiple concepts (like subscription information plus actions to take) is grouped together in a container, but is not considered a card. Whether broad or specific, a user should be able to readily tell the purpose of a container. Separation of containers is marked through a clear visual change, such as contrast in a background color or through spacing. All containers share a common set of rules for styles, padding, and emphasis. Examples of containers: two cards with different sizes and layout options, and a select box. Examples of containers: two cards with different sizes and layout options, and a select box.\n\n### Example\n\nCards and select boxes share container styles. In this example, both use the emphasized style. Cards also have additional options that select boxes do not, like t-shirt size and layout."
+    },
+    {
+      "type": "guideline",
+      "content": "All containers share a set of defined styles. Background color By default, containers are visually distinguished through a change in background color. Learn more about this in background layers. Emphasized In some situations, drop shadows are used to provide emphasis to a container or group of containers, like in a set of related cards. Emphasized containers should be used sparingly. View more about container emphasis. Border Borders can also be used around objects as an alternate style to a background color, and should be used without a fill. Vertical, full-width dividers can also be used to create separation for larger sections of content, like in a panel. View more about border width. Spacing This is the container style with the least emphasis. Instead of using a visible border, spacing is used to create separation between concepts. View more about spacing."
+    },
+    {
+      "type": "guideline",
+      "content": "Example.\n\nThis medium card uses spacing-300 for internal padding."
+    },
+    {
+      "type": "guideline",
+      "content": "Example.\n\nIn this group of containers — each representing a product — different container styles can be used to draw attention to a specific item. In this case, the emphasized container is paired with a badge, and contrasts against the more subdued containers with filled (gray) backgrounds."
+    },
+    {
+      "type": "guideline",
+      "content": "States of interactive, emphasized containers.\n\nIf the whole container is interactive, hover is shown through a slightly more prominent drop shadow. When dragged, a much more prominent shadow is shown in order to bring focus to the dragged item and show elevation above the rest of the UI. Note that specific components might have different options and states."
+    },
+    {
+      "type": "guideline",
+      "content": "A consistent app frame helps create a sense of brand unity and helps users feel comfortable and familiar with our products. Predictable navigation is also especially helpful for users who work across multiple applications, and it makes it easier to learn how to use new products. The Spectrum 2 app frame framework provides a consistent visual style and navigation. It offers foundational structures and guidelines that product teams can adapt to their own contexts. View more details about the S2 app frame. The main content area is defined by a unique container style that's used only in the app frame. It has a subtle drop shadow to provide separation from the navigation. View more about using container styles to divide content within content areas. Example of an app frame with a side navigation. Example of an app frame with a side navigation."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/visual-language/containers",
+  "lastUpdated": "2026-08-19",
+  "status": "published"
+}

package/guidelines/voice-and-tone.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/voice-and-tone.json",
+  "name": "voice-and-tone",
+  "title": "Voice and tone",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Voice and tone" },
+    {
+      "type": "guideline",
+      "content": "Rational.\n\nClear and understandable Ensure decisions about grammar and mechanics are research-informed and tested. Avoid language that’s overly opinionated, funny, or trendy."
+    },
+    {
+      "type": "guideline",
+      "content": "Human.\n\nFriendly, honest, and responsible Vary sentence style and structure for readability and relatability. Acknowledge and account for users’ emotions."
+    },
+    {
+      "type": "guideline",
+      "content": "Focused.\n\nConcise and simple Describe only what’s needed, without unnecessary decoration. Avoid creating new concepts and only name things when necessary."
+    },
+    {
+      "type": "guideline",
+      "content": "Brand guidelines.\n\nThe Adobe Style Guide's \"Voice\" section defines the principles of our brand voice. This guide also contains a glossary with branded terms and information about applying branding guidelines in a variety of different customer-facing situations."
+    },
+    {
+      "type": "guideline",
+      "content": "Tone Spectrum.\n\nThe right tone depends on a user’s contextual needs and corresponding emotions for that experience, as well as how involved and emotional we need to be in the process. Think of the tone for any given experience as being on a spectrum: Tone can fall on a spectrum going from motivational to helpful, helpful to instructive, instructive to reassuring, reassuring to supportive."
+    },
+    {
+      "type": "guideline",
+      "content": "Tone guide.\n\nThe tone spectrum acts as a sliding scale for considering which of our attitudes and expressions are appropriate for different experiences. ToneAttitudeFrequency Motivational Positive and encouraging We're looking out for you and cheering you on. You've got this!Rarely Helpful Polite and respectful We know you're busy, so we'll make this brief.Occasionally Instructive Neutral and direct Here is the information you need.Often Reassuring Professional and reliable We know you're worried about this issue, and we're here to help.Occasionally Supportive Concerned and empathetic Something bad has happened and we understand how you feel. We want to inform, guide, and support you through this.RarelyThe points on this spectrum aren't necessarily binary. For example, the right tone for an experience could be either motivational or helpful, or it could exist somewhere between those points."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/voice-and-tone",
+  "lastUpdated": "2026-09-14",
+  "status": "published",
+  "tags": [
+    "voice",
+    "tone",
+    "brand guidelines",
+    "Adobe Style Guide",
+    "language guidelines",
+    "readability",
+    "user experience",
+    "tone spectrum"
+  ]
+}

package/guidelines/writing-about-people.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/writing-about-people.json",
+  "name": "writing-about-people",
+  "title": "Writing about people",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Writing about people" },
+    {
+      "type": "guideline",
+      "content": "The goal of all UX content is to be understandable to all — not just to the people paying for something or for those in a certain industry — and to accommodate the many ways that people use products. When creating content for product experiences, think and write by centering the person you’re writing to or about in a way that’s compassionate, inclusive, and respectful. Work to grasp the perspective of underrepresented groups, and avoid writing in a way that may view or treat someone as intrinsically different from yourself. You can use methods like co-designing and UX research. Keep the following best practices in mind when writing:"
+    },
+    {
+      "type": "guideline",
+      "content": "Use neutral, precise, relevant descriptions.\n\nOnly include personal qualities if they’re relevant and important. Write what you mean, then look back at what you wrote and think about whom you’re centering with your words. Doing this can reveal which people you’re leaving out. What’s the sentiment behind your words?"
+    },
+    {
+      "type": "guideline",
+      "content": "Choose words carefully and understand historical significance.\n\nBe cautious of appropriating terms from marginalized communities. In this guide, we say “underrepresented groups.” You can also reference 3rd-party sources such as Wikipedia’s list of which words to use and which to avoid."
+    },
+    {
+      "type": "guideline",
+      "content": "Be clear and avoid stereotypes.\n\nBe on the lookout for proxy questions and statements, which appeal to generalizations and stereotypes. For example, saying, “just buy more storage” is a proxy statement on economic status, while “view additional storage options” doesn’t make those assumptions. Communicate from a place of equality, not condescension, and think about the worst-case interpretation of your words. Clear intent excludes fewer people and reduces bias."
+    },
+    {
+      "type": "guideline",
+      "content": "Account for machine learning and AI.\n\nWhen collecting user data in app or web experiences, first think about whether that information is actually needed, and then if it really is, communicate why. Allow for both common and custom responses, self-identification, multiple selections, and the option to opt out of responding. Artificial intelligence learns only from the information we provide to it, so our inherent biases can easily become included in training data. If content allows for variable and AI-provided information, consider the ways that may affect any copy."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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"
+    },
+    {
+      "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.”"
+    },
+    {
+      "type": "guideline",
+      "content": "Use neutral, precise, relevant descriptions.\n\nLet’s say you’re writing a persona. When describing a person's country of origin or race, be as descriptive as possible as to not generalize any race or ethnicity. Race is only pertinent to biographical and announcement-related content that involves significant, groundbreaking, or historical events. For capitalization, Adobe follows AP Stylebook guidelines: capitalize nationalities, peoples, races (all except white), and tribes."
+    },
+    {
+      "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"
+    },
+    {
+      "type": "guideline",
+      "content": "Be clear and avoid stereotypes.\n\nIf you want to use a certain idiomatic or casual phrase, research its history before doing so. For example, imperfect spellings or pronunciations of words can imply pejorative associations with an accent. Be on the lookout for proxy questions, such as relating postal codes to ethnicity in rejecting job candidates, or making pricing or marketing decisions based on the average income of postal codes."
+    },
+    {
+      "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"
+    },
+    {
+      "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)"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "writing",
+    "inclusive design",
+    "neutral language",
+    "person-first language",
+    "identity-first language",
+    "avoid stereotypes",
+    "self-identification",
+    "AI bias"
+  ]
+}

package/guidelines/writing-for-errors.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/writing-for-errors.json",
+  "name": "writing-for-errors",
+  "title": "Writing for errors",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Writing for errors" },
+    {
+      "type": "guideline",
+      "content": "An error occurs when users expect one thing to happen, but either something else — or nothing — happens. Errors can cause frustration, confusion, a loss of data, or more labor for users. These moments make it harder for people to get things done. At Adobe, the audiences for error messages span a wide variety of people. The language we use can vary depending on the audience and the context. But ultimately, these kinds of messages need to be in service of the end user, regardless of their skill sets or technical familiarity. These messages often bring frustrating news, and can be highly visible and memorable, so they need to be relevant, useful, and clear. We show users error messages to let them know what happened, what the cause of the error was, and what (if anything) they can do to resolve it."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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.”"
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Using voice.\n\nAs with all other in-product writing, error messaging should follow Spectrum’s in-product voice principles: Rational (clear and understandable), Human (friendly, honest, and responsible), and Focused (concise and simple)."
+    },
+    {
+      "type": "guideline",
+      "content": "Using tone.\n\nTone is a strategic tool to help a user accomplish goals and more easily relate to a system. Tone changes depending on the audience, context, and severity of an error. Here are a few tones for common error messages: Tone When to use Example Instructive For low-volume, low-consequence errors. When you just want to tell users about an error state. Unable to load this page. Reassuring For minor errors. When you know the user is worried about something, and want them to know there's help available. Our servers timed out and we couldn’t save your file. Please try again, and if the problem persists, contact your IT administrator. Supportive For big errors where something bad has happened. When we want to acknowledge that the user is upset and want to inform, guide, and support them. We’re sorry, but we couldn’t renew your subscription because your credit card has expired. You still have 90 days to recover your files and apps by renewing your subscription with an active card. Contact us if we can help you get set up!"
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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?"
+    },
+    {
+      "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"
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "error messages",
+    "error prevention",
+    "inline validation",
+    "toast",
+    "alert dialog",
+    "disabled states",
+    "anatomy of an error message",
+    "underlying cause",
+    "automatic input correction"
+  ]
+}