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

package/guidelines/language-and-inclusivity-writing-about-people.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/language-and-inclusivity-writing-about-people.json",
+  "name": "language-and-inclusivity-writing-about-people",
+  "title": "Writing about people",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Writing about people" },
+    {
+      "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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1a388ca91b3dac07b8b9d41e693a811e0a4f3cbd5.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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 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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_124bc820debd47d09f5906d12389717f1a10e28c1.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1b0a570fd23357daed6ee5e264ec5b8326414be6f.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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.” Image: Key example showing how not to account for machine learning and AI. Incorrect usage, photograph with metadata tag field, label Tags. Inside tag field, tag label Crazy. (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_190b76647c472a96e68eb4a2a396895832da538a7.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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.) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_18351e9324b727a617022c4fa7a520fa10bf6179b.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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",
+      "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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_19592eaedc34900d2aa16d15a70386bb9ccd17148.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_18e9557448586e8ad2d413900937f8932099077ea.png?width=750&format=png&optimize=medium) 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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_173561d2b0362bcca77aeaba6586133cb79fb99c6.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1cb3343dbe99abbdf43db13cf6c7bd826bacb904f.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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”). Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_11f4fc44c503c2e74074d1314b59e3ba53534177b.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_168e25aded8844c4098a3e13fa36e868c505a615b.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_104a2fe5be94e7d900c6368f6cc24d20f85d0012f.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/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://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/writing-about-people",
+  "lastUpdated": "2026-08-19",
+  "status": "published"
+}

