Ein großer Vorteil von KoliBri liegt in seiner besonders guten Wiederverwendbarkeit und hohen Flexiblität. Denn auf Basis der semantisch barrierefreien Komponenten, in denen alle technische und gesetzliche Anforderungen umgesetzt sind, können eigene Themes unabhängig erstellt werden.

Rückblick​

KoliBri wurde als internes Projekt des ITZBund realisiert und hat sich natürlich dabei anfangs vor allem auf die Bedürfnisse interner Projekte fokussiert. Hierbei sind in erster Linie zahlreiche Themes umgesetzt worden, die nur intern Anwendung finden.

Darüber hinaus wurden auch einige Themes zum Zwecke der Verbesserung umgesetzt, die als Proof-of-Concepts (PoC) dienten.

Migration​

Wir beschreiben jetzt hier in der Migration einfach mal, wie wir das im ITZBund exemplarisch umgesetzt haben, weil dass sicher ein interessanter Aspekt für andere Behörden, Organisationen und Unternehmen ist, wie sie eigene Themes intern bereitstellen können.

Im Grunde haben wir ein neues Repository angelegt und ein Theme-Projekt erstellt (siehe nächsten Abschnitt), in dem wir alle internen Themes pflegen. Wir haben erstmal alle Themes in einem Repository, weil wir das für die Entwicklung aktuell einfacher finden. Es ist aber auch möglich, die Themes in unterschiedlichen Repositories jeweils einzeln zu pflegen.

Mittels des TypeScript-Compilers wird das Theme-Projekt in ein JavaScript-Projekt kompiliert und als NPM-Paket @itzbund/interne-kolibri-themes in unsere interne NPM-Registry versioniert gepublished.

Damit die entwickelnden Projekte jetzt das neue Theme-Paket installieren und verwenden können, muss zunächst die NPM-Konfiguration .npmrc im Projekt-Verzeichnis erweitert und die neue Abhängigkeit in die package.json hinzugefügt werden.

.npmrc (kann mit im Projekt-Verzeichnis liegen oder im Home-Verzeichnis des Benutzers)

@itzbund:registry=https://<URL-zur-internen-registry>

package.json (im Projekt-Verzeichnis)

{
 "dependencies": {
  "@itzbund/interne-kolibri-themes": "1.0.0"
 }
}

Eigenes Theme erstellen​

In diesem Abschnitt wollen wir einen kurzen Einblick geben, wie einfach es ist, ein eigenes Theme zu erstellen.

Rationale​

Einer der wichtigsten Punkte, die man verstehen muss, liegt darin, dass KoliBri sich auf kleinteilige häufig wiederverwendete Komponenten konzentriert (mehr hierzu im ). Das führt dazu, dass wir uns vorallem auf standardisierbare Komponenten fokussieren. Deutlicher wird dies, wenn wir uns vorstellen, eine redundante Umsetzung einer Basis-Komponente unter Beachtung der technischen und gesetzlichen Anforderungen zu entwickeln und am Ende feststellen - die verhält sich ja genauso, wie eine KoliBri- Komponente und ist nahezu gleich semantisch aufgebaut. Insbesondere die technisch semantischen Vorgaben des W3C für die assistive Unterstützung (Barrierefreiheit) fördern das Standardisierungspotenzial.

Wir können somit von einer hohen Überdeckung von Komponenten ausgehen, die allgemein jedes Design System oder Komponenten-Bibliothek beinhalten und sich in der KoliBri-Sammlung verwendbar wiederfinden. Durch das Kompositionsprinzip kann einfach die passende Teilmenge aus KoliBri ausgewählt und wiederverwendet werden. Alle nicht vereinbarten Komponenten können unabhängig von KoliBri und unternehmensspezifisch umgesetzt werden.

Hinweis: Es ist immer möglich eine Konstellation gegen die Wiederverwendung einer KoliBri-Komponenten aufzustellen, die auf die Abweichung von der Referenzimplementierung abzielt. Es ist nicht unsere Entscheidung ob die aufgezeigte Abweichung eine vollständige Eigenentwicklung wirtschaftlich und ökonomisch rechtfertigt. Wir bieten eine Lösung an, die von alle frei und geprüft genutzt werden kann.

Umsetzung​

Mit Hilfe der KoliBri-CLI (npm init kolibri my-theme) kann ein neues Theme-Projekt generiert werden. Das Theme-Projekt ist ein TypeScript-Projekt und beinhalten schon ein Dummy-Theme. Mit Hilfe des KoliBri-Designers kann dann ein Theme interaktiv auf den Basis-Komponenten erstellt, gespeichert, geladen und weiter gepflegt werden. Der vom Designer generierte Code wird einfach in das Theme-Projekt kopiert und kann dann mit dem TypeScript-Compiler kompiliert werden. Anschließend kann es mittels NPM eine interne oder in die öffentliche NPM-Registry gepublished werden.

Wir bieten heute die Varianten von Button, ButtonLink, Link und LinkButton an. Zukünftig werden wir zusätzlich den ButtonToggle (Toogle-Button) anbieten. Optisch gibt es Buttons die genau wie Links aussehen und Links die genauso wie Buttons aussehen.

