Version:

Angular ​

Das Mate Design System stellt eine Angular-Komponentenbibliothek bereit, die auf Web Components basiert und vollständig in Angular-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
  • Ein bestehendes Angular-Projekt (ab Angular 21) oder die Bereitschaft, eines anzulegen
  • Npm-Konfiguration mit Zugriff auf das interne Package Registry

Falls du den Source Code sehen oder das Design System via Contribution mitgestalten möchtest und noch keinen Zugang zum GitLab hast, wende dich an das Entwicklungsteam oder tritt der Usergroup bei.

Installation ​

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

Erste Schritte ​

Nach der Installation muss das Stylesheet des Design Systems eingebunden werden. Füge den Import in deine styles.css oder angular.json ein. Siehe dazu das Angular-Beispiel in Theme.

Anschließend kannst du Komponenten direkt in deinen Angular-Komponenten importieren und verwenden. Ab Angular 17 sind Standalone Components der Standard – importiere die Mate-Komponenten direkt im imports-Array deiner Komponente:

typescript
import { Component } from '@angular/core';
import { MateFormLayoutComponent } from '@mate-angular/form-layout';
import { MateButtonComponent } from '@mate-angular/button';
import { MateTextFieldComponent } from '@mate-angular/text-field';

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [MateFormLayoutComponent, MateButtonComponent, MateTextFieldComponent],
  template: `
    <mate-form-layout>
      <mate-text-field label="Benutzername" />
      <mate-text-field label="Passwort" type="password" />
      <mate-button variant="primary" (click)="login()">Anmelden</mate-button>
    </mate-form-layout>
  `,
})
export class LoginComponent {
  login() {
    // Anmeldelogik
  }
}

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 folgt zu konfigurieren:

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

Arbeiten mit dem Design System ​

Die Angular-Komponenten des Mate Design Systems sind dünne Wrapper um die zugrundeliegenden Web Components. Props werden als Angular-Inputs übergeben, Events folgen der Angular-Konvention mit (eventName)-Bindungen.

Events und Outputs ​

Da die Komponenten auf Web Components basieren, werden Events als native CustomEvents ausgelöst. In Angular bindest du sie über die übliche (event)-Syntax:

typescript
import { Component } from '@angular/core';
import { MateComboBoxComponent } from '@mate-angular/combo-box';

@Component({
  selector: 'app-category-select',
  standalone: true,
  imports: [MateComboBoxComponent],
  template: `
    <mate-combo-box
      label="Kategorie"
      (value-changed)="onValueChanged($event)"
    />
  `,
})
export class CategorySelectComponent {
  onValueChanged(event: CustomEvent) {
    console.log(event.detail.value);
  }
}

Falls du programmatischen Zugriff auf das Element benötigst, nutze @ViewChild:

typescript
import { Component, ViewChild, ElementRef } from '@angular/core';

@Component({ /* ... */ })
export class MyComponent {
  @ViewChild('myField') myField!: ElementRef<HTMLElement>;
}

Formulare und reaktive Formulare ​

Mate-Eingabekomponenten lassen sich sowohl mit Template-driven Forms als auch mit Reactive Forms kombinieren. Für Reactive Forms verwendest du [value] zur Datenbindung und (value-changed) zur Aktualisierung des FormControls:

typescript
import { Component } from '@angular/core';
import { ReactiveFormsModule, FormControl } from '@angular/forms';
import { MateTextFieldComponent } from '@mate-angular/text-field';

@Component({
  selector: 'app-search',
  standalone: true,
  imports: [ReactiveFormsModule, MateTextFieldComponent],
  template: `
    <mate-text-field
      label="Suche"
      [value]="query.value"
      (value-changed)="query.setValue($event.detail.value)"
    />
  `,
})
export class SearchComponent {
  query = new FormControl('');
}

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 Inputs 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 das Stylesheet in deiner styles.css oder angular.json eingebunden ist. Ohne das Stylesheet werden die Web Components zwar gerendert, aber ohne die Mate-Styles.

Angular meldet unbekannte Elemente. Stelle sicher, dass die Mate-Komponenten im imports-Array der jeweiligen Standalone Component (oder im NgModule) eingetragen sind. Fehlt der Import, behandelt Angular das Element als unbekanntes HTML-Element.

Events kommen nicht an. Prüfe den Eventnamen in der Komponentendokumentation. Web Component Events werden in Angular-Templates in Kebab-Case gebunden – also (value-changed) statt (valueChanged). Bei Problemen beide Schreibweisen ausprobieren.

[value]-Binding aktualisiert die Anzeige nicht. Web Components reagieren auf Property-Änderungen, nicht zwingend auf Attribut-Änderungen. Stelle sicher, dass du die eckige-Klammer-Syntax [value] verwendest und nicht das Attribut direkt setzt.

Das Paket wird nicht gefunden. Überprüfe deine .npmrc-Konfiguration und stelle sicher, dass die @mate und @mate-angular Registry richtig ist. Die Pakete benötigen normalerweise kein extra Token.

Weitere Informationen ​