Skip to content
Design System

designsystem

@mmm/designsystem

@mmm/designsystem ist das zentrale UI- und Designsystem-Projekt fuer MMM. Es stellt wiederverwendbare Angular-Komponenten, Design Tokens, Styles und die zugehoerige Dokumentation fuer Produktteams bereit. Ziel ist ein konsistentes Erscheinungsbild, wiederverwendbare UI-Bausteine und eine gemeinsame technische Grundlage fuer Frontends.

Inhalt des Projekts

  • Angular-Komponenten fuer haeufig genutzte UI-Bausteine
  • Design Tokens als Grundlage fuer Farben, Abstaende und weitere Styles
  • Build-Skripte fuer Library, Tokens und Icons
  • Astro-basierte Dokumentation fuer Grundlagen, Icons und Komponenten

Voraussetzungen

  • Node.js
  • pnpm
  • Zugriff auf die interne Registry https://npm.dev.appcenter.de

Registry einrichten

Bevor das Projekt installiert oder das Paket in anderen Anwendungen genutzt werden kann, muss die interne Registry eingebunden werden.

Beispiel mit pnpm:

Terminal window
pnpm config set @mmm:registry https://npm.dev.appcenter.de
pnpm login --registry https://npm.dev.appcenter.de

Alternativ kann die Registry auch direkt in einer .npmrc hinterlegt werden:

@mmm:registry=https://npm.dev.appcenter.de

Anschliessend ist ein Login gegen die Registry erforderlich. Falls der Login nicht funktioniert oder eine Registrierung nicht mehr moeglich ist, bitte bei Paul Wolter pwolter@m-m-m.de melden, damit die Registrierung wieder freigeschaltet wird.

Lokale Entwicklung

Abhaengigkeiten installieren:

Terminal window
pnpm install

Wichtige Befehle:

Terminal window
pnpm build
pnpm docs:dev
pnpm docs:build

PNPM-Befehle

Die folgenden Skripte sind in der package.json hinterlegt und bilden den Standard-Workflow des Projekts ab:

pnpm prepare

Installiert bzw. initialisiert Husky. Dadurch werden die Git-Hooks aus dem .husky-Verzeichnis lokal aktiviert, sobald Abhaengigkeiten installiert wurden.

pnpm build

Fuehrt den kompletten Projekt-Build aus. Zuerst werden die Design Tokens generiert und anschliessend die eigentliche Library gebaut. Dieser Befehl ist der zentrale Standard-Build fuer lokale Entwicklung und Validierung.

pnpm clean

Raeumt generierte Artefakte auf. Der Befehl ist hilfreich, wenn alte Build-Ergebnisse entfernt werden sollen, bevor ein sauberer Neuaufbau gestartet wird.

pnpm icons:build

Erzeugt bzw. aktualisiert die Icon-Artefakte des Designsystems. Dieser Schritt ist relevant, wenn sich die Icon-Quelle oder der generierte Icon-Bestand aendert.

pnpm tokens:build

Generiert die Design Tokens des Projekts. Dazu gehoeren die technischen Ableitungen der zentral gepflegten Designwerte, zum Beispiel fuer Farben, Abstaende oder weitere stilistische Grundlagen.

pnpm tokens:watch

Startet einen Watch-Modus fuer die Design Tokens. Aenderungen an den Token-Quellen werden dabei automatisch neu verarbeitet, ohne dass der Befehl manuell erneut gestartet werden muss.

pnpm lib:build

Baut die eigentliche Angular-Library des Designsystems. Dieser Schritt erstellt die auslieferbaren Paket-Artefakte, die spaeter ueber die Registry bereitgestellt werden.

pnpm docs:dev

Startet die lokale Astro-Dokumentation im Entwicklungsmodus. Dieser Befehl ist fuer die Arbeit an Grundlagen-, Icon- und Komponenten-Dokumentation gedacht.

pnpm docs:preview

Startet eine Vorschau der bereits gebauten Dokumentation. Sinnvoll ist dieser Befehl vor allem nach einem pnpm docs:build, um das Build-Ergebnis lokal zu pruefen.

pnpm astro

Stellt den direkten Zugriff auf die Astro-CLI bereit. Das ist vor allem dann nuetzlich, wenn weitere Astro-Kommandos direkt ueber das Projekt ausgefuehrt werden sollen.

pnpm docs:sync

