docs(blog): explain components, themes and peer dependencies

blog/2025-08-19.mdx

@@ -0,0 +1,35 @@
+---
+title: Komponenten-Paket, Themes und Peer Dependencies
+authors: deleonio
+---
+
+# Komponenten-Paket, Themes und Peer Dependencies
+
+In unserem Projekt arbeiten mehrere NPM-Pakete zusammen, um wiederverwendbare Oberflächen zu schaffen. Das Herzstück ist das Components-Paket. Es liefert die Web Components mit ihrer Funktionalität, aber ohne festes Styling. Dadurch bleibt jede Komponente schlank und kann in unterschiedlichsten Designkonzepten eingesetzt werden.
+
+## Headless Komponenten
+
+Die Komponenten sind bewusst headless aufgebaut. Sie enthalten also keinerlei Vorgaben für Farben, Abstände oder Schriftarten. Diese Freiheit erlaubt es jeder Organisation, das Aussehen komplett selbst zu bestimmen und die Komponenten nahtlos in bestehende Designsysteme einzubetten.
+
+## Themes bringen das Styling
+
+Das Aussehen kommt über separate Theme-Pakete ins Spiel. Ein Theme beschreibt die Gestaltung von Buttons, Formularfeldern oder Tabellen – kurz: es liefert das visuelle Auftreten. Wer die Komponenten nutzt, kann ein eigenes Theme schreiben und so denselben Funktionsumfang mit einer individuellen Oberfläche kombinieren.
+
+## Peer Dependencies: Versionssicherheit
+
+Damit klar ist, welche Theme-Version zu welcher Components-Version passt, setzen wir auf Peer Dependencies. In einem Theme-Paket steht als Peer Dependency der Versionsbereich des Components-Pakets, für den das Theme gedacht ist. Bei uns gilt eine einfache Regel: Eine Theme-Version gehört exakt zu einer Components-Version.
+
+## Installieren und Prüfen
+
+Beim `npm install` prüft NPM automatisch, ob die Peer Dependencies erfüllt sind. Stimmen die Versionen nicht überein, erscheint eine Fehlermeldung. Dieser Hinweis ist gewollt, denn er verhindert, dass man eine Kombination installiert, die später Probleme macht.
+
+## Kein Legacy-Modus
+
+NPM bietet die Option `legacy peer deps`, die diese Prüfung abschaltet. In unserem Setup darf dieser Modus nicht verwendet werden. Ohne die Fehlermeldungen würden leicht falsche oder kaputte Installationen entstehen.
+
+## Fazit
+
+- Components-Paket: liefert die funktionalen Bausteine ohne Styling.
+- Theme-Paket: liefert das Aussehen.
+- Peer Dependencies: stellen sicher, dass beides exakt zusammenpasst.
+- Fehlermeldungen von NPM: sind gewünscht und schützen vor falschen Kombinationen.

i18n/en/docusaurus-plugin-content-blog/2025-08-19.mdx

@@ -0,0 +1,36 @@
+---
+title: Components Package, Themes and Peer Dependencies
+authors: deleonio
+---
+
+# Components Package, Themes and Peer Dependencies
+
+Our project uses several NPM packages that work together to build reusable interfaces. The core is the components package. It delivers the Web Components with their functionality but without fixed styling. This keeps each component lean and allows it to fit into different design concepts.
+
+## Headless components
+
+The components are intentionally built in a headless way. They contain no defaults for colors, spacing or fonts. This freedom allows every organization to define the look completely on its own and seamlessly embed the components into existing design systems.
+
+## Themes provide the styling
+
+The visual appearance is added via separate theme packages. A theme describes the design of buttons, form fields or tables—it delivers the visual look. Users of the components can write their own theme and combine the same functionality with an individual interface.
+
+## Peer dependencies ensure version compatibility
+
+To make clear which theme version matches which components version, we rely on peer dependencies. In a theme package the peer dependency specifies the version range of the components package for which the theme is intended. We follow a simple rule: one theme version belongs exactly to one components version.
+
+## Installation and checks
+
+During `npm install`, NPM automatically verifies whether the peer dependencies are satisfied. If the versions do not match, an error message appears. This hint is intentional, because it prevents installing a combination that could cause problems later.
+
+## No legacy mode
+
+NPM offers the `legacy peer deps` option to skip this verification. In our setup this mode must not be used. Without the error messages it is easy to end up with wrong or broken installations.
+
+## Summary
+
+- Components package: provides the functional building blocks without styling.
+- Theme package: provides the appearance.
+- Peer dependencies: ensure both fit together exactly.
+- NPM error messages: desired and important.
+