2.7.1 • Published 11 months ago

@kern-ux-annex/webc v2.7.1

Weekly downloads
-
License
EUPL-1.2
Repository
gitlab
Last release
11 months ago

KERN Web Components Library

npm version License: EUPL-1.2 Built with Lit Storybook

A comprehensive Web Components library built with Lit and TypeScript, implementing the complete KERN design system for German public administration.

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. KERN ist ein Open-Source-Projekt, das von der 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. Alle Informationen auf unserer Website.

Hinweise

  1. Dieses Projekt befindet sich in aktiver Entwicklung. KERN 2 wurde am 27.5.2025 released. Diese Projekt basiert auf dem KERN – Plain-CSS-HTML-Kit in der Version 2.1.1 (oder höher). Es benutzt dessen CSS-Klassen und HTML Code Beispiele. Vielen Dank an das ganze KERN Projekt!

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

  3. Der jeweils aktuelle Storybook-Build ist unter https://kern-ux-webc.mein-service.net zu finden.

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!

Table of Contents

Features

  • ✅ Built with Lit framework for standards-based web components
  • ✅ TypeScript support with full type definitions
  • ✅ KERN design system integration
  • ✅ Comprehensive test suite
  • ✅ Tree-shakeable builds
  • ✅ Accessible components following ARIA guidelines

Components

This library includes 50+ production-ready components implementing the complete KERN design system, organized into logical categories:

🧭 Navigation & Layout Components

  • kern-accordion - Collapsible content sections with accessible details/summary structure
  • kern-breadcrumb / kern-breadcrumb-item - Navigation hierarchy with keyboard support
  • kern-card - Versatile container with variants (default, hug, active, small, large)
  • kern-card-media / kern-card-header / kern-card-body / kern-card-footer / kern-card-container - Card composition system
  • kern-divider - Visual content separators with semantic meaning
  • kern-grid-container / kern-grid-row / kern-grid-col - Responsive grid layout system
  • kern-kopfzeile - Header/masthead component for site branding
  • kern-menu / kern-menu-item - Accessible dropdown menus and navigation
  • kern-tabs / kern-tab-panel - Tabbed content with variants (default, underlined, pills)

📝 Forms & Input Components

  • kern-button - Interactive buttons with variants, icons, loading states, and block layout
  • kern-checkbox - Accessible checkbox input controls with validation
  • kern-checkbox-list - Grouped checkbox collections with fieldset structure
  • kern-fieldset - Form field grouping with legend and validation support
  • kern-input - Text inputs supporting all HTML5 types (text, email, password, number, tel, url, search, file)
  • kern-label - Form labels with required indicators and accessibility features
  • kern-radio - Radio button controls with group management
  • kern-select - Dropdown selection controls with validation and custom styling
  • kern-textarea - Multi-line text input with resize control and validation

💬 Feedback & Communication Components

  • kern-alert / kern-alert-content - Status messages with dismissible functionality and variants
  • kern-badge / kern-badge-icon - Small status indicators with icon support and color variants
  • kern-dialog - Modal dialogs and overlays with multiple variants and focus management
  • kern-loader - Loading states and spinner animations with size variants
  • kern-progress - Progress bars and loading indicators with customizable styling
  • kern-tooltip - Contextual information on hover/focus with positioning control

📄 Content & Typography Components

  • kern-avatar - User profile pictures with fallback initials and customizable styling
  • kern-body / kern-text - Body text with KERN typography system (size variants: large, default, small)
  • kern-heading - Semantic headings (h1-h6) with 1:1 level-to-size mapping and override options
  • kern-link - Enhanced links with icon support, variants, and accessibility features
  • kern-list / kern-list-item - Styled lists (default, bullet, number) with size variants
  • kern-preline - Pre-content text elements for introductory content
  • kern-subline - Sub-content text with multiple size variants
  • kern-title - Title text component with size variants for hierarchical content

📊 Data Display Components

  • kern-description-list / kern-description-list-item - Key-value pair displays with copyable functionality
  • kern-summary / kern-summary-group - Summary sections with numbered groups and collapsible content
  • kern-table / kern-thead / kern-tbody / kern-tfoot / kern-tr / kern-th / kern-td - Complete table system with responsive design, sorting, and striping
  • kern-task-list / kern-task-list-item / kern-task-list-group - Task management with status tracking and grouping

🎨 Display & Media Components

  • kern-icon - Comprehensive icon system with the complete KERN icon library and size variants

