KERN Web-Components-Kit

Mit KERN schaffen wir einen offenen UX-Standard für die deutsche Verwaltung, der Umsetzende befähigt, barrierefreie digitale Verwaltungslösungen effizient und nutzendenzentriert zu entwickeln.

Disclaimer

Das KERN Web-Components-Kit ist eine Implementation des KERN Design-Systems innerhalb eines Community-Projekts. Das KERN Projektteam ist nicht dafür verantwortlich und kann Dir bei der Nutzung nicht helfen. Kontaktiere den Maintainer direkt, wenn Du Hilfe benötigst, einen Bug melden möchtest oder eine Funktion anfragen willst. Dies funktioniert am besten durch die Erstellung eines Bugs oder eines Issues im Ticket-System dieses Repositorys.

Verantwortlich und Maintainer für dieses Repository ist: Axel Wolters, @OC000011858689

Neue Komponenten sollten über ein Ticket im Haupt-Repository angefragt werden, damit alle Umsetzungen davon profitieren können.

Weitere Information findest Du in den Dateien CODE_OF_CONDUCT, CONTRIBUTING, LICENSE, CHANGELOG und COMPONENTS.

🚀 Quick Start

1. Aktuelle Version: 3.1.2. Dieses Projekt befindet sich in aktiver Entwicklung. Es basiert auf dem KERN – Plain-CSS-HTML-Kit in der Version 2.7.2 und nutzt dessen CSS-Klassen und HTML-Code-Beispiele.

2. Installation:

   npm install @kern-ux-annex/webc

   import '@kern-ux-annex/webc';

3. Live Demo und Beispiele:

   • Die Web Components werden in Storybook entwickelt und dokumentiert.
   • Es gibt ein Figma Beispiel für einen Online-Dienst "Hundehaltung".
   • Und eine Umsetzung des Beispiels mit den Web Componenten.

4. Dokumentation: Die Dokumentation ist derzeit komplett in englischer Sprache. Dieses Projekt ist auch ein Testballon für KI-unterstützte Softwareentwicklung, wobei die "Zusammenarbeit" mit LLMs derzeit noch besser über englische Inhalte funktioniert.

✨ What's New in 3.2.0

Version 3 aligns the library with the official KERN release 2.7.2, makes the form components work inside real HTML forms, and adds a layout utility layer. See CHANGELOG.md for the full history.

Breaking changes in 3.0.0

