Die Token --wpce-*

Die Blöcke des Plugins lesen keine Farben, Abstände oder Rundungen direkt aus dem Theme. Sie lesen Token: CSS-Eigenschaften mit dem Präfix --wpce-. Du änderst ein Token, und alle Blöcke, die es lesen, ziehen mit. Du schreibst kein Selektor-CSS in das Innere eines Blocks.

Das ist der Weg, ein Theme oder ein Child auf einen Verein abzustimmen. Er hält, wenn das Plugin sich ändert, weil die Namen der Token ein Vertrag sind (siehe Der Vertrag).

Die Kette

Jedes Token fällt erst auf einen Wert aus der theme.json zurück und dann auf einen festen Wert. Ein Beispiel:

--wpce-card-radius: var(--wp--custom--wpce--card--radius, var(--wpce-radius));
--wpce-radius:      var(--wp--preset--border-radius--medium, 0.5rem);

Der Kartenradius liest zuerst settings.custom.wpce.card.radius aus der theme.json. Fehlt der Wert, gilt --wpce-radius. Der liest die Rundung medium des Themes. Hat das Theme keine, gilt 0.5rem. Dadurch sieht das Plugin mit jedem Block-Theme ordentlich aus und folgt wpce-theme und jedem Child über deren theme.json.

Schlüssel in camelCase (card.borderWidth) werden in der CSS-Variablen zu Kleinbuchstaben mit Bindestrich (--wp--custom--wpce--card--border-width).

Wo du ein Token setzt

Ein Token ist eine normale CSS-Eigenschaft und wird vererbt. Die Token-Datei des Plugins setzt ihre Werte auf :where(:root), also ohne Spezifität. Jede Regel von dir gewinnt, auch eine auf :root. Du hast drei Orte.

1. In der theme.json (der Normalfall für ein Child): Du setzt settings.custom.wpce.*. Das Plugin liest die Werte von dort.

{
  "version": 3,
  "settings": {
    "custom": {
      "wpce": {
        "card": { "line": "var(--wp--preset--color--neutral)", "borderWidth": "2px", "padding": "1.75rem" }
      }
    }
  }
}

2. Auf :root in assets/css/child.css: für die ganze Website, wenn theme.json den Wert nicht kennt. child.css wird nach den Global Styles des Parents geladen und gewinnt darum gegen dessen :root-Regeln.

:root {
  --wpce-card-radius: 0;
  --wpce-card-line-width: 2px;
}

3. Auf einem Abschnitt oder einem einzelnen Block: für Ausnahmen. Der Wert gilt dort und in allem, was darin steht.

/* Alle Listen in diesem Abschnitt: eckige Karten. */
.mein-abschnitt {
  --wpce-card-radius: 0;
}

/* Nur die Listen der Personen. */
.wpce-entries--type-person {
  --wpce-card-radius: 0;
}

Geprüft im Browser mit den Personenkarten des Demovereins: :root { --wpce-card-radius: 0 } macht den berechneten Radius jeder Karte von 12px zu 0px. Als Eigenschaft an genau einem Block (style="--wpce-card-radius: 0") ändert sich nur dieser Block, der zweite Block der Seite bleibt bei 12px. Die CSS-Regeln wurden in die Seite im Browser eingefügt, gespeichert wurde nichts.

Ein Beispiel mit Bild

Drei Personenkarten, wie das Theme sie zeichnet:

Die Personenkarten des Demovereins, wie das Theme sie zeichnet.

Dieselben Karten mit vier Token auf dem Block:

.wp-block-wpce-entries {
  --wpce-card-radius: 0;
  --wpce-media-radius: 0;
  --wpce-card-line: var(--wp--preset--color--primary);
  --wpce-card-line-width: 2px;
}

Dieselben Karten mit eckigen Ecken und einem blauen Rahmen von zwei Pixeln.

Dunkle Abschnitte und eigene Farben

Die Standardwerte von --wpce-line, --wpce-surface und --wpce-muted kommen aus der Palette des Themes (neutral, contrast-2) und sind für eine helle Seite gedacht. Auf einem dunklen Abschnitt wären sie unlesbar.

Zwei Dinge fangen das ab:

• Abschnittsstile des Themes. Ein Theme mit Abschnittsstilen (wie wpce-theme mit wpce-section-1 bis -5) setzt die Token je Stil neu. Das Plugin muss davon nichts wissen.
• Eigene Farben im Editor. Hat eine Gruppe eine gewählte Hintergrund- oder Textfarbe (.has-background, .has-text-color), leiten sich Linie, Fläche und gedämpfter Text wieder aus der Textfarbe ab. Der Akzent bleibt die Vereinsfarbe nur auf den beiden hellen Flächen der Palette (base, neutral). Sonst gilt die Textfarbe. Das sind Regeln ohne Spezifität: Ein Abschnittsstil des Themes gewinnt dagegen.

