Migrate to new Design Tokens

Viewport's 2023-10-17 release introduces CSS custom properties that represent its new design token foundation in the Help Center theme while deprecating some existing ones.

If you have injected custom CSS into your site and use any of the legacy custom properties, you should switch to the new ones as soon as possible.

To ease the switch, we will continue to support a selection of the most used legacy custom properties until mid 2024. After that, every site must be using the new design token custom properties in order to maintain customized styling.

Affected CSS custom properties

The following overview of all deprecated custom properties and their replacements will help you update your theme's custom code.

The legacy custom property values will still be applied during the migration period (unless described otherwise). Not all legacy custom properties will get a successor property and are instead removed.

The new recommended custom properties are either from the simple Theme Tokens or the advanced Design Token system.

Deprecated custom properties	New successor custom properties
DEPRECATED `--K15t-layout-header-height`	`--vpt-theme-header-height`
DEPRECATED `--K15t-layout-scroll-offset`	`--vpt-theme-scroll-offset`
DEPRECATED `--K15t-layout-container-width`	`--vpt-theme-container-width`
DEPRECATED `--K15t-header-foreground`	`--vpt-header-text-color`
DEPRECATED `--K15t-header-background`	`--vpt-header-background-color`
DEPRECATED `--K15t-banner-foreground`	`--vpt-banner-text-color`
DEPRECATED `--K15t-banner-background`	`--vpt-banner-background-color`
DEPRECATED `--K15t-banner-image`	`--vpt-banner-image`
DEPRECATED `--K15t-footer-foreground`	`--vpt-footer-text-color`
DEPRECATED `--K15t-footer-background`	`--vpt-footer-background-color`
DEPRECATED `--K15t-fab-size`	-
DEPRECATED `--K15t-fab-offset-block`	-
DEPRECATED `--K15t-fab-offset-inline`	-
DEPRECATED `--vp-font-family-default`	`--vpt-theme-text-font`
DEPRECATED `--vp-font-family-headline`	`--vpt-theme-headline-font`
DEPRECATED `--vp-font-size-standard`	`--vpt-theme-text-scale`
DEPRECATED `--vp-heading-h1-font-size`	`--K15t-font-size-headline-large`
DEPRECATED `--vp-color-medium-gray`	`--K15t-foreground-subtle`
DEPRECATED `--vp-color-black`	`--vpt-theme-text-color`
DEPRECATED `--vp-font-family-code`	`--K15t-font-family-code`
DEPRECATED `--vp-roundness-interactive-elements`	Merges into `--vpt-theme-roundness` The new roundness factor property is applied to several elements and controls the general roundness of the theme. The smaller the factor the less round the site gets and the bigger the factor the rounder it gets.
DEPRECATED `--vp-roundness-images`
DEPRECATED `--vp-color-stratos-blue`	-
DEPRECATED `--vp-color-blue`	`--K15t-link`
DEPRECATED `--vp-border-radius-small`	`--K15t-radius-small`
DEPRECATED `--vp-border-radius-big`	`--K15t-radius-large`
DEPRECATED `--vp-color-border-default`	`--K15t-border-neutral`
DEPRECATED `--vp-heading-h1-font-size-mobile`	`--K15t-font-size-headline-large`
DEPRECATED `--vp-layout-container-width`	`--vpt-theme-container-width`
DEPRECATED `--vp-layout-scroll-offset`	`--vpt-theme-scroll-offset`
DEPRECATED `--vp-layout-header-height`	`--vpt-theme-header-height`
DEPRECATED `--vp-header-text-color`	`--vpt-theme-header-text-color`
DEPRECATED `--vp-header-background-color`	`--vpt-theme-header-background-color`
DEPRECATED `--vp-footer-text-color`	`--vpt-theme-footer-text-color`
DEPRECATED `--vp-footer-background-color`	`--vpt-theme-footer-background-color`
DEPRECATED `--vp-portal-banner-text-color`	`--vpt-theme-banner-text-color`
DEPRECATED `--vp-space-banner-text-color`	`--vpt-theme-banner-text-color`
DEPRECATED `--vp-portal-banner-background-image`	`--vpt-theme-banner-image`
DEPRECATED `--vp-space-banner-background-image`	`--vpt-theme-banner-image`
DEPRECATED `--vp-button-variant-floating-action-size`	-
DEPRECATED `--vp-mobile-menu-trigger-position-right`	-
DEPRECATED `--vp-mobile-menu-trigger-position-bottom`	-
DEPRECATED `--vp-button-variant-outline-background`	-
DEPRECATED `--vp-button-variant-outline-foreground`	-
DEPRECATED `--vp-button-background`	-
DEPRECATED `--vp-button-foreground`	-
DEPRECATED `--vp-grid-step`	-

Migration instructions

Deriving legacy custom property values within the theme's custom CSS

If your theme's custom CSS derives legacy custom property values — for example to use their values to style other elements — simply replace the legacy custom property with its successor listed in the Affected CSS custom properties table.

Example:

DIFF

/* Within the theme's custom CSS */

.some-element {
-  color: var(--vp-color-black);
+  color: var(--K15t-foreground);
}

Overriding legacy custom property values within the theme's custom CSS

In case your theme's custom CSS overrides a legacy custom property value — e.g. to better adapt to the corporate identity — follow these steps:

Identify the successor custom property
Override the new custom property on the root level
Remove the legacy custom property from the theme's custom CSS

Example:

DIFF

/* Within the theme's custom CSS */

:root {
-  --vp-font-family-headline: "Merriweather", ui-serif, serif;
+  --vpt-theme-headline-font: "Merriweather", ui-serif, serif;
}

Overriding element styles using various CSS selectors in the theme’s custom CSS

Using element selectors can be error prone and does not always lead to the desired result due to CSS specificity. We recommend to use the appropriate custom properties instead where ever possible which is much more robust and does not rely on CSS selector specificity.

Example:

DIFF

/* Within the theme's custom CSS */

- h1,
- h2,
- h3,
- h4,
- h5,
- h6 {
-   font-family: 'Georgia', 'serif'; 
- }
+ :root {
+   --vpt-theme-headline-font: 'Georgia', 'serif';
+ }