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:
pnpm config set @mmm:registry https://npm.dev.appcenter.depnpm login --registry https://npm.dev.appcenter.deAlternativ kann die Registry auch direkt in einer .npmrc hinterlegt werden:
@mmm:registry=https://npm.dev.appcenter.deAnschliessend 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:
pnpm installWichtige Befehle:
pnpm buildpnpm docs:devpnpm docs:buildPNPM-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 alle Aenderungen seit dem letzten Release-Tag (vX.Y.Z) in der Historie von HEAD. So werden auch mehrere direkt auf main gepushte Commits vollstaendig beruecksichtigt. Existiert noch kein Release-Tag, wird gegen HEAD^ verglichen. Ist HEAD selbst bereits getaggt (z. B. bei einem erneuten Pipeline-Lauf), ergibt sich none.
Relevant sind Dateien unter src/components/ und src/styling/components/. Ausgenommen ist die Dokumentation, die neben den Komponenten liegt, aber nicht ins Paket gebaut wird: die Live-Beispiele in docu/ bzw. doku/ und die .mdx-Doku-Seiten.
- Aenderungen ausserhalb dieser Ordner und reine Doku-Aenderungen fuehren zu keinem Release
- Aenderungen an bestehenden Komponenten- oder Komponenten-Styling-Dateien fuehren zu einem
patch - Neue, geloeschte oder umbenannte Komponenten- oder Komponenten-Styling-Dateien fuehren zu einem
minor - Aenderungen an
src/components/index.tsfuehren ebenfalls zu einemminor
pnpm ci:resolve-next-version
Berechnet die naechste Paketversion auf Basis des RELEASE_TYPE. Ausgangspunkt ist die hoechste bereits existierende Version aus zwei Quellen: allen in der Registry veroeffentlichten Versionen (npm view … versions) und allen vX.Y.Z-Tags im Remote-Repository (git ls-remote). Der latest-Dist-Tag wird bewusst nicht verwendet, da er hinter der hoechsten Version zurueckliegen kann.
minorerhoeht die Nebenversionsnummer und setztpatchauf0patcherhoeht nur die Patch-Version- Falls weder in der Registry noch als Git-Tag eine Version existiert, wird von
1.0.0aus gezaehlt (patch→1.0.1,minor→1.1.0) - Ist die Registry oder das Git-Remote nicht erreichbar (z. B. Netzwerk- oder Authentifizierungsfehler), bricht das Skript ab. Nur ein nicht existierendes Paket (
E404) gilt als „noch keine Version“ - Ist die berechnete Version nicht groesser als die hoechste existierende, bricht das Skript ab
pnpm ci:resolve-prerelease-version
Berechnet die naechste Vorabversion im Format <basis>-<name>.<n>, z. B. 1.18.0-next.4 oder 1.18.0-feature-tooltip.2 (siehe Vorabversionen).
<basis>ist die naechste stabile Version, wie sieci:resolve-next-versionfuer denRELEASE_TYPEberechnen wuerde<name>istPRERELEASE_NAME(z. B.next) oder, falls nicht gesetzt, ein Slug ausBITBUCKET_BRANCH(Kleinbuchstaben,a-z0-9-, max. 40 Zeichen, beginnt immer mit einem Buchstaben)<n>ist die hoechste vorhandene Nummer fuer dieselbe Basis und denselben Namen in der Registry plus 1latest,backport,mainund (als Branch-Name)nextsind als Name reserviert
pnpm ci:resolve-dist-tag
Bestimmt, mit welchem Dist-Tag die Version aus NEXT_VERSION veroeffentlicht wird. Ist sie hoeher als alle Versionen in der Registry, wird latest ausgegeben, sonst backport. So verschiebt ein Publish einer niedrigeren Version den latest-Tag nicht zurueck. Vorabversionen werden unter ihrem Namen veroeffentlicht (1.18.0-next.4 → next), nie als latest.
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:
pnpm ci:resolve-release-typeanalysiert, ob sich seit dem letzten Release-Tag relevante Dateien untersrc/components/odersrc/styling/components/geaendert haben (ohne Doku-Dateien).- Daraus ergibt sich
none,patchoderminor. pnpm ci:resolve-next-versionberechnet auf Basis der hoechsten Version aus Registry und Git-Tags die naechste zu veroeffentlichende Version. Existiert der Tag bereits, schlaegt die Pipeline fehl, statt das Release still zu ueberspringen.- In der Tag-Pipeline bestimmt
pnpm ci:resolve-dist-tagden Dist-Tag, undpnpm ci:prepare-publishbereitet das Paket indist/fuer die Registry vor. - Optional kann ueber
pnpm ci:update-manifestein 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.
Die Dokumentation (Changelog, Docs-Image, Manifest-Update) wird nur auf main gebaut.
Vorabversionen
Neben den stabilen Releases gibt es Vorabversionen, um neue Staende vorab in anderen Paketen und Apps zu testen. Sie haben einen Prerelease-Zusatz in der Versionsnummer (z. B. 1.18.0-next.4) und werden unter einem eigenen Dist-Tag veroeffentlicht. Normale Versionsbereiche wie ^1.17.0 installieren sie nie, man bekommt sie nur ueber den Dist-Tag. Vorabversionen erzeugen keinen Git-Tag und tauchen deshalb nicht im Changelog auf.
next | Branch-Paket | |
|---|---|---|
| Zweck | naechste Version mit allen gesammelten Features testen | einen einzelnen Branch testen, auch mehrere Alternativen parallel |
| Ausloeser | automatisch bei jedem Push/Merge auf den Branch next | manuell: Bitbucket → Pipelines → „Run pipeline“ → Branch waehlen → publish-branch-package |
| Version | 1.18.0-next.4 | 1.18.0-feature-tooltip.2 |
| Dist-Tag | next | Branch-Name als Slug, z. B. feature-tooltip |
- Auf
nextwird wie aufmainnur veroeffentlicht, wenn sich relevante Komponenten-Dateien geaendert haben. Reine Doku-Pushes veroeffentlichen nichts. - Ein Branch-Paket wird immer veroeffentlicht, auch ohne relevante Aenderungen (dann mit
patchals Basis). Aufmainundnextlaesst sich die Pipeline nicht starten.
Arbeitsablauf
Beim Committen und Pushen aendert sich nichts: Commit-Nachrichten bleiben wie bisher, Versionsnummern werden nie von Hand gesetzt. Welches Paket entsteht, haengt nur davon ab, auf welchem Branch gemerged wird.
git checkout -b feature/tooltip nextgit commit -m "feat(tooltip): add tooltip component"git push -u origin feature/tooltip # veroeffentlicht nichts# optional: Branch-Paket in Bitbucket starten → @feature-tooltip# PR nach next mergen → automatisch 1.18.0-next.N- Feature-Branches werden nach
nextgemerged. Jeder Merge veroeffentlicht eine neuenext-Version. - Fuer ein stabiles Release wird
nextnachmaingemerged. - Danach muss
nextwieder auf den Stand vonmaingebracht werden (neu vonmainanlegen odermainnachnextmergen). Sonst kenntnextden neuen Release-Tag nicht und berechnet eine zu hohe Basisversion.
Hotfixes koennen weiterhin direkt nach main gemerged werden.
Vorabversion installieren
pnpm add @mmm/designsystem@next # neueste next-Versionpnpm add @mmm/designsystem@feature-tooltip # Branch-Paketpnpm add @mmm/designsystem@latest # zurueck auf die stabile VersionHusky-Hook
Im Projekt ist aktuell ein Husky-pre-commit-Hook eingerichtet.
Der Hook prueft, ob gestagte Aenderungen unter src/components/ oder src/styling/components/ liegen:
- Wenn weder Komponenten noch Komponenten-Styles betroffen sind, wird der Build uebersprungen
- Wenn Komponenten oder Komponenten-Styles betroffen sind, fuehrt der Hook automatisch
pnpm buildaus
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.