Theme

Das Theme wird benötigt, um alle Styles für die Mate-Komponenten bereitzustellen. Ohne das Theme werden Komponenten zwar korrekt gerendert, aber vollständig ohne das AKDB-Erscheinungsbild – also unstyled. Das Einbinden des Themes ist daher ein Pflichtschritt beim Setup jeder Anwendung, die Mate-Komponenten verwendet.

Wie funktioniert das Theme?

Das Mate Theme bündelt die gesamten CSS-Stile des Design Systems. Es basiert auf Design Tokens – CSS Custom Properties im Namespace --mate-* (z. B. --mate-blue-60, --mate-spacing-md) –, die Farben, Abstände, Typografie, Radien und weitere visuelle Eigenschaften definieren. Diese Tokens werden vom Theme auf alle Vaadin- und Mate-Komponenten angewendet.

Wichtig

Verwende in Mate-Projekten ausschließlich Tokens aus dem Namespace --mate- für eigene Styles. Die Variablen --lumo- und --aura- des Vaadin-Basis-Themes sind im Mate-Kontext nicht definiert und führen zu fehlenden oder fehlerhaften Darstellungen.

Design Tokens

Alle visuellen Eigenschaften im Mate Design System sind als Design Tokens in CSS Custom Properties abgebildet. Sie ermöglichen konsistente, wartbare und skalierbare Benutzeroberflächen.

Beispiele:

Token	Ebene	Verwendung
--mate-blue-60	Core	Farbwert der Primärpalette
--mate-signal-primary	semantisch	Primärfarbe des UI
--mate-spacing-md	semantisch	mittlerer Abstand
--mate-typography-body-md-regular-font-size	semantisch	Schriftgröße für Fließtext
--mate-corner-radius-md	semantisch	mittlerer Eckenradius für Komponenten

Tokens sind auf vier Ebenen strukturiert:

• Core-Ebene – Rohwerte wie eine konkrete Farbe oder ein Maß in rem. Sie ändern sich in keinem Theme.
• Interne Theme-Varianten – die Werte je Theme, erkennbar am Segment light, dark, desktop oder mobile. Sie sind kein Teil der öffentlichen Schnittstelle.
• Semantische Ebene – die Ebene, die Anwendungen verwenden. Ihre Tokens tragen eine Rolle statt eines Werts und wechseln beim Theme-Wechsel automatisch mit.
• Component-Ebene – semantische Tokens einzelner Komponenten mit dem Präfix --mate-components-.

Verwende in eigenem CSS die semantische Ebene und die Component-Ebene. Die Core-Ebene nur dort, wo kein semantischer Token die Rolle trägt; die internen Varianten nie, weil sie nicht umschalten.

Eine vollständige Übersicht aller Token-Kategorien mit Anzahl, Theme-Verhalten und Verweis auf den jeweiligen Katalog findest du in der Design Tokens Dokumentation.

Themes

Das Theme kennt zwei unabhängige Achsen und eine Sonderform. Die Farb-Achse umfasst Light und Dark und folgt standardmäßig der Systemeinstellung. Die Geräte-Achse umfasst Desktop und Mobile und schaltet auf touchbedienten Geräten automatisch um; sie verändert Größen, Abstände und Schriftgrößen. Dazu kommt der High Contrast Mode, der die Farben des Betriebssystems übernimmt und von der Anwendung selbst aktiviert werden muss.

Gesteuert werden die Themes über das theme-Attribut; die Achsen lassen sich frei kombinieren. Welche Werte es gibt, wie die Umschaltung funktioniert und was ein Theme nicht verändert, steht unter Themes.

Einbinden

Das Theme wird als Paket installiert und einmal im Einstiegspunkt der Anwendung importiert. Installation und Import zeigt der Code-Bereich zu dieser Seite; er gilt für Web Components, React und Vue. Für Vaadin Flow wird stattdessen das Flow-Theme als Maven-Abhängigkeit eingebunden – siehe Frameworks > Flow.