🔧 Component Features

  • Accessibility First: Full ARIA support, keyboard navigation, and screen reader compatibility
  • Theme Support: Automatic light/dark theme handling with KERN design tokens
  • Responsive Design: Mobile-first approach with breakpoint-aware components
  • Form Integration: Native form validation and submission support
  • Event System: Custom events with kern- prefix for framework integration
  • TypeScript Support: Full type definitions for all properties and events
  • CSS Custom Properties: Extensive theming through CSS variables
  • Shadow DOM: Encapsulated styling preventing conflicts
  • Tree Shakeable: Import only what you need for optimal bundle size

Installation

npm install @kern-ux-annex/webc

Quick Start

Get started with KERN Web Components in just a few steps:

  1. Install the package:

    npm install @kern-ux-annex/webc

  2. Import components in your project:

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

  3. Use components in your HTML:

    <kern-button variant="primary">My First Button</kern-button>
<kern-alert variant="success">Welcome to KERN!</kern-alert>

  4. Start building! All components are now available and styled with the KERN design system.

Usage

Import all components

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

Import specific components

import '@kern-ux-annex/webc/components/button/kern-button.js';
import '@kern-ux-annex/webc/components/alert/kern-alert.js';

Use in HTML

<kern-button variant="primary" size="large">Click me</kern-button>
<kern-alert variant="success" dismissible>Operation completed!</kern-alert>
<kern-badge variant="warning">New</kern-badge>

Use in frameworks

React

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

function App() {
  return (
    <div>
      <kern-button variant="primary" onClick={handleClick}>
        Click me
      </kern-button>
    </div>
  );
}

Vue

<template>
  <kern-button variant="primary" @kern-click="handleClick">
    Click me
  </kern-button>
</template>

<script>
import '@kern-ux-annex/webc';
</script>

Storybook Integration

The library includes a comprehensive Storybook setup for component development, testing, and documentation.

🎨 Interactive Component Playground

Storybook provides an interactive environment to explore all 50+ KERN components with live examples, property controls, and usage documentation.

🌗 Theme Support

The Storybook environment includes full KERN design system theme support:

  • Light Theme: Default KERN light theme with data-kern-theme="light"
  • Dark Theme: KERN dark theme with data-kern-theme="dark"
  • Dynamic Theme Switching: Toggle between themes using the Storybook toolbar
  • Automatic Theme Attributes: Body element automatically receives appropriate data-kern-theme attributes
  • KERN CSS Integration: Complete KERN CSS framework and Fira Sans fonts are automatically loaded

🎯 Features

  • Complete Component Coverage: All components with multiple variants and states
  • Interactive Controls: Modify component properties in real-time
  • Accessibility Testing: Built-in accessibility checks and documentation
  • Design System Integration: Automatic KERN CSS and font loading
  • Responsive Testing: Test components across different screen sizes
  • Code Examples: Copy-paste ready code snippets for each component

📚 Storybook Commands

# Start Storybook development server
npm run storybook

# Build static Storybook for deployment
npm run build-storybook

🚀 Accessing Storybook

  • Development: http://localhost:6006 (when running npm run storybook)
  • Static Build: Available in storybook-static/ directory after building

Scripts & Commands

The project includes comprehensive npm scripts for all development and deployment tasks:

Development Scripts

# Start development server with hot reload
npm run dev

# Start Storybook for component development
npm run storybook

# Run tests in watch mode
npm run test:watch

# Generate KERN styles from latest CSS
npm run generate:styles

Build Scripts

# Full production build (library + types + changelog)
npm run build

# Build only the bundled library files
npm run build:lib

# Build only TypeScript declaration files
npm run build:types

# Build static Storybook for deployment
npm run build-storybook

Azure Deployment Scripts

# Deploy Storybook to Azure Web App (Linux/macOS)
npm run deploy:azure

# Deploy Storybook to Azure Web App (Windows PowerShell)
npm run deploy:azure-ps

# Prepare deployment package locally
npm run deploy:prepare

Testing Scripts

# Run all tests once
npm test

# Run tests in watch mode for development
npm run test:watch

Publishing Scripts

# Test publish (dry run) - verify package contents
npm run publish:dry-run

# Publish stable release to NPM
npm run publish:package

# Publish beta version with 'beta' tag
npm run publish:beta

# Publish experimental version with 'next' tag
npm run publish:next

# Publish with full test suite (build + test + publish)
npm run publish:with-tests

# Dry run with full test suite
npm run publish:dry-run-with-tests

Release Management Scripts

# Create new release (interactive)
npm run release

# Bump patch version (1.0.0 → 1.0.1)
npm run release:patch

# Bump minor version (1.0.0 → 1.1.0)
npm run release:minor

# Bump major version (1.0.0 → 2.0.0)
npm run release:major

