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

package/guidelines/writing-for-onboarding.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/writing-for-onboarding.json",
+  "name": "writing-for-onboarding",
+  "title": "Writing for onboarding",
+  "category": "designing",
+  "documentBlocks": [
+    { "type": "purpose", "content": "Writing for onboarding" },
+    {
+      "type": "guideline",
+      "content": "Onboarding is often used interchangeably with “new user experience,” but this term also refers to the process of introducing information for more experienced users about new products, new features, or new elements. Ongoing user education also falls under onboarding, since every time you teach a person something, you’re onboarding them onto that new concept. A product’s overall onboarding strategy becomes increasingly important over time and is the biggest factor in sustaining its growth and retention. When a product first launches, early adopters are more likely to engage with it and are invested in figuring out how it works. But later in that product’s life when other user groups with different motivations are trying it out, onboarding is a crucial way to maintain interest and ensure continued usage. Ultimately, onboarding is how a promised user experience bridges what is actually delivered. Creating valuable onboarding experiences within a product connects to even earlier communication moments about that product, such as marketing material. Writing for these experiences involves thinking systematically across messaging channels, writing content that accounts for levels of experience and goals, and ensuring that the information complexity of the message fits an appropriate design component. The result shows consistent value through \"a-ha\" moments that retain user interest."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Reflect what your users already know.\n\nAre your target users beginners? Advanced? What do they want to know? How much information can they handle at once?"
+    },
+    {
+      "type": "guideline",
+      "content": "Remember why your users are there.\n\nKeep onboarding top-of-mind as part of a user’s broader goals and experience. For example, the journey for someone using Photoshop to design is different than someone using Photoshop for photography."
+    },
+    {
+      "type": "guideline",
+      "content": "Sequence topics.\n\nChoose a logical order for the steps that will help a user master the subject. This makes it easier to trim or divide educational content when needed. Also, be sure to mention any prerequisites that people may need to know before they begin."
+    },
+    {
+      "type": "guideline",
+      "content": "Focus each tutorial on one tool or technique.\n\nDon’t try to combine too many skills or concepts into a single tutorial. Each tutorial should ideally focus on only one tool or technique. If there are multiple ways to accomplish a task, choose one way to highlight per tutorial."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t overload your users with steps.\n\nThe longer a tutorial is, the more likely a user will begin to disengage. Try to keep tutorials and product tours under 10 steps. If more steps are needed, consider splitting the subject matter into separate units."
+    },
+    {
+      "type": "guideline",
+      "content": "Set accurate expectations.\n\nUse the first step of a tutorial to clarify what a person will leave knowing how to do, how many steps it will take, how much time it usually takes, the actual output, and so on."
+    },
+    {
+      "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 Frame educational content in a lightweight way using language like “try” and “shows you how.”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. Define jargon like “Learn,” then explain what it’s called.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 Use as a standalone proper noun to refer to a UI element, place, and/or collection of content.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 Highlight relevant content or a unique angle before mentioning there’s more available.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} Use “go to” to imply that a user will be leaving their current experience.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 Emphasize what someone can do without leaving their current experience.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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/writing-for-onboarding",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "onboarding",
+    "new user experience",
+    "in-app learning",
+    "first mile",
+    "Adobe Creative Cloud",
+    "Learn framework",
+    "user goals",
+    "tutorials"
+  ]
+}