Geprüft: Auf der Seite hat --wpce-muted den Wert #4B5B70. Ein div mit .has-background und .has-primary-background-color bekommt color-mix(in srgb, currentcolor 70%, transparent), sein --wpce-accent ist currentcolor.

Vergibst du in deinem Child selbst eine feste dunkle Fläche, setzt du auf ihr drei Token. Alle drei gehören zusammen:

.mein-dunkler-abschnitt {
  background: var(--wp--preset--color--contrast);
  color: var(--wp--preset--color--base);
  --wpce-muted: color-mix(in srgb, var(--wp--preset--color--base) 72%, transparent);
  --wpce-surface: color-mix(in srgb, var(--wp--preset--color--base) 8%, transparent);
  --wpce-line: color-mix(in srgb, var(--wp--preset--color--base) 16%, transparent);
}

Wer einen Abschnittsstil in theme.json hat, setzt den Akzent mit: Ein Abschnitt, der --wpce-accent setzt, setzt auch --wpce-accent-fill (Fläche des Datumsblocks) und --wpce-on-accent (Schrift darauf).

Was kein Token ist

Abstände, die zur Schrift gehören, sind keine Token. Das sind der Abstand zwischen Symbol und Text, zwischen zwei Zeilen einer Liste und das Polster einer aufklappbaren Zeile. Sie stehen in em und wachsen mit der Schriftgröße. Dafür gibt es nichts zu setzen.

Alle Token

Der Vertrag nennt zurzeit 71 Token. Die Tabellen unten nennen jedes. Sie sind nach dem Zweck gruppiert und stammen aus public-contract.json und den Kommentaren der Token-Datei src/blocks/shared/_tokens.scss.

• Standard nennt die Kette: erst den Schlüssel unter settings.custom.wpce oder das Preset des Themes, dann den festen Wert. custom.wpce.card.radius steht kurz für --wp--custom--wpce--card--radius.
• Nicht gesetzt heißt: Das Token ist leer, solange das Theme es nicht nennt, und die Regel fällt dort zurück, wo sie gilt. Ein Child setzt es in theme.json oder selbst.
• Längen in theme.json brauchen eine Einheit: 0px, nicht 0.

wpce-theme setzt einige Token auf :root nach seinem eigenen Maßstab: die vier Abstandsstufen, die zwei Radien, den Schatten und das Farbschema je Abschnitt. Die Werte stehen im README des Themes.

Abstände

Drei Stufen für das Innere und das Äußere einer Komponente, dazu der Abstand zwischen Abschnitten einer Seite und die Lesebreite. Die inneren Stufen haben eine Obergrenze, und jede Stufe ist mindestens so groß wie die vorige. Das schützt vor Themes, deren Abstandsstufen ganz anderes bedeuten.

Token	Steuert	Standard
--wpce-gap-xs	Abstand innerhalb einer Komponente: Symbol und Text, Zeilen einer Tabelle	Stufe 20 des Themes, höchstens 1.25rem; ohne Theme 0.5rem
--wpce-gap-sm	Innenabstand eines Eintrags oder einer Karte	Stufe 30, höchstens 1.75rem, mindestens --wpce-gap-xs; ohne Theme 1rem
--wpce-gap	Abstand zwischen Komponenten, etwa zwischen den Karten eines Rasters	Stufe 40, mindestens --wpce-gap-sm; ohne Theme 1.5rem
--wpce-gap-lg	Abstand zwischen Gruppen von Komponenten	Stufe 50, mindestens --wpce-gap; ohne Theme 2.5rem
--wpce-gap-section	Abstand zwischen zwei Abschnitten einer Plugin-Seite (Einzelseite, Übersicht)	Stufe 60, höchstens 6rem, mindestens --wpce-gap-lg; ohne Theme clamp(3rem, …, 5rem)
--wpce-measure	Lesebreite eines Textes auf den Plugin-Seiten	custom.wpce.measure, sonst 46rem

Rundungen

