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

package/guidelines/creating-bluelines-browsing-context.json

@@ -1,91 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/creating-bluelines-browsing-context.json",
-  "name": "creating-bluelines-browsing-context",
-  "title": "Creating bluelines",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "Creating bluelines" },
-    {
-      "type": "guideline",
-      "content": "The accessible name is the text that software uses to identify a component, and communicates it to the user. Assistive technologies like screen readers and voice control require an accessible name to read aloud content to screen reader users, or to accept speech input from voice control users to interact with digital content. Learn more about accessible names. Accessible names vary depending on the content. Accessible names must be defined for controls that don’t have visible text labels."
-    },
-    {
-      "type": "guideline",
-      "content": "A. Side navigation state control.\n\nThe default accessible name are Show menu labels and Hide menu labels. In general, the names should be as specific as possible and are up to individual product teams to define, based on the content inside. View more details about side navigation state control."
-    },
-    {
-      "type": "guideline",
-      "content": "B. Product lock-up.\n\nWhen an interactive control has a visible text label, there is no requirement to specify an accessible name. The visible text label will be accessible and the graphic will be ignored by a screen reader."
-    },
-    {
-      "type": "guideline",
-      "content": "C. Side navigation labels.\n\nWhen the side navigation is partially minimized (icon-only), the labels on the tooltips and when the side navigation is expanded should match the accessible names. Because a text label is available in both expanded and minimized states, app frame side navigation buttons do not require additional annotation."
-    },
-    {
-      "type": "guideline",
-      "content": "D. Adobe-wide actions.\n\nIf using the universal navigation pattern, follow guidance defined in the design and implementation for continuity across products. Here are some guidelines to keep in mind as you define accessible names in the app frame:"
-    },
-    {
-      "type": "guideline",
-      "content": "D. Adobe-wide actions.\n\nIf using the universal navigation pattern, follow guidance defined in the design and implementation for continuity across products."
-    },
-    {
-      "type": "guideline",
-      "content": "Landmark regions create a programmatic identification of the visual areas or sections of web applications, which represent the spatial layout of the user interface. The purpose of annotating landmark regions is to ensure developers code the page structure correctly, include the correct content in the defined grouping, and apply an accessible name to the landmark regions that require them. Learn more about landmark regions. 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": "Landmark regions create a programmatic identification of the visual areas or sections of web applications, which represent the spatial layout of the user interface. The purpose of annotating landmark regions is to ensure developers code the page structure correctly, include the correct content in the defined grouping, and apply an accessible name to the landmark regions that require them. 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: Note that you may also want to include additional landmark regions for content within each area. A. The navigation areas require accessible names, because there is more than one area on the page. Depending on your content, the accessible names might be different for your product. B. Regions always require accessible names, and should be named based on the content of the region. If using content areas split into additional areas, make sure to name those regions as well. Note: In some cases, landmarks might be better defined as a complementary landmark instead of a region landmark. For example, the AI assistant in Digital Experience products is separate from the main content (not contained within another landmark), but is still supportive of the main content. In that case, the AI assistant would be a complementary landmark instead of a region landmark."
-    },
-    {
-      "type": "guideline",
-      "content": "Heading annotations describe the heading structure of a digital interface and are helpful for all users. Screen reader users in particular rely on them to navigate an interface. They organize information, help create an information hierarchy, and build a mental map of the content available. Learn more about heading annotations. There must be one <h1> heading, and any text that serves the purpose of a heading must be marked accordingly from <h1> to <h6>. Because headings rely greatly on structure and content, they will likely vary depending on the page. As a general rule, the <h1> should live in the main landmark region. Here’s an example of how you might structure heading annotations for this screen:"
-    },
-    {
-      "type": "guideline",
-      "content": "Heading annotations describe the heading structure of a digital interface and are helpful for all users. Screen reader users in particular rely on them to navigate an interface. They organize information, help create an information hierarchy, and build a mental map of the content available. There must be one <h1> heading, and any text that serves the purpose of a heading must be marked accordingly from <h1> to <h6>. Because headings rely greatly on structure and content, they will likely vary depending on the page. As a general rule, the <h1> should live in the main landmark region. Here’s an example of how you might structure heading annotations for this screen:"
-    },
-    {
-      "type": "guideline",
-      "content": "The keyboard focus order describes how someone who uses a keyboard to operate the interface (instead of a pointing device like a mouse), would interact with an interface. Learn more about keyboard focus order. 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": "The keyboard focus order describes how someone who uses a keyboard to operate the interface (instead of a pointing device like a mouse), would interact with an interface. 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": "Support keyboard focus for resizing the side navigation.\n\nExample 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": "Include a “Skip to main content” button.\n\nExample of correct usage, inclusion of a Skip to main content button within the app frame header."
-    },
-    {
-      "type": "guideline",
-      "content": "Support F6 key navigation.\n\nWhen 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. Here are some key quality factors to consider: A keyboard focus indicator should be present to show keyboard-only users their current location within the interface. Ideally, the focus of the F6 key should move in accordance with the landmark regions defined in the HTML of the application. Major sections of the app should be accessible through the F6 key, including main navigation, toolbars, contextual toolbars, and the canvas. Each of these regions must have an accessible name assigned to them, allowing screen reader users to understand which area of the user interface they are currently navigating. For more information about F6 key navigation, please refer to the Digital Accessibility Guide: Design a11y checklist."
-    },
-    {
-      "type": "guideline",
-      "content": "Support F6 key navigation.\n\nWhen 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. Here are some key quality factors to consider: A keyboard focus indicator should be present to show keyboard-only users their current location within the interface. Ideally, the focus of the F6 key should move in accordance with the landmark regions defined in the HTML of the application. Major sections of the app should be accessible through the F6 key, including main navigation, toolbars, contextual toolbars, and the canvas. Each of these regions must have an accessible name assigned to them, allowing screen reader users to understand which area of the user interface they are currently navigating."
-    },
-    {
-      "type": "guideline",
-      "content": "Mobile overlay guidance: Keyboard focus.\n\nFor 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://main--spectrum-hub--adobe.aem.live/foundations/app-frame/creating-bluelines-browsing-context",
-  "lastUpdated": "2026-09-04",
-  "status": "published",
-  "tags": [
-    "app frame",
-    "bluelines",
-    "accessible names",
-    "landmark regions",
-    "heading annotations",
-    "side navigation",
-    "universal navigation",
-    "complementary landmark"
-  ]
-}

