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, we have included the component-level mappings for:

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

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 dist/css/components folder contains the component-level mappings for Spectrum 1, Express, and Spectrum 2. These assets 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.

Components

Assets in this folder must be loaded together in order for the randomly generated system variables to line up.

`bridge`

index.css: everything in the folder rolled up into 1 file.
<component>.css: mappings from local component classes (i.e. .spectrum-ActionBar.spectrum-ActionBar--quiet) to system variables.

These assets must be loaded with one of the matching <component>.css files for the desired context, i.e., dist/css/components/express/<component>.css or dist/css/components/spectrum/<component>.css

`spectrum-two`

index.css: Everything in the folder rolled up into 1 file
<component>.css:
- All properties in these assets are attached to a specific root-level class: .spectrum.
- System variables are mapped to global token variables or custom values (i.e. transparent or 10px, values not present in the token system).

These assets must be loaded with the global token definitions found in this package at the following paths: - dist/css/global-vars.css - dist/css/*-vars.css: load only those assets relevant to the application context

`express`

Same contents as the spectrum-two folder but instead of .spectrum, properties are attached to .spectrum--express.

Note: Do not load these assets with the dist/css/global-vars.css or dist/css/*-vars.css files. Instead, load global token definitions from the last version of the tokens package: v14.x: i.e.,

@spectrum-css/tokens@v14.x: dist/css/global-vars.css
@spectrum-css/tokens@v14.x: dist/css/*-vars.css

When loading express styles, the following assets must be loaded last or be altered to use higher specificity:

@spectrum-css/tokens@v14.x: dist/css/express/global-vars.css
@spectrum-css/tokens@v14.x: dist/css/express/*-vars.css

`spectrum`

Same contents as the spectrum-two folder but instead of .spectrum, properties are attached to .spectrum--legacy.

@spectrum-css/tokens@v14.x: dist/css/global-vars.css
@spectrum-css/tokens@v14.x: dist/css/*-vars.css

When loading legacy spectrum styles, the following assets must be loaded last or be altered to use higher specificity:

@spectrum-css/tokens@v14.x: dist/css/spectrum/global-vars.css
@spectrum-css/tokens@v14.x: dist/css/spectrum/*-vars.css

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 14 Oct 2024

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