Version:

Web Components ​

Das Mate Design System stellt seine Komponenten als native Web Components bereit. Das bedeutet, du kannst sie in jedem modernen Browser und in jedem Framework – oder ganz ohne Framework – verwenden. Diese Seite richtet sich an Teams, die Web Components direkt einsetzen möchten, etwa in leichtgewichtigen Applikationen, Micro-Frontends oder in Projekten, die bewusst auf schwere Abhängigkeiten verzichten.

Voraussetzungen ​

Bevor du mit der Integration beginnst, stelle sicher, dass folgende Voraussetzungen erfüllt sind:

  • Node.js in einer aktuellen LTS-Version
  • Zugang zum AKDB GitLab (exklusiv für Mitglieder des AKDB-Verbunds)
  • Ein bestehendes Webprojekt oder die Bereitschaft, eines anzulegen
  • Npm-Konfiguration mit Zugriff auf das interne Package Registry

Falls du noch keinen Zugang zum GitLab hast, wende dich an das Mate-Team oder tritt der Usergroup bei (Einladung via Giesbrecht.Tim@akdb.de).

Installation ​

Konfiguriere zunächst den Zugang zum internen Package Registry. Füge dazu die Registry in deine .npmrc-Datei im Projektstamm ein und installiere anschließend das Web-Components-Paket des Mate Design Systems. Wie das genau funktioniert, erfährst du in Installation im Web-Components-Beispiel.

Erste Schritte ​

Nach der Installation muss das Stylesheet des Design Systems eingebunden werden. Füge den Import am Anfang deines Einstiegspunkts ein. Siehe dazu das Web-Components-Beispiel in Theme.

Danach stehen alle Mate-Elemente als Custom Elements im HTML zur Verfügung:

html
<mate-form-layout>
  <vaadin-text-field label="Benutzername"></vaadin-text-field>
  <vaadin-text-field label="Passwort" type="password"></vaadin-text-field>
  <vaadin-button variant="primary">Anmelden</vaadin-button>
</mate-form-layout>

Das war es im Wesentlichen. Sobald das Stylesheet eingebunden und defineMateComponents() aufgerufen ist, kannst du alle Komponenten direkt im Markup verwenden.

Internationalization (i18n) ​

Um die Barrierefreiheit gewährleisten zu können, sollte überall, wo möglich das i18n Property gesetzt werden. Um standardmäßig Deutsche Texte zu erhalten, wird empfohlen den Einstiegspunkt der App wie folg zu konfigurieren:

javascript
import '@mate/i18n/src/apply-all';

Arbeiten mit dem Design System ​

Web Components verhalten sich wie gewöhnliche HTML-Elemente. Du kannst Properties über JavaScript setzen, Events abhören und Slots mit eigenen Inhalten befüllen – alles über Standard-DOM-APIs.

Properties und Attribute ​

Einfache Werte wie Strings und Booleans lassen sich als HTML-Attribute setzen. Komplexere Werte – Arrays, Objekte – müssen per JavaScript als Property zugewiesen werden:

ts
const combobox = document.querySelector('vaadin-combobox');

// Property setzen
combobox.items = [
  { label: 'Option A', value: 'a' },
  { label: 'Option B', value: 'b' },
];

Events ​

Mate-Komponenten lösen CustomEvents aus, die du mit addEventListener abhören kannst:

ts
const textField = document.querySelector('vaadin-text-field');

textField.addEventListener('value-changed', (event) => {
  console.log(event.detail.value);
});

Events bubbleln in der Regel durch den DOM-Baum, sofern sie als composed: true definiert sind. In der Komponentendokumentation findest du für jede Komponente die ausgelösten Events und ihre Detail-Struktur.

Slots ​

Viele Mate-Komponenten erlauben es, eigene Inhalte über Slots einzufügen. Slots werden im HTML direkt als Kindelemente mit einem slot-Attribut angegeben:

html
<vaadin-card>
  <span slot="header">Kartentitel</span>
  <p>Hauptinhalt der Karte.</p>
  <vaadin-button slot="footer" variant="tertiary">Mehr erfahren</vaadin-button>
