# Leadity Interaktions- und Accessibility-Vertrag

Status: verbindlicher Querschnittsvertrag für Paket 4 der konsolidierten Grundregeln. Der Umfang wurde aus den vorhandenen Version-1-Regeln, Figma-/Runtime-Belegen und dokumentierten offenen Punkten rekonstruiert und am 22. Juli 2026 durch den Nutzer freigegeben.

## 1. Auswahl der Zustände

Eine Komponente erhält nur Zustände, die zu ihrer Semantik und zu einem belegten Produktverhalten gehören:

- **Interaktive Controls:** Default, sichtbarer Hover und sichtbarer Fokus.
- **Aktionen und Eingaben:** Disabled nur, wenn die Komponente diesen Zustand fachlich benötigt und der Vertrag ihn belegt.
- **Auswahlcontrols:** Checked, Selected, Mixed, Pressed oder Expanded nur mit passender nativer Semantik beziehungsweise synchronem ARIA-Zustand.
- **Formulare:** Readonly und Error bleiben von Disabled getrennt. Readonly ist fokussier- und kopierbar; Disabled ist nicht interaktiv.
- **Loading:** auf Region, Toast, Spinner oder Skeleton beschränkt, solange kein komponentenspezifischer Loadingzustand belegt ist.

Pressed-, Toggle-, Loading- oder Disabled-Zustände werden nicht aus Hoverfarben abgeleitet. `:active` ist kein persistenter Auswahlzustand; vertikale `translateY()`-Bewegung wird für Aktionen nicht verwendet.

## 2. Fokus

- Jede per Tastatur erreichbare interaktive Komponente besitzt einen sichtbaren Fokusindikator.
- Globaler Standard: `--leadity-focus-width` = 2 px, `--leadity-focus-color` = `neutral-80` und `--leadity-focus-offset` = 2 px.
- Auf dunklen oder grünen Flächen der globalen Headerregion verwendet der Fokusindikator Weiß.
- `outline: none` beziehungsweise `outline: 0` ist nur zulässig, wenn dieselbe Komponente oder ihre gemeinsame fokussierte Schale einen mindestens gleichwertigen sichtbaren Fokus zeichnet. Ein Fokusindikator darf nicht ersatzlos entfernt werden.
- Komponentenbezogene Abweichungen benötigen einen eigenen Beleg. Sie ersetzen den globalen Fallback nicht pauschal.

## 3. Semantik und Zustandsbindung

- Native Elemente haben Vorrang: Button für Aktionen, Link für Navigation, Checkbox für bestätigte Mehrfachauswahl, Radio für genau eine Option und native Formcontrols, wenn sie die Produktanforderung erfüllen.
- Sichtbarer und programmatischer Zustand bleiben synchron. Je nach Muster werden `disabled`, `aria-checked`, `aria-pressed`, `aria-selected`, `aria-expanded`, `aria-current`, `aria-invalid`, `aria-sort` oder `aria-busy` verwendet.
- Ein Link erhält keinen erfundenen Disabled-Zustand. Ist Navigation nicht verfügbar, wird kein aktiver Quicklink ausgegeben. Berechtigungsabhängige Navigation benötigt einen eigenen belegten Zustand und blockiert Maus- und Tastaturaktivierung zuverlässig.
- Icon-only-Aktionen besitzen einen zugänglichen Namen über sichtbaren Text, `aria-label` oder `aria-labelledby`.
- Farbe, Icon, Platzhalter, Hover oder Bewegung allein vermitteln keine wesentliche Information und ersetzen kein sichtbares beziehungsweise zugängliches Label.

## 4. Tastatur und Fokusführung