package/guidelines/language-and-inclusivity-writing-with-visuals.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/language-and-inclusivity-writing-with-visuals.json",
+  "name": "language-and-inclusivity-writing-with-visuals",
+  "title": "Writing with visuals",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Writing with visuals" },
+    {
+      "type": "guideline",
+      "content": "Try different ways of organizing information.\n\nOrganize thoughts chronologically, not spatially. If interfaces are organized around time instead of position (e.g., “before” and “after” instead of “above” and “below”), it alleviates a major pain point for people with visual impairments who rely on screen readers (audio or braille devices) or magnifiers (for example, an interface may be too zoomed-in for it to be apparent that person is in a modal). Doing this also avoids confusion for people with learning disabilities that make it hard to understand directional language. Create content that can be presented in different ways without losing information or structure, sometimes called “modular content.” Perhaps the layout can be simplified, or the order of content can be switched around. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1c1dc4df379f4d4000b519df4a8df3be19adff5d4.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1f6fc9881e0884994e76ad4b606dced6c500a3f89.png?width=750&format=png&optimize=medium) Preferred Avoid This article describes linking in more detail.Click here to learn more about linking. Learn how to crop images Take this hands-on tutorial now. [ Start ] This is modular content; all the content pieces could stand alone or be rearranged. Ready to learn? Or are you ready to dig in? How about both? [ Start tutorial / Go back ] This is more traditional content; the content pieces depend on each other in a certain order to make sense. Update your information (step 1 of 3)Confirm your information"
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid directional language.\n\nOrganize interfaces around time (chronologically) instead of position (spatially) to ensure that you don’t use directional language to describe how to accomplish a task. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_110ca6da0114667ec40138d1c6ae7ba8c33b69950.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_162ff93be0b03bb073e96c26e715cf375769de4ce.png?width=750&format=png&optimize=medium) Preferred Avoid FirstAboveNextBelowIn the menu barOn the leftFinallyAt the bottom"
+    },
+    {
+      "type": "guideline",
+      "content": "Prevent errors before correcting them.\n\nHelp people avoid and correct mistakes by writing in a predictable and consistent way, and make screens look and act the way people expect. Consistent navigation and identification of components across products and surfaces will aid in this. Especially in forms, label and instruct sufficiently. If an error occurs, describe the problem in text without relying on icons or colors alone. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_11376671b0abc29eb2039aa53218afc5aa9b279c4.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid naming things.\n\nEvery new name is a new concept that a person must learn, which increases cognitive load. But when naming is unavoidable, be consistent. Name actions across experiences and products the same, or at least predictably. Describe and define the name before mentioning it in UI content."
+    },
+    {
+      "type": "guideline",
+      "content": "Describe what’s happening.\n\nProvide titles to describe a situation, such as in coach marks or a stepped flow, and keep them consistent within the same situation. This helps all people navigate, find content, and determine where they are. If visual content is time-based media, like a tutorial video, text provides descriptive identification and ideally offers an alternative to the visual, such as a transcript, closed captioning, or a step-by-step written guide."
+    },
+    {
+      "type": "guideline",
+      "content": "Write about actions and their effects.\n\nTake a step back to think about the interaction you’re writing about. Then, write about what controls and buttons do, not what they look like, in the interaction. Control type (e.g., “button” or “slider”) is coded separately, so screen readers will already pick up what it’s called. Give each a name that describes its purpose. Focus your attention on results and UI words, not how people should physically interact with a control. Each person’s accessibility tech will describe the correct interaction for them. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_191b4e8a624329ecde87f67128da614a530e691f4.png?width=750&format=png&optimize=medium)Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_128dece0b359eaaed84cdf64e529620307e27c8ff.png?width=750&format=png&optimize=medium)Write about the effect (“make changes with the Edit tool”) rather than the interaction (“click to edit”). Preferred Avoid Enter emailType email addressSaveThe \"Save\" buttonZoom inPinch the trackpadCancelCloseOn/offSwitch/toggle, activateMenuSide drawerEditThe pencil iconSelect, go toClick, tap"
+    },
+    {
+      "type": "guideline",
+      "content": "​​Don’t rely only on color or icons.\n\nAdding words to an interface is better than relying on color or icons as the only way of conveying information, indicating an action, prompting a response, or distinguishing a visual element. If you use links in text, make the purpose of each link clear from the link text alone. Screen readers usually inform the reader if a word is a hyperlink, so the words “click here” or “link” get in the way. Additionally, screen readers can’t differentiate between the many times “click here” can appear in one view. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_12b83bac79712fd24e6b1888a6fcd5f6ebd6a1bb6.png?width=750&format=png&optimize=medium)Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1e2ca96cc7adf7e30732122a616f952c3acfd8f5f.png?width=750&format=png&optimize=medium)Add error message text to the interface, rather than relying only on a red outline to communicate an error state."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t rely on visuals alone to communicate.\n\nThe visual metaphors of emoji and icons can have a wide variety of interpretations, especially across cultures. Describe the interface in terms of actions and tasks, not component color or visual design. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_17c3e920a6440c98e2cb7c5e4b31f20f3cac0b7df.png?width=750&format=png&optimize=medium) Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1731ab8abc7bbac6a3f64aef590d145e560ff877f.png?width=750&format=png&optimize=medium) Preferred Avoid Secure site🔒Saved to the cloud☁️The number you entered isn’t in our system.❌The Go buttonThe green button"
+    },
+    {
+      "type": "guideline",
+      "content": "Provide alt text.\n\nAlt text — short strings that describe the function of interface elements and describe images — improves understanding and clarity for everybody using a product, not only people using assistive technology. For example, if you were to hover your mouse over the “search” magnifying glass icon on Adobe.com, it would reveal the alt text “Search Adobe.com.” This provides more context about the available action. Alt text for any non-text content allows it to be changed into other forms that people need, such as large print, braille, speech, symbols, or simpler language. It makes visual cues, like icons and images, legible to people with low vision using assisted services (e.g., Voiceover on iOS, Talkback on Android ). Talk with engineers about providing alt text, hints, and traits for components. For example, an icon-only button that doesn’t have a text label needs to still communicate its purpose using text. Spectrum’s documentation has detailed guidance about building accessible interfaces, and the W3C also has a list of resources and tutorials about alt text that offer a more comprehensive introduction. For alt text for images, view our writing guide. Preferred Avoid alt=”Chicago Bulls player Michael Jordan making his first of 38 points against the Utah Jazz on their home court, despite widespread speculation that he had the flu.”alt=”Basketball player making a basket at an arena”alt=”Animation showing how to use the touch shortcut. Take the tutorial for more info.”alt=”Animation showing the touch shortcut used with the shape tool to create a shape with a constrained aspect ratio”"
+    },
+    {
+      "type": "guideline",
+      "content": "Photographs and stock images.\n\nIn general, just speak to what something is. One way to approach this is to imagine that you’re describing the image to someone over the phone. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_136dd5563938c3103ef68fb95063e79458395957e.png?width=750&format=png&optimize=medium)Tibetan monk wearing a red robe walking across a wooden bridge covered with multicolor prayer flags."
+    },
+    {
+      "type": "guideline",
+      "content": "Images that show or function as UI.\n\nMention all parts of the UI and what the content is for each part, if applicable. Write in the order of how a screen reader would read the components in the actual UI. When an image functions as a UI component — for example, an icon-only button or an image being used as a button — use verbs to describe the action instead of the appearance of the iconography. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_1a22871ce2657f1384c883cbc027b73ecbf320c7c.png?width=750&format=png&optimize=medium)First example: 2 meters showing positive status. First meter labeled Tutorials completed, 2 of 8. Second meter labeled Storage space, 15%. Second example: Send message (Not: “paper airplane in motion”)."
+    },
+    {
+      "type": "guideline",
+      "content": "Images that describe usage notes or guidelines.\n\nDescribe any specific examples of how to apply (or not to apply) a concept or guideline that has been outlined in other text. Be sure to include any text that’s part of the image. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/media_10dd8f51f80783ba79e4642cea18ff806d07ced9e.png?width=750&format=png&optimize=medium)3 key examples showing correct usage of writing in simple tense. She ran for president. He writes great poetry. Carmen will make the poster."
+    }
+  ],
+  "sourceUrl": "https://preview.spectrum.adobe.com/foundations/content-design/language-and-inclusivity/writing-with-visuals",
+  "lastUpdated": "2026-08-19",
+  "status": "published"
+}