package/guidelines/writing-for-readability.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/writing-for-readability.json",
+  "name": "writing-for-readability",
+  "title": "Writing for readability",
+  "category": "designing",
+  "documentBlocks": [
+    { "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. Preferred Avoid BuyPurchaseHelpAssistAboutApproximatelyLikeSuch as"
+    },
+    {
+      "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? 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."
+    },
+    {
+      "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. Preferred Avoid Select any that applyChoose whatever blows your hair backAgree to terms and conditionsIt be like that sometimesLearn moreGet the deetz"
+    },
+    {
+      "type": "guideline",
+      "content": "Layout.\n\nLeft-align running text (this will be mirrored along with the UI for right-to-left languages). Full justification of text creates text rivers, or alignment of spaces that creates running gaps through the text. This makes text especially difficult for readers with dyslexia. Avoid switching alignments in a single view. Have line lengths at a maximum of 50-75 characters. Use one column per page."
+    },
+    {
+      "type": "guideline",
+      "content": "Grammar and mechanics.\n\nUse sentence case. Sentence case is easier to read and is more natural and approachable. Never use all caps except for an acronym. Use camel case for hashtags to help screen readers parse the words correctly (e.g., “#CamelCase”)."
+    },
+    {
+      "type": "guideline",
+      "content": "Interactions.\n\nAvoid “clear” and ”reset” actions on forms. Someone could select these by accident and erase a lot of painstaking work. Let people save forms so that they can leave and come back. Provide keywords before or inside links."
+    },
+    {
+      "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."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/language-and-inclusivity/writing-for-readability",
+  "lastUpdated": "2026-09-04",
+  "status": "published",
+  "tags": [
+    "writing",
+    "readability",
+    "plain language",
+    "localization",
+    "internationalization",
+    "UX writing",
+    "jargon",
+    "passive voice",
+    "active voice",
+    "dyslexia accessibility",
+    "Flesch-Kincaid"
+  ]
+}

package/guidelines/writing-with-visuals.json

@@ -0,0 +1,70 @@
+{
+  "$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": "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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."
+    },
+    {
+      "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. Preferred Avoid Enter emailType email addressSaveThe \"Save\" buttonZoom inPinch the trackpadCancelCloseOn/offSwitch/toggle, activateMenuSide drawerEditThe pencil iconSelect, go toClick, tap"
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t rely only on color or icons.\n\nAdding words to an interface is better than relying on color or icons as the only way of conveying information, indicating an action, prompting a response, or distinguishing a visual element. If you use links in text, make the purpose of each link clear from the link text alone. Screen readers usually inform the reader if a word is a hyperlink, so the words “click here” or “link” get in the way. Additionally, screen readers can’t differentiate between the many times “click here” can appear in one view."
+    },
+    {
+      "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"
+    },
+    {
+      "type": "guideline",
+      "content": "Provide alt text.\n\nAlt text — short strings that describe the function of interface elements and describe images — improves understanding and clarity for everybody using a product, not only people using assistive technology. For example, if you were to hover your mouse over the “search” magnifying glass icon on Adobe.com, it would reveal the alt text “Search Adobe.com.” This provides more context about the available action. Alt text for any non-text content allows it to be changed into other forms that people need, such as large print, braille, speech, symbols, or simpler language. It makes visual cues, like icons and images, legible to people with low vision using assisted services (e.g., Voiceover on iOS, Talkback on Android ). Talk with engineers about providing alt text, hints, and traits for components. For example, an icon-only button that doesn’t have a text label needs to still communicate its purpose using text. Spectrum’s documentation has detailed guidance about building accessible interfaces, and the W3C also has a list of resources and tutorials about alt text that offer a more comprehensive introduction. For alt text for images, view our writing guide. Preferred Avoid alt=”Chicago Bulls player Michael Jordan making his first of 38 points against the Utah Jazz on their home court, despite widespread speculation that he had the flu.”alt=”Basketball player making a basket at an arena”alt=”Animation showing how to use the touch shortcut. Take the tutorial for more info.”alt=”Animation showing the touch shortcut used with the shape tool to create a shape with a constrained aspect ratio”"
+    },
+    {
+      "type": "guideline",
+      "content": "Photographs and stock images.\n\nIn general, just speak to what something is. One way to approach this is to imagine that you’re describing the image to someone over the phone. 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”)."
+    },
+    {
+      "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."
+    }
+  ],
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/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.2.3",
+  "version": "3.3.0-beta.1",
   "description": "Spectrum design tokens in cascade format — the canonical source of truth for @adobe/spectrum-tokens",
   "type": "module",
   "repository": {

package/guidelines/app-frame-content-area.json

@@ -1,81 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/app-frame-content-area.json",
-  "name": "app-frame-content-area",
-  "title": "App frame content area (browsing context)",
-  "category": "designing",
-  "documentBlocks": [
-    {
-      "type": "purpose",
-      "content": "App frame content area (browsing context)"
-    },
-    {
-      "type": "guideline",
-      "content": "This layout is suitable when all content is related and unified by the primary purpose of the page. This single section can be subdivided using full-width dividers, or by creating visual groupings of content using proximity and spacing."
-    },
-    {
-      "type": "guideline",
-      "content": "Dividers are useful to separate content when using spacing alone wouldn’t be clear enough to mark the boundaries of distinct areas. Generally, more complex content with a varying alignment of objects will benefit the most from using a divider."
-    },
-    {
-      "type": "guideline",
-      "content": "The top section can also be useful to visually indicate that the content is separate and has additional affordances, such as the ability to be minimized. For example, “welcome” type content might be shown in the top section, and recent files might be shown below."
-    },
-    {
-      "type": "guideline",
-      "content": "When using horizontal sections, the page should scroll as a single unit. Consider other ways to minimize the top section if needed, such as through an additional control to show and hide content."
-    },
-    {
-      "type": "guideline",
-      "content": "The top section of a horizontal layout should be reserved for high-attention marketing messages or quick actions, and it should not be scrollable. Put infinite scrolling and longer content in the bottom section."
-    },
-    {
-      "type": "guideline",
-      "content": "This layout is suitable to separate content that’s not semantically related, and if one of the content areas can be minimized. For example, this might apply for onboarding tutorials, or to include an AI assistant."
-    },
-    {
-      "type": "guideline",
-      "content": "This layout is suitable to separate multiple groups of content that aren’t semantically related. For example, this could show several widgets and distinct marketing messages. This layout can also be useful if a user is able to customize the page."
-    },
-    {
-      "type": "guideline",
-      "content": "Make sure to consider smaller breakpoints and decide how content areas should reflow, hide, or combine. In general, show the most important information at the top, and if possible, then progressively disclose the not-as-important information."
-    },
-    {
-      "type": "guideline",
-      "content": "Backgrounds that use gradients are always placed within the app frame intentionally and with a strategic meaning. They should contribute to the visual hierarchy, not distract from it. And, their colors are directly tied to product brand color palettes."
-    },
-    {
-      "type": "guideline",
-      "content": "For example, on a Home screen, gradient backgrounds might call attention to new AI features in the product. On a Learn screen, gradient backgrounds might call attention to tutorials from new creators. On a Files screen, gradient backgrounds might not be used at all in order to focus attention on asset previews. In any context, consider where you want to draw attention and what you want to highlight for the user, what the user’s intentions might be, and how gradient backgrounds may add or detract from the goals of the page."
-    },
-    {
-      "type": "guideline",
-      "content": "While there isn’t an objective scale for each style, it can be helpful to think about backgrounds in terms of how much attention they draw, on a scale of low-to-high."
-    },
-    {
-      "type": "guideline",
-      "content": "While you may have seen past Spectrum 2 explorations showing gradients as the background in header and navigational areas, they should not be used in that context. This is because gradients that appear in the navigation of every page distract from more important information on the page, clash with other imagery, and might not work for some product segments."
-    },
-    {
-      "type": "guideline",
-      "content": "By using gradients in the content areas as backgrounds instead, there’s more flexibility to direct attention to different content and messages, depending on what’s important in the context of that page or workflow."
-    },
-    {
-      "type": "guideline",
-      "content": "Gradients are used to draw attention to important content and features. They can be used in the background of content areas. Using gradients in more than one content area results in multiple areas competing for attention. This is distracting from the task-at-hand workflows on the page."
-    },
-    {
-      "type": "guideline",
-      "content": "Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them."
-    }
-  ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/app-frame-content-area/",
-  "lastUpdated": "2026-02-02",
-  "status": "published",
-  "tags": ["designing"],
-  "related": [
-    { "ref": "s2-app-frame-side-navigation-browsing-context" },
-    { "ref": "s2-app-frame-creating-bluelines-browsing-context" }
-  ]
-}

package/guidelines/app-frame-creating-bluelines.json

@@ -1,58 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/app-frame-creating-bluelines.json",
-  "name": "app-frame-creating-bluelines",
-  "title": "Creating bluelines (browsing context)",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "Creating bluelines (browsing context)" },
-    {
-      "type": "guideline",
-      "content": "Accessible names vary depending on the content. Accessible names must be defined for controls that don’t have visible text labels."
-    },
-    {
-      "type": "guideline",
-      "content": "Here are some guidelines to keep in mind as you define accessible names in the app frame:"
-    },
-    {
-      "type": "guideline",
-      "content": "Any non-text element in a digital interface with a text label must have a text alternative. Here’s an example of how you might name landmark regions in an app frame:"
-    },
-    {
-      "type": "guideline",
-      "content": "Here’s an example of how you might structure heading annotations for this screen:"
-    },
-    {
-      "type": "guideline",
-      "content": "Keyboard focus order will depend on what controls are available on the page. Here’s an example of how you might define the order in the app frame:"
-    },
-    {
-      "type": "guideline",
-      "content": "Example of correct usage, support for keyboard focus for size navigation. The side navigation width is focusable and resizable by using the left and right arrow keys."
-    },
-    {
-      "type": "guideline",
-      "content": "Example of correct usage, inclusion of a Skip to main content button within the app frame header."
-    },
-    {
-      "type": "guideline",
-      "content": "When properly supported, the F6 key allows keyboard users to navigate through different regions of an application efficiently. Without this support, keyboard-only users have no means to jump to specific areas of the application, resulting in an excessive number of keystrokes to reach their desired goal."
-    },
-    {
-      "type": "guideline",
-      "content": "Here are some key quality factors to consider:"
-    },
-    {
-      "type": "guideline",
-      "content": "For mobile breakpoints, a tray is used to open and close the app frame side navigation. In this example, the keyboard focus order starts at the “Create” button and ends at the close button. Clicking on esc should also close the tray."
-    }
-  ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/app-frame-creating-bluelines/",
-  "lastUpdated": "2026-02-02",
-  "status": "published",
-  "tags": ["designing"],
-  "related": [
-    { "ref": "s2-app-frame-content-area-browsing-context" },
-    { "ref": "brand" }
-  ]
-}