package/guidelines/design-tokens.json

@@ -1,122 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/design-tokens.json",
-  "name": "design-tokens",
-  "title": "Design tokens",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "Design tokens" },
-    {
-      "type": "guideline",
-      "content": "Design tokens enable alignment, automation, learnability, and multi-platform fidelity, resulting in high-quality experiences and efficient system management. By defining design decisions once and reusing them consistently, tokens create a shared foundation that helps maintain a common design language across teams, tools, products, and platforms. This allows experiences to adapt to different implementation needs while preserving the intent of the design language."
-    },
-    {
-      "type": "guideline",
-      "content": "Clear.\n\nDesign tokens are created within a well-defined scope, purpose, and meaning so they remain understandable and accurately represent the design language."
-    },
-    {
-      "type": "guideline",
-      "content": "Systematic.\n\nDesign tokens are defined and managed through a structured system that spans design and development resources."
-    },
-    {
-      "type": "guideline",
-      "content": "Learnable.\n\nDesign tokens are supported through documentation, guidance, and educational resources that help people identify, understand, and use them effectively."
-    },
-    {
-      "type": "guideline",
-      "content": "Spectrum uses tokens as a shared foundation for expressing and reusing design decisions throughout the design system. Rather than representing every possible design scenario, the token system focuses on reusable decisions that support many structures, components, products, and experiences Spectrum also prioritizes semantic design decisions over direct values whenever possible. By expressing intent rather than implementation details, tokens become easier to understand, easier to reuse, and more resilient to change over time. Design tokens work together with component libraries, implementation frameworks, documentation, and other Spectrum resources to help maintain a cohesive design language across products and platforms. While tokens capture many design decisions, they are only one part of the broader system used to design, document, and implement Spectrum experiences."
-    },
-    {
-      "type": "guideline",
-      "content": "Token.\n\nA reusable design decision represented as structured data. A token consists of a name and a value. Together, these define both the purpose of a design decision and the data used to implement it."
-    },
-    {
-      "type": "guideline",
-      "content": "Token name.\n\nThe structured classification of a design use case. Token names are created using Spectrum's token taxonomy, which defines the categories, terminology, and ordering used to describe design decisions. This helps ensure that names remain predictable, scalable, and understandable across teams, tools, products, and platforms. Token names form a shared language that helps people and systems understand and apply design decisions consistently across tools, products, and platforms."
-    },
-    {
-      "type": "guideline",
-      "content": "Value.\n\nThe data associated with a token. A value may be a final implementation value such as a color, dimension, percentage, or duration. A value can be dependent on context, such as light or dark color themes. It may also be a reference to another token through aliasing.\n\nToken nameValue blue-900 rgb(59, 99, 251) spacing-100 8px container-padding-medium spacing-300"
-    },
-    {
-      "type": "guideline",
-      "content": "Alias.\n\nA token that references another token instead of a final value. Aliasing allows broad design decisions to be refined into more specific contexts and use cases while preserving consistency and reducing duplication. Each layer adds additional context without redefining the underlying value.\n\nToken nameValue (alias) accent-content-color-default accent-color-900"
-    },
-    {
-      "type": "guideline",
-      "content": "Primitive (aka Global) tokens.\n\nPrimitive tokens define the available values in the design language. They represent raw design values and generally communicate little or no information about how those values should be used. Examples: blue-800 gray-100 corner-radius-75 Primitive tokens provide the foundation for higher-level design decisions. Because they communicate values with no intent, they are typically used indirectly through semantic tokens as an alias."
-    },
-    {
-      "type": "guideline",
-      "content": "Semantic tokens define how design decisions are used throughout the system. Rather than describing values directly, they communicate purpose, intent, structure, or application. Examples: accent-background-color-default negative-content-color-default container-padding-medium group-gap-small Semantic tokens help people understand: Why a decision exists Where it should be used How it relates to other design decisions Semantic tokens are the primary way consumers interact with Spectrum design tokens."
-    },
-    {
-      "type": "guideline",
-      "content": "Component-specific tokens.\n\nComponent-specific tokens represent design decisions that apply to a specific component or implementation. Examples: tooltip-maximum-width divider-thickness-small Spectrum prioritizes reusable semantic decisions whenever possible, which reduces the need for component-specific tokens. However, some implementation-specific needs may still require decisions that are scoped to a particular component. For this reason, component-specific tokens may exist within Spectrum or individual platform implementations, but they play a much smaller role than reusable semantic tokens."
-    },
-    {
-      "type": "guideline",
-      "content": "Meaning.\n\nEvery design decision serves a purpose. Some decisions communicate meaning, helping users understand status, emphasis, importance, or feedback. Examples include: accent-background-color-default negative-border-color-default negative-content-color-default positive-background-color-default These decisions describe what a design choice is intended to communicate.\n\nMeaning helps people understand not only how an interface looks, but what it is trying to convey. By expressing meaning directly in token names, decisions become easier to understand, reuse, and apply consistently across products and platforms."
-    },
-    {
-      "type": "guideline",
-      "content": "Reusable structures.\n\nWhile some design decisions communicate meaning, others help define how components are organized and constructed. Examples include: container-padding-medium group-gap-small base-padding-vertical-large banner-gap-horizontal These decisions describe how interfaces are built.\n\nTo improve reuse and consistency, Spectrum organizes many of these decisions around recurring interface structures. These reusable structures are abstract concepts that describe common UI patterns. They are not specific components or implementation types. Instead, they provide a shared framework for organizing design decisions that can be reused across many different components, products, and technologies. Because these structures represent patterns rather than implementations, they help create design decisions that are more reusable, predictable, and easier to understand. Some structures may closely resemble familiar interface concepts, but they remain independent of any specific platform or implementation. These structures help answer “Where does this design decision apply?” Common structures include: Structure Description BaseThe primary functional element within a structureAccessoryA supporting element associated with another structureGroupA collection of related elementsListA sequence of repeated itemsContainerA structure that organizes contentBannerA structure used for prominent messagingThese structures help answer “Where does this design decision apply?”"
-    },
-    {
-      "type": "guideline",
-      "content": "Components are often composed from one or more reusable structures. Rather than creating unique design decisions for every component, Spectrum reuses decisions across common patterns that appear throughout the system. This approach allows many components to share the same underlying design language while adapting to different contexts and use cases. Platform implementations combine these reusable structures with platform-specific requirements, interaction patterns, accessibility considerations, and implementation constraints to create complete component experiences. By reusing tokens, structures, and components, teams can build cohesive experiences without redefining the same decisions in every implementation. As a result, decisions become more reusable, components become more modular, and the system becomes easier to learn, maintain, and evolve."
-    },
-    {
-      "type": "guideline",
-      "content": "Positive color 600.\n\nThe name identifies: what’s being communicated (positive) which option is used (600) Together they represent a specific color decision."
-    },
-    {
-      "type": "guideline",
-      "content": "Accent background color hover.\n\nThe name identifies: what’s being communicated (accent) what it affects (background-color) when it applies (hover) Together they describe the background color used when an accentuated interface element is hovered."
-    },
-    {
-      "type": "guideline",
-      "content": "Base padding vertical small.\n\nThe name identifies: where it’s applied (base) what it affects (padding) how it’s applied (vertical) which option is used (small) Together they describe a specific spacing decision used by base structures (Action button, Text field, List item contents, etc)."
-    },
-    {
-      "type": "guideline",
-      "content": "Start with Spectrum components.\n\nWhenever possible, use your platform's Spectrum components before working directly with design tokens. Components bring together design decisions, behavior, accessibility, and implementation guidance into reusable solutions that are already aligned with the Spectrum design language. Design tokens provide the foundation that supports those solutions. When existing components don't meet your needs, tokens can help you extend, compose, or create experiences that remain consistent with Spectrum."
-    },
-    {
-      "type": "guideline",
-      "content": "Prioritize semantic tokens.\n\nStart with semantic tokens whenever possible. They communicate intent and context, making design decisions easier to understand, reuse, and maintain over time."
-    },
-    {
-      "type": "guideline",
-      "content": "Use primitive tokens only when necessary.\n\nPrimitive tokens define important building blocks of the design language but contain less contextual meaning. Use them only when no appropriate semantic decision exists."
-    },
-    {
-      "type": "guideline",
-      "content": "Use component-specific tokens only for their intended component.\n\nComponent-specific tokens are intentionally limited. Use them only for their intended component or implementation and avoid reusing them as general-purpose design decisions."
-    },
-    {
-      "type": "guideline",
-      "content": "Foundational tokens are shared design decisions that form the common language of Spectrum. They serve as the source of truth across products, platforms, and implementations."
-    },
-    {
-      "type": "guideline",
-      "content": "Platform tokens support the unique requirements of a specific platform implementation. They allow platforms to adapt shared design decisions to their own needs while remaining connected to the broader Spectrum design language."
-    },
-    {
-      "type": "guideline",
-      "content": "Shared language, flexible implementation.\n\nNot every platform needs every foundational token, and token values may differ between platforms to support differences in sizing, density, theming, or platform capabilities. Even when implementations differ, they remain rooted in the same taxonomy, terminology, and design language. Design data can be re-shaped to fit platform needs while maintaining system cohesion."
-    }
-  ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/design-data/design-tokens",
-  "lastUpdated": "2026-08-14",
-  "status": "published",
-  "tags": [
-    "design tokens",
-    "token taxonomy",
-    "aliasing",
-    "semantic design",
-    "color",
-    "spacing",
-    "typography"
-  ]
-}