Token	Steuert	Standard
--wpce-radius-sm	Steuerelemente und kleine Bilder	Rundung small des Themes, sonst 0.25rem
--wpce-radius	Standardrundung, zum Beispiel für Karten	Rundung medium, sonst 0.5rem
--wpce-radius-full	Runde Dinge, etwa Porträts in einer Liste	Rundung full, sonst 999px
--wpce-card-radius	Ecken jeder Karte (das Bild oben rundet mit)	custom.wpce.card.radius, sonst --wpce-radius
--wpce-media-radius	Ecken der Bilder	custom.wpce.media.radius, sonst --wpce-radius
--wpce-button-radius	Knöpfe, die das Plugin selbst zeichnet (die Route unter einer Karte)	custom.wpce.button.radius, sonst --wpce-radius-sm

Linie, Fläche, gedämpft, Akzent

Das Farbschema der Fläche, auf der ein Block steht. Die Standardwerte leiten sich aus der Textfarbe ab, darum folgen sie dem Abschnitt, in dem der Block steht.

Token	Steuert	Standard
--wpce-line	Haarlinien: Trennlinien, Rahmen	custom.wpce.line, sonst 20 % der Textfarbe
--wpce-surface	ruhige Fläche: Faktenbox, Hinweis, Karte, Bankverbindung, Raumkacheln, Bildplatzhalter, Zeilen im Stil „ruhig“	Palette neutral, sonst 6 % der Textfarbe
--wpce-muted	gedämpfter Text	Palette contrast-2, sonst 70 % der Textfarbe
--wpce-accent	Akzent: Fokusrahmen, Dachzeile, Kennzeichen, Symbole	Palette primary, sonst die Textfarbe
--wpce-accent-fill	gefüllter Akzent: der Datumsblock	--wpce-accent
--wpce-on-accent	Text auf dem gefüllten Akzent	Palette base, sonst Canvas
--wpce-shadow	Schatten einfacher Karten	Schatten soft, sonst none

Karte

Was eine Karte des Listen-Blocks vom Theme annimmt. Einige Token sind absichtlich nicht gesetzt, solange das Theme sie nicht nennt (card-line, card-padding, ebenso table-max, table-bg, table-head). Sie fallen dann an der Stelle zurück, wo sie gelten.

Token	Steuert	Standard
--wpce-card-min	Mindestbreite einer Karte im Raster	custom.wpce.card.min-width, sonst 17.5rem
--wpce-card-floor	wie schmal eine Karte höchstens wird, bevor eine Spalte entfällt; am Block oder um ihn setzen	nicht gesetzt: 13rem; Porträts halbe Zeile bis 13rem, Logos bis 10rem
--wpce-columns	Obergrenze der Spalten. Setzt der Block selbst (Einstellung „Karten nebeneinander“)	vom Block gesetzt, nicht von Hand
--wpce-media-ratio	Format des Kartenbildes	custom.wpce.media.ratio, sonst 3 / 2
--wpce-card-padding	Innenabstand jeder Karte mit Fläche (nicht Stil „flach“)	custom.wpce.card.padding; nicht gesetzt: max(--wpce-gap-sm, 1.25rem), Personenkarten max(--wpce-gap-xs, 0.875rem)
--wpce-card-line	Linie der Karte im Stil „Rahmen“	custom.wpce.card.line; nicht gesetzt: --wpce-line des Abschnitts
--wpce-card-line-width	Stärke dieser Linie	custom.wpce.card.border-width, sonst 1px
--wpce-card-bg	Fläche der Karte im Stil „Rahmen“	custom.wpce.card.background, sonst transparent
--wpce-card-surface	Fläche im Stil „Schatten“ und Grund der Logo-Plakette	Palette base, sonst transparent
--wpce-card-color	Text im Stil „Schatten“	Palette contrast, sonst geerbt
--wpce-card-accent	Akzent im Stil „Schatten“	Palette primary, sonst die Textfarbe
--wpce-card-shadow	Schatten der Karte im Stil „Schatten“, in Ruhe	Schatten soft, sonst weicher Schatten aus der Textfarbe
--wpce-card-shadow-hover	derselbe Schatten unter dem Zeiger; auch die hervorgehobene Karte	Schatten strong, sonst stärkerer Schatten aus der Textfarbe

Hervorgehobene Karte

Der Blockstil „Karten: hervorgehoben“ ist ein Plakat: eigener dunkler Grund unter dem Bild, heller Text darauf. Datumsblock und Knopf sind in der Textfarbe der Karte gezeichnet, mit dem Grund als Schrift, solange das Theme keinen Akzent nennt.