package/guidelines/layout-and-structure-containers.json

@@ -7,30 +7,30 @@
   "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.\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. Examples of containers: two cards with different sizes and layout options, and a select box."
+      "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.\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. Image: UI components showing examples of card layouts for a Photoshop photo editing course on the left with multiple card variations, and a select box component example on the right featuring a checkbox and favorites heart icon. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/media_1daffa98ca15b1299210db1dd829d7377de85e65a.png?width=750&format=png&optimize=medium)Examples of containers: two cards with different sizes and layout options, and a select box."
     },
     {
       "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."
+      "content": "All containers share a set of defined styles. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/media_130061659941d2e3f73cf5a50fb9df8aeb95ca596.png?width=750&format=png&optimize=medium) 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."
+      "content": "Example.\n\nThis medium card uses spacing-300 for internal padding. Image: Card component example with checkbox, abstract wavy image, title and description text, showing spacing-300 (16px) padding measurement indicated by dotted line on the left. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/media_13224b595dae476332958fef768371a29adbc1572.png?width=750&format=png&optimize=medium)"
     },
     {
       "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."
+      "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. Image: Three app product cards displaying Acrobat, Photography, and All apps with icons, pricing placeholders, and Buy now buttons, with the All apps card highlighted by a \"Best value\" badge. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/media_18c340f95534d724d0566c68fa959d8cc3bf5668e.png?width=750&format=png&optimize=medium)"
     },
     {
       "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. Emphasized, default Emphasized, hover Dragged"
+      "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. Image: Unlabeled image (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/media_1d5c23228ef95a1f5def853200c19be7fd89b487e.png?width=750&format=png&optimize=medium) Emphasized, default Emphasized, hover Dragged"
     },
     {
       "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."
+      "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. Image: Adobe Firefly app interface showing left sidebar with navigation menu items (Home, Files, Brands, Discover, Schedule, Learn, Plugins) and a Create button, plus top header with search bar and utility icons. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/media_16b19bf7867ae4d830240dad00019054f87d38fb8.png?width=750&format=png&optimize=medium)Example of an app frame with a side navigation."
     }
   ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/layout-and-structure/containers",
