Kairo-Jinkendo/docs/sprints/Sprint0_AP0_6b_Completion_Report_v0.1.md

AP0.6b – Abschlussbericht Jinkendo UX/PWA Remediation

Version: v0.1
Datum: 2026-07-05
Frontend-Version: 0.6.1-ap0.6b
Branch: develop

---

1. Ausgangsproblem

AP0.6 lieferte die fachliche Workspace-UX (Vorhaben, Maßnahmen, Widget-Registry), aber die GUI war nicht abnahmefähig:

• Generisches Blau-Theme, keine Jinkendo-Familienanmutung
• Keine konsistente App Shell (Navigation, Header, Kontext)
• Fehlende oder unzureichende responsive Umschaltung Desktop/Mobile
• Keine PWA-Grundlagen (Manifest, Icons, Viewport-Meta)
• Uneinheitliche Karten, Badges, Formulare und Zustände (Loading/Error/Empty)
• Verstreute Styles in workspace.css ohne Design-Tokens

AP0.6b ist eine Remediation ohne neue Fachfeatures.

---

2. Umgesetzte Dateien

Neu

Datei	Zweck
frontend/src/styles/tokens.css	Jinkendo Design-Tokens (--jk-*)
frontend/src/styles/shell.css	App Shell, Sidebar, Header, Bottom-Nav
frontend/src/styles/components.css	Cards, Buttons, Badges, Forms, States
frontend/src/styles/pages.css	Seiten-spezifische Ergänzungen
frontend/src/config/appNav.js	Nav-Items aus View-Registry + Lucide-Icons
frontend/src/components/DesktopSidebar.jsx	Desktop-Navigation (≥1024px)
frontend/src/components/BottomNav.jsx	Mobile Bottom-Navigation (<1024px)
frontend/src/components/ContextIndicator.jsx	Tenant-/Actor-Kontext
frontend/src/components/WidgetCard.jsx	Einheitliche Widget-Karten
frontend/src/pages/MyActionsPage.jsx	Route /my-actions
frontend/public/manifest.webmanifest	PWA-Manifest
frontend/public/icons/kairo-icon.svg	App-Icon (Platzhalter, Jinkendo-Grün)

Geändert

• frontend/index.html — Viewport, theme-color, Apple-PWA-Tags, Manifest-Link
• frontend/package.json — lucide-react, Version 0.6.1-ap0.6b
• frontend/src/app.css — zentraler CSS-Import
• frontend/src/layout/AppLayout.jsx — vollständige Shell
• frontend/src/registry/viewRegistry.js — View kairo.my_actions, Nav-Metadaten
• frontend/src/registry/registry.test.js — erweiterte Registry-/Nav-Tests
• Alle Widgets, Pages, Forms, ActionList, AuthPanel, ErrorState

Entfernt

• frontend/src/styles/workspace.css — ersetzt durch strukturierte Stylesheets

Backend

Keine Änderungen (wie gefordert).

---

3. App Shell

Struktur gemäß Auftrag:

AppShell (.app-shell)
  DesktopSidebar          — nur ≥1024px
  app-shell__column
    Header (.app-header--mobile) — Brand + ContextIndicator
    MainContent (.app-main > .app-page)
    BottomNav               — nur <1024px

• Produktname Kairo, Family-Bezug „Jinkendo Program Director“
• Tenant-/Actor-Kontext in Sidebar (Desktop) und kompakt im Mobile-Header
• Logout in der Sidebar
• Content max-width --content-max: 1120px, zentriert

---

4. Jinkendo Look & Feel

Design-Tokens in tokens.css, abgeleitet von Mitai/Shinkan:

Token	Wert (Light)	Herkunft
--jk-primary	#1D9E75	Mitai/Shinkan Accent-Grün
--jk-bg	#f6f5f0	Warme Neutralfläche (Family)
--jk-surface	#ffffff	Karten/Header
--jk-text / --jk-text-muted	#1c1b18 / #5a5955	Lesbare Hierarchie
--jk-radius-card	12px	Konsistente Karten
--jk-shadow-card	dezenter Schatten	Kein Material-Overload

Dark Mode via prefers-color-scheme: dark.

Komponenten: .card, .btn, .badge, .form-*, .state-empty, .state-error, .state-loading — einheitlich in components.css.

---

5. Responsive Desktop/Mobile

Breakpoints (Family-Pattern, Shinkan/Mitai-kompatibel):

Breakpoint	Verhalten
≥1024px	Desktop-Sidebar links, kein Bottom-Nav, Mobile-Header ausgeblendet
768–1023px	Mobile-Layout: Header + Bottom-Nav, Karten stapeln
≤767px	Kompakte Typo, volle Breite, safe-area-insets

Zusätzlich @media (max-width: 768px) in components.css für Formulare und Listen.

Prüfung (manuell, DevTools)

Viewport	Ergebnis
1440×900	Sidebar + 2-spaltiges Widget-Grid, keine horizontale Scrollbar
1024×768	Umschaltung auf Mobile-Shell, Bottom-Nav sichtbar
390×844	Karten gestapelt, Buttons ≥44px Touch, Formulare nutzbar
844×390 (Landscape)	Header + Bottom-Nav mit safe-area, Inhalt scrollbar vertikal

Kein Playwright im Sprint — Checkliste in README dokumentiert.

---

6. PWA-Grundlagen