Changelog Scripts

# Generate complete changelog
npm run changelog:generate

# Update changelog with latest changes
npm run changelog:update

# Add version entry to changelog
npm run changelog:add-version

Preview Scripts

# Preview built application
npm run preview

Component Documentation

kern-button

Interactive button component with multiple variants, icon support, and block layout.

Properties:

  • variant: 'primary' | 'secondary' | 'tertiary' | 'danger' (default: 'primary')
  • disabled: boolean (default: false)
  • type: 'button' | 'submit' | 'reset' (default: 'button')
  • icon-left: KernIconName - Icon to display on the left side
  • icon-right: KernIconName - Icon to display on the right side
  • block: boolean (default: false) - Full width button

Events:

  • kern-click: Fired when button is clicked

Example:

<kern-button variant="primary" icon-left="add">Add Item</kern-button>
<kern-button variant="danger" disabled>Disabled Button</kern-button>
<kern-button block>Full Width Button</kern-button>

kern-alert

Status and notification messages with multiple variants and dismissible support.

Properties:

  • variant: 'info' | 'success' | 'warning' | 'danger' (default: 'info')
  • title: string - Alert title
  • dismissible: boolean (default: false)

Events:

  • kern-dismiss: Fired when alert is dismissed

Slots:

  • title: Alert title content
  • default: Alert message content

Example:

<kern-alert variant="success" title="Success">Operation completed!</kern-alert>
<kern-alert variant="error" dismissible>Something went wrong</kern-alert>

kern-card

Container component with multiple variants and sub-component support.

Properties:

  • variant: 'default' | 'hug' | 'active' | 'small' | 'large' (default: 'default')
  • max-width: string - Optional maximum width

Events:

  • kern-card-click: Fired when active variant card is clicked

Sub-components:

  • kern-card-media: For images and media content
  • kern-card-header: For card headers
  • kern-card-body: For main card content
  • kern-card-footer: For card actions
  • kern-card-container: For grouping header/body/footer

Example:

<kern-card variant="active" max-width="400px">
  <kern-card-media>
    <img src="image.jpg" alt="Card image">
  </kern-card-media>
  <kern-card-container>
    <kern-card-header>
      <kern-title>Card Title</kern-title>
    </kern-card-header>
    <kern-card-body>
      <kern-body>Card content goes here</kern-body>
    </kern-card-body>
    <kern-card-footer>
      <kern-button variant="primary">Action</kern-button>
    </kern-card-footer>
  </kern-card-container>
</kern-card>

kern-tabs

Tabbed content navigation with multiple variants and accessibility support.

Properties:

  • active-tab: string - ID of the currently active tab
  • variant: 'default' | 'underlined' | 'pills' (default: 'pills')
  • size: 'small' | 'medium' | 'large' (default: 'medium')

Events:

  • kern-tab-change: Fired when active tab changes

Sub-components:

  • kern-tab-panel: Individual tab panels with tab-id, tab-label, and disabled properties

Example:

<kern-tabs active-tab="tab1" variant="pills">
  <kern-tab-panel tab-id="tab1" tab-label="First Tab">
    <p>Content for first tab</p>
  </kern-tab-panel>
  <kern-tab-panel tab-id="tab2" tab-label="Second Tab">
    <p>Content for second tab</p>
  </kern-tab-panel>
</kern-tabs>

kern-input

Text input controls with validation and multiple input types.

Properties:

  • label: string - Input label
  • value: string - Input value
  • type: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'file' (default: 'text')
  • placeholder: string - Placeholder text
  • disabled: boolean (default: false)
  • required: boolean (default: false)
  • readonly: boolean (default: false)
  • error-message: string - Error message to display
  • help-text: string - Help text to display
  • name: string - Form field name
  • autocomplete: string - Autocomplete attribute

Events:

  • kern-input: Fired when input value changes
  • kern-focus: Fired when input gains focus
  • kern-blur: Fired when input loses focus

Example:

<kern-input 
  label="Email Address" 
  type="email" 
  required 
  help-text="We'll never share your email">
</kern-input>

kern-table

Complete table system with responsive design and accessibility.

Properties:

  • caption: string - Table caption
  • small: boolean (default: false) - Compact table variant
  • striped: boolean (default: false) - Alternating row colors
  • responsive: boolean (default: false) - Responsive wrapper

Sub-components:

  • kern-thead, kern-tbody, kern-tfoot: Table sections
  • kern-tr: Table rows
  • kern-th, kern-td: Table cells

Example:

<kern-table caption="Data Table" striped responsive>
  <kern-thead>
    <kern-tr>
      <kern-th>Name</kern-th>
      <kern-th>Email</kern-th>
      <kern-th>Role</kern-th>
    </kern-tr>
  </kern-thead>
  <kern-tbody>
    <kern-tr>
      <kern-td>John Doe</kern-td>
      <kern-td>john@example.com</kern-td>
      <kern-td>Admin</kern-td>
    </kern-tr>
  </kern-tbody>
</kern-table>

kern-heading

Semantic heading component with KERN design system typography classes using a 1:1 relationship between heading levels and typography sizes.

Properties:

  • level: 1 | 2 | 3 | 4 | 5 | 6 - REQUIRED - The semantic heading level
  • size: 'display' | 'x-large' | 'large' | 'medium' | 'small' - Optional override for default level-size mapping

Default Level-to-Size Mapping:

  • level="1" → kern-heading-display
  • level="2" → kern-heading-x-large
  • level="3" → kern-heading-large
  • level="4" → kern-heading-medium
  • level="5" → kern-heading-small
  • level="6" → kern-heading-small

Example:

<!-- Default 1:1 mapping -->
<kern-heading level="1">Display Heading (h1)</kern-heading>
<kern-heading level="2">X-Large Heading (h2)</kern-heading>
<kern-heading level="3">Large Heading (h3)</kern-heading>

<!-- Override with custom size -->
<kern-heading level="3" size="display">h3 with Display styling</kern-heading>
<kern-heading level="1" size="small">h1 with Small styling</kern-heading>

kern-body / kern-text

Body text component with KERN design system typography classes. Available as both kern-body and kern-text for semantic flexibility.

Properties:

  • size: 'large' | 'default' | 'small' - Text size variant (defaults to 'default')
  • bold: boolean - Whether to apply bold font weight (defaults to false)

Available KERN CSS Classes Applied:

  • Base: .kern-body
  • Size variants: .kern-body--large, .kern-body--small
  • Weight variant: .kern-body--bold

Example:

<!-- Default body text -->
<kern-body>Standard body text with default size and weight.</kern-body>

<!-- Size variants -->
<kern-body size="large">Large body text for emphasis.</kern-body>
<kern-body size="small">Small body text for secondary information.</kern-body>

<!-- Bold text -->
<kern-body bold>Bold body text for emphasis.</kern-body>

<!-- Combined properties -->
<kern-body size="large" bold>Large bold text for strong emphasis.</kern-body>

<!-- Alternative component name -->
<kern-text size="small">Alternative semantic name for body text.</kern-text>

Development

Prerequisites

  • Node.js 18+ (LTS recommended)
  • npm 8+ or yarn 1.22+
  • Git for version control

Setup

# Clone the repository
git clone https://gitlab.opencode.de/kern-ux/community/kern-webcomponents-light-kit.git
cd kern-webcomponents-light-kit

# Install dependencies
npm install

# Generate KERN styles and start development server
npm run dev

# Start Storybook for component development
npm run storybook

Project Structure

kern-webcomponents-light-kit/
├── examples                # Two example projects for plain HTML usage (with Vite) and React usage.
├── .storybook/              # Storybook configuration
│   ├── main.ts             # Main Storybook config with KERN CSS imports
│   └── preview.ts          # Preview config with theme support
├── src/
│   ├── components/         # All KERN web components
│   │   ├── accordion/      # Component folders with .ts and .stories.ts files
│   │   ├── alert/
│   │   ├── button/
│   │   └── ...            # 50+ component directories
│   ├── styles/            # Global styles and CSS utilities
│   │   ├── kern-styles.ts # Generated KERN CSS content
│   │   └── ...
│   └── index.ts          # Main entry point - exports all components
├── test/                 # Component tests (.test.ts files)
├── scripts/              # Build and automation scripts
│   ├── generate-kern-styles.js    # KERN CSS integration
│   ├── generate-changelog.js     # Automated changelog
│   ├── publish.js                # NPM publishing
│   └── release.js               # Version management
├── docs/                 # Documentation and guides
├── dist/                 # Built library output
└── storybook-static/     # Built Storybook output

Development Workflow

  1. Component Development: Create/modify components in src/components/
  2. Story Creation: Add Storybook stories (.stories.ts) for component testing
  3. Test Writing: Create comprehensive tests in test/ directory
  4. Documentation: Update component documentation and examples
  5. Build & Test: Run full build and test suite before committing

Key Development Files

  • src/index.ts: Main entry point - add new component exports here
  • .storybook/preview.ts: Storybook theme configuration with KERN integration
  • rollup.config.js: Build configuration for library bundling
  • web-test-runner.config.js: Test runner configuration
  • tsconfig.json: TypeScript configuration for development
  • tsconfig.build.json: TypeScript configuration for production builds

