Design tokens

Design tokens are the single source of truth for visual constants — colors, typography, spacing, radii, shadows, and strokes. They are defined in a JSON file using the Design Tokens Community Group (DTCG) format and compiled into CSS custom properties (--*) that are available globally on :root.

For a visual overview of all available tokens and their values, see the B2B Design Token Reference.

How it works

design-tokens.json  ──►  style-dictionary  ──►  design-tokens.css  ──►  webpack (critical CSS)
      (source)              (build step)            (generated)             (bundled)

1. Tokens are authored in a single JSON file.
2. During the frontend build, Style Dictionary reads the JSON and generates a CSS file with custom properties.
3. Webpack includes the generated CSS in the critical entry point, so all variables are available on every page.

File locations

Token categories

The JSON file organizes tokens into six top-level groups.

Color

Spryker splits colors into two layers:

• Primitives (Color.*) — raw palettes (grey, blue, teal, green, forest, yellow, orange, red, purple) with shades 25–950, plus black and white. These are building blocks — avoid using them directly in components.
• Semantic (Semantic Color.*) — named by intent: background, text, border, icon, focus, input, header, footer. Each references a primitive. Use these in components.

color: var(--text-primary);
background-color: var(--background-page);
background-color: var(--background-brand-primary);
border-color: var(--border-default);

Typography

Each text style generates five CSS variables: --{style}-{scale}-family, -weight, -size, -line-height, -letter-spacing.

font-size: var(--heading-lg-size);
line-height: var(--heading-lg-line-height);
font-weight: var(--heading-lg-weight);
letter-spacing: var(--heading-lg-letter-spacing);

Spacing

A scale based on a 4px grid: 0, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64.

padding: var(--scale-16);
gap: var(--scale-8);
margin-bottom: var(--scale-24);

Radius

Stroke

border: var(--stroke-sm) solid var(--border-default);

Shadows

Each shadow scale generates --shadows-{scale}-x, -y, -blur, -spread, -color. Available scales: focus, sm, md, lg, xl.

box-shadow: var(--shadows-sm-x) var(--shadows-sm-y) var(--shadows-sm-blur) var(--shadows-sm-spread)
    var(--shadows-sm-color);

Editing tokens

To change a token value (for example, the primary brand color):

1. Open frontend/assets/global/default/design-tokens/design-tokens.json.
2. Find the token and update its $value:

"brand": {
    "primary": {
        "$type": "color",
        "$value": "{Color.teal.700}"
    }
}

3. Rebuild the frontend — the CSS file is regenerated automatically:

npm run yves

Adding a new token

Add a new entry anywhere in the JSON structure. The build script flattens nested keys into a kebab-case CSS variable name. The first level of the path is stripped.

Example — adding "10" to the spacing scale:

"Spacing": {
    "scale": {
        "10": { "$type": "dimension", "$value": "10px" }
    }
}

This generates --scale-10: 10px;.

Token naming convention

The generated variable name follows this pattern:

--{path minus first segment, joined by hyphens}