package/guidelines/app-frame-header.json

@@ -1,72 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/app-frame-header.json",
-  "name": "app-frame-header",
-  "title": "App frame header (browsing context)",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "App frame header (browsing context)" },
-    {
-      "type": "guideline",
-      "content": "There are several parts of the header that are consistent across all Adobe products:"
-    },
-    {
-      "type": "guideline",
-      "content": "Shows a hamburger button on the far left of the header. This controls whether the minimized style of the side navigation (partial/full)."
-    },
-    { "type": "guideline", "content": "Shows navigation items in the header." },
-    { "type": "guideline", "content": "Shows a search option in the header." },
-    {
-      "type": "guideline",
-      "content": "Defines the style of the search option that's shown."
-    },
-    {
-      "type": "guideline",
-      "content": "The “skip to main content” button helps improve keyboard navigation by creating a shortcut to the main content of the page. This button is an accessibility feature to allow skipping to the first navigable HTML item."
-    },
-    {
-      "type": "guideline",
-      "content": "Shows an icon to represent the header navigation item."
-    },
-    {
-      "type": "guideline",
-      "content": "The text that is displayed as the label of the header navigation item."
-    },
-    {
-      "type": "guideline",
-      "content": "Presents the header side navigation as selected or not selected."
-    },
-    {
-      "type": "guideline",
-      "content": "Changes the header navigation item to the disabled state."
-    },
-    {
-      "type": "guideline",
-      "content": "Shows a chevron next to the label that indicates an additional menu."
-    },
-    {
-      "type": "guideline",
-      "content": "The text that is displayed as the label of the tooltip."
-    },
-    {
-      "type": "guideline",
-      "content": "As a general rule, only use one call-to-action (CTA) button, aside from any buttons used to log in or log out, as defined in the universal nav. When too many CTAs are shown at once, the messages compete for attention and dilute the ability for a focused attention hierarchy."
-    },
-    {
-      "type": "guideline",
-      "content": "If there are multiple actions, consider combining them into a single menu or use other button types. The button should represent the most important CTA across the product; for example, “Share” and “Get desktop app” are common CTAs."
-    },
-    {
-      "type": "guideline",
-      "content": "Diagram with notes about the app frame header in the editing context. If there’s a menu represented by a hamburger icon, such as the application menu in Creative Cloud, it should be shown to the left of the product logo for continuity with the browsing context. The product name can be hidden in the editing context in order to provide more room for other actions. The height of the header should be the same as in the browsing context (56 px)."
-    }
-  ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/app-frame-header/",
-  "lastUpdated": "2026-02-02",
-  "status": "published",
-  "tags": ["designing"],
-  "related": [
-    { "ref": "s2-app-frame" },
-    { "ref": "s2-app-frame-side-navigation-browsing-context" }
-  ]
-}