Adding New Components

  1. Create component directory: src/components/my-component/
  2. Implement component: my-component.ts extending KernElement
  3. Add Storybook stories: my-component.stories.ts
  4. Write tests: test/my-component.test.ts
  5. Export component: Add to src/index.ts
  6. Update documentation: Add to README.md component list

Component Development Guidelines

  • Extend KernElement: All components should extend the base KernElement class
  • Use KERN CSS: Apply KERN design system classes and tokens from @kern-ux/native
  • Follow Lit Patterns: Use Lit decorators, reactive properties, and best practices
  • TypeScript Types: Provide complete TypeScript interfaces and JSDoc documentation
  • Custom Events: Emit events with kern- prefix for consistency
  • CSS Custom Properties: Use CSS variables for theming aligned with KERN tokens
  • Accessibility: Ensure ARIA compliance and keyboard navigation support
  • Testing: Write comprehensive tests covering properties, events, and accessibility

Testing

The project uses Web Test Runner with Playwright for comprehensive testing across multiple browsers.

Test Configuration

  • Framework: @web/test-runner with @open-wc/testing
  • Browsers: Chromium, Firefox, and WebKit via Playwright
  • Coverage: Included in test runs with detailed reporting
  • Accessibility: Built-in accessibility testing with @open-wc/testing

Running Tests

# Run all tests once
npm test

# Run tests in watch mode for development
npm run test:watch

# Run tests with coverage report
npm test -- --coverage

Test Structure

  • Location: All tests in test/ directory
  • Naming: component-name.test.ts format
  • Coverage: Tests cover component properties, events, slots, and accessibility
  • Examples: Each test file includes comprehensive component testing patterns

Writing Tests

import { fixture, assert } from '@open-wc/testing';
import { html } from 'lit';
import '../src/components/button/kern-button.js';

describe('kern-button', () => {
  it('renders with default properties', async () => {
    const el = await fixture(html`<kern-button>Test</kern-button>`);
    assert.shadowDom.equal(el, '<button class="kern-button">Test</button>');
  });

  it('emits kern-click event', async () => {
    const el = await fixture(html`<kern-button>Test</kern-button>`);
    let eventFired = false;
    el.addEventListener('kern-click', () => { eventFired = true; });
    
    el.click();
    assert.isTrue(eventFired);
  });
});

Publishing

The library supports automated publishing to NPM with different distribution tags:

# Test publish (dry run)
npm run publish:dry-run

# Publish stable release
npm run publish:package

# Publish beta version
npm run publish:beta

# Publish experimental version  
npm run publish:next

For detailed publishing instructions, see NPM Publishing Guide.

Performance & Bundle Size

  • Tree-shakeable: Import only the components you need
  • Lightweight: Built with minimal dependencies
  • Modern: Leverages native browser APIs for optimal performance
  • CSS-in-JS free: Uses native CSS with Shadow DOM for style isolation

Bundle Analysis

The library is designed for optimal tree-shaking. When importing individual components:

// Only bundles the button component
import '@kern-ux-annex/webc/components/button/kern-button.js';

Browser Support

Modern browsers that support:

  • ES2019+
  • Web Components (Custom Elements, Shadow DOM)
  • CSS Custom Properties
  • Modern browser versions: Chrome 64+, Firefox 63+, Safari 13+, Edge 79+

License

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

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

For more details, see CONTRIBUTING.md.

Design System

This library implements the KERN design system. For design guidelines and specifications, refer to the KERN design documentation.

The library automatically imports the KERN CSS framework and Fira Sans font. All components use KERN design tokens for consistent styling.

Links & Resources

Related Projects

  • KERN Plain CSS/HTML Kit - The foundation CSS and HTML examples this library is based on
  • KERN Pattern Library - The main KERN design system repository
  • KERN UX Community - Join the interdisciplinary community for digital public administration

Made with ❤️ by the KERN UX Community

KERN-UXwebcomponentslitlit-elementlit-htmlui-componentsui-library
@kern-ux/nativelitplaywrighttslib
2.7.1

11 months ago

2.5.1

11 months ago

2.5.0

11 months ago

2.4.5

11 months ago

2.4.4

11 months ago

2.4.3

11 months ago

2.4.2

11 months ago

2.4.1

11 months ago

2.3.0

11 months ago

2.2.1

11 months ago

2.2.0

11 months ago

2.1.5

11 months ago

2.1.2

11 months ago

2.1.1

11 months ago