@adobe/spectrum-design-data 3.3.0 → 3.4.0

package/guidelines/writing-with-visuals.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/writing-with-visuals.json",
+  "name": "writing-with-visuals",
+  "title": "Writing with visuals",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Writing with visuals" },
+    {
+      "type": "guideline",
+      "content": "UX writing never stands alone. Think and write as if visuals don’t exist, and never rely on images as the sole way to communicate a concept. Advocate for images that show more types of people and content that speaks to broader groups. Be especially mindful of what’s portrayed as typical. For example, when the text refers to “experts,” are the accompanying images only of white people? When the text refers to “learning, building on skills, educating,” are the images only of people of color?"
+    },
+    {
+      "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: Key example showing the correct usage of organizing your writing for comprehension. Heading, Learn how to crop images. Description, take this hands-on tutorial now. Call-to-action button, label Start. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1c1dc4df379f4d4000b519df4a8df3be19adff5d4.png?width=750&format=png&optimize=medium) Image: Key example showing the incorrect usage of organizing your writing for comprehension. Heading, Ready to learn? Description, Or are you ready to dig in? How about both? Call-to-action button, label Start tutorial. Secondary button, label Go back. (source: https://spectrum.adobe.com/content/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: An example of correct usage. In the menu bar. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_110ca6da0114667ec40138d1c6ae7ba8c33b69950.png?width=750&format=png&optimize=medium) Image: An example of correct usage. On the left. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_162ff93be0b03bb073e96c26e715cf375769de4ce.png?width=750&format=png&optimize=medium) Preferred Avoid First Above Next Below In the menu bar On the left Finally At 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: Key example of correctly preventing errors. Required text field showing help text. Label, Password. Help text description, Password must be at least 8 characters. (source: https://spectrum.adobe.com/content/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: Key example of writing about an action and its effect. Correct usage in a coach mark. Title, Edit. Step 1 of 14. Description, You can make changes to your post at any time with the Edit tool. Primary button, label Next. Secondary button, label Skip tour. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_191b4e8a624329ecde87f67128da614a530e691f4.png?width=750&format=png&optimize=medium) Image: Key example of writing about an action and its effect. Incorrect usage in a coach mark. Title, Edit. Step 1 of 14. Description, Click to edit. Primary button, label Next. Secondary button, label Skip tour. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_128dece0b359eaaed84cdf64e529620307e27c8ff.png?width=750&format=png&optimize=medium) Preferred Avoid Enter email Type email address Save The \"Save\" button Zoom in Pinch the trackpad Cancel Close On/off Switch/toggle, activate Menu Side drawer Edit The pencil icon Select, go to Click, 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: Key example of correct usage of adding words to an interface to supplement color and icons. Required text field in an error state with red outline and error icon, label Password. Error message, Create a password with at least 8 characters. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_12b83bac79712fd24e6b1888a6fcd5f6ebd6a1bb6.png?width=750&format=png&optimize=medium) Image: Key example of incorrect usage of adding words to an interface to supplement color and icons. Required text field in an error state with red outline and error icon, label Password. No error message text. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1e2ca96cc7adf7e30732122a616f952c3acfd8f5f.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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: An example of correct usage. Secure site. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_17c3e920a6440c98e2cb7c5e4b31f20f3cac0b7df.png?width=750&format=png&optimize=medium) Image: An example of incorrect usage. A lock icon. (source: https://spectrum.adobe.com/content/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 button The 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": "Some images work in partnership with text to communicate, while other images are more decorative. Determining if an image needs alt text depends on the presence or absence of any supplementary context that text may be providing elsewhere in an experience. A good place to start when considering if an image needs alt text is to consider if the text prefacing or following the image is descriptive enough of what the image is communicating on its own. If the answer is yes, then alt text likely isn’t necessary. Alt text in addition to other text that’s already communicating the same thing can be repetitive and redundant. Any image that’s conveying information on its own, independent of any accompanying text, needs alt text. It’s also needed for images that include language that would need to be localized. It’s usually not needed for images that are purely decorative, or for images that are providing information that is already communicated effectively elsewhere in an experience. If you’ve determined that an image needs alt text, start by thinking about what that image is supposed to be communicating. Then, follow these writing tips: Be additive. You shouldn’t have to repeat the same information as an image’s accompanying text. Write in a way that gives context that would be lost if someone can’t view the image. Use active voice. Active voice is simpler, clearer, and more conversational, which makes alt text sound more human. Use consistent tone and terminology. Alt text is another part of your product’s communication, so ensure that it matches its tone and uses the same words. Don’t use any jargon that isn’t first introduced elsewhere. Consider localization. Writing in a succinct, straightforward way helps ensure that alt text can be properly translated. Avoid writing “image of.” With screen readers, it’s apparent that an element is an image, so saying that something is an “image of” something can be redundant. If an image is a visualization of information, such as a chart, diagram, or data visualization, describe those using phrases like “chart of,” “diagram of,” or “data visualization of.” Use proper grammar and mechanics. Start alt text with a capital letter, and end with a period. Even though alt text is not often in complete sentences, doing this helps a screen reader to read the content with a natural inflection. Avoid using abbreviations of dates, times, or measurements and write out the full word, so a screen reader won’t just spell out an abbreviation. Here’s some examples of how to write alt text, all from the Spectrum website or components:"
+    },
+    {
+      "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: Tibetan monk wearing a red robe walking across a bridge covered with multicolor prayer flags. (source: https://spectrum.adobe.com/content/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: Two examples of images of UI from the Spectrum website. Meters and an icon-only button. (source: https://spectrum.adobe.com/content/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: Key example showing how to use simple tenses. Three examples of correct usage. She ran for president. He writes great poetry. Carmen will make the poster. (source: https://spectrum.adobe.com/content/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://spectrum.adobe.com/content/language-and-inclusivity/writing-with-visuals",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "writing",
+    "inclusive imagery",
+    "modular content",
+    "directional language",
+    "screen readers",
+    "consistent navigation",
+    "error prevention"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spectrum-design-data",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Spectrum design tokens in cascade format — the canonical source of truth for @adobe/spectrum-tokens",
   "type": "module",
   "repository": {
@@ -62,7 +62,7 @@
   "devDependencies": {
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
-    "@adobe/design-data-spec": "4.4.0"
+    "@adobe/design-data-spec": "4.5.0"
   },
   "scripts": {}
 }

package/tokens/layout.tokens.json

@@ -267,6 +267,24 @@
     "description": "Spacing between child elements for banner components",
     "conceptId": "43c9f50a-f664-4319-a502-51734106ec05"
   },
