Introducing Spectrum 2 – a new update to Adobe's design system, now in pre-release! Designed to support our growing suite of products, Spectrum 2 aims to work seamlessly across experiences by balancing personality and function.
+The React Spectrum team has been hard at work to bring the Spectrum 2 design to our components. Spectrum 2 in React Spectrum is built on React Aria Components and a new styling foundation powered by Spectrum Tokens. This gives you access to Spectrum design fundamentals such as colors, spacing, sizing, and typography in your own applications and custom components. Spectrum 2 also brings new features such as t-shirt sizing, improved form layout, dynamic new press interactions, and more.
+Check out the new Button design, with fresh new colors and icons, a fun new press scaling interaction, and support for t-shirt sizes.
+Spectrum 2 switches have a more accessible design, with a solid border and new animations.
+Dialogs have a refreshed design with more pronounced rounding, and improved layout.
+Menus received a major design update, with new styles for sections, links, selection, focus rings, and submenus.
+Getting started
+Installation
+Spectrum 2 in React Spectrum can be installed from npm:
+yarn add @react-spectrum/s2+
Configuring your bundler
+React Spectrum supports styling via macros, a new bundler feature that enables functions to run at build time. Currently, Parcel v2.12.0 and newer supports macros out of the box. When using other build tools, you can install a plugin to enable them.
+See below to learn more about using the React Spectrum style macro.
Webpack, Next.js, Vite, Rollup, or ESBuild
+First, install unplugin-parcel-macros using your package manager:
+yarn add unplugin-parcel-macros --dev+
Then, configure your bundler according to the steps documented in the readme. Note that plugin order is important: unplugin-parcel-macros must run before other plugins like Babel.
You may also need to configure other tools such as TypeScript, Babel, ESLint, and Jest to support parsing import attributes. See these docs for details.
+See the examples folder in our repo for working setups with various build tools.
+Setting up your app
+Unlike React Spectrum v3, a Provider is not required. Instead, import @react-spectrum/s2/page.css in the entry component of your app to apply the background color and color scheme to the {''} element. This ensures that the entire page has the proper styles even before your JavaScript runs.
{highlight(`import '@react-spectrum/s2/page.css';
+import {Button} from '@react-spectrum/s2';
+
+function App() {
+ return (
+
+ );
+}`)}
+ Note: If you’re embedding Spectrum 2 as a section of a larger page rather than taking over the whole window, follow the directions below instead of using page.css.
Overriding the color scheme
+By default, the page follows the user’s operating system color scheme setting, supporting both light and dark mode. The page background is set to the base Spectrum background layer by default. This can be configured by setting the data-color-scheme and data-background attributes on the {''} element. For example, to force the application to only render in light mode, set data-color-scheme="light".
{highlight(`
+
+`)}
+ Overriding the locale
+By default, React Spectrum uses the browser/operating system language setting for localized strings, date and number formatting, and to determine the layout direction (left-to-right or right-to-left). This can be overridden by rendering a {' component at the root of your app, and setting the locale prop.
{highlight(`import {Provider} from '@react-spectrum/s2';
+
+ {/* your app */}
+ `)}
+ Embedded sections
+If you’re building an embedded section of a larger page using Spectrum 2, use the {' component to set the background instead of importing page.css. The background prop should be set to the Spectrum background layer appropriate for your app, and the colorScheme can be overridden as well.
{highlight(`import {Provider} from '@react-spectrum/s2';
+
+ {/* your app */}
+ `)}
+ Styling
+React Spectrum v3 supported a limited set of style props for layout and positioning using Spectrum-defined values. In Spectrum 2, we’re improving on this by offering a much more flexible style macro. This offers additional Spectrum tokens, improves performance by generating CSS at build time rather than runtime, and works with any DOM element for use in custom components.
+Macros are a new bundler feature that enable functions to run at build time. The React Spectrum style macro uses this to generate CSS that can be applied to any DOM element or component. Import the style macro using the with {`{type: 'macro'}`} import attribute, and pass the result to the styles prop of any React Spectrum component to provide it with styles.
{highlight(`import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {ActionButton} from '@react-spectrum/s2';
+
+
+ Edit
+ `)}
+ The styles prop accepts a limited set of CSS properties, including layout, spacing, sizing, and positioning. Other styles such as colors and internal padding cannot be customized within Spectrum components.
Supported CSS properties on Spectrum components
+-
+
margin
+ marginStart
+ marginEnd
+ marginTop
+ marginBottom
+ marginX
+ marginY
+ width
+ minWidth
+ maxWidth
+ flex
+ flexGrow
+ flexShrink
+ flexBasis
+ justifySelf
+ alignSelf
+ order
+ gridArea
+ gridRow
+ gridRowStart
+ gridRowEnd
+ gridColumn
+ gridColumnStart
+ gridColumnEnd
+ position
+ zIndex
+ top
+ bottom
+ inset
+ insetX
+ insetY
+ insetStart
+ insetEnd
+
UNSAFE Style Overrides
+We highly discourage overriding the styles of React Spectrum components because it may break at any time when we change our implementation, making it difficult for you to update in the future. Consider using React Aria Components with our style macro to build a custom component with Spectrum styles instead.
+That said, just like in React Spectrum v3, the UNSAFE_className and UNSAFE_style props are supported on Spectrum 2 components as last-resort escape hatches. However, unlike in v3, UNSAFE_classNames must be placed in a special UNSAFE_overrides CSS cascade layer. This guarentees that your overrides will always win over other styles on the page, no matter the order or specificity of the selector.
{highlight(`/* YourComponent.tsx */
+import {Button} from '@react-spectrum/s2';
+import './YourComponent.css';
+
+function YourComponent() {
+ return ;
+}`)}
+ {highlight(`/* YourComponent.css */
+@layer UNSAFE_overrides {
+ /* Wrap all UNSAFE_className rules in this layer. */
+ .your-unsafe-class {
+ background: red;
+ }
+}`, 'CSS')}
+