package/guidelines/drop-shadow.json

@@ -1,56 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/drop-shadow.json",
-  "name": "drop-shadow",
-  "title": "Drop shadow",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "Drop shadow" },
-    {
-      "type": "guideline",
-      "content": "Create elevation.\n\nUse drop shadows to indicate when content appears above other content. Shadows help establish spatial relationships between interface elements and reinforce the visual hierarchy of the interface."
-    },
-    {
-      "type": "guideline",
-      "content": "Support emphasis.\n\nDrop shadows can also be used to emphasize important interface elements. When applied sparingly, they help guide attention while maintaining a clear and consistent visual hierarchy."
-    },
-    { "type": "guideline", "content": "Drop shadow details" },
-    {
-      "type": "guideline",
-      "content": "Composition.\n\nSpectrum drop shadows are composed of three layers that work together to create a natural sense of depth while preserving the shape of the component. Key shadow Defines the edge of the component against the background. Transition shadow Softens the transition between the key and ambient shadows to create a smoother appearance. Ambient shadow Creates the overall sense of depth and determines the total size of the shadow."
-    },
-    {
-      "type": "guideline",
-      "content": "Dark theme.\n\nDrop shadows continue to communicate elevation in dark theme, but their appearance is adjusted to maintain sufficient contrast against darker surfaces. Dark theme shadows use three times the opacity of their light theme equivalents. Components that appear above other content, such as popovers, also use a border in dark theme to provide additional separation from the background."
-    },
-    {
-      "type": "guideline",
-      "content": "Overlay.\n\nAn overlay communicates elevation by visually separating foreground content from the rest of the interface. When an overlay is used, such as behind a dialog, an additional drop shadow isn't needed because the overlay already establishes the elevated relationship."
-    },
-    {
-      "type": "guideline",
-      "content": "Platform availability.\n\nThese tokens are currently available on web. Guidance for additional platforms will be added in a future release."
-    },
-    {
-      "type": "guideline",
-      "content": "Shadow styles.\n\nEach shadow style is represented by a single composite token that defines the key, transition, and ambient shadow layers used to create the final drop shadow. The table below lists the values for each shadow layer: X: Horizontal offset. 0 px for all layers. Y: Vertical offset. The ambient shadow uses the largest offset. Blur: Blur radius. Each layer uses a different value to create a smooth transition between the shadow layers. Spread: Spread value. 0 px for all layers. Shadow styleTokenKey valuesTransition valuesAmbient valuesEmphasized, defaultdrop-shadow-emphasizedX = 0 Y = 0 Blur = 1 Spread = 0X = 0 Y = 1 Blur = 4 Spread = 0X = 0 Y = 2 Blur = 8 Spread = 0Emphasized, hoverdrop-shadow-emphasized-hoverX = 0 Y = 0 Blur = 2 Spread = 0X = 0 Y = 2 Blur = 6 Spread = 0X = 0 Y = 4 Blur = 12 Spread = 0Elevateddrop-shadow-elevatedX = 0 Y = 0 Blur = 2 Spread = 0X = 0 Y = 2 Blur = 6 Spread = 0X = 0 Y = 4 Blur = 12 Spread = 0Draggeddrop-shadow-draggedX = 0 Y = 0 Blur = 6 Spread = 0X = 0 Y = 6 Blur = 8 Spread = 0X = 0 Y = 12 Blur = 16 Spread = 0"
-    },
-    {
-      "type": "guideline",
-      "content": "Shadow colors.\n\nSpectrum drop shadows use black (#000000) as their base color. The perceived appearance of each shadow is created by varying its opacity and layering. In dark theme, the opacity value is 3× the opacity value of light theme. Shadow colorTokenOpacity valuesEmphasized (Key shadow) drop-shadow-emphasized-key-color 8% (light) 24% (dark)Emphasized, hover (Key shadow) drop-shadow-emphasized-hover-key-color 12% (light) 36% (dark)Elevated (Key shadow) drop-shadow-elevated-key-color 12% (light) 36% (dark)Dragged (Key shadow) drop-shadow-dragged-key-color 16% (light) 48% (dark)All styles (Ambient shadow) drop-shadow-ambient-color 8% (light) 24% (dark)All styles (Transition shadow) drop-shadow-transition-color 4% (light) 12% (dark)"
-    }
-  ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/styles/object-styles/drop-shadow",
-  "lastUpdated": "2026-08-14",
-  "status": "published",
-  "tags": [
-    "drop shadow",
-    "elevation",
-    "ambient shadow",
-    "transition shadow",
-    "key shadow",
-    "dark theme",
-    "overlay",
-    "shadow tokens"
-  ]
-}