+  {
+    "name": {
+      "property": "gap",
+      "structure": "banner",
+      "orientation": "horizontal",
+      "legacyKey": "gap-horizontal"
+    },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
+    "$ref": "ec565065-0820-460f-9a1b-b81911c48cb5",
+    "uuid": "88c10a5d-9495-44b2-8b03-e9283c79144b",
+    "description": "Spacing between child elements for banner components",
+    "lifecycle": {
+      "deprecatedIn": "3.3.0",
+      "deprecatedComment": "Renamed to include the banner structure prefix; use banner-gap-horizontal instead.",
+      "replacedBy": "c0571c46-5946-4896-bcbf-270560de5385"
+    },
+    "conceptId": "2ed53cd0-afb2-4b41-abe8-357b6984d858"
+  },
   {
     "name": {
       "property": "gap",
@@ -279,6 +297,24 @@
     "description": "Spacing between child elements for banner components",
     "conceptId": "e488914b-889c-4455-8dea-5446848d6261"
   },
+  {
+    "name": {
+      "property": "gap",
+      "structure": "banner",
+      "orientation": "vertical",
+      "legacyKey": "gap-vertical"
+    },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
+    "$ref": "507c0b4a-9dbc-4242-89fd-5efc4d1c35b9",
+    "uuid": "952a4750-63b2-458e-81b1-bf00cb064934",
+    "description": "Spacing between child elements for banner components",
+    "lifecycle": {
+      "deprecatedIn": "3.3.0",
+      "deprecatedComment": "Renamed to include the banner structure prefix; use banner-gap-vertical instead.",
+      "replacedBy": "312ebac2-32a0-47a8-9c4e-e366b2232228"
+    },
+    "conceptId": "8e59c7c8-8264-4b14-9554-6df62e0113be"
+  },
   {
     "name": {
       "property": "padding-horizontal",
@@ -290,6 +326,23 @@
     "description": "Horizontal internal spacing for banner components",
     "conceptId": "fe991478-b395-4870-938b-a8a09f721c02"
   },
+  {
+    "name": {
+      "property": "padding-horizontal",
+      "structure": "banner",
+      "legacyKey": "padding-horizontal"
+    },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
+    "$ref": "ba632ede-84a7-4e56-91ef-8143b2499452",
+    "uuid": "f0749dc3-1649-4e6f-957e-c2194e191c88",
+    "description": "Horizontal internal spacing for banner components",
+    "lifecycle": {
+      "deprecatedIn": "3.3.0",
+      "deprecatedComment": "Renamed to include the banner structure prefix; use banner-padding-horizontal instead.",
+      "replacedBy": "eb386242-21c6-437b-8125-e6d4394dd9c5"
+    },
+    "conceptId": "a0789399-daee-4248-b5b1-d36600560eea"
+  },
   {
     "name": {
       "property": "padding-horizontal",
@@ -314,6 +367,23 @@
     "description": "Vertical internal spacing for banner components",
     "conceptId": "6e2370f2-ecbc-4ca9-912a-db39726761d1"
   },
+  {
+    "name": {
+      "property": "padding-vertical",
+      "structure": "banner",
+      "legacyKey": "padding-vertical"
+    },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
+    "$ref": "79fca32b-214b-4760-9d3a-28f4d1bdf86f",
+    "uuid": "9ae57860-2109-4f79-9230-7616e9898fd9",
+    "description": "Vertical internal spacing for banner components",
+    "lifecycle": {
+      "deprecatedIn": "3.3.0",
+      "deprecatedComment": "Renamed to include the banner structure prefix; use banner-padding-vertical instead.",
+      "replacedBy": "64fa4ab7-be93-4420-8cdc-a6ef91499852"
+    },
+    "conceptId": "58fc7a18-a8e3-464b-a282-bc6303a6f063"
+  },
   {
     "name": {
       "property": "gap",
@@ -5948,6 +6018,24 @@
     "description": "Spacing between child elements for list structures (regular density)",
     "conceptId": "3a663b76-4b9c-41bc-833e-5eb7f346fd4c"
   },
+  {
+    "name": {
+      "property": "gap",
+      "structure": "list",
+      "weight": "regular",
+      "legacyKey": "gap-regular"
+    },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
+    "$ref": "576a60a3-ca80-46c5-a066-ba7b6197decd",
+    "uuid": "c2408389-1e7e-4aae-8a49-d8b8233102c7",
+    "description": "Spacing between child elements for list structures (regular density)",
+    "lifecycle": {
+      "deprecatedIn": "3.3.0",
+      "deprecatedComment": "Renamed to include the list structure prefix; use list-gap-regular instead.",
+      "replacedBy": "b7e1af59-753e-4059-8f46-8d862f631ad8"
+    },
+    "conceptId": "ef320d25-625e-404c-8b69-8958ef42223c"
+  },
   {
     "name": {
       "property": "gap",