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.

In der Entwicklung barrierefreier Komponenten stehen wir oft vor spannenden Detailfragen, die mehr Wirkung haben, als man auf den ersten Blick denkt. Ein aktuelles Beispiel aus dem KoliBri-Projekt: Wie sollen unsere Hybrid-Komponenten ButtonLink und LinkButton von Screenreadern vorgelesen werden?

---

Die Debatte​

Es gibt zwei mögliche Ansätze:

1. Nach Design – "So wie es aussieht, wird es vorgelesen."

• Ein ButtonLink, der wie ein Link aussieht, wird als Link vorgelesen.
• Ein LinkButton, der wie ein Button aussieht, wird als Button vorgelesen.

Vorteil: Homogenität – Links klingen gleich, Buttons klingen gleich. Nachteil: Verhalten und Erwartung können auseinanderfallen.

2. Nach Verhalten – "So wie es sich verhält, wird es vorgelesen."

• Ein ButtonLink, der eine Aktion im aktuellen Kontext ausführt, wird als Button vorgelesen.
• Ein LinkButton, der eine Navigation auslöst, wird als Link vorgelesen.

Vorteil: Erwartungskonformität – Nutzer wissen, ob sie klicken oder navigieren. Nachteil: Das visuelle Signal passt nicht immer zum auditiven Signal.

---

Die Entscheidung​

Nach Diskussion mit Design- und Accessibility-Perspektive war klar:

Die Erwartung ist wichtiger als die Optik.

Screenreader-Nutzer verlassen sich darauf, dass Links navigieren und Buttons Aktionen auslösen. Selbst wenn das visuelle Erscheinungsbild abweicht, ist es entscheidender, dass Verhalten und Ansage übereinstimmen.

---

Warum ist das wichtig?​

• Barrierefreiheit bedeutet Verlässlichkeit. Nutzer:innen sollen nicht raten müssen, ob ein "Link" eine Seite wechselt oder nur ein Formular absendet.
• Design kann täuschen, Verhalten nicht. Ein Button, der wie ein Link aussieht, bleibt eine Aktion. Ein Link, der wie ein Button aussieht, bleibt eine Navigation.
• Konsistenz schafft Vertrauen. Gerade beim Vorlesen durch Screenreader ist Klarheit das höchste Gut.

---

Fazit​

Die Entscheidung im KoliBri-Projekt lautet:

• ButtonLink wird als Button vorgelesen.
• LinkButton wird als Link vorgelesen.

Damit setzen wir auf Erwartungskonformität und stärken die Assistivität für alle Nutzer:innen.

---

Komponente	Sieht aus wie …	Verhält sich wie
ButtonLink	Link	Button
LinkButton	Button	Link

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.