Porsche Design System

Theme

Table of Contents

How it works
Scoping Themes
Fixed Light and Dark Sections

How it works#

The new color system leverages the native CSS light-dark() function. By adopting this browser-native engine, we have eliminated proprietary switching logic in favor of a performant, standardized architecture that responds instantly to user preferences.

The Foundation: color-scheme

All system colors are controlled via the CSS color-scheme property and are included in our mandatory Global Styles. These styles also provide utility classes for selecting the active theme and a polyfill to ensure compatibility with browsers that do not yet support light-dark() (see browser support).

Apply these classes to the html element or any container to define the theme context:

.scheme-light — Forces the Light theme.

.scheme-dark — Forces the Dark theme.

.scheme-light-dark — Automatically toggles based on System/OS settings.

Scoping Themes#

Theme context is hierarchical. You can nest these utility classes to create "islands" of different themes within your application. This is particularly useful for dark-themed footers or light-themed modals on dark pages.

<html class="scheme-light-dark">
  <body>
    <p-button>I follow the OS theme</p-button>

    <div class="scheme-dark">
      <p-heading>Dark Section</p-heading>
      <p-button>I use the Dark theme</p-button>
    </div>
  </body>
</html>

Ecosystem Integration

The color-scheme utility classes do more than just update PDS components—they act as a global "source of truth" for your entire styling stack. When you apply a .scheme-* class, it automatically synchronizes the theme across all our supported styling tools:

Tailwind CSS: Custom PDS color utilities (e.g., text-primary) automatically resolve to the correct light or dark values.

SCSS: The PDS mixins and variables hook into the theme context, ensuring your custom stylesheets remain brand-compliant.

Emotion: Design tokens consumed via Emotion are reactive to the color-scheme defined on the parent container.

Vanilla Extract: Design tokens consumed via Vanilla Extract are reactive to the color-scheme defined on the parent container.

Key Takeaway: By using these utility classes, you ensure that your custom UI and PDS components always share the same color palette and contrast ratios, regardless of the styling technology used.

Fixed Light and Dark Sections#

Use .scheme-only-light or .scheme-only-dark on a page section that must remain light or dark independently of its parent scheme. This is useful for fixed campaign sections or other page islands within a page that otherwise follows the user's system preference.

❌ Anti-pattern — overriding global PDS color variables:

.campaign-section {
  --p-color-canvas: #0e0e12;
  --p-color-primary: #fff;
}

✅ Recommended — applying fixed schemes to page islands while continuing to consume PDS variables:

<html class="scheme-light-dark">
  <body>
    <main>
      <section class="campaign-section scheme-only-dark">Dark campaign content</section>
      <section class="campaign-section scheme-only-light">Light campaign content</section>
    </main>
  </body>
</html>

.campaign-section {
  background-color: var(--p-color-canvas);
  color: var(--p-color-primary);
}