Token	Steuert	Standard
--wpce-featured-surface	Grund der Karte (der Schleier über dem Bild)	custom.wpce.featured.surface, dann Palette contrast, sonst #1c1c1c
--wpce-featured-color	Text darauf	custom.wpce.featured.color, dann Palette base, sonst #fff
--wpce-featured-accent	Datumsblock und Knopf	custom.wpce.featured.accent; nicht gesetzt: Textfarbe der Karte
--wpce-featured-on-accent	Schrift auf dem Akzent	custom.wpce.featured.on-accent; nicht gesetzt: Grundfarbe der Karte
--wpce-font-featured	Größe des Titels der hervorgehobenen Karte	custom.wpce.font.featured-title, sonst clamp(1.5rem, …, 2.125rem)

Schrift

Schriftgrößen haben eigene Token statt der font-size-Presets. Die Slugs der Presets bedeuten in jedem Theme etwas anderes: Ein Kartentitel in large war im wpce-theme 32 Pixel groß.

Token	Steuert	Standard
--wpce-font-kicker	Dachzeile über einem Titel	custom.wpce.font.kicker, sonst 0.8125rem
--wpce-font-meta	Angaben auf Karten und in Zeilen	custom.wpce.font.meta, sonst 0.9375rem
--wpce-font-title	Titel einer Karte oder Zeile	custom.wpce.font.card-title, sonst clamp(1.1875rem, …, 1.375rem)
--wpce-font-group-head	Kopf einer Gruppe in der Liste: Wochentag, aufklappbares Jahr	custom.wpce.font.group-head, sonst --wpce-font-title
--wpce-font-heading	Schriftfamilie der Überschriften, für das, was wie eine Überschrift gesetzt ist, ohne eine zu sein: der Tag im Listenstil „Programm“, die Ziffer im Kartenstil „nummerierte Schritte“	custom.wpce.font.heading, dann die Schriftfamilie heading aus den Presets, sonst inherit

Liste und Tagesleiste

Token	Steuert	Standard
--wpce-fact-columns	Zahl der Angabe-Spalten einer Zeile. Setzt der Block selbst	vom Block gesetzt, nicht von Hand
--wpce-pill-height	Höhe der Tagesleiste und der Abteilungsknöpfe eines langen Plans. Nur als Eigenschaft, auf irgendetwas um den Block	2.75rem
--wpce-pill-active-bg	Fläche des Knopfs der gezeigten Ansicht. Nur als Eigenschaft	--wpce-accent-fill
--wpce-pill-active-color	Schrift darauf. Nur als Eigenschaft	--wpce-on-accent

Tabelle

Die Kopfzeile ist ein Schleier der Textfarbe über dem Grund der Tabelle. Sie ist dadurch auf jedem Band die dunklere Zeile, der Streifen der gestreiften Tabelle ebenso.

Token	Steuert	Standard
--wpce-table-max	größte Breite einer Tabelle	custom.wpce.table.max-width; nicht gesetzt: so breit wie der Block. Eine Preisliste ist so breit wie ihr Inhalt, mindestens die Lesebreite
--wpce-table-bg	Grund der Zeilen	custom.wpce.table.background; nicht gesetzt: der Grund, auf dem die Tabelle steht
--wpce-table-head	Grund der Kopfzeile	custom.wpce.table.head; nicht gesetzt: 6 % der Textfarbe über dem Grund der Tabelle

Seite und Bänder

Die Einzelseiten und Übersichten der Inhaltstypen bestehen aus Bändern von Rand zu Rand. Benachbarte Bänder sehen nie gleich aus.

Token	Steuert	Standard
--wpce-band-surface	Fläche jedes zweiten Bandes, wo das Theme keine eigenen Abschnittsstile hat	custom.wpce.page.band-surface, sonst --wpce-surface
--wpce-surface-on-band	was auf einem solchen Band eine „ruhige Fläche“ ist	custom.wpce.page.surface-on-band, sonst Palette base
--wpce-page-padding-top	Raum über dem Inhalt von main.wpce-page	custom.wpce.page.padding-top; nicht gesetzt: --wpce-gap-lg
--wpce-page-padding-bottom	Raum darunter	custom.wpce.page.padding-bottom; nicht gesetzt: --wpce-gap-section

Seitenkopf

Der Seitenkopf (wpce/entry-head) bekommt ein Band von Rand zu Rand, sobald das Theme seine Fläche nennt. Alles ist ohne Wert ausgeschaltet: Kein Band ist der Standard.

