docs: add a concept for device and browser specific issues (#214)

Author: deleonio

dev/docs/01-manifest.mdx

@@ -43,7 +43,15 @@ tags:
 		mit dem strengen Blick auf die W3C Webstandards vereinbar ist. Funktionalitäten können somit entweder in die
 		Komponenten von KoliBri selbst einfließen oder mittels des Swizzling-Konzepts hinzugefügt werden.
 	</p>
-	<h2>§ 6 Sicherheit</h2>
+	<h2>§ 6 Verantwortung</h2>
+	<p>
+		KoliBri setzt auf moderne Webstandards, um barrierefreie Weblösungen geräte- und browserübergreifend zu
+		implementieren. Geräte- und browserspezifische Probleme sollten jedoch idealerweise von den jeweiligen Herstellern
+		behoben werden. Eigene Lösungen könnten instabile und nicht nachhaltige Workarounds darstellen, die möglicherweise
+		neue Barrierefreiheitsprobleme verursachen. Daher ist es sinnvoll, diese Probleme direkt an der Quelle zu
+		adressieren und dort beheben zu lassen.
+	</p>
+	<h2>§ 7 Sicherheit</h2>
 	<p>
 		Alle Komponenten dienen ausschließlich der im Sinne eines Corporate Designs oder Design Systems angestrebten
 		konsistenten und barrierefreien Darstellung von webbasierten Benutzeroberflächen. Wir stellen eine allgemeingültige

dev/docs/20-concepts/05-known-issues.md

@@ -0,0 +1,46 @@
+---
+title: Geräte- und Browser-spezifische Probleme
+description: Warum geräte- oder browserspezifische Barrierefreiheitsprobleme mit HTML zu lösen ineffizient und nicht nachhaltig ist.
+tags:
+  - Architektur
+  - arc42
+  - Konzept
+---
+
+# Konzept: Warum es sich nicht lohnt, geräte- oder browser-spezifische Barrierefreiheitsprobleme mit HTML zu lösen
+
+## Einführung
+
+Die Gewährleistung der Barrierefreiheit im Webdesign ist von zentraler Bedeutung, um allen Nutzern, unabhängig von ihren physischen oder technischen Einschränkungen, den Zugang zu Informationen und Diensten zu ermöglichen. Dabei stellt sich die Frage, ob es sinnvoll ist, geräte- oder browser-spezifische Probleme mit HTML zu lösen. Dieses Konzept beleuchtet, warum es ineffizient ist, sich auf solche spezifischen Lösungen zu konzentrieren, und warum eine standardisierte, umfassende Herangehensweise vorzuziehen ist.
+
+## Vielfalt der Geräte und Browser
+
+Die enorme Vielfalt an verfügbaren Geräten und Browsern auf dem Markt stellt eine Herausforderung dar. Ständige Updates und neue Versionen bedeuten, dass geräte- oder browser-spezifische HTML-Lösungen schnell veraltet sein können. Lösungen, die für ein bestimmtes Gerät oder einen bestimmten Browser entwickelt wurden, funktionieren möglicherweise nicht auf anderen Geräten oder in anderen Browsern.
+
+## Pflege und Wartung
+
+Die Pflege und Wartung solcher spezifischen Lösungen sind zeitaufwendig und kostspielig. Entwickler müssen kontinuierlich testen und Anpassungen vornehmen, um sicherzustellen, dass die Lösungen mit den neuesten Versionen kompatibel bleiben. Dieser fortlaufende Aufwand kann Ressourcen von anderen wichtigen Aspekten der Webentwicklung abziehen.
+
+## Benutzererfahrung
+
+Geräte- oder browser-spezifische Lösungen können die Benutzererfahrung negativ beeinflussen, insbesondere für Nutzer, die andere Geräte oder Browser verwenden. Das Ziel der Barrierefreiheit ist es, eine konsistente und zugängliche Erfahrung für alle Nutzer zu bieten. Spezifische Lösungen können dieses Ziel untergraben und einige Nutzer ausschließen.
+
+## Standardisierte Lösungen
+
+HTML5 und andere moderne Webstandards bieten robuste, zukunftssichere Lösungen zur Verbesserung der Barrierefreiheit. Diese Standards werden von einer breiten Palette an Geräten und Browsern unterstützt und regelmäßig aktualisiert, um mit den neuesten Technologien Schritt zu halten. Durch die Einhaltung dieser Standards können Entwickler sicherstellen, dass ihre Websites und Anwendungen zugänglich sind, ohne sich auf spezifische Lösungen konzentrieren zu müssen.
+
+## Best Practices und Frameworks
+
+Es gibt etablierte Best Practices und Frameworks, die barrierefreie Webentwicklung unterstützen, wie beispielsweise die Web Content Accessibility Guidelines (WCAG). Diese bieten umfassende Richtlinien, die auf allen Geräten und Browsern angewendet werden können. Durch die Einhaltung dieser Best Practices können Entwickler sicherstellen, dass ihre Websites und Anwendungen für ein breites Publikum zugänglich sind.
+
+## Dokumentation bekannter Probleme
+
+Um die bekannten, nicht durch HTML lösbaren Probleme zu dokumentieren, haben wir eine [`KNOWN_ISSUES.md`](https://github.com/public-ui/kolibri/blob/develop/KNOWN_ISSUES.md) erstellt. Diese Liste führt geräte- oder browser-spezifische Probleme auf, die derzeit nicht durch HTML-Lösungen behoben werden können. Durch diese Dokumentation behalten wir den Überblick über bestehende Probleme und können sie bei Bedarf gezielt adressieren.
+
+## Zusammenarbeit mit Herstellern
+
+Wir halten es für sinnvoller, die Fehler an die betreffenden Hersteller der Geräte oder Browser zu melden, anstatt individuelle Workarounds zu entwickeln. Durch die direkte Kommunikation mit den Herstellern können diese gezielt an der Behebung der Probleme arbeiten, was letztendlich zu einer verbesserten Barrierefreiheit für alle Nutzer führt. Diese Vorgehensweise unterstützt nicht nur eine nachhaltige Lösung der Probleme, sondern fördert auch die kontinuierliche Verbesserung der Technologie insgesamt.
+
+## Fazit
+
+Die Lösung geräte- oder browser-spezifischer Barrierefreiheitsprobleme mit HTML ist ineffizient und langfristig nicht nachhaltig. Eine standardisierte, zukunftssichere Herangehensweise unter Verwendung von Webstandards und Best Practices bietet eine bessere Grundlage für die Schaffung barrierefreier Websites und Anwendungen, die allen Nutzern unabhängig von ihrem Gerät oder Browser zugänglich sind. Entwickler sollten daher den Fokus auf allgemeine Barrierefreiheit und die Einhaltung etablierter Standards legen, um eine optimale Benutzererfahrung für alle zu gewährleisten. Die Dokumentation bekannter Probleme und die Zusammenarbeit mit den Herstellern tragen zusätzlich dazu bei, eine nachhaltige Lösung der Barrierefreiheitsprobleme zu erreichen.

dev/i18n/en/docusaurus-plugin-content-docs/current/01-manifest.mdx

@@ -11,36 +11,47 @@ tags:
 	<blockquote>We make the HTML accessible and themeable for reuse.</blockquote>
 	<h2>§ 1 Usability</h2>
 	<p>
-		The ultimate goal is to provide standardized, semantically accessible components for the web. We ensure this by means of clearly defined component APIs and
-		restrictive access to the interior of the components. The usability of the components is largely driven by the test steps of the WCAG and BITV, which
-		standardizes the behavior of the individual interactive elements. Building on this basis, the aesthetics of the components can be freely designed by means
-		of the decoupled KoliBri Designer.
+		The ultimate goal is to provide standardized, semantically accessible components for the web. We ensure this by
+		means of clearly defined component APIs and restrictive access to the interior of the components. The usability of
+		the components is largely driven by the test steps of the WCAG and BITV, which standardizes the behavior of the
+		individual interactive elements. Building on this basis, the aesthetics of the components can be freely designed by
+		means of the decoupled KoliBri Designer.
 	</p>
 	<h2>§ 2 Compatibility</h2>
 	<p>
-		All components are implemented framework-agnostic as Web Components and can thus be easily reused universally in all web-based projects. Additionally,
-		we offer numerous adapters for the most popular frameworks to provide an even better Developer Experience (DX).
+		All components are implemented framework-agnostic as Web Components and can thus be easily reused universally in all
+		web-based projects. Additionally, we offer numerous adapters for the most popular frameworks to provide an even
+		better Developer Experience (DX).
 	</p>
 	<h2>§ 3 Portability</h2>
 	<p>
-		The focus is on small components (e.g. buttons) that can be easily reused. The special thing about this is that an HTML button or input is not accessible
-		without further ado. However, a KoliBri button or input takes into account the numerous use cases and the semantic construction of the components that must
-		be considered.
+		The focus is on small components (e.g. buttons) that can be easily reused. The special thing about this is that an
+		HTML button or input is not accessible without further ado. However, a KoliBri button or input takes into account
+		the numerous use cases and the semantic construction of the components that must be considered.
 	</p>
 	<h2>§ 4 Maintainability</h2>
 	<p>
-		The most modern and popular tools from web development are used for the realization. In addition to the TypeScript programming language, aspects of
-		reusability for other design systems and component libraries have also been incorporated. The architecture is subject to a decoupled modularity and high
-		degree of automation (DevOps).
+		The most modern and popular tools from web development are used for the realization. In addition to the TypeScript
+		programming language, aspects of reusability for other design systems and component libraries have also been
+		incorporated. The architecture is subject to a decoupled modularity and high degree of automation (DevOps).
 	</p>
 	<h2>§ 5 Functional Suitability</h2>
 	<p>
-		There is no perfect solution. However, the claim is to functionally enable everything that is overarching and compatible with the strict view of the W3C web
-		standards. Functionalities can thus either flow into the components of KoliBri itself or be added by means of the swizzling concept.
+		There is no perfect solution. However, the claim is to functionally enable everything that is overarching and
+		compatible with the strict view of the W3C web standards. Functionalities can thus either flow into the components
+		of KoliBri itself or be added by means of the swizzling concept.
 	</p>
-	<h2>§ 6 Security</h2>
+	<h2>§ 6 Responsibility</h2>
 	<p>
-		All components serve solely to achieve a consistent and accessible representation of web-based user interfaces in the sense of a corporate design or design
-		system. We provide a universally applicable and subject-neutral library without any data transfer functionalities and storage.
+		KoliBri relies on modern web standards to implement accessible web solutions across devices and browsers. However,
+		device- and browser-specific issues should ideally be resolved by the respective manufacturers. Our own solutions
+		could result in unstable and unsustainable workarounds that might create new accessibility problems. Therefore, it
+		is advisable to address and resolve these issues directly at their source.
+	</p>
+	<h2>§ 7 Security</h2>
+	<p>
+		All components serve solely to achieve a consistent and accessible representation of web-based user interfaces in
+		the sense of a corporate design or design system. We provide a universally applicable and subject-neutral library
+		without any data transfer functionalities and storage.
 	</p>
 </div>

dev/i18n/en/docusaurus-plugin-content-docs/current/20-concepts/05-known-issues.md

@@ -0,0 +1,46 @@
+---
+title: Device and browser specific issues
+description: Why solving device-or browser-specific accessibility issues with HTML is inefficient and unsustainable.
+tags:
+  - architecture
+  - arc42
+  - concept
+---
+
+# Concept: Why Addressing Device- or Browser-Specific Accessibility Issues with HTML Is Not Worthwhile
+
+## Introduction
+
+Ensuring accessibility in web design is crucial to provide access to information and services for all users, regardless of their physical or technical limitations. This concept explains why it is inefficient to focus on device- or browser-specific solutions using HTML and why a standardized, comprehensive approach is preferable.
+
+## Diversity of Devices and Browsers
+
+The vast array of available devices and browsers presents a significant challenge. Constant updates and new versions mean that device- or browser-specific HTML solutions can quickly become outdated. Solutions developed for a specific device or browser may not work on others.
+
+## Maintenance and Upkeep
+
+Maintaining and updating such specific solutions is time-consuming and costly. Developers need to continuously test and make adjustments to ensure compatibility with the latest versions. This ongoing effort can divert resources from other important aspects of web development.
+
+## User Experience
+
+Device- or browser-specific solutions can negatively impact user experience, especially for those using different devices or browsers. The goal of accessibility is to provide a consistent and accessible experience for all users. Specific solutions can undermine this goal and exclude some users.
+
+## Standardized Solutions
+
+HTML5 and other modern web standards offer robust, future-proof solutions to improve accessibility. These standards are supported by a wide range of devices and browsers and are regularly updated to keep pace with the latest technologies. By adhering to these standards, developers can ensure their websites and applications are accessible without relying on specific solutions.
+
+## Best Practices and Frameworks
+
+There are established best practices and frameworks that support accessible web development, such as the Web Content Accessibility Guidelines (WCAG). These provide comprehensive guidelines that can be applied across all devices and browsers. By following these best practices, developers can ensure their websites and applications are accessible to a broad audience.
+
+## Documentation of Known Issues
+
+To document known issues that cannot be resolved with HTML, we have created a [`KNOWN_ISSUES.md`](https://github.com/public-ui/kolibri/blob/develop/KNOWN_ISSUES.md) file. This list outlines device- or browser-specific problems that currently cannot be addressed with HTML solutions. This documentation helps us keep track of existing problems and address them as needed.
+
+## Collaboration with Manufacturers
+
+We believe it is more effective to report issues to the respective manufacturers of the devices or browsers instead of developing individual workarounds. By directly communicating with manufacturers, they can work on fixing the problems, ultimately improving accessibility for all users. This approach not only supports sustainable problem-solving but also promotes continuous technological improvement.
+
+## Conclusion
+
+Addressing device- or browser-specific accessibility issues with HTML is inefficient and not sustainable in the long term. A standardized, future-proof approach using web standards and best practices provides a better foundation for creating accessible websites and applications that are available to all users, regardless of their device or browser. Developers should focus on general accessibility and compliance with established standards to ensure an optimal user experience for all. Documenting known issues and collaborating with manufacturers further contributes to achieving sustainable solutions to accessibility problems.

dev/i18n/en/docusaurus-plugin-content-docs/version-1.5/01-manifest.mdx

@@ -11,36 +11,47 @@ tags:
 	<blockquote>We make the HTML accessible and themeable for reuse.</blockquote>
 	<h2>§ 1 Usability</h2>
 	<p>
-		The ultimate goal is to provide standardized, semantically accessible components for the web. We ensure this by means of clearly defined component APIs and
-		restrictive access to the interior of the components. The usability of the components is largely driven by the test steps of the WCAG and BITV, which
-		standardizes the behavior of the individual interactive elements. Building on this basis, the aesthetics of the components can be freely designed by means
-		of the decoupled KoliBri Designer.
+		The ultimate goal is to provide standardized, semantically accessible components for the web. We ensure this by
+		means of clearly defined component APIs and restrictive access to the interior of the components. The usability of
+		the components is largely driven by the test steps of the WCAG and BITV, which standardizes the behavior of the
+		individual interactive elements. Building on this basis, the aesthetics of the components can be freely designed by
+		means of the decoupled KoliBri Designer.
 	</p>
 	<h2>§ 2 Compatibility</h2>
 	<p>
-		All components are implemented framework-agnostic as Web Components and can thus be easily reused universally in all web-based projects. Additionally,
-		we offer numerous adapters for the most popular frameworks to provide an even better Developer Experience (DX).
+		All components are implemented framework-agnostic as Web Components and can thus be easily reused universally in all
+		web-based projects. Additionally, we offer numerous adapters for the most popular frameworks to provide an even
+		better Developer Experience (DX).
 	</p>
 	<h2>§ 3 Portability</h2>
 	<p>
-		The focus is on small components (e.g. buttons) that can be easily reused. The special thing about this is that an HTML button or input is not accessible
-		without further ado. However, a KoliBri button or input takes into account the numerous use cases and the semantic construction of the components that must
-		be considered.
+		The focus is on small components (e.g. buttons) that can be easily reused. The special thing about this is that an
+		HTML button or input is not accessible without further ado. However, a KoliBri button or input takes into account
+		the numerous use cases and the semantic construction of the components that must be considered.
 	</p>
 	<h2>§ 4 Maintainability</h2>
 	<p>
-		The most modern and popular tools from web development are used for the realization. In addition to the TypeScript programming language, aspects of
-		reusability for other design systems and component libraries have also been incorporated. The architecture is subject to a decoupled modularity and high
-		degree of automation (DevOps).
+		The most modern and popular tools from web development are used for the realization. In addition to the TypeScript
+		programming language, aspects of reusability for other design systems and component libraries have also been
+		incorporated. The architecture is subject to a decoupled modularity and high degree of automation (DevOps).
 	</p>
 	<h2>§ 5 Functional Suitability</h2>
 	<p>
-		There is no perfect solution. However, the claim is to functionally enable everything that is overarching and compatible with the strict view of the W3C web
-		standards. Functionalities can thus either flow into the components of KoliBri itself or be added by means of the swizzling concept.
+		There is no perfect solution. However, the claim is to functionally enable everything that is overarching and
+		compatible with the strict view of the W3C web standards. Functionalities can thus either flow into the components
+		of KoliBri itself or be added by means of the swizzling concept.
 	</p>
-	<h2>§ 6 Security</h2>
+	<h2>§ 6 Responsibility</h2>
 	<p>
-		All components serve solely to achieve a consistent and accessible representation of web-based user interfaces in the sense of a corporate design or design
-		system. We provide a universally applicable and subject-neutral library without any data transfer functionalities and storage.
+		KoliBri relies on modern web standards to implement accessible web solutions across devices and browsers. However,
+		device- and browser-specific issues should ideally be resolved by the respective manufacturers. Our own solutions
+		could result in unstable and unsustainable workarounds that might create new accessibility problems. Therefore, it
+		is advisable to address and resolve these issues directly at their source.
+	</p>
+	<h2>§ 7 Security</h2>
+	<p>
+		All components serve solely to achieve a consistent and accessible representation of web-based user interfaces in
+		the sense of a corporate design or design system. We provide a universally applicable and subject-neutral library
+		without any data transfer functionalities and storage.
 	</p>
 </div>