Version:

React ​

Das Mate Design System stellt eine React-Komponentenbibliothek bereit, die auf Web Components basiert und vollständig in React-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 React-Projekt (ab React 18) 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 React-Registry in deine .npmrc-Datei im Projektstamm ein und installiere anschließend das React-Paket des Mate Design Systems. Wie das genau funtioniert erfährst du in Installation im React-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.tsx oder index.tsx ein. Siehe dazu das React-Beispiel in Theme.

Anschließend kannst du Komponenten direkt aus dem Paket importieren und in deinen React-Komponenten verwenden:

tsx
import { MateFormLayout } from '@mate-react/form-layout';
import { MateButton } from '@mate-react/button';
import { MateTextField } from '@mate-react/text-field';

function LoginForm() {
  return (
    <MateFormLayout>
      <MateTextField label="Benutzername" />
      <MateTextField label="Passwort" type="password" />
      <MateButton variant="primary">Anmelden</MateButton>
    </MateFormLayout>
  );
}

Das war es im Wesentlichen. Sobald das Stylesheet eingebunden ist, 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 React-Komponenten des Mate Design Systems sind dünne Wrapper um die zugrundeliegenden Web Components. Das bedeutet, dass Props und Events direkt an die Web Component weitergereicht werden. In der Regel sprichst du Komponenten über ihre dokumentierten Props an, so wie du es von anderen React-Komponentenbibliotheken kennst.

Events und Callbacks ​

Da die Komponenten auf Web Components basieren, werden Events als native CustomEvents ausgelöst. React wickelt diese in der Regel automatisch ab. Für den Fall, dass ein Event nicht über das übliche onChange-Muster reagiert, kannst du auf den nativen Event-Handler zurückgreifen:

tsx
import { MateCombobox } from '@mate-react/combo-box';
import { useRef } from 'react';

function CategorySelect() {
  const ref = useRef<HTMLElement>(null);

  return (
    <MateCombobox
      ref={ref}
      label="Kategorie"
      onValueChanged={(e) => console.log(e.detail.value)}
    />
  );
}

Formulare und kontrollierte Komponenten ​

Die Formularkomponenten des Mate Design Systems lassen sich mit React-State kombinieren. Verwende value und den zugehörigen Change-Handler, um kontrollierte Eingaben zu realisieren:

tsx
import { MateTextField } from '@mate-react/text-field';
import { useState } from 'react';

function SearchField() {
  const [query, setQuery] = useState('');

  return (
    <MateTextField
      label="Suche"
      value={query}
      onValueChanged={(e) => setQuery(e.detail.value)}
    />
  );
}

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 – stattdessen 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 deinem Einstiegspunkt vorhanden und korrekt ist. Ohne das Stylesheet werden die Web Components zwar gerendert, aber ohne die Mate-Styles.

TypeScript meldet unbekannte Props. Stelle sicher, dass du eine aktuelle Version des Pakets verwendest und deine tsconfig.json JSX korrekt konfiguriert hat ("jsx": "react-jsx"). Gelegentlich hilft es, den TypeScript-Server im Editor neu zu starten.

Events feuern nicht wie erwartet. Web Component Events unterscheiden sich in ihrer Bubbling-Konfiguration von regulären DOM-Events. Falls ein Event nicht ankommt, prüfe in der Komponentendokumentation, ob das Event als composed: true definiert ist, oder greife auf den ref-Ansatz zurück.

Hydration-Fehler in SSR-Setups (z. B. Next.js). Web Components und Server-Side Rendering vertragen sich grundsätzlich, erfordern aber eine sorgfältige Konfiguration. Stelle sicher, dass die Komponenten clientseitig registriert werden. Wende dich bei Bedarf an das Mate-Team für eine spezifische Hilfestellung.

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 ​