@adobe/spectrum-design-data 3.3.0 → 3.4.0

package/guidelines/design-tokens.json

@@ -0,0 +1,186 @@
+{
+  "$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": "Spectrum design tokens follow three core principles. Image: Stylized 3D icon of an eye with a peach-orange gradient, featuring a simplified almond-shaped outline and a comma-shaped iris, on a soft white background. (source: https://spectrum.adobe.com/foundations/design-data/media_140076ee4f57925def9ca2b4328ba49def5e3262b.png?width=750&format=png&optimize=medium) Image: Stylized 3D icon of a curved S-shaped ribbon with rounded, flared ends, in a pink-to-purple gradient, on a soft white background. (source: https://spectrum.adobe.com/foundations/design-data/media_1a708190100c5bb32bfcf5424787034563655c4bd.png?width=750&format=png&optimize=medium) Image: Stylized 3D icon of a graduation cap with a blue gradient, rendered with soft rounded edges and a tassel hanging from one corner, on a soft white background. (source: https://spectrum.adobe.com/foundations/design-data/media_16d9fc083f6378798d3114f10f579387c88e02000.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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. Image: Nested concentric semicircle diagram illustrating a design system hierarchy, with \"Products\" as the outermost layer, \"Platform components\" in the middle, and \"Tokens\" at the innermost core, rendered in purple gradient tones. (source: https://spectrum.adobe.com/foundations/design-data/media_1c3063afa864ec179a458d95d51558937b4bc43ed.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Understanding a few foundational concepts makes design tokens easier to read, discuss, and use."
+    },
+    {
+      "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": "Image: Code snippet showing a JSON token definition for \"accent-content-color-default,\" including its schema reference, a value pointing to \"{accent-color-900},\" and a UUID. (source: https://spectrum.adobe.com/foundations/design-data/media_180c6be1720908c84590aced0e4ea46ec42d8c386.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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": "Image: Three example design tokens labeled \"Token name,\" each pointing to a specific token: a blue color swatch named \"blue-900\" with value rgb(59, 99, 251); a ruler icon for \"base-padding-vertical-large\" with value 10px; and a font icon for \"sans-serif-font-family\" with value \"Adobe Clean Spectrum VF.\" (source: https://spectrum.adobe.com/foundations/design-data/media_16849d171f58f0ed54185afd8a10028da399cd46c.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Image: Three tokens—\"blue-900\" (rgb(59, 99, 251)), \"base-padding-vertical-large\" (10px), and \"sans-serif-font-family\" (Adobe Clean Spectrum VF)—each with their resolved output highlighted and labeled \"Value.\" (source: https://spectrum.adobe.com/foundations/design-data/media_18b43d82026c0f02530b5ce62978951a800a60d4c.png?width=750&format=png&optimize=medium).\n\nToken name Value 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."
+    },
+    {
+      "type": "guideline",
+      "content": "Image: Diagram showing a token aliasing chain: the base color token \"blue-900\" ( #3B63FB) flows down through an alias called \"accent-color-900,\" which in turn flows into a further alias called \"accent-content-color-default.\" (source: https://spectrum.adobe.com/foundations/design-data/media_11cea602f9ef5940fc07648edb357982ec8e90c5f.png?width=750&format=png&optimize=medium).\n\nToken name Value (alias) accent-content-color-default accent-color-900"
+    },
+    {
+      "type": "guideline",
+      "content": "Spectrum uses multiple token tiers to represent design decisions at different levels of abstraction. Each tier serves a different purpose, and together they create a flexible system that supports both reuse and adaptation."
+    },
+    {
+      "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": "Image: Two token scales side by side: a vertical blue color ramp from light to dark labeled \"blue-900\" at its mid-dark point, and a vertical spacing scale of gray squares increasing in size labeled \"spacing-400\" at a mid-sized square. (source: https://spectrum.adobe.com/foundations/design-data/media_179482299e81daea4dfee0b8609e53447561d4bbb.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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": "Image: Diagram showing the token \"accent-content-color-default\" branching out to five UI examples that use it: a radio button label, a checkbox label, a toggle switch label, a hyperlink, and a menu item checkmark—all rendered in the same blue. (source: https://spectrum.adobe.com/foundations/design-data/media_1dc05f4cd2a0071e6256b9da67fd14f92340485e7.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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": "Image: Diagram showing the token \"tab-gap-horizontal-medium\" pointing to the pink-highlighted gap between two radio button labels in a UI example. (source: https://spectrum.adobe.com/foundations/design-data/media_1de0d50e78fdc61dfc5ba6ac5e78ab4db2ea9bbdf.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Design decisions are most valuable when they can be reused. Rather than organizing decisions around individual components, Spectrum organizes many design decisions around semantic meaning and reusable structures. Together, these concepts help create a shared language that is easier to understand, reuse, and scale across products and platforms. Image: Diagram connecting the token \"positive-background-color-default\" (green) to a green toast notification example reading \"Toast message describing what happened,\" which in turn branches out to four reusable spacing tokens: banner-padding-vertical, banner-padding-horizontal, banner-padding-horizontal-compact, and banner-gap-horizontal. (source: https://spectrum.adobe.com/foundations/design-data/media_12317944fcdcd3d94db4c7d4e9d74465e032ba123.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Image: Diagram grouping UI examples by feedback type: \"Positive\" links to a green \"Approved\" tag and a password field with a matching-passwords confirmation; \"Negative\" links to a red \"Rejected\" tag and a password field showing a \"Passwords do not match\" error with a red tooltip; \"Informative\" links to a blue \"Active\" tag and a blue tooltip. (source: https://spectrum.adobe.com/foundations/design-data/media_1492d46785f384e217b76912d774fa3f5b96d6b28.png?width=750&format=png&optimize=medium).\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."
+    },
+    {
+      "type": "guideline",
+      "content": "Image: Diagram grouping UI components by structure type: \"Base\" links to individual elements like an \"Approved\" tag, a value field, a delete button, a list item, and a stepper; \"Group\" links to sets of related elements like paired radio buttons, toggles, and stacked checkboxes. (source: https://spectrum.adobe.com/foundations/design-data/media_129333dbe5f3c9919f4aa947c23a26c2453169a48.png?width=750&format=png&optimize=medium).\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 Base The primary functional element within a structure Accessory A supporting element associated with another structure Group A collection of related elements List A sequence of repeated items Container A structure that organizes content Banner A structure used for prominent messaging These 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. Image: Diagram showing how reusable structures combine into compositions and then components: a \"Base\" structure and a \"List item\" structure each flow into composition examples with labels, descriptions, and toggles, which then combine into a finished \"Menu item\" component with a value and toggle. (source: https://spectrum.adobe.com/foundations/design-data/media_19eceefe7f3c359ba6f591936e3bf009582d70ea1.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Token names are designed to communicate the purpose of a design decision. Reading a token name from left to right reveals progressively more specific context about how that decision should be used. Names communicate information from broad concepts toward more specific details. Image: Diagram breaking down the token name \"positive-color-600,\" with callouts showing that \"positive\" indicates what's communicated and \"600\" indicates which color option is used, next to a green color swatch. (source: https://spectrum.adobe.com/foundations/design-data/media_1d58375a6ae7a9f1fc730f649f485123c2614161a.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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. Image: Diagram breaking down the token name \"accent-background-color-hover,\" with callouts showing that \"accent\" indicates what's communicated, \"background-color\" indicates what it affects, and \"hover\" indicates when it applies, next to a blue color swatch. (source: https://spectrum.adobe.com/foundations/design-data/media_138f950047d55d3e1a89f6f1cbd0b22558cab1ca2.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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. Image: Diagram breaking down the token name \"base-padding-vertical-small,\" with callouts showing that \"base\" indicates where it applies, \"padding-vertical\" indicates what it affects, and \"small\" indicates which option is used. (source: https://spectrum.adobe.com/foundations/design-data/media_1a19e41620a76ada5ceae2dbb74a4778609a34e35.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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": "Design tokens are intended to make design decisions easier to find, understand, and apply consistently. The following guidelines can help you choose appropriate tokens, avoid common mistakes, and build experiences that remain aligned with the broader Spectrum design language."
+    },
+    {
+      "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. Image: Diagram tracing the token \"Spectrum Button\" to a purple-to-blue gradient \"Upgrade\" button with a crown icon, and further down to a plain rounded rectangle in the same gradient with no label. (source: https://spectrum.adobe.com/foundations/design-data/media_1fe9a6362a1479a1f5959aced7df1ca13884e86b1.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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. Image: Diagram connecting the token \"background-layer-2-color\" to the light gray toolbar background of a Photoshop-style document window, showing a hamburger menu, the Photoshop app icon, \"Document\" text, and a cloud icon. (source: https://spectrum.adobe.com/foundations/design-data/media_1b62af86b141ebe7a61e41687f36c25c542915749.png?width=750&format=png&optimize=medium) Image: Diagram connecting the token \"gray-25\" to the light gray toolbar background of a Photoshop-style document window, showing a hamburger menu, the Photoshop app icon, \"Document\" text, and a cloud icon. (source: https://spectrum.adobe.com/foundations/design-data/media_1c851b0861fdf571ce6a19a98cbca1ef0be7c5f48.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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. Image: Diagram connecting the token \"static-fuchsia-900,\" shown as a purple circle swatch, to a purple-to-blue gradient \"Upgrade\" button with a crown icon. (source: https://spectrum.adobe.com/foundations/design-data/media_1ddaad670f23bdc8178d3642bf345d2c4bb13737a.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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. Image: Diagram showing the token \"tab-gap-horizontal-medium\" pointing to the pink-highlighted gap between two radio button labels in a UI example. (source: https://spectrum.adobe.com/foundations/design-data/media_1de0d50e78fdc61dfc5ba6ac5e78ab4db2ea9bbdf.png?width=750&format=png&optimize=medium) Image: Diagram showing the token \"tab-gap-horizontal-medium\" pointing to the pink-highlighted gap between two colorful gradient card components, each with a card title and description. (source: https://spectrum.adobe.com/foundations/design-data/media_111549edcd66a118c25888112eb46457758a1d42d.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "type": "guideline",
+      "content": "Spectrum supports many products and platforms, each with different requirements. As the token system evolves, Spectrum is establishing a shared foundation of reusable design decisions that can support platform-specific adaptation while maintaining a common design language."
+    },
+    {
+      "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. Image: Diagram illustrating a design system's flexible structure: a purple diamond labeled \"Spectrum Foundations\" and a green pentagon labeled \"Platform\" combine under \"Flexible implementation,\" where the shapes overlap with dashed red gaps highlighted, resulting in \"Spectrum Platform\" — a purple pentagon that fully fills the green pentagon's shape. (source: https://spectrum.adobe.com/foundations/design-data/media_1098f8070212b263e4d2aaeae48257cb8a3c74623.png?width=750&format=png&optimize=medium) Design data can be re-shaped to fit platform needs while maintaining system cohesion."
+    }
+  ],
+  "sourceUrl": "https://spectrum.adobe.com/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,52 @@
     { "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": "Spectrum 2 is available for web-based Spectrum implementations before other platforms like desktop or mobile. There are two primary implementations of Spectrum for web: React Spectrum (RSP) and Spectrum Web Components (SWC). Both of these implementations currently support Spectrum 2 in some form."
     },
     {
       "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": "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": "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": "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": "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": "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": "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": "Mobile support for Spectrum 2 is currently in progress on both Spectrum iOS and Spectrum Android."
+    },
+    {
+      "type": "guideline",
+      "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": "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,76 @@
+{
+  "$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": "Image: An orange rounded diamond outline with a faint reflection beneath it, illustrating how drop shadow creates a sense of elevation above the surface. (source: https://spectrum.adobe.com/foundations/styles/object-styles/media_1fd2551bf64f7d1ba1e4a78bccbfab61dfe691906.png?width=750&format=png&optimize=medium) Image: A 2x2 grid of rounded square icons where the bottom-left square is highlighted with a purple gradient and stronger shadow, illustrating how drop shadow supports visual emphasis. (source: https://spectrum.adobe.com/foundations/styles/object-styles/media_15bd648d872cc9d7f466b226213858ea74155a8e0.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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 shadows are most commonly used when content appears above other content, such as popovers and floating panels. They can also emphasize important interface elements, helping maintain a clear visual hierarchy and consistent sense of depth. Each shadow style is intended for a specific visual purpose. Image: Four rounded white squares numbered 1 through 4 with progressively larger and softer drop shadows, illustrating a scale of shadow depth values. (source: https://spectrum.adobe.com/foundations/styles/object-styles/media_1eb322c7f4517cac9f255fac8142ee3406aaa4637.png?width=750&format=png&optimize=medium) Emphasized, default In certain situations, drop shadows can also be used to provide emphasis to containers within a page. When used appropriately, content that requires more attention will visually stand out, as if it’s slightly elevated or above other content. Emphasized, hover If a whole container is interactive, such as in a select box, the drop shadow becomes emphasized-hover on hover. Elevated Containers that appear on top of content, such as menus and tooltips, have drop shadows to show elevation. Dragged Containers don't use drop shadows by default. When a container is dragged, a drop shadow is applied to indicate that it has been lifted above the interface. This behavior applies to both default and emphasized containers."
+    },
+    { "type": "guideline", "content": "Drop shadow details" },
+    {
+      "type": "guideline",
+      "content": "Image: A stack of three rounded diamond shapes labeled 1, 2, and 3, illustrating the layered composition of a drop shadow effect. (source: https://spectrum.adobe.com/foundations/styles/object-styles/media_1e55ad9fc6b8cfceff097a32b46183149d33d9353.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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": "Image: A dark-theme context menu titled \"Publish and export\" with options for Quick export, Open a copy, and Share link, showing a submenu with Illustrator for iPad and Illustrator desktop, each panel using shadow to convey layering. (source: https://spectrum.adobe.com/foundations/styles/object-styles/media_1a3fef3a1425a17547ec0a976a66ac1b4fbf475bd.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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": "Image: A card UI with an image header and placeholder text lines, shown with a drop shadow against a gray background to illustrate shadow overlay on a light surface. (source: https://spectrum.adobe.com/foundations/styles/object-styles/media_16e79c0908d8d8b02aeb26adfa231019beaac6661.png?width=750&format=png&optimize=medium)"
+    },
+    {
+      "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 style Token Key values Transition values Ambient values Emphasized, default drop-shadow-emphasized X = 0 Y = 0 Blur = 1 Spread = 0 X = 0 Y = 1 Blur = 4 Spread = 0 X = 0 Y = 2 Blur = 8 Spread = 0 Emphasized, hover drop-shadow-emphasized-hover X = 0 Y = 0 Blur = 2 Spread = 0 X = 0 Y = 2 Blur = 6 Spread = 0 X = 0 Y = 4 Blur = 12 Spread = 0 Elevated drop-shadow-elevated X = 0 Y = 0 Blur = 2 Spread = 0 X = 0 Y = 2 Blur = 6 Spread = 0 X = 0 Y = 4 Blur = 12 Spread = 0 Dragged drop-shadow-dragged X = 0 Y = 0 Blur = 6 Spread = 0 X = 0 Y = 6 Blur = 8 Spread = 0 X = 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 color Token Opacity values Emphasized (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://spectrum.adobe.com/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,119 @@
     { "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": "Review our Developer overview page for detailed information about developing with Spectrum 2."
+    },
+    {
+      "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"
+  ]
 }