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

package/guidelines/writing-for-onboarding.json

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

package/guidelines/writing-for-readability.json

@@ -8,15 +8,27 @@
     { "type": "purpose", "content": "Writing for readability" },
     {
       "type": "guideline",
-      "content": "Choose words consciously.\n\nMost common nouns and actions have synonyms that can add unnecessary complexity. Use words that would be at a 6th-grade reading level. Image: An example showing the correct usage. Help. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_1844b8b156b2f87131aae2d756bceb3ffe1cf0837.png?width=750&format=png&optimize=medium)Image: An example showing the incorrect usage. Assist. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_16067fca3f35f7faad8d77ba7015cfde586c2a7fc.png?width=750&format=png&optimize=medium) Preferred Avoid BuyPurchaseHelpAssistAboutApproximatelyLikeSuch as"
+      "content": "Writing for a 6th-grade reading level on the Flesch-Kincaid readability scale includes more people, not just those with disabilities that affect comprehension. Write with short sentences. Avoid adverbs and adjectives. Use simple verb tenses (past, present, future) and active voice. The Hemingway app is a useful tool for checking readability; Adobe Design’s Content Strategy team also uses Readable. Preferred Avoid Why We exported the file. Now you can open it in Illustrator. This file has been exported successfully to be opened in one of our other awesome products, Adobe Illustrator. Sentence length: 2 sentences at 4 and 7 words vs. 1 sentence at 18 words. “Exported” is simple past tense. “Has been exported” is past perfect tense. “Can open” is active voice. “To be opened” is passive voice. “Successfully” is an unnecessary adverb. “Awesome” is an unnecessary adjective. Flesch-Kincaid grade level: 4.8 vs. 13.1 (Readability scores from Readable) People using screen readers can hear 25 syllables per second, while folks at a 6th-grade reading level can read 3 words per second. Use this to estimate the amount of time it would take someone to read a piece of text."
     },
     {
       "type": "guideline",
-      "content": "Avoid internal jargon without explaining what it means.\n\nPut yourself in the mindset of someone who's new to our products, and new to the industry where our products are used. Do they understand the jargon we use every day? Are we giving enough context for them to understand? Image: An example showing the correct usage. Please accept the Terms of Service before continuing. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_1af0b6d0d56faae5d7362957f0a00ef3c496364fe.png?width=750&format=png&optimize=medium)Image: An example showing the incorrect usage. There was a RAISE without a handler. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_184c1f97b56242ff6177372a5393d55756084dc77.png?width=750&format=png&optimize=medium) Preferred Avoid Creative Cloud FilesCC FilesXD cloud documents, a new way to collaborate on any deviceIntroducing XD cloud docs!Please accept the Terms of Service before continuing.There was a RAISE without a handler."
+      "content": "Choose words consciously.\n\nMost common nouns and actions have synonyms that can add unnecessary complexity. Use words that would be at a 6th-grade reading level. Image: An example showing the correct usage. Help. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1844b8b156b2f87131aae2d756bceb3ffe1cf0837.png?width=750&format=png&optimize=medium) Image: An example showing the incorrect usage. Assist. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_16067fca3f35f7faad8d77ba7015cfde586c2a7fc.png?width=750&format=png&optimize=medium) Preferred Avoid Buy Purchase Help Assist About Approximately Like Such as"
     },
     {
       "type": "guideline",
-      "content": "Avoid colloquial language and slang.\n\nSlang and colloquialisms don’t make sense to all generations. Avoid ageism by using plain, clear language. Image: An example showing the correct usage. Learn more. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_11fde3bc1f3c1c5efff6dc951b5f248247ccd60de.png?width=750&format=png&optimize=medium)Image: An example showing the incorrect usage. Get the deetz. (source: https://preview.spectrum.adobe.com/content/language-and-inclusivity/media_1d554b7ba72764b3114ab6b0e3007bf466ae485ca.png?width=750&format=png&optimize=medium) Preferred Avoid Select any that applyChoose whatever blows your hair backAgree to terms and conditionsIt be like that sometimesLearn moreGet the deetz"
+      "content": "Imagine that you are having a friendly conversation with your audience to provide them with helpful information. Using jargon, internal-only, or corporate language in UX writing assumes that people outside of an organization know what it means — even when people internally may not even know what it means. Avoid internal language and jargon. If you have to use it, explain the point in clear language and provide in-line context on first reference. Avoid idioms, especially those with roots intended to belittle non-native English speakers, such as “long time no see.” Don’t rely on symbols or emoji since these rely on cultural references, making them inherently exclusive. Emoji also don’t translate well, so avoiding them will save you time and effort in having to write separate strings for localization."
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid internal jargon without explaining what it means.\n\nPut yourself in the mindset of someone who's new to our products, and new to the industry where our products are used. Do they understand the jargon we use every day? Are we giving enough context for them to understand? Image: An example showing the correct usage. Please accept the Terms of Service before continuing. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1af0b6d0d56faae5d7362957f0a00ef3c496364fe.png?width=750&format=png&optimize=medium) Image: An example showing the incorrect usage. There was a RAISE without a handler. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_184c1f97b56242ff6177372a5393d55756084dc77.png?width=750&format=png&optimize=medium) Preferred Avoid Creative Cloud Files CC Files XD cloud documents, a new way to collaborate on any device Introducing XD cloud docs! Please accept the Terms of Service before continuing. There was a RAISE without a handler."
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid colloquial language and slang.\n\nSlang and colloquialisms don’t make sense to all generations. Avoid ageism by using plain, clear language. Image: An example showing the correct usage. Learn more. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_11fde3bc1f3c1c5efff6dc951b5f248247ccd60de.png?width=750&format=png&optimize=medium) Image: An example showing the incorrect usage. Get the deetz. (source: https://spectrum.adobe.com/content/language-and-inclusivity/media_1d554b7ba72764b3114ab6b0e3007bf466ae485ca.png?width=750&format=png&optimize=medium) Preferred Avoid Select any that apply Choose whatever blows your hair back Agree to terms and conditions It be like that sometimes Learn more Get the deetz"
+    },
+    {
+      "type": "guideline",
+      "content": "Keep the following in mind when you’re writing, to help the greatest number of people understand what you write."
     },
     {
       "type": "guideline",
@@ -32,10 +44,10 @@
     },
     {
       "type": "guideline",
-      "content": "Localization.\n\nExplain branded or technical terms before using them. When using an uncommon abbreviation or acronym, write out the full term on first use and follow it with the shortened version in parentheses. You can also use <abbr> or <acronym> in HTML. Avoid using homonyms (e.g., “bow before the king” vs. “put a bow on it”), or make their meaning clear via context."
+      "content": "Localization.\n\nExplain branded or technical terms before using them. When using an uncommon abbreviation or acronym, write out the full term on first use and follow it with the shortened version in parentheses. You can also use <abbr> or <acronym> in HTML. Avoid using homonyms (e.g., “bow before the king” vs. “put a bow on it”), or make their meaning clear via context."
     }
   ],