+  "sourceUrl": "https://preview.spectrum.adobe.com/foundations/layout-and-structure/containers",
   "lastUpdated": "2026-09-11",
   "status": "published",
   "tags": [

package/guidelines/layout-and-structure-spacing-overview.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/layout-and-structure-spacing-overview.json",
+  "name": "layout-and-structure-spacing-overview",
+  "title": "Spacing",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Spacing" },
+    {
+      "type": "guideline",
+      "content": "Image: Stylized 3D icon of a pentagon shape made of glowing green connected nodes and lines, like a graph or network diagram, on a soft white background. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_1c4326bd9edb77f5d2a52d5aa0e940ddcc9550aa8.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Image: Stylized 3D icon of four rounded outline squares of varying sizes arranged in a 2x2 grid, in a blue-purple gradient, resembling an app grid or dashboard icon. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_184d3e0ac92561baea450f5c37769314753e05828.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Image: Stylized 3D icon of an eye with a purple-to-pink gradient, featuring a simplified almond-shaped outline and a comma-shaped iris, on a soft white background. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_1235ef29d70ad3b98566f79b372b39bd4dc8cf5e7.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Relational.\n\nEvery spacing decision carries meaning. Proximity communicates what belongs together, what is separate, and how an interface is organized."
+    },
+    {
+      "type": "guideline",
+      "content": "Proportional.\n\nNot all elements grow at the same rate. Spectrum uses distinct spacing scales, each tuned to the elements they serve. This keeps values consistent and harmonious across all sizes and contexts."
+    },
+    {
+      "type": "guideline",
+      "content": "Perceptual.\n\nSpectrum's spacing values are based on visual perception. They are designed to support accurate visual interpretation and maintain consistent relationships between interface elements across different contexts."
+    },
+    { "type": "guideline", "content": "Relationships" },
+    {
+      "type": "guideline",
+      "content": "Relationships.\n\nCloser elements are more associated. Distant elements are more independent. Image: Diagram showing a list of content cards grouped by relevance: the top two cards are bracketed and labeled \"More related,\" while all three cards together are bracketed and labeled \"Less related\" on the right side. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_160a34223f929bf2e94eee1cb1d58d7ec90ec86a8.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Boundaries.\n\nConsistent proximity within a group signals that all members are equally related. Image: Diagram showing two identical pairs of content cards, each pair enclosed in a dashed pink box, illustrating a repeated grouping structure. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_1201af3d7c478557df34557c19dab71dc46fd9ad8.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Structure.\n\nThe overall distribution of space shows how content is organized within a layout. Image: Grayscale wireframe mockup of an application interface showing a top navigation bar with tabs, a left sidebar with icon buttons, and a right panel with four labeled sliders and a dropdown menu. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_17a7999c3c47bf695711fccc10e0799cbd6b1957a.png?width=750&format=png&optimize=medium) These three things are connected. Change one, and the others shift too. Spacing decisions are not visual alone, but rather they are structural and meaningful. Spacing also shapes how an interface feels. Negative space (the open areas between and around elements) creates a sense of calm and helps people focus on what matters. It's one of the most effective ways to create visual balance and direct user attention within a layout. Image: Grayscale wireframe mockup of a webpage or app interface with a top navigation bar, a profile icon and menu tabs, a left sidebar list, and a highlighted content panel with text lines and two buttons. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_11265bfff799dcff670349049460f288b6195ee05.png?width=750&format=png&optimize=medium)Less negative space creates clutter and increases cognitive load. Image: Diagram showing two identical pairs of content cards, each pair enclosed in a dashed pink box, illustrating a repeated grouping structure. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_1770c6aefbbcb0ef043022106ea246562c4382558.png?width=750&format=png&optimize=medium)More negative space creates a calm, focused experience."
+    },
+    {
+      "type": "guideline",
+      "content": "Jump to.\n\nImage: Stylized 3D icon of a rounded square divided into three panels—one wide top panel and two smaller bottom panels—in a purple gradient, representing a dashboard or layout structure. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_1caf3f715f3bcde815b184c56914ddf0808a00ffd.png?width=750&format=png&optimize=medium) Layout spacing Layout spacing Image: Stylized 3D icon of two toggle switches stacked vertically in a blue gradient—the top toggle shown in the off position and the bottom toggle shown in the on position. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_164937f2c0285c78dd62f96e1e82519a58de2a3e6.png?width=750&format=png&optimize=medium) Component spacing Component spacing"
+    }
+  ],
+  "sourceUrl": "https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/overview",
+  "lastUpdated": "2026-08-13",
+  "status": "published",
+  "tags": [
+    "Spacing",
+    "Proximity",
+    "Negative space",
+    "Layout spacing",
+    "Component spacing",
+    "Relational",
+    "Perceptual",
+    "Boundaries",
+    "Structure",
+    "Cognitive load"
+  ]
+}

package/guidelines/layout-spacing.json

