@spectrum-web-components/theme

Overview

provides Spectrum design tokens (CSS custom properties) to everything in its DOM scope. Components inside a theme use these tokens to render correctly. The element itself does not visually “apply” styles to your app; it exposes the tokens so your components (and any of your CSS) can consume them.

Spectrum offers multiple variants:

- System: spectrum, express, spectrum-two
- Color: light, dark (legacy: lightest, darkest – deprecated)
- Scale: medium, large

By default, uses the spectrum system, light color, and medium scale.

$3

Visually, all Spectrum Web Components are an expression of the design tokens specified by Spectrum, Adobe's design system. On the web, these tokens are made available as CSS Custom Properties. Using sp-theme as a parent element for your components ensures that those CSS Custom Properties can be leveraged by the elements within your application. This ensures consistent delivery of not only the color and scale you've specified in your particular instance, but for _all_ the other color, scale, and content direction specifications across Spectrum.

Additionally, the sp-theme element manages the content direction applied to the elements in its DOM scope. By default, an sp-theme element resolves its initial content direction from the value specified by its first sp-theme or document ancestor; otherwise, it uses the value dir="ltr" if a content direction isn't present in those elements. When a value for dir is manually supplied to sp-theme, the default value is overridden. In all cases, though, sp-theme manages the dir value of its SpectrumElement descendents, unless another sp-theme element is placed into its scope and overrides that management.

To make the above concepts a little more concrete, take a look at the table below. Try selecting another color in the picker, and notice how that changes the values of the colors. The token names for the variables persist, but the RGB values under the hood change! Considering that sp-theme also manages all the other theme and size options, sp-theme reveals itself to be a pretty powerful component.

When you're ready to look into more advanced usage of the components and themes in your application, there are vanilla CSS implementations of these tokens available in the @spectrum-web-components/styles package.

$3


``bash
yarn add @spectrum-web-components/theme
`

Register the element and load the theme fragments you intend to use:

`js
// Registers the custom element
import '@spectrum-web-components/theme/sp-theme.js';

// Load the specific variants you will use (recommended)
import '@spectrum-web-components/theme/theme-light.js';
import '@spectrum-web-components/theme/scale-medium.js';
// Optionally choose a different system
// import '@spectrum-web-components/theme/express/theme-light.js';
// import '@spectrum-web-components/theme/express/scale-medium.js';
`

If you’re prototyping and want everything available:

`js
import '@spectrum-web-components/theme/sp-theme.js';
import '@spectrum-web-components/theme/src/themes.js'; // spectrum
import '@spectrum-web-components/theme/src/express/themes.js'; // express
import '@spectrum-web-components/theme/src/spectrum-two/themes.js'; // spectrum-two
`

$3

#### Light color, medium scale

`html




The large scale of will switch to using Spectrum's larger mobile Platform Scale.

`html




`html




`js
const themeEl = document.querySelector('sp-theme');

async function updateTheme(system, color, scale) {
const systemBase = system === 'spectrum' ? '' : ${system}/;
await Promise.all([
import(@spectrum-web-components/theme/${systemBase}theme-${color}.js),
import(@spectrum-web-components/theme/${systemBase}scale-${scale}.js),
]);
themeEl.system = system;
themeEl.color = color;
themeEl.scale = scale;
}

updateTheme('spectrum', 'light', 'medium');
`

When bundling your application, be sure to consult the documentation of your bundler for the correct way to ensure proper packaging of the programatic dependency graph that this will create.

#### Language context

Descendants can request the current language by dispatching sp-language-context with a callback. The callback is re-invoked when the theme’s lang changes. This way, you can control the resolved language in , , and other elements in one centralized place.

`ts
// in a descendant component
this.dispatchEvent(
new CustomEvent('sp-language-context', {
bubbles: true,
composed: true,
detail: {
callback: (lang, unsubscribe) => {
this.lang = lang; // use the language value
// call unsubscribe() when you no longer need updates
},
},
})
);
`

$3

- Color and contrast: Ensure sufficient contrast for any backgrounds you apply when consuming tokens (WCAG 2.1 AA). Components themselves meet Spectrum guidance when themed correctly.
- Language: Set lang on to inform number/date formatting and other locale-aware components.
- Directionality: Use dir` to deliver correct LTR/RTL behavior; embedded themes allow mixing contexts.