npm - @public-ui/mcp - Versions diffs - 4.1.1-rc.1 → 4.1.1-rc.3 - Mend

@public-ui/mcp 4.1.1-rc.1 → 4.1.1-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/package.json +4 -4
package/shared/sample-index.json +227 -11

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@public-ui/mcp",
-  "version": "4.1.1-rc.1",
+  "version": "4.1.1-rc.3",
   "license": "EUPL-1.2",
   "homepage": "https://public-ui.github.io",
   "repository": {
@@ -46,16 +46,16 @@
     "express": "5.2.1",
     "fuse.js": "7.1.0",
     "zod": "4.3.6",
-    "@public-ui/components": "4.1.1-rc.1"
+    "@public-ui/components": "4.1.1-rc.3"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.3",
+    "@eslint/js": "9.39.4",
     "@modelcontextprotocol/inspector": "0.21.1",
     "@types/express": "5.0.6",
     "@types/node": "25.3.5",
     "@typescript-eslint/eslint-plugin": "8.56.1",
     "@typescript-eslint/parser": "8.56.1",
-    "eslint": "9.39.3",
+    "eslint": "9.39.4",
     "eslint-plugin-json": "4.0.1",
     "globals": "17.4.0",
     "knip": "5.85.0",

package/shared/sample-index.json CHANGED Viewed

@@ -1,16 +1,16 @@
 {
   "metadata": {
-    "generatedAt": "2026-03-06T06:18:01.612Z",
+    "generatedAt": "2026-03-07T18:42:18.803Z",
     "buildMode": "ci",
     "counts": {
-      "total": 249,
-      "totalDocs": 22,
+      "total": 276,
+      "totalDocs": 48,
       "totalSpecs": 54,
-      "totalSamples": 155,
+      "totalSamples": 156,
       "totalScenarios": 18
     },
     "repo": {
-      "commit": "d55009e9d7c43d98eb07f703ebef4e90a3af5d38",
+      "commit": "c1f3eede0d10695eec0dffbf54ca07fd32f6979a",
       "branch": "develop",
       "repoUrl": "https://github.com/public-ui/kolibri"
     }
@@ -24,6 +24,214 @@
       "code": "# Agent Instructions\n\nThis repository is a monorepo managed with **pnpm** and **Nx**. It contains multiple packages under `packages/` such as web components, themes, adapters, samples and tooling.\n\n## Handling hints\n\nWe have a monorepo structure with multiple packages, each with its own `package.json`. The root `package.json` contains shared dependencies and scripts. Use `pnpm` commands to manage dependencies and run scripts across packages.\n\n- To install dependencies, use `pnpm i` at the root level. This will install all dependencies for all packages.\n- If you change a dependency in a package:\n  - Use only exact version numbers in `package.json`. Other peers will not be able to use the package if you can use a range version.\n  - You need to run `pnpm i` at the root level. This updates the lockfile and ensures all packages are using the correct versions.\n- Never add a `packageManager` field to any `package.json` file.\n- Avoid that branch name may contain hidden characters.\n- If something does not work, check in the event of an error whether all dependent submodules have been built.\n- To build a single package faster, run commands with downstream dependents using `pnpm --filter ...<package>` (e.g., `pnpm --filter ...@public-ui/sample-react build`).\n\n## 🚨 Format-first rule\n\n> **Stop before you commit:** run the formatter so CI never rejects your patch for style drift.\n\n1. Run `pnpm format` from the repo root whenever you change code, docs or configs.\n2. If you only touched one package, you may instead run `pnpm --filter <package> format` for a quicker pass.\n3. Re-stage the affected files (`git add -u`) so the formatted result is what lands in the commit.\n\nNo package scripts in this repo need extra flags such as `-- --write`; the scripts already know when to write changes versus just check.\n\n## Semantic Versioning\n\nThis repository follows **Semantic Versioning** (SemVer) for all packages. Each package version is defined in its own `package.json` file. The versioning scheme is as follows:\n\n- **Major version**: Incremented for incompatible API changes.\n- **Minor version**: Incremented for adding functionality in a backwards-compatible manner.\n- **Patch version**: Incremented for backwards-compatible bug fixes.\n\nIf we deprecate a feature, we will mark it as deprecated in the code and documentation, but we will not remove it immediately. Instead, we will provide a migration guide (migration\\*.md) for users to transition to the new feature. Also we provide a migration tool in the `packages/tools/kolibri-cli` package to help with the migration process. You have to add a migration task from the previous version to the new version in the `packages/tools/kolibri-cli/src/migrations` folder. In the migration package, are a lot of migration tasks already implemented, so you can use them as a reference.\n\n## Project Structure\n\n- `packages/components` – Stencil based web components\n  - `packages/components/src/component` – components\n  - `packages/components/src/schema` – schema definitions for all components\n- `packages/samples` – sample applications demonstrating usage\n  - `packages/samples/angular` – Angular sample app; do not edit\n  - `packages/samples/react` – React sample app; all samples; write component samples here\n- `packages/adapters/*` – generated framework integration packages; do not edit\n- `packages/themes` – style themes and assets\n  - `packages/themes/default` – primary maintained standard theme\n  - All other themes are not actively maintained\n- `packages/tools/kolibri-cli` – helper CLI for migration\n- Documentation lives in `docs/`.\n- Do always ignore and do not edit all `assets` folders in all packages, as these are generated by the build process and should not be edited manually. If you need to change something in the assets, you have to change it in the source code and rebuild the package.\n\n## Theming\n\nThe theming is realized with adopted style sheets on web components and will be adopted at the mounted hook of the components. All following styling rules are only relevant for the `components` and `themes` packages.\n\n### The 5 styling layers\n\n1. **A11y Preset layer**: This layer comes out of the `adopted-style-sheets` package and contains the basic styles for accessibility. It is applied to all components.\n2. **Basis Global layer**: This layer contains the basis global styles for all components and comes out of the `@public-ui/components` package. It is applied only component specific layout styles without margins and paddings. Generally, the styling works without colors, as the colors should only be set through the custom Theme Layer.\n3. **Basis Component layer**: This layer contains the basis styles for one component and comes out of the `@public-ui/components` package. It is applied only component specific layout styles without margins and paddings. Generally, the styling works without colors, as the colors should only be set through the custom Theme Layer.\n4. **Theme Global layer**: This layer contains the global styles for all components of a theme and comes out of a own theme package, like `@public-ui/theme-default`.\n5. **Theme Component layer**: This layer contains the component specific styles for one component of a theme and comes out of a own theme package, like `@public-ui/theme-default`.\n\n### Global accessibility styles\n\n```css\n/*\n * This file contains all rules for accessibility.\n */\n@layer kol-global {\n\t:host {\n\t\t/*\n\t\t * Minimum size of interactive elements.\n\t\t */\n\t\t--a11y-min-size: #{rem(44)};\n\t\t/*\n\t\t * No element should be used without a background and font color whose contrast ratio has\n\t\t * not been checked. By initially setting the background color to white and the font color\n\t\t * to black, the contrast ratio is ensured and explicit adjustment is forced.\n\t\t */\n\t\tbackground-color: white;\n\t\tcolor: black;\n\t}\n\n\t* {\n\t\t/*\n\t\t * This rule enables the word dividing for all texts. That is important for high zoom levels.\n\t\t */\n\t\thyphens: auto;\n\t\t/*\n\t\t * Verdana is an accessible font that can be used without requiring additional loading time.\n\t\t */\n\t\tfont-family: Verdana;\n\t\t/*\n\t\t * Letter spacing is required for all texts.\n\t\t */\n\t\tletter-spacing: inherit;\n\t\t/*\n\t\t * This rule enables the word dividing for all texts. That is important for high zoom levels.\n\t\t */\n\t\tword-break: break-word;\n\t\t/*\n\t\t * Word spacing is required for all texts.\n\t\t */\n\t\tword-spacing: inherit;\n\t}\n\n\t/*\n\t * All interactive elements should have a minimum size of rem(44).\n\t */\n\t/* input:not([type='checkbox'], [type='radio'], [type='range']), */\n\t/* option, */\n\t/* select, */\n\t/* textarea, */\n\t[role='button'],\n\tbutton:not([role='link']),\n\t.kol-input .input {\n\t\tmin-height: var(--a11y-min-size);\n\t\tmin-width: var(--a11y-min-size);\n\t}\n\n\t/*\n\t * Some interactive elements should not inherit the font-family and font-size.\n\t */\n\ta,\n\tbutton,\n\th1,\n\th2,\n\th3,\n\th4,\n\th5,\n\th6,\n\tinput,\n\toption,\n\tselect,\n\ttextarea {\n\t\t/*\n\t\t * All elements should inherit the font family from his parent element.\n\t\t */\n\t\tfont-family: inherit;\n\t\t/*\n\t\t * All elements should inherit the font size from his parent element.\n\t\t */\n\t\tfont-size: inherit;\n\t}\n}\n\n/**\n * Sometimes we need the semantic element for accessibility reasons,\n * but we don't want to show it.\n *\n * - https://www.a11yproject.com/posts/how-to-hide-content/\n */\n.visually-hidden {\n\tclip: rect(0 0 0 0);\n\tclip-path: inset(50%);\n\theight: 1px;\n\toverflow: hidden;\n\tposition: absolute;\n\twhite-space: nowrap;\n\twidth: 1px;\n}\n```\n\n### Styling rules\n\nThe basis global layer set the default font-size and box-sizing for all components.\n\n```css\n@layer kol-global {\n\t:host {\n\t\tfont-size: rem(16);\n\t\t/*\n\t\t * The max-width is needed to prevent the table from overflowing the\n\t\t * parent node, if the table is wider than the parent node.\n\t\t */\n\t\tmax-width: 100%;\n\t}\n\n\t* {\n\t\t/*\n\t\t * We prefer to box-sizing: border-box for all elements.\n\t\t */\n\t\tbox-sizing: border-box;\n\t}\n  ...\n}\n```\n\n### Custom Theming rules\n\nThe custom theme layer is used to set the colors and other theme specific styles. The custom theme layer should not contain any layout styles, as these are already set in the basis global and component layers.\n\nFor example, generally the font-family is set in the theme global layer, on the `:host` element, so that all components inherit the font-family from the theme. The font-size is set in the basis global layer, so that all components inherit the font-size from the basis global layer. But it is possible to set a other base font-size in the theme global layer, if needed.\n\n```css\n@layer kol-theme-global {\n\t:host {\n\t\t--font-family: var(--kolibri-font-family, Verdana, Arial, Calibri, Helvetica, sans-serif);\n\t\t--font-size: var(--kolibri-font-size, #{rem(16)});\n    ...\n\t}\n\n\t:host {\n\t\tfont-size: var(--font-size);\n\n\t\t* {\n\t\t\tfont-family: var(--font-family);\n\t\t}\n\t}\n  ...\n}\n```\n\nIn the theme component layer, you can set what ever you need to realize your own custom style guidelines. For example, you can set the colors, borders, shadows, etc. for the component.\n\n```css\n@layer kol-theme-component {\n  ...\n}\n```\n\n### CSS Custom Properties and SASS Variables\n\nCSS custom properties remain part of the global cascade and are not isolated by the Shadow DOM.\nOverusing them in theme files can collide with variables defined on a host page.\nExpose only well‑prefixed design tokens as custom properties and rely on SASS variables for\ninternal calculations to keep components robust and avoid unintended style leaks.\n\n### SCSS Architecture Guidelines: BEM with Smart Nesting\n\nWhen writing component theme styles, follow these principles for clean, maintainable SCSS:\n\n#### 1. **Flat BEM Structure (Root Level)**\n\nAll BEM modifiers and independent elements belong at **root level** of the mixin. Never nest BEM class names:\n\n```scss\n@mixin kol-alert-theme {\n\t// ✅ All BEM selectors on root (flat)\n\t.kol-alert { ... }\n\t.kol-alert--variant-msg { ... }\n\t.kol-alert--variant-card { ... }\n\t.kol-alert--type-default { ... }\n\t.kol-alert__container { ... }\n\t.kol-alert__heading { ... }\n}\n```\n\n**Why?** BEM classnames are independent selectors. Each class should be predictable and flat.\n\n#### 2. **Contextual Nesting (When Variants Change Element Behavior)**\n\nNest **only when a modifier changes how a child element behaves**. Keep all rules for an element together:\n\n```scss\n.kol-alert__closer {\n\tplace-self: center;\n\n\t.kol-button {\n\t\tborder-radius: 50%;\n\t\twidth: var(--a11y-min-size);\n\t\theight: var(--a11y-min-size);\n\t\tcursor: pointer;\n\n\t\t// ✅ Variant changes button styling - nest here\n\t\t.kol-alert--variant-msg & {\n\t\t\t--text-color: var(--alert-accent-color);\n\t\t}\n\n\t\t.kol-alert--variant-card & {\n\t\t\t--text-color: var(--color-light);\n\t\t}\n\t}\n}\n```\n\n**Rule of thumb**: All rules for `.kol-button` in `.kol-alert__closer` stay in one place. This keeps related styles together and makes maintenance easier.\n\n#### 3. **Never Use `$root` or `@at-root`**\n\n❌ **Outdated pattern (removed):**\n\n```scss\n.kol-alert {\n\t$root: &;\n\t&__closer {\n\t\t@at-root #{$root}--variant-msg & { ... }\n\t}\n}\n```\n\n✅ **Modern pattern (direct nesting):**\n\n```scss\n.kol-alert__closer {\n\t.kol-button {\n\t\t.kol-alert--variant-msg & { ... }\n\t}\n}\n```\n\nThis is clearer and doesn't require Sass variable gymnastics.\n\n#### 4. **Structure Template**\n\n```scss\n@mixin kol-component-theme {\n\t// 1. Base component (no children)\n\t.kol-component {\n\t\tdisplay: flex;\n\t\twidth: 100%;\n\t}\n\n\t// 2. All BEM modifiers at root (flat)\n\t.kol-component--variant-a {\n\t\t...\n\t}\n\n\t.kol-component--type-default {\n\t\t...\n\t}\n\n\t// 3. Elements with contextual nesting for variants\n\t.kol-component__heading {\n\t\tfont-weight: bold;\n\n\t\t.kol-component--variant-a & {\n\t\t\tcolor: red;\n\t\t}\n\t}\n\n\t.kol-component__content {\n\t\tpadding: 1rem;\n\n\t\t.kol-component--variant-a & {\n\t\t\tbackground: white;\n\t\t}\n\t}\n\n\t// 4. Child components with variant context\n\t.kol-component__button {\n\t\t.kol-button {\n\t\t\tcursor: pointer;\n\n\t\t\t.kol-component--variant-a & {\n\t\t\t\t--text-color: var(--accent);\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### General rules for custom themes\n\n- Do not use `!important` in your styles, as this will override the styles of the basis global and component layers.\n- Do only overwrite styling definitions you will really customize. Do not set styling definitions that are already set (redundant) in the basis global and component layers, as this will override the styles of the basis global and component layers.\n- Do not `inherit` styles over the `:host` element, as this will override the styles of the basis global and component layers. This makes your component less robust from outside environment styles. Only the `kol-icon` inherits some specific styles, like `color`, `font-size`, `font-family` and `line-height`, as these are needed for the icon to be displayed correctly inline to this neighbored elements.\n- Do not set the default `font-family`, `font-size` or `box-sizing` in the basis or theme component layer (redundant), as these are already set in the basis global layers. If you need to set a different font-family or font-size, you can do this in the theme global layer.\n- Do not set `margin` or `padding` in the basis global and component layers. If you need to set a different margin or padding, you can do this in the theme global or component layers.\n- Do not use `overflow: hidden` in styling or theming, as it often causes issues for reuse and should be avoided.\n- **Do not use `@layer` declarations in utility files**: Helper files, mixin files, and partial files (starting with `_`) should not contain `@layer` declarations. These files are utilities and should be layer-agnostic. This is enforced by the custom Stylelint rule `kolibri/no-layer-in-utility-files`.\n- **Never use `$root` variables or `@at-root` in component mixins**: All selectors should be explicit. Use direct child/descendant nesting only when a modifier changes element behavior within a specific context.\n\n## Samples\n\nThe samples are located in `packages/samples/react` and demonstrate how to use the components in react. Each component has its own folder and the basic sample are in `basic.tsx`. Other stories can be added in the same folder. All samples of a component are registered in the `routes.ts` file.\n\n## Coding Conventions\n\n- Formatting is enforced via **Prettier** with settings defined in `prettier.config.js` (print width 160, single quotes, tabs).\n- `.editorconfig` sets `indent_style = tab` and `max_line_length = 160` for code files. Markdown and YAML files use spaces.\n- ESLint and Stylelint are run using `pnpm lint`. Lint rules should **not** be disabled via inline comments. Instead, describe the problem and work towards a clean solution.\n- Lists and enumerations in code should be kept in alphanumeric order. This also applies to import specifiers and union type literals.\n- Do not disable ESLint, Stylelint or TypeScript rules inline. Fix the code instead of turning such rules off.\n- ESLint and Stylelint are run using `pnpm lint`.\n- Lists and enumerations in code should be kept in alphabetical order (see `docs/tutorials/NEW_COMPONENT.md`).\n- Commit messages follow the **Conventional Commits** specification.\n- See also the [Contributing Guide](CONTRIBUTING.md) for more details on coding conventions and best practices.\n- Spell \"KoliBri\" with this casing in all documentation and code. The only exception is the component named KolKolibri.\n- Use ESM import syntax in browser code and scripts whenever supported, instead of `require` imports.\n- Do not create barrel files (e.g. `index.ts` that re-export modules). Import modules directly instead.\n- Do not place constant declarations before import statements; imports must always be at the very top of the file.\n- **Scripts must be platform-independent**: All scripts in the `scripts/` folder must work on Windows, macOS, and Linux without requiring external tools or platform-specific dependencies. Use Node.js built-in modules instead of external command-line tools like `rg`, `grep`, `find`, etc.\n\n## Linting and Formatting\n\n- Run `pnpm lint` to check for linting errors across all packages. This script runs ESLint, Stylelint and TypeScript checks.\n  - ⚠️ **Note**: TypeScript type checking in the lint script can require built artifacts. If you've made source code changes, lint will handle any necessary compilation. Explicit pre-build is typically unnecessary.\n  - You can try to automatically fix linting issues with `pnpm lint:eslint --fix`, but this may not resolve all issues.\n- Run `pnpm format` to format all code files using Prettier. You can try to automatically fix linting issues with `pnpm format -w`, but this may not resolve all issues.\n- If your pull request only modifies Markdown files, skip `pnpm build`, `pnpm lint` and `pnpm test`. Just format the Markdown using `pnpm format` or Prettier.\n\n### Pre-commit checklist\n\n- **Always run `pnpm format` (or `pnpm --filter <package> format` for a single workspace) right before committing.** Formatting failures are one of the most common reasons for blocked quality gates, so make this the last step before `git commit` even for documentation-only changes.\n- **For SCSS changes**: Always run `pnpm lint:stylelint --fix` (or `pnpm --filter <package> lint:stylelint --fix`) to automatically correct formatting, property order, and selector structure rules before committing. This ensures compliance with BEM structure and style consistency.\n- After formatting, re-stage affected files with `git add -u` so the formatted content is what gets committed.\n\n## Testing\n\n- Run `pnpm test` from the repository root to execute all unit and integration tests.\n  - ⚠️ **Note**: Test runners (Vitest, Jest, Playwright, etc.) execute an implicit build automatically before running tests. **Do NOT run a separate `pnpm build` beforehand** — this wastes time. The test scripts handle compilation and type checking internally.\n- Visual and snapshot tests can be updated with `pnpm test:update` or via the `update-snapshots.yml` GitHub workflow (see `CONTRIBUTING.md`).\n- Individual packages provide their own test scripts (e.g. `pnpm --filter @public-ui/components test:unit`).\n  - These also perform implicit builds, so explicit pre-build is unnecessary.\n\n## Pull Request Guidelines\n\n- PR titles should be meaningful as they appear in the release notes.\n- Every PR must link to its issue and contain only changes related to that issue.\n- Ensure automated tests pass and manual testing is completed when required.\n- Update documentation or migration guides if your changes affect them.\n",
       "kind": "doc"
     },
+    {
+      "id": "doc/arc42_de/01-introduction-and-goals",
+      "group": "docs/arc42_de",
+      "name": "01-introduction-and-goals",
+      "path": "docs/arc42_de/01-introduction-and-goals.md",
+      "code": "# 1. Einführung und Ziele\n\nDieser Abschnitt führt Public UI - KoliBri (KoliBri) ein und beschreibt dessen Kernauftrag, Stakeholder und übergeordnete Qualitätsziele. Das Verständnis dieser grundlegenden Elemente liefert den Kontext für alle nachfolgenden Architekturentscheidungen und Designentscheidungen.\n\n## 1.1 Anforderungsübersicht\n\n**Public UI - KoliBri (KoliBri)** ist eine Open-Source-Web-Component-Bibliothek, die HTML standardmäßig barrierefrei, semantisch und valide macht. Sie dient als Referenzimplementierung von Barrierefreiheitsstandards und bleibt dabei flexibel genug für verschiedene organisatorische Anforderungen.\n\n### Hauptanforderungen\n\n- **Barrierefreiheit zuerst**: Sicherstellen, dass alle Komponenten die WCAG 2.2 Level AAA Standards und BITV-Anforderungen erfüllen\n- **Framework-agnostisch**: Nahtlose Zusammenarbeit mit jedem Web-Framework oder Vanilla JavaScript\n- **Multi-Theming**: Unterstützung mehrerer Designsysteme und Corporate Identities\n- **Wiederverwendbarkeit**: Bereitstellung atomarer, flexibler Komponenten, die zu komplexen Schnittstellen komponiert werden können\n- **Standardkonformität**: Strikte Einhaltung der W3C-Webstandards\n- **Langzeitunterstützung**: Bereitstellung von LTS-Versionen für Unternehmensstabilität\n\n## 1.2 Qualitätsziele\n\n| Priorität | Qualitätsziel | Motivation |\n|----------|-------------|------------|\n| 1 | **Barrierefreiheit** | Kernauftrag - jede Komponente muss für alle Nutzer unabhängig von Behinderungen zugänglich sein |\n| 2 | **Standardkonformität** | Aufbau auf W3C-Standards gewährleistet Langlebigkeit und Interoperabilität |\n| 3 | **Benutzbarkeit** | Komponenten sollten für Entwickler und Endnutzer intuitiv sein |\n| 4 | **Wartbarkeit** | Saubere Architektur ermöglicht langfristige Entwicklung und Community-Beiträge |\n| 5 | **Performance** | Schnelles Laden und Rendern für optimale Benutzererfahrung |\n\n### Qualitätsszenarien\n\n1. **Barrierefreiheit**: Ein Screenreader-Nutzer kann ohne visuelle Unterstützung durch alle Komponenten navigieren und mit ihnen interagieren\n2. **Framework-Unabhängigkeit**: Entwickler können KoliBri innerhalb von 15 Minuten in React-, Angular-, Vue- oder Vanilla-JS-Projekte integrieren\n3. **Theming**: Organisationen können ihr Corporate Design auf alle Komponenten anwenden, ohne den Komponentencode zu modifizieren\n4. **Wartbarkeit**: Neue Beitragende können die Architektur verstehen und innerhalb von 2 Tagen ihre erste Komponente beitragen\n\n## 1.3 Stakeholder\n\n| Rolle/Name | Erwartungen | Kontakt |\n|-----------|-------------|---------|\n| **Endnutzer** | Barrierefreie, nutzbare Web-Oberflächen, die mit assistiven Technologien funktionieren | - |\n| **Entwickler** | Einfach zu verwendende, gut dokumentierte Komponenten, die sich in ihren Tech-Stack integrieren | - |\n| **Designer** | Flexibles Theming-System, das ihre Designsysteme unterstützt | - |\n| **ITZBund** | Nachhaltiges Open-Source-Projekt, das die Anforderungen des öffentlichen Sektors erfüllt | kolibri@itzbund.de |\n| **Organisationen des öffentlichen Sektors** | BITV-konforme Komponenten für Behördenwebsites und -anwendungen | - |\n| **Open-Source-Community** | Transparente Entwicklung, Beitragsmöglichkeiten und wiederverwendbare Komponenten | GitHub Issues/PRs |\n| **Barrierefreiheits-Befürworter** | Referenzimplementierung von WCAG-Standards in Web Components | - |\n\n## 1.4 Vision und Mission\n\n### Vision\n> Gemeinsam machen wir **HTML** barrierefrei, indem wir **wiederverwendbare Web-Komponenten** verwenden, um **Benutzbarkeit** und **Barrierefreiheit** zu gewährleisten.\n\n### Mission\nDer HTML-Webstandard ist offen spezifiziert, um langlebig und robust zu sein, aber dies führt oft zu Kompositionen, die nicht einfach barrierefrei, semantisch oder valide sind. KoliBri bietet:\n\n- **Framework-agnostische Komponenten** basierend auf W3C-Webstandards\n- **Generische Referenzimplementierung** von WCAG- und BITV-Standards\n- **Multi-Theming-fähige Präsentationsschicht** ohne technische Kopplung oder Datenübertragung\n- **Wiederverwendbare Lösung** für statische Websites und dynamische Webanwendungen\n- **Open-Source-Fundament** ermöglicht breite Akzeptanz und Community-Zusammenarbeit\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/02-architecture-constraints",
+      "group": "docs/arc42_de",
+      "name": "02-architecture-constraints",
+      "path": "docs/arc42_de/02-architecture-constraints.md",
+      "code": "# 2. Randbedingungen\n\nDieser Abschnitt dokumentiert die technischen, organisatorischen und rechtlichen Grenzen, innerhalb derer Public UI - KoliBri operieren muss. Diese Randbedingungen prägen architektonische Entscheidungen und leiten Implementierungsentscheidungen während des gesamten Projekts.\n\n## 2.1 Technische Randbedingungen\n\n| Randbedingung | Beschreibung | Motivation |\n|-----------|-------------|------------|\n| **Nur Webstandards** | Komponenten dürfen nur Standard-Webtechnologien verwenden (HTML, CSS, JavaScript) | Gewährleistet langfristige Kompatibilität und vermeidet Vendor-Lock-in |\n| **Shadow DOM** | Komponenten verwenden Shadow DOM zur Kapselung | Verhindert Stilkonflikte und ermöglicht echte Komponentenisolierung |\n| **Stencil.js Framework** | Web-Komponenten werden mit Stencil erstellt | Bietet hervorragende Entwicklererfahrung und generiert Framework-Adapter |\n| **TypeScript** | Gesamter Code in TypeScript geschrieben | Typsicherheit verbessert Codequalität und Entwicklererfahrung |\n| **pnpm Monorepo** | Projektstruktur als pnpm/Nx Monorepo | Effizientes Abhängigkeitsmanagement und Build-Orchestrierung |\n| **Node.js 22+** | Mindestens Node.js Version 22 | Nutzt moderne JavaScript-Features und Tooling |\n| **CSS Custom Properties** | Minimale Verwendung von CSS Custom Properties für Theming | Vermeidet globale Cascade-Verschmutzung bei gleichzeitiger Anpassbarkeit |\n| **Adopted Style Sheets** | Styling über Adopted Style Sheets | Ermöglicht effizienten Theme-Wechsel und Style-Komposition |\n\n## 2.2 Organisatorische Randbedingungen\n\n| Randbedingung | Beschreibung | Auswirkung |\n|-----------|-------------|--------|\n| **Open-Source-Lizenz** | EUPL-1.2 (European Union Public License) | Alle Beiträge müssen mit dieser Lizenz kompatibel sein |\n| **Kontext des öffentlichen Sektors** | Entstanden aus ITZBund (deutscher Bundes-IT-Dienstleister) | Muss Anforderungen des öffentlichen Sektors erfüllen (BITV, Beschaffungsregeln) |\n| **Community-getrieben** | Offen für externe Beiträge | Entwicklung priorisiert Community-Bedürfnisse und -Beiträge |\n| **Semantische Versionierung** | Strikte SemVer-Konformität | Breaking Changes nur in Hauptversionen |\n| **LTS/STS Release-Modell** | Langzeitunterstützung (3 Jahre) und Kurzzeitunterstützung (15 Monate) Versionen | Unternehmen benötigen Stabilität, während Innovation fortgesetzt wird |\n\n## 2.3 Konventionen\n\n| Konvention | Beschreibung | Durchsetzung |\n|-----------|-------------|------------|\n| **Code-Stil** | Prettier-Formatierung, 160 Zeichen Zeilenlänge, Tabs | Automatisiert über Pre-Commit-Hooks und CI |\n| **Linting** | ESLint und Stylelint mit strengen Regeln | Keine Inline-Regeldeaktivierung erlaubt |\n| **Commit-Nachrichten** | Conventional Commits Spezifikation | PR-Titel-Validierung in CI |\n| **Dokumentation** | Alle öffentlichen APIs müssen dokumentiert sein | Erforderlich für PR-Genehmigung |\n| **Testing** | Unit-Tests für Logik, E2E-Tests für Komponenten | Erforderlich für PR-Genehmigung |\n| **Alphabetische Sortierung** | Listen, Imports und Enumerationen alphabetisch sortiert | Reduziert Merge-Konflikte |\n| **Komponentenbenennung** | Alle Komponenten mit \"Kol\"-Präfix (z.B. KolButton) | Vermeidet Namenskonflikte |\n\n## 2.4 Qualitätsrandbedingungen\n\n| Randbedingung | Beschreibung | Verifizierung |\n|-----------|-------------|--------------|\n| **WCAG 2.2 AAA Konformität** | Alle Komponenten müssen WCAG 2.2 Level AAA Standards erfüllen | Automatisierte axe-core-Tests + manuelle Überprüfung |\n| **BITV-Konformität** | Komponenten müssen deutsche Barrierefreiheitsanforderungen erfüllen | Manuelle Tests und Zertifizierung |\n| **Browser-Unterstützung** | Moderne Browser mit ES2017+ Unterstützung | Automatisierte Cross-Browser-Tests |\n| **Bundle-Größe** | Einzelne Komponenten klein und tree-shakeable halten | Bundle-Größen-Monitoring in CI |\n| **Kontrastverhältnisse** | Minimum 4,5:1 für normalen Text, 3:1 für großen Text | wcag-contrast-Bibliotheksvalidierung |\n| **Interaktive Elementgröße** | Mindestens 44x44px Touch-Target-Größe | Eingebaut in Komponenten-Styling |\n\n## 2.5 Rechtliche Randbedingungen\n\n| Randbedingung | Beschreibung |\n|-----------|-------------|\n| **Lizenzkompatibilität** | Alle Abhängigkeiten müssen mit EUPL-1.2 kompatibel sein |\n| **Keine proprietären Abhängigkeiten** | Vermeidung von Abhängigkeiten mit proprietären Lizenzen |\n| **Exportkonformität** | Als Open Source, entspricht EU-Exportvorschriften |\n| **Datenschutz** | Keine Erfassung personenbezogener Daten in Komponenten |\n| **Drittanbieter-Lizenzen** | Alle Drittanbieter-Lizenzen dokumentiert und überprüft |\n\n## 2.6 Entwicklungsumgebungs-Randbedingungen\n\n| Randbedingung | Beschreibung |\n|-----------|-------------|\n| **Plattformunabhängigkeit** | Build und Entwicklung müssen auf Windows, macOS und Linux funktionieren |\n| **CI/CD-Plattform** | GitHub Actions für alle Automatisierungen |\n| **Paket-Registry** | npm als primärer Verteilungskanal |\n| **Sicherheits-Scanning** | CodeQL und Abhängigkeits-Scanning erforderlich |\n| **Provenance** | SLSA Build Level 3 für veröffentlichte Pakete |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/03-system-scope-and-context",
+      "group": "docs/arc42_de",
+      "name": "03-system-scope-and-context",
+      "path": "docs/arc42_de/03-system-scope-and-context.md",
+      "code": "# 3. Kontextabgrenzung\n\nDieser Abschnitt definiert die Grenzen von Public UI - KoliBri, indem er identifiziert, was innerhalb und außerhalb des Systems liegt. Er klärt die Beziehungen zu externen Systemen, Nutzern und Abhängigkeiten und bietet sowohl geschäftliche als auch technische Perspektiven auf die Systemumgebung.\n\n## 3.1 Fachlicher Kontext\n\n```mermaid\ngraph TB\n    subgraph External Systems\n        Frameworks[Web Frameworks<br/>React, Angular, Vue, etc.]\n        Browser[Web Browser<br/>Chrome, Firefox, Safari, Edge]\n        Assistive[Assistive Technologien<br/>Screenreader, etc.]\n        CDN[Content Delivery Networks<br/>npm, unpkg, jsDelivr]\n        DesignSystems[Design-Systeme<br/>Corporate Design Guidelines]\n    end\n\n    subgraph KoliBri System\n        Components[Web Components Library]\n        Themes[Theme-Pakete]\n        Adapters[Framework-Adapter]\n        CLI[Migrations-CLI-Tool]\n        Docs[Dokumentations-Website]\n    end\n\n    subgraph Users\n        Developers[Anwendungsentwickler]\n        EndUsers[Endnutzer mit/ohne Behinderungen]\n        Designers[UX/UI-Designer]\n        Contributors[Open-Source-Beitragende]\n    end\n\n    Developers -->|integrieren| Components\n    Developers -->|verwenden| Adapters\n    Developers -->|migrieren mit| CLI\n    Developers -->|lesen| Docs\n\n    Designers -->|anpassen| Themes\n    Designers -->|folgen| DesignSystems\n\n    Contributors -->|tragen bei zu| Components\n    Contributors -->|erstellen| Themes\n\n    Components -->|läuft in| Browser\n    Components -->|verwendet| Themes\n    Components -->|konsumiert von| Frameworks\n\n    Browser -->|rendert| Components\n    Browser -->|bietet API| Assistive\n\n    EndUsers -->|interagieren über| Browser\n    EndUsers -->|verwenden| Assistive\n\n    Components -->|verteilt via| CDN\n    Adapters -->|verteilt via| CDN\n    Themes -->|verteilt via| CDN\n```\n\n### Beschreibung des fachlichen Kontexts\n\n| Partner/Schnittstelle | Eingabe | Ausgabe | Beschreibung |\n|-------------------|-------|--------|-------------|\n| **Anwendungsentwickler** | Integrationsanforderungen, Bug-Reports, Feature-Requests | Web-Komponenten, Framework-Adapter, Dokumentation | Hauptnutzer, die KoliBri in ihre Anwendungen integrieren |\n| **Web-Frameworks** | Framework-APIs und -Konventionen | Framework-spezifische Adapter (React, Angular, Vue, etc.) | KoliBri bietet native Integrationen für beliebte Frameworks |\n| **Web-Browser** | Webstandard-APIs (Custom Elements, Shadow DOM) | Gerenderte barrierefreie Komponenten | KoliBri-Komponenten laufen in modernen Browsern |\n| **Assistive Technologien** | ARIA-Attribute, semantisches HTML | Barrierefreie Benutzeroberfläche | Komponenten stellen korrekte Barrierefreiheitsinformationen bereit |\n| **Design-Systeme** | Design-Tokens, Style-Guides, Markenrichtlinien | Themenbezogene Komponenten | Organisationen wenden ihr Design-System über Themes an |\n| **npm Registry** | Paketverteilungsinfrastruktur | Veröffentlichte npm-Pakete | Primärer Verteilungskanal für Komponenten und Themes |\n| **Endnutzer** | Nutzerinteraktionen (Klick, Tastatur, Touch) | Barrierefreie Nutzererfahrung | Letztliche Nutznießer barrierefreier Komponenten |\n| **Open-Source-Community** | Beiträge, Bug-Reports, Diskussionen | Verbesserte Komponenten, neue Features | Community treibt Evolution und Qualität voran |\n\n## 3.2 Technischer Kontext\n\n```mermaid\ngraph TB\n    subgraph Development Tools\n        Node[Node.js 22+]\n        pnpm[pnpm Package Manager]\n        Nx[Nx Build System]\n        TypeScript[TypeScript Compiler]\n        Stencil[Stencil.js]\n    end\n\n    subgraph Build Artifacts\n        ESM[ES Modules]\n        CJS[CommonJS Modules]\n        Types[TypeScript Definitionen]\n        CustomElements[Custom Elements Bundle]\n        Loader[Lazy Loading Wrapper]\n    end\n\n    subgraph Runtime Environment\n        CustomElementsAPI[Custom Elements API]\n        ShadowDOMAPI[Shadow DOM API]\n        AdoptedStyleSheets[Adopted Style Sheets API]\n        DOMAPI[DOM APIs]\n    end\n\n    subgraph Testing Tools\n        Jest[Jest Unit Tests]\n        Playwright[Playwright E2E Tests]\n        AxeCore[axe-core Barrierefreiheits-Tests]\n    end\n\n    subgraph Quality Tools\n        ESLint[ESLint]\n        Stylelint[Stylelint]\n        Prettier[Prettier]\n        CodeQL[CodeQL Security]\n    end\n\n    Stencil -->|kompiliert| TypeScript\n    Stencil -->|generiert| ESM\n    Stencil -->|generiert| CJS\n    Stencil -->|generiert| Types\n    Stencil -->|generiert| CustomElements\n    Stencil -->|generiert| Loader\n\n    Node -->|führt aus| Stencil\n    pnpm -->|verwaltet| Node\n    Nx -->|orchestriert| pnpm\n\n    CustomElements -->|verwendet| CustomElementsAPI\n    CustomElements -->|verwendet| ShadowDOMAPI\n    CustomElements -->|verwendet| AdoptedStyleSheets\n    CustomElements -->|verwendet| DOMAPI\n```\n\n### Technische Schnittstellen\n\n| Schnittstelle | Technologie | Beschreibung |\n|-----------|------------|-------------|\n| **Komponentendefinition** | Stencil.js, TypeScript | Komponenten werden mit Stencil-Dekoratoren und TypeScript-Klassen definiert |\n| **Komponentenregistrierung** | Custom Elements API | Komponenten registrieren sich als benutzerdefinierte HTML-Elemente |\n| **Style-Kapselung** | Shadow DOM, Adopted Style Sheets | Styles sind über Shadow DOM auf Komponenten beschränkt |\n| **Theme-Anwendung** | CSS, SASS, Adopted Style Sheets | Themes stellen CSS bereit, das als Adopted Style Sheets geladen wird |\n| **Framework-Integration** | Framework-spezifische Adapter | Generierte Adapter umhüllen Komponenten für React, Angular, Vue, etc. |\n| **Build-System** | pnpm, Nx, Rollup (über Stencil) | Monorepo-Build orchestriert von pnpm und Nx |\n| **Modulformate** | ES Modules, CommonJS | Komponenten in mehreren Modulformaten verteilt |\n| **Typdefinitionen** | TypeScript .d.ts-Dateien | Vollständige TypeScript-Unterstützung für Entwickler |\n| **Testing** | Jest, Playwright, axe-core | Unit-Tests, E2E-Tests und Barrierefreiheitsvalidierung |\n| **Paketverteilung** | npm-Registry | Komponenten als npm-Pakete veröffentlicht |\n\n### Kommunikationskanäle\n\n| Kanal | Technologie | Zweck |\n|---------|------------|---------|\n| **Komponenten-Props** | JavaScript/TypeScript-Objekte | Konfiguration und Datenübergabe |\n| **Komponenten-Events** | CustomEvent API | Komponenten-zu-Anwendungs-Kommunikation |\n| **CSS Custom Properties** | CSS-Variablen (begrenzt) | Theme-Anpassungspunkte |\n| **Slots** | Shadow DOM Slots | Inhaltsprojektion in Komponenten |\n| **CSS Parts** | ::part() Pseudo-Element | Externes Styling von Komponenten-Interna (begrenzte Nutzung) |\n| **ARIA-Attribute** | HTML-Attribute | Barrierefreiheitsinformationen für assistive Technologien |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/04-solution-strategy",
+      "group": "docs/arc42_de",
+      "name": "04-solution-strategy",
+      "path": "docs/arc42_de/04-solution-strategy.md",
+      "code": "# 4. Lösungsstrategie\n\nDieser Abschnitt präsentiert den grundlegenden Ansatz und die wichtigsten Entscheidungen, die die Architektur von Public UI - KoliBri prägen. Er beschreibt die gewählten Technologien, Architekturmuster und Strategien zur Erreichung der Qualitätsziele des Projekts bei gleichzeitiger Erfüllung der Kernanforderungen.\n\n## 4.1 Technologieentscheidungen\n\n| Entscheidung | Begründung | Konsequenzen |\n|----------|-----------|--------------|\n| **Web Components** | Framework-agnostisch, standardbasiert, native Browser-Unterstützung | Funktioniert mit jedem Framework, langfristige Stabilität, benötigt aber Polyfills für ältere Browser |\n| **Stencil.js** | Bester Web-Component-Compiler, generiert Framework-Adapter, exzellente DX | Bindet Build-Prozess an Stencil, bietet aber enormen Mehrwert bei der Codegenerierung |\n| **Shadow DOM** | Echte Style-Kapselung, verhindert CSS-Konflikte | Komponenten sind isoliert, können aber nicht von außen gestylt werden (by Design) |\n| **TypeScript** | Typsicherheit, bessere IDE-Unterstützung, erkennt Fehler früh | Erfordert Kompilierungsschritt, verbessert aber die Codequalität dramatisch |\n| **pnpm Workspace** | Effizientes Abhängigkeitsmanagement, schnelle Installationen, strikte Abhängigkeiten | Komplexeres Setup als npm, aber besser für Monorepos |\n| **Adopted Style Sheets** | Effizienter Theme-Wechsel, Style-Komposition | Erfordert moderne Browser-Unterstützung, ermöglicht aber mächtiges Theming |\n| **SASS** | Variablen, Mixins, mächtige Theme-Erstellung | Kompilierung erforderlich, bietet aber essenzielle Features für komplexe Themes |\n\n## 4.2 Top-Level-Zerlegung\n\nKoliBri ist als Monorepo mit klarer Trennung der Verantwortlichkeiten strukturiert:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    KoliBri-System                        │\n├─────────────────────────────────────────────────────────┤\n│                                                           │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │\n│  │  Komponenten│  │   Themes    │  │   Adapter   │     │\n│  │   (Kern)    │  │  (Styling)  │  │ (Framework) │     │\n│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │\n│         │                 │                 │             │\n│         └─────────────────┴─────────────────┘            │\n│                           │                               │\n│  ┌─────────────┐  ┌──────┴──────┐  ┌─────────────┐     │\n│  │   Samples   │  │    Tools    │  │     Docs    │     │\n│  │ (Beispiele) │  │  (Tooling)  │  │  (Wissen)   │     │\n│  └─────────────┘  └─────────────┘  └─────────────┘     │\n│                                                           │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Komponenten-Schichten\n\n1. **Kern-Komponenten** (`packages/components/`)\n   - Atomare Web-Komponenten\n   - Geschäftslogik und Barrierefreiheit\n   - Framework-agnostische Implementierung\n\n2. **Themes** (`packages/themes/`)\n   - Visuelle Gestaltung getrennt von Logik\n   - Mehrere Themes für verschiedene Design-Systeme\n   - CSS/SASS mit strikten Scoping-Regeln\n\n3. **Framework-Adapter** (`packages/adapters/`)\n   - Auto-generierte Wrapper für React, Angular, Vue, etc.\n   - Framework-spezifische APIs und Muster\n   - Generiert von Stencil Output Targets\n\n4. **Samples** (`packages/samples/`)\n   - Beispiel-Implementierungen\n   - Testumgebung für neue Features\n   - Dokumentation durch funktionierenden Code\n\n5. **Tools** (`packages/tools/`)\n   - Migrations-CLI für Versions-Upgrades\n   - Visual Regression Testing\n   - Entwicklungsdienstprogramme\n\n## 4.3 Architekturmuster\n\n### Muster: Komposition über Vererbung\n\n- Komponenten sind atomar und komponierbar\n- Komplexe UI durch Kombination einfacher Komponenten aufgebaut\n- Keine Vererbungshierarchien, flache Komponentenstruktur\n\n### Muster: Trennung der Verantwortlichkeiten\n\n- **Struktur/Logik**: Stencil-Komponenten (TypeScript)\n- **Styling**: Theme-Pakete (SASS/CSS)\n- **Integration**: Framework-Adapter (generiert)\n- **Dokumentation**: Separate Dokumentations-Website\n\n### Muster: Fünf-Schichten-Styling-System\n\n1. **A11y-Preset-Schicht**: Barrierefreiheits-Baseline von `adopted-style-sheets`\n2. **Basis Global-Schicht**: Globales Komponenten-Layout (keine Farben/Abstände)\n3. **Basis Komponenten-Schicht**: Komponenten-spezifisches Layout (keine Farben/Abstände)\n4. **Theme Global-Schicht**: Globale Theme-Styles (Farben, Schriften)\n5. **Theme Komponenten-Schicht**: Komponenten-spezifische Theme-Styles\n\nDiese Schichtung gewährleistet:\n\n- Barrierefreiheit standardmäßig\n- Themebar ohne Layout-Bruch\n- Klare Trennung von Struktur und Erscheinung\n\n### Muster: Keine Runtime-Abhängigkeiten\n\n- Komponenten haben minimale Runtime-Abhängigkeiten\n- Keine schweren Framework-Anforderungen\n- Optimiert für Bundle-Größe und Performance\n\n## 4.4 Qualitätsstrategie\n\n### Barrierefreiheit zuerst\n\n- Jede Komponente implementiert WCAG 2.2 Level AAA Standards\n- Tastaturnavigation obligatorisch für alle interaktiven Elemente\n- Screenreader-Tests für alle interaktiven Komponenten\n- Automatisierte axe-core-Tests in CI\n- Manuelle Barrierefreiheitsüberprüfungen und Compliance-Verifizierung\n\n### Standardkonformität\n\n- Strikte Einhaltung der W3C-Spezifikationen\n- Valides HTML, semantisches Markup\n- Korrekter Einsatz von ARIA-Attributen\n- Progressive Enhancement-Prinzipien\n\n### Performance\n\n- Lazy Loading von Komponenten\n- Tree-shakeable Exports\n- Minimaler CSS-Footprint\n- Shadow DOM für effizientes Rendering\n- Bundle-Größen-Monitoring\n\n### Entwicklererfahrung\n\n- Umfassende TypeScript-Typen\n- Klare, durchsuchbare Dokumentation\n- Funktionierende Code-Beispiele\n- Migrations-Tools für Versions-Upgrades\n- Framework-spezifische Integrationen\n\n## 4.5 Organisationsstrategie\n\n### Open Source zuerst\n\n- Öffentliche Entwicklung auf GitHub\n- Community-Beiträge willkommen\n- Transparente Roadmap und Entscheidungsfindung\n- Klare Beitrags-Richtlinien\n\n### LTS/STS Release-Modell\n\n- **LTS (Long-Term Support)**: 3 Jahre Support, Hauptversionen\n- **STS (Short-Term Support)**: 15 Monate Support, schnelle Innovation\n- Semantische Versionierung strikt befolgt\n- Migrations-Leitfäden für alle Breaking Changes\n\n### Quality Gates\n\n- Automatisierte Tests (Unit, E2E, Barrierefreiheit)\n- Code-Review erforderlich für alle Änderungen\n- Linting und Formatierung durchgesetzt\n- Sicherheits-Scanning (CodeQL, Abhängigkeiten)\n- SLSA Build Level 3 für veröffentlichte Pakete\n\n## 4.6 Theming-Strategie\n\n### Multi-Theming-Architektur\n\nThemes sind separate Pakete, die zur Laufzeit gewechselt werden können:\n\n```typescript\nimport { register } from '@public-ui/components';\nimport { DEFAULT } from '@public-ui/theme-default';\n\n// Komponenten mit einem Theme registrieren\nregister(DEFAULT, defineCustomElements);\n```\n\n### Theme-Struktur\n\n- Themes enthalten nur CSS/SASS (keine Logik)\n- Verwenden CSS-Schichten zur Steuerung der Spezifität\n- Minimale CSS Custom Properties zur Vermeidung von Konflikten\n- SASS-Variablen für interne Berechnungen\n- Assets (Schriften, Icons) in Theme-Paketen enthalten\n\n### Vorteile\n\n- Organisationen können benutzerdefinierte Themes ohne Forking erstellen\n- Mehrere Themes können in einer Anwendung koexistieren\n- Theme-Updates erfordern keine Komponenten-Rebuilds\n- Flexibilität des Design-Systems\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/05-building-block-view",
+      "group": "docs/arc42_de",
+      "name": "05-building-block-view",
+      "path": "docs/arc42_de/05-building-block-view.md",
+      "code": "# 5. Bausteinsicht\n\nDieser Abschnitt zerlegt Public UI - KoliBri in seine wichtigsten strukturellen Elemente und zeigt, wie Pakete, Komponenten und Module organisiert sind und wie sie interagieren. Er bietet zunehmend detailliertere Ansichten der statischen Struktur des Systems, von High-Level-Paketen bis hinunter zur individuellen Komponentenorganisation.\n\n## 5.1 Whitebox Gesamtsystem\n\n```mermaid\ngraph TB\n    subgraph KoliBri System\n        Components[Components-Paket<br/>Kern-Web-Komponenten]\n        Themes[Themes-Paket<br/>Visuelle Gestaltung]\n        Adapters[Adapters-Paket<br/>Framework-Wrapper]\n        Tools[Tools-Paket<br/>Entwicklungsdienstprogramme]\n        Samples[Samples-Paket<br/>Beispielanwendungen]\n        Icons[Icons-Paket<br/>Icon-Definitionen]\n    end\n\n    Components -->|gestylt von| Themes\n    Components -->|generiert| Adapters\n    Components -->|demonstriert in| Samples\n    Components -->|verwendet| Icons\n\n    Adapters -->|verwendet in| Samples\n    Themes -->|verwendet in| Samples\n\n    Tools -->|migriert| Components\n    Tools -->|testet| Themes\n```\n\n### Enthaltene Bausteine\n\n| Baustein | Verantwortlichkeit |\n|----------------|----------------|\n| **Components** | Kern-Web-Component-Bibliothek, stellt atomare, barrierefreie HTML-Komponenten bereit |\n| **Themes** | Visuelle Styling-Pakete, trennen Präsentation von Logik |\n| **Adapters** | Framework-spezifische Wrapper (React, Angular, Vue, etc.) für native Integration |\n| **Tools** | Entwicklungs- und Migrations-Utilities (CLI, Visual Testing) |\n| **Samples** | Beispielanwendungen, die die Komponentennutzung demonstrieren |\n| **Icons** | Icon-Font-Definitionen und Assets |\n\n### Wichtige Schnittstellen\n\n| Schnittstelle | Beschreibung |\n|-----------|-------------|\n| `@public-ui/components` | Hauptexport der Komponentenbibliothek |\n| `@public-ui/theme-*` | Theme-Pakete (default, ecl, etc.) |\n| `@public-ui/react`, `@public-ui/angular-*`, `@public-ui/vue` | Framework-Adapter |\n| Theme-Registrierungs-API | `register(theme, defineCustomElements)` |\n\n## 5.2 Components-Paket (Ebene 2)\n\n```mermaid\ngraph TB\n    subgraph Components Package\n        ComponentDefs[Komponentendefinitionen<br/>TypeScript/Stencil]\n        Schema[Schema-Definitionen<br/>Typdefinitionen]\n        Styles[Basis-Styles<br/>Layout CSS/SASS]\n        Assets[Assets<br/>Generierte Dateien]\n        OutputTargets[Output Targets<br/>Adapter-Generierung]\n\n        ComponentDefs -->|verwendet| Schema\n        ComponentDefs -->|gestylt von| Styles\n        ComponentDefs -->|generiert| Assets\n        ComponentDefs -->|kompiliert via| OutputTargets\n    end\n\n    subgraph Core Concepts\n        A11y[Barrierefreiheits-Schicht]\n        Composition[Kompositionslogik]\n        Events[Event-System]\n        Props[Property-API]\n    end\n\n    ComponentDefs -->|implementiert| A11y\n    ComponentDefs -->|verwendet| Composition\n    ComponentDefs -->|emittiert| Events\n    ComponentDefs -->|exponiert| Props\n```\n\n### Komponentenstruktur\n\nJede Komponente besteht aus:\n\n1. **Komponentenklasse** (`.tsx`-Datei)\n   - Stencil-Komponenten-Dekorator\n   - Property-Definitionen mit Validatoren\n   - Lifecycle-Methoden\n   - Render-Methode (JSX)\n\n2. **Schema-Definition** (`schema/`-Ordner)\n   - TypeScript-Interfaces für Props\n   - Typdefinitionen für internen State\n   - Validierungs-Schemas\n\n3. **Basis-Styles** (`.scss`-Dateien)\n   - Nur Layout-Styles (keine Farben)\n   - Barrierefreiheits-Konformität (Min-Größen, Fokus-Styles)\n   - Responsives Verhalten\n\n4. **Tests**\n   - Unit-Tests (Jest)\n   - E2E-Tests (Playwright)\n   - Barrierefreiheits-Tests (axe-core)\n\n### Komponentenkategorien\n\n```\ncomponents/\n├── @deprecated/        # Veraltete Komponenten (für Kompatibilität gepflegt)\n├── @else/             # Utility-Komponenten\n├── @shared/           # Geteilte Utilities und Mixins\n├── abbr/              # Abkürzungs-Komponente\n├── accordion/         # Akkordeon/ausklappbare Abschnitte\n├── alert/             # Alarm-/Benachrichtigungsmeldungen\n├── avatar/            # Benutzer-Avatar-Anzeige\n├── badge/             # Badge-/Label-Komponente\n├── breadcrumb/        # Breadcrumb-Navigation\n├── button/            # Button-Komponente\n├── button-link/       # Button als Link gestylt\n├── card/              # Card-Container\n├── combobox/          # Combo-Box/Autocomplete\n└── ...               # 50+ weitere Komponenten\n```\n\n### Schlüsselkomponenten\n\n| Komponente | Zweck | Komplexität |\n|-----------|---------|------------|\n| `KolButton` | Barrierefreier Button mit Icon- und Label-Unterstützung | Mittel |\n| `KolInputText` | Texteingabe mit Validierung und Fehlerbehandlung | Hoch |\n| `KolTable` | Barrierefreie Datentabelle mit Sortierung und Paginierung | Hoch |\n| `KolModal` | Barrierefreier Modal-Dialog mit Fokus-Management | Hoch |\n| `KolIcon` | Icon-Anzeige aus Icon-Fonts | Niedrig |\n| `KolLink` | Barrierefreier Link mit Icon-Unterstützung | Niedrig |\n\n## 5.3 Themes-Paket (Ebene 2)\n\n```mermaid\ngraph TB\n    subgraph Themes Package\n        DefaultTheme[Default Theme<br/>Haupt-Theme]\n        ECLTheme[ECL Theme<br/>EU-Kommission]\n        ThemeAssets[Theme-Assets<br/>Schriften, Icons]\n\n        subgraph Theme Structure\n            GlobalStyles[Globale Theme-Styles]\n            ComponentStyles[Komponenten-Theme-Styles]\n            Tokens[Design-Tokens]\n            Variables[SASS-Variablen]\n        end\n\n        DefaultTheme -->|enthält| GlobalStyles\n        DefaultTheme -->|enthält| ComponentStyles\n        DefaultTheme -->|verwendet| Tokens\n        DefaultTheme -->|verwendet| Variables\n        DefaultTheme -->|beinhaltet| ThemeAssets\n\n        ECLTheme -->|enthält| GlobalStyles\n        ECLTheme -->|enthält| ComponentStyles\n        ECLTheme -->|verwendet| Tokens\n        ECLTheme -->|verwendet| Variables\n        ECLTheme -->|beinhaltet| ThemeAssets\n    end\n```\n\n### Theme-Paketstruktur\n\n```\nthemes/\n├── default/                   # Standard-KoliBri-Theme (primär)\n│   ├── src/\n│   │   ├── global.scss       # Globale Theme-Styles (Schicht 4)\n│   │   ├── components/       # Komponenten-spezifische Styles (Schicht 5)\n│   │   └── _variables.scss   # SASS-Variablen und Tokens\n│   └── assets/               # Schriften, Icons (kopiert von components)\n├── ecl/                      # European Commission Library Theme\n├── assets/                   # Geteilte Theme-Assets\n│   ├── material-icons/       # Material Icons Font\n│   └── material-symbols/     # Material Symbols Font\n└── package.json              # Workspace-Paket\n```\n\n### Theme-Styling-Schichten\n\n1. **Schicht 1: A11y-Preset** (von `adopted-style-sheets`)\n   - Basis-Barrierefreiheits-Styles\n   - Mindestgrößen, Fokus-Indikatoren\n   - Semantische Defaults\n\n2. **Schicht 2: Basis Global** (von `components`)\n   - Globale Layout-Defaults\n   - Box-sizing, Font-Size-Baseline\n   - Keine Farben oder Abstände\n\n3. **Schicht 3: Basis Komponente** (von `components`)\n   - Komponenten-spezifisches Layout\n   - Nur strukturelles CSS\n   - Keine Farben oder Abstände\n\n4. **Schicht 4: Theme Global** (von `themes`)\n   - Farben, Schriften, Abstände\n   - Design-Tokens\n   - Marken-spezifische Globals\n\n5. **Schicht 5: Theme Komponente** (von `themes`)\n   - Komponenten-spezifisches Theming\n   - Farben, Rahmen, Schatten\n   - Vollständiges visuelles Design\n\n## 5.4 Adapters-Paket (Ebene 2)\n\n```mermaid\ngraph TB\n    subgraph Adapters Package\n        React[React Adapter]\n        ReactV19[React v19 Adapter]\n        ReactStandalone[React Standalone]\n        Angular19[Angular v19]\n        Angular20[Angular v20]\n        Angular21[Angular v21]\n        Vue[Vue Adapter]\n        Solid[Solid Adapter]\n        Svelte[Svelte Adapter]\n        Vaadin[Vaadin Adapter]\n        Hydrate[Hydrate/SSR]\n    end\n\n    subgraph Stencil Output Targets\n        ReactOutput[React Output Target]\n        AngularOutput[Angular Output Target]\n        VueOutput[Vue Output Target]\n        SolidOutput[Solid Output Target]\n        SvelteOutput[Svelte Output Target]\n    end\n\n    ReactOutput -->|generiert| React\n    ReactOutput -->|generiert| ReactV19\n    ReactOutput -->|generiert| ReactStandalone\n    AngularOutput -->|generiert| Angular19\n    AngularOutput -->|generiert| Angular20\n    AngularOutput -->|generiert| Angular21\n    VueOutput -->|generiert| Vue\n    SolidOutput -->|generiert| Solid\n    SvelteOutput -->|generiert| Svelte\n```\n\n### Adapter-Generierung\n\nAlle Adapter werden **automatisch generiert** von Stencil Output Targets. Manuelle Bearbeitung ist verboten.\n\n**Generierungsprozess:**\n\n1. Komponente definiert in `packages/components/src/components/`\n2. Stencil baut Komponente\n3. Output Targets generieren Framework-spezifische Wrapper\n4. Adapter platziert in `packages/adapters/{framework}/`\n5. Jeder Adapter erhält eigenes npm-Paket\n\n### Framework-Unterstützung\n\n| Framework | Paket(e) | Zweck |\n|-----------|-----------|---------|\n| **React** | `@public-ui/react`, `@public-ui/react-v19`, `@public-ui/react-standalone` | React 18, 19 und Standalone-Builds |\n| **Angular** | `@public-ui/angular-v19`, `@public-ui/angular-v20`, `@public-ui/angular-v21` | Angular-Versionen 19, 20, 21 |\n| **Vue** | `@public-ui/vue` | Vue.js-Integration |\n| **Solid** | `@public-ui/solid` | SolidJS-Integration |\n| **Svelte** | `@public-ui/svelte` | Svelte-Integration |\n| **Preact** | `@public-ui/preact` | Preact-Integration |\n| **Vaadin** | `@public-ui/vaadin` | Vaadin Flow (Java) Integration |\n\n## 5.5 Tools-Paket (Ebene 2)\n\n```mermaid\ngraph TB\n    subgraph Tools Package\n        CLI[KoliBri CLI<br/>Migrations-Tool]\n        VisualTests[Visual Tests<br/>Regressions-Testing]\n        MCP[MCP Server<br/>Model Context Protocol]\n    end\n\n    CLI -->|migriert| Components\n    VisualTests -->|testet| Themes\n    MCP -->|bietet Kontext| AITools\n```\n\n### Tool-Komponenten\n\n1. **KoliBri CLI** (`packages/tools/kolibri-cli/`)\n   - Komponentenmigration zwischen Versionen\n   - Projektanalyse und Abhängigkeitsprüfungen\n   - Automatisierte Code-Transformationen\n   - Migrations-Test-Framework\n\n2. **Visual Tests** (`packages/tools/visual-tests/`)\n   - Visuelle Regressionstests für Themes\n   - Screenshot-Vergleich\n   - Snapshot-Management\n   - Theme-Validierung\n\n3. **MCP Server** (`packages/tools/mcp/`)\n   - Model Context Protocol Server\n   - Stellt Repository-Kontext für AI-Tools bereit\n   - Hilft bei Codegenerierung und Review\n\n## 5.6 Wichtige Schnittstellen und Abhängigkeiten\n\n### Externe Abhängigkeiten\n\n| Paket | Zweck | Verwendet von |\n|---------|---------|---------|\n| `@stencil/core` | Web-Component-Compiler | Components |\n| `adopted-style-sheets` | Style-Sheet-Adoptions-Polyfill | Components, Themes |\n| `@floating-ui/dom` | Positionierungs-Engine | Components (Tooltips, Dropdowns) |\n| `markdown-it` | Markdown-Rendering | Components (Rich Text) |\n| `wcag-contrast` | Kontrastverhältnis-Validierung | Components (Farbvalidierung) |\n\n### Interne Abhängigkeiten\n\n```\nComponents → Icons\nComponents → Adapters (generiert)\nSamples → Components\nSamples → Adapters\nSamples → Themes\nTools (CLI) → Components (für Migration)\nTools (Visual Tests) → Themes\n```\n\n### Build-Reihenfolge\n\n1. **Icons** - Zuerst gebaut, keine Abhängigkeiten\n2. **Components** - Hängt von Icons ab, generiert Adapters\n3. **Themes** - Unabhängig, kann parallel gebaut werden\n4. **Adapters** - Generiert durch Components-Build\n5. **Samples** - Hängt von Components, Themes, Adapters ab\n6. **Tools** - Meist unabhängig\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/06-runtime-view",
+      "group": "docs/arc42_de",
+      "name": "06-runtime-view",
+      "path": "docs/arc42_de/06-runtime-view.md",
+      "code": "# 6. Laufzeitsicht\n\nDieser Abschnitt veranschaulicht das dynamische Verhalten von Public UI - KoliBri durch wichtige Laufzeitszenarien. Mithilfe von Sequenzdiagrammen und detaillierten Beschreibungen zeigt er, wie Komponenten während gängiger Operationen wie Initialisierung, Rendering, Event-Handling und Theme-Wechsel interagieren.\n\n## 6.1 Komponentenregistrierung und Initialisierung\n\nDer Komponentenregistrierungsprozess bildet die Grundlage für alle KoliBri-Komponenten in einer Anwendung. Dieser kritische Initialisierungsschritt muss erfolgen, bevor Komponenten gerendert werden.\n\n```mermaid\nsequenceDiagram\n    participant App as Anwendung\n    participant Register as Registrierungs-API\n    participant Theme as Theme-Paket\n    participant Loader as Component Loader\n    participant Browser as Browser\n    participant Component as Web Component\n\n    App->>Register: register(theme, defineCustomElements)\n    Register->>Theme: Lade Theme-Stylesheets\n    Theme-->>Register: Adopted Style Sheets\n    Register->>Loader: defineCustomElements(window)\n    Loader->>Browser: Definiere Custom Elements\n    Browser-->>Loader: Custom Elements registriert\n    Loader-->>Register: Registrierung abgeschlossen\n    Register-->>App: Komponenten bereit\n\n    Note over Browser,Component: Nutzer fügt Komponente zum DOM hinzu\n\n    Browser->>Component: connectedCallback()\n    Component->>Component: Wende Adopted Style Sheets an\n    Component->>Component: Initialisiere Shadow DOM\n    Component->>Component: Rendere Komponente\n    Component-->>Browser: Komponente bereit\n```\n\n### Szenario: Anwendungsstart\n\n**Voraussetzungen:**\n\n- Anwendung hat `@public-ui/components` und ein Theme-Paket installiert\n- Anwendung importiert Registrierungsfunktion\n\n**Schritte:**\n\n1. Anwendung importiert Theme und Registrierungsfunktion:\n\n   ```typescript\n   import { register } from '@public-ui/components';\n   import { defineCustomElements } from '@public-ui/components/loader';\n   import { DEFAULT } from '@public-ui/theme-default';\n   ```\n\n2. Anwendung ruft `register()` mit Theme und Loader auf:\n\n   ```typescript\n   register(DEFAULT, defineCustomElements);\n   ```\n\n3. Registrierungsfunktion:\n   - Lädt Theme-Stylesheets\n   - Ruft `defineCustomElements()` auf, um alle Komponenten zu registrieren\n   - Komponenten werden als Custom Elements im Browser definiert\n\n4. Komponenten sind nun als HTML-Tags verfügbar (z.B. `<kol-button>`)\n\n## 6.2 Komponenten-Rendering\n\n```mermaid\nsequenceDiagram\n    participant User as Nutzer/Framework\n    participant Browser as Browser DOM\n    participant Component as KolComponent\n    participant Shadow as Shadow DOM\n    participant Theme as Adopted Styles\n    participant Props as Component Props\n\n    User->>Browser: Füge <kol-component> zum DOM hinzu\n    Browser->>Component: connectedCallback()\n    Component->>Shadow: attachShadow({mode: 'open'})\n    Shadow-->>Component: Shadow Root erstellt\n\n    Component->>Theme: adoptStyleSheets()\n    Theme-->>Component: Styles angewendet\n\n    Component->>Props: Initialisiere Props mit Defaults\n    Props-->>Component: Props bereit\n\n    Component->>Component: componentWillLoad()\n    Component->>Component: render()\n    Component->>Shadow: Aktualisiere Shadow DOM mit JSX\n    Shadow-->>Browser: Komponente gerendert\n\n    User->>Component: Aktualisiere Prop-Wert\n    Component->>Props: Validiere neuen Wert\n    Props-->>Component: Validierung bestanden\n    Component->>Component: componentWillRender()\n    Component->>Component: render()\n    Component->>Shadow: Aktualisiere Shadow DOM\n    Shadow-->>Browser: Komponente neu gerendert\n```\n\n### Szenario: Komponenten-Lebenszyklus\n\n**Wenn eine Komponente zum DOM hinzugefügt wird:**\n\n1. **connectedCallback()** - Browser benachrichtigt Komponente über DOM-Einfügung\n2. **attachShadow()** - Komponente erstellt Shadow DOM zur Kapselung\n3. **adoptStyleSheets()** - Theme-Styles über Adopted Style Sheets angewendet\n4. **componentWillLoad()** - Komponenten-Initialisierungslogik läuft\n5. **render()** - Komponente rendert JSX ins Shadow DOM\n6. **componentDidLoad()** - Nachbereitungssetup (Event-Listener, etc.)\n\n**Wenn sich eine Komponenten-Prop ändert:**\n\n1. Property-Setter validiert neuen Wert\n2. **componentWillRender()** - Pre-Render-Hook\n3. **render()** - Komponente rendert neu mit neuen Daten\n4. **componentDidRender()** - Post-Render-Hook\n5. Shadow DOM aktualisiert effizient (Virtual DOM Diffing)\n\n## 6.3 Event-Handling und Kommunikation\n\n```mermaid\nsequenceDiagram\n    participant User as Nutzer\n    participant Component as KolButton\n    participant EventSystem as Event-System\n    participant App as Anwendung\n    participant Framework as Framework-Adapter\n\n    User->>Component: Klicke Button\n    Component->>Component: handleClick()\n    Component->>EventSystem: Emittiere CustomEvent('click')\n    EventSystem->>Framework: Fange Event ab\n    Framework->>App: Rufe onClick-Handler auf\n    App->>App: Führe Geschäftslogik aus\n\n    opt Aktualisiere Komponente\n        App->>Component: Aktualisiere Props\n        Component->>Component: Neu rendern\n    end\n\n    Component-->>User: Visuelles Feedback (Ripple, Fokus)\n```\n\n### Szenario: Button-Klick\n\n**Schritte:**\n\n1. Nutzer klickt Button-Element\n2. Button's interner Klick-Handler wird ausgelöst\n3. Komponente validiert Klick (nicht deaktiviert, etc.)\n4. Komponente emittiert CustomEvent mit Typ-Information\n5. Framework-Adapter (falls verwendet) fängt Event ab und ruft React/Angular/Vue-Handler auf\n6. Anwendung führt Geschäftslogik aus\n7. Anwendung kann Komponenten-Props aktualisieren, was Neu-Rendering auslöst\n\n**Event-Typen:**\n\n- Standard-HTML-Events (click, focus, blur, etc.)\n- Benutzerdefinierte Komponenten-Events (change, close, select, etc.)\n- Events durchlaufen Shadow DOM-Grenze (composed: true)\n\n## 6.4 Theme-Wechsel\n\n```mermaid\nsequenceDiagram\n    participant App as Anwendung\n    participant Manager as Theme-Manager\n    participant Components as Alle Komponenten\n    participant Styles as Style Sheets\n    participant Browser as Browser\n\n    App->>Manager: switchTheme(newTheme)\n    Manager->>Styles: Lade neues Theme-CSS\n    Styles-->>Manager: Theme-CSS geladen\n\n    loop Für jede Komponente\n        Manager->>Components: Aktualisiere Adopted Style Sheets\n        Components->>Browser: Ersetze Style Sheets\n        Browser->>Browser: Neu rendern mit neuen Styles\n        Browser-->>Components: Styles angewendet\n    end\n\n    Manager-->>App: Theme-Wechsel abgeschlossen\n```\n\n### Szenario: Runtime-Theme-Änderung\n\n**Voraussetzungen:**\n\n- Mehrere Theme-Pakete installiert\n- Komponenten bereits registriert\n\n**Schritte:**\n\n1. Anwendung lädt neues Theme-Paket\n2. Theme-Manager sammelt neue Style Sheets\n3. Für jede Komponenteninstanz im DOM:\n   - Ersetze Adopted Style Sheets mit neuem Theme\n   - Browser rendert automatisch mit neuen Styles neu\n4. Visuelles Erscheinungsbild ändert sich ohne Komponenten-Reinitialisierung\n\n**Vorteile:**\n\n- Kein Komponenten-Remounting erforderlich\n- Sofortige visuelle Updates\n- Erhält Komponenten-State\n- Effizient - nur Styles ändern sich, nicht DOM-Struktur\n\n## 6.5 Formular-Validierung\n\n```mermaid\nsequenceDiagram\n    participant User as Nutzer\n    participant Input as KolInputText\n    participant Validator as Validierungslogik\n    participant ErrorMsg as Fehlermeldung\n    participant Form as Formular-Kontext\n\n    User->>Input: Gebe Wert ein\n    Input->>Validator: Validiere Eingabe\n\n    alt Gültige Eingabe\n        Validator-->>Input: Validierung bestanden\n        Input->>ErrorMsg: Lösche Fehlermeldung\n        Input->>Form: Aktualisiere Formular-State (gültig)\n        Input->>Input: Aktualisiere visuellen State (gültig)\n    else Ungültige Eingabe\n        Validator-->>Input: Validierung fehlgeschlagen\n        Input->>ErrorMsg: Zeige Fehlermeldung\n        Input->>Form: Aktualisiere Formular-State (ungültig)\n        Input->>Input: Aktualisiere visuellen State (Fehler)\n    end\n\n    Input-->>User: Visuelles Feedback\n\n    User->>Form: Formular absenden\n    Form->>Form: Prüfe alle Eingaben\n\n    alt Alle gültig\n        Form->>Form: Verarbeite Formulardaten\n    else Hat Fehler\n        Form->>Input: Fokussiere erstes ungültiges Feld\n        Input-->>User: Fokus auf Fehler\n    end\n```\n\n### Szenario: Eingabe-Validierung\n\n**Schritte:**\n\n1. Nutzer gibt Text in Eingabefeld ein\n2. Eingabe-Komponente validiert bei Blur oder Echtzeit (je nach Konfiguration)\n3. Validierungslogik prüft:\n   - Pflichtfeld\n   - Muster-Matching (Regex)\n   - Min/Max-Länge\n   - Benutzerdefinierte Validatoren\n4. Wenn gültig:\n   - Lösche Fehlermeldungen\n   - Aktualisiere visuellen State auf gültig\n   - Emittiere Valid-Event\n5. Wenn ungültig:\n   - Zeige Fehlermeldung\n   - Aktualisiere visuellen State auf Fehler\n   - Emittiere Invalid-Event\n   - Verhindere Formular-Absendung\n\n## 6.6 Lazy Loading\n\n```mermaid\nsequenceDiagram\n    participant App as Anwendung\n    participant Loader as Lazy Loader\n    participant Browser as Browser\n    participant Bundle as Component Bundle\n    participant Component as KolComponent\n\n    App->>Browser: Füge <kol-table> zum DOM hinzu\n    Browser->>Loader: Unbekanntes Element erkannt\n    Loader->>Bundle: Lade table.js-Bundle\n\n    alt Erste Verwendung\n        Bundle-->>Loader: Download Komponenten-Code\n        Loader->>Browser: Definiere Custom Element\n    else Bereits geladen\n        Bundle-->>Loader: Komponente im Cache\n    end\n\n    Browser->>Component: Erstelle Komponenten-Instanz\n    Component->>Component: Initialisiere und rendere\n    Component-->>Browser: Komponente bereit\n    Browser-->>App: Element aufgewertet\n```\n\n### Szenario: Komponenten-Lazy-Loading\n\n**Schritte:**\n\n1. Anwendung verwendet Component Loader (nicht direkte Imports)\n2. Browser begegnet unbekanntem Custom Element (z.B. `<kol-table>`)\n3. Stencil's Lazy Loader fängt ab\n4. Loader holt Komponenten-Bundle on-demand\n5. Komponenten-Code heruntergeladen und ausgeführt\n6. Custom Element im Browser definiert\n7. Browser \"wertet\" Element von unbekannt zu definiert auf\n8. Komponente initialisiert und rendert\n\n**Vorteile:**\n\n- Kleinere initiale Bundle-Größe\n- Komponenten nur bei Bedarf geladen\n- Automatisches Code-Splitting\n- Verbesserte Performance für große Anwendungen\n\n## 6.7 Barrierefreiheits-Integration\n\n```mermaid\nsequenceDiagram\n    participant User as Nutzer mit AT\n    participant AT as Assistive Technologie\n    participant Browser as Browser\n    participant Component as KolComponent\n    participant ARIA as ARIA-Attribute\n    participant Keyboard as Keyboard-Handler\n\n    User->>AT: Navigiere mit Tastatur\n    AT->>Browser: Frage Accessibility Tree ab\n    Browser->>Component: Lese ARIA-Attribute\n    Component->>ARIA: Exponiere Role, State, Properties\n    ARIA-->>Browser: Barrierefreiheits-Info\n    Browser-->>AT: Kündige Komponente an\n    AT-->>User: \"Button, Absenden, Enter drücken zum Aktivieren\"\n\n    User->>Keyboard: Drücke Enter\n    Keyboard->>Component: Keyboard-Event\n    Component->>Component: Behandle Tastendruck\n    Component->>Component: Löse Aktion aus\n    Component->>ARIA: Aktualisiere State (aria-pressed)\n    Component->>AT: Kündige State-Änderung an\n    AT-->>User: \"Button gedrückt\"\n```\n\n### Szenario: Screenreader-Navigation\n\n**Schritte:**\n\n1. Nutzer mit Screenreader navigiert Seite mit Tab-Taste\n2. Screenreader fragt Accessibility Tree des Browsers ab\n3. Komponente exponiert:\n   - Semantische Role (button, textbox, dialog, etc.)\n   - State (expanded, selected, checked, etc.)\n   - Properties (label, description, required, etc.)\n4. Screenreader kündigt Komponenten-Informationen dem Nutzer an\n5. Nutzer interagiert über Tastatur\n6. Komponente behandelt Tastatur-Events (Enter, Space, Pfeiltasten, Escape)\n7. Komponente aktualisiert ARIA-Attribute, um State-Änderungen zu reflektieren\n8. Screenreader kündigt Änderungen dem Nutzer an\n\n**Eingebaute Barrierefreiheits-Features:**\n\n- Korrekte ARIA-Rollen auf allen interaktiven Elementen\n- Tastaturnavigations-Unterstützung\n- Fokus-Management (Fokus in Modals einfangen, etc.)\n- Ausreichender Farbkontrast (WCAG 2.2 AAA konform)\n- Minimale Touch-Target-Größen (44x44px)\n- Semantische HTML-Struktur\n- Fehlermeldungs-Assoziationen\n- Live-Regions für dynamische Inhalte\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/07-deployment-view",
+      "group": "docs/arc42_de",
+      "name": "07-deployment-view",
+      "path": "docs/arc42_de/07-deployment-view.md",
+      "code": "# 7. Verteilungssicht\n\nDieser Abschnitt beschreibt die Infrastruktur und Verteilungsszenarien für Public UI - KoliBri. Er umfasst Entwicklungsumgebungen, CI/CD-Pipelines, Paketverteilungsstrategien und verschiedene Anwendungs-Verteilungsmuster, die Konsumenten bei der Integration von KoliBri-Komponenten in ihre Projekte verwenden können.\n\n## 7.1 Infrastrukturübersicht\n\n```mermaid\ngraph TB\n    subgraph Development\n        Dev[Entwickler-Workstation]\n        Git[Git Repository<br/>GitHub]\n    end\n\n    subgraph CI/CD\n        Actions[GitHub Actions]\n        Tests[Test-Runner]\n        Build[Build-Pipeline]\n        Security[Sicherheits-Scanner<br/>CodeQL]\n    end\n\n    subgraph Distribution\n        NPM[npm Registry]\n        CDN1[unpkg.com]\n        CDN2[jsDelivr]\n    end\n\n    subgraph Deployment\n        StaticSite[Statische Websites]\n        SPA[Single Page Apps]\n        SSR[Server-Side Rendered Apps]\n    end\n\n    Dev -->|push code| Git\n    Git -->|trigger| Actions\n    Actions -->|führe aus| Tests\n    Actions -->|führe aus| Build\n    Actions -->|führe aus| Security\n    Actions -->|veröffentliche| NPM\n\n    NPM -->|spiegele| CDN1\n    NPM -->|spiegele| CDN2\n\n    NPM -->|installiere| StaticSite\n    NPM -->|installiere| SPA\n    NPM -->|installiere| SSR\n\n    CDN1 -->|lade| StaticSite\n    CDN2 -->|lade| StaticSite\n```\n\n## 7.2 Entwicklungsumgebung\n\n### Entwickler-Workstation-Anforderungen\n\n| Komponente | Anforderung | Zweck |\n|-----------|------------|---------|\n| **Betriebssystem** | Windows 10+, macOS 11+ oder Linux | Plattformunabhängige Entwicklung |\n| **Node.js** | Version 22.x (erforderlich) | Runtime für Build-Tools |\n| **pnpm** | Version 10.x | Paketmanager |\n| **Git** | Version 2.30+ | Versionskontrolle |\n| **IDE** | VS Code (empfohlen) | Code-Bearbeitung mit TypeScript-Unterstützung |\n| **Browser** | Chrome/Edge (zum Testen) | Entwicklung und Testing |\n\n### Lokales Setup\n\n```bash\n# Repository klonen\ngit clone https://github.com/public-ui/kolibri.git\ncd kolibri\n\n# Node.js 22 installieren\n# (plattformspezifische Installation)\n\n# pnpm aktivieren\ncorepack enable pnpm\n\n# Abhängigkeiten installieren\npnpm i --ignore-scripts\n\n# Alle Pakete bauen\npnpm -r build\n\n# Entwicklungsserver starten\ncd packages/samples/react\npnpm start\n```\n\n### Entwicklungs-Ports\n\n| Port | Dienst | URL |\n|------|---------|-----|\n| 9191 | React-Beispiel-App | http://localhost:9191 |\n| 4200 | Angular-Beispiel-App | http://localhost:4200 |\n| Variabel | Stencil-Dev-Server | http://localhost:3333 |\n\n## 7.3 CI/CD-Pipeline\n\n```mermaid\ngraph LR\n    subgraph GitHub Actions Workflows\n        PR[Pull Request] -->|trigger| CI\n        Push[Push to main] -->|trigger| CI\n        Tag[Tag-Erstellung] -->|trigger| Publish\n\n        CI[CI Workflow]\n        Publish[Publish Workflow]\n        Snapshots[Update Snapshots]\n\n        CI -->|bei Erfolg| Merge\n        Merge[Merge to main]\n        Merge -->|trigger| Tag\n        Tag -->|trigger| Publish\n    end\n\n    subgraph CI Steps\n        Install[Abhängigkeiten installieren]\n        Build[Alle Pakete bauen]\n        Lint[Code linten]\n        Test[Tests ausführen]\n        Security[Sicherheits-Scans]\n\n        Install --> Build\n        Build --> Lint\n        Lint --> Test\n        Test --> Security\n    end\n\n    subgraph Publish Steps\n        VerifyBuild[Build verifizieren]\n        Pack[Pakete packen]\n        Provenance[Provenance generieren]\n        NPMPublish[Zu npm veröffentlichen]\n\n        VerifyBuild --> Pack\n        Pack --> Provenance\n        Provenance --> NPMPublish\n    end\n```\n\n### GitHub Actions Workflows\n\n| Workflow | Trigger | Zweck |\n|----------|---------|---------|\n| **ci.yml** | Push, Pull Request | Tests, Linting, Builds ausführen |\n| **publish.yml** | Tag-Erstellung | Pakete zu npm mit Provenance veröffentlichen |\n| **update-snapshots.yml** | Manueller Trigger | Visual Regression Test Snapshots aktualisieren |\n| **codeql.yml** | Push, Pull Request, Schedule | Sicherheits-Scanning mit CodeQL |\n\n### CI Quality Gates\n\nAlle PRs müssen bestehen:\n\n1. **Build**: Alle Pakete müssen ohne Fehler bauen\n2. **Linting**: ESLint, Stylelint, TypeScript-Checks müssen bestehen\n3. **Unit-Tests**: Alle Jest-Tests müssen bestehen\n4. **E2E-Tests**: Playwright-Tests müssen bestehen\n5. **Sicherheit**: CodeQL-Analyse muss bestehen, keine kritischen Schwachstellen\n6. **Formatierung**: Code muss mit Prettier formatiert sein\n\n## 7.4 Paketverteilung\n\n### npm Registry\n\nPrimärer Verteilungskanal für KoliBri-Pakete:\n\n```mermaid\ngraph TB\n    subgraph \"Published Packages\"\n        Core[\"@public-ui/components\"]\n        DefaultTheme[\"@public-ui/theme-default\"]\n        ECLTheme[\"@public-ui/theme-ecl\"]\n        ReactAdapter[\"@public-ui/react\"]\n        AngularAdapter[\"@public-ui/angular-v21\"]\n        VueAdapter[\"@public-ui/vue\"]\n        CLI[\"@public-ui/kolibri-cli\"]\n    end\n\n    subgraph \"npm Registry\"\n        Registry[npm Registry]\n    end\n\n    subgraph CDN\n        unpkg[unpkg.com]\n        jsDelivr[jsDelivr.net]\n    end\n\n    Core --> Registry\n    DefaultTheme --> Registry\n    ECLTheme --> Registry\n    ReactAdapter --> Registry\n    AngularAdapter --> Registry\n    VueAdapter --> Registry\n    CLI --> Registry\n\n    Registry -->|spiegele| unpkg\n    Registry -->|spiegele| jsDelivr\n```\n\n### Paketstruktur\n\nJedes zu npm veröffentlichte Paket enthält:\n\n```\n@public-ui/components/\n├── dist/                   # Kompiliertes JavaScript\n│   ├── index.js           # ES-Modul-Einstieg\n│   ├── index.cjs.js       # CommonJS-Einstieg\n│   ├── types/             # TypeScript-Definitionen\n│   └── esm/               # ES2017-Module\n├── loader/                # Lazy-Loading-Wrapper\n├── assets/                # Statische Assets (Icons, etc.)\n├── doc/                   # Generierte Dokumentation\n├── custom-elements.json   # Custom Elements Manifest\n└── package.json           # Paket-Metadaten\n```\n\n### SLSA Provenance\n\nKoliBri veröffentlicht Pakete mit SLSA Build Level 3 Provenance:\n\n- Pakete in GitHub Actions mit OIDC-Identität gebaut\n- Mit `--provenance`-Flag veröffentlicht\n- Verifizierbare Attestierungen für alle veröffentlichten Artefakte\n- Gewährleistet Build-Integrität und Supply-Chain-Sicherheit\n\nVerifizierung:\n\n```bash\n# Provenance-Metadaten anzeigen\npnpm view @public-ui/components dist.provenance\n\n# Signaturen verifizieren (falls npm-Client unterstützt)\npnpm audit signatures --package=@public-ui/components@latest\n```\n\n## 7.5 Anwendungs-Verteilungsszenarien\n\n### Szenario 1: Statische Website\n\n```mermaid\ngraph LR\n    Build[Build-Prozess] -->|bundle| Static[Statische Assets]\n    Static -->|deploy| CDN[CDN/Static Host]\n    CDN -->|serve| Browser[Nutzer-Browser]\n    Browser -->|lade| Components[KoliBri-Komponenten]\n```\n\n**Verteilung:**\n\n- Komponenten mit Anwendungscode gebündelt\n- Zu statischem Hosting deployed (Netlify, Vercel, GitHub Pages, S3, etc.)\n- Kein Server-Side Rendering\n- Alle Assets von CDN gecacht\n\n**Beispiel:**\n\n```html\n<!DOCTYPE html>\n<html>\n\t<head>\n\t\t<script type=\"module\" src=\"./kolibri-components.js\"></script>\n\t\t<link rel=\"stylesheet\" href=\"./theme-default.css\" />\n\t</head>\n\t<body>\n\t\t<kol-button _label=\"Klick mich\"></kol-button>\n\t</body>\n</html>\n```\n\n### Szenario 2: Single Page Application (SPA)\n\n```mermaid\ngraph LR\n    Framework[React/Angular/Vue App] -->|bundle| Webpack[Bundler]\n    Webpack -->|build| Assets[Optimierte Assets]\n    Assets -->|deploy| Server[Web-Server]\n    Server -->|serve| Browser[Nutzer-Browser]\n    Browser -->|lazy load| Components[KoliBri-Komponenten]\n```\n\n**Verteilung:**\n\n- Komponenten über Framework-Adapter importiert\n- Mit Anwendung über Webpack/Vite/Rollup gebündelt\n- Lazy Loading für Code-Splitting\n- Zu Anwendungsserver oder CDN deployed\n\n**Beispiel (React):**\n\n```typescript\nimport { KolButton } from '@public-ui/react';\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\n\nawait register(DEFAULT, defineCustomElements);\n\nfunction App() {\n\treturn <KolButton _label=\"Klick mich\" />;\n}\n```\n\n### Szenario 3: Server-Side Rendering (SSR)\n\n```mermaid\ngraph LR\n    SSR[SSR Server] -->|render| HTML[Initiales HTML]\n    HTML -->|sende| Browser[Nutzer-Browser]\n    Browser -->|hydrate| Components[KoliBri-Komponenten]\n    Browser -->|request| SSR\n```\n\n**Verteilung:**\n\n- Komponenten auf Client nach SSR hydratisiert\n- Initiales HTML server-seitig gerendert\n- Client-seitige Hydratisierung für Interaktivität\n- Zu Node.js-Server oder Serverless-Funktionen deployed\n\n**Überlegungen:**\n\n- Verwende Hydrate-Adapter für SSR-Unterstützung\n- Komponenten benötigen client-seitige Hydratisierung\n- Shadow DOM erfordert sorgfältiges SSR-Handling\n\n### Szenario 4: Nur CDN (Kein Build)\n\n```mermaid\ngraph LR\n    CDN[unpkg/jsDelivr] -->|serve| Browser[Nutzer-Browser]\n    Browser -->|lade| Components[KoliBri-Komponenten]\n```\n\n**Verteilung:**\n\n- Komponenten direkt von CDN laden\n- Kein Build-Schritt erforderlich\n- Ideal für Prototypen und einfache Websites\n\n**Beispiel:**\n\n```html\n<script type=\"module\">\n\timport { defineCustomElements } from 'https://unpkg.com/@public-ui/components@latest/loader/index.mjs';\n\timport { register } from 'https://unpkg.com/@public-ui/components@latest/dist/index.js';\n\timport { DEFAULT } from 'https://unpkg.com/@public-ui/theme-default@latest/index.js';\n\n\tawait register(DEFAULT, defineCustomElements);\n</script>\n```\n\n## 7.6 Verteilungstopologie\n\n### Multi-Tier-Architektur\n\n```mermaid\ngraph TB\n    subgraph \"User Tier\"\n        Browser[Web Browser]\n        AT[Assistive Technologie]\n    end\n\n    subgraph \"CDN Tier\"\n        CDN[Content Delivery Network]\n    end\n\n    subgraph \"Application Tier\"\n        AppServer[Anwendungsserver - Node.js/Static]\n        API[Backend-API - optional]\n    end\n\n    subgraph \"Data Tier\"\n        DB[Datenbank - optional]\n    end\n\n    Browser -->|HTTPS| CDN\n    Browser -->|HTTPS| AppServer\n    AT -->|Accessibility API| Browser\n\n    CDN -->|fallback| AppServer\n    AppServer -->|HTTP/REST| API\n    API -->|query| DB\n```\n\n### Komponenten-Lade-Strategie\n\n1. **Initialer Ladevorgang**:\n   - HTML-Seite mit Komponenten-Tags\n   - Kern-Component-Loader-Skript\n   - Theme-CSS\n\n2. **Lazy Loading**:\n   - Individuelle Komponenten-Bundles on-demand geladen\n   - Nur verwendete Komponenten heruntergeladen\n   - Browser-Caching für nachfolgende Ladevorgänge\n\n3. **Caching-Strategie**:\n   - Komponenten: Langer Cache (unveränderliche Versionen)\n   - Themes: Langer Cache (unveränderliche Versionen)\n   - Anwendungscode: Cache mit Revalidierung\n\n## 7.7 Monitoring und Observability\n\n### Client-Side-Monitoring\n\nEmpfehlungen für Anwendungen mit KoliBri:\n\n- **Performance-Monitoring**: Web Vitals\n- **Fehler-Tracking**: Sentry, Rollbar (Anwendungsebene)\n- **Barrierefreiheits-Monitoring**: axe DevTools, automatisierte Scans\n- **Bundle-Size-Tracking**: bundlephobia, webpack-bundle-analyzer\n\n### Build-Pipeline-Monitoring\n\n- **CI/CD-Status**: GitHub Actions Status-Badges\n- **Test-Abdeckung**: Jest-Coverage-Reports\n- **Sicherheits-Warnungen**: GitHub Dependabot, CodeQL-Warnungen\n- **Paket-Gesundheit**: npm-Paket-Gesundheits-Score\n\n### Metriken\n\nWichtige verfolgte Metriken:\n\n- **Build-Zeit**: Vollständige Build-Dauer (~2 Minuten)\n- **Test-Dauer**: Unit + E2E-Test-Ausführung (~3 Minuten)\n- **Paketgröße**: Individuelle Paketgrößen\n- **Download-Statistiken**: npm-Download-Zahlen\n- **Issue-Auflösungszeit**: Zeit bis zum Schließen von Issues/PRs\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/08-cross-cutting-concepts",
+      "group": "docs/arc42_de",
+      "name": "08-cross-cutting-concepts",
+      "path": "docs/arc42_de/08-cross-cutting-concepts.md",
+      "code": "# 8. Querschnittliche Konzepte\n\nDieser Abschnitt behandelt architektonische Prinzipien und Muster, die mehrere Komponenten und Schichten des Systems überspannen. Diese querschnittlichen Belange – Barrierefreiheit, Internationalisierung, Sicherheit, Performance und Testing – gelten durchgängig in Public UI - KoliBri und bilden die Grundlage seiner Designphilosophie.\n\n## 8.1 Barrierefreiheit (A11y)\n\nBarrierefreiheit ist der Eckpfeiler von Public UI - KoliBri. Jede Komponente ist so designed und getestet, dass sie für alle Menschen nutzbar ist, unabhängig von ihren Fähigkeiten oder den verwendeten assistiven Technologien.\n\n### Prinzipien\n\nPublic UI - KoliBri folgt den **WCAG 2.2 Level AAA** Standards und **BITV**-Anforderungen als Kernprinzipien und implementiert stets die neueste Version der Barrierefreiheitsstandards.\n\n### Implementierungsstrategie\n\n| Aspekt | Implementierung | Verifizierung |\n|--------|---------------|--------------|\n| **Tastaturnavigation** | Alle interaktiven Elemente über Tastatur zugänglich (Tab, Enter, Space, Pfeiltasten, Escape) | Manuelle Tastaturtests, automatisierte Tests |\n| **Screenreader-Unterstützung** | Korrekte ARIA-Rollen, Labels und States | Screenreader-Tests (JAWS, NVDA, VoiceOver) |\n| **Farbkontrast** | Minimum 4,5:1 für Text, 3:1 für UI-Komponenten | wcag-contrast-Bibliotheksvalidierung |\n| **Touch-Targets** | Minimum 44x44px für interaktive Elemente | Eingebaut in Komponenten-CSS, automatisierte Tests |\n| **Fokus-Management** | Sichtbare Fokus-Indikatoren, Fokus-Einfangung in Modals | Visuelle Inspektion, automatisierte Tests |\n| **Semantisches HTML** | Verwendung korrekter HTML-Elemente (button, input, nav, etc.) | HTML-Validierung, manuelle Überprüfung |\n| **Alternativtexte** | Bilder und Icons haben Textalternativen | Manuelle Überprüfung, automatisierte Checks |\n| **Formular-Labels** | Alle Formularfelder haben zugeordnete Labels | Automatisierte Barrierefreiheits-Tests |\n\n### Barrierefreiheits-Test-Pyramide\n\n```mermaid\ngraph TB\n    Manual[Manuelle Tests<br/>Screenreader, Tastatur]\n    E2E[E2E-Tests<br/>Playwright + axe-core]\n    Unit[Unit-Tests<br/>ARIA-Attribut-Checks]\n\n    Manual -->|validiert| E2E\n    E2E -->|validiert| Unit\n```\n\n### Eingebaute Barrierefreiheits-Features\n\nJede KoliBri-Komponente beinhaltet:\n\n1. **Semantische Struktur**: Korrekte HTML-Elemente und ARIA-Rollen\n2. **Tastatur-Unterstützung**: Vollständige Tastaturnavigation\n3. **Fokus-Management**: Sichtbarer Fokus, logische Tab-Reihenfolge\n4. **ARIA-Attribute**: Dynamische State- und Property-Updates\n5. **Kontrast-Konformität**: Farben erfüllen WCAG-Standards\n6. **Responsiver Text**: Unterstützt Browser-Zoom bis zu 200%\n7. **Fehlerbehandlung**: Klare Fehlermeldungen mit programmatischen Assoziationen\n\n## 8.2 Internationalisierung (i18n)\n\nPublic UI - KoliBri bietet robuste Internationalisierungsunterstützung durch browserbasierende Spracherkennung und flexible Konfigurationsoptionen.\n\n### Sprachunterstützung\n\nKomponenten unterstützen Internationalisierung basierend auf Browser-Sprach- und Locale-Einstellungen sowie HTML-Element-Attributen:\n\n- **Browser-Spracherkennung**: Verwendet automatisch Browser-Spracheinstellungen\n- **HTML-Attribute**: Respektiert `lang`, `dir` (für RTL) und Locale-Attribute auf dem `html`-Element\n- **Übersetzungsverwaltung**: Optionale Key-Value-Sprachkarten, konfiguriert während des Bootstrap-/Register-Aufrufs\n- **i18next-Integration**: Native Unterstützung für i18next-Übersetzungs-Framework\n\n### Implementierung\n\n```typescript\n// Übersetzungsverwaltung via Register-Konfiguration für komponenten-interne Texte\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\n\nawait register(DEFAULT, defineCustomElements, {\n\ttranslations: {\n\t\t'de': {\n\t\t\t'kol.button.close': 'Schließen',\n\t\t\t'kol.modal.close': 'Schließen'\n\t\t},\n\t\t'en': {\n\t\t\t'kol.button.close': 'Close',\n\t\t\t'kol.modal.close': 'Close'\n\t\t}\n\t}\n});\n\n// Für Anwendungstext, übergebe übersetzte Strings direkt via Props\n<KolButton _label={t('app.button.submit')} />\n\n// Browser-Locale wird für Datums-/Zahlenformatierung respektiert\n<KolInputDate /> // Verwendet automatisch Browser-Locale für Formatierung\n```\n\n### Best Practices\n\n- Setze `lang`- und `dir`-Attribute auf dem HTML-Element für korrekte Lokalisierung\n- Komponenten-interne Texte können über Übersetzungsschlüssel in der Register-Konfiguration angepasst werden\n- Anwendungsspezifischer Text sollte extern übersetzt und via Komponenten-Props übergeben werden\n- Verwende i18next-Integration für komplexe Übersetzungsanforderungen\n- Komponenten formatieren automatisch Datums-, Zahlen- und Währungswerte basierend auf Browser-Locale\n\n## 8.3 Sicherheit\n\n### Sicherheitsprinzipien\n\n| Prinzip | Implementierung |\n|-----------|---------------|\n| **Keine XSS-Schwachstellen** | Alle Nutzereingaben bereinigt, Shadow DOM bietet Isolation |\n| **Content Security Policy** | Komponenten funktionieren mit strikter CSP |\n| **Abhängigkeitssicherheit** | Regelmäßige Sicherheits-Scans, automatisierte Updates |\n| **Sichere Standards** | Komponenten standardmäßig sicher konfiguriert |\n| **SLSA Provenance** | Build Level 3 Attestierungen für veröffentlichte Pakete |\n\n### Sicherheitsmaßnahmen\n\n1. **Abhängigkeits-Scanning**\n   - Dependabot-Warnungen für verwundbare Abhängigkeiten\n   - Regelmäßige Abhängigkeits-Updates\n   - Lizenz-Compliance-Checks\n\n2. **Code-Scanning**\n   - CodeQL-Analyse in CI/CD\n   - Statische Sicherheitsanalyse\n   - Schwachstellenerkennung\n\n3. **Build-Sicherheit**\n   - SLSA Build Level 3 Konformität\n   - Signierte Pakete mit Provenance\n   - Reproduzierbare Builds\n\n4. **Eingabevalidierung**\n   - Alle Props mit TypeScript-Typen validiert\n   - Runtime-Validierung für kritische Werte\n   - Bereinigung von HTML-Inhalten\n\n### Sicherheits-Best-Practices\n\n- Niemals Nutzereingaben vertrauen\n- TypeScript für Typsicherheit verwenden\n- Abhängigkeiten aktuell halten\n- OWASP-Richtlinien folgen\n- Sicherheitsprobleme verantwortungsvoll melden\n\n## 8.4 Performance\n\n### Performance-Prinzipien\n\n| Prinzip | Implementierung |\n|-----------|---------------|\n| **Kleine Bundle-Größe** | Tree-shakeable Exports, Lazy Loading |\n| **Schnelles Rendering** | Shadow DOM, Virtual DOM Diffing |\n| **Effizientes Styling** | Adopted Style Sheets, CSS Containment |\n| **Minimale Abhängigkeiten** | Nur essenzielle Runtime-Abhängigkeiten |\n| **Optimales Laden** | Code-Splitting, Lazy Component Loading |\n\n### Performance-Optimierungstechniken\n\n1. **Lazy Loading**\n   - Komponenten on-demand geladen\n   - Reduziert initiale Bundle-Größe\n   - Schnellere Seitenladezeiten\n\n2. **Shadow DOM**\n   - Effizientes Style-Scoping\n   - Keine globale CSS-Verschmutzung\n   - Optimiertes Rendering\n\n3. **Adopted Style Sheets**\n   - Geteilte Styles über Komponenten hinweg\n   - Effizienter Theme-Wechsel\n   - Memory-effizient\n\n4. **Code-Splitting**\n   - Jede Komponente in separatem Bundle\n   - Nur laden, was verwendet wird\n   - Optimiert für HTTP/2\n\n### Performance-Metriken\n\nZielmetriken für Anwendungen mit KoliBri:\n\n- **First Contentful Paint**: <1,8s\n- **Time to Interactive**: <3,8s\n- **Total Blocking Time**: <300ms\n- **Cumulative Layout Shift**: <0,1\n\n## 8.5 Test-Strategie\n\n```mermaid\ngraph TB\n    Manual[Manuelles Testing]\n    E2E[E2E-Tests<br/>Playwright]\n    Visual[Visual Tests<br/>Screenshot-Vergleich]\n    Unit[Unit-Tests<br/>Jest]\n    Lint[Linting<br/>ESLint, Stylelint]\n    Type[Type-Checking<br/>TypeScript]\n\n    Type --> Lint\n    Lint --> Unit\n    Unit --> Visual\n    Visual --> E2E\n    E2E --> Manual\n```\n\n### Test-Ebenen\n\n1. **Type-Checking** (TypeScript)\n   - Typfehler zur Compile-Zeit abfangen\n   - API-Korrektheit sicherstellen\n   - IDE-Unterstützung\n\n2. **Linting** (ESLint, Stylelint)\n   - Code-Qualität durchsetzen\n   - Konsistenter Code-Stil\n   - Best-Practice-Konformität\n\n3. **Unit-Tests** (Jest)\n   - Komponenten-Logik testen\n   - Property-Validierung\n   - State-Management\n   - Coverage-Ziel: >80%\n\n4. **Visual Tests**\n   - Screenshot-Vergleich\n   - Theme-Validierung\n   - Cross-Browser-Erscheinungsbild\n\n5. **E2E-Tests** (Playwright)\n   - Nutzer-Workflows\n   - Komponenten-Interaktionen\n   - Barrierefreiheits-Validierung (axe-core)\n\n6. **Manuelle Tests**\n   - Screenreader-Tests\n   - Cross-Browser-Tests\n   - Exploratives Testing\n\n### Test-Automatisierung\n\n- **CI/CD-Integration**: Alle Tests laufen in GitHub Actions\n- **Pre-Commit-Hooks**: Linting und Formatierung\n- **Pull-Request-Checks**: Alle Tests müssen bestehen\n- **Geplante Tests**: Regelmäßige Sicherheits- und Abhängigkeits-Scans\n\n## 8.6 Fehlerbehandlung\n\n### Fehlerbehandlungs-Strategie\n\n| Fehlertyp | Behandlungsansatz |\n|-----------|-------------------|\n| **Ungültige Props** | TypeScript-Validierung, Runtime-Warnungen, Fallback auf Defaults |\n| **Fehlende Abhängigkeiten** | Klare Fehlermeldungen, Dokumentationslinks |\n| **Browser-Unterstützung** | Feature-Detection, Graceful Degradation, Fehlermeldungen |\n| **Theme-Fehler** | Fallback auf Barrierefreiheits-Baseline, Konsolen-Warnungen |\n| **Runtime-Fehler** | Try-Catch-Blöcke, Error Boundaries (in Frameworks), nutzerfreundliche Nachrichten |\n\n### Fehler-Kommunikation\n\n1. **Entwickler-Fehler** (Konsole)\n   - TypeScript-Typfehler\n   - Ungültige Property-Warnungen\n   - Fehlende erforderliche Props\n\n2. **Nutzer-Fehler** (UI)\n   - Formular-Validierungsfehler\n   - Pflichtfeld-Indikatoren\n   - Inline-Fehlermeldungen\n   - Fehler-Zusammenfassungen\n\n3. **Barrierefreiheits-Fehler**\n   - ARIA-Live-Regions für dynamische Fehler\n   - Fehlermeldungen mit Feldern assoziiert\n   - Klare Fehler-Identifikation\n\n## 8.7 Dokumentation\n\n### Dokumentations-Strategie\n\n```mermaid\ngraph TB\n    Code[Quellcode] -->|generiert| API[API-Dokumentation]\n    Code -->|enthält| Comments[Inline-Kommentare]\n    Samples[Beispielanwendungen] -->|demonstriert| Usage[Nutzungsbeispiele]\n    Guides[Geschriebene Leitfäden] -->|erklärt| Concepts[Konzepte]\n\n    API --> Website[Dokumentations-Website]\n    Usage --> Website\n    Concepts --> Website\n\n    Website -->|konsumiert von| Developers[Entwickler]\n```\n\n### Dokumentationstypen\n\n1. **API-Dokumentation**\n   - Auto-generiert aus TypeScript\n   - Komponenten-Properties und -Methoden\n   - Event-Beschreibungen\n   - Typdefinitionen\n\n2. **Nutzungsbeispiele**\n   - Funktionierende Code-Samples\n   - React-Beispielanwendung\n   - Angular-Beispielanwendung\n   - Framework-Integrationsleitfäden\n\n3. **Konzeptionelle Dokumentation**\n   - Architekturübersicht\n   - Theming-Leitfaden\n   - Barrierefreiheits-Richtlinien\n   - Migrations-Leitfäden\n\n4. **Inline-Dokumentation**\n   - JSDoc-Kommentare im Code\n   - TypeScript-Typdefinitionen\n   - CSS-Kommentare, die Styles erklären\n\n### Dokumentations-Prinzipien\n\n- **Docs synchron halten**: Dokumentation mit Code-Änderungen aktualisieren\n- **Beispiele über Erklärung**: Funktionierenden Code zeigen\n- **Durchsuchbar**: Klare Struktur und Benennung\n- **Multi-Level**: Von Schnellstart bis zu fortgeschrittenen Themen\n- **Barrierefrei**: Dokumentation selbst muss barrierefrei sein\n\n## 8.8 Code-Qualität\n\n### Qualitätsdurchsetzung\n\n| Aspekt | Tool | Durchsetzung |\n|--------|------|------------|\n| **Formatierung** | Prettier | Pre-Commit-Hook, CI-Check |\n| **Linting** | ESLint, Stylelint | CI-Check, keine Inline-Deaktivierung |\n| **Typsicherheit** | TypeScript | Kompilierungsschritt, Strict-Modus |\n| **Testing** | Jest, Playwright | CI-Check, Coverage-Anforderungen |\n| **Sicherheit** | CodeQL, Dependabot | Automatisiertes Scanning |\n| **Code-Review** | GitHub PR Reviews | Erforderlich vor Merge |\n\n### Code-Konventionen\n\n1. **Benennungskonventionen**\n   - Komponenten: PascalCase mit \"Kol\"-Präfix (KolButton)\n   - Properties: camelCase, mit Unterstrich präfixiert (_label)\n   - CSS-Klassen: BEM-Methodologie\n   - Dateien: kebab-case\n\n2. **Datei-Organisation**\n   - Eine Komponente pro Verzeichnis\n   - Komponente, Styles, Tests zusammen\n   - Alphabetische Sortierung in Listen\n\n3. **Code-Stil**\n   - 160 Zeichen Zeilenlänge\n   - Tabs zur Einrückung\n   - Einfache Anführungszeichen\n   - Trailing Commas\n   - Keine Semikolons (wenn optional)\n\n## 8.9 Versionierung und Kompatibilität\n\n### Semantische Versionierung\n\nKoliBri folgt strikt SemVer 2.0:\n\n- **Major**: Breaking Changes\n- **Minor**: Neue Features, rückwärtskompatibel\n- **Patch**: Bugfixes, rückwärtskompatibel\n\n### Kompatibilitäts-Strategie\n\n| Versionstyp | Support-Dauer | Zweck |\n|-------------|-----------------|---------|\n| **LTS** | 3 Jahre | Langzeitunterstützung für Unternehmen |\n| **STS** | 15 Monate | Kurzzeitunterstützung für schnelle Innovation |\n| **Development** | Bis zur nächsten Freigabe | Neueste Features und Verbesserungen |\n\n### Breaking-Change-Management\n\n1. **Zunächst Deprecation**: Features als deprecated markieren vor Entfernung\n2. **Migrations-Leitfaden**: Detaillierte Upgrade-Anweisungen bereitstellen\n3. **Migrations-Tool**: CLI-Tool automatisiert Code-Updates\n4. **Parallele Unterstützung**: Deprecated Features funktionieren in einer Hauptversion\n5. **Klare Kommunikation**: Release-Notes erklären alle Breaking Changes\n\n## 8.10 Build und Release\n\n### Build-Prozess\n\n```mermaid\ngraph LR\n    Source[Quellcode] -->|TypeScript| Compile[Kompilieren]\n    Compile -->|Stencil| Generate[Outputs generieren]\n    Generate -->|Rollup| Bundle[Bündeln]\n    Bundle -->|Minify| Optimize[Optimieren]\n    Optimize -->|Package| Dist[Verteilungsdateien]\n```\n\n### Build-Artefakte\n\nJedes Paket produziert:\n\n- ES Modules (moderne Browser)\n- CommonJS (Node.js, Legacy-Bundler)\n- TypeScript-Definitionen (.d.ts)\n- Custom Elements JSON (Metadaten)\n- Lazy-Loading-Wrapper\n- Source Maps (Entwicklung)\n\n### Release-Prozess\n\n1. **Versions-Bump**: Version in allen package.json-Dateien aktualisieren\n2. **Changelog**: Alle Änderungen dokumentieren\n3. **Tag-Erstellung**: Git-Tag erstellen (löst CI aus)\n4. **Build**: CI baut alle Pakete\n5. **Test**: CI führt vollständige Test-Suite aus\n6. **Publish**: CI veröffentlicht zu npm mit Provenance\n7. **Dokumentation**: Dokumentations-Website aktualisieren\n8. **Ankündigung**: Release-Notes, Social Media\n\n### Release-Kanäle\n\n- **Latest**: Aktuelle stabile Freigabe\n- **Next**: Pre-Release-Versionen zum Testen\n- **LTS**: Langzeitunterstützungs-Versionen\n- **Legacy**: Ältere Versionen (nur Sicherheitsfixes)\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/09-architecture-decisions",
+      "group": "docs/arc42_de",
+      "name": "09-architecture-decisions",
+      "path": "docs/arc42_de/09-architecture-decisions.md",
+      "code": "# 9. Architekturentscheidungen\n\nDieser Abschnitt dokumentiert die bedeutenden Architekturentscheidungen, die während der Entwicklung von Public UI - KoliBri getroffen wurden. Jeder Architecture Decision Record (ADR) erfasst den Kontext, die Entscheidung und die Konsequenzen wichtiger Entscheidungen und bietet Transparenz und Begründung für zukünftige Wartende und Beitragende.\n\n## 9.1 Entscheidungsaufzeichnungen\n\n### ADR-001: Web Components als Fundament verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nKoliBri muss Framework-agnostisch sein und mit jedem JavaScript-Framework (React, Angular, Vue) oder Vanilla JavaScript funktionieren. Wir benötigen eine Technologie, die standardisiert ist und langfristig unterstützt wird.\n\n**Entscheidung:**\nWeb Components (Custom Elements, Shadow DOM) als Fundament für alle Komponenten verwenden.\n\n**Konsequenzen:**\n\n- ✅ Framework-agnostisch by Design\n- ✅ Basiert auf W3C-Standards (langfristige Stabilität)\n- ✅ Native Browser-Unterstützung (kein Framework-Overhead)\n- ✅ Echte Kapselung via Shadow DOM\n- ❌ Erfordert Polyfills für ältere Browser\n- ❌ Shadow DOM kann bestimmte Styling-Szenarien erschweren\n- ❌ Begrenzt auf Custom Elements API-Fähigkeiten\n\n**Betrachtete Alternativen:**\n\n- React-Komponenten: Zu stark an React-Ökosystem gekoppelt\n- Framework-spezifische Bibliotheken: Verletzt Framework-agnostisches Ziel\n- Reines HTML/CSS: Keine Komponenten-Logik oder Wiederverwendbarkeit\n\n### ADR-002: Stencil.js als Compiler verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nDas direkte Schreiben von Web Components ist verbose und fehleranfällig. Wir benötigen ein Tool, das die Entwicklererfahrung verbessert und dennoch Standard-Web-Components generiert.\n\n**Entscheidung:**\nStencil.js als Web-Component-Compiler verwenden.\n\n**Konsequenzen:**\n\n- ✅ Hervorragende Entwicklererfahrung (TypeScript, JSX, Decorators)\n- ✅ Generiert Framework-Adapter automatisch\n- ✅ Optimierte Ausgabe (Lazy Loading, Code-Splitting)\n- ✅ Starke TypeScript-Unterstützung\n- ❌ Abhängigkeit vom Stencil-Projekt\n- ❌ Lernkurve für Beitragende\n- ❌ Build-Schritt erforderlich\n\n**Betrachtete Alternativen:**\n\n- Lit: Gute DX, aber keine automatische Framework-Adapter-Generierung\n- Native Web Components: Zu verbose, schlechte DX\n- Polymer: Deprecated und nicht aktiv gewartet\n- Custom Solution: Zu viel Wartungsaufwand\n\n### ADR-003: Themes von Komponenten trennen\n\n**Status:** Akzeptiert\n\n**Kontext:**\nVerschiedene Organisationen benötigen verschiedene visuelle Designs (Corporate Design, Design-Systeme). Die Kopplung von Styling mit Komponenten erschwert die Anpassung.\n\n**Entscheidung:**\nThemes in unabhängige Pakete trennen, die zur Laufzeit registriert werden können.\n\n**Konsequenzen:**\n\n- ✅ Organisationen können benutzerdefinierte Themes ohne Forking erstellen\n- ✅ Runtime-Theme-Wechsel möglich\n- ✅ Mehrere Themes können unabhängig gewartet werden\n- ✅ Theme-Updates erfordern keine Komponenten-Rebuilds\n- ❌ Komplexere Architektur\n- ❌ Theme- und Komponentenversionen müssen synchronisiert werden\n- ❌ Zusätzliche Pakete zu warten\n\n**Betrachtete Alternativen:**\n\n- Nur CSS-Variablen: Unzureichend für komplexes Theming\n- Inline-Styles: Koppelt Styling mit Logik\n- Mehrere Komponentenversionen: Wartungs-Alptraum\n- Fork pro Organisation: Fragmentierung, keine Zusammenarbeit\n\n### ADR-004: Shadow DOM für Kapselung verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nKomponenten benötigen Style-Isolation, um CSS-Konflikte zu verhindern. Globales CSS in großen Anwendungen führt oft zu unbeabsichtigten Seiteneffekten.\n\n**Entscheidung:**\nShadow DOM für alle Komponenten verwenden, um echte Style-Kapselung zu erreichen.\n\n**Konsequenzen:**\n\n- ✅ Perfekte Style-Isolation\n- ✅ Keine CSS-Namenskonflikte\n- ✅ Komponenten können nicht versehentlich durch globale Styles kaputt gehen\n- ✅ Vorhersagbares Rendering-Verhalten\n- ❌ Kann Komponenten-Interna nicht von außen stylen (by Design)\n- ❌ Einige CSS-Selektoren funktionieren nicht über Shadow-Grenze\n- ❌ Etwas komplexeres Debugging\n\n**Betrachtete Alternativen:**\n\n- Kein Shadow DOM: Style-Konflikte und unvorhersagbares Verhalten\n- Scoped Styles (wie Vue): Keine echte Kapselung\n- CSS Modules: Erfordert Build-Tooling, nicht standardbasiert\n- BEM-Benennung: Konventionen können gebrochen werden, nicht erzwungen\n\n### ADR-005: Adopted Style Sheets verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nThemes müssen effizient auf viele Komponenteninstanzen angewendet werden. Traditionelle Style-Injection wäre ineffizient und würde viele duplizierte Style-Elemente erstellen.\n\n**Entscheidung:**\nAdopted Style Sheets API für Theme-Anwendung verwenden.\n\n**Konsequenzen:**\n\n- ✅ Effizientes Style-Sharing über Komponenten\n- ✅ Runtime-Theme-Wechsel ohne Neu-Rendering\n- ✅ Memory-effizient (Styles geteilt, nicht dupliziert)\n- ✅ Schnelle Theme-Änderungen\n- ❌ Erfordert modernen Browser (oder Polyfill)\n- ❌ Komplexere Theming-Implementierung\n\n**Betrachtete Alternativen:**\n\n- Style-Tags in jeder Komponente: Ineffizient, memory-intensiv\n- Globale Styles mit CSS Custom Properties: Bricht Kapselung\n- Inline-Styles: Nicht wartbar, keine CSS-Features\n- Einzelnes Style-Tag: Schwer zu verwalten, keine Kapselung\n\n### ADR-006: TypeScript verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nJavaScripts dynamische Natur führt zu Runtime-Fehlern, die zur Compile-Zeit abgefangen werden könnten. Komponenten-APIs benötigen starke Typisierung für gute Entwicklererfahrung.\n\n**Entscheidung:**\nGesamten Code in TypeScript mit aktiviertem Strict-Modus schreiben.\n\n**Konsequenzen:**\n\n- ✅ Typsicherheit fängt Fehler früh ab\n- ✅ Hervorragende IDE-Unterstützung (Autocomplete, Refactoring)\n- ✅ Selbstdokumentierender Code durch Typen\n- ✅ Bessere Wartbarkeit\n- ❌ Kompilierungsschritt erforderlich\n- ❌ Lernkurve für Beitragende\n- ❌ Verboserer Code\n\n**Betrachtete Alternativen:**\n\n- JavaScript mit JSDoc: Begrenzte Typ-Überprüfung\n- Flow: Weniger Ökosystem-Support als TypeScript\n- Reines JavaScript: Zu fehleranfällig für große Codebasis\n- Reason/ReScript: Zu nischig, begrenzte Adoption\n\n### ADR-007: pnpm Workspace Monorepo verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nKoliBri besteht aus vielen Paketen (Komponenten, Themes, Adapter, Tools), die zusammen entwickelt, aber unabhängig released werden müssen.\n\n**Entscheidung:**\npnpm Workspace als Monorepo-Lösung mit Nx für Build-Orchestrierung verwenden.\n\n**Konsequenzen:**\n\n- ✅ Effizientes Abhängigkeitsmanagement\n- ✅ Geteilte Abhängigkeiten (Festplattenplatz-Einsparungen)\n- ✅ Strikte Abhängigkeitsauflösung (keine Phantom-Abhängigkeiten)\n- ✅ Schnelle Installationen\n- ✅ Nx bietet intelligentes Caching und Task-Orchestrierung\n- ❌ Komplexeres Setup als einzelnes Paket\n- ❌ pnpm weniger verbreitet als npm/yarn\n- ❌ Steilere Lernkurve für neue Beitragende\n\n**Betrachtete Alternativen:**\n\n- npm-Workspaces: Weniger effizient als pnpm\n- Yarn-Workspaces: Phantom-Abhängigkeits-Problem\n- Lerna: Overhead ohne pnpm-Vorteile\n- Separate Repositories: Koordinations-Alptraum\n\n### ADR-008: Fünf-Schichten-Styling-Architektur\n\n**Status:** Akzeptiert\n\n**Kontext:**\nStyling muss zwischen Barrierefreiheitsanforderungen, Layout-Struktur und visuellem Design getrennt werden. Teams müssen Erscheinungsbild anpassen können, ohne Barrierefreiheit oder Layout zu brechen.\n\n**Entscheidung:**\nFünf-Schichten-Styling-Architektur implementieren:\n\n1. A11y-Preset-Schicht (Barrierefreiheits-Baseline)\n2. Basis Global-Schicht (globales Layout)\n3. Basis Komponenten-Schicht (Komponenten-Layout)\n4. Theme Global-Schicht (globales Theme)\n5. Theme Komponenten-Schicht (Komponenten-Theme)\n\n**Konsequenzen:**\n\n- ✅ Klare Trennung der Verantwortlichkeiten\n- ✅ Barrierefreiheit kann nicht versehentlich gebrochen werden\n- ✅ Themes können Erscheinungsbild anpassen ohne Layout zu brechen\n- ✅ Vorhersagbare Style-Präzedenz\n- ❌ Anfangs komplexer zu verstehen\n- ❌ Mehr Dateien zu warten\n- ❌ Strikte Konventionen erforderlich\n\n**Betrachtete Alternativen:**\n\n- Flache CSS-Struktur: Zu einfach, Dinge zu brechen\n- Zwei-Schichten (Komponente + Theme): Unzureichende Trennung\n- Nur Theme-Styling: Barrierefreiheit nicht garantiert\n- Inline-Styles mit Theme-Tokens: Nicht wartbar\n\n### ADR-009: CSS Custom Properties minimieren\n\n**Status:** Akzeptiert\n\n**Kontext:**\nCSS Custom Properties (Variablen) durchqueren die Shadow-DOM-Grenze und bleiben in der globalen Cascade. Übermäßige Verwendung kann zu Namenskonflikten und unvorhersagbarem Verhalten führen.\n\n**Entscheidung:**\nCSS Custom Properties sparsam verwenden, nur für Werte, die von außen anpassbar sein müssen. SASS-Variablen für interne Berechnungen verwenden.\n\n**Konsequenzen:**\n\n- ✅ Verhindert Variablen-Namenskonflikte\n- ✅ Robustere Komponenten\n- ✅ Klarere API-Oberfläche\n- ✅ Weniger Verwirrung darüber, was anpassbar ist\n- ❌ Weniger Flexibilität für fortgeschrittene Nutzer\n- ❌ Mehr SASS-Kompilierung erforderlich\n\n**Betrachtete Alternativen:**\n\n- Starke Nutzung von CSS Custom Properties: Zu viele Konflikte\n- Keine CSS Custom Properties: Nicht anpassbar genug\n- Alles als Custom Properties: Globale Namespace-Verschmutzung\n- Nur komponentenspezifische Präfixe: Birgt noch Konfliktrisiko\n\n### ADR-010: LTS/STS Release-Modell\n\n**Status:** Akzeptiert\n\n**Kontext:**\nUnternehmen benötigen stabile, langfristig unterstützte Versionen. Innovation erfordert schnelle Iteration. Diese Bedürfnisse sind im Konflikt.\n\n**Entscheidung:**\nDuales Release-Modell implementieren:\n\n- **LTS (Long-Term Support)**: 3 Jahre Support, konservative Änderungen\n- **STS (Short-Term Support)**: 15 Monate Support, schnelle Innovation\n\n**Konsequenzen:**\n\n- ✅ Unternehmen erhalten Stabilität (LTS)\n- ✅ Innovation setzt sich fort (STS)\n- ✅ Klare Erwartungen an Support-Dauer\n- ✅ Vorhersagbare Upgrade-Zyklen\n- ❌ Mehr Versionen zu warten\n- ❌ Komplexeres Release-Management\n- ❌ Dokumentation für mehrere Versionen\n\n**Betrachtete Alternativen:**\n\n- Einzelne Release-Linie: Kann Stabilität und Innovation nicht ausbalancieren\n- Nur LTS: Verlangsamt Innovation\n- Nur STS: Keine Unternehmens-Adoption\n- Mehrere gleichzeitige Majors: Zu viel Wartung\n\n### ADR-011: Strikte Einhaltung semantischer Versionierung\n\n**Status:** Akzeptiert\n\n**Kontext:**\nNutzer müssen darauf vertrauen können, dass Updates ihre Anwendungen nicht unerwartet brechen. Klare Versionierung hilft beim Abhängigkeitsmanagement.\n\n**Entscheidung:**\nStrikte Einhaltung der Semantic Versioning 2.0:\n\n- Major: Breaking Changes\n- Minor: Neue Features, rückwärtskompatibel\n- Patch: Bugfixes, rückwärtskompatibel\n\n**Konsequenzen:**\n\n- ✅ Vorhersagbare Upgrade-Sicherheit\n- ✅ Klare Kommunikation von Änderungen\n- ✅ Besseres Abhängigkeitsmanagement\n- ✅ Vertrauen von der Community\n- ❌ Hauptversionen können häufig kommen\n- ❌ Deprecation-Prozess braucht Zeit\n- ❌ Design-Fehler können nicht einfach behoben werden\n\n**Betrachtete Alternativen:**\n\n- Rolling Releases: Unvorhersagbar, riskant\n- Kalender-Versionierung: Kommuniziert keine Breaking Changes\n- Lockeres SemVer: Untergräbt Vertrauen\n- Für immer Pre-1.0: Signalisiert Instabilität\n\n### ADR-012: Framework-Adapter auto-generieren\n\n**Status:** Akzeptiert\n\n**Kontext:**\nDie Unterstützung mehrerer Frameworks (React, Angular, Vue, etc.) erfordert Framework-spezifische Wrapper. Diese manuell zu warten wäre zeitaufwändig und fehleranfällig.\n\n**Entscheidung:**\nStencil Output Targets verwenden, um Framework-Adapter automatisch aus Komponentendefinitionen zu generieren.\n\n**Konsequenzen:**\n\n- ✅ Keine manuelle Adapter-Wartung\n- ✅ Konsistente APIs über Frameworks hinweg\n- ✅ Automatische Updates wenn Komponenten sich ändern\n- ✅ Weniger Code zu warten\n- ❌ Abhängig von Stencil Output Target Qualität\n- ❌ Begrenzte Kontrolle über generierten Code\n- ❌ Framework-spezifische Eigenheiten schwerer zu adressieren\n\n**Betrachtete Alternativen:**\n\n- Manuelle Adapter: Zu viel Wartung\n- Einzelnes Framework: Verletzt Framework-agnostisches Ziel\n- Keine Adapter (Web Components direkt nutzen): Schlechte DX in einigen Frameworks\n- Separate Adapter-Projekte: Koordinations-Overhead\n\n### ADR-013: SLSA Build Level 3 für Supply-Chain-Sicherheit\n\n**Status:** Akzeptiert\n\n**Kontext:**\nSupply-Chain-Angriffe nehmen zu. Nutzer benötigen Gewissheit, dass veröffentlichte Pakete nicht manipuliert wurden und aus verifiziertem Quellcode gebaut wurden.\n\n**Entscheidung:**\nSLSA Build Level 3 mit npm Provenance für alle veröffentlichten Pakete implementieren.\n\n**Konsequenzen:**\n\n- ✅ Verifizierbare Build-Provenance\n- ✅ Supply-Chain-Sicherheit\n- ✅ Erhöhtes Vertrauen von Nutzern\n- ✅ Erfüllt Behörden-/Unternehmens-Sicherheitsanforderungen\n- ❌ Komplexeres CI/CD-Setup\n- ❌ Erfordert GitHub OIDC-Konfiguration\n- ❌ npm Provenance-Support erforderlich\n\n**Betrachtete Alternativen:**\n\n- Keine Provenance: Weniger sicher, erfüllt einige Anforderungen nicht\n- SLSA Level 1/2: Unzureichende Sicherheitsgarantien\n- Selbstsignierte Signaturen: Nicht vom Ökosystem verifizierbar\n- Nur Paketsignierung: Beweist nicht die Quelle\n\n### ADR-014: Playwright für E2E-Testing verwenden\n\n**Status:** Akzeptiert\n\n**Kontext:**\nKomponenten benötigen End-to-End-Tests über mehrere Browser. Test-Framework sollte moderne Webtechnologien einschließlich Web Components und Shadow DOM unterstützen.\n\n**Entscheidung:**\nPlaywright als E2E-Test-Framework verwenden.\n\n**Konsequenzen:**\n\n- ✅ Hervorragende Shadow-DOM-Unterstützung\n- ✅ Multi-Browser-Testing (Chromium, Firefox, WebKit)\n- ✅ Schnell und zuverlässig\n- ✅ Gute Entwicklererfahrung\n- ✅ Eingebaute Barrierefreiheits-Tests (axe-core-Integration)\n- ❌ Lernkurve für Beitragende\n- ❌ Test-Wartungs-Overhead\n\n**Betrachtete Alternativen:**\n\n- Cypress: Schwächere Shadow-DOM-Unterstützung zur Zeit der Entscheidung\n- Puppeteer: Nur Chrome, weniger Features\n- Selenium: Älter, langsamer, komplexer\n- TestCafe: Weniger Ökosystem-Support\n\n### ADR-015: Automatisches komponentenbasiertes Lazy Loading via Stencil\n\n**Status:** Akzeptiert\n\n**Kontext:**\nAnwendungen mit KoliBri benötigen möglicherweise nicht alle 50+ Komponenten sofort geladen. Bundle-Größe und Performance sind kritische Belange für Webanwendungen.\n\n**Entscheidung:**\nAuf Stencils eingebaute Lazy-Loading- und Code-Splitting-Fähigkeiten vertrauen, die automatisch nur die tatsächlich in der Anwendung verwendeten Komponenten auf Komponentenbasis laden.\n\n**Konsequenzen:**\n\n- ✅ Komponenten automatisch on-demand geladen, wenn erstmalig verwendet\n- ✅ Keine manuelle Konfiguration für Lazy Loading erforderlich\n- ✅ Minimale initiale Bundle-Größe\n- ✅ Optimale Performance ohne Entwicklereingriff\n- ✅ Jede Komponente in separates Bundle für effizientes Laden kompiliert\n- ❌ Erfordert moderne Bundler-Unterstützung für ES-Module\n- ❌ Zusätzliche HTTP-Requests für jede Komponente (durch HTTP/2 gemildert)\n\n**Betrachtete Alternativen:**\n\n- In Kategorie-Pakete aufteilen: Komplexere Wartung, weniger flexibel\n- Einzelnes monolithisches Bundle: Größerer initialer Ladevorgang, langsamere Performance\n- Manuelles Lazy Loading: Mehr Entwickler-Aufwand, fehleranfällig\n\n### ADR-016: SASS-Variablen für Basis-Theme (Keine Design-Tokens)\n\n**Status:** Akzeptiert\n\n**Kontext:**\nDesign-Tokens (CSS Custom Properties) werden für Theming populär, aber sie durchqueren die Shadow-DOM-Grenze und können von außen manipuliert werden, was potenziell das Erscheinungsbild der Komponente brechen und Robustheit reduzieren kann.\n\n**Entscheidung:**\nSASS-Variablen exklusiv für interne Berechnungen und Styling im Basis-Theme verwenden. Organisationen können optional Design-Tokens in ihren benutzerdefinierten Themes verwenden, aber das Basis-Theme vermeidet sie zur Aufrechterhaltung der Komponenten-Robustheit und Vermeidung externer Manipulation.\n\n**Konsequenzen:**\n\n- ✅ Komponenten bleiben robust und vorhersagbar in allen Umgebungen\n- ✅ Keine externe Manipulation von Komponenten-Interna via CSS-Variablen\n- ✅ Ähnliche Wartbarkeitsvorteile wie Design-Tokens (Variablen, Berechnungen)\n- ✅ Organisationen frei, Design-Tokens in benutzerdefinierten Themes zu verwenden\n- ✅ Klare Trennung zwischen komponenten-internem Styling und externer Anpassung\n- ❌ Weniger Runtime-Flexibilität im Vergleich zu CSS Custom Properties\n- ❌ Theme-Änderungen erfordern Rekompilierung statt Runtime-Updates\n- ❌ Kann einige moderne CSS-Features nicht nutzen, die auf Custom Properties basieren\n\n**Betrachtete Alternativen:**\n\n- Starke Nutzung von CSS Custom Properties: Externes Manipulationsrisiko, weniger robust\n- Design Tokens W3C-Format: Gleiche Probleme wie CSS Custom Properties für Basis-Theme\n- Keine Variablen überhaupt: Schlechte Wartbarkeit, Code-Duplizierung\n- Nur komponenten-spezifische CSS-Variablen: Durchquert noch Shadow-DOM-Grenze\n\n## 9.2 Offene Entscheidungen\n\nDiese Entscheidungen werden in Betracht gezogen und werden in zukünftigen Planungszyklen adressiert, während sich das Projekt weiterentwickelt und neue Anforderungen aufkommen.\n\n### OD-001: Server-Side-Rendering-Strategie\n\n**Status:** Offen\n\n**Kontext:**\nSSR-Unterstützung für Web Components ist komplex. Aktueller Hydrate-Adapter ist begrenzt. Vollständige SSR-Lösung für einige Anwendungsfälle benötigt.\n\n**Optionen:**\n\n1. Bestehenden Hydrate-Adapter verbessern\n2. Declarative Shadow DOM Ansatz\n3. Mit SSR-Framework-Projekten zusammenarbeiten\n4. Einschränkungen und Workarounds dokumentieren\n\n**Entscheidungszeitlinie:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/10-quality-requirements",
+      "group": "docs/arc42_de",
+      "name": "10-quality-requirements",
+      "path": "docs/arc42_de/10-quality-requirements.md",
+      "code": "# 10. Qualitätsanforderungen\n\nDieser Abschnitt definiert die konkreten Qualitätsziele für Public UI - KoliBri durch messbare Szenarien und Akzeptanzkriterien. Er übersetzt die abstrakten Qualitätsziele aus Abschnitt 1 in spezifische, testbare Anforderungen, die Entwicklungs- und Validierungsbemühungen leiten.\n\n## 10.1 Qualitätsbaum\n\n```mermaid\ngraph TB\n    Quality[Qualitätsanforderungen]\n\n    Quality --> Accessibility\n    Quality --> Maintainability\n    Quality --> Performance\n    Quality --> Usability\n    Quality --> Compatibility\n    Quality --> Security\n\n    Accessibility --> A1[WCAG 2.1 AA Konformität]\n    Accessibility --> A2[Screenreader-Unterstützung]\n    Accessibility --> A3[Tastaturnavigation]\n\n    Maintainability --> M1[Code-Qualität]\n    Maintainability --> M2[Dokumentation]\n    Maintainability --> M3[Test-Abdeckung]\n\n    Performance --> P1[Bundle-Größe]\n    Performance --> P2[Rendering-Geschwindigkeit]\n    Performance --> P3[Speichernutzung]\n\n    Usability --> U1[Entwicklererfahrung]\n    Usability --> U2[Klare Dokumentation]\n    Usability --> U3[Fehlermeldungen]\n\n    Compatibility --> C1[Framework-Unterstützung]\n    Compatibility --> C2[Browser-Unterstützung]\n    Compatibility --> C3[Versionsstabilität]\n\n    Security --> S1[Keine Schwachstellen]\n    Security --> S2[Sichere Standards]\n    Security --> S3[Build-Provenance]\n```\n\n## 10.2 Qualitätsszenarien\n\n### Barrierefreiheits-Szenarien\n\n#### Szenario A1: Screenreader-Navigation\n\n**Qualitätsziel:** Vollständige Barrierefreiheit für Screenreader-Nutzer\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer mit Screenreader navigiert Anwendung |\n| **Umgebung** | Produktions-Webanwendung, JAWS/NVDA/VoiceOver |\n| **Reaktion** | Alle Komponenten kündigen korrekt an, Tastaturnavigation funktioniert |\n| **Messung** | 100% der interaktiven Komponenten über Screenreader zugänglich |\n\n**Akzeptanzkriterien:**\n\n- Screenreader kündigt Komponenten-Rolle, Name und State an\n- Nutzer kann alle interaktiven Elemente über Tastatur aktivieren\n- Fokus-Reihenfolge ist logisch und vorhersagbar\n- Dynamische Änderungen über ARIA-Live-Regions angekündigt\n\n#### Szenario A2: Tastaturnavigation\n\n**Qualitätsziel:** Vollständiger Tastaturzugriff auf alle Funktionalität\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer navigiert Anwendung nur mit Tastatur |\n| **Umgebung** | Jeder moderne Browser |\n| **Reaktion** | Alle interaktiven Elemente zugänglich, Fokus sichtbar |\n| **Messung** | 100% der Features mit Tastatur allein nutzbar |\n\n**Akzeptanzkriterien:**\n\n- Tab-Taste bewegt Fokus durch alle interaktiven Elemente\n- Enter/Space aktiviert Buttons und Controls\n- Pfeiltasten navigieren innerhalb zusammengesetzter Widgets (Menüs, Tabs)\n- Escape schließt Modale Dialoge und Dropdowns\n- Fokus-Indikatoren immer sichtbar (3px Outline, 3:1 Kontrast)\n\n#### Szenario A3: Farbkontrast\n\n**Qualitätsziel:** Ausreichender Kontrast für Lesbarkeit\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer mit Sehschwäche betrachtet Komponenten |\n| **Umgebung** | Jeder Browser, Standard-Theme |\n| **Reaktion** | Alle Texte und UI-Elemente erfüllen Kontrastanforderungen |\n| **Messung** | 100% der Elemente erfüllen WCAG AA Kontrastverhältnisse |\n\n**Akzeptanzkriterien:**\n\n- Normaler Text (< 18pt): Minimum 4,5:1 Kontrast\n- Großer Text (≥ 18pt): Minimum 3:1 Kontrast\n- UI-Komponenten: Minimum 3:1 Kontrast\n- Fokus-Indikatoren: Minimum 3:1 Kontrast\n- Automatisierte wcag-contrast-Bibliotheksvalidierung\n\n### Performance-Szenarien\n\n#### Szenario P1: Initiale Ladezeit\n\n**Qualitätsziel:** Schneller initialer Seitenladevorgang\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer öffnet Anwendung zum ersten Mal |\n| **Umgebung** | 4G Mobilverbindung, Mittelklasse-Gerät |\n| **Reaktion** | Seite lädt und wird schnell interaktiv |\n| **Messung** | Time to Interactive < 3,8 Sekunden |\n\n**Akzeptanzkriterien:**\n\n- First Contentful Paint < 1,8s\n- Time to Interactive < 3,8s\n- Total Blocking Time < 300ms\n\n#### Szenario P2: Komponenten-Laden\n\n**Qualitätsziel:** Lazy-Loading-Effizienz\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer begegnet neuem Komponententyp |\n| **Umgebung** | Anwendung bereits geladen |\n| **Reaktion** | Komponente lädt ohne merkliche Verzögerung |\n| **Messung** | Komponente erscheint innerhalb von 200ms |\n\n**Akzeptanzkriterien:**\n\n- Individuelle Komponenten-Bundles < 50KB\n- Komponente lädt in < 200ms auf 4G\n- Kein Layout-Shift wenn Komponente erscheint\n- Lazy Loading funktioniert korrekt\n\n#### Szenario P3: Theme-Wechsel\n\n**Qualitätsziel:** Sofortige Theme-Änderungen\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer wechselt Theme (Dark Mode, hoher Kontrast) |\n| **Umgebung** | Anwendung mit mehreren gerenderten Komponenten |\n| **Reaktion** | Theme ändert sich sofort über alle Komponenten |\n| **Messung** | Visuelle Änderung innerhalb von 16ms (ein Frame) |\n\n**Akzeptanzkriterien:**\n\n- Theme-Wechsel abgeschlossen in < 16ms\n- Kein Neu-Rendering von Komponenten erforderlich\n- Keine Layout-Shifts während Theme-Änderung\n- Speichernutzung bleibt stabil\n\n### Wartbarkeits-Szenarien\n\n#### Szenario M1: Neue Komponente hinzufügen\n\n**Qualitätsziel:** Einfaches Hinzufügen neuer Komponenten\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Entwickler fügt neue Komponente zur Bibliothek hinzu |\n| **Umgebung** | Entwicklungsumgebung, frisches Checkout |\n| **Reaktion** | Komponente funktioniert mit allen Themes und Frameworks |\n| **Messung** | Neue Komponente integriert in < 8 Stunden |\n\n**Akzeptanzkriterien:**\n\n- Komponenten-Scaffolding verfügbar\n- Klare Dokumentation für Komponentenerstellung\n- Automatisierte Tests bestehen\n- Framework-Adapter automatisch generiert\n- Visual-Regression-Tests erstellt\n\n#### Szenario M2: Bug beheben\n\n**Qualitätsziel:** Schnelle und sichere Bugfixes\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Bug in Produktions-Komponente gemeldet |\n| **Umgebung** | Komponente mit existierenden Tests |\n| **Reaktion** | Bug behoben ohne andere Features zu brechen |\n| **Messung** | Fix und Verifizierung in < 4 Stunden |\n\n**Akzeptanzkriterien:**\n\n- Bug reproduzierbar via Test\n- Fix bricht keine existierenden Tests\n- Regressions-Test hinzugefügt\n- Alle automatisierten Checks bestehen\n- PR reviewed und gemerged\n\n#### Szenario M3: Major-Version-Upgrade\n\n**Qualitätsziel:** Reibungslose Versions-Upgrades\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Anwendung muss von v3 auf v4 upgraden |\n| **Umgebung** | Große Anwendung mit vielen Komponenten |\n| **Reaktion** | Upgrade mit minimalen manuellen Änderungen abgeschlossen |\n| **Messung** | 90% der Änderungen via Migrations-Tool automatisiert |\n\n**Akzeptanzkriterien:**\n\n- Migrations-Leitfaden verfügbar\n- CLI-Tool automatisiert Code-Änderungen\n- Breaking Changes dokumentiert\n- Deprecated Features funktionieren noch mit Warnungen\n- Parallele Versionsunterstützung für Übergang\n\n### Benutzbarkeits-Szenarien\n\n#### Szenario U1: Erste Komponenten-Integration\n\n**Qualitätsziel:** Einfach für neue Entwickler\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Neuer Entwickler integriert erste Komponente |\n| **Umgebung** | React/Angular/Vue-Anwendung |\n| **Reaktion** | Komponente funktioniert ohne Probleme |\n| **Messung** | Funktionierende Integration in < 15 Minuten |\n\n**Akzeptanzkriterien:**\n\n- Schnellstart-Leitfaden verfügbar\n- Installation mit einzelnem Befehl\n- Beispiel-Code funktioniert Copy-Paste\n- TypeScript-Typen funktionieren in IDE\n- Klare Fehlermeldungen bei Fehlkonfiguration\n\n#### Szenario U2: Komponenten-Problem debuggen\n\n**Qualitätsziel:** Einfaches Debugging\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Komponente rendert nicht wie erwartet |\n| **Umgebung** | Browser-Dev-Tools |\n| **Reaktion** | Entwickler identifiziert und behebt Problem |\n| **Messung** | Problem identifiziert in < 10 Minuten |\n\n**Akzeptanzkriterien:**\n\n- Shadow DOM in Dev Tools inspizierbar\n- Klare Konsolen-Warnungen für ungültige Props\n- Hilfreiche Fehlermeldungen\n- Dokumentation erklärt häufige Probleme\n- Komponenten-State in Dev Tools sichtbar\n\n#### Szenario U3: Benutzerdefiniertes Theme erstellen\n\n**Qualitätsziel:** Einfache Theme-Anpassung\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Designer möchte Markenfarben anwenden |\n| **Umgebung** | SASS/CSS-Kenntnisse, Design-System |\n| **Reaktion** | Benutzerdefiniertes Theme erstellt und angewendet |\n| **Messung** | Basis-Theme in < 2 Stunden |\n\n**Akzeptanzkriterien:**\n\n- Theme-Template verfügbar\n- Dokumentation erklärt Theming-System\n- SASS-Variablen dokumentiert\n- Beispiel-Themes als Referenz\n- Visual-Regression-Tests bereitgestellt\n\n### Kompatibilitäts-Szenarien\n\n#### Szenario C1: Framework-Integration\n\n**Qualitätsziel:** Funktioniert mit jedem großen Framework\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Entwickler verwendet Komponente in React/Angular/Vue |\n| **Umgebung** | Neueste Framework-Version |\n| **Reaktion** | Komponente funktioniert natürlich im Framework |\n| **Messung** | 100% der Features funktionieren in allen unterstützten Frameworks |\n\n**Akzeptanzkriterien:**\n\n- Framework-Adapter verfügbar\n- Framework-spezifische Muster unterstützt\n- TypeScript-Typen funktionieren\n- Events integrieren mit Framework-Event-System\n- Props folgen Framework-Konventionen\n\n#### Szenario C2: Browser-Unterstützung\n\n**Qualitätsziel:** Funktioniert in allen modernen Browsern\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Nutzer öffnet Anwendung im Browser |\n| **Umgebung** | Chrome, Firefox, Safari, Edge (neueste 2 Versionen) |\n| **Reaktion** | Komponenten rendern und funktionieren korrekt |\n| **Messung** | 100% Feature-Parität über Browser hinweg |\n\n**Akzeptanzkriterien:**\n\n- Visuelles Erscheinungsbild konsistent\n- Alle Features funktional\n- Performance akzeptabel\n- Keine Konsolen-Fehler\n- Automatisierte Cross-Browser-Tests\n\n#### Szenario C3: Versionskompatibilität\n\n**Qualitätsziel:** Reibungslose Upgrades zwischen Versionen\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Anwendung verwendet ältere Komponentenversion |\n| **Umgebung** | Produktions-Anwendung |\n| **Reaktion** | Kann ohne Breaking Changes upgraden (innerhalb Major) |\n| **Messung** | Null Breaking Changes in Minor/Patch-Versionen |\n\n**Akzeptanzkriterien:**\n\n- SemVer strikt befolgt\n- Deprecation-Warnungen vor Entfernung\n- LTS-Version erhält Sicherheitsfixes\n- Klarer Upgrade-Pfad dokumentiert\n- Migrations-Tool für Hauptversionen verfügbar\n\n### Sicherheits-Szenarien\n\n#### Szenario S1: Keine XSS-Schwachstellen\n\n**Qualitätsziel:** Cross-Site-Scripting verhindern\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Anwendung übergibt Nutzereingabe an Komponente |\n| **Umgebung** | Komponente mit Textinhalt |\n| **Reaktion** | Bösartige Scripts werden nicht ausgeführt |\n| **Messung** | Null XSS-Schwachstellen |\n\n**Akzeptanzkriterien:**\n\n- Alle Nutzereingaben bereinigt\n- Shadow DOM bietet Isolation\n- Kein innerHTML mit Nutzerinhalt\n- CSP-kompatibel\n- Automatisiertes Sicherheits-Scanning besteht\n\n#### Szenario S2: Abhängigkeits-Schwachstellen\n\n**Qualitätsziel:** Keine verwundbaren Abhängigkeiten\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Sicherheitsschwachstelle in Abhängigkeit offengelegt |\n| **Umgebung** | Produktions-Anwendung |\n| **Reaktion** | Schwachstelle schnell gepatcht |\n| **Messung** | Kritische Schwachstellen innerhalb von 24 Stunden behoben |\n\n**Akzeptanzkriterien:**\n\n- Automatisiertes Schwachstellen-Scanning\n- Dependabot-Warnungen aktiviert\n- Regelmäßige Abhängigkeits-Updates\n- Sicherheits-Patches priorisiert\n- Nutzer über Sicherheitsupdates informiert\n\n#### Szenario S3: Build-Sicherheit\n\n**Qualitätsziel:** Verifizierbare Build-Provenance\n\n| Aspekt | Details |\n|--------|---------|\n| **Stimulus** | Organisation auditiert Abhängigkeiten |\n| **Umgebung** | Veröffentlichte npm-Pakete |\n| **Reaktion** | Build-Provenance verifizierbar |\n| **Messung** | SLSA Build Level 3 Konformität |\n\n**Akzeptanzkriterien:**\n\n- Builds in GitHub Actions mit OIDC\n- Mit npm Provenance veröffentlicht\n- Signierte Attestierungen verfügbar\n- Reproduzierbare Builds\n- Supply-Chain-Sicherheit validiert\n\n## 10.3 Qualitätsmetriken\n\n| Qualitätsattribut | Metrik | Ziel | Messmethode |\n|-------------------|--------|--------|-------------------|\n| **Barrierefreiheit** | WCAG 2.1 AA Konformität | 100% | Manuelles Testing + axe-core |\n| **Barrierefreiheit** | Tastaturnavigation | 100% | Manuelles Testing |\n| **Performance** | Time to Interactive | < 3,8s | WebPageTest |\n| **Performance** | Bundle-Größe | < 50KB pro Komponente | Bundlephobia-Analyse |\n| **Wartbarkeit** | Test-Abdeckung | > 80% | Jest-Coverage-Report |\n| **Wartbarkeit** | Code-Duplizierung | < 5% | SonarQube/manuelle Überprüfung |\n| **Sicherheit** | Schwachstellen | 0 kritisch/hoch | Dependabot, CodeQL |\n| **Benutzbarkeit** | Zeit bis zur ersten Komponente | < 15 min | Nutzer-Testing |\n| **Kompatibilität** | Browser-Unterstützung | Neueste 2 Versionen | Automatisiertes Testing |\n| **Qualität** | Linting-Fehler | 0 | ESLint, Stylelint |\n| **Qualität** | Typ-Fehler | 0 | TypeScript-Compiler |\n\n## 10.4 Qualitätssicherungs-Methoden\n\n| Methode | Zweck | Frequenz | Verantwortlich |\n|--------|---------|-----------|-------------|\n| **Automatisierte Tests** | Regressionen abfangen | Jeder Commit | CI/CD |\n| **Code-Review** | Qualität sicherstellen | Jeder PR | Team-Mitglieder |\n| **Barrierefreiheits-Audit** | WCAG-Konformität | Jede Komponente | A11y-Spezialisten |\n| **Performance-Testing** | Performance überwachen | Wöchentlich | Automatisierte Tests |\n| **Sicherheits-Scanning** | Schwachstellen finden | Jeder Commit | CodeQL, Dependabot |\n| **Nutzer-Testing** | Benutzbarkeit validieren | Vor Major-Releases | UX-Team |\n| **Visual Regression** | Visuelle Änderungen erkennen | Jede Theme-Änderung | Visual Tests |\n| **Manuelle Tests** | Exploratives Testing | Vor Releases | QA-Team |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/11-risks-and-technical-debt",
+      "group": "docs/arc42_de",
+      "name": "11-risks-and-technical-debt",
+      "path": "docs/arc42_de/11-risks-and-technical-debt.md",
+      "code": "# 11. Risiken und technische Schulden\n\nDieser Abschnitt identifiziert und bewertet potenzielle Risiken für das Public UI - KoliBri Projekt zusammen mit aktuellen technischen Schulden. Das Verständnis dieser Faktoren hilft, Mitigierungsbemühungen zu priorisieren und nachhaltige langfristige Entwicklung zu planen.\n\n## 11.1 Identifizierte Risiken\n\n### Risiko R1: Browser-API-Änderungen\n\n**Beschreibung:** Web-Component-APIs (Custom Elements, Shadow DOM) könnten sich ändern oder deprecated werden.\n\n**Wahrscheinlichkeit:** Niedrig\n**Auswirkung:** Hoch\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- APIs sind W3C-Standards (stabil)\n- W3C-Spezifikationen auf Änderungen überwachen\n- Polyfills für ältere Browser verfügbar\n- Aktive Teilnahme in Web-Component-Community\n\n**Notfallplan:**\n\n- Adapter-Schicht zwischen Komponenten und Browser-APIs implementieren\n- Alternative Technologien evaluieren falls nötig\n- Community würde wahrscheinlich Migrationspfade bereitstellen\n\n### Risiko R2: Stencil.js-Wartung\n\n**Beschreibung:** Stencil.js-Projekt könnte aufgegeben werden oder inkompatibel mit zukünftigen Web-Component-Standards werden.\n\n**Wahrscheinlichkeit:** Niedrig\n**Auswirkung:** Hoch\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- Stencil von Ionic-Team gewartet (starke Unterstützung)\n- Große Community und Unternehmensnutzer\n- Regelmäßige Releases und aktive Entwicklung\n- Stencil generiert Standard-Web-Components\n\n**Notfallplan:**\n\n- Stencil forken und warten falls notwendig\n- Zu alternativem Compiler migrieren (Lit, custom Solution)\n- Generierte Komponenten würden weiterhin funktionieren\n\n### Risiko R3: Framework-Kompatibilität\n\n**Beschreibung:** Große Frameworks könnten sich auf Weise ändern, die Web-Component-Integration brechen.\n\n**Wahrscheinlichkeit:** Mittel\n**Auswirkung:** Mittel\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- Web Components sind Framework-agnostisch by Design\n- Meiste Frameworks verbessern Web-Component-Support\n- Stencil Output Targets behandeln Framework-spezifische Eigenheiten\n- Regelmäßige Tests mit neuesten Framework-Versionen\n\n**Notfallplan:**\n\n- Framework-Adapter nach Bedarf aktualisieren\n- Mit Framework-Maintainern an Kompatibilität arbeiten\n- Framework-spezifische Workarounds dokumentieren\n- Support für problematische Frameworks ggf. einstellen\n\n### Risiko R4: Barrierefreiheits-Standard-Änderungen\n\n**Beschreibung:** WCAG- oder BITV-Standards könnten neue Anforderungen einführen.\n\n**Wahrscheinlichkeit:** Mittel\n**Auswirkung:** Mittel\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- WCAG-Arbeitsgruppe überwachen\n- Architektur erlaubt Hinzufügen von Barrierefreiheits-Features\n- Regelmäßige Barrierefreiheits-Audits\n- Community-Feedback zu Barrierefreiheit\n\n**Notfallplan:**\n\n- Komponenten aktualisieren, um neue Standards zu erfüllen\n- Migrations-Leitfäden für Breaking Changes bereitstellen\n- Nicht-konforme Features schrittweise deprecaten\n\n### Risiko R5: Performance-Regression\n\n**Beschreibung:** Komponenten-Ergänzungen oder -Änderungen könnten Performance verschlechtern.\n\n**Wahrscheinlichkeit:** Mittel\n**Auswirkung:** Mittel\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- Bundle-Größen-Monitoring\n- Performance-Budgets\n- Regelmäßiges Performance-Profiling\n\n**Notfallplan:**\n\n- Performance-Review vor Major-Releases\n- Kritische Komponenten optimieren\n- Performance-Best-Practices-Dokumentation bereitstellen\n- Performance-fokussierte Komponenten-Varianten erwägen\n\n### Risiko R6: Sicherheitsschwachstellen\n\n**Beschreibung:** Komponenten oder Abhängigkeiten könnten Sicherheitsschwachstellen haben.\n\n**Wahrscheinlichkeit:** Mittel\n**Auswirkung:** Hoch\n**Risikolevel:** Hoch\n\n**Mitigierung:**\n\n- Automatisiertes Abhängigkeits-Scanning (Dependabot)\n- CodeQL-Sicherheitsanalyse\n- Regelmäßige Abhängigkeits-Updates\n- Sicherheitsfokussierte Code-Reviews\n- SLSA Build Level 3 Provenance\n\n**Notfallplan:**\n\n- Notfall-Patch-Releases\n- Sicherheitsadvisory-Veröffentlichung\n- Direkte Benachrichtigung betroffener Nutzer\n- Temporäre Workarounds dokumentiert\n\n### Risiko R7: Breaking Changes in Hauptversionen\n\n**Beschreibung:** Major-Version-Upgrades könnten schwierig sein und Adoption entmutigen.\n\n**Wahrscheinlichkeit:** Hoch\n**Auswirkung:** Mittel\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- Klarer Deprecation-Prozess\n- Migrations-Leitfäden für alle Breaking Changes\n- Automatisiertes Migrations-CLI-Tool\n- LTS-Versionen für Stabilität\n\n**Notfallplan:**\n\n- LTS-Support nach Bedarf verlängern\n- Professionellen Migrations-Support bereitstellen\n- Detaillierte Migrations-Dokumentation erstellen\n- Migrations-Workshops anbieten\n\n### Risiko R8: Theme-Inkompatibilität\n\n**Beschreibung:** Theme-Updates könnten mit neuen Komponentenversionen brechen.\n\n**Wahrscheinlichkeit:** Mittel\n**Auswirkung:** Mittel\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- Semantische Versionierung für Themes\n- Theme-Komponenten-Kompatibilitätsmatrix\n- Visual-Regression-Tests\n- Theme-Template-Dokumentation\n\n**Notfallplan:**\n\n- Mehrere Theme-Versionen warten\n- Theme-Migrations-Leitfäden bereitstellen\n- Automatisierte Theme-Update-Tools\n- Community-Theme-Support\n\n### Risiko R9: Community-Adoption\n\n**Beschreibung:** Unzureichende Community-Adoption könnte zu Projekt-Stagnation führen.\n\n**Wahrscheinlichkeit:** Niedrig\n**Auswirkung:** Hoch\n**Risikolevel:** Mittel\n\n**Mitigierung:**\n\n- Klare Dokumentation und Beispiele\n- Aktive Kommunikation und Support\n- Regelmäßige Releases mit Verbesserungen\n- Projekte, die KoliBri verwenden, zeigen\n- Konferenz-Vorträge und Blog-Posts\n\n**Notfallplan:**\n\n- Marketing-Bemühungen verstärken\n- Mit Organisationen partnern\n- Onboarding-Erfahrung verbessern\n- Nutzer-Feedback sammeln und umsetzen\n\n### Risiko R10: Build-System-Komplexität\n\n**Beschreibung:** Monorepo-Build-Komplexität könnte Entwicklung verlangsamen.\n\n**Wahrscheinlichkeit:** Mittel\n**Auswirkung:** Niedrig\n**Risikolevel:** Niedrig\n\n**Mitigierung:**\n\n- Nx-Caching und Task-Orchestrierung\n- Klare Build-Dokumentation\n- Automatisierte Setup-Skripte\n- Regelmäßige Build-Optimierung\n\n**Notfallplan:**\n\n- Build-Prozess vereinfachen\n- Bessere Build-Dokumentation\n- Training für Beitragende\n- Build-System-Alternativen erwägen\n\n## 11.2 Technische Schulden\n\n### TD1: Legacy-Theme-Support\n\n**Beschreibung:** Nicht-Standard-Themes (außer ECL) werden nicht aktiv gewartet.\n\n**Auswirkung:** Mittel\n**Aufwand zur Behebung:** Hoch\n**Priorität:** Niedrig\n\n**Details:**\n\n- Mehrere Themes früh im Projekt erstellt\n- Begrenzte Ressourcen, um alle Themes zu warten\n- Einige Themes funktionieren möglicherweise nicht mit neuesten Komponenten\n\n**Lösungsplan:**\n\n- Dokumentieren, welche Themes gewartet werden\n- Nicht gewartete Themes deprecaten\n- Theme-Migrations-Leitfäden bereitstellen\n- Alte Themes als Beispiele archivieren\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n### TD2: Test-Abdeckungs-Lücken\n\n**Beschreibung:** Einige Komponenten haben unvollständige Test-Abdeckung.\n\n**Auswirkung:** Mittel\n**Aufwand zur Behebung:** Hoch\n**Priorität:** Mittel\n\n**Details:**\n\n- Einige ältere Komponenten fehlen E2E-Tests\n- Edge Cases nicht immer abgedeckt\n- Visual-Regression-Tests unvollständig\n\n**Lösungsplan:**\n\n- Alle Komponenten auf Test-Abdeckung auditieren\n- Tests für kritische Pfade hinzufügen\n- Test-Dokumentation verbessern\n- Minimum-Coverage-Anforderungen festlegen\n\n**Zeitrahmen:** Laufend\n\n### TD3: Dokumentations-Inkonsistenzen\n\n**Beschreibung:** Dokumentations-Qualität variiert zwischen Komponenten.\n\n**Auswirkung:** Niedrig\n**Aufwand zur Behebung:** Mittel\n**Priorität:** Mittel\n\n**Details:**\n\n- Einige Komponenten haben minimale Dokumentation\n- Beispiele nicht immer aktuell\n- API-Dokumentation an Stellen unvollständig\n\n**Lösungsplan:**\n\n- Dokumentations-Audit und Standardisierung\n- Dokumentations-Templates\n- Verbesserte automatisierte Dokumentationsgenerierung\n- Community-Dokumentations-Beiträge\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n### TD4: Deprecated Komponenten\n\n**Beschreibung:** Deprecated Komponenten noch in Codebasis.\n\n**Auswirkung:** Niedrig\n**Aufwand zur Behebung:** Mittel\n**Priorität:** Niedrig\n\n**Details:**\n\n- Komponenten als deprecated markiert, aber nicht entfernt\n- Erhöht Wartungsaufwand\n- Erstellt Verwirrung für neue Nutzer\n\n**Lösungsplan:**\n\n- Deprecation-Zeitlinie dokumentieren\n- Migrations-Leitfäden bereitstellen\n- In nächster Hauptversion entfernen\n- Klare Kommunikation an Nutzer\n\n**Zeitrahmen:** Geplant für nächstes Major-Version-Release\n\n### TD5: Build-Zeit-Optimierung\n\n**Beschreibung:** Vollständiger Monorepo-Build dauert ~2 Minuten.\n\n**Auswirkung:** Niedrig\n**Aufwand zur Behebung:** Mittel\n**Priorität:** Niedrig\n\n**Details:**\n\n- Sequenzielle Paket-Builds\n- Einige Optimierungsmöglichkeiten existieren\n- Noch kein größerer Engpass\n\n**Lösungsplan:**\n\n- Build-Prozess profilieren\n- Langsame Schritte optimieren\n- Bessere Nutzung von Nx-Caching\n- Parallele Builds wo sicher erwägen\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n### TD6: SSR-Support\n\n**Beschreibung:** Server-Side-Rendering-Support ist begrenzt.\n\n**Auswirkung:** Mittel\n**Aufwand zur Behebung:** Hoch\n**Priorität:** Mittel\n\n**Details:**\n\n- Hydrate-Adapter existiert, aber begrenzt\n- Declarative Shadow DOM Support benötigt\n- SSR-Anwendungsfälle wachsen\n\n**Lösungsplan:**\n\n- Declarative Shadow DOM evaluieren\n- Hydrate-Adapter verbessern\n- SSR-Einschränkungen dokumentieren\n- SSR-Beispiele bereitstellen\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n### TD7: Barrierefreiheits-Test-Automatisierung\n\n**Beschreibung:** Einige Barrierefreiheits-Tests sind manuell.\n\n**Auswirkung:** Mittel\n**Aufwand zur Behebung:** Hoch\n**Priorität:** Hoch\n\n**Details:**\n\n- Screenreader-Tests größtenteils manuell\n- Tastaturnavigations-Tests manuell\n- Zeitaufwändiger Prozess\n\n**Lösungsplan:**\n\n- axe-core-Integration erweitern\n- Automatisierte Tastaturnavigations-Tests hinzufügen\n- Automatisierte Screenreader-Test-Tools erwägen\n- Barrierefreiheits-Test-Dokumentation verbessern\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n### TD8: Monorepo-Struktur\n\n**Beschreibung:** Einige Pakete haben inkonsistente Struktur.\n\n**Auswirkung:** Niedrig\n**Aufwand zur Behebung:** Mittel\n**Priorität:** Niedrig\n\n**Details:**\n\n- Frühe Pakete unterschiedlich strukturiert\n- Inkonsistente Benennungskonventionen\n- Script-Variationen zwischen Paketen\n\n**Lösungsplan:**\n\n- Paketstruktur standardisieren\n- Ältere Pakete aktualisieren\n- Paket-Template erstellen\n- Standards dokumentieren\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n### TD9: Migrations-Tool-Abdeckung\n\n**Beschreibung:** Migrations-CLI deckt nicht alle Breaking Changes ab.\n\n**Auswirkung:** Mittel\n**Aufwand zur Behebung:** Mittel\n**Priorität:** Mittel\n\n**Details:**\n\n- Einige Migrationen erfordern manuelle Arbeit\n- Tool könnte umfassender sein\n- Nicht alle Edge Cases behandelt\n\n**Lösungsplan:**\n\n- Migrations-Tool-Fähigkeiten erweitern\n- Bessere Dokumentation manueller Schritte\n- Community-Feedback zu Migrations-Schmerzpunkten\n- Automatisierte Tests von Migrationen\n\n**Zeitrahmen:** Laufend mit jeder Hauptversion\n\n### TD10: Performance-Monitoring\n\n**Beschreibung:** Kein kontinuierliches Performance-Monitoring in Produktion.\n\n**Auswirkung:** Niedrig\n**Aufwand zur Behebung:** Mittel\n**Priorität:** Niedrig\n\n**Details:**\n\n- Keine Real-World-Performance-Daten\n- Kann Performance-Regressionen in Produktion nicht erkennen\n\n**Lösungsplan:**\n\n- Performance-Monitoring zu Sample-Apps hinzufügen\n- Web-Vitals-Daten sammeln\n- Performance-Dashboard erstellen\n- Performance-Alerts einrichten\n\n**Zeitrahmen:** In kommenden vierteljährlichen Planungssitzungen zu überprüfen\n\n## 11.3 Risikomanagement-Strategie\n\n### Risikobewertungs-Prozess\n\n1. **Identifizieren**: Regelmäßige Risiko-Review in Team-Meetings\n2. **Analysieren**: Wahrscheinlichkeit und Auswirkung bewerten\n3. **Priorisieren**: Fokus auf High-Risk-Items\n4. **Planen**: Mitigerungs- und Notfallpläne erstellen\n5. **Überwachen**: Risiken verfolgen und nach Bedarf aktualisieren\n\n### Risiko-Review-Kadenz\n\n- **Wöchentlich**: Sicherheitswarnungen und CI-Ausfälle überwachen\n- **Monatlich**: Risiko-Register überprüfen, neue Risiken bewerten\n- **Vierteljährlich**: Umfassende Risiko-Analyse mit Team\n- **Jährlich**: Externes Sicherheits-Audit und Risikobewertung\n\n### Technische-Schulden-Management\n\n- **Vierteljährliche Planung**: Zeit für technische Schulden zuweisen\n- **20%-Regel**: ~20% jedes Sprints für technische Schulden\n- **Dokumentation**: Alle technischen Schulden-Items verfolgen\n- **Priorisierung**: Features mit Schuldenreduzierung ausbalancieren\n\n### Kommunikation\n\n- **Transparenz**: Alle Risiken öffentlich dokumentiert\n- **Nutzer-Kommunikation**: Sicherheits-Advisories, Breaking Changes\n- **Team-Kommunikation**: Risiko-Register mit allen Beitragenden geteilt\n- **Community-Input**: Risiko-Reports von Community akzeptieren\n\n## 11.4 Annahmen und Abhängigkeiten\n\n### Annahmen\n\n| Annahme | Auswirkung wenn falsch | Verifizierung |\n|-----------|----------------|--------------|\n| Web Components bleiben unterstützt | Projekt-Fundament gefährdet | W3C-Standards überwachen |\n| Stencil setzt Entwicklung fort | Build-System gefährdet | Stencil-Releases überwachen |\n| npm bleibt primäre Distribution | Distributions-Unterbrechung | Paket-Registry-Alternativen |\n| Moderne Browser halten Kompatibilität | Breaking Changes benötigt | Browser-Releases überwachen |\n| Community wächst weiter | Projekt-Nachhaltigkeit | GitHub-Metriken verfolgen |\n\n### Kritische Abhängigkeiten\n\n| Abhängigkeit | Zweck | Risiko-Mitigierung |\n|-----------|---------|-----------------|\n| **Stencil.js** | Komponenten-Kompilierung | Aktives Monitoring, Fork-Plan |\n| **TypeScript** | Typsystem | Gut gewartet von Microsoft |\n| **pnpm** | Paketmanagement | Könnte bei Bedarf zu npm wechseln |\n| **GitHub Actions** | CI/CD | Alternative CI-Plattformen verfügbar |\n| **npm Registry** | Distribution | Mehrere Registry-Optionen |\n| **@floating-ui/dom** | Positionierungslogik | Könnte Alternative implementieren |\n| **adopted-style-sheets** | Theming-Polyfill | Könnte bei Bedarf forken |\n\n### Externe Standards\n\n| Standard | Auswirkung | Monitoring |\n|----------|--------|-----------|\n| **WCAG** | Barrierefreiheits-Konformität | W3C WAI Arbeitsgruppe |\n| **BITV** | Deutsches Barrierefreiheitsgesetz | Regierungs-Updates |\n| **W3C Web Components** | Kern-Technologie | W3C WICG |\n| **ES Standards** | JavaScript-Features | TC39-Proposals |\n| **CSS Standards** | Styling-Fähigkeiten | W3C CSS WG |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/12-glossary",
+      "group": "docs/arc42_de",
+      "name": "12-glossary",
+      "path": "docs/arc42_de/12-glossary.md",
+      "code": "# 12. Glossar\n\nDieses Glossar bietet Definitionen für Schlüsselbegriffe, Konzepte und Abkürzungen, die in der Public UI - KoliBri Architekturdokumentation verwendet werden. Es dient als Referenz, um ein konsistentes Verständnis über alle Stakeholder hinweg sicherzustellen.\n\n## A\n\n**Barrierefreiheit (A11y)**\nDie Praxis, Webinhalte für Menschen mit Behinderungen nutzbar zu machen. Public UI - KoliBri fokussiert sich darauf, WCAG 2.2 Level AAA Standards zu erfüllen.\n\n**Adapter**\nFramework-spezifischer Wrapper um KoliBri-Komponenten. Auto-generiert von Stencil Output Targets für React, Angular, Vue, etc.\n\n**Adopted Style Sheets**\nWeb-API, die das Teilen von Style Sheets über mehrere Shadow-DOM-Instanzen ermöglicht. Von KoliBri für effizientes Theming verwendet.\n\n**ARIA (Accessible Rich Internet Applications)**\nSammlung von Attributen, die Wege definieren, um Webinhalte für Menschen mit Behinderungen zugänglicher zu machen.\n\n**Atomare Komponente**\nKleine, einzelne Komponente (Button, Input, Icon), die zu größeren Komponenten komponiert werden kann. KoliBri fokussiert sich auf atomare Komponenten.\n\n## B\n\n**BEM (Block Element Modifier)**\nCSS-Benennungskonvention, die im KoliBri-Styling verwendet wird. Beispiel: `.kol-button__icon--small`\n\n**BITV (Barrierefreie-Informationstechnik-Verordnung)**\nDeutsche Barrierefreiheitsverordnung, die KoliBri einhält. Basiert auf WCAG-Standards.\n\n**Bundle-Größe**\nGesamtgröße von JavaScript- und CSS-Dateien. KoliBri optimiert Bundle-Größe durch Lazy Loading und Code-Splitting.\n\n## C\n\n**Komponente**\nWiederverwendbares UI-Element mit gekapselter Struktur, Styling und Verhalten. In KoliBri bezieht sich dies auf Web Components.\n\n**Komponenten-Bibliothek**\nSammlung wiederverwendbarer Komponenten. KoliBri ist eine Komponenten-Bibliothek für barrierefreies HTML.\n\n**CSP (Content Security Policy)**\nSicherheitsstandard, der hilft, XSS-Angriffe zu verhindern. KoliBri-Komponenten sind CSP-kompatibel.\n\n**Custom Element**\nWebstandard zur Definition neuer HTML-Elemente. KoliBri-Komponenten sind Custom Elements (z.B. `<kol-button>`).\n\n**Custom Element Manifest**\nJSON-Datei, die Custom Elements' APIs beschreibt. Generiert von Stencil und verwendet für Dokumentation und IDE-Support.\n\n## D\n\n**Declarative Shadow DOM**\nServer-Side-Rendering-Technik für Web Components. KoliBri hat derzeit begrenzte Unterstützung.\n\n**Design-System**\nSammlung wiederverwendbarer Komponenten und Design-Richtlinien. KoliBri bietet Fundament für Design-Systeme.\n\n**Design-Token**\nBenannter Wert (Farbe, Abstand, Schrift), der in Design-Systemen verwendet wird. KoliBri-Themes verwenden Design-Tokens.\n\n**DX (Developer Experience)**\nWie einfach und angenehm es ist, ein Tool oder eine Bibliothek zu verwenden. KoliBri priorisiert gute DX.\n\n## E\n\n**Kapselung**\nIsolation der Komponenten-Implementierung von externem Code. Erreicht durch Shadow DOM.\n\n**EUPL (European Union Public License)**\nOpen-Source-Lizenz, die von KoliBri verwendet wird (Version 1.2).\n\n**Event**\nSignal, das von Komponente emittiert wird, wenn etwas passiert (Klick, Änderung, etc.). KoliBri verwendet CustomEvent API.\n\n## F\n\n**Framework-Adapter**\nPaket, das KoliBri-Komponenten natürlich in spezifischen Frameworks funktionieren lässt (React, Angular, Vue).\n\n**Framework-agnostisch**\nFunktioniert mit jedem oder keinem Framework. Kernprinzip von KoliBri.\n\n## H\n\n**Hydratisierung**\nProzess des Anhängens von Event-Handlern an server-gerendertes HTML. Relevant für SSR-Szenarien.\n\n## I\n\n**ITZBund (Informationstechnikzentrum Bund)**\nDeutscher Bundes-IT-Dienstleister, der KoliBri erstellt und als Open Source veröffentlicht hat.\n\n## J\n\n**JSX (JavaScript XML)**\nSyntaxerweiterung für JavaScript, die in Stencil-Komponenten-Templates verwendet wird.\n\n## K\n\n**KoliBri**\nComponent Library for Accessibility - der Name dieses Projekts. Immer mit dieser Schreibweise geschrieben.\n\n## L\n\n**Lazy Loading**\nCode nur bei Bedarf laden. KoliBri-Komponenten werden lazy geladen für optimale Performance.\n\n**LTS (Long-Term Support)**\nVersion mit 3 Jahren Support. Bietet Stabilität für Unternehmensnutzer.\n\n**Loader**\nJavaScript-Modul, das Custom Elements definiert. KoliBri bietet Loader für Lazy Loading.\n\n## M\n\n**Monorepo**\nEinzelnes Repository mit mehreren Paketen. KoliBri verwendet pnpm Workspace Monorepo.\n\n**Multi-Theming**\nFähigkeit, verschiedene visuelle Themes auf gleiche Komponenten anzuwenden. Kern-KoliBri-Feature.\n\n## N\n\n**npm (Node Package Manager)**\nPaket-Registry, wo KoliBri-Pakete veröffentlicht werden.\n\n**Nx**\nBuild-System für Monorepos. KoliBri verwendet Nx für Build-Orchestrierung und Caching.\n\n## O\n\n**Output Target**\nStencil-Konfiguration zur Generierung von Framework-Adaptern. KoliBri verwendet Output Targets für React, Angular, Vue, etc.\n\n## P\n\n**pnpm (Performant npm)**\nSchneller, festplatteneffizienter Paketmanager. KoliBri verwendet pnpm Workspaces.\n\n**Polyfill**\nCode, der Funktionalität bereitstellt, die von Browsern nicht nativ unterstützt wird. Kann für ältere Browser benötigt werden.\n\n**Props (Properties)**\nKonfigurationsoptionen, die an Komponenten übergeben werden. KoliBri verwendet Unterstrich-Präfix (z.B. `_label`).\n\n**Provenance**\nBuild-Attestierung, die Paket-Authentizität beweist. KoliBri veröffentlicht mit SLSA Build Level 3 Provenance.\n\n## R\n\n**React**\nBeliebtes JavaScript-Framework. KoliBri bietet React-Adapter.\n\n**Responsive**\nPasst sich verschiedenen Bildschirmgrößen an. KoliBri-Komponenten sind standardmäßig responsive.\n\n**RTL (Right-to-Left)**\nTextrichtung für Sprachen wie Arabisch und Hebräisch. KoliBri unterstützt RTL-Layouts.\n\n## S\n\n**SASS (Syntactically Awesome Style Sheets)**\nCSS-Präprozessor, der für KoliBri-Themes verwendet wird.\n\n**Screenreader**\nAssistive Technologie, die Webinhalte laut vorliest. KoliBri gewährleistet Screenreader-Kompatibilität.\n\n**Semantisches HTML**\nHTML-Elemente gemäß ihrer Bedeutung verwenden (Button für Buttons, nicht Div). KoliBri erzwingt semantisches HTML.\n\n**SemVer (Semantic Versioning)**\nVersionierungsschema (MAJOR.MINOR.PATCH). KoliBri folgt strikt SemVer 2.0.\n\n**Shadow DOM**\nWebstandard zur Kapselung von Komponenten-DOM und -Styles. Kern von KoliBris Architektur.\n\n**SLSA (Supply-chain Levels for Software Artifacts)**\nSicherheits-Framework für Software-Supply-Chains. KoliBri strebt Build Level 3 an.\n\n**Slot**\nWeb-Components-Mechanismus für Content-Projektion. Verwendet für flexible Komponenten-Komposition.\n\n**SSR (Server-Side Rendering)**\nKomponenten auf Server rendern. KoliBri hat begrenzte SSR-Unterstützung über Hydrate-Adapter.\n\n**Stencil**\nWeb-Component-Compiler, der zum Bau von KoliBri verwendet wird. Entwickelt vom Ionic-Team.\n\n**STS (Short-Term Support)**\nVersion mit 15 Monaten Support. Ermöglicht schnelle Innovation.\n\n## T\n\n**Theme**\nPaket mit visuellen Styles für Komponenten. KoliBri trennt Themes von Komponenten-Logik.\n\n**Tree Shaking**\nEntfernen ungenutzten Codes während des Bundlings. KoliBri unterstützt Tree Shaking für kleinere Bundles.\n\n**TypeScript**\nTypisierte Obermenge von JavaScript. Gesamter KoliBri-Code in TypeScript geschrieben.\n\n## V\n\n**Vue.js**\nProgressives JavaScript-Framework. KoliBri bietet Vue-Adapter.\n\n## W\n\n**W3C (World Wide Web Consortium)**\nStandards-Organisation für das Web. KoliBri folgt W3C-Standards.\n\n**WCAG (Web Content Accessibility Guidelines)**\nInternationale Barrierefreiheits-Standards. Public UI - KoliBri implementiert WCAG 2.2 Level AAA.\n\n**Web Component**\nSammlung von Webstandards zur Erstellung wiederverwendbarer Custom Elements. Fundament von KoliBri.\n\n**Webstandard**\nOffizielle Spezifikation vom W3C. KoliBri auf Webstandards für Langlebigkeit gebaut.\n\n## Abkürzungen\n\n| Abkürzung | Vollständiger Begriff |\n|--------------|-----------|\n| A11y | Accessibility (Barrierefreiheit) |\n| API | Application Programming Interface |\n| ARIA | Accessible Rich Internet Applications |\n| BEM | Block Element Modifier |\n| BITV | Barrierefreie-Informationstechnik-Verordnung |\n| CDN | Content Delivery Network |\n| CI/CD | Continuous Integration / Continuous Deployment |\n| CJS | CommonJS |\n| CLI | Command Line Interface |\n| CSP | Content Security Policy |\n| CSS | Cascading Style Sheets |\n| DOM | Document Object Model |\n| DX | Developer Experience |\n| E2E | End-to-End |\n| ES | ECMAScript |\n| ESM | ES Modules |\n| EUPL | European Union Public License |\n| HTML | HyperText Markup Language |\n| i18n | Internationalization (Internationalisierung) |\n| IDE | Integrated Development Environment |\n| ITZBund | Informationstechnikzentrum Bund |\n| JSX | JavaScript XML |\n| LTS | Long-Term Support |\n| MCP | Model Context Protocol |\n| npm | Node Package Manager |\n| OIDC | OpenID Connect |\n| pnpm | Performant npm |\n| PR | Pull Request |\n| RTL | Right-to-Left |\n| SASS | Syntactically Awesome Style Sheets |\n| SemVer | Semantic Versioning |\n| SLSA | Supply-chain Levels for Software Artifacts |\n| SPA | Single Page Application |\n| SSR | Server-Side Rendering |\n| STS | Short-Term Support |\n| UI | User Interface |\n| UX | User Experience |\n| W3C | World Wide Web Consortium |\n| WCAG | Web Content Accessibility Guidelines |\n| XSS | Cross-Site Scripting |\n\n## Komponentenbenennung\n\nAlle KoliBri-Komponenten sind mit \"Kol\" präfixiert, um Namenskonflikte zu vermeiden:\n\n- `<kol-button>` - Button-Komponente\n- `<kol-input-text>` - Texteingabe-Komponente\n- `<kol-table>` - Tabellen-Komponente\n- `<kol-modal>` - Modal-Dialog-Komponente\n- etc.\n\n## Property-Benennung\n\nKomponenten-Properties sind mit Unterstrich präfixiert, um Konflikte mit nativen HTML-Attributen zu vermeiden:\n\n- `_label` - Komponenten-Label\n- `_disabled` - Deaktiviert-State\n- `_variant` - Visuelle Variante\n- `_icons` - Icon-Konfiguration\n- etc.\n\n## Dateiendungen\n\n| Endung | Zweck |\n|-----------|---------|\n| `.tsx` | TypeScript mit JSX (Komponenten-Dateien) |\n| `.ts` | TypeScript (Utilities, Typen) |\n| `.scss` | SASS-Stylesheet |\n| `.css` | CSS-Stylesheet |\n| `.spec.ts` | Unit-Test-Datei |\n| `.e2e.ts` | E2E-Test-Datei |\n| `.md` | Markdown-Dokumentation |\n\n## Paket-Scopes\n\n| Scope | Zweck |\n|-------|---------|\n| `@public-ui/components` | Kern-Komponenten-Bibliothek |\n| `@public-ui/theme-*` | Theme-Pakete |\n| `@public-ui/react` | React-Adapter |\n| `@public-ui/angular-*` | Angular-Adapter |\n| `@public-ui/vue` | Vue-Adapter |\n| `@public-ui/solid` | Solid-Adapter |\n| `@public-ui/svelte` | Svelte-Adapter |\n| `@public-ui/kolibri-cli` | Migrations-CLI-Tool |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42_de/README",
+      "group": "docs/arc42_de",
+      "name": "README",
+      "path": "docs/arc42_de/README.md",
+      "code": "# Public UI - KoliBri Architekturdokumentation (arc42)\n\nDieses Verzeichnis enthält die umfassende Architekturdokumentation für Public UI - KoliBri (KoliBri), eine barrierefreie Web-Component-Bibliothek. Die Dokumentation folgt der bewährten arc42-Vorlagenstruktur und bietet Stakeholdern, Entwicklern und Architekten klare Einblicke in das Design, die Entscheidungen und die Qualitätsanforderungen des Systems.\n\n## Inhaltsverzeichnis\n\n1. [Einführung und Ziele](01-introduction-and-goals.md)\n2. [Randbedingungen](02-architecture-constraints.md)\n3. [Kontextabgrenzung](03-system-scope-and-context.md)\n4. [Lösungsstrategie](04-solution-strategy.md)\n5. [Bausteinsicht](05-building-block-view.md)\n6. [Laufzeitsicht](06-runtime-view.md)\n7. [Verteilungssicht](07-deployment-view.md)\n8. [Querschnittliche Konzepte](08-cross-cutting-concepts.md)\n9. [Architekturentscheidungen](09-architecture-decisions.md)\n10. [Qualitätsanforderungen](10-quality-requirements.md)\n11. [Risiken und technische Schulden](11-risks-and-technical-debt.md)\n12. [Glossar](12-glossary.md)\n\n## Über arc42\n\narc42 ist eine bewährte Vorlage für die Dokumentation und Kommunikation von Softwarearchitekturen. Sie bietet eine klare Struktur zur Dokumentation von Software- und Systemarchitekturen.\n\nWeitere Informationen: https://arc42.org\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/01-introduction-and-goals",
+      "group": "docs/arc42",
+      "name": "01-introduction-and-goals",
+      "path": "docs/arc42/01-introduction-and-goals.md",
+      "code": "# 1. Introduction and Goals\n\nThis section introduces Public UI - KoliBri (KoliBri), outlining its core mission, stakeholders, and overarching quality objectives. Understanding these foundational elements provides context for all subsequent architectural decisions and design choices.\n\n## 1.1 Requirements Overview\n\n**Public UI - KoliBri (KoliBri)** is an open-source web component library designed to make HTML accessible, semantic, and valid by default. It serves as a reference implementation of accessibility standards while remaining flexible enough for diverse organizational needs.\n\n### Key Requirements\n\n- **Accessibility First**: Ensure all components meet WCAG 2.2 Level AAA standards and BITV requirements\n- **Framework Agnostic**: Work seamlessly with any web framework or vanilla JavaScript\n- **Multi-theming**: Support multiple design systems and corporate identities\n- **Reusability**: Provide atomic, flexible components that can be composed into complex interfaces\n- **Standards Compliance**: Follow W3C web standards strictly\n- **Long-term Support**: Maintain LTS versions for enterprise stability\n\n## 1.2 Quality Goals\n\n| Priority | Quality Goal | Motivation |\n|----------|-------------|------------|\n| 1 | **Accessibility** | Core mission - every component must be accessible to all users regardless of disabilities |\n| 2 | **Standard Compliance** | Build on W3C standards ensures longevity and interoperability |\n| 3 | **Usability** | Components should be intuitive for developers and end-users |\n| 4 | **Maintainability** | Clean architecture enables long-term evolution and community contributions |\n| 5 | **Performance** | Fast loading and rendering for optimal user experience |\n\n### Quality Scenarios\n\n1. **Accessibility**: A screen reader user can navigate and interact with all components without visual assistance\n2. **Framework Independence**: Developers can integrate KoliBri into React, Angular, Vue, or vanilla JS projects within 15 minutes\n3. **Theming**: Organizations can apply their corporate design to all components without modifying component code\n4. **Maintainability**: New contributors can understand the architecture and contribute their first component within 2 days\n\n## 1.3 Stakeholders\n\n| Role/Name | Expectations | Contact |\n|-----------|-------------|---------|\n| **End Users** | Accessible, usable web interfaces that work with assistive technologies | - |\n| **Developers** | Easy-to-use, well-documented components that integrate with their tech stack | - |\n| **Designers** | Flexible theming system that supports their design systems | - |\n| **ITZBund** | Sustainable open-source project that meets public sector requirements | kolibri@itzbund.de |\n| **Public Sector Organizations** | BITV-compliant components for government websites and applications | - |\n| **Open Source Community** | Transparent development, contribution opportunities, and reusable components | GitHub Issues/PRs |\n| **Accessibility Advocates** | Reference implementation of WCAG standards in web components | - |\n\n## 1.4 Vision and Mission\n\n### Vision\n> Together we make **HTML** accessible using **reusable web components** to ensure **usability** and **accessibility**.\n\n### Mission\nThe HTML web standard is openly specified to be long-lasting and robust, but this often results in compositions that are not easily accessible, semantic, or valid. KoliBri provides:\n\n- **Framework-agnostic components** based on W3C web standards\n- **Generic reference implementation** of WCAG and BITV standards\n- **Multi-theming capable presentation layer** without technical coupling or data transfer\n- **Reusable solution** for static websites and dynamic web applications\n- **Open source foundation** enabling wide adoption and community collaboration\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/02-architecture-constraints",
+      "group": "docs/arc42",
+      "name": "02-architecture-constraints",
+      "path": "docs/arc42/02-architecture-constraints.md",
+      "code": "# 2. Architecture Constraints\n\nThis section documents the technical, organizational, and legal boundaries within which Public UI - KoliBri must operate. These constraints shape architectural decisions and guide implementation choices throughout the project.\n\n## 2.1 Technical Constraints\n\n| Constraint | Description | Motivation |\n|-----------|-------------|------------|\n| **Web Standards Only** | Components must use only standard web technologies (HTML, CSS, JavaScript) | Ensures long-term compatibility and avoids vendor lock-in |\n| **Shadow DOM** | Components use Shadow DOM for encapsulation | Prevents style conflicts and enables true component isolation |\n| **Stencil.js Framework** | Web components are built with Stencil | Provides excellent developer experience and generates framework adapters |\n| **TypeScript** | All code written in TypeScript | Type safety improves code quality and developer experience |\n| **pnpm Monorepo** | Project structure as pnpm/Nx monorepo | Efficient dependency management and build orchestration |\n| **Node.js 22+** | Minimum Node.js version 22 | Leverages modern JavaScript features and tooling |\n| **CSS Custom Properties** | Minimal use of CSS custom properties for theming | Avoids global cascade pollution while enabling customization |\n| **Adopted Style Sheets** | Styling via adopted style sheets | Enables efficient theme switching and style composition |\n\n## 2.2 Organizational Constraints\n\n| Constraint | Description | Impact |\n|-----------|-------------|--------|\n| **Open Source License** | EUPL-1.2 (European Union Public License) | All contributions must be compatible with this license |\n| **Public Sector Context** | Originated from ITZBund (German federal IT service provider) | Must meet public sector requirements (BITV, procurement rules) |\n| **Community Driven** | Open for external contributions | Development prioritizes community needs and contributions |\n| **Semantic Versioning** | Strict SemVer compliance | Breaking changes only in major versions |\n| **LTS/STS Release Model** | Long-term support (3 years) and short-term support (15 months) versions | Enterprises need stability while innovation continues |\n\n## 2.3 Conventions\n\n| Convention | Description | Enforcement |\n|-----------|-------------|------------|\n| **Code Style** | Prettier formatting, 160 character line width, tabs | Automated via pre-commit hooks and CI |\n| **Linting** | ESLint and Stylelint with strict rules | No inline rule disabling allowed |\n| **Commit Messages** | Conventional Commits specification | PR title validation in CI |\n| **Documentation** | All public APIs must be documented | Required for PR approval |\n| **Testing** | Unit tests for logic, E2E tests for components | Required for PR approval |\n| **Alphabetical Ordering** | Lists, imports, and enumerations kept alphabetically sorted | Reduces merge conflicts |\n| **Component Naming** | All components prefixed with \"Kol\" (e.g., KolButton) | Avoids naming conflicts |\n\n## 2.4 Quality Constraints\n\n| Constraint | Description | Verification |\n|-----------|-------------|--------------|\n| **WCAG 2.2 AAA Compliance** | All components must meet WCAG 2.2 Level AAA standards | Automated axe-core testing + manual review |\n| **BITV Compliance** | Components must meet German accessibility requirements | Manual testing and certification |\n| **Browser Support** | Modern browsers with ES2017+ support | Automated cross-browser testing |\n| **Bundle Size** | Keep individual components small and tree-shakeable | Bundle size monitoring in CI |\n| **Contrast Ratios** | Minimum 4.5:1 for normal text, 3:1 for large text | wcag-contrast library validation |\n| **Interactive Element Size** | Minimum 44x44px touch target size | Built into component styling |\n\n## 2.5 Legal Constraints\n\n| Constraint | Description |\n|-----------|-------------|\n| **License Compatibility** | All dependencies must be compatible with EUPL-1.2 |\n| **No Proprietary Dependencies** | Avoid dependencies with proprietary licenses |\n| **Export Compliance** | As open source, complies with EU export regulations |\n| **Data Protection** | No personal data collection in components |\n| **Third-party Licenses** | All third-party licenses documented and reviewed |\n\n## 2.6 Development Environment Constraints\n\n| Constraint | Description |\n|-----------|-------------|\n| **Platform Independence** | Build and development must work on Windows, macOS, and Linux |\n| **CI/CD Platform** | GitHub Actions for all automation |\n| **Package Registry** | npm as primary distribution channel |\n| **Security Scanning** | CodeQL and dependency scanning required |\n| **Provenance** | SLSA Build Level 3 for published packages |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/03-system-scope-and-context",
+      "group": "docs/arc42",
+      "name": "03-system-scope-and-context",
+      "path": "docs/arc42/03-system-scope-and-context.md",
+      "code": "# 3. System Scope and Context\n\nThis section defines the boundaries of Public UI - KoliBri by identifying what is inside and outside the system. It clarifies the relationships with external systems, users, and dependencies, providing both business and technical perspectives on the system's environment.\n\n## 3.1 Business Context\n\n```mermaid\ngraph TB\n    subgraph External Systems\n        Frameworks[Web Frameworks<br/>React, Angular, Vue, etc.]\n        Browser[Web Browsers<br/>Chrome, Firefox, Safari, Edge]\n        Assistive[Assistive Technologies<br/>Screen Readers, etc.]\n        CDN[Content Delivery Networks<br/>npm, unpkg, jsDelivr]\n        DesignSystems[Design Systems<br/>Corporate Design Guidelines]\n    end\n    \n    subgraph KoliBri System\n        Components[Web Components Library]\n        Themes[Theme Packages]\n        Adapters[Framework Adapters]\n        CLI[Migration CLI Tool]\n        Docs[Documentation Site]\n    end\n    \n    subgraph Users\n        Developers[Application Developers]\n        EndUsers[End Users with/without Disabilities]\n        Designers[UX/UI Designers]\n        Contributors[Open Source Contributors]\n    end\n    \n    Developers -->|integrate| Components\n    Developers -->|use| Adapters\n    Developers -->|migrate with| CLI\n    Developers -->|read| Docs\n    \n    Designers -->|customize| Themes\n    Designers -->|follow| DesignSystems\n    \n    Contributors -->|contribute to| Components\n    Contributors -->|create| Themes\n    \n    Components -->|runs in| Browser\n    Components -->|uses| Themes\n    Components -->|consumed by| Frameworks\n    \n    Browser -->|renders| Components\n    Browser -->|provides API| Assistive\n    \n    EndUsers -->|interact via| Browser\n    EndUsers -->|use| Assistive\n    \n    Components -->|distributed via| CDN\n    Adapters -->|distributed via| CDN\n    Themes -->|distributed via| CDN\n```\n\n### Business Context Description\n\n| Partner/Interface | Input | Output | Description |\n|-------------------|-------|--------|-------------|\n| **Application Developers** | Integration requirements, bug reports, feature requests | Web components, framework adapters, documentation | Primary users who integrate KoliBri into their applications |\n| **Web Frameworks** | Framework APIs and conventions | Framework-specific adapters (React, Angular, Vue, etc.) | KoliBri provides native integrations for popular frameworks |\n| **Web Browsers** | Web standards APIs (Custom Elements, Shadow DOM) | Rendered accessible components | KoliBri components run in modern browsers |\n| **Assistive Technologies** | ARIA attributes, semantic HTML | Accessible user interface | Components expose proper accessibility information |\n| **Design Systems** | Design tokens, style guides, brand guidelines | Themed components | Organizations apply their design system via themes |\n| **npm Registry** | Package distribution infrastructure | Published npm packages | Primary distribution channel for components and themes |\n| **End Users** | User interactions (click, keyboard, touch) | Accessible user experience | Ultimate beneficiaries of accessible components |\n| **Open Source Community** | Contributions, bug reports, discussions | Improved components, new features | Community drives evolution and quality |\n\n## 3.2 Technical Context\n\n```mermaid\ngraph TB\n    subgraph Development Tools\n        Node[Node.js 22+]\n        pnpm[pnpm Package Manager]\n        Nx[Nx Build System]\n        TypeScript[TypeScript Compiler]\n        Stencil[Stencil.js]\n    end\n    \n    subgraph Build Artifacts\n        ESM[ES Modules]\n        CJS[CommonJS Modules]\n        Types[TypeScript Definitions]\n        CustomElements[Custom Elements Bundle]\n        Loader[Lazy Loading Wrapper]\n    end\n    \n    subgraph Runtime Environment\n        CustomElementsAPI[Custom Elements API]\n        ShadowDOMAPI[Shadow DOM API]\n        AdoptedStyleSheets[Adopted Style Sheets API]\n        DOMAPI[DOM APIs]\n    end\n    \n    subgraph Testing Tools\n        Jest[Jest Unit Tests]\n        Playwright[Playwright E2E Tests]\n        AxeCore[axe-core Accessibility Tests]\n    end\n    \n    subgraph Quality Tools\n        ESLint[ESLint]\n        Stylelint[Stylelint]\n        Prettier[Prettier]\n        CodeQL[CodeQL Security]\n    end\n    \n    Stencil -->|compiles| TypeScript\n    Stencil -->|generates| ESM\n    Stencil -->|generates| CJS\n    Stencil -->|generates| Types\n    Stencil -->|generates| CustomElements\n    Stencil -->|generates| Loader\n    \n    Node -->|runs| Stencil\n    pnpm -->|manages| Node\n    Nx -->|orchestrates| pnpm\n    \n    CustomElements -->|uses| CustomElementsAPI\n    CustomElements -->|uses| ShadowDOMAPI\n    CustomElements -->|uses| AdoptedStyleSheets\n    CustomElements -->|uses| DOMAPI\n```\n\n### Technical Interfaces\n\n| Interface | Technology | Description |\n|-----------|------------|-------------|\n| **Component Definition** | Stencil.js, TypeScript | Components are defined using Stencil decorators and TypeScript classes |\n| **Component Registration** | Custom Elements API | Components register as custom HTML elements |\n| **Style Encapsulation** | Shadow DOM, Adopted Style Sheets | Styles are scoped to components via Shadow DOM |\n| **Theme Application** | CSS, SASS, Adopted Style Sheets | Themes provide CSS loaded as adopted style sheets |\n| **Framework Integration** | Framework-specific adapters | Generated adapters wrap components for React, Angular, Vue, etc. |\n| **Build System** | pnpm, Nx, Rollup (via Stencil) | Monorepo build orchestrated by pnpm and Nx |\n| **Module Formats** | ES Modules, CommonJS | Components distributed in multiple module formats |\n| **Type Definitions** | TypeScript .d.ts files | Full TypeScript support for developers |\n| **Testing** | Jest, Playwright, axe-core | Unit tests, E2E tests, and accessibility validation |\n| **Package Distribution** | npm registry | Components published as npm packages |\n\n### Communication Channels\n\n| Channel | Technology | Purpose |\n|---------|------------|---------|\n| **Component Props** | JavaScript/TypeScript objects | Configuration and data passing |\n| **Component Events** | CustomEvent API | Component-to-application communication |\n| **CSS Custom Properties** | CSS Variables (limited) | Theme customization points |\n| **Slots** | Shadow DOM slots | Content projection into components |\n| **CSS Parts** | ::part() pseudo-element | External styling of component internals (limited use) |\n| **ARIA Attributes** | HTML attributes | Accessibility information for assistive technologies |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/04-solution-strategy",
+      "group": "docs/arc42",
+      "name": "04-solution-strategy",
+      "path": "docs/arc42/04-solution-strategy.md",
+      "code": "# 4. Solution Strategy\n\nThis section presents the fundamental approach and key decisions that shape Public UI - KoliBri's architecture. It describes the chosen technologies, architectural patterns, and strategies for achieving the project's quality goals while addressing its core requirements.\n\n## 4.1 Technology Decisions\n\n| Decision | Rationale | Consequences |\n|----------|-----------|--------------|\n| **Web Components** | Framework-agnostic, standards-based, native browser support | Works with any framework, long-term stability, but requires polyfills for older browsers |\n| **Stencil.js** | Best-in-class web component compiler, generates framework adapters, excellent DX | Ties build process to Stencil, but provides tremendous value in code generation |\n| **Shadow DOM** | True style encapsulation, prevents CSS conflicts | Components are isolated but can't be styled from outside (by design) |\n| **TypeScript** | Type safety, better IDE support, catches errors early | Requires compilation step, but dramatically improves code quality |\n| **pnpm Workspace** | Efficient dependency management, fast installs, strict dependencies | More complex setup than npm, but better for monorepos |\n| **Adopted Style Sheets** | Efficient theme switching, style composition | Requires modern browser support, but enables powerful theming |\n| **SASS** | Variables, mixins, powerful theme authoring | Compilation required, but provides essential features for complex themes |\n\n## 4.2 Top-level Decomposition\n\nKoliBri is structured as a monorepo with clear separation of concerns:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    KoliBri System                        │\n├─────────────────────────────────────────────────────────┤\n│                                                           │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │\n│  │  Components │  │   Themes    │  │   Adapters  │     │\n│  │   (Core)    │  │  (Styling)  │  │ (Framework) │     │\n│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │\n│         │                 │                 │             │\n│         └─────────────────┴─────────────────┘            │\n│                           │                               │\n│  ┌─────────────┐  ┌──────┴──────┐  ┌─────────────┐     │\n│  │   Samples   │  │    Tools    │  │     Docs    │     │\n│  │ (Examples)  │  │  (Tooling)  │  │ (Knowledge) │     │\n│  └─────────────┘  └─────────────┘  └─────────────┘     │\n│                                                           │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Component Layers\n\n1. **Core Components** (`packages/components/`)\n   - Atomic web components\n   - Business logic and accessibility\n   - Framework-agnostic implementation\n\n2. **Themes** (`packages/themes/`)\n   - Visual styling separate from logic\n   - Multiple themes for different design systems\n   - CSS/SASS with strict scoping rules\n\n3. **Framework Adapters** (`packages/adapters/`)\n   - Auto-generated wrappers for React, Angular, Vue, etc.\n   - Framework-specific APIs and patterns\n   - Generated by Stencil output targets\n\n4. **Samples** (`packages/samples/`)\n   - Example implementations\n   - Testing ground for new features\n   - Documentation through working code\n\n5. **Tools** (`packages/tools/`)\n   - Migration CLI for version upgrades\n   - Visual regression testing\n   - Development utilities\n\n## 4.3 Architectural Patterns\n\n### Pattern: Composition over Inheritance\n\n- Components are atomic and composable\n- Complex UI built by combining simple components\n- No inheritance hierarchies, flat component structure\n\n### Pattern: Separation of Concerns\n\n- **Structure/Logic**: Stencil components (TypeScript)\n- **Styling**: Theme packages (SASS/CSS)\n- **Integration**: Framework adapters (generated)\n- **Documentation**: Separate docs site\n\n### Pattern: Five-Layer Styling System\n\n1. **A11y Preset Layer**: Accessibility baseline from `adopted-style-sheets`\n2. **Basis Global Layer**: Global component layout (no colors/margins)\n3. **Basis Component Layer**: Component-specific layout (no colors/margins)\n4. **Theme Global Layer**: Global theme styles (colors, fonts)\n5. **Theme Component Layer**: Component-specific theme styles\n\nThis layering ensures:\n\n- Accessibility by default\n- Themeable without breaking layout\n- Clear separation of structure and appearance\n\n### Pattern: Zero Runtime Dependencies\n\n- Components have minimal runtime dependencies\n- No heavy framework requirements\n- Optimized for bundle size and performance\n\n## 4.4 Quality Strategy\n\n### Accessibility First\n\n- Every component implements WCAG 2.2 Level AAA standards\n- Keyboard navigation mandatory for all interactive elements\n- Screen reader testing for all interactive components\n- Automated axe-core testing in CI\n- Manual accessibility reviews and compliance verification\n\n### Standards Compliance\n\n- Strict adherence to W3C specifications\n- Valid HTML, semantic markup\n- Proper use of ARIA attributes\n- Progressive enhancement principles\n\n### Performance\n\n- Lazy loading of components\n- Tree-shakeable exports\n- Minimal CSS footprint\n- Shadow DOM for efficient rendering\n- Bundle size monitoring\n\n### Developer Experience\n\n- Comprehensive TypeScript types\n- Clear, searchable documentation\n- Working code examples\n- Migration tools for version upgrades\n- Framework-specific integrations\n\n## 4.5 Organizational Strategy\n\n### Open Source First\n\n- Public development on GitHub\n- Community contributions welcome\n- Transparent roadmap and decision-making\n- Clear contribution guidelines\n\n### LTS/STS Release Model\n\n- **LTS (Long-Term Support)**: 3 years support, major versions\n- **STS (Short-Term Support)**: 15 months support, rapid innovation\n- Semantic versioning strictly followed\n- Migration guides for all breaking changes\n\n### Quality Gates\n\n- Automated testing (unit, E2E, accessibility)\n- Code review required for all changes\n- Linting and formatting enforced\n- Security scanning (CodeQL, dependencies)\n- SLSA Build Level 3 for published packages\n\n## 4.6 Theming Strategy\n\n### Multi-Theming Architecture\n\nThemes are separate packages that can be switched at runtime:\n\n```typescript\nimport { register } from '@public-ui/components';\nimport { DEFAULT } from '@public-ui/theme-default';\n\n// Register components with a theme\nregister(DEFAULT, defineCustomElements);\n```\n\n### Theme Structure\n\n- Themes contain only CSS/SASS (no logic)\n- Use CSS layers to control specificity\n- Minimal CSS custom properties to prevent conflicts\n- SASS variables for internal calculations\n- Assets (fonts, icons) included in theme packages\n\n### Benefits\n\n- Organizations can create custom themes without forking\n- Multiple themes can coexist in one application\n- Theme updates don't require component rebuilds\n- Design system flexibility\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/05-building-block-view",
+      "group": "docs/arc42",
+      "name": "05-building-block-view",
+      "path": "docs/arc42/05-building-block-view.md",
+      "code": "# 5. Building Block View\n\nThis section decomposes Public UI - KoliBri into its major structural elements, showing how packages, components, and modules are organized and how they interact. It provides progressively more detailed views of the system's static structure, from high-level packages down to individual component organization.\n\n## 5.1 Whitebox Overall System\n\n```mermaid\ngraph TB\n    subgraph KoliBri System\n        Components[Components Package<br/>Core Web Components]\n        Themes[Themes Package<br/>Visual Styling]\n        Adapters[Adapters Package<br/>Framework Wrappers]\n        Tools[Tools Package<br/>Development Utilities]\n        Samples[Samples Package<br/>Example Applications]\n        Icons[Icons Package<br/>Icon Definitions]\n    end\n    \n    Components -->|styled by| Themes\n    Components -->|generate| Adapters\n    Components -->|demonstrated in| Samples\n    Components -->|use| Icons\n    \n    Adapters -->|used in| Samples\n    Themes -->|used in| Samples\n    \n    Tools -->|migrate| Components\n    Tools -->|test| Themes\n```\n\n### Contained Building Blocks\n\n| Building Block | Responsibility |\n|----------------|----------------|\n| **Components** | Core web component library, provides atomic, accessible HTML components |\n| **Themes** | Visual styling packages, separate presentation from logic |\n| **Adapters** | Framework-specific wrappers (React, Angular, Vue, etc.) for native integration |\n| **Tools** | Development and migration utilities (CLI, visual testing) |\n| **Samples** | Example applications demonstrating component usage |\n| **Icons** | Icon font definitions and assets |\n\n### Important Interfaces\n\n| Interface | Description |\n|-----------|-------------|\n| `@public-ui/components` | Main component library export |\n| `@public-ui/theme-*` | Theme packages (default, ecl, etc.) |\n| `@public-ui/react`, `@public-ui/angular-*`, `@public-ui/vue` | Framework adapters |\n| Theme registration API | `register(theme, defineCustomElements)` |\n\n## 5.2 Components Package (Level 2)\n\n```mermaid\ngraph TB\n    subgraph Components Package\n        ComponentDefs[Component Definitions<br/>TypeScript/Stencil]\n        Schema[Schema Definitions<br/>Type Definitions]\n        Styles[Basis Styles<br/>Layout CSS/SASS]\n        Assets[Assets<br/>Generated Files]\n        OutputTargets[Output Targets<br/>Adapter Generation]\n        \n        ComponentDefs -->|uses| Schema\n        ComponentDefs -->|styled by| Styles\n        ComponentDefs -->|generates| Assets\n        ComponentDefs -->|compiled via| OutputTargets\n    end\n    \n    subgraph Core Concepts\n        A11y[Accessibility Layer]\n        Composition[Composition Logic]\n        Events[Event System]\n        Props[Property API]\n    end\n    \n    ComponentDefs -->|implements| A11y\n    ComponentDefs -->|uses| Composition\n    ComponentDefs -->|emits| Events\n    ComponentDefs -->|exposes| Props\n```\n\n### Component Structure\n\nEach component consists of:\n\n1. **Component Class** (`.tsx` file)\n   - Stencil component decorator\n   - Property definitions with validators\n   - Lifecycle methods\n   - Render method (JSX)\n\n2. **Schema Definition** (`schema/` folder)\n   - TypeScript interfaces for props\n   - Type definitions for internal state\n   - Validation schemas\n\n3. **Basis Styles** (`.scss` files)\n   - Layout-only styles (no colors)\n   - Accessibility compliance (min sizes, focus styles)\n   - Responsive behavior\n\n4. **Tests**\n   - Unit tests (Jest)\n   - E2E tests (Playwright)\n   - Accessibility tests (axe-core)\n\n### Component Categories\n\n```\ncomponents/\n├── @deprecated/        # Deprecated components (maintained for compatibility)\n├── @else/             # Utility components\n├── @shared/           # Shared utilities and mixins\n├── abbr/              # Abbreviation component\n├── accordion/         # Accordion/expandable sections\n├── alert/             # Alert/notification messages\n├── avatar/            # User avatar display\n├── badge/             # Badge/label component\n├── breadcrumb/        # Breadcrumb navigation\n├── button/            # Button component\n├── button-link/       # Button styled as link\n├── card/              # Card container\n├── combobox/          # Combo box/autocomplete\n└── ...               # 50+ more components\n```\n\n### Key Components\n\n| Component | Purpose | Complexity |\n|-----------|---------|------------|\n| `KolButton` | Accessible button with icon and label support | Medium |\n| `KolInputText` | Text input with validation and error handling | High |\n| `KolTable` | Accessible data table with sorting and pagination | High |\n| `KolModal` | Accessible modal dialog with focus management | High |\n| `KolIcon` | Icon display from icon fonts | Low |\n| `KolLink` | Accessible link with icon support | Low |\n\n## 5.3 Themes Package (Level 2)\n\n```mermaid\ngraph TB\n    subgraph Themes Package\n        DefaultTheme[Default Theme<br/>Main Theme]\n        ECLTheme[ECL Theme<br/>EU Commission]\n        ThemeAssets[Theme Assets<br/>Fonts, Icons]\n        \n        subgraph Theme Structure\n            GlobalStyles[Global Theme Styles]\n            ComponentStyles[Component Theme Styles]\n            Tokens[Design Tokens]\n            Variables[SASS Variables]\n        end\n        \n        DefaultTheme -->|contains| GlobalStyles\n        DefaultTheme -->|contains| ComponentStyles\n        DefaultTheme -->|uses| Tokens\n        DefaultTheme -->|uses| Variables\n        DefaultTheme -->|includes| ThemeAssets\n        \n        ECLTheme -->|contains| GlobalStyles\n        ECLTheme -->|contains| ComponentStyles\n        ECLTheme -->|uses| Tokens\n        ECLTheme -->|uses| Variables\n        ECLTheme -->|includes| ThemeAssets\n    end\n```\n\n### Theme Package Structure\n\n```\nthemes/\n├── default/                   # Default KoliBri theme (primary)\n│   ├── src/\n│   │   ├── global.scss       # Global theme styles (layer 4)\n│   │   ├── components/       # Component-specific styles (layer 5)\n│   │   └── _variables.scss   # SASS variables and tokens\n│   └── assets/               # Fonts, icons (copied from components)\n├── ecl/                      # European Commission Library theme\n├── assets/                   # Shared theme assets\n│   ├── material-icons/       # Material Icons font\n│   └── material-symbols/     # Material Symbols font\n└── package.json              # Workspace package\n```\n\n### Theme Styling Layers\n\n1. **Layer 1: A11y Preset** (from `adopted-style-sheets`)\n   - Basic accessibility styles\n   - Minimum sizes, focus indicators\n   - Semantic defaults\n\n2. **Layer 2: Basis Global** (from `components`)\n   - Global layout defaults\n   - Box-sizing, font-size baseline\n   - No colors or margins\n\n3. **Layer 3: Basis Component** (from `components`)\n   - Component-specific layout\n   - Structural CSS only\n   - No colors or margins\n\n4. **Layer 4: Theme Global** (from `themes`)\n   - Colors, fonts, spacing\n   - Design tokens\n   - Brand-specific globals\n\n5. **Layer 5: Theme Component** (from `themes`)\n   - Component-specific theming\n   - Colors, borders, shadows\n   - Complete visual design\n\n## 5.4 Adapters Package (Level 2)\n\n```mermaid\ngraph TB\n    subgraph Adapters Package\n        React[React Adapter]\n        ReactV19[React v19 Adapter]\n        ReactStandalone[React Standalone]\n        Angular19[Angular v19]\n        Angular20[Angular v20]\n        Angular21[Angular v21]\n        Vue[Vue Adapter]\n        Solid[Solid Adapter]\n        Svelte[Svelte Adapter]\n        Vaadin[Vaadin Adapter]\n        Hydrate[Hydrate/SSR]\n    end\n    \n    subgraph Stencil Output Targets\n        ReactOutput[React Output Target]\n        AngularOutput[Angular Output Target]\n        VueOutput[Vue Output Target]\n        SolidOutput[Solid Output Target]\n        SvelteOutput[Svelte Output Target]\n    end\n    \n    ReactOutput -->|generates| React\n    ReactOutput -->|generates| ReactV19\n    ReactOutput -->|generates| ReactStandalone\n    AngularOutput -->|generates| Angular19\n    AngularOutput -->|generates| Angular20\n    AngularOutput -->|generates| Angular21\n    VueOutput -->|generates| Vue\n    SolidOutput -->|generates| Solid\n    SvelteOutput -->|generates| Svelte\n```\n\n### Adapter Generation\n\nAll adapters are **automatically generated** by Stencil output targets. Manual editing is forbidden.\n\n**Generation Process:**\n\n1. Component defined in `packages/components/src/components/`\n2. Stencil builds component\n3. Output targets generate framework-specific wrappers\n4. Adapters placed in `packages/adapters/{framework}/`\n5. Each adapter gets its own npm package\n\n### Framework Support\n\n| Framework | Package(s) | Purpose |\n|-----------|-----------|---------|\n| **React** | `@public-ui/react`, `@public-ui/react-v19`, `@public-ui/react-standalone` | React 18, 19, and standalone builds |\n| **Angular** | `@public-ui/angular-v19`, `@public-ui/angular-v20`, `@public-ui/angular-v21` | Angular versions 19, 20, 21 |\n| **Vue** | `@public-ui/vue` | Vue.js integration |\n| **Solid** | `@public-ui/solid` | SolidJS integration |\n| **Svelte** | `@public-ui/svelte` | Svelte integration |\n| **Preact** | `@public-ui/preact` | Preact integration |\n| **Vaadin** | `@public-ui/vaadin` | Vaadin Flow (Java) integration |\n\n## 5.5 Tools Package (Level 2)\n\n```mermaid\ngraph TB\n    subgraph Tools Package\n        CLI[KoliBri CLI<br/>Migration Tool]\n        VisualTests[Visual Tests<br/>Regression Testing]\n        MCP[MCP Server<br/>Model Context Protocol]\n    end\n    \n    CLI -->|migrates| Components\n    VisualTests -->|tests| Themes\n    MCP -->|provides context| AITools\n```\n\n### Tool Components\n\n1. **KoliBri CLI** (`packages/tools/kolibri-cli/`)\n   - Component migration between versions\n   - Project analysis and dependency checks\n   - Automated code transformations\n   - Migration testing framework\n\n2. **Visual Tests** (`packages/tools/visual-tests/`)\n   - Visual regression testing for themes\n   - Screenshot comparison\n   - Snapshot management\n   - Theme validation\n\n3. **MCP Server** (`packages/tools/mcp/`)\n   - Model Context Protocol server\n   - Provides repository context to AI tools\n   - Helps with code generation and review\n\n## 5.6 Key Interfaces and Dependencies\n\n### External Dependencies\n\n| Package | Purpose | Used By |\n|---------|---------|---------|\n| `@stencil/core` | Web component compiler | Components |\n| `adopted-style-sheets` | Style sheet adoption polyfill | Components, Themes |\n| `@floating-ui/dom` | Positioning engine | Components (tooltips, dropdowns) |\n| `markdown-it` | Markdown rendering | Components (rich text) |\n| `wcag-contrast` | Contrast ratio validation | Components (color validation) |\n\n### Internal Dependencies\n\n```\nComponents → Icons\nComponents → Adapters (generated)\nSamples → Components\nSamples → Adapters\nSamples → Themes\nTools (CLI) → Components (for migration)\nTools (Visual Tests) → Themes\n```\n\n### Build Order\n\n1. **Icons** - Built first, no dependencies\n2. **Components** - Depends on Icons, generates Adapters\n3. **Themes** - Independent, can build in parallel\n4. **Adapters** - Generated by Components build\n5. **Samples** - Depends on Components, Themes, Adapters\n6. **Tools** - Mostly independent\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/06-runtime-view",
+      "group": "docs/arc42",
+      "name": "06-runtime-view",
+      "path": "docs/arc42/06-runtime-view.md",
+      "code": "# 6. Runtime View\n\nThis section illustrates the dynamic behavior of Public UI - KoliBri through key runtime scenarios. Using sequence diagrams and detailed descriptions, it shows how components interact during common operations such as initialization, rendering, event handling, and theme switching.\n\n## 6.1 Component Registration and Initialization\n\nThe component registration process establishes the foundation for all KoliBri components in an application. This critical initialization step must occur before any components are rendered.\n\n```mermaid\nsequenceDiagram\n    participant App as Application\n    participant Register as Registration API\n    participant Theme as Theme Package\n    participant Loader as Component Loader\n    participant Browser as Browser\n    participant Component as Web Component\n    \n    App->>Register: register(theme, defineCustomElements)\n    Register->>Theme: Load theme stylesheets\n    Theme-->>Register: Adopted style sheets\n    Register->>Loader: defineCustomElements(window)\n    Loader->>Browser: Define custom elements\n    Browser-->>Loader: Custom elements registered\n    Loader-->>Register: Registration complete\n    Register-->>App: Components ready\n    \n    Note over Browser,Component: User adds component to DOM\n    \n    Browser->>Component: connectedCallback()\n    Component->>Component: Apply adopted style sheets\n    Component->>Component: Initialize shadow DOM\n    Component->>Component: Render component\n    Component-->>Browser: Component ready\n```\n\n### Scenario: Application Startup\n\n**Prerequisites:**\n\n- Application has installed `@public-ui/components` and a theme package\n- Application imports registration function\n\n**Steps:**\n\n1. Application imports theme and registration function:\n\n   ```typescript\n   import { register } from '@public-ui/components';\n   import { defineCustomElements } from '@public-ui/components/loader';\n   import { DEFAULT } from '@public-ui/theme-default';\n   ```\n\n2. Application calls `register()` with theme and loader:\n\n   ```typescript\n   register(DEFAULT, defineCustomElements);\n   ```\n\n3. Registration function:\n   - Loads theme stylesheets\n   - Calls `defineCustomElements()` to register all components\n   - Components are defined as custom elements in the browser\n\n4. Components are now available as HTML tags (e.g., `<kol-button>`)\n\n## 6.2 Component Rendering\n\n```mermaid\nsequenceDiagram\n    participant User as User/Framework\n    participant Browser as Browser DOM\n    participant Component as KolComponent\n    participant Shadow as Shadow DOM\n    participant Theme as Adopted Styles\n    participant Props as Component Props\n    \n    User->>Browser: Add <kol-component> to DOM\n    Browser->>Component: connectedCallback()\n    Component->>Shadow: attachShadow({mode: 'open'})\n    Shadow-->>Component: Shadow root created\n    \n    Component->>Theme: adoptStyleSheets()\n    Theme-->>Component: Styles applied\n    \n    Component->>Props: Initialize props with defaults\n    Props-->>Component: Props ready\n    \n    Component->>Component: componentWillLoad()\n    Component->>Component: render()\n    Component->>Shadow: Update shadow DOM with JSX\n    Shadow-->>Browser: Component rendered\n    \n    User->>Component: Update prop value\n    Component->>Props: Validate new value\n    Props-->>Component: Validation passed\n    Component->>Component: componentWillRender()\n    Component->>Component: render()\n    Component->>Shadow: Update shadow DOM\n    Shadow-->>Browser: Component re-rendered\n```\n\n### Scenario: Component Lifecycle\n\n**When a component is added to the DOM:**\n\n1. **connectedCallback()** - Browser notifies component of DOM insertion\n2. **attachShadow()** - Component creates shadow DOM for encapsulation\n3. **adoptStyleSheets()** - Theme styles applied via adopted style sheets\n4. **componentWillLoad()** - Component initialization logic runs\n5. **render()** - Component renders JSX to shadow DOM\n6. **componentDidLoad()** - Post-render setup (event listeners, etc.)\n\n**When a component prop changes:**\n\n1. Property setter validates new value\n2. **componentWillRender()** - Pre-render hook\n3. **render()** - Component re-renders with new data\n4. **componentDidRender()** - Post-render hook\n5. Shadow DOM updates efficiently (virtual DOM diffing)\n\n## 6.3 Event Handling and Communication\n\n```mermaid\nsequenceDiagram\n    participant User as User\n    participant Component as KolButton\n    participant EventSystem as Event System\n    participant App as Application\n    participant Framework as Framework Adapter\n    \n    User->>Component: Click button\n    Component->>Component: handleClick()\n    Component->>EventSystem: Emit CustomEvent('click')\n    EventSystem->>Framework: Catch event\n    Framework->>App: Call onClick handler\n    App->>App: Execute business logic\n    \n    opt Update component\n        App->>Component: Update props\n        Component->>Component: Re-render\n    end\n    \n    Component-->>User: Visual feedback (ripple, focus)\n```\n\n### Scenario: Button Click\n\n**Steps:**\n\n1. User clicks button element\n2. Button's internal click handler is triggered\n3. Component validates click (not disabled, etc.)\n4. Component emits CustomEvent with type information\n5. Framework adapter (if used) catches event and calls React/Angular/Vue handler\n6. Application executes business logic\n7. Application may update component props, triggering re-render\n\n**Event Types:**\n\n- Standard HTML events (click, focus, blur, etc.)\n- Custom component events (change, close, select, etc.)\n- Events bubble through shadow DOM boundary (composed: true)\n\n## 6.4 Theme Switching\n\n```mermaid\nsequenceDiagram\n    participant App as Application\n    participant Manager as Theme Manager\n    participant Components as All Components\n    participant Styles as Style Sheets\n    participant Browser as Browser\n    \n    App->>Manager: switchTheme(newTheme)\n    Manager->>Styles: Load new theme CSS\n    Styles-->>Manager: Theme CSS loaded\n    \n    loop For each component\n        Manager->>Components: Update adopted style sheets\n        Components->>Browser: Replace style sheets\n        Browser->>Browser: Re-render with new styles\n        Browser-->>Components: Styles applied\n    end\n    \n    Manager-->>App: Theme switch complete\n```\n\n### Scenario: Runtime Theme Change\n\n**Prerequisites:**\n\n- Multiple theme packages installed\n- Components already registered\n\n**Steps:**\n\n1. Application loads new theme package\n2. Theme manager collects new style sheets\n3. For each component instance in the DOM:\n   - Replace adopted style sheets with new theme\n   - Browser automatically re-renders with new styles\n4. Visual appearance changes without component re-initialization\n\n**Benefits:**\n\n- No component remounting required\n- Instant visual updates\n- Maintains component state\n- Efficient - only styles change, not DOM structure\n\n## 6.5 Form Validation\n\n```mermaid\nsequenceDiagram\n    participant User as User\n    participant Input as KolInputText\n    participant Validator as Validation Logic\n    participant ErrorMsg as Error Message\n    participant Form as Form Context\n    \n    User->>Input: Enter value\n    Input->>Validator: Validate input\n    \n    alt Valid input\n        Validator-->>Input: Validation passed\n        Input->>ErrorMsg: Clear error message\n        Input->>Form: Update form state (valid)\n        Input->>Input: Update visual state (valid)\n    else Invalid input\n        Validator-->>Input: Validation failed\n        Input->>ErrorMsg: Show error message\n        Input->>Form: Update form state (invalid)\n        Input->>Input: Update visual state (error)\n    end\n    \n    Input-->>User: Visual feedback\n    \n    User->>Form: Submit form\n    Form->>Form: Check all inputs\n    \n    alt All valid\n        Form->>Form: Process form data\n    else Has errors\n        Form->>Input: Focus first invalid field\n        Input-->>User: Focus on error\n    end\n```\n\n### Scenario: Input Validation\n\n**Steps:**\n\n1. User enters text in input field\n2. Input component validates on blur or real-time (depending on configuration)\n3. Validation logic checks:\n   - Required field\n   - Pattern matching (regex)\n   - Min/max length\n   - Custom validators\n4. If valid:\n   - Clear error messages\n   - Update visual state to valid\n   - Emit valid event\n5. If invalid:\n   - Show error message\n   - Update visual state to error\n   - Emit invalid event\n   - Prevent form submission\n\n## 6.6 Lazy Loading\n\n```mermaid\nsequenceDiagram\n    participant App as Application\n    participant Loader as Lazy Loader\n    participant Browser as Browser\n    participant Bundle as Component Bundle\n    participant Component as KolComponent\n    \n    App->>Browser: Add <kol-table> to DOM\n    Browser->>Loader: Unknown element detected\n    Loader->>Bundle: Load table.js bundle\n    \n    alt First use\n        Bundle-->>Loader: Download component code\n        Loader->>Browser: Define custom element\n    else Already loaded\n        Bundle-->>Loader: Component in cache\n    end\n    \n    Browser->>Component: Create component instance\n    Component->>Component: Initialize and render\n    Component-->>Browser: Component ready\n    Browser-->>App: Element upgraded\n```\n\n### Scenario: Component Lazy Loading\n\n**Steps:**\n\n1. Application uses component loader (not direct imports)\n2. Browser encounters unknown custom element (e.g., `<kol-table>`)\n3. Stencil's lazy loader intercepts\n4. Loader fetches component bundle on-demand\n5. Component code downloaded and executed\n6. Custom element defined in browser\n7. Browser \"upgrades\" the element from unknown to defined\n8. Component initializes and renders\n\n**Benefits:**\n\n- Smaller initial bundle size\n- Components loaded only when needed\n- Automatic code splitting\n- Improved performance for large applications\n\n## 6.7 Accessibility Integration\n\n```mermaid\nsequenceDiagram\n    participant User as User with AT\n    participant AT as Assistive Technology\n    participant Browser as Browser\n    participant Component as KolComponent\n    participant ARIA as ARIA Attributes\n    participant Keyboard as Keyboard Handler\n    \n    User->>AT: Navigate with keyboard\n    AT->>Browser: Query accessibility tree\n    Browser->>Component: Read ARIA attributes\n    Component->>ARIA: Expose role, state, properties\n    ARIA-->>Browser: Accessibility info\n    Browser-->>AT: Announce component\n    AT-->>User: \"Button, Submit, press Enter to activate\"\n    \n    User->>Keyboard: Press Enter\n    Keyboard->>Component: Keyboard event\n    Component->>Component: Handle key press\n    Component->>Component: Trigger action\n    Component->>ARIA: Update state (aria-pressed)\n    Component->>AT: Announce state change\n    AT-->>User: \"Button pressed\"\n```\n\n### Scenario: Screen Reader Navigation\n\n**Steps:**\n\n1. User with screen reader navigates page with Tab key\n2. Screen reader queries browser's accessibility tree\n3. Component exposes:\n   - Semantic role (button, textbox, dialog, etc.)\n   - State (expanded, selected, checked, etc.)\n   - Properties (label, description, required, etc.)\n4. Screen reader announces component information to user\n5. User interacts via keyboard\n6. Component handles keyboard events (Enter, Space, Arrow keys, Escape)\n7. Component updates ARIA attributes to reflect state changes\n8. Screen reader announces changes to user\n\n**Accessibility Features Built-in:**\n\n- Proper ARIA roles on all interactive elements\n- Keyboard navigation support\n- Focus management (trap focus in modals, etc.)\n- Sufficient color contrast (WCAG 2.2 AAA compliant)\n- Minimum touch target sizes (44x44px)\n- Semantic HTML structure\n- Error message associations\n- Live regions for dynamic content\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/07-deployment-view",
+      "group": "docs/arc42",
+      "name": "07-deployment-view",
+      "path": "docs/arc42/07-deployment-view.md",
+      "code": "# 7. Deployment View\n\nThis section describes the infrastructure and deployment scenarios for Public UI - KoliBri. It covers development environments, CI/CD pipelines, package distribution strategies, and various application deployment patterns that consumers can use when integrating KoliBri components into their projects.\n\n## 7.1 Infrastructure Overview\n\n```mermaid\ngraph TB\n    subgraph Development\n        Dev[Developer Workstation]\n        Git[Git Repository<br/>GitHub]\n    end\n    \n    subgraph CI/CD\n        Actions[GitHub Actions]\n        Tests[Test Runners]\n        Build[Build Pipeline]\n        Security[Security Scanners<br/>CodeQL]\n    end\n    \n    subgraph Distribution\n        NPM[npm Registry]\n        CDN1[unpkg.com]\n        CDN2[jsDelivr]\n    end\n    \n    subgraph Deployment\n        StaticSite[Static Sites]\n        SPA[Single Page Apps]\n        SSR[Server-Side Rendered Apps]\n    end\n    \n    Dev -->|push code| Git\n    Git -->|trigger| Actions\n    Actions -->|run| Tests\n    Actions -->|run| Build\n    Actions -->|run| Security\n    Actions -->|publish| NPM\n    \n    NPM -->|mirror| CDN1\n    NPM -->|mirror| CDN2\n    \n    NPM -->|install| StaticSite\n    NPM -->|install| SPA\n    NPM -->|install| SSR\n    \n    CDN1 -->|load| StaticSite\n    CDN2 -->|load| StaticSite\n```\n\n## 7.2 Development Environment\n\n### Developer Workstation Requirements\n\n| Component | Requirement | Purpose |\n|-----------|------------|---------|\n| **Operating System** | Windows 10+, macOS 11+, or Linux | Platform-independent development |\n| **Node.js** | Version 22.x (required) | Runtime for build tools |\n| **pnpm** | Version 10.x | Package manager |\n| **Git** | Version 2.30+ | Version control |\n| **IDE** | VS Code (recommended) | Code editing with TypeScript support |\n| **Browser** | Chrome/Edge (for testing) | Development and testing |\n\n### Local Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/public-ui/kolibri.git\ncd kolibri\n\n# Install Node.js 22\n# (platform-specific installation)\n\n# Enable pnpm\ncorepack enable pnpm\n\n# Install dependencies\npnpm i --ignore-scripts\n\n# Build all packages\npnpm -r build\n\n# Start development server\ncd packages/samples/react\npnpm start\n```\n\n### Development Ports\n\n| Port | Service | URL |\n|------|---------|-----|\n| 9191 | React sample app | http://localhost:9191 |\n| 4200 | Angular sample app | http://localhost:4200 |\n| Variable | Stencil dev server | http://localhost:3333 |\n\n## 7.3 CI/CD Pipeline\n\n```mermaid\ngraph LR\n    subgraph GitHub Actions Workflows\n        PR[Pull Request] -->|trigger| CI\n        Push[Push to main] -->|trigger| CI\n        Tag[Tag creation] -->|trigger| Publish\n        \n        CI[CI Workflow]\n        Publish[Publish Workflow]\n        Snapshots[Update Snapshots]\n        \n        CI -->|on success| Merge\n        Merge[Merge to main]\n        Merge -->|trigger| Tag\n        Tag -->|trigger| Publish\n    end\n    \n    subgraph CI Steps\n        Install[Install Dependencies]\n        Build[Build All Packages]\n        Lint[Lint Code]\n        Test[Run Tests]\n        Security[Security Scans]\n        \n        Install --> Build\n        Build --> Lint\n        Lint --> Test\n        Test --> Security\n    end\n    \n    subgraph Publish Steps\n        VerifyBuild[Verify Build]\n        Pack[Pack Packages]\n        Provenance[Generate Provenance]\n        NPMPublish[Publish to npm]\n        \n        VerifyBuild --> Pack\n        Pack --> Provenance\n        Provenance --> NPMPublish\n    end\n```\n\n### GitHub Actions Workflows\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| **ci.yml** | Push, Pull Request | Run tests, linting, builds |\n| **publish.yml** | Tag creation | Publish packages to npm with provenance |\n| **update-snapshots.yml** | Manual trigger | Update visual regression test snapshots |\n| **codeql.yml** | Push, Pull Request, Schedule | Security scanning with CodeQL |\n\n### CI Quality Gates\n\nAll PRs must pass:\n\n1. **Build**: All packages must build without errors\n2. **Linting**: ESLint, Stylelint, TypeScript checks must pass\n3. **Unit Tests**: All Jest tests must pass\n4. **E2E Tests**: Playwright tests must pass\n5. **Security**: CodeQL analysis must pass, no high-severity vulnerabilities\n6. **Formatting**: Code must be formatted with Prettier\n\n## 7.4 Package Distribution\n\n### npm Registry\n\nPrimary distribution channel for KoliBri packages:\n\n```mermaid\ngraph TB\n    subgraph \"Published Packages\"\n        Core[\"@public-ui/components\"]\n        DefaultTheme[\"@public-ui/theme-default\"]\n        ECLTheme[\"@public-ui/theme-ecl\"]\n        ReactAdapter[\"@public-ui/react\"]\n        AngularAdapter[\"@public-ui/angular-v21\"]\n        VueAdapter[\"@public-ui/vue\"]\n        CLI[\"@public-ui/kolibri-cli\"]\n    end\n    \n    subgraph \"npm Registry\"\n        Registry[npm Registry]\n    end\n    \n    subgraph CDN\n        unpkg[unpkg.com]\n        jsDelivr[jsDelivr.net]\n    end\n    \n    Core --> Registry\n    DefaultTheme --> Registry\n    ECLTheme --> Registry\n    ReactAdapter --> Registry\n    AngularAdapter --> Registry\n    VueAdapter --> Registry\n    CLI --> Registry\n    \n    Registry -->|mirror| unpkg\n    Registry -->|mirror| jsDelivr\n```\n\n### Package Structure\n\nEach package published to npm includes:\n\n```\n@public-ui/components/\n├── dist/                   # Compiled JavaScript\n│   ├── index.js           # ES module entry\n│   ├── index.cjs.js       # CommonJS entry\n│   ├── types/             # TypeScript definitions\n│   └── esm/               # ES2017 modules\n├── loader/                # Lazy loading wrapper\n├── assets/                # Static assets (icons, etc.)\n├── doc/                   # Generated documentation\n├── custom-elements.json   # Custom Elements Manifest\n└── package.json           # Package metadata\n```\n\n### SLSA Provenance\n\nKoliBri publishes packages with SLSA Build Level 3 provenance:\n\n- Packages built in GitHub Actions with OIDC identity\n- Published with `--provenance` flag\n- Verifiable attestations for all published artifacts\n- Ensures build integrity and supply chain security\n\nVerification:\n\n```bash\n# View provenance metadata\npnpm view @public-ui/components dist.provenance\n\n# Verify signatures (if npm client supports)\npnpm audit signatures --package=@public-ui/components@latest\n```\n\n## 7.5 Application Deployment Scenarios\n\n### Scenario 1: Static Website\n\n```mermaid\ngraph LR\n    Build[Build Process] -->|bundle| Static[Static Assets]\n    Static -->|deploy| CDN[CDN/Static Host]\n    CDN -->|serve| Browser[User Browser]\n    Browser -->|load| Components[KoliBri Components]\n```\n\n**Deployment:**\n\n- Components bundled with application code\n- Deployed to static hosting (Netlify, Vercel, GitHub Pages, S3, etc.)\n- No server-side rendering\n- All assets cached by CDN\n\n**Example:**\n\n```html\n<!DOCTYPE html>\n<html>\n\t<head>\n\t\t<script type=\"module\" src=\"./kolibri-components.js\"></script>\n\t\t<link rel=\"stylesheet\" href=\"./theme-default.css\" />\n\t</head>\n\t<body>\n\t\t<kol-button _label=\"Click me\"></kol-button>\n\t</body>\n</html>\n```\n\n### Scenario 2: Single Page Application (SPA)\n\n```mermaid\ngraph LR\n    Framework[React/Angular/Vue App] -->|bundle| Webpack[Bundler]\n    Webpack -->|build| Assets[Optimized Assets]\n    Assets -->|deploy| Server[Web Server]\n    Server -->|serve| Browser[User Browser]\n    Browser -->|lazy load| Components[KoliBri Components]\n```\n\n**Deployment:**\n\n- Components imported via framework adapter\n- Bundled with application via Webpack/Vite/Rollup\n- Lazy loading for code splitting\n- Deployed to application server or CDN\n\n**Example (React):**\n\n```typescript\nimport { KolButton } from '@public-ui/react';\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\n\nawait register(DEFAULT, defineCustomElements);\n\nfunction App() {\n\treturn <KolButton _label=\"Click me\" />;\n}\n```\n\n### Scenario 3: Server-Side Rendering (SSR)\n\n```mermaid\ngraph LR\n    SSR[SSR Server] -->|render| HTML[Initial HTML]\n    HTML -->|send| Browser[User Browser]\n    Browser -->|hydrate| Components[KoliBri Components]\n    Browser -->|request| SSR\n```\n\n**Deployment:**\n\n- Components hydrated on client after SSR\n- Initial HTML rendered server-side\n- Client-side hydration for interactivity\n- Deployed to Node.js server or serverless functions\n\n**Considerations:**\n\n- Use hydrate adapter for SSR support\n- Components need client-side hydration\n- Shadow DOM requires careful SSR handling\n\n### Scenario 4: CDN Only (No Build)\n\n```mermaid\ngraph LR\n    CDN[unpkg/jsDelivr] -->|serve| Browser[User Browser]\n    Browser -->|load| Components[KoliBri Components]\n```\n\n**Deployment:**\n\n- Load components directly from CDN\n- No build step required\n- Ideal for prototypes and simple sites\n\n**Example:**\n\n```html\n<script type=\"module\">\n\timport { defineCustomElements } from 'https://unpkg.com/@public-ui/components@latest/loader/index.mjs';\n\timport { register } from 'https://unpkg.com/@public-ui/components@latest/dist/index.js';\n\timport { DEFAULT } from 'https://unpkg.com/@public-ui/theme-default@latest/index.js';\n\n\tawait register(DEFAULT, defineCustomElements);\n</script>\n```\n\n## 7.6 Deployment Topology\n\n### Multi-Tier Architecture\n\n```mermaid\ngraph TB\n    subgraph \"User Tier\"\n        Browser[Web Browser]\n        AT[Assistive Technology]\n    end\n    \n    subgraph \"CDN Tier\"\n        CDN[Content Delivery Network]\n    end\n    \n    subgraph \"Application Tier\"\n        AppServer[Application Server - Node.js/Static]\n        API[Backend API - optional]\n    end\n    \n    subgraph \"Data Tier\"\n        DB[Database - optional]\n    end\n    \n    Browser -->|HTTPS| CDN\n    Browser -->|HTTPS| AppServer\n    AT -->|Accessibility API| Browser\n    \n    CDN -->|fallback| AppServer\n    AppServer -->|HTTP/REST| API\n    API -->|query| DB\n```\n\n### Component Loading Strategy\n\n1. **Initial Load**:\n   - HTML page with component tags\n   - Core component loader script\n   - Theme CSS\n\n2. **Lazy Loading**:\n   - Individual component bundles loaded on-demand\n   - Only used components downloaded\n   - Browser caching for subsequent loads\n\n3. **Caching Strategy**:\n   - Components: Long cache (immutable versions)\n   - Themes: Long cache (immutable versions)\n   - Application code: Cache with revalidation\n\n## 7.7 Monitoring and Observability\n\n### Client-Side Monitoring\n\nRecommendations for applications using KoliBri:\n\n- **Performance Monitoring**: Web Vitals\n- **Error Tracking**: Sentry, Rollbar (application level)\n- **Accessibility Monitoring**: axe DevTools, automated scans\n- **Bundle Size Tracking**: bundlephobia, webpack-bundle-analyzer\n\n### Build Pipeline Monitoring\n\n- **CI/CD Status**: GitHub Actions status badges\n- **Test Coverage**: Jest coverage reports\n- **Security Alerts**: GitHub Dependabot, CodeQL alerts\n- **Package Health**: npm package health score\n\n### Metrics\n\nKey metrics tracked:\n\n- **Build Time**: Full build duration (~2 minutes)\n- **Test Duration**: Unit + E2E test execution (~3 minutes)\n- **Package Size**: Individual package sizes\n- **Download Stats**: npm download counts\n- **Issue Resolution Time**: Time to close issues/PRs\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/08-cross-cutting-concepts",
+      "group": "docs/arc42",
+      "name": "08-cross-cutting-concepts",
+      "path": "docs/arc42/08-cross-cutting-concepts.md",
+      "code": "# 8. Cross-cutting Concepts\n\nThis section covers architectural principles and patterns that span multiple components and layers of the system. These cross-cutting concerns—accessibility, internationalization, security, performance, and testing—apply consistently throughout Public UI - KoliBri and form the foundation of its design philosophy.\n\n## 8.1 Accessibility (A11y)\n\nAccessibility is the cornerstone of Public UI - KoliBri. Every component is designed and tested to ensure usability for all people, regardless of their abilities or the assistive technologies they use.\n\n### Principles\n\nPublic UI - KoliBri follows the **WCAG 2.2 Level AAA** standards and **BITV** requirements as core principles, always implementing the latest version of accessibility standards.\n\n### Implementation Strategy\n\n| Aspect | Implementation | Verification |\n|--------|---------------|--------------|\n| **Keyboard Navigation** | All interactive elements accessible via keyboard (Tab, Enter, Space, Arrow keys, Escape) | Manual keyboard testing, automated tests |\n| **Screen Reader Support** | Proper ARIA roles, labels, and states | Screen reader testing (JAWS, NVDA, VoiceOver) |\n| **Color Contrast** | Minimum 4.5:1 for text, 3:1 for UI components | wcag-contrast library validation |\n| **Touch Targets** | Minimum 44x44px for interactive elements | Built into component CSS, automated tests |\n| **Focus Management** | Visible focus indicators, focus trapping in modals | Visual inspection, automated tests |\n| **Semantic HTML** | Use correct HTML elements (button, input, nav, etc.) | HTML validation, manual review |\n| **Alternative Text** | Images and icons have text alternatives | Manual review, automated checks |\n| **Form Labels** | All form fields have associated labels | Automated accessibility tests |\n\n### Accessibility Testing Pyramid\n\n```mermaid\ngraph TB\n    Manual[Manual Testing<br/>Screen readers, keyboard]\n    E2E[E2E Tests<br/>Playwright + axe-core]\n    Unit[Unit Tests<br/>ARIA attribute checks]\n    \n    Manual -->|validates| E2E\n    E2E -->|validates| Unit\n```\n\n### Built-in Accessibility Features\n\nEvery KoliBri component includes:\n\n1. **Semantic Structure**: Correct HTML elements and ARIA roles\n2. **Keyboard Support**: Full keyboard navigation\n3. **Focus Management**: Visible focus, logical tab order\n4. **ARIA Attributes**: Dynamic state and property updates\n5. **Contrast Compliance**: Colors meet WCAG standards\n6. **Responsive Text**: Supports browser zoom up to 200%\n7. **Error Handling**: Clear error messages with programmatic associations\n\n## 8.2 Internationalization (i18n)\n\nPublic UI - KoliBri provides robust internationalization support through browser-based language detection and flexible configuration options.\n\n### Language Support\n\nComponents support internationalization based on browser language and locale settings, as well as HTML element attributes:\n\n- **Browser Language Detection**: Automatically uses browser's language settings\n- **HTML Attributes**: Respects `lang`, `dir` (for RTL), and locale attributes on the `html` element\n- **Translation Management**: Optional key-value language maps configured during bootstrap/register call\n- **i18next Integration**: Native support for i18next translation framework\n\n### Implementation\n\n```typescript\n// Translation management via register configuration for component-internal texts\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\n\nawait register(DEFAULT, defineCustomElements, {\n\ttranslations: {\n\t\t'de': {\n\t\t\t'kol.button.close': 'Schließen',\n\t\t\t'kol.modal.close': 'Schließen'\n\t\t},\n\t\t'en': {\n\t\t\t'kol.button.close': 'Close',\n\t\t\t'kol.modal.close': 'Close'\n\t\t}\n\t}\n});\n\n// For application text, pass translated strings directly via props\n<KolButton _label={t('app.button.submit')} />\n\n// Browser locale respected for date/number formatting\n<KolInputDate /> // Automatically uses browser locale for formatting\n```\n\n### Best Practices\n\n- Set `lang` and `dir` attributes on the HTML element for proper localization\n- Component-internal texts can be customized via translation keys in register configuration\n- Application-specific text should be translated externally and passed via component props\n- Use i18next integration for complex translation needs\n- Components automatically format dates, numbers, and currencies based on browser locale\n\n## 8.3 Security\n\n### Security Principles\n\n| Principle | Implementation |\n|-----------|---------------|\n| **No XSS Vulnerabilities** | All user input sanitized, Shadow DOM provides isolation |\n| **Content Security Policy** | Components work with strict CSP |\n| **Dependency Security** | Regular security scans, automated updates |\n| **Secure Defaults** | Components configured securely by default |\n| **SLSA Provenance** | Build Level 3 attestations for published packages |\n\n### Security Measures\n\n1. **Dependency Scanning**\n   - Dependabot alerts for vulnerable dependencies\n   - Regular dependency updates\n   - License compliance checks\n\n2. **Code Scanning**\n   - CodeQL analysis in CI/CD\n   - Static security analysis\n   - Vulnerability detection\n\n3. **Build Security**\n   - SLSA Build Level 3 compliance\n   - Signed packages with provenance\n   - Reproducible builds\n\n4. **Input Validation**\n   - All props validated with TypeScript types\n   - Runtime validation for critical values\n   - Sanitization of HTML content\n\n### Security Best Practices\n\n- Never trust user input\n- Use TypeScript for type safety\n- Keep dependencies updated\n- Follow OWASP guidelines\n- Report security issues responsibly\n\n## 8.4 Performance\n\n### Performance Principles\n\n| Principle | Implementation |\n|-----------|---------------|\n| **Small Bundle Size** | Tree-shakeable exports, lazy loading |\n| **Fast Rendering** | Shadow DOM, virtual DOM diffing |\n| **Efficient Styling** | Adopted style sheets, CSS containment |\n| **Minimal Dependencies** | Only essential runtime dependencies |\n| **Optimal Loading** | Code splitting, lazy component loading |\n\n### Performance Optimization Techniques\n\n1. **Lazy Loading**\n   - Components loaded on-demand\n   - Reduces initial bundle size\n   - Faster page load times\n\n2. **Shadow DOM**\n   - Efficient style scoping\n   - No global CSS pollution\n   - Optimized rendering\n\n3. **Adopted Style Sheets**\n   - Shared styles across components\n   - Efficient theme switching\n   - Memory efficient\n\n4. **Code Splitting**\n   - Each component in separate bundle\n   - Only load what you use\n   - Optimized for HTTP/2\n\n### Performance Metrics\n\nTarget metrics for applications using KoliBri:\n\n- **First Contentful Paint**: <1.8s\n- **Time to Interactive**: <3.8s\n- **Total Blocking Time**: <300ms\n- **Cumulative Layout Shift**: <0.1\n\n## 8.5 Testing Strategy\n\n```mermaid\ngraph TB\n    Manual[Manual Testing]\n    E2E[E2E Tests<br/>Playwright]\n    Visual[Visual Tests<br/>Screenshot Comparison]\n    Unit[Unit Tests<br/>Jest]\n    Lint[Linting<br/>ESLint, Stylelint]\n    Type[Type Checking<br/>TypeScript]\n    \n    Type --> Lint\n    Lint --> Unit\n    Unit --> Visual\n    Visual --> E2E\n    E2E --> Manual\n```\n\n### Testing Levels\n\n1. **Type Checking** (TypeScript)\n   - Catch type errors at compile time\n   - Ensure API correctness\n   - IDE support\n\n2. **Linting** (ESLint, Stylelint)\n   - Enforce code quality\n   - Consistent code style\n   - Best practice compliance\n\n3. **Unit Tests** (Jest)\n   - Test component logic\n   - Property validation\n   - State management\n   - Coverage target: >80%\n\n4. **Visual Tests**\n   - Screenshot comparison\n   - Theme validation\n   - Cross-browser appearance\n\n5. **E2E Tests** (Playwright)\n   - User workflows\n   - Component interactions\n   - Accessibility validation (axe-core)\n\n6. **Manual Testing**\n   - Screen reader testing\n   - Cross-browser testing\n   - Exploratory testing\n\n### Test Automation\n\n- **CI/CD Integration**: All tests run in GitHub Actions\n- **Pre-commit Hooks**: Linting and formatting\n- **Pull Request Checks**: All tests must pass\n- **Scheduled Tests**: Regular security and dependency scans\n\n## 8.6 Error Handling\n\n### Error Handling Strategy\n\n| Error Type | Handling Approach |\n|-----------|-------------------|\n| **Invalid Props** | TypeScript validation, runtime warnings, fallback to defaults |\n| **Missing Dependencies** | Clear error messages, documentation links |\n| **Browser Support** | Feature detection, graceful degradation, error messages |\n| **Theme Errors** | Fallback to accessibility baseline, console warnings |\n| **Runtime Errors** | Try-catch blocks, error boundaries (in frameworks), user-friendly messages |\n\n### Error Communication\n\n1. **Developer Errors** (Console)\n   - TypeScript type errors\n   - Invalid property warnings\n   - Missing required props\n\n2. **User Errors** (UI)\n   - Form validation errors\n   - Required field indicators\n   - Inline error messages\n   - Error summaries\n\n3. **Accessibility Errors**\n   - ARIA live regions for dynamic errors\n   - Error messages associated with fields\n   - Clear error identification\n\n## 8.7 Documentation\n\n### Documentation Strategy\n\n```mermaid\ngraph TB\n    Code[Source Code] -->|generates| API[API Documentation]\n    Code -->|contains| Comments[Inline Comments]\n    Samples[Sample Applications] -->|demonstrates| Usage[Usage Examples]\n    Guides[Written Guides] -->|explains| Concepts[Concepts]\n    \n    API --> Website[Documentation Website]\n    Usage --> Website\n    Concepts --> Website\n    \n    Website -->|consumed by| Developers[Developers]\n```\n\n### Documentation Types\n\n1. **API Documentation**\n   - Auto-generated from TypeScript\n   - Component properties and methods\n   - Event descriptions\n   - Type definitions\n\n2. **Usage Examples**\n   - Working code samples\n   - React sample application\n   - Angular sample application\n   - Framework integration guides\n\n3. **Conceptual Documentation**\n   - Architecture overview\n   - Theming guide\n   - Accessibility guidelines\n   - Migration guides\n\n4. **Inline Documentation**\n   - JSDoc comments in code\n   - TypeScript type definitions\n   - CSS comments explaining styles\n\n### Documentation Principles\n\n- **Keep docs in sync**: Update docs with code changes\n- **Examples over explanation**: Show working code\n- **Searchable**: Clear structure and naming\n- **Multi-level**: From quick start to advanced topics\n- **Accessible**: Documentation itself must be accessible\n\n## 8.8 Code Quality\n\n### Quality Enforcement\n\n| Aspect | Tool | Enforcement |\n|--------|------|------------|\n| **Formatting** | Prettier | Pre-commit hook, CI check |\n| **Linting** | ESLint, Stylelint | CI check, no inline disabling |\n| **Type Safety** | TypeScript | Compilation step, strict mode |\n| **Testing** | Jest, Playwright | CI check, coverage requirements |\n| **Security** | CodeQL, Dependabot | Automated scanning |\n| **Code Review** | GitHub PR reviews | Required before merge |\n\n### Code Conventions\n\n1. **Naming Conventions**\n   - Components: PascalCase with \"Kol\" prefix (KolButton)\n   - Properties: camelCase, prefixed with underscore (_label)\n   - CSS classes: BEM methodology\n   - Files: kebab-case\n\n2. **File Organization**\n   - One component per directory\n   - Component, styles, tests together\n   - Alphabetical ordering in lists\n\n3. **Code Style**\n   - 160 character line width\n   - Tabs for indentation\n   - Single quotes\n   - Trailing commas\n   - No semicolons (when optional)\n\n## 8.9 Versioning and Compatibility\n\n### Semantic Versioning\n\nKoliBri strictly follows SemVer 2.0:\n\n- **Major**: Breaking changes\n- **Minor**: New features, backwards compatible\n- **Patch**: Bug fixes, backwards compatible\n\n### Compatibility Strategy\n\n| Version Type | Support Duration | Purpose |\n|-------------|-----------------|---------|\n| **LTS** | 3 years | Long-term support for enterprises |\n| **STS** | 15 months | Short-term support for rapid innovation |\n| **Development** | Until next release | Latest features and improvements |\n\n### Breaking Change Management\n\n1. **Deprecation First**: Mark features as deprecated before removal\n2. **Migration Guide**: Provide detailed upgrade instructions\n3. **Migration Tool**: CLI tool automates code updates\n4. **Parallel Support**: Deprecated features work in one major version\n5. **Clear Communication**: Release notes explain all breaking changes\n\n## 8.10 Build and Release\n\n### Build Process\n\n```mermaid\ngraph LR\n    Source[Source Code] -->|TypeScript| Compile[Compile]\n    Compile -->|Stencil| Generate[Generate Outputs]\n    Generate -->|Rollup| Bundle[Bundle]\n    Bundle -->|Minify| Optimize[Optimize]\n    Optimize -->|Package| Dist[Distribution Files]\n```\n\n### Build Artifacts\n\nEach package produces:\n\n- ES Modules (modern browsers)\n- CommonJS (Node.js, legacy bundlers)\n- TypeScript definitions (.d.ts)\n- Custom Elements JSON (metadata)\n- Lazy loading wrapper\n- Source maps (development)\n\n### Release Process\n\n1. **Version Bump**: Update version in all package.json files\n2. **Changelog**: Document all changes\n3. **Tag Creation**: Create git tag (triggers CI)\n4. **Build**: CI builds all packages\n5. **Test**: CI runs full test suite\n6. **Publish**: CI publishes to npm with provenance\n7. **Documentation**: Update documentation site\n8. **Announcement**: Release notes, social media\n\n### Release Channels\n\n- **Latest**: Current stable release\n- **Next**: Pre-release versions for testing\n- **LTS**: Long-term support versions\n- **Legacy**: Older versions (security fixes only)\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/09-architecture-decisions",
+      "group": "docs/arc42",
+      "name": "09-architecture-decisions",
+      "path": "docs/arc42/09-architecture-decisions.md",
+      "code": "# 9. Architecture Decisions\n\nThis section documents the significant architectural decisions made during the development of Public UI - KoliBri. Each Architecture Decision Record (ADR) captures the context, decision, and consequences of important choices, providing transparency and rationale for future maintainers and contributors.\n\n## 9.1 Decision Records\n\n### ADR-001: Use Web Components as Foundation\n\n**Status:** Accepted\n\n**Context:**\nKoliBri needs to be framework-agnostic and work with any JavaScript framework (React, Angular, Vue) or vanilla JavaScript. We need a technology that is standardized and will be supported long-term.\n\n**Decision:**\nUse Web Components (Custom Elements, Shadow DOM) as the foundation for all components.\n\n**Consequences:**\n\n- ✅ Framework-agnostic by design\n- ✅ Based on W3C standards (long-term stability)\n- ✅ Native browser support (no framework overhead)\n- ✅ True encapsulation via Shadow DOM\n- ❌ Requires polyfills for older browsers\n- ❌ Shadow DOM can complicate certain styling scenarios\n- ❌ Limited to Custom Elements API capabilities\n\n**Alternatives Considered:**\n\n- React components: Too coupled to React ecosystem\n- Framework-specific libraries: Violates framework-agnostic goal\n- Pure HTML/CSS: No component logic or reusability\n\n### ADR-002: Use Stencil.js as Compiler\n\n**Status:** Accepted\n\n**Context:**\nWriting Web Components directly is verbose and error-prone. We need a tool that improves developer experience while still generating standard Web Components.\n\n**Decision:**\nUse Stencil.js as the Web Component compiler.\n\n**Consequences:**\n\n- ✅ Excellent developer experience (TypeScript, JSX, decorators)\n- ✅ Generates framework adapters automatically\n- ✅ Optimized output (lazy loading, code splitting)\n- ✅ Strong TypeScript support\n- ❌ Dependency on Stencil project\n- ❌ Learning curve for contributors\n- ❌ Build step required\n\n**Alternatives Considered:**\n\n- Lit: Good DX, but no automatic framework adapter generation\n- Native Web Components: Too verbose, poor DX\n- Polymer: Deprecated and not actively maintained\n- Custom solution: Too much maintenance overhead\n\n### ADR-003: Separate Themes from Components\n\n**Status:** Accepted\n\n**Context:**\nDifferent organizations need different visual designs (corporate design, design systems). Coupling styling with components makes customization difficult.\n\n**Decision:**\nSeparate themes into independent packages that can be registered at runtime.\n\n**Consequences:**\n\n- ✅ Organizations can create custom themes without forking\n- ✅ Runtime theme switching possible\n- ✅ Multiple themes can be maintained independently\n- ✅ Theme updates don't require component rebuilds\n- ❌ More complex architecture\n- ❌ Theme and component versions must be synchronized\n- ❌ Additional packages to maintain\n\n**Alternatives Considered:**\n\n- CSS variables only: Insufficient for complex theming\n- Inline styles: Couples styling with logic\n- Multiple component versions: Maintenance nightmare\n- Fork per organization: Fragmentation, no collaboration\n\n### ADR-004: Use Shadow DOM for Encapsulation\n\n**Status:** Accepted\n\n**Context:**\nComponents need style isolation to prevent CSS conflicts. Global CSS in large applications often leads to unintended side effects.\n\n**Decision:**\nUse Shadow DOM for all components to achieve true style encapsulation.\n\n**Consequences:**\n\n- ✅ Perfect style isolation\n- ✅ No CSS naming conflicts\n- ✅ Components can't be accidentally broken by global styles\n- ✅ Predictable rendering behavior\n- ❌ Can't style component internals from outside (by design)\n- ❌ Some CSS selectors don't work across shadow boundary\n- ❌ Slightly more complex debugging\n\n**Alternatives Considered:**\n\n- No Shadow DOM: Style conflicts and unpredictable behavior\n- Scoped styles (like Vue): Not true encapsulation\n- CSS Modules: Requires build tooling, not standards-based\n- BEM naming: Conventions can be broken, not enforced\n\n### ADR-005: Use Adopted Style Sheets\n\n**Status:** Accepted\n\n**Context:**\nThemes need to be applied efficiently to many component instances. Traditional style injection would be inefficient and create many duplicate style elements.\n\n**Decision:**\nUse Adopted Style Sheets API for theme application.\n\n**Consequences:**\n\n- ✅ Efficient style sharing across components\n- ✅ Runtime theme switching without re-rendering\n- ✅ Memory efficient (styles shared, not duplicated)\n- ✅ Fast theme changes\n- ❌ Requires modern browser (or polyfill)\n- ❌ More complex theming implementation\n\n**Alternatives Considered:**\n\n- Style tags in each component: Inefficient, memory intensive\n- Global styles with CSS custom properties: Breaks encapsulation\n- Inline styles: Not maintainable, no CSS features\n- Single style tag: Difficult to manage, no encapsulation\n\n### ADR-006: Use TypeScript\n\n**Status:** Accepted\n\n**Context:**\nJavaScript's dynamic nature leads to runtime errors that could be caught at compile time. Component APIs need strong typing for good developer experience.\n\n**Decision:**\nWrite all code in TypeScript with strict mode enabled.\n\n**Consequences:**\n\n- ✅ Type safety catches errors early\n- ✅ Excellent IDE support (autocomplete, refactoring)\n- ✅ Self-documenting code via types\n- ✅ Better maintainability\n- ❌ Compilation step required\n- ❌ Learning curve for contributors\n- ❌ More verbose code\n\n**Alternatives Considered:**\n\n- JavaScript with JSDoc: Limited type checking\n- Flow: Less ecosystem support than TypeScript\n- Plain JavaScript: Too error-prone for large codebase\n- Reason/ReScript: Too niche, limited adoption\n\n### ADR-007: Use pnpm Workspace Monorepo\n\n**Status:** Accepted\n\n**Context:**\nKoliBri consists of many packages (components, themes, adapters, tools) that need to be developed together but released independently.\n\n**Decision:**\nUse pnpm workspace as the monorepo solution with Nx for build orchestration.\n\n**Consequences:**\n\n- ✅ Efficient dependency management\n- ✅ Shared dependencies (disk space savings)\n- ✅ Strict dependency resolution (no phantom dependencies)\n- ✅ Fast installs\n- ✅ Nx provides intelligent caching and task orchestration\n- ❌ More complex setup than single package\n- ❌ pnpm less common than npm/yarn\n- ❌ Steeper learning curve for new contributors\n\n**Alternatives Considered:**\n\n- npm workspaces: Less efficient than pnpm\n- Yarn workspaces: Phantom dependencies issue\n- Lerna: Overhead without pnpm's benefits\n- Separate repositories: Coordination nightmare\n\n### ADR-008: Five-Layer Styling Architecture\n\n**Status:** Accepted\n\n**Context:**\nStyling needs to be separated between accessibility requirements, layout structure, and visual design. Teams need to customize appearance without breaking accessibility or layout.\n\n**Decision:**\nImplement a five-layer styling architecture:\n\n1. A11y Preset Layer (accessibility baseline)\n2. Basis Global Layer (global layout)\n3. Basis Component Layer (component layout)\n4. Theme Global Layer (global theme)\n5. Theme Component Layer (component theme)\n\n**Consequences:**\n\n- ✅ Clear separation of concerns\n- ✅ Accessibility can't be accidentally broken\n- ✅ Themes can customize appearance without breaking layout\n- ✅ Predictable style precedence\n- ❌ More complex to understand initially\n- ❌ More files to maintain\n- ❌ Strict conventions required\n\n**Alternatives Considered:**\n\n- Flat CSS structure: Too easy to break things\n- Two-layer (component + theme): Insufficient separation\n- Theme-only styling: Accessibility not guaranteed\n- Inline styles with theme tokens: Not maintainable\n\n### ADR-009: Minimize CSS Custom Properties\n\n**Status:** Accepted\n\n**Context:**\nCSS custom properties (variables) cross the shadow DOM boundary and remain in the global cascade. Overuse can lead to naming conflicts and unpredictable behavior.\n\n**Decision:**\nUse CSS custom properties sparingly, only for values that must be customizable from outside. Use SASS variables for internal calculations.\n\n**Consequences:**\n\n- ✅ Prevents variable name conflicts\n- ✅ More robust components\n- ✅ Clearer API surface\n- ✅ Less confusion about what can be customized\n- ❌ Less flexibility for advanced users\n- ❌ More SASS compilation required\n\n**Alternatives Considered:**\n\n- Heavy use of CSS custom properties: Too many conflicts\n- No CSS custom properties: Not customizable enough\n- Everything as custom properties: Global namespace pollution\n- Component-specific prefixes only: Still risks conflicts\n\n### ADR-010: LTS/STS Release Model\n\n**Status:** Accepted\n\n**Context:**\nEnterprises need stable, long-supported versions. Innovation requires rapid iteration. These needs conflict.\n\n**Decision:**\nImplement a dual release model:\n\n- **LTS (Long-Term Support)**: 3 years support, conservative changes\n- **STS (Short-Term Support)**: 15 months support, rapid innovation\n\n**Consequences:**\n\n- ✅ Enterprises get stability (LTS)\n- ✅ Innovation continues (STS)\n- ✅ Clear expectations for support duration\n- ✅ Predictable upgrade cycles\n- ❌ More versions to maintain\n- ❌ More complex release management\n- ❌ Documentation for multiple versions\n\n**Alternatives Considered:**\n\n- Single release line: Can't balance stability and innovation\n- Only LTS: Slows innovation\n- Only STS: No enterprise adoption\n- Multiple concurrent majors: Too much maintenance\n\n### ADR-011: Semantic Versioning Strict Compliance\n\n**Status:** Accepted\n\n**Context:**\nUsers need to trust that updates won't break their applications unexpectedly. Clear versioning helps with dependency management.\n\n**Decision:**\nStrictly follow Semantic Versioning 2.0:\n\n- Major: Breaking changes\n- Minor: New features, backwards compatible\n- Patch: Bug fixes, backwards compatible\n\n**Consequences:**\n\n- ✅ Predictable upgrade safety\n- ✅ Clear communication of changes\n- ✅ Better dependency management\n- ✅ Trust from community\n- ❌ Major versions can come frequently\n- ❌ Deprecation process takes time\n- ❌ Cannot fix design mistakes easily\n\n**Alternatives Considered:**\n\n- Rolling releases: Unpredictable, risky\n- Calendar versioning: Doesn't communicate breaking changes\n- Loose SemVer: Erodes trust\n- Pre-1.0 forever: Signals instability\n\n### ADR-012: Auto-generate Framework Adapters\n\n**Status:** Accepted\n\n**Context:**\nSupporting multiple frameworks (React, Angular, Vue, etc.) requires framework-specific wrappers. Manually maintaining these would be time-consuming and error-prone.\n\n**Decision:**\nUse Stencil output targets to automatically generate framework adapters from component definitions.\n\n**Consequences:**\n\n- ✅ No manual adapter maintenance\n- ✅ Consistent APIs across frameworks\n- ✅ Automatic updates when components change\n- ✅ Less code to maintain\n- ❌ Dependent on Stencil output target quality\n- ❌ Limited control over generated code\n- ❌ Framework-specific quirks harder to address\n\n**Alternatives Considered:**\n\n- Manual adapters: Too much maintenance\n- Single framework: Violates framework-agnostic goal\n- No adapters (use web components directly): Poor DX in some frameworks\n- Separate adapter projects: Coordination overhead\n\n### ADR-013: SLSA Build Level 3 for Supply Chain Security\n\n**Status:** Accepted\n\n**Context:**\nSupply chain attacks are increasing. Users need assurance that published packages haven't been tampered with and were built from verified source code.\n\n**Decision:**\nImplement SLSA Build Level 3 with npm provenance for all published packages.\n\n**Consequences:**\n\n- ✅ Verifiable build provenance\n- ✅ Supply chain security\n- ✅ Increased trust from users\n- ✅ Meets government/enterprise security requirements\n- ❌ More complex CI/CD setup\n- ❌ Requires GitHub OIDC configuration\n- ❌ npm provenance support required\n\n**Alternatives Considered:**\n\n- No provenance: Less secure, doesn't meet some requirements\n- SLSA Level 1/2: Insufficient security guarantees\n- Self-signed signatures: Not verifiable by ecosystem\n- Package signing only: Doesn't prove source\n\n### ADR-014: Use Playwright for E2E Testing\n\n**Status:** Accepted\n\n**Context:**\nComponents need end-to-end testing across multiple browsers. Testing framework should support modern web technologies including Web Components and Shadow DOM.\n\n**Decision:**\nUse Playwright as the E2E testing framework.\n\n**Consequences:**\n\n- ✅ Excellent Shadow DOM support\n- ✅ Multi-browser testing (Chromium, Firefox, WebKit)\n- ✅ Fast and reliable\n- ✅ Good developer experience\n- ✅ Built-in accessibility testing (axe-core integration)\n- ❌ Learning curve for contributors\n- ❌ Test maintenance overhead\n\n**Alternatives Considered:**\n\n- Cypress: Weaker Shadow DOM support at the time\n- Puppeteer: Chrome-only, less features\n- Selenium: Older, slower, more complex\n- TestCafe: Less ecosystem support\n\n### ADR-015: Automatic Component-Level Lazy Loading via Stencil\n\n**Status:** Accepted\n\n**Context:**\nApplications using KoliBri might not need all 50+ components loaded immediately. Bundle size and performance are critical concerns for web applications.\n\n**Decision:**\nRely on Stencil's built-in lazy loading and code splitting capabilities, which automatically load only the components actually used in the application on a per-component basis.\n\n**Consequences:**\n\n- ✅ Components automatically loaded on-demand when first used\n- ✅ No manual configuration required for lazy loading\n- ✅ Minimal initial bundle size\n- ✅ Optimal performance without developer intervention\n- ✅ Each component compiled to separate bundle for efficient loading\n- ❌ Requires modern bundler support for ES modules\n- ❌ Additional HTTP requests for each component (mitigated by HTTP/2)\n\n**Alternatives Considered:**\n\n- Split into category packages: More complex maintenance, less flexible\n- Single monolithic bundle: Larger initial load, slower performance\n- Manual lazy loading: More developer burden, error-prone\n\n### ADR-016: SASS Variables for Base Theme (No Design Tokens)\n\n**Status:** Accepted\n\n**Context:**\nDesign tokens (CSS custom properties) are becoming popular for theming, but they cross the Shadow DOM boundary and can be manipulated from outside the component, potentially breaking the component's appearance and reducing robustness.\n\n**Decision:**\nUse SASS variables exclusively for internal calculations and styling in the base theme. Organizations can optionally use design tokens in their custom themes, but the base theme avoids them to maintain component robustness and prevent external manipulation.\n\n**Consequences:**\n\n- ✅ Components remain robust and predictable in all environments\n- ✅ No external manipulation of component internals via CSS variables\n- ✅ Similar maintainability benefits as design tokens (variables, calculations)\n- ✅ Organizations free to use design tokens in custom themes if desired\n- ✅ Clear separation between component-internal styling and external customization\n- ❌ Less runtime flexibility compared to CSS custom properties\n- ❌ Theme changes require recompilation rather than runtime updates\n- ❌ Cannot leverage some modern CSS features that rely on custom properties\n\n**Alternatives Considered:**\n\n- Heavy use of CSS custom properties: External manipulation risk, less robust\n- Design Tokens W3C format: Same issues as CSS custom properties for base theme\n- No variables at all: Poor maintainability, code duplication\n- Component-specific CSS variables only: Still crosses Shadow DOM boundary\n\n## 9.2 Open Decisions\n\nThese decisions are under consideration and will be addressed in future planning cycles as the project evolves and new requirements emerge.\n\n### OD-001: Server-Side Rendering Strategy\n\n**Status:** Open\n\n**Context:**\nSSR support for Web Components is complex. Current hydrate adapter is limited. Full SSR solution needed for some use cases.\n\n**Options:**\n\n1. Improve existing hydrate adapter\n2. Declarative Shadow DOM approach\n3. Partner with SSR framework projects\n4. Document limitations and workarounds\n\n**Decision Timeline:** To be reviewed in upcoming quarterly planning sessions\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/10-quality-requirements",
+      "group": "docs/arc42",
+      "name": "10-quality-requirements",
+      "path": "docs/arc42/10-quality-requirements.md",
+      "code": "# 10. Quality Requirements\n\nThis section defines the concrete quality goals for Public UI - KoliBri through measurable scenarios and acceptance criteria. It translates the abstract quality objectives from Section 1 into specific, testable requirements that guide development and validation efforts.\n\n## 10.1 Quality Tree\n\n```mermaid\ngraph TB\n    Quality[Quality Requirements]\n    \n    Quality --> Accessibility\n    Quality --> Maintainability\n    Quality --> Performance\n    Quality --> Usability\n    Quality --> Compatibility\n    Quality --> Security\n    \n    Accessibility --> A1[WCAG 2.1 AA Compliance]\n    Accessibility --> A2[Screen Reader Support]\n    Accessibility --> A3[Keyboard Navigation]\n    \n    Maintainability --> M1[Code Quality]\n    Maintainability --> M2[Documentation]\n    Maintainability --> M3[Test Coverage]\n    \n    Performance --> P1[Bundle Size]\n    Performance --> P2[Rendering Speed]\n    Performance --> P3[Memory Usage]\n    \n    Usability --> U1[Developer Experience]\n    Usability --> U2[Clear Documentation]\n    Usability --> U3[Error Messages]\n    \n    Compatibility --> C1[Framework Support]\n    Compatibility --> C2[Browser Support]\n    Compatibility --> C3[Version Stability]\n    \n    Security --> S1[No Vulnerabilities]\n    Security --> S2[Secure Defaults]\n    Security --> S3[Build Provenance]\n```\n\n## 10.2 Quality Scenarios\n\n### Accessibility Scenarios\n\n#### Scenario A1: Screen Reader Navigation\n\n**Quality Goal:** Full accessibility for screen reader users\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User with screen reader navigates application |\n| **Environment** | Production web application, JAWS/NVDA/VoiceOver |\n| **Response** | All components announce correctly, keyboard navigation works |\n| **Measure** | 100% of interactive components accessible via screen reader |\n\n**Acceptance Criteria:**\n\n- Screen reader announces component role, name, and state\n- User can activate all interactive elements via keyboard\n- Focus order is logical and predictable\n- Dynamic changes announced via ARIA live regions\n\n#### Scenario A2: Keyboard Navigation\n\n**Quality Goal:** Complete keyboard access to all functionality\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User navigates application using only keyboard |\n| **Environment** | Any modern browser |\n| **Response** | All interactive elements accessible, focus visible |\n| **Measure** | 100% of features usable with keyboard alone |\n\n**Acceptance Criteria:**\n\n- Tab key moves focus through all interactive elements\n- Enter/Space activates buttons and controls\n- Arrow keys navigate within composite widgets (menus, tabs)\n- Escape closes modal dialogs and dropdowns\n- Focus indicators always visible (3px outline, 3:1 contrast)\n\n#### Scenario A3: Color Contrast\n\n**Quality Goal:** Sufficient contrast for readability\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User with low vision views components |\n| **Environment** | Any browser, default theme |\n| **Response** | All text and UI elements meet contrast requirements |\n| **Measure** | 100% of elements meet WCAG AA contrast ratios |\n\n**Acceptance Criteria:**\n\n- Normal text (< 18pt): Minimum 4.5:1 contrast\n- Large text (≥ 18pt): Minimum 3:1 contrast\n- UI components: Minimum 3:1 contrast\n- Focus indicators: Minimum 3:1 contrast\n- Automated wcag-contrast library validation\n\n### Performance Scenarios\n\n#### Scenario P1: Initial Load Time\n\n**Quality Goal:** Fast initial page load\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User opens application for first time |\n| **Environment** | 4G mobile connection, mid-range device |\n| **Response** | Page loads and becomes interactive quickly |\n| **Measure** | Time to Interactive < 3.8 seconds |\n\n**Acceptance Criteria:**\n\n- First Contentful Paint < 1.8s\n- Time to Interactive < 3.8s\n- Total Blocking Time < 300ms\n\n#### Scenario P2: Component Load\n\n**Quality Goal:** Lazy loading efficiency\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User encounters new component type |\n| **Environment** | Application already loaded |\n| **Response** | Component loads without noticeable delay |\n| **Measure** | Component appears within 200ms |\n\n**Acceptance Criteria:**\n\n- Individual component bundles < 50KB\n- Component loads in < 200ms on 4G\n- No layout shift when component appears\n- Lazy loading works correctly\n\n#### Scenario P3: Theme Switching\n\n**Quality Goal:** Instant theme changes\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User switches theme (dark mode, high contrast) |\n| **Environment** | Application with multiple components rendered |\n| **Response** | Theme changes instantly across all components |\n| **Measure** | Visual change within 16ms (one frame) |\n\n**Acceptance Criteria:**\n\n- Theme switch completes in < 16ms\n- No re-rendering of components required\n- No layout shifts during theme change\n- Memory usage remains stable\n\n### Maintainability Scenarios\n\n#### Scenario M1: Add New Component\n\n**Quality Goal:** Easy addition of new components\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Developer adds new component to library |\n| **Environment** | Development environment, fresh checkout |\n| **Response** | Component works with all themes and frameworks |\n| **Measure** | New component integrated in < 8 hours |\n\n**Acceptance Criteria:**\n\n- Component scaffolding available\n- Clear documentation for component creation\n- Automated tests pass\n- Framework adapters generated automatically\n- Visual regression tests created\n\n#### Scenario M2: Fix Bug\n\n**Quality Goal:** Quick and safe bug fixes\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Bug reported in production component |\n| **Environment** | Component with existing tests |\n| **Response** | Bug fixed without breaking other features |\n| **Measure** | Fix and verification in < 4 hours |\n\n**Acceptance Criteria:**\n\n- Bug reproducible via test\n- Fix doesn't break existing tests\n- Regression test added\n- All automated checks pass\n- PR reviewed and merged\n\n#### Scenario M3: Upgrade Major Version\n\n**Quality Goal:** Smooth version upgrades\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Application needs to upgrade from v3 to v4 |\n| **Environment** | Large application using many components |\n| **Response** | Upgrade completed with minimal manual changes |\n| **Measure** | 90% of changes automated via migration tool |\n\n**Acceptance Criteria:**\n\n- Migration guide available\n- CLI tool automates code changes\n- Breaking changes documented\n- Deprecated features still work with warnings\n- Parallel version support for transition\n\n### Usability Scenarios\n\n#### Scenario U1: First Component Integration\n\n**Quality Goal:** Easy for new developers\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | New developer integrates first component |\n| **Environment** | React/Angular/Vue application |\n| **Response** | Component works without issues |\n| **Measure** | Working integration in < 15 minutes |\n\n**Acceptance Criteria:**\n\n- Quick start guide available\n- Installation with single command\n- Example code works copy-paste\n- TypeScript types work in IDE\n- Clear error messages if misconfigured\n\n#### Scenario U2: Debug Component Issue\n\n**Quality Goal:** Easy debugging\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Component doesn't render as expected |\n| **Environment** | Browser dev tools |\n| **Response** | Developer identifies and fixes issue |\n| **Measure** | Issue identified in < 10 minutes |\n\n**Acceptance Criteria:**\n\n- Shadow DOM inspectable in dev tools\n- Clear console warnings for invalid props\n- Helpful error messages\n- Documentation explains common issues\n- Component state visible in dev tools\n\n#### Scenario U3: Create Custom Theme\n\n**Quality Goal:** Easy theme customization\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Designer wants to apply brand colors |\n| **Environment** | SASS/CSS knowledge, design system |\n| **Response** | Custom theme created and applied |\n| **Measure** | Basic theme in < 2 hours |\n\n**Acceptance Criteria:**\n\n- Theme template available\n- Documentation explains theming system\n- SASS variables documented\n- Example themes as reference\n- Visual regression tests provided\n\n### Compatibility Scenarios\n\n#### Scenario C1: Framework Integration\n\n**Quality Goal:** Work with any major framework\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Developer uses component in React/Angular/Vue |\n| **Environment** | Latest framework version |\n| **Response** | Component works naturally in framework |\n| **Measure** | 100% of features work in all supported frameworks |\n\n**Acceptance Criteria:**\n\n- Framework adapter available\n- Framework-specific patterns supported\n- TypeScript types work\n- Events integrate with framework event system\n- Props follow framework conventions\n\n#### Scenario C2: Browser Support\n\n**Quality Goal:** Work in all modern browsers\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | User opens application in browser |\n| **Environment** | Chrome, Firefox, Safari, Edge (latest 2 versions) |\n| **Response** | Components render and function correctly |\n| **Measure** | 100% feature parity across browsers |\n\n**Acceptance Criteria:**\n\n- Visual appearance consistent\n- All features functional\n- Performance acceptable\n- No console errors\n- Automated cross-browser testing\n\n#### Scenario C3: Version Compatibility\n\n**Quality Goal:** Smooth upgrades between versions\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Application uses older component version |\n| **Environment** | Production application |\n| **Response** | Can upgrade without breaking changes (within major) |\n| **Measure** | Zero breaking changes in minor/patch versions |\n\n**Acceptance Criteria:**\n\n- SemVer strictly followed\n- Deprecation warnings before removal\n- LTS version gets security fixes\n- Clear upgrade path documented\n- Migration tool available for major versions\n\n### Security Scenarios\n\n#### Scenario S1: No XSS Vulnerabilities\n\n**Quality Goal:** Prevent cross-site scripting\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Application passes user input to component |\n| **Environment** | Component with text content |\n| **Response** | Malicious scripts do not execute |\n| **Measure** | Zero XSS vulnerabilities |\n\n**Acceptance Criteria:**\n\n- All user input sanitized\n- Shadow DOM provides isolation\n- No innerHTML with user content\n- CSP compatible\n- Automated security scanning passes\n\n#### Scenario S2: Dependency Vulnerabilities\n\n**Quality Goal:** No vulnerable dependencies\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Security vulnerability disclosed in dependency |\n| **Environment** | Production application |\n| **Response** | Vulnerability patched quickly |\n| **Measure** | Critical vulnerabilities fixed within 24 hours |\n\n**Acceptance Criteria:**\n\n- Automated vulnerability scanning\n- Dependabot alerts enabled\n- Regular dependency updates\n- Security patches prioritized\n- Users notified of security updates\n\n#### Scenario S3: Build Security\n\n**Quality Goal:** Verifiable build provenance\n\n| Aspect | Details |\n|--------|---------|\n| **Stimulus** | Organization audits dependencies |\n| **Environment** | Published npm packages |\n| **Response** | Build provenance verifiable |\n| **Measure** | SLSA Build Level 3 compliance |\n\n**Acceptance Criteria:**\n\n- Builds in GitHub Actions with OIDC\n- Published with npm provenance\n- Signed attestations available\n- Reproducible builds\n- Supply chain security validated\n\n## 10.3 Quality Metrics\n\n| Quality Attribute | Metric | Target | Measurement Method |\n|-------------------|--------|--------|-------------------|\n| **Accessibility** | WCAG 2.1 AA Compliance | 100% | Manual testing + axe-core |\n| **Accessibility** | Keyboard Navigation | 100% | Manual testing |\n| **Performance** | Time to Interactive | < 3.8s | WebPageTest |\n| **Performance** | Bundle Size | < 50KB per component | Bundlephobia analysis |\n| **Maintainability** | Test Coverage | > 80% | Jest coverage report |\n| **Maintainability** | Code Duplication | < 5% | SonarQube/manual review |\n| **Security** | Vulnerabilities | 0 critical/high | Dependabot, CodeQL |\n| **Usability** | Time to First Component | < 15 min | User testing |\n| **Compatibility** | Browser Support | Latest 2 versions | Automated testing |\n| **Quality** | Linting Errors | 0 | ESLint, Stylelint |\n| **Quality** | Type Errors | 0 | TypeScript compiler |\n\n## 10.4 Quality Assurance Methods\n\n| Method | Purpose | Frequency | Responsible |\n|--------|---------|-----------|-------------|\n| **Automated Tests** | Catch regressions | Every commit | CI/CD |\n| **Code Review** | Ensure quality | Every PR | Team members |\n| **Accessibility Audit** | WCAG compliance | Every component | A11y specialists |\n| **Performance Testing** | Monitor performance | Weekly | Automated tests |\n| **Security Scanning** | Find vulnerabilities | Every commit | CodeQL, Dependabot |\n| **User Testing** | Validate usability | Before major releases | UX team |\n| **Visual Regression** | Detect visual changes | Every theme change | Visual tests |\n| **Manual Testing** | Exploratory testing | Before releases | QA team |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/11-risks-and-technical-debt",
+      "group": "docs/arc42",
+      "name": "11-risks-and-technical-debt",
+      "path": "docs/arc42/11-risks-and-technical-debt.md",
+      "code": "# 11. Risks and Technical Debt\n\nThis section identifies and assesses potential risks to the Public UI - KoliBri project, along with current technical debt items. Understanding these factors helps prioritize mitigation efforts and plan for sustainable long-term development.\n\n## 11.1 Identified Risks\n\n### Risk R1: Browser API Changes\n\n**Description:** Web Component APIs (Custom Elements, Shadow DOM) could change or be deprecated.\n\n**Probability:** Low  \n**Impact:** High  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- APIs are W3C standards (stable)\n- Monitor W3C specifications for changes\n- Polyfills available for older browsers\n- Active participation in Web Component community\n\n**Contingency:**\n\n- Implement adapter layer between components and browser APIs\n- Evaluate alternative technologies if needed\n- Community would likely provide migration paths\n\n### Risk R2: Stencil.js Maintenance\n\n**Description:** Stencil.js project could be abandoned or become incompatible with future Web Component standards.\n\n**Probability:** Low  \n**Impact:** High  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Stencil maintained by Ionic team (strong backing)\n- Large community and corporate users\n- Regular releases and active development\n- Stencil generates standard Web Components\n\n**Contingency:**\n\n- Fork and maintain Stencil if necessary\n- Migrate to alternative compiler (Lit, custom solution)\n- Generated components would still work\n\n### Risk R3: Framework Compatibility\n\n**Description:** Major frameworks could change in ways that break Web Component integration.\n\n**Probability:** Medium  \n**Impact:** Medium  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Web Components are framework-agnostic by design\n- Most frameworks improving Web Component support\n- Stencil output targets handle framework-specific quirks\n- Regular testing with latest framework versions\n\n**Contingency:**\n\n- Update framework adapters as needed\n- Work with framework maintainers on compatibility\n- Document framework-specific workarounds\n- Consider dropping support for problematic frameworks\n\n### Risk R4: Accessibility Standard Changes\n\n**Description:** WCAG or BITV standards could introduce new requirements.\n\n**Probability:** Medium  \n**Impact:** Medium  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Monitor WCAG working group\n- Architecture allows adding accessibility features\n- Regular accessibility audits\n- Community feedback on accessibility\n\n**Contingency:**\n\n- Update components to meet new standards\n- Provide migration guides for breaking changes\n- Deprecate non-compliant features gradually\n\n### Risk R5: Performance Regression\n\n**Description:** Component additions or changes could degrade performance.\n\n**Probability:** Medium  \n**Impact:** Medium  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Bundle size monitoring\n- Performance budgets\n- Regular performance profiling\n\n**Contingency:**\n\n- Performance review before major releases\n- Optimize critical components\n- Provide performance best practices documentation\n- Consider performance-focused component variants\n\n### Risk R6: Security Vulnerabilities\n\n**Description:** Components or dependencies could have security vulnerabilities.\n\n**Probability:** Medium  \n**Impact:** High  \n**Risk Level:** High\n\n**Mitigation:**\n\n- Automated dependency scanning (Dependabot)\n- CodeQL security analysis\n- Regular dependency updates\n- Security-focused code reviews\n- SLSA Build Level 3 provenance\n\n**Contingency:**\n\n- Emergency patch releases\n- Security advisory publication\n- Direct notification of affected users\n- Temporary workarounds documented\n\n### Risk R7: Breaking Changes in Major Versions\n\n**Description:** Major version upgrades could be difficult and discourage adoption.\n\n**Probability:** High  \n**Impact:** Medium  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Clear deprecation process\n- Migration guides for all breaking changes\n- Automated migration CLI tool\n- LTS versions for stability\n\n**Contingency:**\n\n- Extend LTS support if needed\n- Provide professional migration support\n- Create detailed migration documentation\n- Offer migration workshops\n\n### Risk R8: Theme Incompatibility\n\n**Description:** Theme updates could break with new component versions.\n\n**Probability:** Medium  \n**Impact:** Medium  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Semantic versioning for themes\n- Theme-component compatibility matrix\n- Visual regression tests\n- Theme template documentation\n\n**Contingency:**\n\n- Maintain multiple theme versions\n- Provide theme migration guides\n- Automated theme update tools\n- Community theme support\n\n### Risk R9: Community Adoption\n\n**Description:** Insufficient community adoption could lead to project stagnation.\n\n**Probability:** Low  \n**Impact:** High  \n**Risk Level:** Medium\n\n**Mitigation:**\n\n- Clear documentation and examples\n- Active communication and support\n- Regular releases with improvements\n- Showcase projects using KoliBri\n- Conference talks and blog posts\n\n**Contingency:**\n\n- Increase marketing efforts\n- Partner with organizations\n- Improve onboarding experience\n- Gather and act on user feedback\n\n### Risk R10: Build System Complexity\n\n**Description:** Monorepo build complexity could slow development.\n\n**Probability:** Medium  \n**Impact:** Low  \n**Risk Level:** Low\n\n**Mitigation:**\n\n- Nx caching and task orchestration\n- Clear build documentation\n- Automated setup scripts\n- Regular build optimization\n\n**Contingency:**\n\n- Simplify build process\n- Better build documentation\n- Training for contributors\n- Consider build system alternatives\n\n## 11.2 Technical Debt\n\n### TD1: Legacy Theme Support\n\n**Description:** Non-default themes (except ECL) are not actively maintained.\n\n**Impact:** Medium  \n**Effort to Resolve:** High  \n**Priority:** Low\n\n**Details:**\n\n- Multiple themes created early in project\n- Limited resources to maintain all themes\n- Some themes may not work with latest components\n\n**Resolution Plan:**\n\n- Document which themes are maintained\n- Deprecate unmaintained themes\n- Provide theme migration guides\n- Archive old themes as examples\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions\n\n### TD2: Test Coverage Gaps\n\n**Description:** Some components have incomplete test coverage.\n\n**Impact:** Medium  \n**Effort to Resolve:** High  \n**Priority:** Medium\n\n**Details:**\n\n- Some older components lack E2E tests\n- Edge cases not always covered\n- Visual regression tests incomplete\n\n**Resolution Plan:**\n\n- Audit all components for test coverage\n- Add tests for critical paths\n- Improve test documentation\n- Set minimum coverage requirements\n\n**Timeline:** Ongoing\n\n### TD3: Documentation Inconsistencies\n\n**Description:** Documentation quality varies between components.\n\n**Impact:** Low  \n**Effort to Resolve:** Medium  \n**Priority:** Medium\n\n**Details:**\n\n- Some components have minimal documentation\n- Examples not always up-to-date\n- API documentation incomplete in places\n\n**Resolution Plan:**\n\n- Documentation audit and standardization\n- Documentation templates\n- Automated documentation generation improvements\n- Community documentation contributions\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions\n\n### TD4: Deprecated Components\n\n**Description:** Deprecated components still in codebase.\n\n**Impact:** Low  \n**Effort to Resolve:** Medium  \n**Priority:** Low\n\n**Details:**\n\n- Components marked deprecated but not removed\n- Increases maintenance burden\n- Creates confusion for new users\n\n**Resolution Plan:**\n\n- Document deprecation timeline\n- Provide migration guides\n- Remove in next major version\n- Clear communication to users\n\n**Timeline:** Planned for next major version release\n\n### TD5: Build Time Optimization\n\n**Description:** Full monorepo build takes ~2 minutes.\n\n**Impact:** Low  \n**Effort to Resolve:** Medium  \n**Priority:** Low\n\n**Details:**\n\n- Sequential package builds\n- Some optimization opportunities exist\n- Not a major bottleneck yet\n\n**Resolution Plan:**\n\n- Profile build process\n- Optimize slow steps\n- Better use of Nx caching\n- Consider parallel builds where safe\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions\n\n### TD6: SSR Support\n\n**Description:** Server-side rendering support is limited.\n\n**Impact:** Medium  \n**Effort to Resolve:** High  \n**Priority:** Medium\n\n**Details:**\n\n- Hydrate adapter exists but limited\n- Declarative Shadow DOM support needed\n- SSR use cases growing\n\n**Resolution Plan:**\n\n- Evaluate Declarative Shadow DOM\n- Improve hydrate adapter\n- Document SSR limitations\n- Provide SSR examples\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions-Q3\n\n### TD7: Accessibility Test Automation\n\n**Description:** Some accessibility testing is manual.\n\n**Impact:** Medium  \n**Effort to Resolve:** High  \n**Priority:** High\n\n**Details:**\n\n- Screen reader testing mostly manual\n- Keyboard navigation testing manual\n- Time-consuming process\n\n**Resolution Plan:**\n\n- Expand axe-core integration\n- Add automated keyboard navigation tests\n- Consider automated screen reader testing tools\n- Improve accessibility test documentation\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions\n\n### TD8: Monorepo Structure\n\n**Description:** Some packages have inconsistent structure.\n\n**Impact:** Low  \n**Effort to Resolve:** Medium  \n**Priority:** Low\n\n**Details:**\n\n- Early packages structured differently\n- Inconsistent naming conventions\n- Script variations between packages\n\n**Resolution Plan:**\n\n- Standardize package structure\n- Update older packages\n- Create package template\n- Document standards\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions\n\n### TD9: Migration Tool Coverage\n\n**Description:** Migration CLI doesn't cover all breaking changes.\n\n**Impact:** Medium  \n**Effort to Resolve:** Medium  \n**Priority:** Medium\n\n**Details:**\n\n- Some migrations require manual work\n- Tool could be more comprehensive\n- Not all edge cases handled\n\n**Resolution Plan:**\n\n- Expand migration tool capabilities\n- Better documentation of manual steps\n- Community feedback on migration pain points\n- Automated testing of migrations\n\n**Timeline:** Ongoing with each major version\n\n### TD10: Performance Monitoring\n\n**Description:** No continuous performance monitoring in production.\n\n**Impact:** Low  \n**Effort to Resolve:** Medium  \n**Priority:** Low\n\n**Details:**\n\n- No real-world performance data\n- Can't detect performance regressions in production\n\n**Resolution Plan:**\n\n- Add performance monitoring to sample apps\n- Collect Web Vitals data\n- Create performance dashboard\n- Set up performance alerts\n\n**Timeline:** To be reviewed in upcoming quarterly planning sessions\n\n## 11.3 Risk Management Strategy\n\n### Risk Assessment Process\n\n1. **Identify**: Regular risk review in team meetings\n2. **Analyze**: Assess probability and impact\n3. **Prioritize**: Focus on high-risk items\n4. **Plan**: Create mitigation and contingency plans\n5. **Monitor**: Track risks and update as needed\n\n### Risk Review Cadence\n\n- **Weekly**: Monitor security alerts and CI failures\n- **Monthly**: Review risk register, assess new risks\n- **Quarterly**: Comprehensive risk analysis with team\n- **Annually**: External security audit and risk assessment\n\n### Technical Debt Management\n\n- **Quarterly Planning**: Allocate time for technical debt\n- **20% Rule**: ~20% of each sprint for technical debt\n- **Documentation**: Track all technical debt items\n- **Prioritization**: Balance features with debt reduction\n\n### Communication\n\n- **Transparency**: All risks documented publicly\n- **User Communication**: Security advisories, breaking changes\n- **Team Communication**: Risk register shared with all contributors\n- **Community Input**: Accept risk reports from community\n\n## 11.4 Assumptions and Dependencies\n\n### Assumptions\n\n| Assumption | Impact if Wrong | Verification |\n|-----------|----------------|--------------|\n| Web Components remain supported | Project foundation at risk | Monitor W3C standards |\n| Stencil continues development | Build system at risk | Monitor Stencil releases |\n| npm remains primary distribution | Distribution disruption | Package registry alternatives |\n| Modern browsers maintain compatibility | Breaking changes needed | Monitor browser releases |\n| Community continues to grow | Project sustainability | Track GitHub metrics |\n\n### Critical Dependencies\n\n| Dependency | Purpose | Risk Mitigation |\n|-----------|---------|-----------------|\n| **Stencil.js** | Component compilation | Active monitoring, fork plan |\n| **TypeScript** | Type system | Well-maintained by Microsoft |\n| **pnpm** | Package management | Could switch to npm if needed |\n| **GitHub Actions** | CI/CD | Alternative CI platforms available |\n| **npm Registry** | Distribution | Multiple registry options |\n| **@floating-ui/dom** | Positioning logic | Could implement alternative |\n| **adopted-style-sheets** | Theming polyfill | Could fork if needed |\n\n### External Standards\n\n| Standard | Impact | Monitoring |\n|----------|--------|-----------|\n| **WCAG** | Accessibility compliance | W3C WAI working group |\n| **BITV** | German accessibility law | Government updates |\n| **W3C Web Components** | Core technology | W3C WICG |\n| **ES Standards** | JavaScript features | TC39 proposals |\n| **CSS Standards** | Styling capabilities | W3C CSS WG |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/12-glossary",
+      "group": "docs/arc42",
+      "name": "12-glossary",
+      "path": "docs/arc42/12-glossary.md",
+      "code": "# 12. Glossary\n\nThis glossary provides definitions for key terms, concepts, and abbreviations used throughout the Public UI - KoliBri architecture documentation. It serves as a reference to ensure consistent understanding across all stakeholders.\n\n## A\n\n**Accessibility (A11y)**  \nThe practice of making web content usable by people with disabilities. Public UI - KoliBri focuses on meeting WCAG 2.2 Level AAA standards.\n\n**Adapter**  \nFramework-specific wrapper around KoliBri components. Auto-generated by Stencil output targets for React, Angular, Vue, etc.\n\n**Adopted Style Sheets**  \nWeb API that allows sharing style sheets across multiple shadow DOM instances. Used by KoliBri for efficient theming.\n\n**ARIA (Accessible Rich Internet Applications)**  \nSet of attributes that define ways to make web content more accessible to people with disabilities.\n\n**Atomic Component**  \nSmall, single-purpose component (button, input, icon) that can be composed into larger components. KoliBri focuses on atomic components.\n\n## B\n\n**BEM (Block Element Modifier)**  \nCSS naming convention used in KoliBri's styling. Example: `.kol-button__icon--small`\n\n**BITV (Barrierefreie-Informationstechnik-Verordnung)**  \nGerman accessibility regulation that KoliBri complies with. Based on WCAG standards.\n\n**Bundle Size**  \nTotal size of JavaScript and CSS files. KoliBri optimizes bundle size through lazy loading and code splitting.\n\n## C\n\n**Component**  \nReusable UI element with encapsulated structure, styling, and behavior. In KoliBri, refers to Web Components.\n\n**Component Library**  \nCollection of reusable components. KoliBri is a component library for accessible HTML.\n\n**CSP (Content Security Policy)**  \nSecurity standard that helps prevent XSS attacks. KoliBri components are CSP-compatible.\n\n**Custom Element**  \nWeb standard for defining new HTML elements. KoliBri components are custom elements (e.g., `<kol-button>`).\n\n**Custom Element Manifest**  \nJSON file describing custom elements' APIs. Generated by Stencil and used for documentation and IDE support.\n\n## D\n\n**Declarative Shadow DOM**  \nServer-side rendering technique for Web Components. KoliBri has limited support currently.\n\n**Design System**  \nSet of reusable components and design guidelines. KoliBri provides foundation for design systems.\n\n**Design Token**  \nNamed value (color, spacing, font) used in design systems. KoliBri themes use design tokens.\n\n**DX (Developer Experience)**  \nHow easy and pleasant it is to use a tool or library. KoliBri prioritizes good DX.\n\n## E\n\n**Encapsulation**  \nIsolation of component implementation from outside code. Achieved through Shadow DOM.\n\n**EUPL (European Union Public License)**  \nOpen source license used by KoliBri (version 1.2).\n\n**Event**  \nSignal emitted by component when something happens (click, change, etc.). KoliBri uses CustomEvent API.\n\n## F\n\n**Framework Adapter**  \nPackage that makes KoliBri components work naturally in specific frameworks (React, Angular, Vue).\n\n**Framework-Agnostic**  \nWorks with any or no framework. Core principle of KoliBri.\n\n## H\n\n**Hydration**  \nProcess of attaching event handlers to server-rendered HTML. Relevant for SSR scenarios.\n\n## I\n\n**ITZBund (Informationstechnikzentrum Bund)**  \nGerman federal IT service provider that created and open-sourced KoliBri.\n\n## J\n\n**JSX (JavaScript XML)**  \nSyntax extension for JavaScript used in Stencil component templates.\n\n## K\n\n**KoliBri**  \nComponent Library for Accessibility - the name of this project. Always spelled with this casing.\n\n## L\n\n**Lazy Loading**  \nLoading code only when needed. KoliBri components are lazy-loaded for optimal performance.\n\n**LTS (Long-Term Support)**  \nVersion supported for 3 years. Provides stability for enterprise users.\n\n**Loader**  \nJavaScript module that defines custom elements. KoliBri provides loader for lazy loading.\n\n## M\n\n**Monorepo**  \nSingle repository containing multiple packages. KoliBri uses pnpm workspace monorepo.\n\n**Multi-Theming**  \nAbility to apply different visual themes to same components. Core KoliBri feature.\n\n## N\n\n**npm (Node Package Manager)**  \nPackage registry where KoliBri packages are published.\n\n**Nx**  \nBuild system for monorepos. KoliBri uses Nx for build orchestration and caching.\n\n## O\n\n**Output Target**  \nStencil configuration for generating framework adapters. KoliBri uses output targets for React, Angular, Vue, etc.\n\n## P\n\n**pnpm (Performant npm)**  \nFast, disk-efficient package manager. KoliBri uses pnpm workspaces.\n\n**Polyfill**  \nCode that provides functionality not natively supported by browsers. May be needed for older browsers.\n\n**Props (Properties)**  \nConfiguration options passed to components. KoliBri uses underscore prefix (e.g., `_label`).\n\n**Provenance**  \nBuild attestation proving package authenticity. KoliBri publishes with SLSA Build Level 3 provenance.\n\n## R\n\n**React**  \nPopular JavaScript framework. KoliBri provides React adapter.\n\n**Responsive**  \nAdapts to different screen sizes. KoliBri components are responsive by default.\n\n**RTL (Right-to-Left)**  \nText direction for languages like Arabic and Hebrew. KoliBri supports RTL layouts.\n\n## S\n\n**SASS (Syntactically Awesome Style Sheets)**  \nCSS preprocessor used for KoliBri themes.\n\n**Screen Reader**  \nAssistive technology that reads web content aloud. KoliBri ensures screen reader compatibility.\n\n**Semantic HTML**  \nUsing HTML elements according to their meaning (button for buttons, not div). KoliBri enforces semantic HTML.\n\n**SemVer (Semantic Versioning)**  \nVersioning scheme (MAJOR.MINOR.PATCH). KoliBri strictly follows SemVer 2.0.\n\n**Shadow DOM**  \nWeb standard for encapsulating component DOM and styles. Core to KoliBri's architecture.\n\n**SLSA (Supply-chain Levels for Software Artifacts)**  \nSecurity framework for software supply chains. KoliBri aims for Build Level 3.\n\n**Slot**  \nWeb Components mechanism for content projection. Used for flexible component composition.\n\n**SSR (Server-Side Rendering)**  \nRendering components on server. KoliBri has limited SSR support via hydrate adapter.\n\n**Stencil**  \nWeb Component compiler used to build KoliBri. Developed by Ionic team.\n\n**STS (Short-Term Support)**  \nVersion supported for 15 months. Enables rapid innovation.\n\n## T\n\n**Theme**  \nPackage containing visual styles for components. KoliBri separates themes from component logic.\n\n**Tree Shaking**  \nRemoving unused code during bundling. KoliBri supports tree shaking for smaller bundles.\n\n**TypeScript**  \nTyped superset of JavaScript. All KoliBri code written in TypeScript.\n\n## V\n\n**Vue.js**  \nProgressive JavaScript framework. KoliBri provides Vue adapter.\n\n## W\n\n**W3C (World Wide Web Consortium)**  \nStandards organization for the web. KoliBri follows W3C standards.\n\n**WCAG (Web Content Accessibility Guidelines)**  \nInternational accessibility standards. Public UI - KoliBri implements WCAG 2.2 Level AAA.\n\n**Web Component**  \nSet of web standards for creating reusable custom elements. Foundation of KoliBri.\n\n**Web Standard**  \nOfficial specification from W3C. KoliBri built on web standards for longevity.\n\n## Abbreviations\n\n| Abbreviation | Full Term |\n|--------------|-----------|\n| A11y | Accessibility |\n| API | Application Programming Interface |\n| ARIA | Accessible Rich Internet Applications |\n| BEM | Block Element Modifier |\n| BITV | Barrierefreie-Informationstechnik-Verordnung |\n| CDN | Content Delivery Network |\n| CI/CD | Continuous Integration / Continuous Deployment |\n| CJS | CommonJS |\n| CLI | Command Line Interface |\n| CSP | Content Security Policy |\n| CSS | Cascading Style Sheets |\n| DOM | Document Object Model |\n| DX | Developer Experience |\n| E2E | End-to-End |\n| ES | ECMAScript |\n| ESM | ES Modules |\n| EUPL | European Union Public License |\n| HTML | HyperText Markup Language |\n| i18n | Internationalization |\n| IDE | Integrated Development Environment |\n| ITZBund | Informationstechnikzentrum Bund |\n| JSX | JavaScript XML |\n| LTS | Long-Term Support |\n| MCP | Model Context Protocol |\n| npm | Node Package Manager |\n| OIDC | OpenID Connect |\n| pnpm | Performant npm |\n| PR | Pull Request |\n| RTL | Right-to-Left |\n| SASS | Syntactically Awesome Style Sheets |\n| SemVer | Semantic Versioning |\n| SLSA | Supply-chain Levels for Software Artifacts |\n| SPA | Single Page Application |\n| SSR | Server-Side Rendering |\n| STS | Short-Term Support |\n| UI | User Interface |\n| UX | User Experience |\n| W3C | World Wide Web Consortium |\n| WCAG | Web Content Accessibility Guidelines |\n| XSS | Cross-Site Scripting |\n\n## Component Naming\n\nAll KoliBri components are prefixed with \"Kol\" to avoid naming conflicts:\n\n- `<kol-button>` - Button component\n- `<kol-input-text>` - Text input component\n- `<kol-table>` - Table component\n- `<kol-modal>` - Modal dialog component\n- etc.\n\n## Property Naming\n\nComponent properties are prefixed with underscore to avoid conflicts with native HTML attributes:\n\n- `_label` - Component label\n- `_disabled` - Disabled state\n- `_variant` - Visual variant\n- `_icons` - Icon configuration\n- etc.\n\n## File Extensions\n\n| Extension | Purpose |\n|-----------|---------|\n| `.tsx` | TypeScript with JSX (component files) |\n| `.ts` | TypeScript (utilities, types) |\n| `.scss` | SASS stylesheet |\n| `.css` | CSS stylesheet |\n| `.spec.ts` | Unit test file |\n| `.e2e.ts` | E2E test file |\n| `.md` | Markdown documentation |\n\n## Package Scopes\n\n| Scope | Purpose |\n|-------|---------|\n| `@public-ui/components` | Core component library |\n| `@public-ui/theme-*` | Theme packages |\n| `@public-ui/react` | React adapter |\n| `@public-ui/angular-*` | Angular adapters |\n| `@public-ui/vue` | Vue adapter |\n| `@public-ui/solid` | Solid adapter |\n| `@public-ui/svelte` | Svelte adapter |\n| `@public-ui/kolibri-cli` | Migration CLI tool |\n",
+      "kind": "doc"
+    },
+    {
+      "id": "doc/arc42/README",
+      "group": "docs/arc42",
+      "name": "README",
+      "path": "docs/arc42/README.md",
+      "code": "# Public UI - KoliBri Architecture Documentation (arc42)\n\nThis directory contains the comprehensive architecture documentation for Public UI - KoliBri (KoliBri), an accessible web component library. The documentation follows the proven arc42 template structure, providing stakeholders, developers, and architects with clear insights into the system's design, decisions, and quality requirements.\n\n## Table of Contents\n\n1. [Introduction and Goals](01-introduction-and-goals.md)\n2. [Architecture Constraints](02-architecture-constraints.md)\n3. [System Scope and Context](03-system-scope-and-context.md)\n4. [Solution Strategy](04-solution-strategy.md)\n5. [Building Block View](05-building-block-view.md)\n6. [Runtime View](06-runtime-view.md)\n7. [Deployment View](07-deployment-view.md)\n8. [Cross-cutting Concepts](08-cross-cutting-concepts.md)\n9. [Architecture Decisions](09-architecture-decisions.md)\n10. [Quality Requirements](10-quality-requirements.md)\n11. [Risks and Technical Debt](11-risks-and-technical-debt.md)\n12. [Glossary](12-glossary.md)\n\n## About arc42\n\narc42 is a proven template for software architecture documentation and communication. It provides a clear structure for documenting software and system architectures.\n\nMore information: https://arc42.org\n",
+      "kind": "doc"
+    },
     {
       "id": "doc/BREAKING_CHANGES.v2",
       "group": "docs",
@@ -85,7 +293,7 @@
       "group": "docs",
       "name": "CVE_OVERVIEW",
       "path": "docs/CVE_OVERVIEW.md",
-      "code": "# CVE Overview\n\n> For more security information, see [SECURITY.md](./SECURITY.md)\n\n## 1. Production Dependencies\n\n### Summary\n\n| Severity |  v4 |  v3 |  v2 |  v1 |\n| -------- | --: | --: | --: | --: |\n| critical |   0 |   0 |   0 |   0 |\n| high     |   0 |   0 |   0 |   4 |\n| moderate |   0 |   0 |   0 |   0 |\n| low      |   0 |   0 |   0 |   0 |\n| info     |   0 |   0 |   0 |   0 |\n| unknown  |   0 |   0 |   0 |   0 |\n\n### Vulnerabilities\n\n| Package              | Severity | CVE                 | Affected Versions | Description                                                                       |\n| -------------------- | -------- | ------------------- | ----------------- | --------------------------------------------------------------------------------- |\n| lodash.pick          | high     | CVE-2020-8203       | v1                | Prototype Pollution in lodash                                                     |\n| minimatch            | high     | CVE-2026-27903      | v1                | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja  |\n| minimatch            | high     | CVE-2026-27904      | v1                | minimatch ReDoS: nested \\*() extglobs generate catastrophically backtracking regu |\n| serialize-javascript | high     | GHSA-5c6j-r48x-rmvq | v1                | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to  |\n\n## 2. All Dependencies\n\n### Summary\n\n| Severity |  v4 |  v3 |  v2 |  v1 |\n| -------- | --: | --: | --: | --: |\n| critical |   3 |   3 |   3 |   1 |\n| high     |  14 |  15 |  21 |  17 |\n| moderate |   3 |   2 |  11 |   1 |\n| low      |   2 |   2 |   7 |   0 |\n| info     |   0 |   0 |   0 |   0 |\n| unknown  |   0 |   0 |   0 |   0 |\n\n### Vulnerabilities\n\n| Package              | Severity | CVE                 | Affected Versions | Description                                                                       |\n| -------------------- | -------- | ------------------- | ----------------- | --------------------------------------------------------------------------------- |\n| basic-ftp            | critical | CVE-2026-27699      | v4, v3, v2        | Basic FTP has Path Traversal Vulnerability in its downloadToDir() method          |\n| fast-xml-parser      | critical | CVE-2026-25896      | v4, v3, v2        | fast-xml-parser has an entity encoding bypass via regex injection in DOCTYPE ent  |\n| locutus              | critical | CVE-2026-25521      | v4, v3, v2, v1    | locutus is vulnerable to Prototype Pollution                                      |\n| @angular/common      | high     | CVE-2025-66035      | v1                | Angular is Vulnerable to XSRF Token Leakage via Protocol-Relative URLs in Angula  |\n| @angular/compiler    | high     | CVE-2025-66412      | v1                | Angular Stored XSS Vulnerability via SVG Animation, SVG URL and MathML Attribute  |\n| @angular/compiler    | high     | CVE-2026-22610      | v1                | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes               |\n| @angular/core        | high     | CVE-2026-22610      | v1                | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes               |\n| @angular/core        | high     | CVE-2026-27970      | v1                | Angular i18n vulnerable to Cross-Site Scripting                                   |\n| axios                | high     | CVE-2026-25639      | v3, v2            | Axios is Vulnerable to Denial of Service via **proto** Key in mergeConfig         |\n| braces               | high     | CVE-2024-4068       | v4, v3, v2, v1    | Uncontrolled resource consumption in braces                                       |\n| fast-xml-parser      | high     | CVE-2026-25128      | v4, v3, v2        | fast-xml-parser has RangeError DoS Numeric Entities Bug                           |\n| fast-xml-parser      | high     | CVE-2026-26278      | v4, v3, v2        | fast-xml-parser affected by DoS through entity expansion in DOCTYPE (no expansio  |\n| lodash.pick          | high     | CVE-2020-8203       | v2, v1            | Prototype Pollution in lodash                                                     |\n| minimatch            | high     | CVE-2026-27903      | v4, v3, v2, v1    | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja  |\n| minimatch            | high     | CVE-2026-27904      | v4, v3, v2, v1    | minimatch ReDoS: nested \\*() extglobs generate catastrophically backtracking regu |\n| minimatch            | high     | CVE-2026-26996      | v4, v3, v2        | minimatch has a ReDoS via repeated wildcards with non-matching literal in patter  |\n| rollup               | high     | CVE-2026-27606      | v4, v3, v1        | Rollup 4 has Arbitrary File Write via Path Traversal                              |\n| semver               | high     | CVE-2022-25883      | v2                | semver vulnerable to Regular Expression Denial of Service                         |\n| serialize-javascript | high     | GHSA-5c6j-r48x-rmvq | v4, v3, v2, v1    | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to  |\n| tar                  | high     | CVE-2026-23950      | v1                | Race Condition in node-tar Path Reservations via Unicode Ligature Collisions on   |\n| tar                  | high     | CVE-2026-24842      | v1                | node-tar Vulnerable to Arbitrary File Creation/Overwrite via Hardlink Path Trave  |\n| tar                  | high     | CVE-2026-23745      | v1                | node-tar is Vulnerable to Arbitrary File Overwrite and Symlink Poisoning via Ins  |\n| tar                  | high     | CVE-2026-26960      | v4, v3, v2, v1    | Arbitrary File Read/Write via Hardlink Target Escape Through Symlink Chain in no  |\n| ajv                  | moderate | CVE-2025-69873      | v4, v3, v2        | ajv has ReDoS when using `$data` option                                           |\n| ejs                  | moderate | CVE-2024-33883      | v2                | ejs lacks certain pollution protection                                            |\n| esbuild              | moderate | GHSA-67mh-4wv8-2f99 | v2                | esbuild enables any website to send any requests to the development server and r  |\n| js-yaml              | moderate | CVE-2025-64718      | v2                | js-yaml has prototype pollution in merge (<<)                                     |\n| micromatch           | moderate | CVE-2024-4067       | v4, v3, v2, v1    | Regular Expression Denial of Service (ReDoS) in micromatch                        |\n| nanoid               | moderate | CVE-2024-55565      | v2                | Predictable results in nanoid generation when given non-integer values            |\n| qs                   | moderate | CVE-2025-15284      | v2                | qs's arrayLimit bypass in its bracket notation allows DoS via memory exhaustion   |\n| serialize-javascript | moderate | CVE-2024-11831      | v2                | Cross-site Scripting (XSS) in serialize-javascript                                |\n| webpack              | moderate | CVE-2024-43788      | v2                | Webpack's AutoPublicPathRuntimeModule has a DOM Clobbering Gadget that leads to   |\n| webpack-dev-server   | moderate | CVE-2025-30360      | v2                | webpack-dev-server users' source code may be stolen when they access a malicious  |\n| webpack-dev-server   | moderate | CVE-2025-30359      | v2                | webpack-dev-server users' source code may be stolen when they access a malicious  |\n| diff                 | low      | CVE-2026-24001      | v4, v3, v2        | jsdiff has a Denial of Service vulnerability in parsePatch and applyPatch         |\n| fast-xml-parser      | low      | CVE-2026-27942      | v4, v3, v2        | fast-xml-parser has stack overflow in XMLBuilder with preserveOrder               |\n| hono                 | low      | GHSA-gq3j-xvxp-8hrf | v2                | Hono added timing comparison hardening in basicAuth and bearerAuth                |\n| qs                   | low      | CVE-2026-2391       | v2                | qs's arrayLimit bypass in comma parsing allows denial of service                  |\n| webpack              | low      | CVE-2025-68458      | v2                | webpack buildHttp: allowedUris allow-list bypass via URL userinfo (@) leading to  |\n| webpack              | low      | CVE-2025-68157      | v2                | webpack buildHttp HttpUriPlugin allowedUris bypass via HTTP redirects → SSRF + c  |\n",
+      "code": "# CVE Overview\n\n> For more security information, see [SECURITY.md](./SECURITY.md)\n\n## 1. Production Dependencies\n\n### Summary\n\n| Severity |  v4 |  v3 |  v2 |  v1 |\n| -------- | --: | --: | --: | --: |\n| critical |   0 |   0 |   0 |   0 |\n| high     |   0 |   0 |   0 |   4 |\n| moderate |   0 |   0 |   0 |   0 |\n| low      |   0 |   0 |   0 |   0 |\n| info     |   0 |   0 |   0 |   0 |\n| unknown  |   0 |   0 |   0 |   0 |\n\n### Vulnerabilities\n\n| Package              | Severity | CVE                 | Affected Versions | Description                                                                       |\n| -------------------- | -------- | ------------------- | ----------------- | --------------------------------------------------------------------------------- |\n| lodash.pick          | high     | CVE-2020-8203       | v1                | Prototype Pollution in lodash                                                     |\n| minimatch            | high     | CVE-2026-27903      | v1                | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja  |\n| minimatch            | high     | CVE-2026-27904      | v1                | minimatch ReDoS: nested \\*() extglobs generate catastrophically backtracking regu |\n| serialize-javascript | high     | GHSA-5c6j-r48x-rmvq | v1                | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to  |\n\n## 2. All Dependencies\n\n### Summary\n\n| Severity |  v4 |  v3 |  v2 |  v1 |\n| -------- | --: | --: | --: | --: |\n| critical |   3 |   3 |   3 |   1 |\n| high     |  17 |  17 |  27 |  20 |\n| moderate |   1 |   2 |  13 |   1 |\n| low      |   3 |   3 |   8 |   0 |\n| info     |   0 |   0 |   0 |   0 |\n| unknown  |   0 |   0 |   0 |   0 |\n\n### Vulnerabilities\n\n| Package              | Severity | CVE                 | Affected Versions | Description                                                                       |\n| -------------------- | -------- | ------------------- | ----------------- | --------------------------------------------------------------------------------- |\n| basic-ftp            | critical | CVE-2026-27699      | v4, v3, v2        | Basic FTP has Path Traversal Vulnerability in its downloadToDir() method          |\n| fast-xml-parser      | critical | CVE-2026-25896      | v4, v3, v2        | fast-xml-parser has an entity encoding bypass via regex injection in DOCTYPE ent  |\n| locutus              | critical | CVE-2026-25521      | v4, v3, v2, v1    | locutus is vulnerable to Prototype Pollution                                      |\n| @angular/common      | high     | CVE-2025-66035      | v1                | Angular is Vulnerable to XSRF Token Leakage via Protocol-Relative URLs in Angula  |\n| @angular/compiler    | high     | CVE-2025-66412      | v1                | Angular Stored XSS Vulnerability via SVG Animation, SVG URL and MathML Attribute  |\n| @angular/compiler    | high     | CVE-2026-22610      | v1                | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes               |\n| @angular/core        | high     | CVE-2026-22610      | v1                | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes               |\n| @angular/core        | high     | CVE-2026-27970      | v1                | Angular i18n vulnerable to Cross-Site Scripting                                   |\n| @hono/node-server    | high     | CVE-2026-29087      | v2                | @hono/node-server has authorization bypass for protected static paths via encode  |\n| axios                | high     | CVE-2026-25639      | v3, v2            | Axios is Vulnerable to Denial of Service via **proto** Key in mergeConfig         |\n| braces               | high     | CVE-2024-4068       | v4, v3, v2, v1    | Uncontrolled resource consumption in braces                                       |\n| express-rate-limit   | high     | CVE-2026-30827      | v2                | express-rate-limit: IPv4-mapped IPv6 addresses bypass per-client rate limiting o  |\n| fast-xml-parser      | high     | CVE-2026-25128      | v4, v3, v2        | fast-xml-parser has RangeError DoS Numeric Entities Bug                           |\n| fast-xml-parser      | high     | CVE-2026-26278      | v4, v3, v2        | fast-xml-parser affected by DoS through entity expansion in DOCTYPE (no expansio  |\n| hono                 | high     | CVE-2026-29045      | v2                | Hono vulnerable to arbitrary file access via serveStatic vulnerability            |\n| immutable            | high     | CVE-2026-29063      | v2                | Immutable is vulnerable to Prototype Pollution                                    |\n| locutus              | high     | CVE-2026-29091      | v4, v3, v2, v1    | locutus call_user_func_array vulnerable to Remote Code Execution (RCE) due to Co  |\n| lodash.pick          | high     | CVE-2020-8203       | v2, v1            | Prototype Pollution in lodash                                                     |\n| minimatch            | high     | CVE-2026-27903      | v4, v3, v2, v1    | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja  |\n| minimatch            | high     | CVE-2026-27904      | v4, v3, v2, v1    | minimatch ReDoS: nested \\*() extglobs generate catastrophically backtracking regu |\n| minimatch            | high     | CVE-2026-26996      | v4, v3, v2        | minimatch has a ReDoS via repeated wildcards with non-matching literal in patter  |\n| rollup               | high     | CVE-2026-27606      | v1                | Rollup 4 has Arbitrary File Write via Path Traversal                              |\n| semver               | high     | CVE-2022-25883      | v2                | semver vulnerable to Regular Expression Denial of Service                         |\n| serialize-javascript | high     | GHSA-5c6j-r48x-rmvq | v4, v3, v2, v1    | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to  |\n| svgo                 | high     | CVE-2026-29074      | v4, v3, v2, v1    | SVGO DoS through entity expansion in DOCTYPE (Billion Laughs)                     |\n| tar                  | high     | CVE-2026-23950      | v1                | Race Condition in node-tar Path Reservations via Unicode Ligature Collisions on   |\n| tar                  | high     | CVE-2026-24842      | v1                | node-tar Vulnerable to Arbitrary File Creation/Overwrite via Hardlink Path Trave  |\n| tar                  | high     | CVE-2026-23745      | v1                | node-tar is Vulnerable to Arbitrary File Overwrite and Symlink Poisoning via Ins  |\n| tar                  | high     | CVE-2026-26960      | v4, v3, v1        | Arbitrary File Read/Write via Hardlink Target Escape Through Symlink Chain in no  |\n| tar                  | high     | CVE-2026-29786      | v4, v3, v2, v1    | tar has Hardlink Path Traversal via Drive-Relative Linkpath                       |\n| ajv                  | moderate | CVE-2025-69873      | v3, v2            | ajv has ReDoS when using `$data` option                                           |\n| ejs                  | moderate | CVE-2024-33883      | v2                | ejs lacks certain pollution protection                                            |\n| esbuild              | moderate | GHSA-67mh-4wv8-2f99 | v2                | esbuild enables any website to send any requests to the development server and r  |\n| hono                 | moderate | CVE-2026-29086      | v2                | Hono Vulnerable to Cookie Attribute Injection via Unsanitized domain and path in  |\n| hono                 | moderate | CVE-2026-29085      | v2                | Hono Vulnerable to SSE Control Field Injection via CR/LF in writeSSE()            |\n| js-yaml              | moderate | CVE-2025-64718      | v2                | js-yaml has prototype pollution in merge (<<)                                     |\n| micromatch           | moderate | CVE-2024-4067       | v4, v3, v2, v1    | Regular Expression Denial of Service (ReDoS) in micromatch                        |\n| nanoid               | moderate | CVE-2024-55565      | v2                | Predictable results in nanoid generation when given non-integer values            |\n| qs                   | moderate | CVE-2025-15284      | v2                | qs's arrayLimit bypass in its bracket notation allows DoS via memory exhaustion   |\n| serialize-javascript | moderate | CVE-2024-11831      | v2                | Cross-site Scripting (XSS) in serialize-javascript                                |\n| webpack              | moderate | CVE-2024-43788      | v2                | Webpack's AutoPublicPathRuntimeModule has a DOM Clobbering Gadget that leads to   |\n| webpack-dev-server   | moderate | CVE-2025-30360      | v2                | webpack-dev-server users' source code may be stolen when they access a malicious  |\n| webpack-dev-server   | moderate | CVE-2025-30359      | v2                | webpack-dev-server users' source code may be stolen when they access a malicious  |\n| @tootallnate/once    | low      | CVE-2026-3449       | v4, v3, v2        | @tootallnate/once vulnerable to Incorrect Control Flow Scoping                    |\n| diff                 | low      | CVE-2026-24001      | v4, v3, v2        | jsdiff has a Denial of Service vulnerability in parsePatch and applyPatch         |\n| fast-xml-parser      | low      | CVE-2026-27942      | v4, v3, v2        | fast-xml-parser has stack overflow in XMLBuilder with preserveOrder               |\n| hono                 | low      | GHSA-gq3j-xvxp-8hrf | v2                | Hono added timing comparison hardening in basicAuth and bearerAuth                |\n| qs                   | low      | CVE-2026-2391       | v2                | qs's arrayLimit bypass in comma parsing allows denial of service                  |\n| webpack              | low      | CVE-2025-68458      | v2                | webpack buildHttp: allowedUris allow-list bypass via URL userinfo (@) leading to  |\n| webpack              | low      | CVE-2025-68157      | v2                | webpack buildHttp HttpUriPlugin allowedUris bypass via HTTP redirects → SSRF + c  |\n",
       "kind": "doc"
     },
     {
@@ -1272,6 +1480,14 @@
       "code": "import type { KoliBriTableCell, KoliBriTableSelection, KoliBriTableSelectionKeys } from '@public-ui/components';\nimport { createReactRenderElement, KolButton, KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useEffect, useRef, useState } from 'react';\nimport { useToasterService } from '../../hooks/useToasterService';\nimport { getRoot } from '../../shares/react-roots';\nimport { SampleDescription } from '../SampleDescription';\n\ntype SelectionValue = string | number;\ntype KolTableStatelessElement = {\n\taddEventListener: (type: string, listener: (event: CustomEvent<SelectionValue[]>) => void) => void;\n\tremoveEventListener: (type: string, listener: (event: CustomEvent<SelectionValue[]>) => void) => void;\n};\n\nconst DATA = [\n\t{ id: '1001', name: 'Foo Bar', internalIdentifier: `AAA1001` },\n\t{ id: '1002', name: 'Foo Baz', internalIdentifier: `AAA1002` },\n\t{ id: '1003', name: 'Foo Disabled', internalIdentifier: `AAA1003` },\n];\ntype Data = (typeof DATA)[0];\n\nfunction KolButtonWrapper({ label }: { label: string }) {\n\tconst { dummyClickEventHandler } = useToasterService();\n\n\tconst dummyEventHandler = {\n\t\tonClick: dummyClickEventHandler,\n\t};\n\n\treturn <KolButton _label={label} _on={dummyEventHandler} />;\n}\n\nexport const TableStatelessWithSingleSelection: FC = () => {\n\tconst [selectedKeys, setSelectedKeys] = useState<KoliBriTableSelectionKeys>(['1002']);\n\n\tconst selection: KoliBriTableSelection = {\n\t\tlabel: (row) => `Selection for ${(row as Data).name}`,\n\t\tmultiple: false,\n\t\tselectedKeys,\n\t\tdisabledKeys: ['AAA1003'],\n\t\tkeyPropertyName: 'internalIdentifier',\n\t};\n\n\tconst kolTableStatelessRef = useRef<HTMLKolTableStatelessElement>(null);\n\n\tconst handleSelectionChangeEvent = ({ detail: selection }: CustomEvent<SelectionValue[]>) => {\n\t\tconsole.log('Selection change via event', selection);\n\t};\n\tconst handleSelectionChangeCallback = (_event: Event, selection: SelectionValue[]) => {\n\t\tconsole.log('Selection change via callback', selection);\n\t\tsetSelectedKeys(selection);\n\t};\n\n\tuseEffect(() => {\n\t\tconst tableElement = kolTableStatelessRef.current as unknown as KolTableStatelessElement | null;\n\t\tconst selectionChangeEvent = 'kolSelectionChange';\n\t\ttableElement?.addEventListener(selectionChangeEvent, handleSelectionChangeEvent);\n\n\t\treturn () => {\n\t\t\ttableElement?.removeEventListener(selectionChangeEvent, handleSelectionChangeEvent);\n\t\t};\n\t}, [kolTableStatelessRef]);\n\n\tconst renderButton = (element: HTMLElement, cell: KoliBriTableCell) => {\n\t\tconst data = (cell as { data?: Data }).data;\n\t\tconst id = data?.id;\n\t\tgetRoot(createReactRenderElement(element)).render(<KolButtonWrapper label={`Click ${id}`} />);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This sample shows KolTableStateless with checkboxes for selection enabled.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<section className=\"w-full\">\n\t\t\t\t<KolTableStateless\n\t\t\t\t\t_label=\"Table with selection checkboxes\"\n\t\t\t\t\t_headerCells={{\n\t\t\t\t\t\thorizontal: [\n\t\t\t\t\t\t\t[\n\t\t\t\t\t\t\t\t{ key: 'id', label: '#ID', textAlign: 'left' },\n\t\t\t\t\t\t\t\t{ key: 'name', label: 'Name', textAlign: 'left' },\n\t\t\t\t\t\t\t\t{ key: 'action', label: 'Action', textAlign: 'left', render: renderButton },\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t],\n\t\t\t\t\t}}\n\t\t\t\t\t_data={DATA}\n\t\t\t\t\t_selection={selection}\n\t\t\t\t\t_on={{ onSelectionChange: handleSelectionChangeCallback }}\n\t\t\t\t\tclassName=\"block\"\n\t\t\t\t\tstyle={{ maxWidth: '600px' }}\n\t\t\t\t\tref={kolTableStatelessRef}\n\t\t\t\t/>\n\t\t\t</section>\n\t\t</>\n\t);\n};\n",
       "kind": "sample"
     },
+    {
+      "id": "sample/table/sticky-cols",
+      "group": "table",
+      "name": "sticky-cols",
+      "path": "packages/samples/react/src/components/table/sticky-col.tsx",
+      "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport type { KoliBriTableHeaders, KoliBriTableSelection } from '@public-ui/components';\nimport { KolHeading, KolTableStateful } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\nimport { COMPLEX_DATA } from './test-complex-data';\n\ntype Data = (typeof COMPLEX_DATA)[0];\n\nconst selection: KoliBriTableSelection = {\n\tlabel: (row) => `Selection for ${(row as Data).common_name}`,\n\tmultiple: false,\n\tkeyPropertyName: 'internalIdentifier',\n};\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{ label: 'ID', key: 'id', textAlign: 'right', width: 60 },\n\t\t\t{ label: 'Common name', key: 'common_name', textAlign: 'left', width: 250 },\n\t\t\t{ label: 'Scientific name', key: 'scientific_name', textAlign: 'left', width: 400 },\n\t\t\t{ label: 'Conservation status', key: 'conservation_status', textAlign: 'left', width: 250 },\n\t\t\t{ label: 'Habitat', key: 'habitat', textAlign: 'left', width: 400 },\n\t\t\t{ label: 'Diet', key: 'diet', textAlign: 'left', width: 200 },\n\t\t\t{ label: 'Geographic range', key: 'geographic_range', textAlign: 'left', width: 300 },\n\t\t],\n\t],\n};\n\nexport const TableStickyCol: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows KolTableStateful with the first three and last columns sticky. It should be focusable and scrollable with the keyboard. The table\n\t\t\t\theadline should be sticky at the top of the table. The data lists animal species with conservation-focused details.\n\t\t\t</p>\n\t\t</SampleDescription>\n\n\t\t<KolHeading _level={2} _label=\"Sticky columns\" />\n\t\t<KolTableStateful\n\t\t\t_label=\"Animal species overview\"\n\t\t\t_data={COMPLEX_DATA}\n\t\t\t_headers={HEADERS_HORIZONTAL}\n\t\t\tclassName=\"block\"\n\t\t\t_selection={selection}\n\t\t\t_fixedCols={[2, 1]}\n\t\t/>\n\t</>\n);\n",
+      "kind": "sample"
+    },
     {
       "id": "sample/table/sticky-header",
       "group": "table",
@@ -1501,7 +1717,7 @@
       "group": "scenarios",
       "name": "performance-test",
       "path": "packages/samples/react/src/scenarios/performance-test.tsx",
-      "code": "import { KolButton, KolInputCheckbox, KolInputNumber, KolInputText, KolSkeleton } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\n\ntype ComponentType = 'text' | 'number' | 'checkbox' | 'skeleton';\n\nexport const PerformanceTest: FC = () => {\n\tconst [count, setCount] = useState<number>(100);\n\tconst [activeComponent, setActiveComponent] = useState<ComponentType | null>(null);\n\tconst [renderTime, setRenderTime] = useState<number | null>(null);\n\tconst [isRendering, setIsRendering] = useState<boolean>(false);\n\n\tconst handleEvents = {\n\t\tonInput: (_event: Event, value: unknown) => {\n\t\t\tsetCount(value as number);\n\t\t},\n\t};\n\n\tconst renderComponent = (type: ComponentType, idx: number) => {\n\t\tswitch (type) {\n\t\t\tcase 'text':\n\t\t\t\treturn <KolInputText key={idx} _label={`TextInput #${idx}`} />;\n\t\t\tcase 'number':\n\t\t\t\treturn <KolInputNumber key={idx} _label={`NumberInput #${idx}`} />;\n\t\t\tcase 'checkbox':\n\t\t\t\treturn <KolInputCheckbox key={idx} _label={`Checkbox #${idx}`} />;\n\t\t\tcase 'skeleton':\n\t\t\t\treturn <KolSkeleton key={idx} _count={3} _name={`skeleton-${idx}`} />;\n\t\t\tdefault:\n\t\t\t\treturn null;\n\t\t}\n\t};\n\n\tconst renderComponents = () => {\n\t\tif (!activeComponent) return null;\n\n\t\tconst components = [];\n\t\tfor (let i = 1; i <= count; i++) {\n\t\t\tcomponents.push(renderComponent(activeComponent, i));\n\t\t}\n\t\treturn components;\n\t};\n\n\tconst handleComponentRender = (type: ComponentType) => {\n\t\tsetIsRendering(true);\n\t\tsetRenderTime(null);\n\t\tconst startTime = performance.now();\n\n\t\tsetActiveComponent(type);\n\n\t\t// Verwende setTimeout um die Renderzeit nach dem nächsten Render-Zyklus zu messen\n\t\tsetTimeout(() => {\n\t\t\tconst endTime = performance.now();\n\t\t\tsetRenderTime(endTime - startTime);\n\t\t\tsetIsRendering(false);\n\t\t}, 0);\n\t};\n\n\tconst handleClear = () => {\n\t\tsetActiveComponent(null);\n\t\tsetRenderTime(null);\n\t\tsetIsRendering(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This example renders many KoliBri components to show the performance. Choose a component type and set the number of instances to render.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"w-full mb-6\">\n\t\t\t\t<div className=\"flex flex-wrap items-end gap-4 mb-4\">\n\t\t\t\t\t<KolInputNumber _label=\"Number of components\" _value={count} _min={1} _max={500} _on={handleEvents} />\n\t\t\t\t</div>\n\n\t\t\t\t<div className=\"flex flex-wrap gap-4 mb-6\">\n\t\t\t\t\t<KolButton _label=\"Render TextInputs\" _variant=\"primary\" onClick={() => handleComponentRender('text')} />\n\t\t\t\t\t<KolButton _label=\"Render NumberInputs\" _variant=\"primary\" onClick={() => handleComponentRender('number')} />\n\t\t\t\t\t<KolButton _label=\"Render Checkboxes\" _variant=\"primary\" onClick={() => handleComponentRender('checkbox')} />\n\t\t\t\t\t<KolButton _label=\"Render Skeletons\" _variant=\"primary\" onClick={() => handleComponentRender('skeleton')} />\n\t\t\t\t\t<KolButton _label=\"Clear\" _variant=\"secondary\" onClick={handleClear} />\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{activeComponent && (\n\t\t\t\t<div className=\"w-full mb-4\">\n\t\t\t\t\t<p className=\"text-sm text-gray-600 mb-2\">\n\t\t\t\t\t\tRendering {count} {activeComponent} component{count !== 1 ? 's' : ''}\n\t\t\t\t\t</p>\n\t\t\t\t\t{isRendering && <p className=\"text-sm text-blue-600\">⏱️ Measuring render time...</p>}\n\t\t\t\t\t{renderTime !== null && !isRendering && <p className=\"text-sm text-green-600\">✅ Render time: {renderTime.toFixed(2)}ms</p>}\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t<div className=\"w-full grid gap-4\">{renderComponents()}</div>\n\t\t</>\n\t);\n};\n",
+      "code": "import { KolButton, KolInputCheckbox, KolInputNumber, KolInputText, KolSkeleton } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\n\ntype ComponentType = 'text' | 'number' | 'checkbox' | 'skeleton';\n\nexport const PerformanceTest: FC = () => {\n\tconst [count, setCount] = useState<number>(100);\n\tconst [activeComponent, setActiveComponent] = useState<ComponentType | null>(null);\n\tconst [renderTime, setRenderTime] = useState<number | null>(null);\n\tconst [isRendering, setIsRendering] = useState<boolean>(false);\n\n\tconst handleEvents = {\n\t\tonInput: (_event: Event, value: unknown) => {\n\t\t\tsetCount(value as number);\n\t\t},\n\t};\n\n\tconst renderComponent = (type: ComponentType, idx: number) => {\n\t\tswitch (type) {\n\t\t\tcase 'text':\n\t\t\t\treturn <KolInputText key={idx} _label={`TextInput #${idx}`} />;\n\t\t\tcase 'number':\n\t\t\t\treturn <KolInputNumber key={idx} _label={`NumberInput #${idx}`} />;\n\t\t\tcase 'checkbox':\n\t\t\t\treturn <KolInputCheckbox key={idx} _label={`Checkbox #${idx}`} />;\n\t\t\tcase 'skeleton':\n\t\t\t\treturn <KolSkeleton key={idx} _name={`skeleton-${idx}`} />;\n\t\t\tdefault:\n\t\t\t\treturn null;\n\t\t}\n\t};\n\n\tconst renderComponents = () => {\n\t\tif (!activeComponent) return null;\n\n\t\tconst components = [];\n\t\tfor (let i = 1; i <= count; i++) {\n\t\t\tcomponents.push(renderComponent(activeComponent, i));\n\t\t}\n\t\treturn components;\n\t};\n\n\tconst handleComponentRender = (type: ComponentType) => {\n\t\tsetIsRendering(true);\n\t\tsetRenderTime(null);\n\t\tconst startTime = performance.now();\n\n\t\tsetActiveComponent(type);\n\n\t\t// Verwende setTimeout um die Renderzeit nach dem nächsten Render-Zyklus zu messen\n\t\tsetTimeout(() => {\n\t\t\tconst endTime = performance.now();\n\t\t\tsetRenderTime(endTime - startTime);\n\t\t\tsetIsRendering(false);\n\t\t}, 0);\n\t};\n\n\tconst handleClear = () => {\n\t\tsetActiveComponent(null);\n\t\tsetRenderTime(null);\n\t\tsetIsRendering(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This example renders many KoliBri components to show the performance. Choose a component type and set the number of instances to render.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"w-full mb-6\">\n\t\t\t\t<div className=\"flex flex-wrap items-end gap-4 mb-4\">\n\t\t\t\t\t<KolInputNumber _label=\"Number of components\" _value={count} _min={1} _max={500} _on={handleEvents} />\n\t\t\t\t</div>\n\n\t\t\t\t<div className=\"flex flex-wrap gap-4 mb-6\">\n\t\t\t\t\t<KolButton _label=\"Render TextInputs\" _variant=\"primary\" onClick={() => handleComponentRender('text')} />\n\t\t\t\t\t<KolButton _label=\"Render NumberInputs\" _variant=\"primary\" onClick={() => handleComponentRender('number')} />\n\t\t\t\t\t<KolButton _label=\"Render Checkboxes\" _variant=\"primary\" onClick={() => handleComponentRender('checkbox')} />\n\t\t\t\t\t<KolButton _label=\"Render Skeletons\" _variant=\"primary\" onClick={() => handleComponentRender('skeleton')} />\n\t\t\t\t\t<KolButton _label=\"Clear\" _variant=\"secondary\" onClick={handleClear} />\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{activeComponent && (\n\t\t\t\t<div className=\"w-full mb-4\">\n\t\t\t\t\t<p className=\"text-sm text-gray-600 mb-2\">\n\t\t\t\t\t\tRendering {count} {activeComponent} component{count !== 1 ? 's' : ''}\n\t\t\t\t\t</p>\n\t\t\t\t\t{isRendering && <p className=\"text-sm text-blue-600\">⏱️ Measuring render time...</p>}\n\t\t\t\t\t{renderTime !== null && !isRendering && <p className=\"text-sm text-green-600\">✅ Render time: {renderTime.toFixed(2)}ms</p>}\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t<div className=\"w-full grid gap-4\">{renderComponents()}</div>\n\t\t</>\n\t);\n};\n",
       "kind": "scenario"
     },
     {
@@ -1541,7 +1757,7 @@
       "group": "scenarios",
       "name": "skeleton",
       "path": "packages/samples/react/src/scenarios/skeleton.tsx",
-      "code": "import type { FC } from 'react';\nimport React, { useCallback, useRef, useState } from 'react';\n\nimport { KolButton, KolInputRange, KolSkeleton } from '@public-ui/react-v19';\nimport { SampleDescription } from '../components/SampleDescription';\n\ninterface EventLogEntry {\n\ttimestamp: string;\n\tcount: number;\n\tid: number;\n}\n\nexport const Skeleton: FC = () => {\n\tconst skeletonRef = useRef<HTMLKolSkeletonElement>(null);\n\tconst rangeRef = useRef<HTMLKolInputRangeElement>(null);\n\tconst initialCount = 3;\n\n\tconst durationFormatter = new Intl.NumberFormat('de-DE', { style: 'unit', unit: 'millisecond', maximumFractionDigits: 1 });\n\tconst timeFormatter = new Intl.DateTimeFormat('de-DE', { hour: '2-digit', minute: '2-digit', second: '2-digit' });\n\n\tconst [count, setCount] = useState<number>(initialCount);\n\tconst [eventLog, setEventLog] = useState<EventLogEntry[]>([]);\n\tconst [lastEventTime, setLastEventTime] = useState<string>('');\n\tconst [eventCount, setEventCount] = useState<number>(0);\n\tconst [skeletonCount, setSkeletonCount] = useState<number>(20);\n\n\t// Render benchmark state\n\tconst [generation, setGeneration] = useState<number>(0);\n\tconst [renderDuration, setRenderDuration] = useState<number | null>(null);\n\tconst [isMeasuring, setIsMeasuring] = useState<boolean>(false);\n\n\t// Refs for stable values in closures (no stale closure issues)\n\tconst renderStartTimeRef = useRef<number>(0);\n\tconst expectedCountRef = useRef<number>(20);\n\tconst renderedCountRef = useRef<number>(0);\n\n\tconst handleLoaded = (event: CustomEvent<number>) => {\n\t\tconst now = new Date();\n\t\tconst timestamp = timeFormatter.format(now);\n\t\tconst newEventCount = eventCount + 1;\n\n\t\tsetCount(event.detail);\n\t\tsetLastEventTime(timestamp);\n\t\tsetEventCount(newEventCount);\n\n\t\t// Add to event log (keep only last 5 entries)\n\t\tsetEventLog((prev) => {\n\t\t\tconst newEntry: EventLogEntry = {\n\t\t\t\ttimestamp,\n\t\t\t\tcount: event.detail,\n\t\t\t\tid: newEventCount,\n\t\t\t};\n\t\t\treturn [newEntry, ...prev.slice(0, 4)];\n\t\t});\n\t};\n\n\tconst handleRendered = useCallback(() => {\n\t\trenderedCountRef.current += 1;\n\n\t\tif (renderedCountRef.current >= expectedCountRef.current) {\n\t\t\tconst duration = performance.now() - renderStartTimeRef.current;\n\t\t\tsetRenderDuration(duration);\n\t\t\tsetIsMeasuring(false);\n\t\t}\n\t}, []);\n\n\tconst handleRangeChange = (_event: Event, value: unknown) => {\n\t\tconst newValue = Number(value);\n\t\tsetSkeletonCount(newValue);\n\n\t\t// Start benchmark measurement\n\t\trenderedCountRef.current = 0;\n\t\texpectedCountRef.current = newValue;\n\t\trenderStartTimeRef.current = performance.now();\n\t\tsetRenderDuration(null);\n\t\tsetIsMeasuring(true);\n\t\tsetGeneration((prev) => prev + 1);\n\t};\n\n\tconst handleRangeBlur = () => {\n\t\t// Sicherstellen, dass der interne Wert mit dem State synchronisiert ist\n\t\tif (rangeRef.current) {\n\t\t\trangeRef.current._value = skeletonCount;\n\t\t}\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tKolSkeleton demonstriert Event-Emitter mit automatischem Intervall. Die Komponente emittiert alle 2 Sekunden ein &quot;loaded&quot; Event mit dem\n\t\t\t\t\taktuellen Count-Wert. Über die Buttons kann die Komponente getoggled und fokussiert werden. Der interne ClickButton erhöht bei Klick den Counter.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid md:grid-cols-2 gap-4 mb-4 items-center\">\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4\">\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Toggle Sichtbarkeit\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.toggle(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"primary\"\n\t\t\t\t\t/>\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Fokus auf Button\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.focus(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"secondary\"\n\t\t\t\t\t/>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4 items-center\">\n\t\t\t\t\t<KolInputRange\n\t\t\t\t\t\tref={rangeRef}\n\t\t\t\t\t\t_label=\"Anzahl der Skeletons\"\n\t\t\t\t\t\t_hideLabel\n\t\t\t\t\t\t_min={1}\n\t\t\t\t\t\t_max={10000}\n\t\t\t\t\t\t_step={25}\n\t\t\t\t\t\t_value={skeletonCount}\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonChange: handleRangeChange,\n\t\t\t\t\t\t\tonBlur: handleRangeBlur,\n\t\t\t\t\t\t}}\n\t\t\t\t\t/>\n\t\t\t\t\t<span className=\"text-sm text-gray-600 whitespace-nowrap\">{skeletonCount} Skeletons</span>\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/* Render Benchmark */}\n\t\t\t<div className=\"mb-4 px-3 py-2 border border-gray-300 rounded bg-gray-50 flex items-center gap-4 text-sm\">\n\t\t\t\t<span className=\"font-semibold\">Benchmark:</span>\n\t\t\t\t<span className={isMeasuring ? 'text-orange-600 font-bold' : renderDuration !== null ? 'text-green-600' : 'text-gray-400'}>\n\t\t\t\t\t{isMeasuring ? 'Rendering…' : renderDuration !== null ? 'Fertig' : 'Bereit'}\n\t\t\t\t</span>\n\t\t\t\t<span className=\"font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t{renderDuration !== null ? durationFormatter.format(renderDuration) : '—'}\n\t\t\t\t</span>\n\t\t\t</div>\n\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t{Array.from({ length: skeletonCount }, (_, idx) => (\n\t\t\t\t\t<KolSkeleton\n\t\t\t\t\t\tkey={`skeleton-${generation}-${idx}`}\n\t\t\t\t\t\t_count={initialCount}\n\t\t\t\t\t\t_name={`Example ${idx}`}\n\t\t\t\t\t\tonLoaded={idx === 0 ? handleLoaded : undefined}\n\t\t\t\t\t\tonRendered={handleRendered}\n\t\t\t\t\t\tref={idx === 0 ? skeletonRef : undefined}\n\t\t\t\t\t/>\n\t\t\t\t))}\n\t\t\t</div>\n\n\t\t\t<div className=\"mt-6 p-4 border border-gray-300 rounded-lg bg-gray-50\">\n\t\t\t\t<h3 className=\"text-lg font-semibold mb-3\">Event Monitor</h3>\n\t\t\t\t<div className=\"grid grid-cols-1 md:grid-cols-2 gap-4\">\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Aktueller Count-Wert:</p>\n\t\t\t\t\t\t<p className=\"text-2xl font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{count}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Letztes Event:</p>\n\t\t\t\t\t\t<p className=\"text-lg\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{lastEventTime || 'Noch kein Event empfangen'}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4\">\n\t\t\t\t\t<p className=\"font-medium mb-2\">\n\t\t\t\t\t\tEvents empfangen: <span className=\"font-bold\">{eventCount}</span>\n\t\t\t\t\t</p>\n\t\t\t\t\t{eventLog.length > 0 && (\n\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t<p className=\"font-medium mb-2\">Event-Historie (letzte 5):</p>\n\t\t\t\t\t\t\t<ul className=\"text-sm space-y-1 max-h-32 overflow-y-auto\">\n\t\t\t\t\t\t\t\t{eventLog.map((entry) => (\n\t\t\t\t\t\t\t\t\t<li key={entry.id} className=\"flex justify-between items-center p-2 bg-white rounded border\">\n\t\t\t\t\t\t\t\t\t\t<span>\n\t\t\t\t\t\t\t\t\t\t\t#{entry.id}: Count = {entry.count}\n\t\t\t\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t\t\t\t\t<span className=\"text-gray-500\">{entry.timestamp}</span>\n\t\t\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t\t</ul>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4 p-3 bg-blue-50 rounded\">\n\t\t\t\t\t<p className=\"text-sm text-blue-800\">\n\t\t\t\t\t\t💡 <strong>Tipp:</strong> Die Komponente emittiert automatisch alle 2 Sekunden ein Event. Klicke auf den &quot;Click Button&quot; in der Komponente,\n\t\t\t\t\t\tum den Count-Wert zu erhöhen.\n\t\t\t\t\t</p>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
+      "code": "import type { FC } from 'react';\nimport React, { useCallback, useRef, useState } from 'react';\n\nimport { KolButton, KolInputRange, KolSkeleton } from '@public-ui/react-v19';\nimport { SampleDescription } from '../components/SampleDescription';\n\ninterface EventLogEntry {\n\ttimestamp: string;\n\tcount: number;\n\tid: number;\n}\n\nexport const Skeleton: FC = () => {\n\tconst skeletonRef = useRef<HTMLKolSkeletonElement>(null);\n\tconst rangeRef = useRef<HTMLKolInputRangeElement>(null);\n\tconst initialCount = 3;\n\n\tconst durationFormatter = new Intl.NumberFormat('de-DE', { style: 'unit', unit: 'millisecond', maximumFractionDigits: 1 });\n\tconst timeFormatter = new Intl.DateTimeFormat('de-DE', { hour: '2-digit', minute: '2-digit', second: '2-digit' });\n\n\tconst [count, setCount] = useState<number>(initialCount);\n\tconst [eventLog, setEventLog] = useState<EventLogEntry[]>([]);\n\tconst [lastEventTime, setLastEventTime] = useState<string>('');\n\tconst [eventCount, setEventCount] = useState<number>(0);\n\tconst [skeletonCount, setSkeletonCount] = useState<number>(20);\n\n\t// Render benchmark state\n\tconst [generation, setGeneration] = useState<number>(0);\n\tconst [renderDuration, setRenderDuration] = useState<number | null>(null);\n\tconst [isMeasuring, setIsMeasuring] = useState<boolean>(false);\n\n\t// Refs for stable values in closures (no stale closure issues)\n\tconst renderStartTimeRef = useRef<number>(0);\n\tconst expectedCountRef = useRef<number>(20);\n\tconst renderedCountRef = useRef<number>(0);\n\n\tconst handleLoaded = (event: CustomEvent<number>) => {\n\t\tconst now = new Date();\n\t\tconst timestamp = timeFormatter.format(now);\n\t\tconst newEventCount = eventCount + 1;\n\n\t\tsetCount(event.detail);\n\t\tsetLastEventTime(timestamp);\n\t\tsetEventCount(newEventCount);\n\n\t\t// Add to event log (keep only last 5 entries)\n\t\tsetEventLog((prev) => {\n\t\t\tconst newEntry: EventLogEntry = {\n\t\t\t\ttimestamp,\n\t\t\t\tcount: event.detail,\n\t\t\t\tid: newEventCount,\n\t\t\t};\n\t\t\treturn [newEntry, ...prev.slice(0, 4)];\n\t\t});\n\t};\n\n\tconst handleRendered = useCallback(() => {\n\t\trenderedCountRef.current += 1;\n\n\t\tif (renderedCountRef.current >= expectedCountRef.current) {\n\t\t\tconst duration = performance.now() - renderStartTimeRef.current;\n\t\t\tsetRenderDuration(duration);\n\t\t\tsetIsMeasuring(false);\n\t\t}\n\t}, []);\n\n\tconst handleRangeChange = (_event: Event, value: unknown) => {\n\t\tconst newValue = Number(value);\n\t\tsetSkeletonCount(newValue);\n\n\t\t// Start benchmark measurement\n\t\trenderedCountRef.current = 0;\n\t\texpectedCountRef.current = newValue;\n\t\trenderStartTimeRef.current = performance.now();\n\t\tsetRenderDuration(null);\n\t\tsetIsMeasuring(true);\n\t\tsetGeneration((prev) => prev + 1);\n\t};\n\n\tconst handleRangeBlur = () => {\n\t\t// Sicherstellen, dass der interne Wert mit dem State synchronisiert ist\n\t\tif (rangeRef.current) {\n\t\t\trangeRef.current._value = skeletonCount;\n\t\t}\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tKolSkeleton demonstriert Event-Emitter mit automatischem Intervall. Die Komponente emittiert alle 2 Sekunden ein &quot;loaded&quot; Event mit dem\n\t\t\t\t\taktuellen Count-Wert. Über die Buttons kann die Komponente getoggled und fokussiert werden. Der interne ClickButton erhöht bei Klick den Counter.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid md:grid-cols-2 gap-4 mb-4 items-center\">\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4\">\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Toggle Sichtbarkeit\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.toggle(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"primary\"\n\t\t\t\t\t/>\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Fokus auf Button\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.focus(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"secondary\"\n\t\t\t\t\t/>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4 items-center\">\n\t\t\t\t\t<KolInputRange\n\t\t\t\t\t\tref={rangeRef}\n\t\t\t\t\t\t_label=\"Anzahl der Skeletons\"\n\t\t\t\t\t\t_hideLabel\n\t\t\t\t\t\t_min={1}\n\t\t\t\t\t\t_max={10000}\n\t\t\t\t\t\t_step={25}\n\t\t\t\t\t\t_value={skeletonCount}\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonChange: handleRangeChange,\n\t\t\t\t\t\t\tonBlur: handleRangeBlur,\n\t\t\t\t\t\t}}\n\t\t\t\t\t/>\n\t\t\t\t\t<span className=\"text-sm text-gray-600 whitespace-nowrap\">{skeletonCount} Skeletons</span>\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/* Render Benchmark */}\n\t\t\t<div className=\"mb-4 px-3 py-2 border border-gray-300 rounded bg-gray-50 flex items-center gap-4 text-sm\">\n\t\t\t\t<span className=\"font-semibold\">Benchmark:</span>\n\t\t\t\t<span className={isMeasuring ? 'text-orange-600 font-bold' : renderDuration !== null ? 'text-green-600' : 'text-gray-400'}>\n\t\t\t\t\t{isMeasuring ? 'Rendering…' : renderDuration !== null ? 'Fertig' : 'Bereit'}\n\t\t\t\t</span>\n\t\t\t\t<span className=\"font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t{renderDuration !== null ? durationFormatter.format(renderDuration) : '—'}\n\t\t\t\t</span>\n\t\t\t</div>\n\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t{Array.from({ length: skeletonCount }, (_, idx) => (\n\t\t\t\t\t<KolSkeleton\n\t\t\t\t\t\tkey={`skeleton-${generation}-${idx}`}\n\t\t\t\t\t\t_name={`Example ${idx}`}\n\t\t\t\t\t\tonLoaded={idx === 0 ? handleLoaded : undefined}\n\t\t\t\t\t\tonRendered={handleRendered}\n\t\t\t\t\t\tref={idx === 0 ? skeletonRef : undefined}\n\t\t\t\t\t/>\n\t\t\t\t))}\n\t\t\t</div>\n\n\t\t\t<div className=\"mt-6 p-4 border border-gray-300 rounded-lg bg-gray-50\">\n\t\t\t\t<h3 className=\"text-lg font-semibold mb-3\">Event Monitor</h3>\n\t\t\t\t<div className=\"grid grid-cols-1 md:grid-cols-2 gap-4\">\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Aktueller Count-Wert:</p>\n\t\t\t\t\t\t<p className=\"text-2xl font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{count}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Letztes Event:</p>\n\t\t\t\t\t\t<p className=\"text-lg\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{lastEventTime || 'Noch kein Event empfangen'}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4\">\n\t\t\t\t\t<p className=\"font-medium mb-2\">\n\t\t\t\t\t\tEvents empfangen: <span className=\"font-bold\">{eventCount}</span>\n\t\t\t\t\t</p>\n\t\t\t\t\t{eventLog.length > 0 && (\n\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t<p className=\"font-medium mb-2\">Event-Historie (letzte 5):</p>\n\t\t\t\t\t\t\t<ul className=\"text-sm space-y-1 max-h-32 overflow-y-auto\">\n\t\t\t\t\t\t\t\t{eventLog.map((entry) => (\n\t\t\t\t\t\t\t\t\t<li key={entry.id} className=\"flex justify-between items-center p-2 bg-white rounded border\">\n\t\t\t\t\t\t\t\t\t\t<span>\n\t\t\t\t\t\t\t\t\t\t\t#{entry.id}: Count = {entry.count}\n\t\t\t\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t\t\t\t\t<span className=\"text-gray-500\">{entry.timestamp}</span>\n\t\t\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t\t</ul>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4 p-3 bg-blue-50 rounded\">\n\t\t\t\t\t<p className=\"text-sm text-blue-800\">\n\t\t\t\t\t\t💡 <strong>Tipp:</strong> Die Komponente emittiert automatisch alle 2 Sekunden ein Event. Klicke auf den &quot;Click Button&quot; in der Komponente,\n\t\t\t\t\t\tum den Count-Wert zu erhöhen.\n\t\t\t\t\t</p>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
       "kind": "scenario"
     },
     {
@@ -1909,7 +2125,7 @@
       "group": "spec",
       "name": "skeleton",
       "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/skeleton.md",
-      "code": "# kol-skeleton\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property             | Attribute | Description                               | Type                            | Default     |\n| -------------------- | --------- | ----------------------------------------- | ------------------------------- | ----------- |\n| `_count`             | `_count`  | Sets the count of the skeleton component. | `number \\| string \\| undefined` | `undefined` |\n| `_name` _(required)_ | `_name`   | Sets the name of the skeleton component.  | `string`                        | `undefined` |\n\n\n## Events\n\n| Event      | Description                                                     | Type                  |\n| ---------- | --------------------------------------------------------------- | --------------------- |\n| `loaded`   | Emitted when the skeleton has finished loading.                 | `CustomEvent<number>` |\n| `rendered` | Emitted when the skeleton has been rendered for the first time. | `CustomEvent<void>`   |\n\n\n## Methods\n\n### `focus() => Promise<void>`\n\nFocuses the interactive element of the component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `toggle() => Promise<void>`\n\nToggles the visibility of the skeleton component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
+      "code": "# kol-skeleton\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property             | Attribute | Description                              | Type     | Default     |\n| -------------------- | --------- | ---------------------------------------- | -------- | ----------- |\n| `_name` _(required)_ | `_name`   | Sets the name of the skeleton component. | `string` | `undefined` |\n\n\n## Events\n\n| Event      | Description                                                     | Type                  |\n| ---------- | --------------------------------------------------------------- | --------------------- |\n| `loaded`   | Emitted when the skeleton has finished loading.                 | `CustomEvent<number>` |\n| `rendered` | Emitted when the skeleton has been rendered for the first time. | `CustomEvent<void>`   |\n\n\n## Methods\n\n### `focus() => Promise<void>`\n\nFocuses the interactive element of the component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `toggle() => Promise<void>`\n\nToggles the visibility of the skeleton component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
       "kind": "spec"
     },
     {
@@ -1941,7 +2157,7 @@
       "group": "spec",
       "name": "table-stateful",
       "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateful.md",
-      "code": "# kol-table-stateful\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property                | Attribute              | Description                                                                                                        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Default     |\n| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_allowMultiSort`       | `_allow-multi-sort`    | Defines whether to allow multi sort.                                                                               | `boolean \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |\n| `_data` _(required)_    | `_data`                | Defines the primary table data.                                                                                    | `KoliBriTableDataType[] \\| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `undefined` |\n| `_dataFoot`             | `_data-foot`           | Defines the data for the table footer.                                                                             | `KoliBriTableDataType[] \\| string \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `undefined` |\n| `_hasSettingsMenu`      | `_has-settings-menu`   | Enables the settings menu if true (default: false).                                                                | `boolean \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |\n| `_headers` _(required)_ | `_headers`             | Defines the horizontal and vertical table headers.                                                                 | `string \\| { horizontal?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                         | `undefined` |\n| `_label` _(required)_   | `_label`               | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined` |\n| `_on`                   | --                     | Defines the callback functions for table events.                                                                   | `undefined \\| { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> \\| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                                          | `undefined` |\n| `_pagination`           | `_pagination`          | Defines whether to show the data distributed over multiple pages.                                                  | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _label?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition`   | `_pagination-position` | Controls the position of the pagination.                                                                           | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `'bottom'`  |\n| `_selection`            | `_selection`           | Defines how rows can be selected and the current selection.                                                        | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })`                                                                                                                                                                                                                                                                  | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n\n----------------------------------------------\n\n\n",
+      "code": "# kol-table-stateful\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property                | Attribute              | Description                                                                                                        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Default     |\n| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_allowMultiSort`       | `_allow-multi-sort`    | Defines whether to allow multi sort.                                                                               | `boolean \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |\n| `_data` _(required)_    | `_data`                | Defines the primary table data.                                                                                    | `KoliBriTableDataType[] \\| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `undefined` |\n| `_dataFoot`             | `_data-foot`           | Defines the data for the table footer.                                                                             | `KoliBriTableDataType[] \\| string \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `undefined` |\n| `_fixedCols`            | --                     | Defines the fixed number of columns from start and end of the table                                                | `[number, number] \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `undefined` |\n| `_hasSettingsMenu`      | `_has-settings-menu`   | Enables the settings menu if true (default: false).                                                                | `boolean \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |\n| `_headers` _(required)_ | `_headers`             | Defines the horizontal and vertical table headers.                                                                 | `string \\| { horizontal?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                         | `undefined` |\n| `_label` _(required)_   | `_label`               | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined` |\n| `_on`                   | --                     | Defines the callback functions for table events.                                                                   | `undefined \\| { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> \\| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                                          | `undefined` |\n| `_pagination`           | `_pagination`          | Defines whether to show the data distributed over multiple pages.                                                  | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _label?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition`   | `_pagination-position` | Controls the position of the pagination.                                                                           | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `'bottom'`  |\n| `_selection`            | `_selection`           | Defines how rows can be selected and the current selection.                                                        | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })`                                                                                                                                                                                                                                                                  | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n\n----------------------------------------------\n\n\n",
       "kind": "spec"
     },
     {
@@ -1949,7 +2165,7 @@
       "group": "spec",
       "name": "table-stateless",
       "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateless.md",
-      "code": "# kol-table-stateless\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property                    | Attribute            | Description                                                                                                        | Type                                                                                                                                                                                                                                                                                   | Default     |\n| --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_data` _(required)_        | `_data`              | Defines the primary table data.                                                                                    | `KoliBriTableDataType[] \\| string`                                                                                                                                                                                                                                                     | `undefined` |\n| `_dataFoot`                 | `_data-foot`         | Defines the data for the table footer.                                                                             | `KoliBriTableDataType[] \\| string \\| undefined`                                                                                                                                                                                                                                        | `undefined` |\n| `_hasSettingsMenu`          | `_has-settings-menu` | Enables the settings menu if true (default: false).                                                                | `boolean \\| undefined`                                                                                                                                                                                                                                                                 | `undefined` |\n| `_headerCells` _(required)_ | `_header-cells`      | Defines the horizontal and vertical table headers.                                                                 | `string \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| undefined; }`                                                                                                                                                              | `undefined` |\n| `_label` _(required)_       | `_label`             | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string`                                                                                                                                                                                                                                                                               | `undefined` |\n| `_on`                       | --                   | Defines the callback functions for table events.                                                                   | `undefined \\| { onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; }` | `undefined` |\n| `_selection`                | `_selection`         | Defines how rows can be selected and the current selection.                                                        | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })`                     | `undefined` |\n\n\n----------------------------------------------\n\n\n",
+      "code": "# kol-table-stateless\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property                    | Attribute            | Description                                                                                                        | Type                                                                                                                                                                                                                                                                                   | Default     |\n| --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_data` _(required)_        | `_data`              | Defines the primary table data.                                                                                    | `KoliBriTableDataType[] \\| string`                                                                                                                                                                                                                                                     | `undefined` |\n| `_dataFoot`                 | `_data-foot`         | Defines the data for the table footer.                                                                             | `KoliBriTableDataType[] \\| string \\| undefined`                                                                                                                                                                                                                                        | `undefined` |\n| `_fixedCols`                | --                   | Defines the fixed number of columns from start and end of the table                                                | `[number, number] \\| undefined`                                                                                                                                                                                                                                                        | `undefined` |\n| `_hasSettingsMenu`          | `_has-settings-menu` | Enables the settings menu if true (default: false).                                                                | `boolean \\| undefined`                                                                                                                                                                                                                                                                 | `undefined` |\n| `_headerCells` _(required)_ | `_header-cells`      | Defines the horizontal and vertical table headers.                                                                 | `string \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| undefined; }`                                                                                                                                                              | `undefined` |\n| `_label` _(required)_       | `_label`             | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string`                                                                                                                                                                                                                                                                               | `undefined` |\n| `_on`                       | --                   | Defines the callback functions for table events.                                                                   | `undefined \\| { onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; }` | `undefined` |\n| `_selection`                | `_selection`         | Defines how rows can be selected and the current selection.                                                        | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })`                     | `undefined` |\n\n\n----------------------------------------------\n\n\n",
       "kind": "spec"
     },
     {