DOCSEARCHbyAlgolia
Submit Docs

KoliBri Web Component Library

repository·develop·Indexed 43 days ago

https://github.com/public-ui/kolibri

A library of accessible, framework-agnostic Web Components designed to extend the HTML5 standard. KoliBri provides atomic, semantic UI elements that can be themed for any design system. It includes official adapters for Angular (v20, v21), React (including React 19), SolidJS, Preact, and React Hook Form, as well as an experimental hydrate adapter for Server Side Rendering (SSR).

Tokens
196.1K
Snippets
429
Records
705
Agent score
51%

What's inside KoliBri

  1. Overview of the KoliBri System Architecture

    develop

    KoliBri is organized into several core packages that separate concerns between logic, styling, and framework integration:

    • @public-ui/components: The core Web Component library providing atomic, accessible HTML components.
    • @public-ui/themes: Visual styling packages that separate presentation from logic.
    • @public-ui/adapters: Framework-specific wrappers (React, Angular, Vue, etc.) for native integration.
    • @public-ui/icons: Icon font definitions and assets.
    • @public-ui/tools: Development and migration utilities (CLI, Visual Testing).
    • @public-ui/samples: Example applications demonstrating component usage.

    Key Interfaces:

    • @public-ui/components: Main export for the component library.
    • @public-ui/theme-*: Theme packages (e.g., default, ecl).
    • @public-ui/react, @public-ui/angular-*, @public-ui/vue: Framework adapters.
    • Theme Registration API: register(theme, defineCustomElements)

  2. Overview of kol-all component collection

    develop
    The kol-all package serves as an aggregate collection of all KoliBri components. It acts as a single entry point or dependency umbrella that includes the entire suite of individual component packages. This is useful for projects that want to ensure access to the full range of KoliBri UI elements without managing dozens of individual package dependencies manually.

  4. Overview of KoliBri Tools

    develop

    KoliBri provides a suite of tools located in the packages/tools/ directory to assist with maintenance, testing, and AI-assisted development:

    • KoliBri CLI (packages/tools/kolibri-cli/): Used for component migration between versions, project analysis, dependency checks, automated code transformations, and running the migration test framework.
    • Visual Tests (packages/tools/visual-tests/): Performs visual regression testing for Themes using screenshot comparisons, snapshot management, and theme validation.
    • MCP Server (packages/tools/mcp/): A Model Context Protocol server that provides repository context to AI tools to assist with code generation and reviews.

  5. Overview of KoliBri core requirements and capabilities

    develop

    KoliBri is an open-source web component library designed to provide accessible, semantic, and valid HTML by default. It is built to serve as a reference implementation for accessibility standards while maintaining high flexibility for different organizational needs.

    Key Capabilities

    • Accessibility First: Components are designed to meet WCAG 2.2 Level AAA and BITV requirements.
    • Framework Agnostic: The library is designed to work with any web framework (e.g., React, Angular, Vue) or vanilla JavaScript.
    • Multi-theming: Supports multiple design systems and corporate identities through a presentation layer that allows applying corporate designs without modifying component code.
    • Reusability: Provides atomic, flexible components that can be composed into complex interfaces.
    • Standards Compliance: Strictly follows W3C web standards.
    • Long-term Support: Provides LTS versions for enterprise-grade stability.

  6. Overview of KoliBri Architecture Documentation

    develop
    KoliBri is an accessible web component library. Its architecture is documented using the arc42 template, which provides structured insights into the system's design, decisions, and quality requirements. The documentation is organized into several key sections including goals, constraints, building blocks, runtime views, and cross-cutting concepts to help developers and architects understand the system's implementation and design rationale.

  7. Overview of the Open Source Process

    develop

    The Open Source process for KoliBri involves several parallel sub-processes to transition a project to a public state. The main stages are:

    1. NPM Setup: Configuring the organization and metadata on NPM.
    2. GitHub Setup: Setting up the organization, security, landing pages, and repository pipelines on GitHub.
    3. Repository Preparation: Cleaning up internals and adding essential documentation (CoC, Contributing, CLA, Changelog).
    4. Team Organization: Defining ownership, communication standards, and funding.
    5. Legal & Brand: Protecting trademarks and verifying licenses.

    Once these are complete, the process requires management approval (Leitungsfreigabe), history cleanup (Historie bereinigen), and finally publishing the source code or artifacts.

  8. Understand KoliBri project risks and technical debt

    develop

    The KoliBri project maintains a risk register and technical debt log to ensure long-term sustainability. Developers and users should be aware of these factors when planning integrations or contributing to the codebase.

    Key Risk Areas

    • Security (High Risk): Managed via automated dependency scanning (Dependabot), CodeQL analysis, and SLSA Build Level 3 provenance.
    • Breaking Changes (Medium Risk): Mitigated through a clear deprecation process, migration guides, and an automated migration CLI tool.
    • Framework Compatibility (Medium Risk): Components are Web Component-based (framework-agnostic), with specific adapters provided for major frameworks.
    • Accessibility (Medium Risk): Monitored against WCAG/BITV standards with regular audits.

    Known Technical Debt

    • SSR Support: Server-side rendering is currently limited; while a hydrate adapter exists, declarative Shadow DOM support is a known area for improvement.
    • Theme Support: Non-default themes (except ECL) are not actively maintained.
    • Test Coverage: Some older components may have gaps in E2E or visual regression testing.
    • Migration Tooling: The migration CLI may not cover all breaking changes, occasionally requiring manual intervention.

  9. KoliBri quality and release strategy

    develop

    KoliBri follows a structured release and quality model:

    Release Models

    • LTS (Long-Term Support): 3 years of support for major versions.
    • STS (Short-Term Support): 15 months of support for rapid innovation.
    • Versioning: Strict adherence to Semantic Versioning (SemVer).

    Quality Standards

    • Accessibility: WCAG 2.2 Level AAA compliance, mandatory keyboard navigation, and automated axe-core testing.
    • Security: SLSA Build Level 3 for published packages.
    • Performance: Lazy loading, tree-shakeable exports, and minimal CSS footprint.

  11. Non-goals and future work for Base Styling vs. Theming

    develop

    The Base Styling vs. Theming concept defines the architectural boundaries for where styling logic resides, but it does not implement specific themes itself.

    Key constraints and upcoming enforcement mechanisms:

    • No Dark Theme Implementation: This concept does not implement a Dark Theme; it only defines the location where such implementations should occur.
    • Fallback Preservation: Existing black/white fallbacks in the base layer remain unchanged.
    • Automated Enforcement (Planned): A Stylelint rule kolibri/component-no-color-scheme will be added to packages/tools/stylelint-rules. This rule will prohibit the use of prefers-color-scheme, color-scheme, and light-dark() within packages/components to ensure component neutrality.
    • Visual Regression Testing (Planned): A dark run of the unstyled snapshot check will be integrated into the CI to provide permanent proof of scheme neutrality.

  12. Understand the React Sample App structure

    develop

    The KoliBri React Sample App is organized to demonstrate components, scenarios, and shared logic. Use this structure to locate specific component implementations or utility patterns:

    • src/react.main.tsx: The entry point that bootstraps the React application and configures theming.
    • src/components: Demos of individual KoliBri components, organized by folder.
    • src/scenarios: Demonstrations of how multiple components work together in complex use cases.
    • src/shares: Shared utilities used across the sample app.