Spectrum Tokens

Generated legacy output. @adobe/spectrum-tokens is generated from the canonical data in packages/design-data and kept for existing npm consumers. schemas/ and naming-exceptions.json are generated copies (sources: design-data-spec/schemas and design-data/naming-exceptions.json). Don't build new tooling on this package; see .ai/rules/legacy-tokens.md.

Design tokens are primarily name-value pairs used to store design decisions and distributed in a way platforms, implementations, and products can use across design tools and coding languages. These value types are represented as data, which include spacing, color, typography, object styles, animation, etc. These can represent anything defined by design: a color as an RGB value, an opacity as a number, and an animation ease function as Bezier coordinates. They're used in place of hard-coded values to ensure flexibility and unity across all product experiences.

Design tokens are directly integrated into our component libraries, UI kits, and the Spectrum XD plugin. They cover the various options of platform scales, color themes, component states, and more. We also offer teams a variety of token types to use directly within their products if they are not using a Spectrum component library.

Getting started

Follow the monorepo setup guide.

Design Data validation

Moon tasks run the Rust design-data CLI against src/ and schemas/:

• moon run tokens:validateDesignData — JSON Schema (Layer 1) + catalog rules (Layer 2)
• moon run tokens:verifyDesignDataSnapshot — same as above, compared to snapshots/validation-snapshot.json (update with design-data migrate snapshot when outputs change)

From the repo root with Rust available, you can also run cargo run -p design-data-cli --manifest-path sdk/Cargo.toml -- validate ./packages/tokens/src --schema-path ./packages/tokens/schemas.

Generate a Diff from the last release

The pnpm generateDiffResult script will build the project and compare the tokens in the dist directory with the last released version of Spectrum Tokens. It will generate a report of added tokens, deleted tokens, tokens with value changes, and tokens with potential name changes. The script can't guarantee the correct name changes; it compares new tokens and deleted tokens to see if any have the same value and are likely to be token name changes.

Versioning

This project uses Semantic Versioning (semver). It also utilizes Conventional Commits and semantic-release with a GitHub Action to automate the release process.

Major, minor, and patch criteria

Patches

x.x.n+1 releases are for bug fixes and patches.

• bug fixes
• typos
• mistakes

Example: a token name changing from detail-margin-top-mulitplier to detail-margin-top-multiplier to fix a spelling mistake.

Minor

x.n+1.0 releases are for new tokens and features.

• adding new token
• changing a value intentionally
• adding deprecation metadata and aliased new tokens where applicable

Major

n+1.0.0 releases are for breaking changes.

• deleting tokens
• changing token value type (e.g., from a color to a dimension; anything that would break a parser expecting specific data types)

Deprecations

Planned token name changes

Tokens with a name changed will first be marked as deprecated, while a new token will be created with the new name; the deprecated token will then become an alias for the new token. Finally, the deprecated token will eventually be removed, most likely in the next major release if there has been sufficient time to notify teams. The required amount of time is still to be determined.

Token properties for deprecation tracking

• deprecated (boolean): Marks a token as deprecated
• deprecated_comment (string): Provides context about why the token is deprecated and migration guidance
• renamed (string): For 1:1 token replacements, specifies the new token name that should be used instead

When a token is renamed:

1. Set deprecated: true on the old token
2. Add renamed: "new-token-name" to specify the replacement
3. Update deprecated_comment to provide additional context if needed
4. The old token's value should typically alias to the new token

Releases

All commits merged or pushed to the main branch will be released as a stable version with the latest tag on NPM. All commits merged or pushed to next, or next-major will update the version number according to the types of commits made in the branch (breaking change, feature, bug fix) and release it to NPM with the next tag.

More details can be found in this example workflow.

Spectrum Tokens 11.x.x and 12.x.x

Starting with @adobe/spectrum-tokens v12.0.0, this project uses a more efficient list of tokens. Previously in v11.x.x, every possible combination of component options was used to define tokens, resulting in an unnecessarily large list of tokens. However, while the work is ongoing in migrating components from the old system to the newer one, v12.0.0 and future versions will be published under the latest tag. To install it, use the script:

pnpm add @adobe/spectrum-tokens

or

npm install --save @adobe/spectrum-tokens

If you need to use the older and more complete set of tokens side by side with the v12.x.x release while the development of this migration is ongoing, you can use the @adobe/spectrum-tokens-depreacated package, which is an archived release of @adobe/[email protected].

Token Types and $schema

Tokens now have a $schema property that relates to a type defined in the schemas/token-types/ directory. Even those these are being released as part of the regular releases, they shouldn't be considered formal API yet. There are planned adjustments with further data integration in design tools and workflows. Ideally, designers would be able to author new tokens and manage type across all the data.