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

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

@@ -0,0 +1,91 @@
+{
+  "$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

@@ -0,0 +1,122 @@
+{
+  "$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/developer-overview.json

@@ -8,28 +8,44 @@
     { "type": "purpose", "content": "Developer overview" },
     {
       "type": "guideline",
-      "content": "Spectrum 2 offers a new look and feel that your team will want to adopt for your product. You’ll probably have questions, like “How do we get started?” “How do we migrate?” or “How do we roll this out?”"
+      "content": "React Spectrum (RSP).\n\nSpectrum 2 for React Spectrum is now Generally Available. Over 70 components matching the Spectrum 2 Figma designs are now production-ready and available in the new @react-spectrum/s2 package. The Spectrum 2 package supports both new projects and those already on React Spectrum v3, with the ability to migrate portions of an application independently. Migration support is available through the upgrade migration tool as well as documentation on the website. See our guides to learn how to use Spectrum tokens via the style macros and ways to build using AI agents. React Spectrum components are built on React Aria Components and Spectrum Tokens, and will continue to be added incrementally as designs become available. For a full list of currently available components, see the Status section of the Spectrum 2 for React Spectrum page. Visit the React Spectrum website for component documentation, examples, latest updates, and release information. Join #react-spectrum and #rsp-announcements on Slack for announcements and support."
     },
     {
       "type": "guideline",
-      "content": "On this page, we’ve addressed some common questions from product developers as Spectrum 2 has rolled out. For more specific, detailed, and up-to-date information about working with a particular implementation, visit its documentation site."
+      "content": "Spectrum Web Components (SWC).\n\nSpectrum Web Components is migrating components to full Spectrum 2 fidelity, meaning components are being rebuilt to look and behave like the Spectrum 2 designs, through a new version of the library and package. Gen1 components ship as versions 1.x, and Gen2 components ship as versions starting at 2.x—so the package version is the simplest way to know which generation you're on. The migration strategy A core principle is that Gen1 and Gen2 components can coexist, so the migration strategy is flexible to meet each team's needs. SWC's first step toward full-fidelity Spectrum 2 was called Spectrum 2 Foundations and is currently available for all Gen1 components. This theme updates the colors, corner radii, and icons of its components to provide the Spectrum 2 look and feel, while supporting backward compatibility with the Spectrum 1 and Express themes. This allowed teams to update closer to Spectrum 2 without introducing breaking changes. Gen2 is the next step in the migration path. These components are being rebuilt from the ground up so components are more stable and flexible, and fully match the Spectrum 2 designs. While these components have some breaking changes, they fully match Spectrum 2 design intent. How to stay up to date All major announcements about Gen2 component availability and releases are made through the project's Slack channels ( #swc-announcements and #spectrum-web-components ). You can track the progress of these migrations by viewing the roadmap. Additional details about Gen1 and Gen2 are available in the project's documentation."
     },
     {
       "type": "guideline",
-      "content": "As of May 2025, Spectrum is in the process of staffing a team to design and build an implementation of Spectrum for Android. Once onboarding wraps up and development begins, the team will begin communication about the status of the new library."
+      "content": "The first phase of Spectrum 2 has been focused on the web. Though Spectrum has always made cross-platform design a priority, the majority of emerging products at Adobe have been web-first in recent years. As such, we’re not ready to share any detailed plans for updates to desktop component libraries such as Qt or Drover. Learn more about desktop and mobile platforms in the FAQs."
     },
     {
       "type": "guideline",
-      "content": "If your team uses design data (like design tokens or CSS custom properties from Spectrum CSS) in any customizations or overrides in your project, you’ll want to keep track of updates to the implementation or design data resource you’re using and plan for time to verify any breaking changes."
+      "content": "iOS.\n\nSpectrum iOS is a Swift-based implementation of Spectrum, offering native components for both UIKit and SwiftUI products. Design and engineering artifacts are versioned together—the Figma library and Swift Package are always in sync—so what you see in Figma is what's available to ship. The team shipped 1.0 and has continued building. Available components include Button, Menu, Picker, Pop-Up Button, Switch, Toggle Button, and Toast, with full Dynamic Type support for typography. The library is actively growing, with more components on the way. Try it on a device The Spectrum iOS Catalog app is the best way to explore what's available—see components in context, feel the interactions, and learn about each component's features and options. Open this link on an iOS device to join: Join the Catalog App on TestFlight Resources Spectrum iOS GitHub Repository Spectrum iOS Figma For questions or to engage with the team, reach out in #spectrum-ios."
     },
     {
       "type": "guideline",
-      "content": "The most important thing you can do — as noted above — is to limit your usage of hard-coded values, direct usage of global tokens, or overriding global tokens via CSS properties/override APIs. Using the correct aliases ensures that components will continue to point to sensible values. In some cases, you may not even notice the change!"
+      "content": "Android.\n\nSpectrum Android is a Kotlin-based implementation of Spectrum, offering native components for Jetpack Compose products. Design and engineering artifacts are versioned together - the Figma library and the Gradle artifacts are always in sync - so what you see in Figma is what's available to ship. As of April 2026, the team is fully staffed with 3 engineers and 1 designer, and is actively building the foundational layers and components for Android in parallel. The first release, Token SDK 1.0, is planned for early June and will ship with Color and Typography tokens so teams can easily consume and use them. Component SDK 1.0 will follow in the subsequent months, bringing the foundational components, Iconography, and accessibility support for building Spectrum experiences on Android. The library is actively growing, with more on the way. Try it on a device The Spectrum Android Catalog app is the best way to explore what's available, see components in context, feel the interactions, and learn about each component's features and options. To join the waitlist, subscribe to the GRP-GCP-0873-READONLY IAM group. You'll receive an invite to preview and download pre-release and release builds via Firebase App Distribution as the library progresses. Resources Spectrum Android Tokens GitHub Repository Spectrum Android Components GitHub Repository For questions or to engage with the team, reach out in #spectrum-android."
+    },
+    {
+      "type": "guideline",
+      "content": "If your team is building a new implementation of Spectrum components, or is using an implementation not mentioned above, please reach out to us in #spectrum-general."
+    },
+    {
+      "type": "guideline",
+      "content": "If your team uses design data (like design tokens or CSS custom properties) in any customizations or overrides in your project, you’ll want to keep track of updates to the implementation or design data resource you’re using and plan for time to verify any breaking changes. The best way to make your current code base ready for the future is to avoid using direct, hard-coded values (e.g., HEX or RGB values) or global tokens (e.g., gray-300). Instead, replace these with more semantic aliases (e.g., negative-border-color-default). The Spectrum Token Visualizer tool is helpful for looking up aliases by the global token they reference. The Spectrum Engineering teams are working on other tools to help with this process — like linters, deprecation warnings, data visualizers, and improved documentation — to help ensure your team makes the best use of the available data. If you’re concerned about the customizations your team made in Spectrum 1 and how Spectrum 2 might impact them, please contact the team for the implementation you’re using through their Slack channel. A full list of Slack channels is available on the Contact page. If you have any questions about what token to use for a particular use case or ideas for improved tooling, please reach out through #spectrum-tokens."
     }
   ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/developer-overview/",
-  "lastUpdated": "2026-02-02",
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/support/developer-overview",
+  "lastUpdated": "2026-09-04",
   "status": "published",
-  "tags": ["developing"],
-  "related": [{ "ref": "motion" }, { "ref": "action-bar" }]
+  "tags": [
+    "Spectrum 2",
+    "React Spectrum",
+    "Spectrum Web Components",
+    "migration",
+    "upgrade migration tool",
+    "Spectrum tokens",
+    "iOS",
+    "Android"
+  ]
 }

package/guidelines/drop-shadow.json

@@ -0,0 +1,56 @@
+{
+  "$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/faqs.json

@@ -8,28 +8,115 @@
     { "type": "purpose", "content": "FAQs" },
     {
       "type": "guideline",
-      "content": "As we progress, we're committed to extending Spectrum 2 to include desktop and mobile platforms with ongoing workshops and to ensure a comprehensive update to our design system."
+      "content": "Spectrum 2 is a significant version update — for both design and engineering — of the Spectrum design system. For more information, view the Introduction page."
     },
     {
       "type": "guideline",
-      "content": "Though Spectrum has always made cross-platform design a priority, the majority of emerging products at Adobe have been web-first in recent years."
+      "content": "The first phase of Spectrum 2 has been focused on the web. If you are working on a product built for a web implementation, you can start using Spectrum 2 today. Remember to work closely with your engineering partners to ensure a smooth implementation. As we progress, we're committed to extending Spectrum 2 to include desktop and mobile platforms with ongoing workshops and to ensure a comprehensive update to our design system."
     },
     {
       "type": "guideline",
-      "content": "That said, Adobe Design has been collectively working on the future of desktop and mobile. One of the central goals of Spectrum 2 is to make sure that it feels “at home.” Both professional desktop and mobile tools have a unique set of requirements and each will get the attention they require."
+      "content": "Though Spectrum has always made cross-platform design a priority, most emerging products at Adobe have been web-first in recent years. That said, Adobe Design has been collectively working on the future of desktop and mobile. One of the central goals of Spectrum 2 is to make sure that it feels \"at home.\" Both professional desktop and mobile tools have a unique set of requirements, and each will get the attention they require. On mobile, that work now has a home on the Spectrum team: Spectrum iOS and Spectrum Android exist as dedicated implementations of Spectrum 2. Neither is complete, but both are actively building, and we continue to expand their scope as the mobile design language matures. On desktop, we've been partnering with desktop teams and preparing their implementations for Spectrum 2 by using Spectrum's design data. We continue to expand the scope of our partnership as we build out Spectrum 2 and the toolchain to support it."
     },
     {
       "type": "guideline",
-      "content": "In the meantime, we’ve been partnering with both desktop and mobile teams and preparing their implementations for Spectrum 2 by using Spectrum’s design data. We continue to expand the scope of our partnership as we build out Spectrum 2 and the toolchain to support it."
+      "content": "Review the Spectrum 2 documentation.\n\nMake sure to regularly review design documentation to keep up-to-date with releases. Familiarize yourself with the changes to components, patterns, styles, and usage guidelines. And most importantly, read the release notes (posted in #spectrum-bulletin ) which explain what’s changed and why."
     },
     {
       "type": "guideline",
-      "content": "Carve out time to plan for the update and create a migration plan. We recommend breaking down the update process into planned, manageable tasks in order to avoid a need to react to massive changes all at once. Prioritize areas of the code base that directly impact the UI, as well as the code that customizes, overrides, or otherwise changes Spectrum defaults."
+      "content": "Perform an UI audit.\n\nConduct an audit of your existing UI components and patterns, specifically identifying the elements that need updating in order to align to Spectrum 2. Evaluate the design of the overall layouts, interaction patterns, and the level of consistency with the new guidelines."
+    },
+    {
+      "type": "guideline",
+      "content": "Create a transition or migration plan.\n\nPartner with your implementation team to develop a plan that outlines the order and priority of updating the components and foundations (such as color and styling). Prioritize the most frequently used components, then create a transition plan that breaks the implementation down into manageable phases. For example, you could start with core components that are used in multiple areas of your product (like buttons). Given that iterative migration plans are most successful, you should expect S1 and S2 design languages to live side-by-side in the same UIs for some period of time. As long as a full migration plan is committed, temporarily mixing design languages is acceptable."
+    },
+    {
+      "type": "guideline",
+      "content": "Apply Spectrum 2 and replace outdated components.\n\nReview the Spectrum 2 Figma libraries and update your components, typography, and icons, among the other changes. As you update your designs, please work with your implementation team on a migration plan. Especially pay attention to components that have changed between Spectrum 1 and Spectrum 2.. Note any custom components in the UI and work with your engineering team to replace any hard-coded values with a semantic alias."
+    },
+    {
+      "type": "guideline",
+      "content": "Collaborate with engineers.\n\nDepending on your product’s implementation, there may be differences between what’s in Figma and code. Work closely with your engineering partners to ensure a smooth implementation of the updated UI. Communicate any changes or updates clearly, provide them with necessary resources, components, or patterns, and address any questions or concerns they may have."
+    },
+    {
+      "type": "guideline",
+      "content": "Collaborate with content strategists.\n\nWork closely with your content strategy partners to ensure that messaging, voice, and tone are being holistically incorporated into interface updates. Work together to create experiences that support your users and communicate clearly about any design updates."
+    },
+    {
+      "type": "guideline",
+      "content": "Breaking changes ahead.\n\nThe update to Spectrum 2 may cause breaking changes. Changes will include updates to colors, renamed tokens in the gray system, updates to corner rounding, and increased padding."
+    },
+    {
+      "type": "guideline",
+      "content": "Modify custom component implementations.\n\nIdentify components in your code base that are customized or not using a standard framework implementation, as those will need manual updating to align with Spectrum 2. If you have custom components, be sure to replace hard-coded values with the appropriate semantic alias. Work with your designers to align custom or product-specific components with the Spectrum 2 design language."
+    },
+    {
+      "type": "guideline",
+      "content": "Review the Spectrum 2 documentation.\n\nMake sure to regularly review documentation to keep up-to-date and monitor releases of your Spectrum implementation. Familiarize yourself with the changes to components, patterns, styles, and usage guidelines. If you author custom components that utilize design data (tokens), it may be helpful to read the release notes (posted in #spectrum-bulletin ) which explain what’s changed and why. Especially pay attention to changes in naming conventions, variables, and overall structure. If you build product UI, monitor the release notes for the implementation your product uses and make sure to update to the latest version at regular intervals. Release announcements for implementations are posted in their respective Slack channels. A full list of channels is available on the Contact page."
+    },
+    {
+      "type": "guideline",
+      "content": "Review your existing code base to ensure you’re using the latest version of a Spectrum implementation. Identify any dependencies that might be affected by the changes, and evaluate if your code is heavily customizing Spectrum components. If so, you may experience breaking changes that need to be reviewed. For more details about your implementation, view our Developer overview page. Carve out time to plan for the update and create a migration plan. We recommend breaking down the update process into planned, manageable tasks in order to avoid a need to react to massive changes all at once. Prioritize areas of the code base that directly impact the UI, as well as the code that customizes, overrides, or otherwise changes Spectrum defaults."
+    },
+    {
+      "type": "guideline",
+      "content": "Collaborate with your designers.\n\nWork with your design partners to develop a plan for testing visual changes, to ensure they align with updated designs that use Spectrum 2."
+    },
+    {
+      "type": "guideline",
+      "content": "Breaking changes ahead.\n\nThe update to Spectrum 2 may cause breaking changes. Please plan ahead with your team to prepare."
+    },
+    {
+      "type": "guideline",
+      "content": "Define a project timeline and an implementation roadmap.\n\nWork with both your design and engineering teams to define a project timeline and break down the migration process. Coordinate and align the efforts of both teams to ensure smooth coordination and avoid disruptions in the development workflow. Set realistic deadlines and milestones to track progress and manage expectations. Reach out to the Spectrum team for help working on a plan."
+    },
+    {
+      "type": "guideline",
+      "content": "Review the Spectrum 2 documentation.\n\nMake sure to regularly review documentation to keep up-to-date with releases. Read the release notes (posted in #spectrum-bulletin ) which explain what’s changed and why."
+    },
+    {
+      "type": "guideline",
+      "content": "Test and validate.\n\nCollaborate with your development or QE team to create a testing plan to validate Spectrum 2. Ensure that Spectrum 2 functions as intended and delivers the desired experience. Address any issues or bugs and coordinate with your design and development teams to implement necessary fixes."
+    },
+    {
+      "type": "guideline",
+      "content": "Facilitate cross-functional collaboration.\n\nEncourage collaboration and open communication between your team’s designers and engineers. Create an environment where your team can discuss challenges, exchange ideas, and share knowledge. Arrange regular meetings or workshops to facilitate cross-functional collaboration, allowing teammates to align on their understanding of Spectrum 2 and have the space to clarify any questions or concerns."
+    },
+    {
+      "type": "guideline",
+      "content": "Attend Spectrum shareouts and trainings.\n\nParticipate in the shareouts and training sessions being organized by the Spectrum team to familiarize yourself with Spectrum 2. These will help you understand the updated design principles, guidelines, and components. And, you’ll learn how to use new design assets, style guides, and tools that apply to your area of focus."
+    },
+    {
+      "type": "guideline",
+      "content": "Review existing assets that use Spectrum.\n\nReview your current marketing materials, banners, or social media graphics to identify design elements that need updating (for example, if your product uses screenshots of UI in your marketing materials or home screens). Take note of any iconography, colors, or imagery that may conflict with Spectrum 2. Apply the Spectrum 2 components across all relevant channels to maintain consistency."
+    },
+    {
+      "type": "guideline",
+      "content": "Review the Spectrum 2 documentation.\n\nRead through this website to understand the changes coming to components, patterns, styles, and usage guidelines. Follow the release notes (posted in #spectrum-bulletin ) for updates."
+    },
+    {
+      "type": "guideline",
+      "content": "Provide feedback.\n\nWhen collaborating with your design team and product leaders throughout the transition process, share insights from your perspective to help refine Spectrum 2 or report any inconsistencies you may come across. Learn about how to reach out."
+    },
+    {
+      "type": "guideline",
+      "content": "The Spectrum team manages Spectrum 2 components and styles as Figma libraries. These are available on the Resources page."
+    },
+    {
+      "type": "guideline",
+      "content": "For general inquiries, post in #spectrum-general or email the Spectrum team. For specific inquiries, view the Contact page for more information on how to get in touch."
     }
   ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/faqs/",
-  "lastUpdated": "2026-02-02",
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/support/faqs",
+  "lastUpdated": "2026-09-04",
   "status": "published",
-  "tags": ["support"],
-  "related": [{ "ref": "steplist" }, { "ref": "contact" }]
+  "tags": [
+    "web",
+    "desktop",
+    "mobile",
+    "Figma",
+    "release notes",
+    "migration plan",
+    "engineering collaboration"
+  ]
 }

package/guidelines/fonts.json

@@ -6,53 +6,68 @@
   "category": "designing",
   "documentBlocks": [
     { "type": "purpose", "content": "Fonts" },
+    { "type": "guideline", "content": "Page last updated: July 31, 2026" },
     {
       "type": "guideline",
-      "content": "Adobe Clean Spectrum VF is Spectrum's primary typeface and an update to Adobe Clean, with more modern metrics for usage in UI and product design. It can be used for Latin-based languages as well as Greek and Cyrillic scripts.\n\n[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EovtJyyD70JGnU6GAFB39a8B0igit__I1kwIOdOQmRdZRg?e=5PaJvw)"
+      "content": "Adobe Clean Spectrum VF is Spectrum’s primary typeface and an update to Adobe Clean, with more modern metrics for usage in UI and product design. It can be used for Latin-based languages as well as Greek and Cyrillic scripts. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Spectrum Serif VF is a companion font to Adobe Clean Spectrum VF, for usage in UI and product design. It can be used for Latin-based languages as well as Greek and Cyrillic scripts.\n\n[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EtGh4hIaNC5BplE0Fpd42aMBucEzpj85P3-uwnQoSS56Zg?e=7rkwnp)"
+      "content": "Adobe Clean Spectrum Serif VF is a companion font to Adobe Clean Spectrum VF, for usage in UI and product design. It can be used for Latin-based languages as well as Greek and Cyrillic scripts. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean is Adobe's corporate typeface. It can be used for Latin-based languages as well as Greek and Cyrillic scripts.\n\n[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EtE69FE1M5NNssssA8MUktcB69v3tyM8x9mz-Qs9sHmG3g?e=cbftOo)"
+      "content": "Adobe Clean is Adobe’s corporate typeface. It can be used for Latin-based languages as well as Greek and Cyrillic scripts. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Serif is a companion font family to Adobe Clean. It covers most Latin-based languages as well as Greek and Cyrillic scripts.\n\n[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/Ej0pcVTelONCqghOsr5W4EwBWX-tOlQl4jx8iuHPHHatIQ?e=wvXNfq)"
+      "content": "Adobe Clean Serif is a companion font family to Adobe Clean. It covers most Latin-based languages as well as Greek and Cyrillic scripts. Download font"
     },
     {
       "type": "guideline",
-      "content": "Source Code Pro is used to display code snippets, either inline with another typeface or as a standalone block.\n\n[Download from Github](https://github.com/adobe-fonts/source-code-pro)"
+      "content": "Source Code Pro is used to display code snippets, either inline with another typeface or as a standalone block. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Han is a version of Adobe Clean supporting ideographic scripts – Chinese (Simplified and Traditional), Japanese, and Korean.\n\n[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EsY41oy5pZxNlTrUwlEw-iYBthO9_oR9e1mzSSr_pFLCuw?e=d2Pd6m)"
+      "content": "Adobe Clean Han is a version of Adobe Clean supporting ideographic scripts – Chinese (Simplified and Traditional), Japanese, and Korean. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Thai is used for setting the Thai script, in both looped and loopless styles.\n\n[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/ErsoedmOVINBqpzUC1CTu8gBfZrAeEQ1pKq6gwHHYIN7Dg?e=8GtE7b)"
+      "content": "Adobe Clean Thai is used for setting the Thai script, in both looped and loopless styles. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Arabic is used for the Arabic language, as well as other languages using the Arabic script, such as Persian.\n\n[Download font](https://adobe.sharepoint.com/sites/Spectrum/Design%20files/Forms/AllItems.aspx?id=%2Fsites%2FSpectrum%2FDesign%20files%2FSpectrum%20fonts%2FAdobe%20Clean%20Arabic\\&p=true\\&ga=1)"
+      "content": "Adobe Clean Arabic is used for the Arabic language, as well as other languages using the Arabic script, such as Persian. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Hebrew is used for modern Hebrew typesetting.\n\n[Download font](https://adobe.sharepoint.com/sites/Spectrum/Design%20files/Forms/AllItems.aspx?id=%2Fsites%2FSpectrum%2FDesign%20files%2FSpectrum%20fonts%2FAdobe%20Clean%20Hebrew\\&p=true\\&ga=1)"
+      "content": "Adobe Clean Hebrew is used for modern Hebrew typesetting. Download font"
     },
     {
       "type": "guideline",
-      "content": "Adobe Clean Devanagari supports the Devanagari script, which is used for Hindi and Marathi languages.\n\n[Download font](https://adobe.sharepoint.com/sites/Spectrum/Design%20files/Forms/AllItems.aspx?id=%2Fsites%2FSpectrum%2FDesign%20files%2FSpectrum%20fonts%2FAdobe%20Clean%20Devanagari\\&p=true\\&ga=1)"
+      "content": "Adobe Clean Devanagari supports the Devanagari script, which is used for Hindi and Marathi languages. Download font"
     },
     {
       "type": "guideline",
-      "content": "These resources are [restricted fonts](https://www.adobe.com/products/type/font-licensing/restricted-fonts.html) for the exclusive use of Adobe products and software. They should only be used through Adobe Fonts (not self-hosted). For instructions, view [Using Adobe Fonts at Adobe](https://wiki.corp.adobe.com/display/fonts/Using+Adobe+Fonts+at+Adobe)."
+      "content": "Adobe Clean Display is a companion typeface to Adobe Clean, and is mostly used for branding and marketing experiences. It is available only for Latin-based languages. For more information about using Clean Display in Marketing applications, view Usage guidelines in the RED Brand book. Adobe Clean Display is available through Adobe Fonts. For instructions, view Using Adobe Fonts at Adobe."
+    },
+    {
+      "type": "guideline",
+      "content": "These resources are restricted fonts for the exclusive use of Adobe products and software. They should only be used through Adobe Fonts (not self-hosted). For instructions, view Using Adobe Fonts at Adobe."
     }
   ],
-  "sourceUrl": "https://s2.spectrum.corp.adobe.com/page/fonts/",
-  "lastUpdated": "2026-02-02",
+  "sourceUrl": "https://main--spectrum-hub--adobe.aem.live/foundations/typography/fonts",
+  "lastUpdated": "2026-09-10",
   "status": "published",
-  "tags": ["designing"]
+  "tags": [
+    "Adobe Clean Spectrum",
+    "Spectrum fonts",
+    "Adobe Fonts",
+    "Typekit",
+    "Latin-based languages",
+    "Greek",
+    "Cyrillic",
+    "Adobe Clean Han",
+    "Source Code Pro"
+  ]
 }