Skip to content

docs(textarea): Overhaul Barrierefreiheit/Accessibility section with WCAG 2.2, BITV 2.0, EN 301 549 #653

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
+104 −16
Draft

docs(textarea): Overhaul Barrierefreiheit/Accessibility section with WCAG 2.2, BITV 2.0, EN 301 549 #653

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ef31886
docs(textarea): update Barrierefreiheit/Accessibility section with WC…
Copilot Apr 2, 2026
3260a57
docs(textarea): fix WCAG 3.3.2 description and add _hideLabel accessi…
Copilot Apr 2, 2026
0992ffd
docs(textarea): fix ARIA claims, remove keyboard controls from a11y s…
Copilot Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 50 additions & 11 deletions docs/30-components/textarea.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,60 @@ Standard-Textarea mit Beschriftung und Platzhaltertext:

## Barrierefreiheit

Die **Textarea**-Komponente wurde mit Fokus auf Barrierefreiheit entwickelt und unterstützt verschiedene assistive Technologien:
Die **Textarea**-Komponente basiert auf dem nativen `<textarea>`-HTML-Element und wurde konsequent nach den Anforderungen der WCAG 2.2, BITV 2.0 und EN 301 549 entwickelt.

- **Label-Pflicht**: Jede Textarea muss über das Attribut `_label` eine sichtbare Beschriftung erhalten. Dies gewährleistet, dass Screenreader-Nutzer verstehen, welchen Zweck das Eingabefeld erfüllt.
- **Hinweistexte**: Mit `_hint` können zusätzliche Informationen bereitgestellt werden, die für alle Nutzer zugänglich sind und von Screenreadern vorgelesen werden.
- **Fehlermeldungen**: Fehlerhafte Eingaben können über das Attribut `_msg` mit aussagekräftigen Fehlermeldungen versehen werden, die von assistiven Technologien erkannt und vorgelesen werden.
- **Zeichenzähler**: Bei aktiviertem Zeichenzähler (`_has-counter`) wird der Status mit einer Verzögerung von 500 ms aktualisiert, um Screenreader nicht bei jeder Eingabe zu unterbrechen. Zusätzlich wird ein versteckter, nur für assistive Technologien sichtbarer Text eingeblendet (z.B. "Sie können bis zu 100 Zeichen eingeben").
- **Fokusmanagement**: Die Textarea ist vollständig über die Tastatur bedienbar und bietet klare Fokusindikatoren.
- **Pflichtfelder**: Mit `_required` gekennzeichnete Felder werden korrekt an assistive Technologien kommuniziert.
### Semantik und ARIA

- Die Komponente rendert ein natives `<textarea>`-Element, das über das `for`/`id`-Muster mit einem `<label>`-Element verknüpft ist. Diese native HTML-Verknüpfung stellt sicher, dass Screenreader das Eingabefeld korrekt ansagen — ohne zusätzliche ARIA-Attribute.
- Hinweistexte (`_hint`) und Fehlermeldungen (`_msg`) werden über `aria-describedby` mit der Textarea verknüpft, sodass assistive Technologien diese Informationen zusammen mit der Feldbezeichnung vorlesen.
- Pflichtfelder (`_required`) setzen das native `required`-Attribut. Ein redundantes `aria-required` wird nicht gesetzt, da das native Attribut für assistive Technologien ausreicht.
- Fehlerzustände werden über `aria-describedby` kommuniziert, das auf die angezeigte Fehlermeldung verweist. Es wird kein `aria-invalid` gesetzt — die Fehlerbeschreibung im verknüpften Element ist für Screenreader ausreichend.
- Deaktivierte Felder (`_disabled`) verwenden das native `disabled`-Attribut; schreibgeschützte Felder (`_readOnly`) setzen das native `readonly`-Attribut. ARIA-Entsprechungen werden bewusst nicht gesetzt (Minimal-ARIA-Prinzip).

### Beschriftung und Textalternativen