- Hoverabhängige Information oder Bedienung ist zusätzlich per Tastatur erreichbar. Tooltips erscheinen bei Hover und Fokus und lassen sich mit Escape schließen.
- Custom Comboboxen und Listboxen unterstützen Pfeiltasten, Enter, Escape, Type-ahead sowie synchrones `aria-selected`.
- Tabs unterstützen Pfeil links/rechts, Home und End. Expandierbare Controls synchronisieren `aria-expanded`.
- Dialoge und Popover besitzen einen zugänglichen Titel, einen sinnvollen Initialfokus und stellen den Fokus beim Schließen wieder am Auslöser her. Kritische Dialoge fokussieren zuerst die sichere Gegenaktion.
- Validierungsfehler setzen `aria-invalid`, verknüpfen die sichtbare Meldung über `aria-describedby` und fokussieren beim Absenden das erste fehlerhafte Control.

## 5. Trefferflächen

- Reguläre Controls besitzen mindestens 40 × 40 px wirksame Trefferfläche.
- Sichtbar kompakte 32-px-Controls behalten mindestens 40 × 40 px wirksame Trefferfläche, ohne benachbarte Trefferflächen zu überlagern.
- Navigationseinträge sind mindestens 44 px hoch.
- Isolierte prominente Kontextaktionen sind 48 px groß.
- Ein sichtbares Info-i bleibt gemäß Overlayvertrag 16 × 16 px ohne sichtbare Buttonschale; seine unsichtbare wirksame Trefferfläche erfüllt mindestens 40 × 40 px. Close-Icons dürfen ebenfalls kleiner sichtbar sein, sofern ihre fokussierbare Elternaktion die Mindesttrefferfläche erfüllt.

## 6. Fehler, Status und Feedback

- Fehler kombinieren sichtbare Meldung, semantische Farbe und programmatische Bindung. Farbe allein genügt nicht.
- Status und Passwortstärke werden zusätzlich durch Text, Icon oder Zahl benannt.
- Dynamische Ergebnis- und Filtermeldungen verwenden eine passende Live-Region, ersetzen aber keinen sichtbaren Zustand.
- Toasts dienen transientem Feedback; Messages persistenten Hinweisen. Kritische Informationen werden nicht ausschließlich als automatisch verschwindender Toast ausgegeben.

## 7. Bewegung und Loading

- `prefers-reduced-motion` reduziert oder entfernt dekorative Übergänge, Transformationen und Skeletonanimationen. Zustandswechsel bleiben unmittelbar sichtbar und funktional verständlich.
- Hover- und Fokuszustände dürfen keine positionsverändernde Bewegung auslösen.
- Eine ladende Region setzt `aria-busy` und erhält bei blockierenden oder längeren Vorgängen deutsche Statuscopy.
- Spinner und Skeleton werden nicht gleichzeitig für dieselbe Region eingesetzt. Ein Skeleton bildet die erwartete Inhaltsform ab und ist kein Empty State.
- Ein generischer Button-Loadingzustand wird erst nach einem eigenen Komponentenbeleg ergänzt.

## 8. Verbindliche Grenzen

- Quicklinks besitzen keinen kanonischen Disabled-Zustand.
- Für Header-Aktionen bleiben unbelegte Kombinationen aus Active + Hover sowie exakte Pressed-/Disabled-Flächen offen.
- Komponenten dürfen spezialisierte Fokus-, Hover-, Error- oder Loadingzustände nur aus ihrem zuständigen Vertrag übernehmen.
- Lokale Ersatzvarianten, Hoverableitungen und parallele Zustandsfarbpaletten sind unzulässig.

## 9. Prüfung

Eine interaktive Oberfläche ist nur freigabefähig, wenn:

1. jede Tastaturaktion einen sichtbaren Fokus besitzt;
2. `outline: none` nur mit gleichwertigem Ersatz vorkommt;
3. Hover keine exklusive Information oder Funktion trägt;
4. sichtbarer und programmatischer Zustand synchron sind;
5. Quicklinks keinen erfundenen Disabled-Zustand erhalten;
6. Fehler, Status und Loading nicht allein durch Farbe oder Bewegung kommuniziert werden;
7. Trefferflächen 40/44/48 px gemäß Einsatzkontext erfüllen;
8. Reduced Motion gebunden ist;
9. keine unbelegten Pressed-, Loading- oder Disabled-Varianten ergänzt wurden.