MABEA/arbeitskacheln/22_ui_redesign_v2.md

Epic 22 — UI-Redesign Runde 2 (Patterns aus ai-coding-starter-kit-v2)

Details zu UI2-001 … UI2-010, alle offen/ungeplant (Backlog-Planung, bewusst noch nicht gestartet). Ausgangspunkt: Subagenten-Analyse von gitea.perlbach24.de/scripte/ai-coding-starter-kit-v2 (2026-09-08), vertieft am 2026-09-09, reines shadcn/ui-Komponenten-Skelett (Vite/React/TS, Tailwind v3, Radix, react-hook-form+zod). Kein Framework-Wechsel, kein Neubau — Epic 20 (UI-001..008) bleibt Grundlage, hier werden zusätzliche, im Code konkret nachgewiesene Lücken geschlossen. Kein kompletter Frontend-Neubau — bewusste Entscheidung, siehe Chat 2026-09-08.

---

UI2-001 — Granularere Design-Tokens (Card/Popover/Sidebar)

• Ziel: Card-/Popover-/Sidebar-Hintergründe über eigene Tokens statt generischem --color-primary/bg-white.
• Beschreibung: --color-card, --color-card-foreground, --color-popover etc. in frontend/src/styles/global/tokens.css ergänzen (Light+Dark), bestehende Komponenten schrittweise umstellen.
• Benutzerwert: Konsistentere Flächenhierarchie, einfacheres Dark-Mode-Feintuning.
• Abhängigkeiten: UI-001 (bereits erledigt)
• Backend: keins
• Frontend: styles/global/tokens.css
• Rechte: keine Änderung
• Akzeptanzkriterien: neue Tokens vorhanden, mind. Card-Komponente nutzt sie statt Hardcoded-Werten.
• Tests: keine (reines Styling).
• ACHTUNG (QA-Review 2026-09-09, siehe CLAUDE.md „Wichtige Stolperfallen"): Neue Token-Namen in tokens.css dürfen NIEMALS denselben Namen wie ein Tailwind-@theme-Token bekommen — führte in diesem Projekt bereits zweimal zu app-weit kaputten Farben (zirkuläre Custom-Properties, guaranteed-invalid value). Vor dem Anlegen von --color-card etc. gegen tailwind.css/@theme prüfen, keine Namenskollision. Diese Warnung gilt für UI2-001 als Basis genauso wie für UI2-010 (Dark-Mode-Vorbereitung), die direkt darauf aufbaut.
• DoD: offen.

UI2-002 — AdminPage Sidebar/Sheet-Umschaltung

• Ziel: Touch-taugliche Navigation für AdminPage-Tabs — Desktop Sidebar, Mobile Sheet-Overlay statt aktuellem Tab-Leisten-Umbruch.
• Beschreibung: Pattern aus Starter-Kit (useIsMobile-Hook + Radix-Dialog-Sheet), MABEA hat bereits useIsDesktop — Umschaltung analog, kein natives Drag&Drop.
• Benutzerwert: Bessere Bedienbarkeit auf Tablet im Feld.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: AdminPage.tsx, ggf. neue components/ui/sheet.tsx
• Mobile: Priorität — Zielgerät Tablet
• Rechte: keine Änderung
• Akzeptanzkriterien: AdminPage-Tabs auf schmalem Viewport über Sheet erreichbar, bestehende Tab-Inhalte unverändert.
• Tests: keine neuen (reines UI/Routing).
• DoD: offen.

UI2-003 — Formular-Feld-Komposition

• Ziel: Wiederverwendbarer Feld-Baustein (Label+Input+Fehlermeldung) statt individueller State-Verdrahtung pro Feld in Formularen.
• Beschreibung: Leichtgewichtiges FormField-Pattern (kein react-hook-form/zod nötig, MABEA nutzt bereits einfache useState-Formulare — nur Layout/Fehler- Darstellung vereinheitlichen), zuerst in ObjektAnlegenFormular.tsx und ObjekttypSection.tsx angewendet.
• Benutzerwert: Einheitliche Fehlerdarstellung, weniger Boilerplate bei neuen Formularen.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: neue components/ui/form-field.tsx, ObjektAnlegenFormular.tsx, ObjekttypSection.tsx darauf umgestellt
• Rechte: keine Änderung
• Akzeptanzkriterien: beide Formulare nutzen den neuen Baustein, Verhalten unverändert.
• Tests: bestehende Vitest-Tests bleiben grün.
• DoD: offen.
• Referenz (vertiefte Starter-Kit-Analyse 2026-09-09): form.tsx im Quell-Repo verdrahtet a11y konkret statt nur visuell — FormLabel wird bei Fehler rot, FormControl setzt aria-invalid, FormMessage nur bei vorhandenem Error gerendert, aria-describedby verlinkt zur Fehlermeldung. 1:1 mit MABEAs useState-Ansatz nachbaubar (kein react-hook-form/Context nötig) — sollte in den FormField-Baustein mit einfließen, nicht nur reines Layout.

UI2-009 — Formular-Fehlerzustand-Verdrahtung (a11y, ergänzt UI2-003)

• Ziel: aria-invalid/aria-describedby/Fehlerfarbe systematisch statt nur visuell.
• Beschreibung: siehe Referenz-Absatz bei UI2-003 — kein eigenständiges Feature, sondern eine konkrete Ausbaustufe von UI2-003, aus organisatorischen Gründen als eigene Kachel geführt (klar abhakbar, statt in UI2-003 zu verschwimmen).
• Benutzerwert: Bessere Screenreader-/Assistive-Tech-Unterstützung, klarere Fehlererkennung bei schlechtem Licht/Handschuhen (Fehlerfarbe + Text statt nur Farbe).
• Abhängigkeiten: UI2-003
• Backend: keins
• Frontend: components/ui/form-field.tsx
• Rechte: keine Änderung
• Akzeptanzkriterien: Fehlerfeld hat aria-invalid="true" und aria-describedby auf die Fehlermeldung, kein Verlust bestehender Funktionalität.
• Tests: keine neuen (reines Markup/Attribut).
• DoD: offen.

UI2-004 — Skeleton-Loading für Dashboard-Kacheln

• Ziel: Skeleton-Platzhalter statt Spinner/nichts beim Nachladen von Dashboard-Kacheln.
• Beschreibung: Einfache animate-pulse-Komponente (components/ui/skeleton.tsx), in Dashboard-Tiles während Ladezustand eingesetzt.
• Benutzerwert: Wahrgenommene Ladezeit sinkt, weniger Layout-Sprung.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: neue components/ui/skeleton.tsx, Dashboard-Tiles (*Tile.tsx)
• Rechte: keine Änderung
• Akzeptanzkriterien: sichtbarer Skeleton-Zustand vor Dateneintreffen, kein Layout-Sprung beim Einblenden der echten Daten.
• Tests: keine neuen.
• DoD: offen.

UI2-005 — Scrollbarer Table-Wrapper für Materiallisten

• Ziel: Materiallisten/Kontroll-Tabellen brechen auf schmalem Tablet-Viewport nicht das Seiten-Layout, sondern scrollen innerhalb eines eigenen Containers.
• Beschreibung: Gemeinsamer Table-Wrapper (overflow-x: auto) statt Ad-hoc-Lösung je Seite, zuerst in KontrollPage.tsx-Listen angewendet.
• Benutzerwert: Kein horizontales Seiten-Scrollen mehr auf kleinen Screens.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: KontrollPage.tsx bzw. betroffene Listen-Komponenten
• Mobile: Priorität — Tablet-Ziel
• Rechte: keine Änderung
• Akzeptanzkriterien: Tabelle scrollt intern, Seite selbst nie horizontal.
• Tests: keine neuen.
• DoD: offen.

UI2-006 — Toast/Benachrichtigungskomponente

• Ziel: Aktionsfeedback (gespeichert/Fehler/Sync-Status) ohne Modal-Unterbrechung.
• Beschreibung: Leichtgewichtige Toast-Komponente (kein sonner-Paket-Zwang, Pattern nachbaubar: Portal + Auto-Dismiss-Timer + Stapel-Anzeige bei mehreren gleichzeitigen Meldungen).
• Benutzerwert: Häufige kleine Aktionen (Kontrolle bestätigen, Position speichern) unterbrechen den Arbeitsfluss nicht mit einem Wegklick-Dialog.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: neue components/ui/toast.tsx, zentrale Toast-Provider-Einbindung
• Mobile: Dauer konfigurierbar halten (bei schlechtem Netz/langsamer Interaktion reicht kurze Anzeigedauer sonst nicht)
• Rechte: keine Änderung
• Akzeptanzkriterien: Toast erscheint bei Erfolg/Fehler, verschwindet automatisch, mehrere gleichzeitige Toasts stapeln statt überschreiben.
• Tests: keine neuen (reines UI).
• DoD: offen.

UI2-007 — Dialog/AlertDialog-Baustein für Bestätigungen

• Ziel: Einheitliche Bestätigungsdialoge (z.B. „Material löschen?") statt nativem window.confirm().
• Beschreibung: Radix-artiges Dialog-Pattern mit Fokus-Trap und Escape-zum-Schließen, große Touch-taugliche Buttons.
• Benutzerwert: Konsistentes Aussehen statt Browser-natives, unstyliertes confirm()-Popup; Fokus-Trap verhindert versehentliches Wegtippen auf Tablet.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: neue components/ui/dialog.tsx/alert-dialog.tsx, schrittweise bestehende confirm()-Aufrufe ersetzen
• Mobile: Priorität — Fokus-Trap/Escape wichtig bei externer Tastatur an Tablets mit Kartenleser
• Rechte: keine Änderung
• Akzeptanzkriterien: mind. eine bestehende confirm()-Stelle ersetzt, Verhalten (Bestätigen/Abbrechen) unverändert.
• Tests: bestehende Tests an der ersetzten Stelle bleiben grün.
• DoD: offen.

UI2-008 — Badge-Komponente für Status-Chips

• Ziel: Bestandsstatus/Ablaufdatum-Kennzeichnung visuell einheitlich statt Ad-hoc-Farbklassen je Stelle.
• Beschreibung: Kleine Badge-Komponente mit Varianten (ok/warnung/kritisch/ abgelaufen), nutzt UI2-001-Tokens.
• Benutzerwert: Schneller visueller Überblick in Listen/Kacheln, geringer Aufwand.
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: neue components/ui/badge.tsx, Einsatz in Materiallisten/Dashboard
• Rechte: keine Änderung
• Akzeptanzkriterien: mind. eine Liste (z.B. Ablaufdatum-Übersicht) nutzt Badge statt Inline-Farbklassen.
• Tests: keine neuen.
• DoD: offen.

UI2-010 — Dark-Mode-fähige Token-Struktur (Vorbereitung, kein Umschalter)

• Ziel: UI2-001-Tokens so anlegen, dass ein späterer Dark-Mode-Umschalter keinen Umbau der Token-Struktur erfordert — auch wenn der Umschalter selbst kein aktueller Bedarf ist (Tablet im Feld, meist Tageslicht).
• Beschreibung: Je Token aus UI2-001 (--color-card, --color-popover, etc.) zusätzlich einen .dark/[data-theme=dark]-Override-Block in tokens.css vorsehen, auch wenn er anfangs mit denselben Werten wie Light gefüllt ist.
• Benutzerwert: Kein nachträglicher Breaking-Umbau, falls Dark Mode später doch gebraucht wird (z.B. Nachteinsätze).
• Abhängigkeiten: UI2-001
• Backend: keins
• Frontend: styles/global/tokens.css
• Rechte: keine Änderung
• Akzeptanzkriterien: jeder neue UI2-001-Token hat einen Dark-Override-Platzhalter, keine funktionale Änderung im Light-Modus.
• Tests: keine neuen (reines CSS).
• DoD: offen. Achtung MABEA-spezifisch: Cascade-Layer-Struktur beachten (global-css-Layer niedriger als Tailwind-Layer, siehe CLAUDE.md „Wichtige Stolperfallen") — Dark-Override darf keine Layer-Kollision mit Tailwinds @theme erzeugen, insbesondere keinen Tailwind-Token-Namen doppelt vergeben.

---

Reihenfolge (empfohlen, nicht blockierend innerhalb der Gruppen): UI2-001 zuerst (Basis für alle). Danach zwei unabhängige Gruppen: UI2-002/003+009/010 (Struktur/ Formulare/Tokens) und UI2-004/005/006/007/008 (einzelne UI-Bausteine) — Reihenfolge innerhalb der Gruppen nach Nutzerpriorität.

Nicht-Ziele: kein Wechsel auf react-hook-form/zod/Radix, kein kompletter Frontend-Neubau, keine Breaking Changes an bestehender Fachlogik/API. Bewusst NICHT übernommen (Overkill/Desktop-lastig für ein Fach-Tool, siehe vertiefte Analyse 2026-09-09): Command-Palette/Combobox, Navigation-Menu, Accordion/Collapsible, Avatar, Pagination, Tooltip (auf Touch unzuverlässig), Sidebar-Zusatzfeatures wie Cookie-Persistenz/Keyboard-Shortcuts.

Referenzen

Subagenten-Analyse ai-coding-starter-kit-v2, Chat 2026-09-08 (kein Frontend-Neubau, Patterns schrittweise als Kacheln übernehmen). Vertiefte Analyse derselben Quelle 2026-09-09 (vollständige Komponentenliste, a11y-Patterns, Dark-Mode-Struktur) ergab UI2-006..010.