Tokens

What are tokens

A design token captures a single design decision (a color, a spacing step, a font size) as a named value that both design and code reference. Naming raw values this way keeps the UI consistent and maintainable across tools and platforms.

Token names explained

Each part of a token's name specifies one aspect of its use:

• Type: the broad classification (color, font, scale, border-radius).
• Category: a grouping within the type (icon, text, background, elevation).
• Instance: a usage within the category (primary, positive, critical).
• Variant: the state (default, hover, pressed, disabled).

This four-part structure applies to semantic color tokens; others such as --font-size-s or --scale-size-8 use fewer parts because they carry no state.

Usage

See Installation to install the token package and import the theme CSS.

All tokens

Adding a new token

New tokens require sign-off from both design and engineering before they are added. The process is intentionally lightweight but ensures every new token has a clear purpose and fits the existing naming structure.

Starting a proposal

A new token can be initiated from either side. A designer might identify a gap while building a new component in Figma; an engineer might notice a hardcoded value that should be abstracted. Either way, the proposal should be shared with the other discipline before work begins. Use a GitHub issue, a Figma comment on the library file, or the Meteor Slack channel to open the discussion.

What a good proposal includes

• What the token represents and where it will be used
• The proposed name following the type-category-instance-variant structure
• The intended value in all available themes
• Whether an existing token could cover the need instead

Review and sign-off

Both the design team and the Meteor engineering team review the proposal. The review checks that the name is consistent with existing conventions, that the token is genuinely needed and not a duplicate, and that it works correctly across both themes.

From Figma to code

Once approved, the token is added to the Figma Variables library first. From there it is synced to the token package using the Figma Variables sync workflow. The Meteor team owns the PR that lands the token in the codebase and publishes it in the next release.

Customizing tokens

We recommend against overriding existing Meteor tokens. Overrides can cause unexpected visual divergence from the design system and break when token values change in future releases. If your project needs additional tokens, define new ones with a custom prefix instead.

If you do need to override, do so after importing the Meteor token files and scope changes to [data-theme="dark"] for theme variants.

@import "@shopware-ag/meteor-tokens/administration/light.css";
@import "@shopware-ag/meteor-tokens/administration/dark.css";

/* Add new tokens with a custom prefix */
:root {
  --myapp-color-brand-default: #7c3aed;
  --myapp-color-brand-hover: #6d28d9;
}

[data-theme="dark"] {
  --myapp-color-brand-default: #8b5cf6;
  --myapp-color-brand-hover: #7c3aed;
}