docs: massive restructuring of documentation, development guides and agent playbooks
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
---
|
||||
type: Frontend Guideline
|
||||
status: APPROVED
|
||||
owner: 🖌️ UI/UX Designer
|
||||
reviewed_by: 🎨 Frontend Expert
|
||||
last_update: 2026-04-03
|
||||
related:
|
||||
- docs/06_Frontend/Navigation_V3_Screen-Baum_und_Back-Stack.md
|
||||
- docs/04_Agents/Roadmaps/UIUX_Roadmap.md
|
||||
---
|
||||
|
||||
# Entscheidungsrichtlinie — Editier-Formulare
|
||||
|
||||
Ziel: Klare, implementierbare Regeln, wann wir ein Edit als AlertDialog, als dedizierten Fullscreen oder als Sliding Panel (Modal Bottom/Side Sheet) umsetzen. Grundlage: Navigation V3, High‑Density Desktop UX, Offline‑First.
|
||||
|
||||
Leitsatz: Kontext bewahren, kognitive Last minimieren, sichere Eingaben (Undo/Cancel) bevorzugen.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR — Entscheidungsmatrix
|
||||
|
||||
- AlertDialog (modal, klein)
|
||||
- Felder: ≤ 3 (einfache Felder: Text, Toggle, Single Select)
|
||||
- Keine abhängigen Validierungen/Async‑Laden
|
||||
- Sofortige Aktion, geringe Tragweite, seltene Nutzung
|
||||
- Dauer des Vorgangs < 20 s
|
||||
- Back‑Stack: kein Eintrag (Schließen kehrt zum Ursprungs‑Screen)
|
||||
|
||||
- Sliding Panel (Side/Bottom Sheet)
|
||||
- Felder: 3–8, mittlere Komplexität, evtl. Sektionen
|
||||
- Kontext muss sichtbar bleiben (Liste/Detail im Hintergrund relevant)
|
||||
- Leichte Abhängigkeiten erlaubt (z. B. abhängige Selects), klare Inline‑Validierung
|
||||
- Dauer 20–60 s
|
||||
- Back‑Stack: kein Eintrag; Reopen über denselben Trigger
|
||||
|
||||
- Fullscreen Edit (eigener Screen)
|
||||
- Felder: > 8 oder mehrere Sektionen/Steps
|
||||
- Starke Abhängigkeiten, Validierungen, asynchrone Daten (z. B. Lookup Reiter/Pferd)
|
||||
- Kritische Aktion mit größerer Tragweite (z. B. Stammdatenänderung)
|
||||
- Benötigt volle Tastatur‑Fokusstrecke, Hotkeys, Review/Preview
|
||||
- Dauer > 60 s
|
||||
- Back‑Stack: eigener Eintrag; Zurück führt sicher zurück, Unsaved‑Changes‑Guard aktiv
|
||||
|
||||
Hinweis: Auf Desktop bevorzugen wir Side Sheet (rechts) als „Kontext‑Erhalt bei mittlerer Komplexität“.
|
||||
|
||||
---
|
||||
|
||||
## Do/Don’t (Auszug)
|
||||
|
||||
- Don’t: Mehr als 3 Eingabefelder in AlertDialogs stapeln → führt zu Scrollen/Übersehen.
|
||||
- Do: Kurze Bestätigungen/Umbenennen/Flag toggeln als Dialog lösen.
|
||||
- Don’t: Async‑Suchfelder im Dialog (z. B. Reiter‑Lookup) → Side Sheet oder Fullscreen.
|
||||
- Do: Unsaved‑Changes vor Navigation abfangen (Confirm‑Dialog, kein Stack‑Eintrag für Modal/Sheet; V3‑Regel).
|
||||
|
||||
---
|
||||
|
||||
## Beispiel A — Reiter bearbeiten (Side Sheet empfohlen)
|
||||
|
||||
Kontext: Edit von Stammdaten, typ. 4–7 Felder (Name, Lizenzklasse, Verein, Notizen, aktiv). Liste/Detail im Blick behalten (Suche, Auswahl vergleichen).
|
||||
|
||||
ASCII‑Wireframe (Desktop, Right Side Sheet ~420–520 px):
|
||||
|
||||
```
|
||||
┌──────────────────────────── AppContent (z. B. Reiter‑Liste) ────────────────────────────┐┌───────────── Side Sheet ─────────────┐
|
||||
│ Suche [__________] Filter [v] ▢ ✕ ││ Reiter bearbeiten ✕ │
|
||||
│───────────────────────────────────────────────────────────────────────────────────────││──────────────────────────────────────│
|
||||
│ ▸ Mayer, Anna | Lizenz B | Verein X ││ Name [ Anna Mayer ] │
|
||||
│ ▸ König, Tom | Lizenz A | Verein Y ││ Lizenzklasse [ A v ] │
|
||||
│ ▸ … ││ Verein [ Suche… 🔎 ] │
|
||||
│ ││ Aktiv [ ✓ ] │
|
||||
│ ││ Notizen [ ............. ] │
|
||||
│ ││ │
|
||||
│ ││ ← Abbrechen Speichern → │
|
||||
└─────────────────────────────────────────────────────────────────────────────────────┘└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Interaktion:
|
||||
- Öffnen: Button „Bearbeiten“ in Zeile/Karte → Side Sheet schiebt von rechts ein.
|
||||
- Validierung inline; Verein‑Lookup als Such‑DropDown (debounced, Offline‑Cache).
|
||||
- Schließen: ESC/✕/Abbrechen; bei Änderungen Confirm‑Dialog (Unsaved‑Changes‑Guard).
|
||||
|
||||
---
|
||||
|
||||
## Beispiel B — Pferd bearbeiten (Fullscreen empfohlen)
|
||||
|
||||
Kontext: Mehr Felder und Abhängigkeiten (Name, Jahrgang, Geschlecht, Rasse, Besitzer/Verein, Registrier‑Nrn., Notizen). Teilweise Lookups, ggf. Bild.
|
||||
|
||||
ASCII‑Wireframe (Dedicated Screen):
|
||||
|
||||
```
|
||||
TopBar: ← Pferd bearbeiten [Abbrechen] [Speichern]
|
||||
Breadcrumb: Reiter & Pferde > Pferd.Detail > Edit
|
||||
|
||||
┌─ MeldestelleCard: Stammdaten ───────────────────────────────────────────────────────┐
|
||||
│ Name [ ....................... ] Jahrgang [ 20__ ] Geschlecht [v] │
|
||||
│ Rasse [ ....................... ] Farbe [ ..... ] │
|
||||
│ Registrier‑Nr. [ ....................... ] Chip‑Nr. [ ..... ] │
|
||||
└──────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─ MeldestelleCard: Zuordnung ────────────────────────────────────────────────────────┐
|
||||
│ Besitzer [ Suche Person/Verein 🔎 ] Verein [ Suche Verein 🔎 ] │
|
||||
│ Lizenzzuordnung [ None v ] (Info‑Badge zu Regeln) │
|
||||
└──────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─ Notizen ────────────────────────────────────────────────────────────────────────────┐
|
||||
│ [ Mehrzeiliges Textfeld ………………………………………… ] │
|
||||
└──────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Interaktion:
|
||||
- Eigener Screen mit vollem Tastatur‑Support, Fokus‑Reihenfolge, Hotkeys (Ctrl+S speichert).
|
||||
- Unsaved‑Changes‑Guard auf Back/Navi, Validierung vor Speichern, Fehler an Feldern.
|
||||
|
||||
---
|
||||
|
||||
## Komponenten & States (für Frontend)
|
||||
|
||||
- Reusable: `MeldestelleCard`, `SectionHeader`, `FormRow`, `PrimaryButton`, `SecondaryButton`, `StatusBadge`.
|
||||
- Validation: Inline (per Field), Summary oben optional; Disabled Save wenn kritisch.
|
||||
- Loading: Per‑Field Spinner bei Lookups; Gesamtscreen nie blockieren.
|
||||
- Accessibility: Tab‑Order, sichtbare Fokus‑Ringe, Labels neben/über Feldern (Dichte abhängig).
|
||||
|
||||
---
|
||||
|
||||
## Navigation & Back‑Stack (V3‑Konformität)
|
||||
|
||||
- Dialog/Sheet: Kein eigener Stack‑Eintrag; Schließen führt zum Ursprungs‑Screen zurück.
|
||||
- Fullscreen: Eigener Stack‑Eintrag. Deep‑Link baut synthetische Eltern auf (siehe V3).
|
||||
- Vor Navigation prüfen: Unsaved‑Changes → Confirm‑Dialog.
|
||||
|
||||
---
|
||||
|
||||
## Entscheidung als Regel (pseudocode)
|
||||
|
||||
```
|
||||
if fieldCount <= 3 and complexity == low and noAsyncLookups:
|
||||
use AlertDialog
|
||||
elif 3 < fieldCount <= 8 and complexity in {low, medium} and contextRelevant:
|
||||
use SideSheet (preferred on Desktop)
|
||||
else:
|
||||
use FullscreenEdit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Freigabe & Verbindlichkeit
|
||||
|
||||
| Kriterium | Entscheidung |
|
||||
|--------------------|---------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **Status** | **APPROVED** — verbindliche Design-Richtlinie ab 2026-04-03 |
|
||||
| **Reviewed by** | 🎨 Frontend Expert (bestätigt durch Implementierung von `ReiterProfilEditDialog` und `PferdProfilEditDialog` gemäß Side-Sheet-Muster) |
|
||||
| **Gültig für** | Alle Edit-Formulare im Meldestelle-Desktop-MVP |
|
||||
| **Ausnahmen** | Müssen explizit im jeweiligen Feature-Ticket begründet und dokumentiert werden |
|
||||
| **Nächste Review** | Bei Einführung der Web-App / PWA (andere Interaktionsparadigmen möglich) |
|
||||
|
||||
### Anwendung auf bestehende Screens (Mapping)
|
||||
|
||||
| Screen / Entity | Felder (ca.) | Async-Lookup | Empfehlung | Umgesetzt |
|
||||
|-------------------|--------------|---------------|-------------|------------------------------------------------|
|
||||
| Veranstalter Edit | 4–5 | Nein | Side Sheet | ✅ (Dialog) |
|
||||
| Reiter Edit | 5–7 | Ja (Verein) | Side Sheet | ✅ |
|
||||
| Pferd Edit | 8–10 | Ja (Besitzer) | Fullscreen | ✅ (Dialog — Migration zu Fullscreen empfohlen) |
|
||||
| Verein Edit | 3–4 | Nein | Side Sheet | ⬜ offen |
|
||||
| Funktionär Edit | 3–4 | Nein | Side Sheet | ⬜ offen |
|
||||
| Bewerb Edit | 6–8 | Ja | Side Sheet | ⬜ offen |
|
||||
| Turnier Edit | 4–5 | Nein | Side Sheet | ⬜ offen |
|
||||
| Abteilung Edit | 3–4 | Nein | AlertDialog | ⬜ offen |
|
||||
|
||||
> **Hinweis Pferd:** Der bestehende `PferdProfilEditDialog` überschreitet mit 8–10 Feldern und Async-Lookups die
|
||||
> Dialog-Grenze. Migration zu Fullscreen-Edit ist für Sprint C-1 vorgesehen.
|
||||
Reference in New Issue
Block a user