- Das Attribut `_label` ist verpflichtend und stellt den barrierefreien Namen (accessible name) des Eingabefelds programmatisch bereit. Screenreader lesen diesen Namen beim Fokussieren der Textarea vor (WCAG 2.2 Erfolgskriterium 3.3.2).
- Wird `_hideLabel` gesetzt, wird das Label visuell ausgeblendet und erscheint nur als Tooltip, wenn die Komponente den Fokus erhält. Der barrierefreie Name bleibt erhalten, da `_label` weiterhin im Accessibility Tree verfügbar ist. Aus Barrierefreiheitssicht sind dauerhaft sichtbare Labels jedoch zu bevorzugen: Nutzende mit kognitiven Einschränkungen sind auf persistente Beschriftungen angewiesen, und Touch-Nutzende sehen Tooltips in der Regel nicht.
- Ergänzende Hinweise werden über `_hint` bereitgestellt und über `aria-describedby` mit dem Eingabefeld verknüpft.
- Fehlermeldungen werden über `_msg` übergeben, ebenfalls per `aria-describedby` verknüpft und von Screenreadern vorgelesen.

### Zeichenzähler

- Bei aktiviertem Zeichenzähler (`_has-counter`) aktualisiert sich die Anzeige mit einer **Verzögerung von 500 ms**, damit Screenreader-Ankündigungen gebündelt werden und das Tippen nicht unterbrechen.
- Zusätzlich wird ein für sehende Nutzende versteckter Text ausgegeben (z.B. „Sie können bis zu 100 Zeichen eingeben"), der ausschließlich für assistive Technologien sichtbar ist.
- Bei `_max-length-behavior="soft"` wird das native `maxlength`-Attribut **nicht** gesetzt; der Zähler zeigt überschrittene Zeichen an, ohne die Eingabe zu sperren.

### Relevante WCAG 2.2 Erfolgskriterien

| Erfolgskriterium | Beschreibung | Konformitätsstufe |
| ---------------- | ------------ | ----------------- |
| 1.3.1 | Informationen und Beziehungen — Label-Verknüpfung und `aria-describedby` für Hinweise und Fehlermeldungen | A |
| 1.3.5 | Eingabezweck bestimmen — Unterstützung von `autocomplete`-Attribut für bekannte Eingabetypen | AA |
| 1.4.3 | Kontrast (Minimum) — Text im Eingabefeld und Beschriftung erfüllen das Kontrastverhältnis von 4,5:1 | AA |
| 1.4.11 | Nicht-Text-Kontrast — Fokusindikator und Rahmen des Eingabefelds erfüllen ein Kontrastverhältnis von mindestens 3:1 | AA |
| 2.1.1 | Tastatur — Die Komponente ist vollständig per Tastatur bedienbar | A |
| 2.4.7 | Sichtbarer Fokus — Der Fokuszustand der Textarea ist visuell erkennbar | AA |
| 2.4.11 | Fokus nicht verdeckt (Minimum) — Die fokussierte Textarea wird nicht vollständig durch andere Inhalte überdeckt | AA |
| 2.5.8 | Zielgröße (Minimum) — Das Eingabefeld erfüllt die Mindestgröße von 24×24 CSS-Pixeln | AA |
| 3.3.1 | Fehlererkennung — Fehlerhafte Eingaben werden über `aria-describedby` mit einer beschreibenden Fehlermeldung (`_msg`) kommuniziert | A |
| 3.3.2 | Beschriftungen oder Anweisungen — `_label` ist verpflichtend und stellt den barrierefreien Namen bereit; bei Verwendung von `_hideLabel` bleibt der accessible name erhalten, das Label ist jedoch nur als Tooltip beim Fokus sichtbar | A |
| 4.1.2 | Name, Rolle, Wert — Name (label), Rolle (textarea), Zustand (required, disabled, invalid) sind programmatisch bestimmbar | A |
| 4.1.3 | Statusmeldungen — Der Zeichenzähler nutzt eine zeitlich verzögerte Aktualisierung, um Screenreader-Ereignisse zu bündeln | AA |

### BITV 2.0 und EN 301 549

Die BITV 2.0 verweist in § 3 Abs. 1 auf die EN 301 549 als verbindlichen technischen Standard. Alle oben genannten WCAG 2.2 Erfolgskriterien sind über Kapitel 9 (Web) der EN 301 549 v3.2.1 abgedeckt. Für den Einsatz in nativen Web-Applikationen gelten ergänzend die Anforderungen aus Kapitel 11 der EN 301 549 (Software). Spezifische BITV-Anforderungen wie Gebärdensprachvideos oder Leichte-Sprache-Alternativen sind für diese Komponente nicht direkt relevant.

Die [Handreichung zur BITV 2.0 — Barrierefreie Gestaltung von User Interface-Elementen](https://handreichungen.bfit-bund.de/barrierefreie-uie/) des bfit-bund enthält konkrete Prüfanleitungen für Texteingabefelder (Kategorie *Texteingabe*), die insbesondere die programmatische Beschriftung (9.1.3.1h), die Fehleridentifikation (9.3.3.1) sowie die Tastaturbedienbarkeit (9.2.1.1) abdecken und mit den oben aufgeführten Kriterien übereinstimmen.

### Links und Referenzen

- <ExampleLink component="textarea" />
- <kol-link _href="https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html" _target="_blank" _label="WCAG 2.1 - Labels or Instructions"></kol-link>
- <kol-link _href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea" _target="_blank" _label="MDN Web Docs - textarea Element"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html" _target="_blank" _label="WCAG 2.1 - Error Identification"></kol-link>
- <kol-link _href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea" _target="_blank" _label="MDN Web Docs: textarea-Element"></kol-link>
- <kol-link _href="https://handreichungen.bfit-bund.de/barrierefreie-uie/" _target="_blank" _label="Handreichung zur BITV 2.0: Barrierefreie Gestaltung von User Interface-Elementen (bfit-bund)"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html" _target="_blank" _label="WCAG 2.2: Erfolgskriterium 3.3.2 Beschriftungen oder Anweisungen verstehen"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html" _target="_blank" _label="WCAG 2.2: Erfolgskriterium 3.3.1 Fehlererkennung verstehen"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html" _target="_blank" _label="WCAG 2.2: Erfolgskriterium 4.1.2 Name, Rolle, Wert verstehen"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html" _target="_blank" _label="WCAG 2.2: Erfolgskriterium 2.1.1 Tastatur verstehen"></kol-link>
- <kol-link _href="https://medium.com/@gavyn/til-autofocus-inputs-are-an-accessibility-problem-32ced60c3109" _target="_blank" _label="Autofocus und Barrierefreiheit"></kol-link>

## Nutzung
Expand Down
59 changes: 54 additions & 5 deletions i18n/en/docusaurus-plugin-content-docs/current/30-components/textarea.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,61 @@ The **`_resize`** attribute can also be used to specify whether and in which dir

## Accessibility

### Keyboard controls
The **Textarea** component is based on the native `<textarea>` HTML element and has been developed in accordance with the requirements of WCAG 2.2, BITV 2.0 and EN 301 549.

| button | Function |
| -------------- | ------------------------------------------------------------------------------- |
| `Tab` | Focuses the text area. |
| `arrow keys` | Can be used to navigate the content of the focused text area. |
### Semantics and ARIA

- The component renders a native `<textarea>` element linked to a `<label>` element via the standard `for`/`id` pattern. This native HTML association ensures that screen readers announce the input correctly — no additional ARIA attributes are needed.
- Hint texts (`_hint`) and error messages (`_msg`) are linked to the textarea via `aria-describedby`, so that assistive technologies read these together with the field label.
- Required fields (`_required`) set the native `required` attribute. A redundant `aria-required` is not set, as the native attribute is sufficient for assistive technologies.
- Error states are communicated via `aria-describedby`, which points to the displayed error message. No `aria-invalid` is set — the error description in the linked element is sufficient for screen readers.
- Disabled fields (`_disabled`) use the native `disabled` attribute; read-only fields (`_readOnly`) set the native `readonly` attribute. ARIA equivalents are deliberately not set (minimal-ARIA principle).

### Labels and text alternatives

- The `_label` attribute is mandatory and programmatically provides the accessible name of the input field. Screen readers announce this name when the textarea receives focus (WCAG 2.2 success criterion 3.3.2).
- When `_hideLabel` is set, the label is visually hidden and only appears as a tooltip when the component receives focus. The accessible name is preserved because `_label` remains available in the accessibility tree. However, persistently visible labels are strongly preferred for accessibility: users with cognitive impairments rely on persistent labels, and touch users typically never see tooltips.
- Supplementary hints are provided via `_hint` and linked to the input field via `aria-describedby`.
- Error messages are passed via `_msg`, also linked via `aria-describedby` and read out by screen readers.

### Character counter

- When the character counter is enabled (`_has-counter`), the display updates with a **500 ms delay** so that screen reader announcements are bundled and typing is not interrupted.
- An additional text that is hidden for sighted users (e.g. "You can enter up to 100 characters.") is output exclusively for assistive technologies.
- With `_max-length-behavior="soft"`, the native `maxlength` attribute is **not** set; the counter shows exceeded characters without blocking input.

### Relevant WCAG 2.2 success criteria

| Success criterion | Description | Conformance level |
| ----------------- | ----------- | ----------------- |
| 1.3.1 | Info and Relationships — label association and `aria-describedby` for hints and error messages | A |
| 1.3.5 | Identify Input Purpose — support for `autocomplete` attribute for known input types | AA |
| 1.4.3 | Contrast (Minimum) — text inside the input field and label meet the 4.5:1 contrast ratio | AA |
| 1.4.11 | Non-text Contrast — focus indicator and input border meet a contrast ratio of at least 3:1 | AA |
| 2.1.1 | Keyboard — the component is fully operable via keyboard | A |
| 2.4.7 | Focus Visible — the focused state of the textarea is visually recognisable | AA |
| 2.4.11 | Focus Not Obscured (Minimum) — the focused textarea is not completely hidden by other content | AA |
| 2.5.8 | Target Size (Minimum) — the input field meets the minimum size of 24×24 CSS pixels | AA |
| 3.3.1 | Error Identification — invalid input is communicated via `aria-describedby` with a descriptive error message (`_msg`) | A |
| 3.3.2 | Labels or Instructions — `_label` is mandatory and provides the accessible name; when `_hideLabel` is used, the accessible name is preserved but the label is only visible as a tooltip on focus | A |
| 4.1.2 | Name, Role, Value — name (label), role (textarea) and state (required, disabled, invalid) are programmatically determinable | A |
| 4.1.3 | Status Messages — the character counter uses a time-delayed update to bundle screen reader events | AA |

### BITV 2.0 and EN 301 549

BITV 2.0 (§ 3 para. 1) refers to EN 301 549 as the binding technical standard. All WCAG 2.2 success criteria listed above are covered by Chapter 9 (Web) of EN 301 549 v3.2.1. For use in native web applications, the requirements of Chapter 11 (Software) of EN 301 549 additionally apply. BITV-specific requirements such as sign language videos or easy language alternatives are not directly relevant for this component.

The [Handreichung zur BITV 2.0 — Barrierefreie Gestaltung von User Interface-Elementen](https://handreichungen.bfit-bund.de/barrierefreie-uie/) from bfit-bund provides specific test instructions for text input fields, covering programmatic labelling (9.1.3.1h), error identification (9.3.3.1) and keyboard operability (9.2.1.1), which align with the criteria listed above.

### Links and references

- <kol-link _href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea" _target="_blank" _label="MDN Web Docs: textarea element"></kol-link>
- <kol-link _href="https://handreichungen.bfit-bund.de/barrierefreie-uie/" _target="_blank" _label="Handreichung zur BITV 2.0: Accessible UI Elements (bfit-bund)"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html" _target="_blank" _label="WCAG 2.2: Understanding Success Criterion 3.3.2 Labels or Instructions"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html" _target="_blank" _label="WCAG 2.2: Understanding Success Criterion 3.3.1 Error Identification"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html" _target="_blank" _label="WCAG 2.2: Understanding Success Criterion 4.1.2 Name, Role, Value"></kol-link>
- <kol-link _href="https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html" _target="_blank" _label="WCAG 2.2: Understanding Success Criterion 2.1.1 Keyboard"></kol-link>
- <kol-link _href="https://medium.com/@gavyn/til-autofocus-inputs-are-an-accessibility-problem-32ced60c3109" _target="_blank" _label="Autofocus and accessibility"></kol-link>


## Character limit and character counter
Expand Down