Porsche Design System

Introduction

Table of Contents

Styles
Setup
Color Scheme

Styles#

Styles are the foundational layer of our design language. They define the basics, such as colors across themes, typography, and visual effects, and they also provide structural primitives such as the layout grid and spacing scale.

Use these styles only when you need to build a custom component or pattern that is not yet available in the component library, or when working with foundational layout objects such as typography, surfaces, and boxes.

Setup#

1. Install Vanilla Extract

Follow the official installation guide:

Install Vanilla Extract Documentation

2. Import the Porsche Design System Vanilla Extract Styles

Use the following path to import the styles:

import { … } from '@porsche-design-system/components-{js|angular|react|vue}/vanilla-extract';

3. Include the Color Scheme global styles

Include the colorSchemeStyles in your global styles to enable the color scheme utilities and add a polyfill for browsers that don’t yet support light-dark(). See the Color Scheme section for details.

// app.css.ts
import { colorSchemeStyles } from '@porsche-design-system/components-{js|angular|react|vue}/vanilla-extract';
import { type GlobalStyleRule, globalStyle } from '@vanilla-extract/css';

for (const { selector, rule } of colorSchemeStyles) {
  globalStyle(selector, rule as GlobalStyleRule);
}

Color Scheme#

The color system leverages the CSS light-dark() function to deliver native, preference-based theming. By adopting this browser-native engine, we have eliminated the need for proprietary switching logic, resulting in a more performant and standardized architecture.

Core Implementation

All colors and styles are driven by the CSS color-scheme property. To ensure broad compatibility, we provide the global colorSchemeStyles, which generates utility classes and includes a polyfill for browsers that do not yet support light-dark() (see browser support).

Utility Classes

Apply these classes to the document or any container to control the theme context:

.scheme-light — Forces light mode.

.scheme-dark — Forces dark mode.

.scheme-light-dark — Dynamically follows system/OS settings.

Usage

1. Global Setup

Include the global styles once in your app.css.ts to initialize the theme utilities.

// app.css.ts

+ import { colorSchemeStyles } from '@porsche-design-system/components-react/vanilla-extract';
+ import { type GlobalStyleRule, globalStyle } from '@vanilla-extract/css';

+ for (const { selector, rule } of colorSchemeStyles) {
+   globalStyle(selector, rule as GlobalStyleRule);
+ }

2. Component Implementation

Use the new tokens in your styles. These variables automatically resolve to the correct value based on the active theme.

import { colorFrosted, colorPrimary } from '@porsche-design-system/components-react/vanilla-extract';
import { style } from '@vanilla-extract/css';

export const myComponent = style({
  backgroundColor: colorFrosted,
  color: colorPrimary,
});

3. Application

The selected theme context cascades to all child elements.

import { myComponent } from './myComponent.css';

<!-- Defined theme will be applied to all child elements -->
export const App = () => {
  return (
    <div className="scheme-dark">
      <div className={myComponent}></div>
    </div>
  );
};