Core tokens: The base set of design data that define the system. These are the key-value pairs that are used to build the design system and are sourced from the design team via @adobe/spectrum-tokens. You can find the relevant versioning information in the package.json file.
Custom properties: These are CSS variables generated from the core tokens using the StyleDictionary build process. These are used in the CSS base styles to apply the design system to the components in a way that can respond to changes in color, scale, or context.
Context: This terms refers to the design language an application wants to use. Contexts previously supported were Spectrum and Express. The current system supports only Spectrum but has committed to offering backward compatibility through at least December 2024.
Color: This term refers to the color mode. The current system supports light and dark only. The lightest and darkest color modes were deprecated in the final version for 14.x.
Scale: This term refers to the scale of the design system. The current system supports medium and large scales. The large scale is used for mobile applications and the medium scale is used for desktop applications.
System variables: These are randomly generated variable names (prefixed with --system) that are used to map the component-level class styles to the core tokens from the desired context. These are generated by the postcss-add-theming-layer plugin as part of the build and should not be relied upon for naming consistency across releases. Do not attempt to overwrite or extend these variables in your application.

Backwards compatibility for Spectrum 1 and Express

Though the token data in this package focus on only the current context (Spectrum 2), our team is committed to offering backwards compatibility for Spectrum 1 and Express through at least December of 2024.

To this end, every component that requires backward mapping support will include:

Spectrum 1: dist/themes/spectrum.css
Express: dist/themes/express.css
Spectrum 2: dist/themes/spectrum-two.css

Consumers should load only the mappings for the components they are using in their application. This will ensure that the component-level mappings are aligned with the base CSS for each component. Spectrum 1 and Express component mappings should be loaded with the global-vars.css and appropriate color and scale assets from the last version of the tokens package: v14.x. Loading the Spectrum 1 or Express component-level mappings with the Spectrum 2 global variables will result in incorrect values being applied to the components and will break the desired design for the component.

Usage

The output is concatenated into a single dist/index.css for use in a vanilla HTML application. This entire file should be imported, and the relevant classes should be toggled to swap out core tokens.

On the <body> element, start with .spectrum, add in .spectrum--light, then .spectrum--medium. To switch to another context, add .spectrum--legacy or .spectrum--express.

For additional guidance on which assets to load, see the architecture section below.

Architecture

All compiled assets are shipped from the dist folder. Most of the assets are available in the dist/css folder. The component-level mappings for Spectrum 1, Express, and Spectrum 2 exist in the components output as theme assets. These should be loaded with the appropriate global variables and color and scale assets from the last version of the tokens package: v14.x.

Global core tokens

global-vars.css: Shared global, unchanging tokens.
light-vars.css: Tokens specific to the light color.
dark-vars.css: Tokens specific to the dark color.
medium-vars.css: Tokens specific to the medium (desktop) scale.
large-vars.css: Tokens specific to the large (mobile) scale.
index.css: The above files rolled up into 1 css file for convenience; best for use in a vanilla HTML application.

Overrides and additions

Overrides and additions to core tokens can be added to custom/*-vars.css.

Ensure that you add new values to the appropriate color, or scale file:

global-vars.css - Shared global, unchanging tokens
light-vars.css - Tokens specific to the light color
dark-vars.css - Tokens specific to the dark color
medium-vars.css - Tokens specific to the medium (desktop) scale
large-vars.css - Tokens specific to the large (mobile) scale

Values added here will be copied over and concatenated with the custom properties being generated from the core tokens by StyleDictionary.

Breaking changes from v14 to v15

There are no additional contextual folders (i.e., dist/css/spectrum/) because this package supports no other theming systems outside of the component token mappings. All global tokens are found in the dist/css folder.

For more notes on how the token data has changed, see the @adobe/spectrum-tokens release documentation.

Keywords

FAQs

What is @spectrum-css/tokens?

Is @spectrum-css/tokens popular?

Is @spectrum-css/tokens well maintained?

Package last updated on 12 Feb 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@spectrum-css/tokens