In der folgenden Tabelle wir eine Übersicht über die Unterschiede dargestellt:

Motivation​

KoliBri strebt neben einer hohe Standardkonformität auch eine sehr gute Wiederverwendbarkeit (Developer Experience DX) an. Diese wird durch die Einheitlichkeit zu den HTML-Attributen und dem sparsamen Umgang mit zusätzlichen Properties adressiert.

Rationale: Wenn wir bei einer Link-Komponente, die zum Navigieren gedacht ist, die beiden Verhalten Navigieren und Klick ohne Navigieren anbieten würden, dann hätten wir einen Widerspruch im Verhalten. Auch bei der Verwendung in der Entwicklung müssten wir die Properties _href und _on optional machen und wir könnten nicht mehr vor der Falschverwendung warnen (Statische Codeprüfung).

Herausforderungen​

Diese strenge Auslegung kann dazu führen, dass es bei der Entwicklung mit anderen Bibliotheken und Frameworks zu Problemen kommt. Vor allem dann, wenn diese bei einem Link einen Klick erwarten.

React-Router​

Der React-Router bildet das Navigieren über Klicks ab. Bei der Verwendung mit der Link-Komponente gibt es unterschiedliche Möglichkeiten der Implementierung.

Wrapping:

<Link to="/">
 <KolLink _href="" _label={`Home`}/>
</Link>
<Link to="/test">
 <KolLink _href="" _label={`Test`}/>
</Link>

Per Klick:

<KolButtonLink
 _label="Home"
 _on={{
  onClick: () => navigate("/")
 }}
>
 Home
</KolButtonLink>
<KolButtonLink
 _label="Test"
 _on={{
  onClick: () => navigate("/test")
 }}
>
 Test
</KolButtonLink>

React-Link:

<KolLink
 _href=""
 _label="Home"
 onClick={() => navigate("/")}
>
 Home
</KolLink>
<KolLink
 _href=""
 _label="Test"
 onClick={() => navigate("/test")}
>
 Test
</KolLink>

Hinweis: _href="" ist eigentlich nicht erlaubt.

Hier gibt es auch ein kleines Code-Beispiel zum .

Die angegebenen Beispiele zeigen, dass die Link- und ButtonLink-Komponente für die direkte Nutzung mit React-Router geeignet sind. Allerdings wird die Link-Komponente auch innerhalb anderer KoliBri-Komponenten verwendet. Wo das so nicht funktionieren würde!

Server-Side-Rendering​

Das Server-Side-Rendering ist sehr ähnlich zum React-Router, weil dieser technisch sehr stark durch das Framework Remix getrieben ist. Remix ist ein Framework zum Erstellen von hybriden Client- und Server-Side-Webapplications. Das heißt die Implementierung unterscheiden sich nicht, ob ich die Anwendung später als Client- oder Server-seitige Anwendung bauen möchte. Für Server-Side-Anwendungen müssen die navigierenden Links mit einem Klick funktionieren, weil diese Anwendungen auf dem Server und nicht im Browser ausgeführt werden.

Um die Wiederverwendbarkeit von KoliBri auch für Server-Side-Webapplications zu gewährleisten, muss der Seitenwechsel auch durch Klick ohne Navigieren möglich sein.

Lösung​

Um die Herausforderungen zu lösen, werden alle Komponenten, denen Link-Definitionen übergeben werden, erweitert. Wenn diesen Komponenten wahlweise auch ButtonLink-Definitionen übergeben werden können, dann können diese auch Klicks abbilden ohne zu Navigieren, sehen aber optisch weiterhin wie Links aus.

Folgende Komponenten müssen dazu noch erweitert werden:

• Breadcrumb
• LinkGroup
• Nav
• SkipNav

Als Open Source-Projekt ist es für KoliBri wichtig eine Community rund um das Thema barrierefreie Basis-Komponenten aufzubauen. Damit auch hierfür eine optimiale Zugänglichkeit gegeben ist, sollten alle technischen Spezifikationen mindestens in English verfügbar sein. Wie auch in der Wissenschaft ermöglicht das Feedback und Mitwirkung aus allen potenziellen Bereichen.

Maßnahmen​

Englische Spezifikation​

Die technische Spezifikation wird automatisiert aus dem Quellcode generiert und synchronisiert. Alle Informationen die wir aus dem Quellcode in die Spezifikation überführen, wird in Zukunft ausschließlich in English bereitgestellt.

Das betrifft beispielsweise:

• API-Spezifikation auf der Website
• Details in der IDE-Autovervollständigung
• Darstellungen die aus den Meta-Daten des Quellcodes generiert werden

Multilinguale Dokumentation​

Die Dokumentation wird in Zukunft (mittelfristig) alle Inhalte jeweils primär in Deutsch und sekundär in English bereitgestellt.

Das betrifft beispielsweise:

• Anleitungen, Konzepte, Beispiele uvm.
• Blog-Beiträge