package/guidelines/app-frame-side-navigation.json

@@ -1,138 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/app-frame-side-navigation.json",
-  "name": "app-frame-side-navigation",
-  "title": "App frame side navigation (browsing context)",
-  "category": "designing",
-  "documentBlocks": [
-    {
-      "type": "purpose",
-      "content": "App frame side navigation (browsing context)"
-    },
-    {
-      "type": "guideline",
-      "content": "The side navigation is always used in partnership with the header, and never instead of it. When used, the side navigation holds the main categories of product functionality, such as workflow-related navigational items (e.g., Home, Files, Learn, Dashboards). Don’t use this for categorizing marketing pages."
-    },
-    {
-      "type": "guideline",
-      "content": "Side navigation consists of a few parts:"
-    },
-    {
-      "type": "guideline",
-      "content": "Additionally, this button should not be used outside of the app frame context. It has unique animations between expanding and collapsing that are optimized for the app frame side navigation panel."
-    },
-    {
-      "type": "guideline",
-      "content": "Allows the side navigation to be minimized by the user."
-    },
-    {
-      "type": "guideline",
-      "content": "The partial style displays icon-only side navigation items when minimized. The full style hides the side navigation when minimized."
-    },
-    {
-      "type": "guideline",
-      "content": "Shows a create button at the top of the panel."
-    },
-    { "type": "guideline", "content": "Enables drag on the side navigation." },
-    {
-      "type": "guideline",
-      "content": "If the side navigation panel can be minimized (Can be minimized: true), dragging to the min width (expanded) will collapse the side navigation into the minimized state."
-    },
-    {
-      "type": "guideline",
-      "content": "The minimum width that the side navigation panel can be adjusted to."
-    },
-    {
-      "type": "guideline",
-      "content": "The default width that the side navigation panel appears in."
-    },
-    {
-      "type": "guideline",
-      "content": "The text that is displayed as the label of the app frame side navigation item, to supplement the icon."
-    },
-    {
-      "type": "guideline",
-      "content": "Hides the label, making the app frame side navigation item icon-only."
-    },
-    {
-      "type": "guideline",
-      "content": "The number of lines that is shown before the label is truncated."
-    },
-    {
-      "type": "guideline",
-      "content": "After the user clicks on an app frame side navigation item, the left visual bar will turn gray-800, text will bold, and color will change to content-neutral."
-    },
-    {
-      "type": "guideline",
-      "content": "Changes the side navigation item to the disabled state."
-    },
-    {
-      "type": "guideline",
-      "content": "The text that is displayed as the label of the tooltip."
-    },
-    {
-      "type": "guideline",
-      "content": "Use the overlay variant of the app frame: side navigation (browsing) component for smaller breakpoints. The overlay is triggered via the hamburger menu in the header (rather than a touchpoint at the bottom)."
-    },
-    {
-      "type": "guideline",
-      "content": "Although 768 px is the recommended breakpoint to begin displaying the overlay designs, each product team should determine which breakpoint best suits their needs."
-    },
-    {
-      "type": "guideline",
-      "content": "The divider at the bottom of the side navigation is an intentional visual element that separates overflow side navigation items and end section items from the state control icon."
-    },
-    {
-      "type": "guideline",
-      "content": "The end section is optional and used to contain navigation items in a separate category that is secondary to the main navigation items. Categories, when defined, should readily communicate a clear purpose and be meaningful to users. Items placed here sit on a separate area. When resized to a smaller height, the items should append onto the start section and scroll together."
-    },
-    {
-      "type": "guideline",
-      "content": "The minimum width is customizable, depending on the number of levels:"
-    },
-    {
-      "type": "guideline",
-      "content": "If the side navigation contains user-generated content (like shortcuts to folders and files), enabling resizing can be a good way to improve usability by respecting user content, without needing to predict the length of labels that users might input."
-    },
-    {
-      "type": "guideline",
-      "content": "Along with being descriptive, the labels of navigation items should be succinct. Keep navigation strings to 1 or 2 and no more than 3 concise words (in U.S. English, which is the source locale). Reduce any unnecessary words in order to ensure simplicity."
-    },
-    {
-      "type": "guideline",
-      "content": "Navigation items should never be so long that they require truncation, except in instances where navigation is user-generated (e.g., folder and file names)."
-    },
-    {
-      "type": "guideline",
-      "content": "If possible, the default width should auto-adjust to the longest string in the navigation in order to accommodate all translations. As a last resort for long strings, specific line breaks can be built into the implementation. These line breaks depend on the content, and requires manual handling by Globalization engineers."
-    },
-    {
-      "type": "guideline",
-      "content": "When navigation items are shown in both the side navigation and header at the same time, the hierarchy and relationships between them become unclear. If the side navigation is used, don’t put any navigation items in the header."
-    },
-    {
-      "type": "guideline",
-      "content": "Supporting multiple states (default, and partial or fully minimized style) provides users with the option to choose their preferred layout based on their own preferences. In user studies, individual preference is the biggest factor when it comes to whether or not people want to view labels by default."
-    },
-    {
-      "type": "guideline",
-      "content": "If supporting multiple states, consider showing the side navigation in the expanded state by default, and preserve user preferences across pages and sessions. If minimizing the side navigation is not supported, show the side navigation in the expanded state. Showing labels by default increases recognition and familiarity."
-    },
-    {
-      "type": "guideline",
-      "content": "There are some app frame-specific constraints for the side navigation. Icons are required at the parent level. Nested items can have no icon, but the parent level must have an icon."
-    },
-    {
-      "type": "guideline",
-      "content": "Diagram describing notes about the side navigation for the app frame, in the editing context. While toolbars share the same location as the app frame side navigation in a browsing context, toolbars in an editing context serve a different purpose: to readily select commonly used tools, rather than to navigate between pages. The behavior and interaction of toolbars doesn’t need to mirror the side navigation and should instead best serve user needs in an editing context. For example, the option to show and hide tool labels can be an additional customization option and doesn’t need to be controlled by the hamburger menu, which is used to display the application menu in Creative Cloud."
-    }
-  ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/app-frame-side-navigation/",
-  "lastUpdated": "2026-02-02",
-  "status": "published",
-  "tags": ["designing"],
-  "related": [
-    { "ref": "s2-app-frame-header-browsing-context" },
-    { "ref": "s2-app-frame-content-area-browsing-context" }
-  ]
-}