package/guidelines/grammar-and-mechanics.json

@@ -1,252 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/grammar-and-mechanics.json",
-  "name": "grammar-and-mechanics",
-  "title": "Grammar and mechanics",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "Grammar and mechanics" },
-    {
-      "type": "guideline",
-      "content": "We use Associated Press (AP) style for in-product UX writing, with any exceptions noted on this page."
-    },
-    {
-      "type": "guideline",
-      "content": "Active voice.\n\nIn an active sentence, it's clear who's doing what. The actor is the subject, and the subject of the sentence is doing something."
-    },
-    {
-      "type": "guideline",
-      "content": "Passive voice.\n\nAt times, active voice can come across too harshly. In these cases, use passive voice. This separates the actor from the action enough to soften a sentence. In a passive sentence, action is being taken upon the subject."
-    },
-    {
-      "type": "guideline",
-      "content": "Avoid passive voice by reframing the focus.\n\nYou can usually reframe a message to focus on the object, or on the actions someone could take, as another way to avoid passive voice."
-    },
-    {
-      "type": "guideline",
-      "content": "Common contractions.\n\nUse commonly understood contractions to keep sentences from feeling out-of-touch, robotic, or overly formal. Some common contractions: What's We'll You'll You're You've We're They're Doesn't Didn't Isn't Aren't Can't"
-    },
-    {
-      "type": "guideline",
-      "content": "Contraction considerations.\n\nAvoid contracting nouns with is, does, has, or was. This might make it look like the noun is possessive. Don’t use uncommon or old-fashioned contractions (e.g., would’ve or tweren't ). Don’t use colloquial contractions (e.g., ain't, y'all, yinz ). Be mindful of how many contractions you use in a sentence. Too many contractions can make things difficult to read. Avoid using contractions when dealing with legal concerns, payment processing, and account security. Casual isn’t always the best style when handling sensitive information."
-    },
-    {
-      "type": "guideline",
-      "content": "Why we use simple verb tenses.\n\nThere are a number of reasons why we use simple verb tenses for in-product writing: They use fewer words and are more concise. They can make content easier to scan and faster to read. Fewer words and simpler phrases mean better readability. According to the latest U.S. Census, more than 20% of people living in the U.S. speak a language other than English at home. For more people, simple verb tenses are easier to understand. Present tense improves readability scores."
-    },
-    {
-      "type": "guideline",
-      "content": "What's not simple tense.\n\nIf any of the following comes before the verb in a sentence, it’s not simple tense: Was/wasn’t, were, weren’t Has/hasn’t, have/haven’t Is/isn’t, are/aren’t Be If the verb in a sentence ends in “-ing,” it’s not simple tense."
-    },
-    {
-      "type": "guideline",
-      "content": "Sentence case.\n\nUse sentence case for all aspects of designing or re-designing Adobe product experiences, including titles and UI elements (e.g., tooltips, tabs, menu items). This transition will take time for older products, and temporary inconsistency is fine. Writing in sentence case has been proven to be easier for users to read and comprehend, it sounds more friendly and less formal, and it helps better identify proper nouns and branded terms that need to be capitalized. When to use sentence case: Only capitalize the first word in a phrase, title, or UI reference (e.g., Adjust borders tool) Always capitalize proper nouns and branded terms (e.g., Adobe Help Center) Capitalize acronyms (e.g., XD, AEM)"
-    },
-    {
-      "type": "guideline",
-      "content": "Title case.\n\nUse title case only when it clarifies that we’re speaking about a specific, official entity (such as a title or name). Title case is often a marker of formality in English, and overuse can cause users stress by implying formality or officialness where it doesn’t exist."
-    },
-    {
-      "type": "guideline",
-      "content": "All caps.\n\nUse all caps sparingly. When to use all caps: Acronyms, such as accepted product names on second attribution (e.g., Adobe Experience Manager (AEM)) Names of file extensions (e.g., TIF, ZIP, or PSD files) All caps should never be used to emphasize a point."
-    },
-    {
-      "type": "guideline",
-      "content": "Branded terms.\n\nUse title case to reference branded terms, such as names and features. This includes the names of Adobe products, like Adobe Photoshop or Advertising Cloud. Here are some common branded terms: Creative Cloud Photoshop Lightroom Illustrator Premiere Pro XD Adobe Stock Document Cloud Fill & Sign Magic Heal Adobe Sensei Experience Cloud Advertising Cloud Analytics Audience Manager Campaign Experience Manager Commerce Cloud Marketo Engage Adobe Acrobat Adobe Sign"
-    },
-    {
-      "type": "guideline",
-      "content": "Referring to the user.\n\nIn UX content, we want to talk about what’s happening rather than who or what is making something happen. We avoid speaking as our users. In nearly all situations, we aim to be conversational and talk to the user — not as them. Any exceptions depend on situational needs for sensitivity and clarity."
-    },
-    {
-      "type": "guideline",
-      "content": "Second person.\n\nMost of the time, use second person ( you, your, you’re ) to address users and services."
-    },
-    {
-      "type": "guideline",
-      "content": "First person.\n\nUse first person ( me, I, my ) only in these situations: Someone responds to the interface or answers a question they've been asked directly When additional sensitivity is necessary, or to indicate privacy When there's a legal need to use first person to ask for consent (e.g., “I agree to these terms and conditions”) On rare occasions, it can be appropriate to use we or us to mean “Adobe”: \"We're sorry\" (for a critical error) \"Help us improve this feature\" (requesting feedback)"
-    },
-    {
-      "type": "guideline",
-      "content": "Singular they.\n\nIn most situations, Adobe doesn't need to know or assume the gender of our users. So when we refer to users, we use singular they. We don’t use “he/she” or “(s)he” — those are clunky and they exclude users who identify outside of the male/female binary. Use any of these variants of they in their proper grammatical contexts: They Them Their Theirs Themselves Themself"
-    },
-    {
-      "type": "guideline",
-      "content": "Ampersand.\n\nDon’t use ampersands (&) in UI copy. Instead, spell out the word “and.” Using the word “and” is more inclusive, localizable, and readable: It’s more widely known and understood for people who are non-fluent English speakers It translates more easily into many languages Spelled-out words require less mental and cognitive effort to read Ampersands bring attention to the conjunction in a phrase which is the least important part of the sentence The ampersand symbol can be distracting, since it’s taller than many letters and is an unusual shape"
-    },
-    {
-      "type": "guideline",
-      "content": "Apostrophe.\n\nDon’t use apostrophes (') in place of quotation marks. When pluralizing singular and plural words, add apostrophe-\"s\" when there’s no \"s\" at the end. For plural nouns that end with \"s,\" add only an apostrophe. For any other specifics on possessive apostrophes, refer to the AP style handbook."
-    },
-    {
-      "type": "guideline",
-      "content": "Asterisk.\n\nUse asterisks ( * ) or \"(required)\" to establish form fields as required. Don’t use asterisks to denote anything as optional. Make sure to use the Spectrum asterisk icon that comes built in with the design components — not the text form of an asterisk within the label string. Don’t use asterisks in running text or labels when parentheses or a tooltip would suffice."
-    },
-    {
-      "type": "guideline",
-      "content": "At sign.\n\nDon’t use the at sign (@) in place of the word \"at."
-    },
-    {
-      "type": "guideline",
-      "content": "Brackets.\n\nDon’t use brackets ([] {}) in UI copy or running sentences. Instead, use parentheses ( ( ) )."
-    },
-    {
-      "type": "guideline",
-      "content": "Colon.\n\nTry to simplify a complex sentence into multiple sentences first, but if you can’t, try a colon (:). Colons are helpful when introducing lists of items or steps in a workflow. The lists and steps should be introduced on new lines. They’re also useful for high-level headlines or marketing-sounding UI content. Don’t use a colon at the end of a label for a form field. The design component should already communicate the relationship between the label and the input."
-    },
-    {
-      "type": "guideline",
-      "content": "Comma.\n\nWhen listing things, use the serial comma (also known as the Oxford comma). This means providing a comma before the word “and” when listing multiple items in a sentence. If you’re having to use a lot of commas in a sentence, consider whether you can split the sentence up with periods or em dashes."
-    },
-    {
-      "type": "guideline",
-      "content": "Ellipsis.\n\nUse ellipses (…) when truncating text in small spaces. Use an ellipsis at the end of the text to communicate the progress of something that is in process, such as a waiting or loading state. In general, avoid using an ellipsis in a button. If a button will take a user to a completely different or more complicated view (such as going from a dialog to a settings panel), it can be acceptable to include an ellipsis at the end of the label text to communicate that there's more action needed beyond the button's initial interaction. For prompt text in a picker, use an ellipsis at the end of the text to communicate that a user can select an option (e.g., “Select category…”). If your product uses a menu pattern native to an operating system (OS), follow the company’s guidelines. If it uses Spectrum’s Menu component, see Ellipses in menu commands. If you need to directly refer to a UI element whose name ends with an ellipsis (e.g., “ Find… “) in running text, drop the ellipsis: “Use Find to search the database.” Use the more icon (not an ellipsis as a string of text) when designing a More menu."
-    },
-    {
-      "type": "guideline",
-      "content": "Emoji.\n\nDon’t use emoji in any interface language. Emoji often convey tones that may be inappropriate in certain contexts. They’re also difficult to localize, and tend to diminish readability and comprehension. When writing about emoji, you can have one emoji or multiple emoji. The spelling is the same for both the singular and plural noun forms."
-    },
-    {
-      "type": "guideline",
-      "content": "Equals sign.\n\nDon’t use an equals sign (=) in place of the word \"equals,\" and don’t use this as shorthand for \"meaning,\" \"means,” or \"is."
-    },
-    {
-      "type": "guideline",
-      "content": "Exclamation mark.\n\nDon’t use exclamation marks (!) since they are difficult to localize and easy to overuse."
-    },
-    {
-      "type": "guideline",
-      "content": "Greater than and less than.\n\nWhen communicating navigation, such as in breadcrumbs, use the \"chevron\" icon built into the component, not the greater than symbol. Don’t use the greater than and less than symbols to communicate steps in a flow — use bulleted or numbered lists instead. Don’t use these symbols to replace the words \"greater than\" or \"less than.\" And don’t use them to accent or decorate a word."
-    },
-    {
-      "type": "guideline",
-      "content": "Hyphen and dash.\n\nUse em dashes (—) to separate distinct but related thoughts. Include spaces before and after the em dash. Use en dashes (–) for number ranges and lengths of time, with no spaces before or after the en dash. Don’t use them when paired with the words “from” or “between.” When needing to show gaps in data in a table, use an en dash to represent null, unavailable, or inapplicable values. Use hyphens (-) between words, and with no spaces before or after the hyphen."
-    },
-    {
-      "type": "guideline",
-      "content": "Minus sign.\n\nDon’t use the minus sign (-) in place of the word “minus,” “without,” “less,” “negative,” or other words related to subtraction."
-    },
-    {
-      "type": "guideline",
-      "content": "Parentheses.\n\nUse parentheses ( ( ) ) to provide supplementary context. Don’t use parentheses in simple tooltips. In rich tooltips, they can indicate keyboard shortcuts. Don’t use brackets in place of parentheses."
-    },
-    {
-      "type": "guideline",
-      "content": "Period.\n\nIn general, if your text is a full sentence, add a period to the end. If it's a short, direct phrase — either standalone, or within a UI component like a toast or alert banner — don't add a period. In the majority of cases, don’t use periods (.) or any other punctuation on the end of bulleted or numbered lists. If one list item is a complete sentence, then it would end with a period (or question mark). In this case, use periods at the end of all items. Don’t use periods in headers or buttons."
-    },
-    {
-      "type": "guideline",
-      "content": "Plus sign.\n\nDon’t use plus signs (+) in place of the word \"and,\" bullet points, or as any other design elements. Don’t use plus signs when indicating there is more of something available."
-    },
-    {
-      "type": "guideline",
-      "content": "Question mark.\n\nWhen writing titles, questions marks (?) are the only acceptable punctuation mark to include. Avoid using question marks to ask rhetorical questions."
-    },
-    {
-      "type": "guideline",
-      "content": "Quotation mark.\n\nIn UI copy, only use quotation marks (“”) when quoting someone’s words or when referring to a file or asset name. Always use smart quotation marks (also called “curly” or “directional”), except when showing code. Smart quotation marks are easier to read because they better match the other characters in a typeface. Straight quotes may also be confused with prime symbols, which are used for measurements. Don’t use quotation marks when directly referring to interface elements. View the Typography page for guidance on using bold text to do so."
-    },
-    {
-      "type": "guideline",
-      "content": "Semicolon.\n\nDon’t use semicolons (;). If you need a break in a sentence, use periods, commas, or occasionally em dashes. While semicolons are useful for connecting two related thoughts, they add a formal and academic tone to text and have shown to negatively affect user comprehension in UX writing."
-    },
-    {
-      "type": "guideline",
-      "content": "Slash.\n\nDon’t use backward slashes, and don’t use a forward slash ( / ) to combine words or ideas. This comes across as noncommittal, and affects comprehension and clarity. Instead, use the words “and” or “or.” Don’t use “and/or.”"
-    },
-    {
-      "type": "guideline",
-      "content": "Vertical bar.\n\nDon’t use the vertical bar (|) in running text. Avoid using it to divide information in places other than webpage titles tags and footer info. It shouldn’t be used for purely stylistic or decorative purposes when blank space between items is sufficient. When you use the vertical bar, use an icon and not its text form. Additionally, make sure you change its name in JAWS to “Pause” for proper accessibility."
-    },
-    {
-      "type": "guideline",
-      "content": "Amounts.\n\nUse K for thousands, M for millions, B for billions, capitalized, no periods. Include a space between the number and the unit of measurement (e.g., \"71 M records found\")."
-    },
-    {
-      "type": "guideline",
-      "content": "Measurements and dimensions.\n\nFor full sentences where measurements or other numbers are present, use AP style and spell out the unit of measurement (e.g., 2 points, 2 picas, 2 pixels, 2 megabytes). Similarly, use AP style when abbreviating measurements or time. Make sure there’s a space between the number and the unit of measurement (e.g., 2 pt, 2 MB, 2 min, 2 hr)."
-    },
-    {
-      "type": "guideline",
-      "content": "Months.\n\nUse Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec (no periods)."
-    },
-    {
-      "type": "guideline",
-      "content": "Days.\n\nUse Sun, Mon, Tue, Wed, Thu, Fri, Sat (no periods)."
-    },
-    {
-      "type": "guideline",
-      "content": "Time.\n\nUse sec, min, hr as singular, no periods, no comma, and with a space in between the number and the unit of time (e.g., 1 hr 21 min). Use lowercase am and pm indicators without a preceding space, unless you’re describing 24-hour time (e.g., 17:15)."
-    },
-    {
-      "type": "guideline",
-      "content": "Currency.\n\nUse the numerical form of $1.00 when formality is needed, or when the number is dynamic and might include cents. Use the number form of $1 when you need a more casual, neutral tone or if there is a space constraint and you can round off to the nearest dollar. Use the international abbreviation for the currency when you need to disambiguate types of currency (e.g., \"$100 USD equals $138.21 SGD\")."
-    },
-    {
-      "type": "guideline",
-      "content": "Large numbers.\n\nUse a comma to offset groups of three digits, for readability: 10 100 1,000 10,000 100,000 1,000,000 But for the best readability, when citing large, round numbers, spell out the word: 4 thousand 81 million 2.5 billion"
-    },
-    {
-      "type": "guideline",
-      "content": "Numerals.\n\nIn running text, write out the words zero through nine, then start using the number for 10 and higher. When telling time, presenting a series or range, or providing a timestamp, use the number forms: 0 through 9. You can adjust how you format numerals if you feel it’s appropriate for your situation. Using a number adds more emphasis than spelling out the word. For example, if you were to say “Compare two files and see the changes,” the emphasis is on the comparison, not on the number of files. \"Read all eight comments\" focuses on the availability of comments; \"Read all 8 comments\" focuses on the number of comments. If you’re mentioning currency or time alongside other types of numbers, spell out the number to make the currency or time more prominent."
-    },
-    {
-      "type": "guideline",
-      "content": "Percentages.\n\nUse the percent symbol (%) instead of spelling out the word \"percent."
-    },
-    {
-      "type": "guideline",
-      "content": "Dates.\n\nDate formatting is contextual, and it will depend on your product and use case. Different kinds of date formatting can be used for standalone strings in running text or for strings in more data-rich views. Some experiences might require the full format, where others might require something more compact: Full: Monday, August 21, 2017 at 3:07pm Compact: Mon, Aug 21, 2017, 3:07pm Additionally, dates are often localized. For example, in Europe and the U.K., the previous date example would be written: Full: Monday, 21 August at 15:07 Compact: Mon, 21 Aug, 15:07 For U.S. English, you can also format dates as MM-DD-YYYY, using the numeral for the month instead of the word. Use a 2-digit format (including a 0, even with single digit months and days). The 2-digit format also helps make it easier to parse and compare multiple dates, especially in tables or lists: 02/24/2000 04/01/2015 Work with a localization expert to localize dates and times for your product’s specific cases. Learn more about the formatting for abbreviating dates (months and days) in the Abbreviations section."
-    },
-    {
-      "type": "guideline",
-      "content": "Time.\n\nDo not use:00 with whole numbers When presenting a range of time, use an en dash without spaces in between, and do not include am or pm on the first time if it’s the same as the last When translating to 24-hour time, do not include am and pm (e.g., 17:15) Learn more about the formatting for abbreviating time (hours, minutes, seconds, and am and pm indicators) in the Abbreviations section."
-    },
-    {
-      "type": "guideline",
-      "content": "Relative time is either used to convey the amount of time elapsed since an event (such as how long since a project was last saved or edited), or the amount of time remaining in an ongoing process (such as how much longer an asset will take to render or download). Use words like “hour,” “day,” and “month” and their respective abbreviations once the time has reached that threshold for measurement. Such as: 1 hour (rather than 60 minutes) 1 day (rather than 24 hours) 1 month (rather than 30 days) 1 year (rather than 365 days) The usage of relative time is contextual, and will depend on your product and use case (for example, timestamps and locale style or standards). If you’re not building in U.S. English, partner with a localization expert for your product’s specific considerations."
-    },
-    {
-      "type": "guideline",
-      "content": "Elapsed time.\n\nWhen describing elapsed time, break it down as follows: Just now 1 minute ago X minutes ago 1 hour ago X hours ago 1 day ago X days ago 1 month ago X months ago 1 year ago X years ago"
-    },
-    {
-      "type": "guideline",
-      "content": "Remaining time.\n\nWhen showing remaining time, use the following pattern: X hours remaining X minutes remaining X seconds remaining For describing an estimated or uncertain amount of remaining time, use the word \"about\" at the beginning of the string."
-    },
-    {
-      "type": "guideline",
-      "content": "Timestamps.\n\nFor a timestamp in a video editor where precision is needed, go by hour, then minute, then second, following this formula: HHSS. In a tutorial playlist, for example, less detail is needed. If the video is less than an hour long, omit the hours."
-    },
-    {
-      "type": "guideline",
-      "content": "Time zones.\n\nAvoid time zones unless absolutely necessary — if possible, dynamically convert to the user’s time zone. If the time zone is absolute, use the common name, like Pacific Time, or India Standard Time. Don’t use UTC formulas. If space is constrained, use a time zone's acronym (e.g., PST, EST), but make sure you provide extra context to your localization team if doing so. For relative time and clarity, say “in your time zone.”"
-    },
-    {
-      "type": "guideline",
-      "content": "Introductory phrases.\n\nUse an introductory phrase with a colon to lead into the list, and write each list item so it works with that phrase."
-    },
-    {
-      "type": "guideline",
-      "content": "Be consistent and use parallel construction.\n\nPhrase your list items to be consistent with each other as much as possible. This helps with comprehension and readability. Some things to keep in mind when writing lists: Capitalize the first letter of each list item. Generally, don’t use terminal punctuation in list items, unless it’s a complete sentence or sentences. If the list includes action items (as in a series of instructions), the entire list should follow the same format, with the verb first. If it’s a list of nouns, all items on the list should include nouns."
-    },
-    {
-      "type": "guideline",
-      "content": "Capitalize each list item.\n\nCapitalize the first letter of each list item and use sentence case."
-    }
-  ],
-  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/content/grammar-and-mechanics",
-  "lastUpdated": "2026-09-04",
-  "status": "published",
-  "tags": [
-    "UX writing",
-    "AP style",
-    "Active voice",
-    "Passive voice",
-    "Contractions",
-    "Contraction considerations",
-    "Verb tenses",
-    "Readability",
-    "Localization"
-  ]
-}

