Zum Hauptinhalt springen

Ihre Meinung ist uns wichtig! Gemeinsam mit Ihnen möchten wir KoliBri stetig verbessern. Teilen Sie uns Ihre Ideen, Wünsche oder Anregungen mit – schnell und unkompliziert.

Erste Schritte

Für Projekte im ITZBund gibt es ein vorgegebenes Starter-Repository, welches über die internen Kommunikationswege angefragt werden kann.

KoliBri ist eine Open-Source-Bibliothek für barrierefreie Web Components, entwickelt von der Bundesregierung. Die Komponenten sind framework-unabhängig, nach BITV 2.0 und WCAG 2.2 konform und können in nahezu jedem webbasierten Projekt verwendet werden. Diese Seite gibt einen kompakten Überblick, wie Sie starten.

⚠️ Voraussetzungen

  • Ein moderner Browser (Chrome, Firefox, Edge, Safari ≥ 16.4).
  • Für lokale Entwicklung: Node.js (für npx -y serve).

Statisches Beispiel (2 Schritte)​

Der schnellste Weg, KoliBri auszuprobieren, ist ein statisches HTML-File:

Schritt 1: Erstellen Sie eine index.html-Datei:

<!DOCTYPE html>
<html>
 <head>
 <title>Hello KoliBri!</title>
 </head>
 <body>
 <h1>Hello KoliBri!</h1>
 <kol-button _label="Klick mich" onclick="handleClick()"></kol-button>
 <script type="module">
 import { register } from 'https://unpkg.com/@public-ui/components/dist/index.js';
 import { defineCustomElements } from 'https://unpkg.com/@public-ui/components/loader/index.mjs';
 import { DEFAULT } from 'https://unpkg.com/@public-ui/theme-default/dist/index.mjs';

 await register(DEFAULT, defineCustomElements);

 function handleClick() {
 alert("Button clicked!");
 }
 window.handleClick = handleClick;
 </script>
 </body>
</html>

Schritt 2: Starten Sie einen lokalen Server:

npx -y serve

Dann öffnen Sie http://localhost:3000 in Ihrem Browser.

💡 Hinweis: KoliBri verwendet _-präfixierte Attribute (z. B. _label) für Komponenten-Properties, um Konflikte mit Standard-HTML-Attributen zu vermeiden.

Projekt aus Templates erstellen​

Für Framework-Projekte können Sie vorgefertigte Templates verwenden:

npx degit public-ui/templates/csr/react-vite my-kolibri-app
cd my-kolibri-app
npm i
npm start

Verfügbare Templates finden Sie im .

Theme registrieren​

KoliBri liefert die Komponenten ohne festes Styling aus. Das visuelle Erscheinungsbild wird über ein Theme bestimmt, das bei der Registrierung übergeben wird. Das Paket @public-ui/themes enthält mehrere vorgefertigte Themes:

ThemeExportBeschreibung
DefaultDEFAULTDas Standard-Theme von KoliBri
BWStBWStWasserstraßen- und Schifffahrtsverwaltung des Bundes;
DesyDesyV11Zoll Design-System (Generalzolldirektion);
ECL (EC)ECL_ECEuropean Commission Design-System;
ECL (EU)ECL_EUEuropean Union Design-System;
KERNKERN_V2KERN-UX Standard Design-System;

Theme registrieren​

Das Theme wird beim Aufruf von register() als erster Parameter übergeben.

import { register } from '@public-ui/components@4.2.1';
import { defineCustomElements } from '@public-ui/components@4.2.1/loader';
import { DEFAULT } from '@public-ui/theme-default';

// Theme registrieren
await register(DEFAULT, defineCustomElements);

💡 Tipp: Sie können das Theme einfach ändern, indem Sie das entsprechende Theme-Paket importieren, z. B.:

import { BWSt } from '@public-ui/theme-bwst';
register(BWSt, defineCustomElements).catch(console.warn);

Verfügbare Themes: @public-ui/theme-default, @public-ui/theme-bwst, @public-ui/theme-desy, @public-ui/theme-ecl-ec, @public-ui/theme-ecl-eu, @public-ui/theme-kern

Eigenes Theme erstellen​

Wenn keines der mitgelieferten Themes zu Ihrem Corporate Design passt, können Sie ein eigenes Theme erstellen. Das Vorgehen orientiert sich am bestehenden Theme-Aufbau und wird vollständig im Code gepflegt.

KoliBri mit KI-Assistenten nutzen (MCP)​

KoliBri bietet einen Model Context Protocol (MCP) Server, mit dem Sie die Dokumentation und Komponenten direkt in Ihrer KI-Umgebung (z. B. Cursor, Claude Code, oder VS Code mit MCP-Erweiterungen) nutzen können.

🔗 MCP-Server ausprobieren

Vorteile:

  • Direkter Zugriff auf die KoliBri-Dokumentation und API.
  • Kontextbewusste Hilfe für Komponenten, Properties und Beispiele.
  • Integriert in Ihre Entwicklungsumgebung (z. B. Autocompletion, Tool-Tips).

Beispiel: Fragen Sie Ihre KI:

"Wie verwende ich den kol-button mit einem Custom-Theme?" → Die KI nutzt den MCP-Server, um aktuelle und genaue Antworten aus der KoliBri-Dokumentation zu liefern.

Häufige Fragen​

Komponenten werden nicht angezeigt?

Stellen Sie sicher, dass register() vor dem Rendern aufgerufen wurde und das Promise aufgelöst ist.

// ✅ Richtig
await register(DEFAULT, defineCustomElements);
// Jetzt Komponenten rendern

// ❌ Falsch
register(DEFAULT, defineCustomElements); // Promise nicht abgewartet
// App wird sofort gerendert - Komponenten fehlen
Welches Theme soll ich verwenden?
  • DEFAULT – Neutrales Standard-Theme (empfohlen für den Start)
  • ECL_EC / ECL_EU – European Commission / European Union Design-System
  • KERN_V2 – KERN-UX Standard Design-System
  • Eine Übersicht aller Themes finden Sie oben im Abschnitt Themes.
  • Eigenes Theme erstellen
TypeScript-Fehler bei Properties?

Prüfen Sie:

  1. "moduleResolution": "Node" in tsconfig.json
  2. Framework-Adapter installiert (z.B. @public-ui/react-v19)
  3. Komponenten aus dem Adapter importieren (nicht aus @public-ui/components)

Nächste Schritte: Komponenten​

Sobald Ihr Projekt eingerichtet und ein Theme registriert ist, können Sie die KoliBri-Komponenten verwenden. Eine vollständige Übersicht aller verfügbaren Komponenten — mit Beispielen, Eigenschaften und Events — finden Sie in der .