Skip to content

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 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.ts fuehren ebenfalls zu einem minor

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.

  • minor erhoeht die Nebenversionsnummer und setzt patch auf 0
  • patch erhoeht nur die Patch-Version
  • Falls weder in der Registry noch als Git-Tag eine Version existiert, wird von 1.0.0 aus 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 sie ci:resolve-next-version fuer den RELEASE_TYPE berechnen wuerde
  • <name> ist PRERELEASE_NAME (z. B. next) oder, falls nicht gesetzt, ein Slug aus BITBUCKET_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 1
  • latest, backport, main und (als Branch-Name) next sind 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:

  1. pnpm ci:resolve-release-type analysiert, ob sich seit dem letzten Release-Tag relevante Dateien unter src/components/ oder src/styling/components/ geaendert haben (ohne Doku-Dateien).
  2. Daraus ergibt sich none, patch oder minor.
  3. pnpm ci:resolve-next-version berechnet 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.
  4. In der Tag-Pipeline bestimmt pnpm ci:resolve-dist-tag den Dist-Tag, und 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.

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.

nextBranch-Paket
Zwecknaechste Version mit allen gesammelten Features testeneinen einzelnen Branch testen, auch mehrere Alternativen parallel
Ausloeserautomatisch bei jedem Push/Merge auf den Branch nextmanuell: Bitbucket → Pipelines → „Run pipeline“ → Branch waehlen → publish-branch-package
Version1.18.0-next.41.18.0-feature-tooltip.2
Dist-TagnextBranch-Name als Slug, z. B. feature-tooltip
  • Auf next wird wie auf main nur 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 patch als Basis). Auf main und next laesst 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.

Terminal window
git checkout -b feature/tooltip next
git 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
  1. Feature-Branches werden nach next gemerged. Jeder Merge veroeffentlicht eine neue next-Version.
  2. Fuer ein stabiles Release wird next nach main gemerged.
  3. Danach muss next wieder auf den Stand von main gebracht werden (neu von main anlegen oder main nach next mergen). Sonst kennt next den neuen Release-Tag nicht und berechnet eine zu hohe Basisversion.

Hotfixes koennen weiterhin direkt nach main gemerged werden.

Vorabversion installieren

Terminal window
pnpm add @mmm/designsystem@next # neueste next-Version
pnpm add @mmm/designsystem@feature-tooltip # Branch-Paket
pnpm add @mmm/designsystem@latest # zurueck auf die stabile Version

Husky-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 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.