Token	Steuert	Standard
--wpce-head-surface	das Band hinter dem Kopf	custom.wpce.head.surface; nicht gesetzt: kein Band
--wpce-head-color	Text darauf	custom.wpce.head.color; nicht gesetzt: Textfarbe der Seite
--wpce-head-muted	Einleitung darauf	custom.wpce.head.muted; nicht gesetzt: --wpce-muted
--wpce-head-accent	Zeile über dem Titel, Kennzeichen, Initialen	custom.wpce.head.accent; nicht gesetzt: --wpce-accent
--wpce-head-link	Links des Pfads	custom.wpce.head.link; nicht gesetzt: Textfarbe
--wpce-head-padding-top	Raum im Band oben	custom.wpce.head.padding-top; nicht gesetzt: 0
--wpce-head-padding-bottom	Raum im Band unten	custom.wpce.head.padding-bottom; nicht gesetzt: 0
--wpce-head-gap	Abstand zu dem, was folgt	custom.wpce.head.gap; nicht gesetzt: --wpce-gap-section
--wpce-head-placeholder	Grund des Titelbilds, bis es geladen ist	custom.wpce.head.placeholder; nicht gesetzt: --wpce-surface
--wpce-head-image-ratio	Seitenverhältnis des Titelbilds. Setzt das Plugin je Bild	vom Plugin gesetzt, nicht von Hand
--wpce-head-image-width	Breite des Titelbilds. Setzt das Plugin je Bild	vom Plugin gesetzt, nicht von Hand

Chronik

Token	Steuert	Standard
--wpce-timeline-period	Spalte der Jahreszahlen der Chronik; am Block oder um ihn setzen	7.5rem

Bewegung

Kurz und klein. Ein Theme setzt Zeiten auf 0s und Wege auf 0px (Zoom auf 1), um sie auszuschalten. Das Theme setzt sie über custom.wpce.motion.*, siehe Die Bewegung dämpfen oder ausschalten.

Token	Steuert	Standard
--wpce-duration-fast	kurze Übergänge: Farben	custom.wpce.motion.duration.fast, sonst 150ms
--wpce-duration	Übergänge: Heben, Zoom	custom.wpce.motion.duration.base, sonst 250ms
--wpce-ease	Verlauf der Übergänge	custom.wpce.motion.ease.out, sonst cubic-bezier(0.22, 1, 0.36, 1)
--wpce-lift	wie weit sich eine Karte hebt	custom.wpce.motion.distance.lift, sonst 3px
--wpce-arrow-shift	wie weit ein Pfeil vorrückt	custom.wpce.motion.distance.arrow, sonst 4px
--wpce-zoom	Zoom eines Bildes unter dem Zeiger	custom.wpce.motion.scale.image, sonst 1.04

Nicht zugesagt

Sechs Eigenschaften stehen im Code, aber nicht im Vertrag. Sie können sich ändern, auch ohne neue Hauptversion; stütze dich nicht auf sie.

• --wpce-step-20 bis --wpce-step-60: die Stufen des Themes, als Länge gelesen. Sie sind der Eingang der Abstands-Token und nicht zum Setzen gedacht. Setze stattdessen --wpce-gap-xs, --wpce-gap-sm, --wpce-gap, --wpce-gap-lg oder --wpce-gap-section.
• --wpce-collection-border: ein alter Name aus der Zeit vor den Token für die Linie der Karten in den Listen der Downloads. Setze stattdessen --wpce-line.

Was schiefgeht

• Ein Token, das nicht im Vertrag steht. Setz nur Token aus den Tabellen. Eine Eigenschaft, die du dir ausdenkst, liest niemand.
• Ein Wert ohne Einheit. --wpce-gap: 0 in einer Rechnung mit min() oder max() macht die ganze Rechnung ungültig, und jedes Polster wird null. Schreib 0px. Die Abstandsstufen liest das Plugin deshalb über registrierte Eigenschaften (@property, Syntax <length-percentage>), sodass ein nacktes 0 als 0px ankommt. Das schützt dich nur dort, nicht bei deinen eigenen Werten.
• Selektoren in das Innere eines Blocks. .wpce-card__title { … } ist kein Vertrag. Das Markup darin ändert sich ohne Ankündigung. Wähle ein Token oder einen Blockstil, siehe Der Vertrag.
• Ein dunkler Abschnitt ohne eigene Werte für --wpce-muted, --wpce-surface und --wpce-line. Der gedämpfte Text wird zu dunkel auf dunkel.
• Ein Token auf :root, das ein Abschnitt neu setzt. Token werden vererbt, der nächste Wert gewinnt. Setzt ein Abschnittsstil des Themes --wpce-accent auf dem Abschnitt, gilt in ihm sein Wert und nicht deiner von :root. Setz das Token dort, wo es gelten soll.

Weiter

• Block-Stile: feste Aussehen, die ein Redakteur im Editor wählt.
• Der Vertrag: warum die Namen hier halten.
• Farben, Schriften, Abstände: dieselben Werte in der theme.json des Childs.