package/guidelines/header-browsing-context.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/guideline.schema.json",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/guidelines/header-browsing-context.json",
-  "name": "header-browsing-context",
-  "title": "Browsing context: Header",
-  "category": "designing",
-  "documentBlocks": [
-    { "type": "purpose", "content": "Browsing context: Header" },
-    {
-      "type": "guideline",
-      "content": "Limit the number of call-to-action (CTA) buttons.\n\nAs 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. 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": "Examples" },
-    {
-      "type": "guideline",
-      "content": "Keyboard interactions.\n\nIf a “skip to main content” button is enabled, it appears only on keyboard focus as the first item in the focus order. View details and examples of keyboard interactions documentation. Key Interactions TabFocuses onto or off of the header.Arrow keysMoves between header navigation items.Space/enterExecutes selection of the item and changes the view of the page in the content area. The focus remains on the selected header item."
-    },
-    {
-      "type": "guideline",
-      "content": "Cursor guidelines.\n\nState Cursor Description HoverPointer Product icon and name is a link and should use a pointer.HoverArrowEverything else that is not a link."
-    },
-    {
-      "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://main--spectrum-hub--adobe.aem.live/foundations/app-frame/header-browsing-context",
-  "lastUpdated": "2026-09-04",
-  "status": "published",
-  "tags": [
-    "App frame header",
-    "Top App Bar (TAB)",
-    "Product lock-up",
-    "Navigation",
-    "Universal nav"
-  ]
-}