Synchronisiert Komponenten-Dokumentation. Der Befehl dient dazu, dokumentationsbezogene Inhalte oder Ableitungen aus den Komponenten in den Docs-Bereich zu ueberfuehren.

pnpm docs:build

Baut die komplette Dokumentationsseite als statisches Astro-Ergebnis. Dieser Schritt wird fuer Deployments oder zur Pruefung des finalen Doku-Outputs verwendet.

pnpm ci:resolve-release-type

Bestimmt automatisiert, ob ein Release vom Typ none, patch oder minor vorliegt. Grundlage sind die Aenderungen zwischen HEAD^ und HEAD.

  • Aenderungen ausserhalb von src/components/ fuehren zu keinem Release
  • Aenderungen an bestehenden Komponenten-Dateien fuehren zu einem patch
  • Neue, geloeschte oder umbenannte Komponenten-Dateien fuehren zu einem minor
  • Aenderungen an src/components/index.ts fuehren ebenfalls zu einem minor

pnpm ci:resolve-next-version

Berechnet die naechste Paketversion auf Basis der bereits veroeffentlichten Registry-Version und des RELEASE_TYPE. Automatisiert werden hier aktuell patch und minor.

  • minor erhoeht die Nebenversionsnummer und setzt patch auf 0
  • patch erhoeht nur die Patch-Version
  • Falls noch keine Version in der Registry existiert, werden Initialwerte erzeugt

pnpm ci:resolve-version-from-tag

Liest die Version aus einem Git-Tag ueber die Umgebungsvariable BITBUCKET_TAG. Erwartet wird ein Format wie v1.2.3 oder 1.2.3.

pnpm ci:prepare-publish

Bereitet das Paket in dist/ fuer die Veroeffentlichung vor. Dabei werden Metadaten aus dem Root-package.json uebernommen, die Zielversion gesetzt, die Registry konfiguriert und die README.md in den Auslieferungsordner kopiert.

pnpm ci:bump-version

Erhoeht die Version in der Root-package.json anhand des RELEASE_TYPE. Auch dieser Schritt unterstuetzt derzeit patch und minor.

pnpm ci:update-manifest

Aktualisiert in einem separaten Manifest-Repository den Docker-Image-Tag fuer die Dokumentation und pusht die Aenderung anschliessend automatisiert auf den konfigurierten Branch.

CI-Konzept

Die CI-Pipeline ist darauf ausgelegt, Releases nicht manuell pflegen zu muessen, sondern den Releasetyp aus den Komponenten-Aenderungen abzuleiten.

Wichtig ist dabei: Im aktuellen Stand werden patch und minor automatisiert behandelt. Ein automatisches major-Release ist in den vorhandenen Skripten nicht implementiert.

Der Ablauf ist konzeptionell wie folgt:

  1. pnpm ci:resolve-release-type analysiert, ob sich relevante Dateien unter src/components/ geaendert haben.
  2. Daraus ergibt sich none, patch oder minor.
  3. pnpm ci:resolve-next-version berechnet auf Basis der Registry-Version die naechste zu veroeffentlichende Version.
  4. pnpm ci:prepare-publish bereitet das Paket in dist/ fuer die Registry vor.
  5. Optional kann ueber pnpm ci:update-manifest ein nachgelagertes Manifest-Repository aktualisiert werden.

Damit wird sichergestellt, dass Aenderungen an bestehenden Komponenten in der Regel als Bugfix- oder kleine Verbesserungsversion erscheinen, waehrend strukturelle Erweiterungen im Komponentenbestand eine neue Minor-Version erzeugen.

Husky-Hook

Im Projekt ist aktuell ein Husky-pre-commit-Hook eingerichtet.

Der Hook prueft, ob gestagte Aenderungen unter src/components/ liegen:

  • Wenn keine Komponenten betroffen sind, wird der Build uebersprungen
  • Wenn Komponenten betroffen sind, fuehrt der Hook automatisch pnpm build aus

Dadurch wird vor dem Commit sichergestellt, dass relevante Komponenten-Aenderungen direkt gegen den Build validiert werden. Eine pre-push-Hook-Datei liegt im aktuellen Repository-Stand dagegen nicht vor.

Ziel des Designsystems

Das Projekt dient dazu, wiederkehrende UI-Muster zu standardisieren und Entwicklung in mehreren Anwendungen zu vereinfachen. Komponenten, Tokens und Dokumentation werden hier gemeinsam gepflegt, damit Teams schneller konsistente und wartbare Oberflaechen entwickeln koennen.