Grundlagen

@mmm/designsystem

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

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 Oberflächen entwickeln können.

Inhalt des Projekts

• Angular-Komponenten für häufig genutzte UI-Bausteine
• Design Tokens als Grundlage für Farben, Abstände und weitere Styles
• Build-Skripte für Library, Tokens und Icons
• Astro-basierte Dokumentation für 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:

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

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

Lokale Entwicklung

Abhängigkeiten installieren:

pnpm install

Wichtige Befehle:

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 Abhängigkeiten installiert wurden.

pnpm build Führt den kompletten Projekt-Build aus. Zuerst werden die Design Tokens generiert und anschließend die eigentliche Library gebaut. Dieser Befehl ist der zentrale Standard-Build für lokale Entwicklung und Validierung.

pnpm clean Räumt 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 ändert.

pnpm tokens:build Generiert die Design Tokens des Projekts. Dazu gehören die technischen Ableitungen der zentral gepflegten Designwerte, zum Beispiel für Farben, Abstände oder weitere stilistische Grundlagen.

pnpm tokens:watch Startet einen Watch-Modus für die Design Tokens. Änderungen 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 später über die Registry bereitgestellt werden.

pnpm docs:dev Startet die lokale Astro-Dokumentation im Entwicklungsmodus. Dieser Befehl ist für 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 prüfen.

pnpm astro Stellt den direkten Zugriff auf die Astro-CLI bereit. Das ist vor allem dann nützlich, wenn weitere Astro-Kommandos direkt über das Projekt ausgeführt werden sollen.

pnpm docs:sync Synchronisiert Komponenten-Dokumentation. Der Befehl dient dazu, dokumentationsbezogene Inhalte oder Ableitungen aus den Komponenten in den Docs-Bereich zu überführen.

pnpm docs:build Baut die komplette Dokumentationsseite als statisches Astro-Ergebnis. Dieser Schritt wird für Deployments oder zur Prüfung 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 Änderungen zwischen HEAD^ und HEAD.

Regeln:

• Änderungen außerhalb von src/components/ führen zu keinem Release
• Änderungen an bestehenden Komponenten-Dateien führen zu einem patch
• Neue, gelöschte oder umbenannte Komponenten-Dateien führen zu einem minor
• Änderungen an src/components/index.ts führen ebenfalls zu einem minor

pnpm ci:resolve-next-version Berechnet die nächste Paketversion auf Basis der bereits veröffentlichten Registry-Version und des RELEASE_TYPE.

Regeln:

• minor erhöht die Nebenversionsnummer und setzt patch auf 0
• patch erhöht 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 über 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/ für die Veröffentlichung vor. Dabei werden Metadaten aus dem Root-package.json übernommen, die Zielversion gesetzt, die Registry konfiguriert und die README.md in den Auslieferungsordner kopiert.

pnpm ci:bump-version Erhöht die Version in der Root-package.json anhand des RELEASE_TYPE. Auch dieser Schritt unterstützt derzeit patch und minor.

pnpm ci:update-manifest Aktualisiert in einem separaten Manifest-Repository den Docker-Image-Tag für die Dokumentation und pusht die Änderung anschließend automatisiert auf den konfigurierten Branch.

CI-Konzept

Die CI-Pipeline ist darauf ausgelegt, Releases nicht manuell pflegen zu müssen, sondern den Releasetyp aus den Komponenten-Änderungen 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/ geändert haben.
2. Daraus ergibt sich none, patch oder minor.
3. pnpm ci:resolve-next-version berechnet auf Basis der Registry-Version die nächste zu veröffentlichende Version.
4. pnpm ci:prepare-publish bereitet das Paket in dist/ für die Registry vor.
5. Optional kann über pnpm ci:update-manifest ein nachgelagertes Manifest-Repository aktualisiert werden.

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

Husky-Hook

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

Der Hook prüft, ob gestagte Änderungen unter src/components/ liegen:

• Wenn keine Komponenten betroffen sind, wird der Build übersprungen
• Wenn Komponenten betroffen sind, führt der Hook automatisch pnpm build aus

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