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 December 2023. After that date, every theme 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.

Legacy custom properties	New custom properties
--vp-font-family-default	--K15t-font-family-body
--vp-font-family-headline	--K15t-font-family-headline
--vp-font-size-standard	--K15t-font-size-body-medium
--vp-heading-h1-font-size	--K15t-font-size-headline-large
--vp-color-medium-gray	--K15t-foreground-subtle
--vp-color-black	--K15t-foreground
--vp-font-family-code	--K15t-font-family-code
--vp-roundness-interactive-elements	Merges into --K15t-roundess-factor 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.
--vp-roundness-images
--vp-color-stratos-blue	REMOVED
--vp-color-blue	--K15t-link
--vp-border-radius-small	--K15t-radius-small
--vp-border-radius-big	--K15t-radius-large
--vp-color-border-default	--K15t-border-neutral / --K15t-border-brand
--vp-heading-h1-font-size-mobile	--K15t-font-size-headline-large
--vp-layout-container-width	--K15t-layout-container-width
--vp-layout-scroll-offset	--K15t-layout-scroll-offset
--vp-layout-header-height	--K15t-layout-header-height
--vp-header-text-color	--K15t-header-foreground
--vp-header-background-color	--K15t-header-background
--vp-footer-text-color	--K15t-footer-foreground
--vp-footer-background-color	--K15t-footer-background
--vp-portal-banner-text-color	--K15t-banner-foreground
--vp-space-banner-text-color	--K15t-banner-foreground
--vp-portal-banner-background-image	--K15t-banner-image
--vp-space-banner-background-image	--K15t-banner-image
--vp-button-variant-floating-action-size	--K15t-fab-size
--vp-mobile-menu-trigger-position-right	--K15t-fab-offset-inline
--vp-mobile-menu-trigger-position-bottom	--K15t-fab-offset-block
--vp-button-variant-outline-background	REMOVED
--vp-button-variant-outline-foreground	REMOVED
--vp-button-background	REMOVED
--vp-button-foreground	REMOVED
--vp-grid-step	--vp-grid-step Planned obsolescence. We recommend not using or overriding it.

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:

/* 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:

1. Identify the successor custom property

2. Override the new custom property on the root level

3. Remove the legacy custom property from the theme's custom CSS

Example:

/* Within the theme's custom CSS */

:root {
-  --vp-font-family-headline: "Merriweather", ui-serif, serif;
+  --K15t-font-family-headline: "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:

/* Within the theme's custom CSS */

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