From 8e51689907e2b89eed98310f0c6c033c47a50c91 Mon Sep 17 00:00:00 2001
From: Stefan Dietz <mail@stefan-dietz.eu>
Date: Wed, 18 Jun 2025 10:22:15 +0200
Subject: [PATCH 1/4] Add Known Issues page (English)

---
 docs/91-known-issues.mdx                      |   5 +
 .../current/91-known-issues.mdx               | 146 ++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 docs/91-known-issues.mdx
 create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx

diff --git a/docs/91-known-issues.mdx b/docs/91-known-issues.mdx
new file mode 100644
index 0000000000..21a344509d
--- /dev/null
+++ b/docs/91-known-issues.mdx
@@ -0,0 +1,5 @@
+---
+title: Bekannte Probleme
+---
+
+todo
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx b/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
new file mode 100644
index 0000000000..08085697c8
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
@@ -0,0 +1,146 @@
+---
+title: Known Issues
+---
+
+## General
+
+### All text inputs
+
+In Chrome on Windows, clicking outside an HTML input but inside a WebComponent does not give focus to the input when it is empty. This issue sometimes does not occur if the input already contains a value. We suspect a focus propagation problem related to WebComponent behavior.
+
+[🐞 GitHub issue #7713](https://github.com/public-ui/kolibri/issues/7713)
+
+### NVDA spells out certain words instead of reading them
+
+It has been observed that on a system with German locale, NVDA spells out certain English words such as "selection", instead of reading them properly.
+
+[🐞 GitHub issue #6898](https://github.com/public-ui/kolibri/issues/6898),
+[Stack Overflow](https://stackoverflow.com/questions/69091167/nvda-spells-words-where-it-shouldnt)
+
+
+## Components
+
+### kol-select
+
+- Disabled options in KolSelect affect the total count in screen readers When an option in `KolSelect` is set to `disabled: true`, it is still counted by screen readers. This leads to incorrect numbering, for example, NVDA announces "2 of 4" instead of "2 of 3". To ensure the correct order, the `aria-hidden="true"` attribute should be set for `disabled` options. This will hide the disabled option from screen readers and keep the total number of items consistent.
+
+[🐞 GitHub issue #7453](https://github.com/public-ui/kolibri/pull/7453)
+
+### kol-input-color
+
+The component InputColor is a wrapper for the native HTML element `<input type="color">` which has accessibility problems:
+
+- With NVDA, the element is announced as "clickable" and not as an input element.
+- It's not possible to select a color using a screen reader.
+- **9.1.3.1h Labeling of form elements programmatically detectable:**
+The label is not announced by the screen reader. Since it reads linearly, no label is perceivable when `hideLabel` is used.
+- **9.1.3.2 Meaningful sequence:**
+When opening the color selection for "Color with error," there is no output. It is not accessible via the Tab key, only with the arrow keys, making it very confusing for screen reader users.
+- **9.2.4.3 Logical keyboard navigation order:**
+The focus order for "Color with error" is very unusual. Users do not realize that they have to use arrow keys to enter. This is especially problematic since it is not visible on black.
+- **9.2.4.7 Clearly visible focus position:**
+The focus is not visible on the black color icon in "Color with error."
+
+For full accessibility, consider using predefined colors lists, e.g. using KolSelect or KolCheckbox.
+
+[🐞 GitHub issue #5549](https://github.com/public-ui/kolibri/issues/5549),
+[🐞 GitHub issue #7455](https://github.com/public-ui/kolibri/pull/7455)
+
+### kol-table-stateful and kol-table-stateless
+
+#### `aria-sort` changes sometimes not announced in NVDA
+
+When a table column changes its sort order (i.e. when its `aria-sort` attribut changes), screen readers announce this change automatically.
+For unknown reasons, this sometime does not happen in NVDA.
+
+[🐞 GitHub issue (PR) #5780](https://github.com/public-ui/kolibri/pull/5780),
+[🐞 NVDA issue #10890](https://github.com/nvaccess/nvda/issues/10890),
+[🐞 NVDA issue #8132](https://github.com/nvaccess/nvda/issues/8132)
+
+#### Sticky headers
+
+Sticky headers in tables are not supported at the moment, because `position: sticky` doesn't work together with `overflow: auto` on the table container, without introducing other drawbacks.
+
+[🐞 GitHub issue #7490](https://github.com/public-ui/kolibri/issues/7490),
+[CSSWG Drafts issue](https://github.com/w3c/csswg-drafts/issues/865),
+[Code-Sample (StackBlitz)](https://stackblitz.com/edit/stackblitz-starters-umfg2y7m)
+
+### kol-input-number and kol-input-date
+
+#### 'readonly' not announced in NVDA
+
+The components InputNumber and InputDate render their respective native HTML elements `<input type="number">` and `<input type="date">` which both support the
+attribute `readonly`.
+When focusing the element, it's expected that the `readonly` attribute is announced as part of the element description. This isn't the case for NVDA.
+
+[🐞 GitHub issue #5554](https://github.com/public-ui/kolibri/issues/5554) (For number),
+[🐞 GitHub issue #5749](https://github.com/public-ui/kolibri/issues/5749) (For date),
+[🐞 NVDA issue #13672](https://github.com/nvaccess/nvda/issues/13672)
+
+### kol-input-date
+
+#### VoiceOver Reads Date Inputs with Percentage in Google Chrome
+
+In Google Chrome, when using VoiceOver with empty `date` input fields (no initial value), an unexpected percentage value is read aloud alongside the usual prompt.
+
+Notably, this issue does not occur with Windows Narrator, which handles empty date inputs correctly.
+
+There is a Bug Report for this Issue:
+
+[VoiceOver reads negative percent values for month, day, and year steppers in `<input type="date">`](https://issuetracker.google.com/issues/361250561?pli=1)
+
+### kol-input-text
+
+The `search` of this component is highly browser-dependent. For example, the close button is either shown or hidden depending on the browser. Accessibility is therefore not achieved.
+
+[🐞 GitHub issue #6307](https://github.com/public-ui/kolibri/issues/6307)
+
+### kol-select
+
+#### Screen reader only reads last selected option
+
+KolSelect is using native HTML `<select>`.
+
+When using KolSelect with the `multiple` property, the native HTML `<select>` may cause problems with screen readers.
+Often the entire selection is not read out, but only the last one. Therefore, the KolSelect has no full accessibility.
+
+#### Limited Styling Capabilities for `<select>` and `<option>` Elements
+
+[Stackblitz Example](https://stackblitz.com/edit/vitejs-vite-nthnce?file=src%2Fstyle.css)
+
+The `<select>` element and its `<option>` tags offer limited styling options. Specifically, states such as "selected", "focus" or "active" cannot be reliably customized using CSS. This leads to challenges in meeting accessibility standards, especially in ensuring sufficient contrast ratios.
+
+**Impact**:
+
+- **Limited Customization**: The visual state of dropdown options (e.g., on focus or selection) cannot be consistently customized across all browsers. This makes it difficult to create an accessible visual experience for all users.
+
+- **Browser-Dependent Rendering**: The appearance of the `<select>` element varies across browsers and operating systems, resulting in inconsistent user experiences.
+
+- **Contrast Issues**: Since the contrast of the default dropdown rendering is controlled by the browser, it's not always possible to ensure WCAG-compliant contrast ratios, which may hinder readability for users with visual impairments.
+
+### kol-icon
+
+#### Firefox Accessibility Issue with `aria-label`
+
+The use of `aria-label` or `aria-labelledby` on `<kol-icon>` or its nested elements does not work reliably in Firefox. Even applying these attributes directly to `<kol-icon>` has no effect, which points to a browser-specific issue with ARIA support in custom elements or shadow DOM contexts.
+
+##### Key Points
+
+- The issue lies in Firefox's handling of ARIA attributes on custom web components or deeply nested elements.
+- This is not related to dynamic announcements (`aria-live`) but specifically to the inability of Firefox to process `aria-label` or `aria-labelledby` correctly in these cases.
+- The issue is browser-specific and does not consistently occur in Chrome, Edge, or Safari.
+
+##### Conclusion
+
+This is a limitation in Firefox’s ARIA implementation. Until it is resolved, alternative strategies like visually hidden text near the element or redundant error messages should be used to ensure accessibility.
+
+[🐞 GitHub issue #7076](https://github.com/public-ui/kolibri/issues/7076),
+[🐞 GitHub issue #7119](https://github.com/public-ui/kolibri/issues/7119)
+
+### Toaster
+
+Toasts are rendered in a container that's appended as first element of `<body>` and elevated using a high `z-index`.
+
+When using [modal Dialogs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) these are rendered above toasts on the
+[top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer). Hence, toast messages are always blocked by Modal Dialogs. We recommend completely
+avoiding Toasts in Modals and giving feedback within the modal directly.

From e6e06908af0c8926cc2995c7e9b4027790aed00e Mon Sep 17 00:00:00 2001
From: Peter Laske <37439758+laske185@users.noreply.github.com>
Date: Fri, 20 Jun 2025 09:05:05 +0200
Subject: [PATCH 2/4] docs: Update kol-select known issues from kolibri-develop

---
 .../docusaurus-plugin-content-docs/current/91-known-issues.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx b/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
index 08085697c8..a21600f6a0 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
+++ b/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
@@ -22,9 +22,10 @@ It has been observed that on a system with German locale, NVDA spells out certai
 
 ### kol-select
 
-- Disabled options in KolSelect affect the total count in screen readers When an option in `KolSelect` is set to `disabled: true`, it is still counted by screen readers. This leads to incorrect numbering, for example, NVDA announces "2 of 4" instead of "2 of 3". To ensure the correct order, the `aria-hidden="true"` attribute should be set for `disabled` options. This will hide the disabled option from screen readers and keep the total number of items consistent.
+- Disabled options in KolSelect affect the total count in some screen readers. When an option is set to disabled: true, it may still be included in the overall option count announced by assistive technology. Using aria-hidden="true" on <option> is not conforming with WAI‑ARIA and causes browser warnings, therefore it has been removed. As a result, screen readers might announce a higher number of available options than can actually be selected.
 
 [🐞 GitHub issue #7453](https://github.com/public-ui/kolibri/pull/7453)
+[🐞 GitHub issue #7920](https://github.com/public-ui/kolibri/pull/7920)
 
 ### kol-input-color
 

From 02654683be4d447909a5a9d273f2bb1b30d90d0f Mon Sep 17 00:00:00 2001
From: Peter Laske <37439758+laske185@users.noreply.github.com>
Date: Fri, 20 Jun 2025 12:34:45 +0200
Subject: [PATCH 3/4] fix: correct formatting of code snippet in kol-select
 known issues

---
 .../docusaurus-plugin-content-docs/current/91-known-issues.mdx  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx b/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
index a21600f6a0..aa58df6c34 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
+++ b/i18n/en/docusaurus-plugin-content-docs/current/91-known-issues.mdx
@@ -22,7 +22,7 @@ It has been observed that on a system with German locale, NVDA spells out certai
 
 ### kol-select
 
-- Disabled options in KolSelect affect the total count in some screen readers. When an option is set to disabled: true, it may still be included in the overall option count announced by assistive technology. Using aria-hidden="true" on <option> is not conforming with WAI‑ARIA and causes browser warnings, therefore it has been removed. As a result, screen readers might announce a higher number of available options than can actually be selected.
+- Disabled options in KolSelect affect the total count in some screen readers. When an option is set to disabled: true, it may still be included in the overall option count announced by assistive technology. Using aria-hidden="true" on `<option>` is not conforming with WAI‑ARIA and causes browser warnings, therefore it has been removed. As a result, screen readers might announce a higher number of available options than can actually be selected.
 
 [🐞 GitHub issue #7453](https://github.com/public-ui/kolibri/pull/7453)
 [🐞 GitHub issue #7920](https://github.com/public-ui/kolibri/pull/7920)

From d943f45297137a411dcdafd7863a3f273f943a82 Mon Sep 17 00:00:00 2001
From: Peter Laske <37439758+laske185@users.noreply.github.com>
Date: Fri, 20 Jun 2025 12:35:03 +0200
Subject: [PATCH 4/4] docs: translate the known issues to german

---
 docs/91-known-issues.mdx | 137 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 136 insertions(+), 1 deletion(-)

diff --git a/docs/91-known-issues.mdx b/docs/91-known-issues.mdx
index 21a344509d..e196a52e79 100644
--- a/docs/91-known-issues.mdx
+++ b/docs/91-known-issues.mdx
@@ -2,4 +2,139 @@
 title: Bekannte Probleme
 ---
 
-todo
+## Allgemein
+
+### Alle Texteingabefelder
+
+In Chrome unter Windows erhält ein leeres HTML-Eingabefeld beim Klicken außerhalb des Eingabefelds, aber innerhalb einer WebComponent, keinen Fokus. Dieses Problem tritt manchmal nicht auf, wenn das Eingabefeld bereits einen Wert enthält. Wir vermuten ein Problem mit der Fokus-Weitergabe im Zusammenhang mit WebComponent-Verhalten.
+
+[🐞 GitHub Issue #7713](https://github.com/public-ui/kolibri/issues/7713)
+
+### NVDA buchstabiert bestimmte Wörter statt sie vorzulesen
+
+Es wurde beobachtet, dass NVDA auf einem System mit deutscher Spracheinstellung bestimmte englische Wörter wie "selection" buchstabiert, anstatt sie korrekt vorzulesen.
+
+[🐞 GitHub Issue #6898](https://github.com/public-ui/kolibri/issues/6898),
+[Stack Overflow](https://stackoverflow.com/questions/69091167/nvda-spells-words-where-it-shouldnt)
+
+## Komponenten
+
+### kol-select
+
+- Deaktivierte Optionen in KolSelect beeinflussen die Gesamtanzahl in einigen Screenreadern. Wenn eine Option mit disabled: true gesetzt ist, wird sie möglicherweise trotzdem in der Gesamtanzahl der Optionen von unterstützenden Technologien mitgezählt. Die Verwendung von aria-hidden="true" auf `<option>` entspricht nicht den WAI-ARIA-Richtlinien und verursacht Browser-Warnungen, daher wurde dies entfernt. Infolgedessen könnten Screenreader eine höhere Anzahl verfügbarer Optionen ansagen, als tatsächlich auswählbar sind.
+
+[🐞 GitHub Issue #7453](https://github.com/public-ui/kolibri/pull/7453)
+[🐞 GitHub Issue #7920](https://github.com/public-ui/kolibri/pull/7920)
+
+### kol-input-color
+
+Die Komponente InputColor ist ein Wrapper für das native HTML-Element `<input type="color">`, das Zugänglichkeitsprobleme aufweist:
+
+- Mit NVDA wird das Element als "klickbar" und nicht als Eingabefeld angekündigt.
+- Es ist nicht möglich, mit einem Screenreader eine Farbe auszuwählen.
+- **9.1.3.1h Programmgesteuerte Erkennbarkeit der Beschriftung von Formularelementen:**
+Das Label wird vom Screenreader nicht angekündigt. Da linear gelesen wird, ist bei Verwendung von `hideLabel` kein Label wahrnehmbar.
+- **9.1.3.2 Sinnvolle Reihenfolge:**
+Beim Öffnen der Farbauswahl für "Farbe mit Fehler" erfolgt keine Ausgabe. Sie ist nicht über die Tab-Taste, sondern nur mit den Pfeiltasten erreichbar, was für Screenreader-Nutzer sehr verwirrend ist.
+- **9.2.4.3 Logische Tastaturnavigationsreihenfolge:**
+Die Fokusreihenfolge für "Farbe mit Fehler" ist sehr ungewöhnlich. Nutzer erkennen nicht, dass sie die Pfeiltasten verwenden müssen. Dies ist besonders problematisch, da es auf Schwarz nicht sichtbar ist.
+- **9.2.4.7 Deutlich sichtbare Fokusposition:**
+Der Fokus ist auf dem schwarzen Farbsymbol bei "Farbe mit Fehler" nicht sichtbar.
+
+Für vollständige Barrierefreiheit sollten vordefinierte Farblisten, z. B. mit KolSelect oder KolCheckbox, verwendet werden.
+
+[🐞 GitHub Issue #5549](https://github.com/public-ui/kolibri/issues/5549),
+[🐞 GitHub Issue #7455](https://github.com/public-ui/kolibri/pull/7455)
+
+### kol-table-stateful und kol-table-stateless
+
+#### Änderungen an `aria-sort` werden manchmal in NVDA nicht angekündigt
+
+Wenn sich die Sortierreihenfolge einer Tabellenspalte ändert (d. h. wenn sich das `aria-sort`-Attribut ändert), kündigen Screenreader diese Änderung normalerweise automatisch an. Aus unbekannten Gründen geschieht dies manchmal in NVDA nicht.
+
+[🐞 GitHub Issue (PR) #5780](https://github.com/public-ui/kolibri/pull/5780),
+[🐞 NVDA Issue #10890](https://github.com/nvaccess/nvda/issues/10890),
+[🐞 NVDA Issue #8132](https://github.com/nvaccess/nvda/issues/8132)
+
+#### Feste Tabellenköpfe (Sticky Headers)
+
+Feste Tabellenköpfe werden derzeit nicht unterstützt, da `position: sticky` nicht mit `overflow: auto` im Tabellen-Container funktioniert, ohne andere Nachteile einzuführen.
+
+[🐞 GitHub Issue #7490](https://github.com/public-ui/kolibri/issues/7490),
+[CSSWG Drafts Issue](https://github.com/w3c/csswg-drafts/issues/865),
+[Code-Beispiel (StackBlitz)](https://stackblitz.com/edit/stackblitz-starters-umfg2y7m)
+
+### kol-input-number und kol-input-date
+
+#### 'readonly' wird in NVDA nicht angekündigt
+
+Die Komponenten InputNumber und InputDate rendern die jeweiligen nativen HTML-Elemente `<input type="number">` und `<input type="date">`, die beide das Attribut `readonly` unterstützen. Beim Fokussieren des Elements wird erwartet, dass das Attribut `readonly` als Teil der Elementbeschreibung angekündigt wird. Dies ist bei NVDA nicht der Fall.
+
+[🐞 GitHub Issue #5554](https://github.com/public-ui/kolibri/issues/5554) (Für number),
+[🐞 GitHub Issue #5749](https://github.com/public-ui/kolibri/issues/5749) (Für date),
+[🐞 NVDA Issue #13672](https://github.com/nvaccess/nvda/issues/13672)
+
+### kol-input-date
+
+#### VoiceOver liest Datumsfelder mit Prozentangabe in Google Chrome vor
+
+In Google Chrome liest VoiceOver bei leeren `date`-Eingabefeldern (ohne Anfangswert) einen unerwarteten Prozentwert zusammen mit der üblichen Eingabeaufforderung vor.
+
+Dieses Problem tritt bei Windows Narrator nicht auf, der leere Datumsfelder korrekt behandelt.
+
+Es gibt einen Bug-Report zu diesem Problem:
+
+[VoiceOver reads negative percent values for month, day, and year steppers in `<input type="date">`](https://issuetracker.google.com/issues/361250561?pli=1)
+
+### kol-input-text
+
+Das Suchfeld dieser Komponente ist stark vom Browser abhängig. Beispielsweise wird das Schließen-Symbol je nach Browser angezeigt oder nicht. Barrierefreiheit ist daher nicht gewährleistet.
+
+[🐞 GitHub Issue #6307](https://github.com/public-ui/kolibri/issues/6307)
+
+### kol-select
+
+#### Screenreader liest nur die zuletzt ausgewählte Option vor
+
+KolSelect verwendet das native HTML-Element `<select>`.
+
+Bei Verwendung von KolSelect mit der Eigenschaft `multiple` kann das native HTML-Element `<select>` Probleme mit Screenreadern verursachen. Oft wird nicht die gesamte Auswahl vorgelesen, sondern nur die letzte. Daher ist KolSelect nicht vollständig barrierefrei.
+
+#### Eingeschränkte Styling-Möglichkeiten für `<select>` und `<option>`-Elemente
+
+[Stackblitz-Beispiel](https://stackblitz.com/edit/vitejs-vite-nthnce?file=src%2Fstyle.css)
+
+Das `<select>`-Element und seine `<option>`-Tags bieten nur eingeschränkte Styling-Möglichkeiten. Insbesondere Zustände wie "selected", "focus" oder "active" können nicht zuverlässig per CSS angepasst werden. Dies erschwert es, Barrierefreiheitsstandards einzuhalten, insbesondere ausreichende Kontrastverhältnisse sicherzustellen.
+
+**Auswirkungen**:
+
+- **Eingeschränkte Anpassbarkeit**: Der visuelle Zustand von Dropdown-Optionen (z. B. bei Fokus oder Auswahl) kann nicht in allen Browsern konsistent angepasst werden. Dadurch ist es schwierig, ein barrierefreies visuelles Erlebnis für alle Nutzer zu schaffen.
+
+- **Browserabhängige Darstellung**: Das Erscheinungsbild des `<select>`-Elements variiert je nach Browser und Betriebssystem, was zu uneinheitlichen Nutzererfahrungen führt.
+
+- **Kontrastprobleme**: Da der Kontrast der Standard-Dropdown-Darstellung vom Browser gesteuert wird, ist es nicht immer möglich, WCAG-konforme Kontrastverhältnisse sicherzustellen, was die Lesbarkeit für sehbehinderte Nutzer beeinträchtigen kann.
+
+### kol-icon
+
+#### Firefox-Problem mit `aria-label` bei Barrierefreiheit
+
+Die Verwendung von `aria-label` oder `aria-labelledby` auf `<kol-icon>` oder dessen verschachtelten Elementen funktioniert in Firefox nicht zuverlässig. Selbst das direkte Anwenden dieser Attribute auf `<kol-icon>` hat keine Wirkung, was auf ein browser-spezifisches Problem mit ARIA-Unterstützung bei Custom Elements oder Shadow DOM hinweist.
+
+##### Wichtige Punkte
+
+- Das Problem liegt in der Handhabung von ARIA-Attributen bei benutzerdefinierten Webkomponenten oder tief verschachtelten Elementen in Firefox.
+- Es handelt sich nicht um dynamische Ankündigungen (`aria-live`), sondern speziell um die Unfähigkeit von Firefox, `aria-label` oder `aria-labelledby` in diesen Fällen korrekt zu verarbeiten.
+- Das Problem ist browser-spezifisch und tritt nicht konsistent in Chrome, Edge oder Safari auf.
+
+##### Fazit
+
+Dies ist eine Einschränkung in der ARIA-Implementierung von Firefox. Bis das Problem behoben ist, sollten alternative Strategien wie visuell versteckter Text in der Nähe des Elements oder redundante Fehlermeldungen verwendet werden, um Barrierefreiheit sicherzustellen.
+
+[🐞 GitHub Issue #7076](https://github.com/public-ui/kolibri/issues/7076),
+[🐞 GitHub Issue #7119](https://github.com/public-ui/kolibri/issues/7119)
+
+### Toaster
+
+Toasts werden in einem Container gerendert, der als erstes Element in `<body>` eingefügt und mit einem hohen `z-index` versehen wird.
+
+Bei der Verwendung von [modalen Dialogen](https://developer.mozilla.org/de/docs/Web/HTML/Element/dialog) werden diese über Toasts auf der [Top Layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer) gerendert. Daher werden Toast-Nachrichten immer von Modalen blockiert. Wir empfehlen, Toasts in Modalen komplett zu vermeiden und Rückmeldungen direkt im Modal zu geben.