-  "sourceUrl": "https://preview.spectrum.adobe.com/content/language-and-inclusivity/writing-for-readability",
+  "sourceUrl": "https://spectrum.adobe.com/content/language-and-inclusivity/writing-for-readability",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [

package/guidelines/writing-with-visuals.json

@@ -8,15 +8,19 @@
     { "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. 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"
+      "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": "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. Preferred Avoid FirstAboveNextBelowIn the menu barOn the leftFinallyAt the bottom"
+      "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": "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."
+      "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",
@@ -28,34 +32,38 @@
     },
     {
       "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. Preferred Avoid Enter emailType email addressSaveThe \"Save\" buttonZoom inPinch the trackpadCancelCloseOn/offSwitch/toggle, activateMenuSide drawerEditThe pencil iconSelect, go toClick, tap"
+      "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 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."
+      "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": "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. Preferred Avoid Secure site🔒Saved to the cloud☁️The number you entered isn’t in our system.❌The Go buttonThe green button"
+      "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": "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”"
+      "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. Tibetan monk wearing a red robe walking across a wooden bridge covered with multicolor prayer flags."
+      "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. 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”)."
+      "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. 3 key examples showing correct usage of writing in simple tense. She ran for president. He writes great poetry. Carmen will make the poster."
+      "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://main--spectrum-hub--adobe.aem.live/content/language-and-inclusivity/writing-with-visuals",
+  "sourceUrl": "https://spectrum.adobe.com/content/language-and-inclusivity/writing-with-visuals",
   "lastUpdated": "2026-09-04",
   "status": "published",
   "tags": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spectrum-design-data",
-  "version": "3.3.0-beta.2",
+  "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.2.0"
+    "@adobe/design-data-spec": "4.5.0"
   },
   "scripts": {}
 }

package/registry/platform-implementations.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "platform-implementation",
+  "description": "Machine-readable ids for platform-manifest implementations (repos or in-monorepo directories that own a Layer 2 platform manifest.json). Distinct from platforms.json, which enumerates device targets (desktop/mobile/web/ios/android) referenced by token names — this registry enumerates concrete implementation projects a manifest's `platform` field may declare (spec/manifest.md#identity-fields). Referencing an id here is a SHOULD, not a MUST: a manifest may declare a `platform` value not yet listed while a new implementation is incubating.",
+  "values": [
+    {
+      "id": "react-spectrum",
+      "label": "React Spectrum",
+      "description": "Adobe's React implementation of Spectrum, incubating its platform manifest at platforms/react-spectrum/ ahead of an eventual hand-off to the React Spectrum team.",
+      "repository": "https://github.com/adobe/react-spectrum"
+    },
+    {
+      "id": "web-components",
+      "label": "Spectrum Web Components",
+      "description": "Adobe's Web Components implementation of Spectrum, incubating its platform manifest at platforms/web-components/ ahead of an eventual hand-off to the Spectrum Web Components team.",
+      "repository": "https://github.com/adobe/spectrum-web-components"
+    },
+    {
+      "id": "ios",
+      "label": "Spectrum iOS",
+      "description": "Adobe's iOS implementation of Spectrum, with its platform manifest already externalized (see epic h890.22).",
+      "repository": "https://github.com/GarthDB/spectrum-ios-design-data"
+    },
+    {
+      "id": "android",
+      "label": "Spectrum Android",
+      "description": "Adobe's Android implementation of Spectrum. No platform manifest exists yet (see epic h890.22.6, follow-up to the iOS work)."
+    }
+  ]
+}