Polaris CSS-Variablen (Design-Tokens)

Polaris Web Components bringen ihr eigenes Styling mit, aber eine App hat meist auch eigenes CSS: ein Seitenraster, eine eigene Karte, eine Diagrammlegende, einen Abstand zwischen zwei Komponenten. Mit den Polaris CSS-Variablen nutzt dieses CSS dieselben Farben, Abstände, Radien und Schriften wie die umgebenden Komponenten und passt so zum Design des Adminbereichs, statt auf fest codierten Schätzwerten zu beruhen.

polaris-vue-elements liefert sie als ein einziges Stylesheet, tokens.css, aus der Polaris-Runtime extrahiert, die die App lädt.

Inoffiziell

Shopify veröffentlicht keine Liste der CSS-Variablen für Polaris Web Components. Diese Namen und Werte werden aus der Runtime von Shopify (polaris-2.js) extrahiert. Die Werte folgen daher dem CDN, und ein Name kann sich ändern oder verschwinden, wenn Shopify ihn umbenennt. Die Liste wird täglich geprüft (siehe Wie sie aktuell bleibt).

Wann sie sinnvoll sind

• Verwenden für Elemente, die der App selbst gehören: Wrapper, Layout-Container, eigene Widgets, Text, der außerhalb von Polaris-Komponenten gerendert wird.
• Nicht verwenden, um Polaris-Komponenten umzustylen. Jede Komponente wird in ihrem eigenen Shadow Root gerendert, daher färbt --p-color-bg-fill-brand auf der Seite <SButton> nicht um. Stattdessen die Props der Komponente nutzen (tone, variant, padding, …).
• Zuerst Layout-Komponenten bevorzugen. <SStack>, <SGrid> und <SBox> nehmen Polaris-Werte für Abstände, Innenabstände und Rahmen bereits als Props entgegen. CSS-Variablen erst dann einsetzen, wenn diese nicht abdecken, was gebraucht wird.

Installation

Das Stylesheet einmal importieren, zum Beispiel in main.ts. Sie brauchen es auch dann, wenn Ihre App im Shopify-Adminbereich läuft (warum):

import 'polaris-vue-elements/tokens.css'

Danach die Variablen in beliebigem CSS verwenden:

<template>
  <div class="summary">
    <SText type="strong">Orders today</SText>
    <SText>42</SText>
  </div>
</template>

<style scoped>
.summary {
  display: flex;
  justify-content: space-between;
  gap: var(--p-space-300);
  padding: var(--p-space-400);
  border: var(--p-border-width-025) solid var(--p-color-border);
  border-radius: var(--p-border-radius-300);
  background: var(--p-color-bg-surface);
  box-shadow: var(--p-shadow-100);
}
</style>

Die rohen Namen und Werte gibt es auch als JSON, für Tooling oder CSS-in-JS:

import tokens from 'polaris-vue-elements/tokens.json'

tokens.tokens['--p-space-400'] // '1rem'

Themes

Die Runtime kennt zwei Erscheinungsbilder. Ein Shop mit dem bisherigen Admin-Design erhält die Basiswerte (den :root-Block in tokens.css). Ein Shop mit dem neuen Admin-Design sowie jede Seite außerhalb des Shopify-Adminbereichs erhält das Theme admin-next: Sobald die erste Polaris-Komponente gerendert wird, fügt die Runtime die Klasse p-partial-theme-admin-next zu <html> hinzu, und tokens.css überschreibt unter genau dieser Klasse die abweichenden Werte. Das eigene CSS folgt so ohne zusätzlichen Aufwand dem Theme, das die Runtime gewählt hat. Unter Alle Variablen lässt sich zwischen Basis und admin-next umschalten, um jeweils deren Werte zu sehen; ein halb gefüllter Punkt markiert Variablen, deren Wert sich zwischen den beiden unterscheidet.

Werte, die die Runtime nur unter zusätzlichen Bedingungen anwendet (P3-Farben mit großem Farbraum, Schriftgrößen für Mobilgeräte, Hochkontrastmodus, Unterstützung für corner-shape), sind nicht enthalten; tokens.css enthält jeweils den Standardwert.

Wie sie aktuell bleibt

Ein geplanter Job liest täglich polaris-2.js aus dem CDN von Shopify, extrahiert die Variablen und öffnet einen Pull Request, sobald etwas hinzugefügt, entfernt oder geändert wurde. Jedes Release von polaris-vue-elements enthält die Liste zum Stand dieses Releases.

• Alle Variablen
• Migration von @shopify/polaris-tokens

Häufige Fragen

Haben Polaris Web Components CSS-Variablen?

Ja. Die Polaris-Runtime (polaris-2.js) definiert rund 700 --p-* Custom Properties auf :root und verwendet sie in ihren Komponenten. Shopify dokumentiert sie nicht, und die Namen in der Runtime tragen einen Build-Hash. tokens.css stellt dieselben Werte unter stabilen Namen bereit.

Meine App läuft im Shopify-Adminbereich. Brauche ich trotzdem tokens.css?

Ja. Die Runtime definiert die Variablen nur unter Namen mit Hash, etwa --p-color-bg-surface-6e076, nie unter --p-color-bg-surface. Ohne tokens.css wird var(--p-color-bg-surface) daher zu nichts aufgelöst. Der Hash ändert sich mit jedem Shopify-Build, sodass Sie auch die Namen mit Hash nicht verwenden können. Das eigene CSS des Adminbereichs erreicht Ihre App nicht, weil eine eingebettete App in einem iframe läuft.

Kann ich eine Polaris-Komponente mit diesen Variablen umstylen?

Nein. Jede Komponente wird in ihrem eigenen Shadow Root gerendert und liest die eigenen, gehashten Variablen der Runtime. Wird --p-color-bg-fill-brand auf der Seite gesetzt, ändert sich <SButton> daher nicht. Stattdessen die Props der Komponente nutzen, etwa tone und variant. Die Variablen sind für die eigenen Elemente rund um die Komponenten gedacht.

Warum enden die Variablennamen in den DevTools auf einen Hash wie -6e076?

Die Runtime hängt an jeden Namen ein buildspezifisches Suffix an (--p-color-bg-surface-6e076), und dieses Suffix ändert sich von Build zu Build. Diese Namen also nicht ins eigene CSS kopieren: tokens.css entfernt das Suffix, sodass var(--p-color-bg-surface) auch dann weiter funktioniert, wenn Shopify einen neuen Build ausliefert.

Worin unterscheidet sich das von @shopify/polaris-tokens?

@shopify/polaris-tokens ist das Token-Paket für Polaris React. Diese Liste stammt direkt aus der Runtime der Web Components und enthält daher die Tokens, die die Komponenten tatsächlich verwenden, einschließlich der Werte für das neue Admin-Design (admin-next). Die meisten Namen sind gleich; die Unterschiede zeigt Migration von @shopify/polaris-tokens.

Unterstützen die Variablen den Dark Mode?

Nicht als Theme für die Seite. Die Runtime hat zwar einen dunklen Wertesatz (admin-next-dark), wendet ihn aber nur auf Teile innerhalb einiger Komponenten an, nie auf die Seite. Deshalb hat tokens.css kein dunkles Theme. Wer eines bauen möchte, findet die Werte in tokens.json unter themes["admin-next-dark"].