</vaadin-card>

Welche Slots eine Komponente anbietet, ist in der jeweiligen Komponentendokumentation beschrieben.

Zugänglichkeit ​

Die Komponenten des Mate Design Systems bringen eine solide Basis für barrierefreie Anwendungen mit: ARIA-Rollen, Tastaturnavigation und Screenreader-Unterstützung sind in die Komponenten eingebaut. Das bedeutet aber nicht, dass eine Anwendung automatisch barrierefrei ist – das hängt entscheidend davon ab, wie die Komponenten verwendet werden.

Konkret: Ein Button ohne lesbaren Text, ein Eingabefeld ohne Label oder eine Pflichtangabe, die nicht als solche markiert ist, sind auch mit Mate-Komponenten nicht zugänglich. Vergib als HTML-Attribut immer ein label, setze required wenn nötig und nutze error-message sowie helper-text, um Nutzenden verständlich zu machen, was von ihnen erwartet wird.

Darüber hinaus gibt es Aspekte der Barrierefreiheit, die grundsätzlich kontextabhängig sind und nicht von einer Komponentenbibliothek gelöst werden können: Fokus-Management nach Seitenübergängen, Live-Regionen für dynamisch aktualisierte Inhalte oder die Reihenfolge von Überschriften im Dokumentenbaum. Diese liegen in der Verantwortung der Anwendungsentwicklung.

Best Practices ​

Komponentengrenzen respektieren. Versuche nicht, über Shadow-DOM-Piercing oder interne CSS-Selektoren in die Komponenten einzugreifen. Nutze ausschließlich die dokumentierten Properties, Attribute, Events und Slots.

Konsistenz durch das Design System sicherstellen. Verwende ausschließlich Mate-Komponenten für UI-Elemente, die im Design System definiert sind. Eigenentwicklungen für Buttons, Eingabefelder oder Dialoge führen zu Inkonsistenzen und erhöhen den Wartungsaufwand.

defineMateComponents() nur einmal aufrufen. Mehrfache Aufrufe führen zu Warnungen im Browser, da Custom Elements nur einmal pro Tag definiert werden können.

Keine Inline-Styles auf Mate-Komponenten. Das Design System definiert alle visuellen Aspekte über Design Tokens. Inline-Styles überschreiben diese und führen zu unerwünschten Abweichungen. Falls du Abstände oder Layouts anpassen musst, tue das auf der umgebenden Wrapper-Ebene.

Updates im Blick behalten. Das Design System entwickelt sich weiter. Abonniere den Release-Kanal oder halte Ausschau nach Changelog-Einträgen, wenn du das Paket aktualisierst – Breaking Changes werden dort kommuniziert.

Troubleshooting ​

Komponenten werden unstyled dargestellt. Überprüfe, ob das Stylesheet korrekt eingebunden ist. Ohne das CSS-File werden die Web Components zwar gerendert, aber ohne die Mate-Styles.

Elemente werden nicht als Custom Elements erkannt (z. B. <mate-button> erscheint als unbekanntes Element). Stelle sicher, dass defineMateComponents() aufgerufen wird, bevor die Komponenten im DOM erscheinen. Bei dynamisch geladenem Markup kann es helfen, den Aufruf ganz an den Anfang des Einstiegspunkts zu legen.

Properties lassen sich nicht setzen. Überprüfe, ob das Element bereits im DOM vorhanden ist, bevor du Properties setzt. Greife erst nach DOMContentLoaded oder nach dem expliziten Einfügen des Elements auf seine Properties zu.

Events kommen nicht an. Prüfe, ob das Event als composed: true definiert ist. Events mit composed: false verlassen den Shadow DOM nicht und müssen direkt am Element abgehört werden, nicht an einem Vorfahren-Element.

Das Paket wird nicht gefunden. Überprüfe deine .npmrc-Konfiguration und stelle sicher, dass der Auth-Token aktuell ist. Tokens laufen in der Regel nach einer bestimmten Zeit ab und müssen erneuert werden.

Weitere Informationen ​