Anforderung	Status
manifest.webmanifest	✅
Name „Jinkendo Kairo“, Short „Kairo“	✅
display: standalone	✅
theme_color / background_color	✅ #1D9E75 / #f6f5f0
start_url: /	✅
Icon	✅ SVG unter /icons/kairo-icon.svg
Viewport meta + viewport-fit=cover	✅
Apple Web App Tags	✅
Service Worker	❌ bewusst nicht — analog Shinkan; Installierbarkeit über Manifest, kein Offline-Caching in Sprint 0

Build kopiert Manifest und Icons nach dist/.

---

7. Navigation

Zentral über viewRegistry.js + config/appNav.js:

Route	Label	Nav
/workspace	Workspace	✅
/initiatives (+ Detail)	Vorhaben	✅ (Detail via matchPrefix)
/my-actions	Meine Maßnahmen	✅ neu

• Aktive Route: CSS-Klassen is-active + Prefix-Matching für Vorhaben-Detail
• Desktop: permanente Sidebar
• Mobile: Bottom-Nav mit Icons (lucide-react)
• Keine doppelte Navigation

---

8. Widget/View Registry

Unverändert im Prinzip (frontend-only):

• Widgets: widgetRegistry.js — 4 Workspace-Widgets, Capability-Filter
• Views: viewRegistry.js — +1 View kairo.my_actions, Nav-Metadaten
• Keine Backend-Registry, kein Drag & Drop, keine Layout-Persistenz

Tests: 6 Registry-/Nav-Tests in registry.test.js.

---

9. Workspace UX

Alle AP0.6-Widgets/Pages auf WidgetCard + Family-Styles umgestellt:

• Meine offenen Maßnahmen, Aktive Vorhaben, Blockierte Maßnahmen, Tenant-Kontext
• Vorhabenliste, Vorhaben-Detail, Maßnahmenliste, Formulare
• Einheitliche Card-Header, primäre/sekundäre Buttons
• StatusBadge / PriorityBadge mit Textlabels (nicht nur Farbe)
• Loading, Error (mit Retry), Empty States gestaltet

---

10. Accessibility / Bedienbarkeit

• Formular-Labels auf allen Inputs
• Buttons mit sichtbarem Text (Nav mit Icon + Label/shortLabel)
• :focus-visible Outline auf interaktiven Elementen
• Badges mit Text + Farbe
• Touch-Ziele Bottom-Nav ≥48px Höhe
• Kontrast Primary auf Weiß: akzeptabel für Sprint-0-Basis

---

11. Tests und Smoke-Tests

cd frontend && npm run test && npm run build

Suite	Ergebnis
badges.test.jsx	3/3 ✅
registry.test.js	6/6 ✅
vite build	✅

Backend unverändert — bestehende pytest-Suite nicht betroffen.

---

12. Übernommene Muster aus Mitai

• Accent-Grün #1D9E75, warme Hintergründe
• Dashboard-/Card-Struktur mit dezentem Schatten
• Widget-Karten mit Header + Inhalt
• Mobile-first mit Bottom-Navigation
• CSS-Variablen für Family-Tokens
• 100dvh + safe-area für Mobile Shell

Nicht übernommen: Gesundheits-/Tracking-Karten, Domänenlogik, Mitai-spezifische Widgets.

---

13. Übernommene Muster aus Shinkan

• Desktop-Sidebar ab 1024px
• Sachlicher Header mit Produkt-/Kontextzeile
• Mandanten-/Actor-Kontext sichtbar
• Klare Admin-ähnliche Navigation (vereinfacht auf 3 Hauptpunkte)
• Robuste Seitenstruktur ohne horizontales Overflow

Nicht übernommen: Trainings-/Vereinslogik, Übungskatalog, Shinkan-Workarounds.

---

14. Bewusst nicht umgesetzte Punkte

• Service Worker / Offline-Caching
• Push Notifications, Background Sync
• Playwright Viewport-Tests
• PNG-Icon-Set (nur SVG-Platzhalter)
• GET /api/actors (weiter AP0.7)
• Admin-Konsole, Drag & Drop, User-Dashboard-Konfiguration
• Neues UI-Framework

---

15. Noch offene UX-Mängel

• Actor-Zuweisung nur Human Actor (API-Lücke)
• Kein dediziertes Tablet-Split-Layout (nutzt Mobile-Shell ab <1024px)
• SVG-Icon nicht maskable-optimiert für alle Android-Launcher
• Kein explizites Light/Dark-Toggle (nur System-Preference)
• Vorhaben-Detail auf sehr schmalen Screens: lange Titel können umbrechen — lesbar, aber nicht perfekt

---

16. Empfehlung für den nächsten Schritt

1. AP0.7: GET /api/actors + ActorSelect mit echter Liste
2. Design: PNG-Icons (192/512) für breitere PWA-Kompatibilität
3. Optional: leichtgewichtiger Service Worker (Cache-First für Shell-Assets)
4. QA: Playwright-Smoke mit Viewports 1440/1024/390 in CI
5. Danach Sprint-1-Fachscope gemäß Product Spec (nicht vorziehen)

---

Abnahme-Checkliste AP0.6b

Kriterium	Erfüllt
Nicht mehr generische Demo-App	✅
Jinkendo-Produkt erkennbar	✅
Desktop brauchbar (1440px)	✅ manuell
Mobile brauchbar (390px)	✅ manuell
Desktop/Mobile-Umschaltung	✅ @1024px
PWA-Manifest korrekt	✅
Konsistente Karten/Widgets	✅
Klare Navigation	✅
Status/Priorität visuell sauber	✅
Loading/Error/Empty States	✅
Registry klein und nutzbar	✅
Keine neuen Fachfeatures	✅
Tests grün	✅ 9 Frontend-Tests