@@ -8,22 +8,22 @@
     { "type": "purpose", "content": "Layout spacing" },
     {
       "type": "guideline",
-      "content": "Layout spacing governs object relationships, such as the spacing between components, patterns, and regions of a UI. It’s implemented through global tokens, which follow a geometric progression with values that round to familiar numbers: 2, 4, 8, 16. If you're used to an 8 px grid, these will feel recognizable. The scale provides consistent perceptual difference between adjacent values across its full range."
+      "content": "Layout spacing governs object relationships, such as the spacing between components, patterns, and regions of a UI. It’s implemented through global tokens, which follow a geometric progression with values that round to familiar numbers: 2, 4, 8, 16. If you're used to an 8 px grid, these will feel recognizable. The scale provides consistent perceptual difference between adjacent values across its full range. Image: Scale of gray squares increasing in size from left to right, labeled with values 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 80, and 96, with a dotted diagonal line showing the growth curve. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_115ea12e4cac857c4b8d7fccac0293a81ae114447.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "Global tokens govern object relationships in a layout. They create and distinguish the relationships between the components that make up a product UI. Smaller values create tighter relationships. Larger values create more visual independence. The choice should reflect the actual relationship between the objects being spaced."
+      "content": "Global tokens govern object relationships in a layout. They create and distinguish the relationships between the components that make up a product UI. Smaller values create tighter relationships. Larger values create more visual independence. The choice should reflect the actual relationship between the objects being spaced. Image: Screenshot of the Adobe GenStudio interface showing a top navigation bar with a search field, a green table icon with a loading placeholder bar, and a floating toolbar with icons for image approval, comment, \"Cr,\" and a highlighted gold icon; two callouts label the horizontal bands as \"spacing-100\" and \"spacing-250.\" (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_1a16efb69dea68171c4c4dcbcff449b7c21eaa2ad.png?width=750&format=png&optimize=medium)"
     },
     {
       "type": "guideline",
-      "content": "A common approach to spacing is to pick a base unit and build all spacing values from its multiples, such as 8, 16, 24, 32. These values are familiar and easy to remember, which is part of their appeal. This approach is called a linear progression. Linear progressions like this work well in many situations, but have two limitations. First, spacing needs to grow with the elements around it. A 4 px gap between an icon and label looks right in a small component, but as the component scales up, the nearest grid values (4 px or 8 px) no longer fit the relationship correctly. Second, linear scales lose differentiation at larger values. The difference between 4 px and 8 px is obvious. The difference between 72 px and 80 px is almost imperceptible. Both of these limitations come down to the same underlying cause: human perception doesn't measure space in fixed increments. Spectrum's spacing system is built around geometric progressions and semantic tokens to address this directly. The next page explains how."
+      "content": "A common approach to spacing is to pick a base unit and build all spacing values from its multiples, such as 8, 16, 24, 32. These values are familiar and easy to remember, which is part of their appeal. This approach is called a linear progression. Linear progressions like this work well in many situations, but have two limitations. First, spacing needs to grow with the elements around it. A 4 px gap between an icon and label looks right in a small component, but as the component scales up, the nearest grid values (4 px or 8 px) no longer fit the relationship correctly. Second, linear scales lose differentiation at larger values. The difference between 4 px and 8 px is obvious. The difference between 72 px and 80 px is almost imperceptible. Image: Scale of gray squares increasing in size from left to right beneath a pink upward curve, with a bracket over the first two squares labeled \"100% increase\" and a bracket over the last two squares labeled \"11% increase,\" illustrating a decelerating growth rate. (source: https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/media_10c237cd90839604eca53c6ac170d7cf2f3812435.png?width=750&format=png&optimize=medium)Both of these limitations come down to the same underlying cause: human perception doesn't measure space in fixed increments. Spectrum's spacing system is built around geometric progressions and semantic tokens to address this directly. The next page explains how."
     },
     {
       "type": "guideline",
       "content": "Use global tokens for layout spacing. TokenValuespacing-251pxspacing-502pxspacing-754pxspacing-856pxspacing-1008pxspacing-20012pxspacing-30016pxspacing-35020pxspacing-40024pxspacing-50032pxspacing-60040pxspacing-70048pxspacing-75056pxspacing-80064pxspacing-90080pxspacing-100096px"
     }
   ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/layout-and-structure/spacing/layout-spacing",
+  "sourceUrl": "https://preview.spectrum.adobe.com/foundations/layout-and-structure/spacing/layout-spacing",
   "lastUpdated": "2026-08-13",
   "status": "published",
   "tags": [