• @kern-ux/native upgraded from 2.2.0 to 2.7.2. The reference examples require classes that do not exist in 2.2.0.
• kern-button with href now renders an <a class="kern-btn"> instead of a <button> that assigned window.location.href, so middle-click, ctrl-click and "copy link address" work again.
• The advertised ./components/* deep import never actually existed and has been removed from the package exports. Import from the package root.

New

• KERN Editor export target — the kit now implements all 84 KERN Editor component types across over 100 registered custom elements. Where the editor and the kit named a concept differently, the kit accepts both spellings via additive kebab-case aliases. The machine-readable contract ships as kern-editor-manifest.json and is described in docs/concepts/editor-export-target.md.
• Optional peer dependencies — kern-chart, kern-map, kern-knowledge-graph and Markdown rendering load their libraries lazily and degrade to an accessible fallback when the library is absent (see below).
• Form participation — kern-input, kern-textarea, kern-checkbox, kern-checkbox-list, kern-radio, kern-select and kern-search are form-associated via ElementInternals. They contribute to FormData, respond to form.reset(), take part in constraint validation and honour a disabled ancestor <fieldset>.
• kern-search — the official KERN search pattern in all three documented variants.
• Layout utilities — kern-stack, kern-flex, kern-grid, kern-grid-item, kern-aspect-ratio and kern-visually-hidden.
• kern-body muted — muted and bold are independent and combine into the muted-bold style.

Accessibility — BITV 2.0 / WCAG 2.1 AA

• An automated audit with Playwright and axe-core over all 538 stories in both themes went from 1 718 node occurrences to 0. npm run test:stories now gates the result at a11y.test: 'error', with no per-story opt-outs, so a regression fails the build. This is not a conformance statement. It is an automated Chromium snapshot of each story's initial state; 122 checks per theme remain unresolved and need manual measurement, and whole criteria — keyboard journeys, screen-reader output, reflow, page-level structure — are outside what any automated scan can decide.
• The largest defect class was structural: a shadow boundary between a list and its items meant <dl>/<ol> had no children and <dt>/<dd>/<li> had no parent. Containers now own the semantic structure and project each item into its own cell.
• The KERN base stylesheet removed the focus ring precisely when a keyboard user focused an element. KernElement restores it for every focusable host (WCAG 2.4.7).
• Accessible names written as aria-label on a component host now reach the element that owns the role — a host has no role, so they previously reached nothing. kern-label's for now names its target for the first time (naming only — native click-to-focus still needs a real <label>).
• Run it yourself with npm run audit:a11y; the full report, the dispositions of every unresolved check and what automation cannot cover are in docs/security-audit.md.

Correctness and tooling

• 57 non-existent --kern-* custom properties were mapped onto real KERN design tokens; they had silently resolved to fallbacks, so components were not actually themeable. A further 52 invented tokens were removed from the stories in 3.2.0.
• Invented kern-* class names were removed, and npm run lint:kern now fails the build if a component uses a token or class that KERN does not define.
• The KERN fonts are now actually loaded and self-hosted; the Google Fonts dependency is gone.
• Dark mode is bridged to the native color-scheme property.
• vscode-html-custom-data.json is generated from source and covers every element, attribute, accepted value, property type, public method and event.
• README.md, CHANGELOG.md, LICENSE.md, COMPONENTS.md, vscode-html-custom-data.json and sbom-cyclonedx.json are copied into dist/.
• 2 049 unit tests (coverage gate 94 % statements / 86 % branches / 85 % functions / 94 % lines) plus 538 story tests that render every story in a real browser once per theme and scan it with axe, and 51 Node tests for the tooling.
• npm audit reports no vulnerabilities.

Tech stack: Node 22+ · Lit 3.3.1 · TypeScript 5.8.3 · Vite 7.3.6 · Rollup 4.62.3 · Storybook 10.5.5 · Vitest 4.1.10 · ESLint 10.8.0

🧩 Optional peer dependencies

Three components wrap a third-party library, and Markdown rendering needs two more. All of them are declared as optional peer dependencies (peerDependenciesMeta.*.optional = true) and imported lazily at runtime. Nothing breaks when they are absent: the component renders a documented, accessible fallback and logs a single console warning explaining how to enable the feature.

| Feature | Peer dependency | Unlocks | Fallback when absent | | --- | --- | --- | --- | | kern-chart | echarts | Interactive charts | Accessible data table | | kern-map | leaflet (+ @geoman-io/leaflet-geoman-free for the drawing tools) | Interactive map | Static attribution/summary block | | kern-knowledge-graph | force-graph | Interactive graph | Accessible node list | | any enable-markdown field | markdown-it + dompurify | Markdown rendering | Escaped plain text |

Install only what you use:

npm install echarts                                   # kern-chart
npm install leaflet @geoman-io/leaflet-geoman-free    # kern-map
npm install force-graph                               # kern-knowledge-graph
npm install markdown-it dompurify                     # enable-markdown

Hosts that externalise these libraries (for example through an import map or a bundler alias) can register their own instance with the registerOptionalPeer() escape hatch instead of letting the kit resolve the bare specifier:

import { registerOptionalPeer } from '@kern-ux-annex/webc';
import * as echarts from 'echarts';

registerOptionalPeer('echarts', echarts);

🧭 KERN Editor interoperability

The kit is designed to double as a Web Components export target for the KERN Editor. It implements all 84 of the editor's ProjectComponentType values, and a CI gate (npm run lint:kern, which now also runs check:editor-coverage --strict and check:editor-manifest) keeps that coverage from regressing.

• kern-editor-manifest.json — the authoritative, machine-readable inventory: for every editor type it lists the custom element tag, each public property with its actual attribute name, the alias properties, the property renames, the deliberately omitted fields and the children/slot contract. Read properties[].attribute rather than deriving attribute names — Lit lowercases the property name by default, so it is not always kebab-case.
• docs/concepts/editor-export-target.md — the contract document: aliases, nesting, form association, pass-through guarantees, the optional peers and what the kit deliberately leaves to the host (data binding, credentials, validation policy).

import manifest from '@kern-ux-annex/webc/kern-editor-manifest.json' with { type: 'json' };

Refresh the editor type snapshot from a local editor checkout, then regenerate and verify the manifest:

npm run snapshot:editor-types -- ../kern-editor
npm run generate:editor-manifest
npm run check:editor-manifest

Beitragen

Die Entwicklung des KERN Design-Systems ist im Hauptrepository organisiert.

Für Bugs und Verbesserungsvorschläge, die sich ausschließlich auf den CSS/HTML-Code beziehen, schaue dir bitte unsere Contributing Guidelines an. Wir freuen uns auf deinen Beitrag!

📚 Documentation

• Component Documentation - Detailed component APIs, properties, events, and examples
• Development & DevOps Guide - Development setup, build processes, testing, and deployment
• IntelliSense Setup Guide - Complete guide for setting up IDE support with autocompletion
• Live Storybook Demo - Interactive component playground
• KERN Design System - Official KERN design system documentation

🔤 Schriftarten

Das KERN-Stylesheet wird beim Import automatisch eingebunden, die Schriftdateien jedoch nicht: kern.css enthält keine @font-face-Regeln, KERN liefert die Schriften als eigene Stylesheets aus. Ohne diesen Import greift der System-Fallback und die Typografie weicht sichtbar vom KERN Design-System ab.

import '@kern-ux-annex/webc';

// Schriften zusätzlich laden – ohne sie greift der System-Fallback
import '@kern-ux/native/dist/fonts/fira-sans.css';
import '@kern-ux/native/dist/fonts/noto-sans.css';

Alternativ per <link>, wenn kein Bundler verwendet wird. Die Dateien müssen dann selbst ausgeliefert werden – in diesem Repository liegen sie unter public/fonts/kern/:

<link rel="stylesheet" href="/fonts/kern/fira-sans.css" />
<link rel="stylesheet" href="/fonts/kern/fira-mono.css" />

Wichtig: Schriften bitte immer selbst ausliefern und nicht über einen Drittanbieter-CDN wie Google Fonts einbinden. Für Angebote der öffentlichen Verwaltung ist das aus Datenschutzgründen in der Regel nicht zulässig.

Die Schrift-Stylesheets referenzieren die .woff2-Dateien relativ zum eigenen Pfad. Sie müssen daher als Datei geladen werden und können nicht in ein <style>-Element inliniert werden.

🎨 Theming & Dark Mode

Die Komponenten beziehen ihre Farben ausschließlich aus den KERN Design-Tokens (CSS Custom Properties wie --kern-color-layout-text-default). Diese Tokens werden von KERN auf Dokument-Ebene deklariert – auf :root, body, [data-kern-theme] sowie .kern-light / .kern-dark.

Das ist wichtig zu verstehen: Keiner dieser Selektoren kann innerhalb eines Shadow Roots greifen. Die Tokens erreichen die Komponenten daher über die Vererbung von CSS Custom Properties aus dem Dokument. Damit das funktioniert, injiziert die Bibliothek beim Import automatisch eine Dokument-Schicht mit KERN-Tokens, globalen Regeln, Grid und Hilfsklassen in den <head>. Die vollständigen, minifizierten Komponenten-Styles werden als ein gemeinsam genutztes Stylesheet in den Shadow Roots adoptiert. Details und CSP-Optionen beschreibt das CSS-Integrationskonzept.

<!-- Helles Design erzwingen -->
<html data-kern-theme="light">
  ...
</html>

<!-- Dunkles Design erzwingen -->
<html data-kern-theme="dark">
  ...
</html>

<!-- Systemeinstellung übernehmen: Attribut einfach weglassen -->
<html>
  ...
</html>

Ein Design kann auch auf einem beliebigen Vorfahren gesetzt werden, nicht nur auf <html> – verschachtelte Bereiche sind damit möglich:

<div class="kern-dark">
  <kern-button variant="primary">Immer dunkel</kern-button>
</div>

Zur Laufzeit stehen Hilfsfunktionen bereit:

import { applyKernTheme, toggleKernTheme, getCurrentThemeMode } from '@kern-ux-annex/webc';

applyKernTheme({ mode: 'dark' });
toggleKernTheme();
getCurrentThemeMode(); // 'light' | 'dark'

🧠 IntelliSense Support

KERN Web Components provide full IntelliSense support for:

• ✅ HTML files - Component autocompletion and attribute suggestions
• ✅ TypeScript/JavaScript - Full type safety and autocompletion
• ✅ React/JSX - Component props and event handling
• ✅ Vue.js - Template syntax support
• ✅ VS Code - Custom HTML data for enhanced development experience

Quick Setup

// TypeScript - automatic IntelliSense
import '@kern-ux-annex/webc';

const button = document.querySelector('kern-button');
button.variant = 'primary'; // IntelliSense suggests available variants

<!-- HTML - with VS Code custom data -->
<kern-button variant="primary" size="x-small">
  <!-- IntelliSense will suggest all available attributes -->
</kern-button>

For detailed setup instructions, see our IntelliSense Setup Guide.

Quick Contributing Guide

1. Fork the repository
2. Install dependencies: npm install
3. Start development: npm run dev
4. Make your changes following our guidelines
5. Run tests: npm test
6. Submit a pull request

Testing

| Command | What it does | | --- | --- | | npm test | Component tests with coverage thresholds (94/86/85/94) | | npm run lint | ESLint, Prettier and the KERN class/token conformance check | | npm run lint:package | Verifies the built package matches what package.json advertises | | npm run test:stories | Runs every story through Vitest in a real browser, once per theme, and applies the accessibility scan. Gated at error. | | npm run test:scripts | Node tests for the build and audit tooling | | npm run audit:a11y | Full Playwright + axe-core accessibility audit of every story in both themes, with provenance |

npm run lint:kern fails the build when a component uses a kern-* class or a --kern-* design token that the KERN stylesheet does not define — both are invisible at runtime, because an unknown class is simply unstyled and an unknown token silently falls back to whatever literal sits next to it. It also runs check:editor-coverage --strict and check:editor-manifest, so the build fails if an editor component type becomes unmapped or if kern-editor-manifest.json drifts from the sources.

For detailed contribution guidelines, see CONTRIBUTING.md.

🔗 Links & Resources

• KERN UX Website - Official KERN design system website
• Live Storybook - Interactive component demo
• GitLab Repository - Source code
• NPM Package - Package page

📄 License

EUPL-1.2 License - see LICENSE.md file for details

KERN ist ein Open-Source-Projekt, das von den Ländern Hamburg und Schleswig-Holstein initiiert wurde. Alle mit Interesse an der Digitalisierung der öffentlichen Verwaltung sind herzlich eingeladen, Teil der bundesweiten interdisziplinären Community zu werden.