Version:

Vue ​

Das Mate Design System stellt eine Vue-Komponentenbibliothek bereit, die auf Web Components basiert und vollständig in Vue-3-Projekte integriert werden kann. Die Komponenten folgen den Designprinzipien des Mate Design Systems und sind so konzipiert, dass sie konsistent, zugänglich und wiederverwendbar sind.

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 Vue-3-Projekt oder die Bereitschaft, eines anzulegen
  • Npm- oder Yarn-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 Vue-Registry in deine .npmrc-Datei im Projektstamm ein und installiere anschließend das Vue-Paket des Mate Design Systems. Wie das genau funktioniert, erfährst du in Installation im Vue-Beispiel.

Erste Schritte ​

Nach der Installation muss das Stylesheet des Design Systems in deinen Einstiegspunkt importiert werden. Füge den Import am Anfang deiner main.ts ein. Siehe dazu das Vue-Beispiel in Theme.

Anschließend stehen alle Mate-Komponenten global in deinen Templates zur Verfügung:

vue
<template>
  <MateFormLayout>
    <MateTextField label="Benutzername" />
    <MateTextField label="Passwort" type="password" />
    <MateButton variant="primary" @click="login">Anmelden</MateButton>
  </MateFormLayout>
</template>

<script setup lang="ts">
function login() {
  // Anmeldelogik
}
</script>

Das war es im Wesentlichen. Sobald das Plugin und das Stylesheet eingebunden sind, verhält sich jede Komponente wie erwartet – du musst kein weiteres Setup durchführen.

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 ​

Die Vue-Komponenten des Mate Design Systems sind Wrapper um die zugrundeliegenden Web Components, die sich nahtlos in Vues Reaktivitätssystem integrieren. Props werden als reguläre Vue-Props übergeben, Events folgen der Vue-Konvention mit @-Bindungen.

Events und v-model ​

Für Eingabekomponenten steht v-model zur Verfügung, sofern die Komponente das entsprechende Emitter-Interface implementiert:

vue
<template>
  <MateTextField label="Suche" v-model="query" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const query = ref('');
</script>

Falls v-model für eine Komponente nicht unterstützt wird, kannst du den Event manuell binden:

vue
<template>
  <MateCombobox
    label="Kategorie"
    :value="selected"
    @value-changed="onValueChanged"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const selected = ref('');

function onValueChanged(event: CustomEvent) {
  selected.value = event.detail.value;
}
</script>

Beachte, dass Web Component Events in Vue typischerweise in Kebab-Case angegeben werden, also @value-changed statt @valueChanged.

Formulare und Validierung ​

Mate-Eingabekomponenten lassen sich gut mit Formular-Bibliotheken wie VeeValidate kombinieren. Da die Komponenten als reguläre HTML-Elemente im DOM erscheinen, greifen die meisten Validierungsansätze ohne zusätzliche Konfiguration.

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. Nutze die bereitgestellten Props – label, required, error-message, helper-text – konsequent und mit aussagekräftigen Inhalten.

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. Mate-Komponenten sind so entworfen, dass sie eigenständige Einheiten sind. Versuche nicht, interne DOM-Strukturen der Web Components direkt zu manipulieren – nutze immer die offiziell dokumentierten Props 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.

Typen nutzen. Das Paket liefert TypeScript-Definitionen mit. Nutze diese konsequent, um Fehler frühzeitig zu erkennen und die Autovervollständigung in deinem Editor zu verbessern.

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 der CSS-Import in deiner main.ts vorhanden und korrekt ist. Ohne das Stylesheet werden die Web Components zwar gerendert, aber ohne die Mate-Styles.

Vue gibt Warnungen zu unbekannten Komponenten aus. Stelle sicher, dass app.use(MatePlugin) vor app.mount() aufgerufen wird. Falls Komponenten trotzdem nicht erkannt werden, prüfe, ob du die korrekte Plugin-Instanz importierst.

v-model funktioniert nicht wie erwartet. Nicht alle Komponenten implementieren das v-model-Interface. Wechsle in diesem Fall auf die explizite :value-Bindung kombiniert mit einem @value-changed-Handler.

Events kommen nicht an. Prüfe den Eventnamen in der Komponentendokumentation. Web Component Events können in Vue sowohl in camelCase als auch in Kebab-Case gebunden werden – bei Problemen beide Varianten ausprobieren.

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 ​