docs(blog): safe CSS properties in themes (#377)

deleonio · web-flow · commit f9220c1d4f43 · 2025-09-07T09:53:24.000+02:00
diff --git a/blog/2023-06-21.mdx b/blog/2023-06-21.mdx
@@ -8,7 +8,6 @@ title: SPA, PWA und Hyprid-Apps
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Motivation
 
@@ -70,4 +69,3 @@ Einige beliebte Hybrid-Frameworks und Plattformen sind Cordova/PhoneGap, Ionic u
 
 Es ist wichtig anzumerken, dass Hybrid-Apps im Vergleich zu nativen Apps möglicherweise nicht die gleiche Leistung oder nahtlose Integration in die Plattform bieten können. Die Wahl zwischen einer Hybrid-App und einer nativen App hängt von den spezifischen Anforderungen des Projekts, dem erforderlichen Grad an Plattformintegration und der Benutzererfahrung ab, die Sie erreichen möchten.
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/blog/2023-06-28.mdx b/blog/2023-06-28.mdx
@@ -8,7 +8,6 @@ title: Komponentenbibliothek vs. Designsystem
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Was ist eine Komponentenbibliothek?
 
@@ -139,4 +138,3 @@ Für die Betrachtung des Themas Komponentenbibliothek vs. Designsysteme aus ande
 - https://www.ramotion.com/blog/design-system-vs-component-library/#section-component-library-definition (EN)
 - https://www.uxpin.com/studio/blog/design-systems-vs-pattern-libraries-vs-style-guides-whats-difference/ (EN)
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/blog/2023-06-30.mdx b/blog/2023-06-30.mdx
@@ -8,7 +8,6 @@ title: Web- und Native-Apps
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Motivation
 
@@ -86,4 +85,3 @@ Für die Betrachtung des Themas Web- und Native-Apps aus anderen Perspektiven is
 
 - https://app-entwickler-verzeichnis.de/faq-app-entwicklung/11-definitionen/586-unterschiede-und-vergleich-native-apps-vs-web-apps-2
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/blog/2023-07-01.mdx b/blog/2023-07-01.mdx
@@ -8,7 +8,6 @@ title: React Native vs. Flutter
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Was ist React Native?
 
@@ -55,4 +54,3 @@ Für die Betrachtung des Themas React Native vs. Flutter aus anderen Perspektive
 - https://hackr.io/blog/react-native-vs-flutter (EN)
 - https://www.it-intouch.de/news/details/react-native-vs-flutter-unterschiede-gemeinsamkeiten-im-vergleich/
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/blog/2023-07-11.mdx b/blog/2023-07-11.mdx
@@ -8,7 +8,6 @@ title: KoliBri - intuitiv erlernen
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 Im Laufe der Jahre weisen die Benennung und Semantik in HTML teilweise große Unterschieden auf. Aufgrund der Abwärtskompatibilität von HTML sind Korrekturen und Änderungen nur äußerst schwierig umzusetzen. Diese Situation hat zu unzähligen Best Practices und How-to's geführt, die versuchen, auf unterschiedliche Weise ähnliche Anforderungen umzusetzen. Angesichts des wachsenden Bewusstseins für Barrierefreiheit und den damit verbundenen gesetzlichen Anforderungen gewinnt die Semantik jedoch eine immense Bedeutung. Hier kommt KoliBri ins Spiel, indem es einen barrierefreien Webcomponent-Standard auf HTML schafft und gleichzeitig für eine einheitlichere und somit leicht erlernbare Verwendung sorgt.
 
@@ -36,4 +35,3 @@ Die Verwendung von einheitlichen Eigenschaften in der Entwicklung von Komponente
 
 Und das Beste ist, alle Verbesserungen fließen soweit möglich schon in Version 1 ein und bereiten damit eine möglichst harmonische Migration auf Version 2 vor.
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/blog/2025-08-28-css-properties-in-themes.mdx b/blog/2025-08-28-css-properties-in-themes.mdx
@@ -0,0 +1,33 @@
+---
+authors:
+- deleonio
+- chatgpt
+date: '2025-08-28'
+title: CSS-Properties in Themes sicher nutzen
+---
+
+
+# CSS-Properties in Themes sicher nutzen
+
+KoliBri, auch bekannt als Public UI Components, ermöglicht durch adaptive Styles ein flexibles Theming. Über CSS-Properties lassen sich Farben, Abstände und weitere Designwerte zentral steuern. Allerdings greift der Schutz des Shadow DOMs hier nicht: CSS-Properties wirken global und können ungewollt mit Variablen der hostenden Seite kollidieren.
+
+## Problemstellung
+
+Wer in seinen Themes viele Custom Properties verwendet, riskiert Konflikte mit gleichnamigen Variablen auf der Root-Seite. Diese Überschneidungen können das Erscheinungsbild einer Anwendung unerwartet verändern und damit sowohl Nutzende als auch Entwickler:innen irritieren.
+
+## Strategien zur Konfliktvermeidung
+
+- **Namensräume nutzen:** Präfixe wie `--kolibri-` reduzieren die Wahrscheinlichkeit, dass sich Variablen überschneiden. Vollständige Sicherheit bietet dieser Ansatz jedoch nicht.
+- **Interne Werte in SCSS abbilden:** Für Berechnungen und Zwischenschritte sollten SASS-Variablen (`$variable`) verwendet werden. Sie werden zur Build-Zeit aufgelöst und tauchen nicht mehr als globale CSS-Properties auf.
+- **Nur notwendige Properties exponieren:** Externe Custom Properties sollten auf ein Minimum reduziert werden. Je weniger globale Variablen, desto geringer die Kollisionsgefahr.
+
+## Handreichung
+
+1. **Design Tokens als Basis:** Übernehmt die in Figma definierten, bereits präfixierten Tokens als Ausgangspunkt.
+2. **SCSS-Variablen einsetzen:** Wandelt interne Custom Properties in SASS-Variablen um, um Berechnungen kapselnd zu halten.
+3. **Dokumentation erweitern:** Beschreibt klar, welche Properties extern verfügbar sind und welche ausschließlich intern genutzt werden.
+
+## Fazit
+
+Durch den bewussten Einsatz von SCSS und einem schlanken Satz an Custom Properties bleiben Themes wartbar und kollisionsfrei. Wer diese einfachen Regeln beachtet, schafft robuste und leicht integrierbare Designs.
+
diff --git a/docs/20-concepts/05-styling/40-scss.md b/docs/20-concepts/05-styling/40-scss.md
@@ -13,6 +13,10 @@ Dieser Artikel beschreibt, wie Scss zur Erstellung von KoliBri-Themes genutzt we
   KoliBri bietet zum Erstellen von Themes auch einen <KolLink _label="Designer" _href="/docs/concepts/styling/designer" /> an. Je nach persönlichen Präferenzen kann Scss oder der Designer verwendet werden.
 </KolAlert><br/>
 
+<KolAlert _label="CSS-Properties" _type="warning" _variant="card">
+  CSS-Custom-Properties wirken global und sind nicht durch den Shadow DOM geschützt. Verwende präfixierte Namen und bilde interne Werte über SASS-Variablen ab, damit es zu keinen Kollisionen mit Variablen der hostenden Seite kommt.
+</KolAlert><br/>
+
 Scss ist eine Erweiterung von CSS, die es ermöglicht, Variablen, Funktionen, Mixins und vieles mehr zu verwenden. Scss kann für die Erstellung von KoliBri-Themes genutzt. Hierfür hat das Entwicklungsteam vom Projekt <KolLink _label="KERN" _href="https://gitlab.opencode.de/kern-designsystem/pattern-library" _target="_blank" /> ein Build-Script geschrieben, um aus Scss-Dateien die entsprechenden KoliBri-Themes zu generieren.
 
 ## Hintergrund
diff --git a/i18n/en/docusaurus-plugin-content-blog/2023-06-21.mdx b/i18n/en/docusaurus-plugin-content-blog/2023-06-21.mdx
@@ -10,7 +10,6 @@ title: SPA, PWA und Hyprid-Apps
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Motivation
 
@@ -72,4 +71,3 @@ Einige beliebte Hybrid-Frameworks und Plattformen sind Cordova/PhoneGap, Ionic u
 
 Es ist wichtig anzumerken, dass Hybrid-Apps im Vergleich zu nativen Apps möglicherweise nicht die gleiche Leistung oder nahtlose Integration in die Plattform bieten können. Die Wahl zwischen einer Hybrid-App und einer nativen App hängt von den spezifischen Anforderungen des Projekts, dem erforderlichen Grad an Plattformintegration und der Benutzererfahrung ab, die Sie erreichen möchten.
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/i18n/en/docusaurus-plugin-content-blog/2023-06-28.mdx b/i18n/en/docusaurus-plugin-content-blog/2023-06-28.mdx
@@ -8,7 +8,6 @@ title: Component Library vs. Design System
 
 import { KolLink } from '@public-ui/react';
 
-> Note: This article was generated in part by [ChatGPT]. The content was checked by a human and adjusted if necessary.
 
 # Component library vs. design system
 
@@ -141,4 +140,3 @@ The following articles are also worth reading for a different perspective on the
 - https://www.ramotion.com/blog/design-system-vs-component-library/#section-component-library-definition (EN)
 - https://www.uxpin.com/studio/blog/design-systems-vs-pattern-libraries-vs-style-guides-whats-difference/ (EN)
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/i18n/en/docusaurus-plugin-content-blog/2023-06-30.mdx b/i18n/en/docusaurus-plugin-content-blog/2023-06-30.mdx
@@ -10,7 +10,6 @@ title: Web- und Native-Apps
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Motivation
 
@@ -88,4 +87,3 @@ Für die Betrachtung des Themas Web- und Native-Apps aus anderen Perspektiven is
 
 - https://app-entwickler-verzeichnis.de/faq-app-entwicklung/11-definitionen/586-unterschiede-und-vergleich-native-apps-vs-web-apps-2
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/i18n/en/docusaurus-plugin-content-blog/2023-07-01.mdx b/i18n/en/docusaurus-plugin-content-blog/2023-07-01.mdx
@@ -10,7 +10,6 @@ title: React Native vs. Flutter
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 ## Was ist React Native?
 
@@ -57,4 +56,3 @@ Für die Betrachtung des Themas React Native vs. Flutter aus anderen Perspektive
 - https://hackr.io/blog/react-native-vs-flutter (EN)
 - https://www.it-intouch.de/news/details/react-native-vs-flutter-unterschiede-gemeinsamkeiten-im-vergleich/
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/i18n/en/docusaurus-plugin-content-blog/2023-07-11.mdx b/i18n/en/docusaurus-plugin-content-blog/2023-07-11.mdx
@@ -10,7 +10,6 @@ title: KoliBri - intuitiv erlernen
 
 import { KolLink } from '@public-ui/react';
 
-> Hinweis: Dieser Artikel wurde zu Teilen durch [ChatGPT] generiert. Die Inhalte wurden von einem Menschen überprüft und ggf. angepasst.
 
 Im Laufe der Jahre weisen die Benennung und Semantik in HTML teilweise große Unterschieden auf. Aufgrund der Abwärtskompatibilität von HTML sind Korrekturen und Änderungen nur äußerst schwierig umzusetzen. Diese Situation hat zu unzähligen Best Practices und How-to's geführt, die versuchen, auf unterschiedliche Weise ähnliche Anforderungen umzusetzen. Angesichts des wachsenden Bewusstseins für Barrierefreiheit und den damit verbundenen gesetzlichen Anforderungen gewinnt die Semantik jedoch eine immense Bedeutung. Hier kommt KoliBri ins Spiel, indem es einen barrierefreien Webcomponent-Standard auf HTML schafft und gleichzeitig für eine einheitlichere und somit leicht erlernbare Verwendung sorgt.
 
@@ -38,4 +37,3 @@ Die Verwendung von einheitlichen Eigenschaften in der Entwicklung von Komponente
 
 Und das Beste ist, alle Verbesserungen fließen soweit möglich schon in Version 1 ein und bereiten damit eine möglichst harmonische Migration auf Version 2 vor.
 
-[ChatGPT]: https://chat.openai.com/
diff --git a/i18n/en/docusaurus-plugin-content-blog/2025-08-28-css-properties-in-themes.mdx b/i18n/en/docusaurus-plugin-content-blog/2025-08-28-css-properties-in-themes.mdx
@@ -0,0 +1,33 @@
+---
+authors:
+- deleonio
+- chatgpt
+date: '2025-08-28'
+title: Using CSS Custom Properties Safely in Themes
+---
+
+
+# Using CSS Custom Properties Safely in Themes
+
+KoliBri, also known as Public UI Components, relies on adaptive styles to enable flexible theming. CSS custom properties provide a convenient way to control colors, spacing and other design values. However, the Shadow DOM does not shield them: custom properties cascade globally and may collide with variables on the host page.
+
+## Problem
+
+Extensive use of custom properties in a theme increases the risk of name clashes with root-level variables. Such conflicts can unexpectedly change the appearance of an application and confuse both users and developers.
+
+## Strategies to Avoid Collisions
+
+- **Use namespaces:** Prefixes like `--kolibri-` lower the chance of overlapping variable names, yet they are no absolute guarantee.
+- **Map internal values to SCSS:** Calculations and intermediate values should rely on SASS variables (`$variable`). They are resolved at build time and do not appear as global custom properties.
+- **Expose only what is necessary:** Keep the set of external custom properties as small as possible to minimize collision risks.
+
+## Checklist
+
+1. **Start from design tokens:** Use the prefixed tokens defined in Figma as your foundation.
+2. **Switch to SCSS variables:** Replace internal custom properties with SASS variables to keep computations encapsulated.
+3. **Update documentation:** Clearly state which properties are public and which remain internal.
+
+## Conclusion
+
+By combining SCSS with a minimal set of custom properties, themes stay maintainable and collision-free. Following these guidelines results in robust designs that integrate smoothly into any host environment.
+
