--- stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14] status: 'complete' completedAt: '2026-05-25' inputDocuments: - prds/prd-projectmanagement-2026-05-25/prd.md - prds/prd-projectmanagement-2026-05-25/addendum.md - prds/prd-projectmanagement-2026-05-25/.decision-log.md - prds/prd-projectmanagement-2026-05-25/inputs/unternehmens-cockpit.html - prds/prd-projectmanagement-2026-05-25/inputs/ToolCTRL_Projektmanagement-Leitfaden_v3.0.pdf - prds/prd-projectmanagement-2026-05-25/extract-prototype-html.md - architecture.md workflowType: 'ux-design' project_name: 'ToolCTRL Unternehmens-Cockpit' user_name: 'Dejancosic' date: '2026-05-25' binding_frame: 'ToolCTRL Projektmanagement-Leitfaden v3.0 (Mai 2026)' prd_status: 'final' architecture_status: 'complete' --- # UX Design Specification — ToolCTRL Unternehmens-Cockpit **Author:** Dejancosic **Date:** 2026-05-25 > Dieses Dokument legt das Visual Design, die Komponenten-Bibliothek, die Layouts und die Mikrocopy fest. Es operationalisiert die UX-Anforderungen aus PRD (NFR-8, NFR-9, NFR-12/13) und liefert die Brand-Token-Werte (OQ-2), die in `tailwind.config.ts` einfließen. --- --- ## Executive Summary ### Project Vision Das **ToolCTRL Unternehmens-Cockpit** ist ein internes Web-Werkzeug, das jeden Werktag in unter 60 Sekunden sichtbar macht, woran das Team arbeitet, was klemmt und welche Projekte aus dem Plan laufen. Es operationalisiert den Projektmanagement-Leitfaden v3.0 als drittes Werkzeug neben Plane (Arbeit) und Outline (Gedächtnis) und ist die Antwort auf das wiederkehrende „Wir starten viel, wir bekommen nichts fertig"-Muster. UX-Aufgabe: Eine Anwendung schaffen, die sich **unaufgeregt, lesbar und schnell** anfühlt — kein „Tool, das einen checkt", sondern ein gemeinsamer Spiegel des Tages. Die Anwendung muss Disziplin erzeugen, ohne Lästergefühl zu produzieren (PRD CM3). ### Target Users Alle ToolCTRL-Mitarbeiter (6-15 Personen), aufgeteilt in zwei Sichtebenen: **Leitfaden-Rollen (pro Projekt):** - **P1 Projektverantwortliche/r** — pflegt Ampelstatus und Trend, moderiert Jourfixe, achtet auf Pflicht-Minimum. - **P2 Team** — schreibt Tagesupdates, setzt Blocker, pflegt Meilenstein-Status. - **P3 Product Owner** — Lese-Schwerpunkt, Priorisierungs-Diskussionen. - **P4 Auftraggeber** (intern = Geschäftsführung) — Lese-Hauptnutzer für Puls und Pflicht-Minimum. **Querschnittsrollen (alle Mitarbeiter):** - **Q1 Entwickler** — Updates mit Projektbezug, viele Bezugswechsel pro Tag, möchte unter 30 s pro Touchpoint. - **Q2 Sales** — lebt im Kanban, verschiebt 5–10 Deals pro Woche, schreibt Updates ungern wenn das System träge ist. - **Q3 Marketing** — pflegt Lead-Funnel + Kampagnen, weniger täglicher Fortschritt → das System darf „heute kein Fortschritt, aber dran"-Updates nicht verteufeln. - **Q4 Design / Q5 Buchhaltung** — schreiben „Allgemein"-Updates, brauchen keine Projektpflicht. Stand der Nutzer-Reife: hoch tech-affin (alle haben ein Authentik-SSO-Login bereits gewohnheitsmäßig), Desktop-First-Nutzer, Deutsch als Arbeitssprache. ### Key Design Challenges 1. **Zwei Touchpoints pro Tag, beide unter 60 Sekunden.** Morgen-Einstempeln + ToDos und Abend-Reflexion müssen *sehr* schnell zu erledigen sein — sonst erodiert die Disziplinmechanik (CM1a/CM1b). 2. **Sichtbarkeitsmodell pre/post Publikation.** Innerhalb des Tages: ToDos sind privat, nur „eingestempelt: ja/nein" für Kollegen sichtbar. Ab nächstem Werktagsmorgen: konsolidierter Eintrag wird öffentlich. Die UI muss diese Privatheit ohne Erklärungstext verständlich machen. 3. **Pflicht-Minimum als Erstklass-Information.** Die 6 Leitfaden-Pflicht-Punkte pro Projekt müssen prominent und auf einen Blick lesbar sein — sie sind die Brücke zwischen Cockpit und Leitfaden, nicht eine Detailseite. 4. **Drei strukturell unterschiedliche Bereichs-Details.** Entwicklung (Projekte+Meilensteine), Vertrieb (Kanban+gewichtete Pipeline), Marketing (Lead-Funnel+Kampagnen) sehen visuell anders aus, gehören aber in dasselbe Layout-Skelett — das verlangt eine konsistente Schale mit feature-spezifischem Inhalt. 5. **Drei Status-Ampelfarben in einer monochrom-geprägten Brand.** Brand ist schwarz/weiß; Ampel braucht Grün/Gelb/Rot semantisch. Sie müssen funktional erkennbar bleiben, ohne die Brand-Sprache zu sprengen. 6. **Voice & Tone als Disziplin-Anker.** Locker und direkt (`„Stark."`, `„Wie läuft es?"`) — UI-Mikrocopy ist Pflicht-Vehikel, kein Beiwerk. ### Design Opportunities 1. **Ein einzelner „Puls"-Bildschirm als tägliche Heimat.** Wenn der Puls in einem Blick die Antwort auf „Was muss ich heute wissen?" liefert, gewinnt das Cockpit täglich. Konsequente Information-Density ohne Overload. 2. **„Mein heute" als persönliche Tagesoase.** Eine ruhige, private Sicht, die der einzige Ort ist, wo ToDos heute bearbeitbar sind — visuell von der öffentlichen Puls-Sicht trennen. 3. **Reflexion als geführter, kurzer Flow.** Statt eines Formulars: eine schrittweise Reflexion (ToDos abhaken → Freitext → Ampel + Trend → fertig), die sich wie ein Tagesabschluss anfühlt, nicht wie ein Pflicht-Formular. 4. **Markenmäßige Reduktion als Feature.** Brand ist monochrom — das passt zu „weniger ablenken, mehr Übersicht". Statt das als Limit zu sehen, ist es ein Wettbewerbsvorteil gegenüber bunten SaaS-Tools. 5. **Der `^`-Caret als wiederkehrender Mikro-Anker.** Das macOS-Ctrl-Symbol als kleines Brand-Element (im Logo, in Tab-Indikatoren, in Bestätigungs-Toasts) zieht eine subtile Identitätslinie durch die App. 6. **Sichtbar gemachte Streaks als sozialer Motivator.** Wer 14 Werktage in Folge eingestempelt ist, sieht das prominent im Profil und im „Heute fehlt"-Modul. Sozialer Druck ohne Public Shaming. --- ## Core User Experience ### Defining Experience Die Kern-Erfahrung des Cockpits ist der **Tagesrhythmus**: Eine Person stempelt morgens ein und definiert ihre ToDos für den Tag; am Abend reflektiert sie, hakt ab, setzt Ampel und Trend; am nächsten Werktagsmorgen sehen Kollegen den konsolidierten Vortags-Eintrag. Diese Schleife wiederholt sich jeden Werktag und ist der zentrale Wertbeitrag des Produkts. Alles andere — Puls, Bereichs-Details, Pflicht-Minimum, Blocker — ist die Auswertungs- und Übersichts-Schicht über dieser täglichen Routine. Der zweite zentrale Moment ist der **Jourfixe-Puls am Dienstag 11:00**: Die Übersichtsseite wird vom PM (P1/P4) als Hauptbildschirm aufgerufen, alle drei Bereiche werden in einer scroll-bereiten Sicht durchgegangen, rote/gelbe Projekte und offene Blocker werden direkt angesprochen. ### Platform Strategy - **Plattform:** Web-Anwendung (SPA), self-hosted unter `cockpit.tool-ctrl.de`. - **Primärer Input:** Maus + Tastatur. Touch-Geräte sind nicht primär, müssen aber das Tagesupdate-Schreiben nicht blockieren. - **Bildschirmgröße:** Desktop-first (≥ 1280 px breit). Mobile/Tablet: lesbar (responsive Layout-Grid), nicht primär schreibbar (PRD NFR-10). - **Offline:** keine Offline-Fähigkeit im MVP. Cockpit ist immer online (interne Infrastruktur). - **Geräte-Capabilities:** kein Spezial-Hardware, kein Push, keine Kamera. Der Browser ist die einzige Bühne. - **Browser-Support:** moderne Evergreen-Browser (Chrome, Firefox, Safari der letzten 2 Major-Versionen). Kein IE11. ### Effortless Interactions Diese Dinge müssen sich **mühelos** anfühlen — wenn hier Reibung entsteht, scheitert das ganze Produkt: - **Einstempeln** — Person klickt einen großen CTA auf der Puls-Seite, Modal öffnet sich mit Bereichs-Default und leerer ToDo-Liste. Tippen → Enter → nächster ToDo → Enter. Speichern mit Cmd/Ctrl+S oder Enter auf leerer Zeile. Ziel: ≤ 30 Sekunden für 3-5 ToDos. - **ToDo abhaken in der Reflexion** — Single-Click auf die Checkbox neben jedem ToDo. Optionaler Verwerf-Modus (Rechtsklick oder Hover-Button) für „verworfen mit Grund". - **Ampel + Trend setzen** — drei große farbige Buttons (Grün/Gelb/Rot), nicht ein winziges Dropdown. Trend als drei Pfeil-Buttons (↗︎ → ↘︎). - **Blocker erfassen** — entweder inline beim Reflektieren (Toggle „Blocker?") oder über ein „+ Neuer Blocker"-Button im Header, der von jeder Seite aus erreichbar ist. - **Projekt wechseln** — Bereichs-Detail hat eine Projekt-Rail oben mit Klick-zum-Wechsel; Projekt-Detail hat „← Bereich" als Breadcrumb. - **Login** — automatischer Authentik-Redirect; nach erfolgreichem Login landet die Person auf der Puls-Seite. Kein Login-Formular im Cockpit selbst. ### Critical Success Moments 1. **Morgen-Eintritt:** Person öffnet das Cockpit (oder folgt einem Reminder-Link). Die Puls-Seite zeigt prominent oben „Du hast heute noch nicht gepingt." mit einem großen primären Button. Die Person ist in 3 Klicks im Einstempeln-Flow. **Failure-Mode:** Diesen Hinweis übersehen oder das Formular träge bedienen — die Streak wird gefährdet. 2. **Reflexions-Moment am Abend:** Ab 17:00 Uhr erscheint im Header ein dezenter Hinweis „Du hast heute noch nicht reflektiert." Die Person klickt, sieht die eigene ToDo-Liste vom Morgen wieder, hakt ab, schreibt 2–3 Sätze, setzt Ampel. **Failure-Mode:** Die Reflexion fühlt sich wie ein Bürokratie-Akt an — dann wird sie ausgelassen und der Tag bleibt „halb". 3. **Jourfixe-Aufruf am Dienstag:** PM öffnet Puls, scrollt einmal von oben nach unten, hat in 60 Sekunden Übersicht über alle Bereiche, Blocker und Pflicht-Minimum-Verstöße. **Failure-Mode:** Wenn Informationen verstreut auf mehreren Tabs liegen, wird die Jourfixe ineffizient. 4. **Nächster-Morgen-Reveal:** Person öffnet das Cockpit am Tag X+1, sieht im Area-Feed die konsolidierten Vortags-Einträge der Kollegen — ToDos, abgehakte Status, Reflexion, Ampel. Das schafft das Gefühl gemeinsamer Sichtbarkeit. **Failure-Mode:** Wenn die Publikation um 00:05 fehlschlägt (Cron-Job), erscheint der Tag X+1 leer — Vertrauen ins Cockpit erodiert. 5. **Pflicht-Minimum-Erstmal-Sichtbar-Werden:** Bei Projekt-Neuanlage wird in der Projekt-Detail-Sicht die 6-Punkte-Checkliste angezeigt; offene Punkte sind sofort visuell als „nicht erfüllt" markiert. **Failure-Mode:** Wenn die Checkliste versteckt in einem Tab liegt, vergessen Verantwortliche, sie zu pflegen — der zentrale Leitfaden-Hebel verschwindet. ### Experience Principles 1. **Disziplin durch Sichtbarkeit, nicht durch Reibung.** Das Cockpit erzwingt nichts mit roten Bannern oder Pflicht-Pop-ups. Es macht nur sichtbar, wer und welches Projekt fehlt. Sichtbarkeit ist der Hebel, nicht Druck. 2. **Privat tagsüber, öffentlich rückblickend.** „Mein heute" gehört der Person; der konsolidierte Vortagseintrag gehört dem Team. Diese Zeit-Asymmetrie ist UI-konstitutiv. 3. **Monochrome Ruhe, semantische Klarheit.** Weiß und Schwarz dominieren. Farbe (Grün/Gelb/Rot) trägt ausschließlich Bedeutung — niemals Dekoration. 4. **Drei-Klick-Maximum für Schreib-Touchpoints.** Einstempeln, Reflexion, Neuer Blocker sind von der Puls-Seite in ≤ 3 Klicks erreichbar (PRD NFR-9). 5. **Voice statt Decoration.** „Stark.", „Wie läuft es?", „Du hast heute noch nicht gepingt." als Mikrocopy-Anker. Kein Corporate-Sprech, keine Emojis im UI-Text, keine englischen Floskeln. 6. **Die Wahrheit lebt woanders.** Steckbrief in Outline, Issues in Plane, Tickets nicht im Cockpit. Verlinkungen sind eine UI-Erstklass-Komponente, nicht ein technischer Hinweis. 7. **Geschwindigkeit ist ein Feature.** Puls < 1,5 s, Update-Speichern < 500 ms. Performance-Wahrnehmung ist Teil des UX-Versprechens — träge wirkt wie respektlos gegenüber der Zeit der Mitarbeiter. --- ## Desired Emotional Response ### Primary Emotional Goals Das Cockpit soll vier Gefühle gleichzeitig erzeugen: - **Ruhe.** Beim Öffnen kein Lärm, keine bunten Banner, keine Notifications-Flut. Der erste visuelle Eindruck ist *aufgeräumt*. - **Selbstwirksamkeit.** Nach dem Einstempeln das Gefühl: „Ich weiß, was ich heute will." Nach der Reflexion: „Ich weiß, was ich geschafft habe." Kein Pflichtgefühl, sondern stiller Stolz. - **Mitsehen-Können.** Beim Puls-Scrollen: „Ah, so läuft's bei den anderen — gut, dass ich das ohne Fragen sehe." Geteilte Sichtbarkeit ohne Überwachungsgefühl. - **Frühwarn-Vertrauen.** Wenn ein Projekt rot wird, vertraut man dem Cockpit, dass es das schon Tage vorher angedeutet hätte (gelb → rot Trend). Das Cockpit ist ein verlässlicher Frühwarn-Spiegel, kein Schock-Geber. Was das Cockpit **nicht** erzeugen darf: - ❌ **Lästergefühl** — das „fehlt heute"-Modul darf sich nicht wie ein Pranger anfühlen (PRD CM3). - ❌ **Hektik** — keine roten Banner, keine Pulsing-Animationen, keine Pop-ups. - ❌ **Bürokratie** — Reflexion soll wie ein Tagesabschluss-Ritual wirken, nicht wie ein Stundenzettel. - ❌ **Spielerei** — keine Konfetti-Animationen für Streaks, keine Gamification-Badges. Subtil bleiben. ### Emotional Journey Mapping Eine typische Werktag-Emotion einer Person (Q1 Entwickler oder Q2 Sales): | Moment | Erwartete Emotion | UI-Antwort | |---|---|---| | **Login morgens** | Neugierig, leicht angespannt | Klarer Begrüßungs-Header, „Wie läuft es?" sanft, kein Druck | | **„Du hast heute noch nicht gepingt"** | Erinnerung statt Anklage | Großer freundlicher CTA, keine roten Akzente | | **ToDos schreiben** | Fokussierung | Minimalistisches Formular, eine Spalte, monospaced-Optionen | | **Tagsüber im Cockpit reinschauen** | Schnelles Vergewissern | Puls in unter 60 s gelesen, Streak-Badge sichtbar, kein Drill-Down nötig | | **Reflexion abends** | Ritualisches Abschließen | Geführter Flow: Checkboxen → Freitext → Ampel → fertig. Bestätigung mit „Stark." | | **Morgens X+1: Vortags-Reveal** | Soziale Verbundenheit | Konsolidierte Vortageseinträge im Feed, ruhig präsentiert | | **Wenn ein Projekt gelb wird** | Vorsichtige Wachsamkeit | Subtile Gelb-Akzente, klare Erläuterung („Maßnahmenplan greift") | | **Wenn ein Projekt rot wird** | Handlungsbereitschaft | Klarer roter Akzent, Hinweis „braucht jetzt eine Entscheidung", direkter Link zum Projekt-Detail | | **Wenn man die Streak verliert** | Verständnis, keine Strafe | Streak-Counter geht auf 0 ohne Drama; vorheriger Höchstwert wird im Profil als „bester Lauf" gespeichert | ### Micro-Emotions Diese kleinen Momente machen den Unterschied zwischen „funktional" und „liebenswert": - **„Stark."-Bestätigungs-Toast** nach erfolgreicher Reflexion. Drei Buchstaben, schwarzer Pill, 2 Sekunden sichtbar. - **Tagesplan-Echo:** Beim Reflektieren werden die ToDos vom Morgen mit einer leichten Animation eingeblendet — die Person sieht das eigene morgendliche Ich wieder. - **Subtile Ladekontrolle:** Skeleton-Boxen statt Spinner. Wartezeit fühlt sich wie „die App ist schon fast da" an, nicht wie „die App hängt". - **Streak-Tag im Profil:** Eine schlichte Zahl mit dem `^`-Caret als Suffix. „14 ^". Keine Trophäen. - **Reflexions-Erinnerung:** Ab 17:00 erscheint im Header ein dezenter Hinweis-Pill „Reflexion offen". Klick → direkt im Flow. Kein Notification-Lärm. - **Vortags-Reveal:** Beim Laden des Feeds am Morgen X+1 erscheinen die neuen konsolidierten Einträge mit einer kurzen Fade-In-Animation (≤ 200 ms). Markiert visuell „diese sind neu seit gestern". ### Design Implications Die emotionalen Ziele übersetzen sich in folgende UX-Pflichten: - **Weißraum großzügig.** Cards mit viel Padding, klare vertikale Rhythmen — keine Information-Density um jeden Preis. - **Typografie als Hauptkommunikator.** Hierarchie über Schriftgrade und Gewichte, nicht über Farben. - **Animationen sparsam und schnell.** Höchstens 200 ms, ease-out, niemals länger oder bouncy. Animation als Bestätigung, nicht als Show. - **Status-Farben nur funktional.** Grün/Gelb/Rot ausschließlich bei Ampel/Trend/Blocker. Keine farbigen Decorative-Akzente sonst. - **Mikrocopy konsequent deutsch und kurz.** Keine englischen Floskeln, keine Höflichkeitsfloskeln („Bitte beachten Sie…"). - **Kein Drama bei Fehlern.** Fehler-Toasts dezent, in der unteren rechten Ecke, schwarz mit weißem Text. ### Emotional Design Principles 1. **Subtil schlägt laut.** Animationen, Farbakzente und Mikrocopy sind unaufdringlich; nichts ringt um Aufmerksamkeit. 2. **Ritual statt Pflicht.** Reflexion fühlt sich wie ein Abschluss-Ritual an, nicht wie ein Formular. 3. **Sichtbarkeit ist freundlich, nicht überwachend.** „Heute fehlt"-Anzeige als Information, nicht als Anklage. 4. **Geschwindigkeit ist Respekt.** Schnell laden, schnell reagieren — das vermittelt: Wir respektieren deine Zeit. 5. **Stille Anerkennung.** Streaks, „Stark."-Toasts, „bester Lauf"-Memory: kleine Anerkennungen, keine Trophäen-Show. --- ## UX Pattern Analysis & Inspiration ### Inspiring Products Analysis Vier Produkte dienen als Pattern-Referenzen für das Cockpit. Wir kopieren nicht ihren Look, sondern lernen *welche UX-Muster sich für unsere Probleme bewährt haben*. **Linear (linear.app)** — Issue-Tracker für Tech-Teams - **Was übernehmen:** Aufgeräumte, monochrome Listen-Ansichten; Tastatur-Shortcuts als Erstklass-Interaktion; sehr schnelle Mutations-Feedback-Schleifen; Status-Icons als kleine Quadrate statt Text. - **Was nicht:** Linear ist Ticket-Tool — wir sind explizit *kein* Ticket-Tool (PRD Anti-Ziel A1). **Linear's Sub-Issue-System** — Mini-Hierarchie für Tagesplan - Übertragbar als Inspiration für die ToDo-Liste: minimalistisches Inline-Editing, Tippen → Enter → nächste Zeile. **Notion** (notion.so) — Doku & Wissens-Tool - **Was übernehmen:** Klare Typografie-Hierarchie; reduzierte Farbpalette; Embed-/Verlinkungs-Patterns für externe Tools. - **Was nicht:** Wir sind kein Doku-Tool (Outline-Job). Keine Notion-typischen Floating-Elements oder Slash-Commands. **GitHub Projects (Roadmap-Sicht)** — Multi-Projekt-Übersicht - **Was übernehmen:** Tabellen-Sicht über viele Items mit klar erkennbarem Status, Filter-Persistenz, Spalten-Sortierung. - **Was nicht:** GitHub-typische Density (für uns zu viel auf einen Blick) und die Bunt-Tags-Kultur. **Apple HIG (Human Interface Guidelines)** — System-Design-Sprache - **Was übernehmen:** Klare Modal-Patterns, Toast-Position, Form-Stil, San-Serif Lesbarkeit, generöser Weißraum. **Plane (plane.so)** — das parallel laufende Schwester-Tool - **Was übernehmen:** UX-Konsistenz bei Iconografie und Statusfarben, damit der Wechsel Plane ↔ Cockpit nicht mental zerreisst. - **Was nicht:** Plane's volle Issue-Listen — die spiegeln wir nicht (Anti-Ziel A5). ### Transferable UX Patterns | Pattern | Quelle | Anwendung im Cockpit | |---|---|---| | **Inline-Add-on-Enter** | Linear, Notion | ToDo-Liste: Enter erzeugt neue ToDo-Zeile; Cmd+Enter speichert die ganze Liste. | | **Tastatur-Shortcuts mit `?`-Help** | Linear, GitHub | `g p` → Puls, `g h` → Mein heute, `g a` → Archiv. `?` öffnet Cheatsheet. | | **Optimistic Updates mit zarter Bestätigung** | Linear | Beim Abhaken eines ToDos: sofortige UI-Reaktion + leichtes Häkchen-Fade-In; Rollback bei API-Fehler. | | **Skeleton-Cards** | Linear, Vercel | Statt Spinner: graue Card-Skelette mit identischem Layout wie die Echtdaten. | | **Hover-Reveal-Actions** | Linear | Sekundäre Aktionen (Edit, Verwerfen, Löschen) erst beim Hover/Focus sichtbar. Reduziert visuelle Last. | | **Linkurations-Cards** | Notion, Slack-Unfurls | Beim Verlinken einer Plane-URL erscheint im Update eine kleine Card mit Titel und Status (Phase 2 mit API; im MVP: nur URL). | | **Sticky-Sub-Header** | GitHub Projects | Bei langer Bereichs-Detail-View bleibt der Bereichs-Header oben sticky, damit man immer weiß wo man ist. | | **Status-Pill mit Trend-Pfeil** | GitHub PR-Status | Ampel-Pill mit anhängendem Trend-Pfeil als kompaktes Statussignal an Projekt-Karten. | | **Profil-Streak-Stat** | Duolingo (abstrahiert) | Streak als schlichte Zahl im Profil, ohne Streak-Recovery-Käufe oder Drama. | ### Anti-Patterns to Avoid Diese Patterns sind im Cockpit **verboten**, weil sie den Experience Principles widersprechen: - ❌ **Roter Mahn-Banner oben.** Statt „Du hast heute noch nicht eingestempelt"-Banner: ein freundlicher CTA mit `^`-Caret und schwarzem Pill-Button. Niemals Alarmrot. - ❌ **Notification-Badges mit Zahlen.** Wir zeigen Status, nicht Posteingänge. Keine roten Zähler. - ❌ **Gamification-Trophäen.** Keine Badges, keine Levels, keine Konfetti-Animationen. Streak ist genug. - ❌ **Pflicht-Pop-up beim Login** („Bitte stempel zuerst ein"). Stattdessen ist der Einstempel-CTA Teil der Puls-Seite, nicht ein Modal. - ❌ **Bunte Status-Tags** in Marketing-/Vertrieb-Stil. Status-Farben bleiben monochrom + 3 Ampel-Töne. - ❌ **Komplexe Filter-Sidebar**. Im MVP keine Multi-Facet-Filter. Wenn der Feed lang wird: Bereich-Filter + „nur meine" reicht. - ❌ **Dichte Tabellen mit 10+ Spalten.** Karten/Lists, keine Excel-Sheets. - ❌ **Pulsing-/Spin-Animationen** auf der Puls-Seite. Animation nur bei expliziter User-Aktion. - ❌ **Auto-Refresh**. Daten werden bei Page-Navigation und manuellem Pull-to-Refresh-Equivalent neu geholt. Kein Background-Polling außer am User-aktiven Tab. - ❌ **Drag-and-Drop überall**. Drag-and-Drop nur im Sales-Kanban (FR-12), nicht für ToDos oder Meilensteine. ### Design Inspiration Strategy - **Atomare Inspiration, nicht Holistik.** Wir kopieren keine ganzen App-Looks; wir übernehmen einzelne Patterns (Inline-Add, Skeleton, Sticky-Sub-Header) und kombinieren sie mit der ToolCTRL-Brand. - **Brand schlägt Pattern.** Wo ein Pattern (z. B. Notion-Slash-Commands) gegen die Brand-Reduktion arbeiten würde, lassen wir es weg. - **Linear ist die nächste Konstante.** Im Zweifel folgen wir Linear-Patterns für Listenwesen und Mutations-Feedback, da Linear das am saubersten löst für Tech-Teams. - **Eigene Patterns nur wo nötig.** Sichtbarkeitsmodell pre/post Publikation und Pflicht-Minimum-Panel sind eigene Erfindungen — die müssen wir selbst gut machen. --- ## Design System Foundation ### Design System Choice **Tailwind CSS** (vom Architektur-Starter gesetzt) als Utility-First-Foundation, ergänzt um **Radix UI Primitives** für interaktive Komponenten (Dialog, Dropdown, Tabs, Tooltip) und eine **schlanke Custom-Component-Library** in `apps/web/src/components/ui/`. **Keine vollständige Component-Library** (kein shadcn-Bulk-Install, kein Material-UI, kein Ant Design): Die Brand ist zu spezifisch und das Tooling-Volumen zu klein, um eine externe Library zu rechtfertigen. ### Rationale for Selection - **Tailwind passt zur Brand:** Monochrome Palette, klare Spacing-Skala, kein Default-Theme das mit der Brand kämpft. - **Radix UI Primitives liefern Accessibility-Korrektheit** ohne Visual-Design — wir styleen sie mit Tailwind nach unserer Sprache. Spart Bug-Klassen wie kaputte Focus-Traps in Modalen, falsche ARIA-Roles, etc. - **Eigene Components statt shadcn:** shadcn copies kleine Library-Snippets ins Repo — bei unserer Größe ist es kontrollierbarer, ~15 Komponenten direkt im Brand-Stil zu schreiben, als 50 Snippets zu kopieren und Brand-anzupassen. - **Keine Dark-Mode-Pflicht im MVP:** Das Cockpit ist Single-Theme (weiß primär). Phase 2 kann Dark Mode hinzufügen. ### Implementation Approach ``` apps/web/src/components/ui/ # Eigene Brand-konforme Komponenten ├── Button.tsx # 3 Varianten: primary, secondary, ghost ├── Card.tsx # Standard-Container mit großen Radii ├── Input.tsx # Text + Number + URL ├── Textarea.tsx ├── Select.tsx # nutzt Radix Select ├── Checkbox.tsx # nutzt Radix Checkbox ├── Toggle.tsx # 3-Wege-Toggle (Ampel) ├── Dialog.tsx # nutzt Radix Dialog ├── Tabs.tsx # nutzt Radix Tabs ├── Tooltip.tsx # nutzt Radix Tooltip ├── Toast.tsx # nutzt Sonner (toast lib) ├── SkeletonCard.tsx ├── AmpelBadge.tsx # Status-Pill mit Trend ├── PflichtMinimumIndicator.tsx # 6-Punkt-Block-Indikator └── KeyCaret.tsx # Das `^`-Brand-Element ``` ### Customization Strategy 1. **Brand-Tokens als CSS-Variablen im `:root`**, von Tailwind via Theme-Erweiterung konsumiert. Das erlaubt späteres Dark-Mode-Switching ohne Class-Renaming. 2. **Eine `tailwind.config.ts` als Source of Truth** für Spacing, Radii, Schriftgrade, Farben. Custom-Components verwenden `@apply`-Composition oder direkte Utility-Klassen. 3. **Radix-Komponenten werden gestyled, nicht überschrieben.** Tailwind-Classes auf Radix-Primitives (``). 4. **Icon-Set:** **Lucide-React** als Default (offen, kostenlos, konsistent). Wo Brand-Icons aus `ToolCTRL Brand Identity/Brand EcoSystem/Ui icons Pattern` vorhanden sind (Home, Settings, Search, Trash, Zoom-in, etc.) — bevorzugt verwenden; Rest aus Lucide. Beide Sets sind monochrom-filled. --- ## Defining Experience (Detail) ### Defining Experience Im Zentrum steht der **Tagesrhythmus-Doppeltakt**: ein zeitlich getrennter Schreib-Workflow (morgens setzen, abends reflektieren), der bewusst nicht als ein einziges Formular vereint wird, sondern als zwei eigene Touchpoints existiert — getrennt durch den Tag. Die Trennung ist kein technischer Workaround, sondern das UX-Versprechen: „Plan und Realität dürfen sich unterscheiden, und wir machen genau diese Differenz sichtbar." Die zweite Erfahrungs-Säule ist der **Puls als gemeinsamer Spiegel**: ein einziger, dichter Bildschirm, der jeden Werktagsmorgen die Antwort liefert auf „Wie steht es heute um uns alle?". ### User Mental Model Die Personen sollen das Cockpit so verstehen: - **„Mein heute" ist mein Privates** — wie eine Tageskarte, die nur ich sehe. - **Der Puls ist unser Gemeinsames** — wie ein Schwarzes Brett, das jeden Werktag aktuell ist. - **Bereich = Familie meines Projekts/Deals/Kampagne** — Entwicklung, Vertrieb, Marketing als drei eigene Häuser unter einem Dach. - **Plane ist Werkzeug, Outline ist Wissen, Cockpit ist Spiegel.** Das Cockpit interpretiert oder editiert nichts — es zeigt. Was das Modell **vermeiden** muss: die Verwechslung „das Cockpit ist mein Ticket-Tool" (es ist nicht Plane) oder „das Cockpit ist mein Wiki" (es ist nicht Outline). ### Success Criteria Die Kern-Erfahrung gilt als erfolgreich, wenn nach 8 Wochen Live-Betrieb gilt: - ≥ 80 % der Werktage haben pro aktiver Person mindestens ein abgeschlossenes Tagesupdate (PRD M1). - Median Einstempel-Zeit ≤ 60 s, Median Reflexions-Zeit ≤ 90 s (CM1a/CM1b). - 100 % der Jourfixes nutzen den Puls als Hauptbildschirm (M4). - Kein erhöhter Druck-/Lästergefühl im 4-Wochen-Retro (CM3). ### Novel UX Patterns Diese Patterns sind im Cockpit **neu erfunden** (haben kein direktes Vorbild in der Inspirations-Bibliothek): 1. **Sichtbarkeits-Asymmetrie über Zeit:** ToDos sind tagsüber privat, am nächsten Werktagsmorgen publiziert — bewusst keine Realtime-Sichtbarkeit. Visuell muss klar sein: „Was du gerade tippst, sehen Kollegen ab morgen." 2. **Pflicht-Minimum-Indikator:** Sechs kleine Blöcke (•••••• statt einzelner Häkchen-Checkliste) zeigen pro Projekt den Erfüllungsstand auf einen Blick. Ein klick zum Detail. 3. **Tagesplan-Echo:** Bei der Abend-Reflexion erscheinen die morgens gesetzten ToDos zurück — Person konfrontiert sich mit dem eigenen morgendlichen Plan. 4. **Tagesstatus-Pill pro Person:** 🟢 voll, 🟡 halb, ⚪ nicht angefangen, 🟣 abwesend — eine vierwertige Statusanzeige, die sich klar von Projekt-Ampeln (3-wertig + grau) unterscheidet. ### Experience Mechanics **Morgen-Einstempeln-Flow:** 1. Person öffnet Cockpit → Puls-Seite. 2. CTA „Einstempeln" prominent oberhalb des Folds. Bei nicht-eingestempelten Personen großer schwarzer Pill-Button mit `^`-Caret. 3. Klick öffnet `/mein-heute` (kein Modal — eigene Route, das `^` der Brand wird Teil des Headers). 4. Eine zentrale Spalte: leere ToDo-Liste mit Cursor auf Zeile 1. 5. Bereich ist vorausgewählt (Default = eigene Area). Bezugs-Auswahl pro ToDo erscheint inline rechts neben der Zeile, wenn die ToDo fokussiert ist (Hover-Reveal-Pattern). 6. Enter erzeugt nächste Zeile. Cmd/Ctrl+S oder Klick auf „Eingestempelt"-Button speichert. 7. Bestätigung: Subtiler „Eingestempelt."-Toast (2 s) + Redirect auf Puls. „Heute fehlt"-Modul auf Puls zeigt eine Person weniger. **Abend-Reflexions-Flow:** 1. Ab 17:00 erscheint im Header-Bereich ein dezenter „Reflexion offen"-Pill. 2. Klick → Route `/reflexion` (oder `/mein-heute` mit Reflexions-Tab). 3. Person sieht die morgens definierte ToDo-Liste, Klick auf Checkbox-Icon hakt ab, Klick auf X-Icon verwirft (mit optionalem Grund im Inline-Field). 4. Unter der ToDo-Liste: ein Freitext-Bereich „Sonst noch was?" (1.000 Zeichen, monospaced-Counter zeigt verbleibende Zeichen unauffällig). 5. Drei große farbige Ampel-Buttons (Grün/Gelb/Rot), darunter drei Trend-Pfeile (Pflicht, wenn Bezug=Projekt). 6. Optionaler „Blocker?"-Toggle, öffnet ein Inline-Feld. 7. „Reflektiert."-Toast (2 s) + Redirect auf Puls. **Vortags-Reveal:** - Beim ersten Laden des Puls am Werktag X+1 erscheinen die konsolidierten Vortageseinträge im Feed mit kurzem Fade-In. Header-Hinweis (sehr dezent): „Stand: Mo, 24. Mai". --- ## Visual Design Foundation ### Color System Konkrete Brand-Tokens, abgeleitet aus der ToolCTRL Brand Identity. Werden in `apps/web/src/styles/globals.css` als CSS-Variablen definiert und in `tailwind.config.ts` als Theme-Erweiterung gespiegelt. **Neutrals (Hauptpalette):** | Token | Hex | Verwendung | |---|---|---| | `--color-bg` | `#ffffff` | App-Hintergrund | | `--color-surface` | `#fafafa` | Card-Hintergrund (sehr subtil von BG getrennt) | | `--color-surface-elevated` | `#ffffff` | Modal-Hintergrund, schwebende Elemente (mit Schatten) | | `--color-border` | `#e5e5e5` | Dünne Trennlinien, Card-Borders | | `--color-border-strong` | `#d4d4d4` | Hover-Border, fokussierter Trennstrich | | `--color-ink` | `#0a0a0a` | Haupttext (near-black, nicht reines #000 für weichere Lesbarkeit) | | `--color-ink-muted` | `#525252` | Sekundärtext, Labels | | `--color-ink-faint` | `#a3a3a3` | Tertiärtext, Platzhalter | | `--color-brand` | `#0a0a0a` | Primärbutton-Hintergrund, Marken-Akzente (= ink) | | `--color-brand-fg` | `#ffffff` | Text auf Brand-Flächen | **Semantische Ampel-Farben** (auch hell genug für die Brand-Welt): | Token | Hex (Foreground/Text) | Hex (Background/Surface) | Verwendung | |---|---|---|---| | `--color-ampel-green` | `#15803d` | `#dcfce7` | Status „Im Plan" | | `--color-ampel-amber` | `#a16207` | `#fef3c7` | Status „Gefährdet" | | `--color-ampel-red` | `#b91c1c` | `#fee2e2` | Status „Blockiert" | **Trend-Indikatoren:** | Token | Hex | |---|---| | `--color-trend-up` | `#15803d` (besser, ↗︎) | | `--color-trend-flat` | `#525252` (gleich, →) | | `--color-trend-down` | `#b91c1c` (schlechter, ↘︎) | **Focus / Interaction:** | Token | Hex | Verwendung | |---|---|---| | `--color-focus-ring` | `#0a0a0a` mit 20% opacity outline | Tastatur-Fokus-Indikator | | `--color-hover-overlay` | `rgba(0,0,0,0.04)` | Hover-Layer auf Cards/Buttons | ### Typography System **Schriftfamilie:** - **Sans-Serif (UI):** `Inter` — selbst-gehostet via `@fontsource/inter`. Variable Font (300–900). Lehnt am Brand-Marketing-Sans an (geometrische Sans-Serif). - **Monospace (Werte/Zeiten):** `JetBrains Mono` — selbst-gehostet via `@fontsource/jetbrains-mono`. Für Zeitstempel, EUR-Beträge, Datums-Anzeigen. **Type-Scale** (basierend auf 16 px Body): | Token | Größe / Line-Height / Weight | Verwendung | |---|---|---| | `text-xs` | 12 / 16 / 500 | Labels, Captions, Audit-Zeitstempel | | `text-sm` | 14 / 20 / 400 | Sekundärtext, Meta-Information | | `text-base` | 16 / 24 / 400 | Body, Form-Inputs | | `text-lg` | 18 / 28 / 500 | Card-Titel | | `text-xl` | 20 / 28 / 600 | Sektions-Header | | `text-2xl` | 24 / 32 / 700 | Seitentitel | | `text-3xl` | 32 / 40 / 700 | Hero im Puls („Stand: Di, 25. Mai") | **Voice-Anker-Typografie:** - „**Stark.**" (Toast): `text-base font-semibold` schwarzer Pill. - „**Wie läuft es?**" (Reflexions-Header): `text-xl font-medium ink-muted`. - „**Du hast heute noch nicht gepingt.**" (Puls-CTA-Banner): `text-lg font-medium ink` + Button daneben. ### Spacing & Layout Foundation **Spacing-Skala** (Tailwind-Standard `0.25rem` = `4px`): | Token | Wert | Anwendung | |---|---|---| | `space-1` | 4 px | Mikro-Padding | | `space-2` | 8 px | Innen-Padding kleiner Pills | | `space-3` | 12 px | Standard-Gap zwischen Inline-Elementen | | `space-4` | 16 px | Card-Inner-Padding small | | `space-6` | 24 px | Card-Inner-Padding default | | `space-8` | 32 px | Sektions-Abstand | | `space-12` | 48 px | Seitenrand-Padding | | `space-16` | 64 px | Hero-Abstand | **Radii:** | Token | Wert | Verwendung | |---|---|---| | `radius-sm` | 6 px | kleine Pills, Inputs | | `radius-md` | 10 px | Buttons, Tags | | `radius-lg` | 16 px | Cards, Modal-Container | | `radius-xl` | 24 px | Hero-Cards, Brand-konforme Big-Rounded-Boxes (vgl. Need-Help-PDF Brand-Stil) | | `radius-full` | 9999 px | Pills, Avatars | **Schatten (sehr subtil, near-black mit niedriger Opacity):** | Token | Wert | Verwendung | |---|---|---| | `shadow-sm` | `0 1px 2px rgba(10,10,10,0.04)` | Cards in Default-State | | `shadow-md` | `0 4px 12px rgba(10,10,10,0.06)` | Hover-State Cards | | `shadow-lg` | `0 12px 32px rgba(10,10,10,0.10)` | Modale, Dropdowns | **Grid & Container:** - **Container-Max-Width:** 1.280 px, horizontal zentriert. - **Container-Padding-X:** 24 px (mobile) → 48 px (≥ md). - **Grid:** 12-Spalten-Grid mit 24 px Gap auf Desktop. - **Puls-Layout:** 3-Spalten-Grid für die drei Bereiche; auf Tablet 2-Spalten; auf Mobile single-column-Stack. ### Accessibility Considerations - **WCAG 2.1 AA** als Mindeststandard für Kontraste: - `--color-ink` auf `--color-bg`: 19.5:1 ✅ - `--color-ink-muted` auf `--color-bg`: 8.1:1 ✅ - `--color-ampel-green` Text auf Green-BG: 5.5:1 ✅ - `--color-ampel-amber` Text auf Amber-BG: 5.8:1 ✅ - `--color-ampel-red` Text auf Red-BG: 6.1:1 ✅ - **Farbe ist nie alleinige Information.** Ampel hat zusätzlich Icon + Text-Label („Im Plan", „Gefährdet", „Blockiert"). Trend hat Pfeil-Icon zusätzlich zur Farbe. - **Fokus-Indikator** auf jedem interaktiven Element — `outline: 2px solid var(--color-ink)` mit 2 px Offset. - **Tastatur-Navigation:** Tab-Order folgt visueller Reihenfolge; alle interaktiven Elemente sind ohne Maus erreichbar. - **Screenreader:** Radix-Primitives liefern korrekte ARIA-Roles automatisch. Custom-Components ergänzen `aria-label` wo nötig (z. B. Icon-Only-Buttons). - **Reduzierte Bewegung:** `prefers-reduced-motion: reduce` schaltet Fade-In-Animationen auf 0 ms. - **Schriftgrad-Mindest:** keine Schriftgröße kleiner als 12 px im UI. --- ## Design Direction Decision ### Design Directions Explored Drei Visualrichtungen wurden konzeptionell erwogen: 1. **"Office Minimal" (gewählt)** — fast vollständig weiß-grau-schwarz, Typografie-getragen, einzelne semantische Farbakzente, sehr ruhig. 2. **"Brand Dark Hero"** — schwarzer Header und Hero-Bereich wie in den LinkedIn-Posts; Body auf Weiß. Dramatischer, marken-näher. 3. **"Colorful Status Pop"** — Brand monochrom, aber Ampeln und Bereichs-Akzente sehr farbig und groß. Spielerischer Versuch. ### Chosen Direction **Office Minimal** — die Anwendung präsentiert sich als ruhiges, fast nüchternes Werkzeug, das durch Klarheit überzeugt, nicht durch visuelle Effekte. ### Design Rationale - **Passt zum User-Kontext:** Internes Tool, das mehrmals täglich geöffnet wird. „Brand Dark Hero" ermüdet auf Dauer, „Colorful Status Pop" wird laut. - **Passt zur Brand-Reduktion:** ToolCTRL ist visuell minimal — Office Minimal überträgt diese Reduktion in die App. - **Diensthandelnde Klarheit:** Wer schnell wissen will, „läuft das Projekt?", soll die Antwort in 1 s lesen können — das geht am besten mit hohem Kontrast und wenig Visual-Noise. - **Brand-Akzente bleiben übrig:** Der `^`-Caret als wiederkehrendes Element, der schwarze Pill-Button-Stil, große Radii — das bringt die Marken-DNA in die App, ohne sie aufzudrängen. ### Implementation Approach - Weiß als Default-Background überall. - Cards mit `radius-lg` (16 px), `shadow-sm`, `border: 1px solid var(--color-border)`. - Primärbuttons schwarz mit weißem Text + `radius-md` (10 px). - Sekundärbuttons mit transparentem Hintergrund + 1 px Border in `--color-ink`. - Ghost-Buttons (z. B. „Abbrechen") ganz ohne Border, nur Text-Color. - Ampel-Indikatoren als kleine farbige Punkte/Pills mit kontrastreichem Text auf zarter Background-Farbe. - Brand-Element `^` als kleines Detail im Logo-Lockup oben links: `cockpit ^`. - Hero-Texte (z. B. „Stand: Di, 25. Mai") in `text-3xl font-bold` schwarz auf weiß. --- ## User Journey Flows ### UJ-1 — Tagesrhythmus (Morgen → Abend → Nächster Morgen) ```mermaid flowchart TD A[Login via Authentik] --> B[Puls-Seite] B --> C{Schon eingestempelt?} C -- nein --> D[CTA Einstempeln klicken] D --> E[/mein-heute öffnet sich] E --> F[ToDos tippen, Enter erzeugt neue Zeile] F --> G[Eingestempelt-Button] G --> H[Stark.-Toast 2s] H --> B C -- ja --> I[Tagsüber arbeiten / weitere Cockpit-Lookups] I --> J{Nach 17:00?} J -- nein --> I J -- ja --> K[Reflexion-offen-Pill im Header] K --> L[/reflexion oder /mein-heute Tab Reflexion] L --> M[ToDos abhaken / verwerfen] M --> N[Freitext was sonst noch] N --> O[Ampel + Trend setzen] O --> P{Blocker?} P -- ja --> Q[Blocker-Text inline] P -- nein --> R[Reflektieren-Button] Q --> R R --> S[Reflektiert.-Toast] S --> B B --> T[Nächster Werktag 00:05: Cron publiziert] T --> U[Vortrags-Reveal im Feed mit Fade-In] ``` **Touchpoints im Detail:** - **Morgen (CM1a ≤ 60 s):** Person + Bereich (Default) + 3-5 ToDos + Submit. UI muss Tab-Reihenfolge perfekt einhalten — Erste ToDo-Zeile bekommt sofort Fokus. - **Tagsüber:** Cockpit darf aufgerufen werden, aber zeigt der Person nur die eigene Sicht + den Puls; die ToDos sind nur für sie selbst sichtbar. - **Abend (CM1b ≤ 90 s):** Tagesplan-Echo (ToDos vom Morgen erscheinen mit kurzem Fade-In), schnelles Abhaken via Klick, ein bis drei Sätze Freitext, drei große Buttons für Ampel, drei Pfeile für Trend, fertig. - **Nächster Morgen:** Vortrags-Reveal als zarte UI-Akzentuierung; sonst bleibt das Cockpit ruhig. ### UJ-2 — Jourfixe-Moderation (Di 11:00, P1/P4) ```mermaid flowchart TD A[PM öffnet Cockpit am Di 11:00] --> B[Puls-Seite] B --> C[Bereichs-Strip lesen: 3 Ampelstatus] C --> D[Blocker-Liste lesen] D --> E[Pflicht-Minimum-Übersicht lesen] E --> F{Rote oder gelbe Projekte?} F -- ja --> G[Klick auf rotes/gelbes Projekt] G --> H[Projekt-Detail mit Updates + Meilensteinen] H --> I[Diskussion mit Verantwortlichem] I --> J{Weitere Projekte?} J -- ja --> G J -- nein --> K[Optional: Jourfixe-Meta-Update als allgemeines Update] F -- nein --> K K --> L[Jourfixe beendet] ``` ### UJ-3 — Verfall früh erkennen (P1, P4) ```mermaid flowchart TD A[Person scrollt durch Puls] --> B[Projekt mit rotem Status auffällt] B --> C[Klick auf Projekt-Card] C --> D[Projekt-Detail zeigt: letzter Update vor X Tagen] D --> E[Letzte Reflexionen mit Trend ↘︎] E --> F[Meilenstein-Status: X von Y überzogen] F --> G[Pflicht-Minimum-Panel zeigt unerfüllte Punkte] G --> H[Person schreibt allgemeines Update mit Bezug auf Projekt] ``` ### UJ-4 — Onboarding eines neuen Mitarbeiters ```mermaid flowchart TD A[Admin legt User in Authentik an + Group] --> B[User loggt sich erstmals ein] B --> C[OIDC-Flow läuft, Backend legt User-Zeile an] C --> D[Default-Bereich aus Authentik-Group gemappt] D --> E[Puls-Seite: Hero-Hinweis Erstes Tagesupdate] E --> F[User klickt Einstempeln] F --> G[Schreibt erste ToDos] G --> H[Erscheint in Anwesenheits- + Streak-Liste, Streak=1] ``` ### UJ-5 — Projekt im Cockpit-Sicht anlegen (P1) ```mermaid flowchart TD A[P1 legt Steckbrief in Outline an] --> B[Wechsel ins Cockpit] B --> C[Bereichs-Detail → Neues Projekt] C --> D[Modal: Name, Verantwortliche/r, Projektart, Arbeitsmodus] D --> E[Felder: Steckbrief-URL Pflicht, Plane-Board-URL Pflicht] E --> F[Optional: DoD-Text, Risikoliste-URL] F --> G[Optional: erste Meilensteine inline] G --> H[Speichern → Projekt erscheint im Bereich + im Puls] H --> I[Pflicht-Minimum-Indikator startet bei 4-6 erfüllten Punkten] ``` ### Journey Patterns - **„Puls-zurück" als roter Faden:** Nach jedem Schreib-Touchpoint kehrt die Person auf den Puls zurück. Das verankert den Puls als Heimat. - **Toast als kleinster Erfolg:** Jede Mutation → kurze Toast-Bestätigung mit Voice-Anker (`Stark.`, `Reflektiert.`, `Blocker offen.`). - **Inline-Eingabe statt Modal-Stapel:** Wo möglich, werden Bezüge inline gesetzt, nicht in einem zweiten Modal. Modals nur für Projekt-Anlage und Blocker-Auflösung. - **Breadcrumb über Tabs:** Statt Tabs nutzen wir Breadcrumbs (Puls → Bereich → Projekt) für sauberere Navigation und einfachere Tastatursteuerung. ### Flow Optimization Principles 1. **First-Field-Focus.** Jedes Modal/jeder Schreib-Flow setzt den Cursor automatisch auf das erste sinnvolle Feld. 2. **Enter ist Submit, wo es Sinn ergibt.** ToDo-Liste: Enter → neue Zeile. Reflexion: Cmd/Ctrl+Enter → Submit. 3. **Esc schließt Modale ohne Speichern** (Standard für alle Radix-Dialoge). 4. **Keine Multi-Step-Wizards.** Selbst die Reflexion ist ein single-screen Flow mit gestaffeltem visuellem Aufbau, nicht „Schritt 1 von 3". 5. **Konsequente Rückkehr.** Nach Erfolg: zurück zum Puls. Nach Abbruch: zurück zur Vor-Seite via Browser-History (Esc + Back). --- ## Component Strategy ### Design System Components Aus dem Tailwind + Radix-Stack stehen folgende Primitives ohne Eigenentwicklung zur Verfügung: - **Radix UI:** Dialog, Dropdown Menu, Select, Checkbox, Tabs, Toast (via Sonner), Tooltip, Popover, Hover Card, Collapsible, Accordion, Avatar, Form, Label, Toggle, Toggle Group. - **Lucide React:** ~1.500 monochrome Icons (Suche, Settings, Plus, Check, X, ChevronDown, ArrowUpRight, ArrowRight, ArrowDownRight, Calendar, Clock, User, Filter, etc.) - **Sonner:** Toast-Library. - **React Hook Form + Zod:** Form-Management. - **@fontsource/inter + @fontsource/jetbrains-mono:** Selbst-hostbare Brand-Fonts. ### Custom Components 15 hauseigene Komponenten in `apps/web/src/components/ui/`: | Komponente | Zweck | Verwendung in FRs | |---|---|---| | `Button` | 3 Varianten (primary/secondary/ghost), 3 Größen (sm/md/lg) | Überall | | `Card` | Standard-Container mit `radius-lg`, `shadow-sm`, `border` | Puls, Bereiche, Projekte, Listen | | `Input` | Text-Input mit Brand-Style | FR-21, FR-22, FR-26 | | `Textarea` | Multi-Line-Eingabe, Counter unten rechts | FR-26 | | `Select` | Auf Radix-Select, kompakter dropdown | FR-22 Bezug, Bereich | | `Checkbox` | Auf Radix-Checkbox, animiertes Häkchen | FR-26 ToDo abhaken | | `AmpelButton` | 3-Wege-Toggle Grün/Gelb/Rot, große Klick-Targets | FR-26 | | `TrendButton` | 3-Wege-Toggle ↗︎/→/↘︎ | FR-26 | | `Dialog` | Auf Radix-Dialog, mit Brand-Header und `radius-xl` | FR-31 Blocker, FR-45 Abschluss | | `Tooltip` | Auf Radix-Tooltip, schwarzer Bubble mit weißem Text | Hover-Erläuterungen | | `Toast` | via Sonner, schwarzer Pill mit weißem Text, Bottom-Right | Voice-Ankerbestätigungen | | `SkeletonCard` | Graue Card-Skelette identischer Geometrie wie echte Cards | Loading-States überall | | `AmpelBadge` | Status-Pill mit Farbpunkt + Label + optionalem Trend-Pfeil | FR-9, FR-21 | | `PflichtMinimumIndicator` | Sechs kleine Quadrate horizontal, gefüllt/leer | FR-9 (Projekt-Card), FR-7 (Puls) | | `KeyCaret` | Brand-`^`-Element als SVG, einbindbar in Header/Logo | TopNav, Toast-Bestätigung | ### Component Implementation Strategy - **Compound-Components statt Prop-Explosion:** ``, ``, ``, `` für flexible Layouts ohne 20 Props. - **`cva` (class-variance-authority)** für Variant-Verwaltung (`Button.variants.primary`, `Button.variants.secondary`). - **Storybook entfällt im MVP** — bei 15 Komponenten und einem Frontend-Team können wir per `apps/web/src/routes/dev/components.tsx` eine eigene „Component Gallery"-Seite bauen, die nur in dev-Mode sichtbar ist. - **Snapshot-Tests via Vitest + jsdom** für Komponenten-Stabilität. ### Implementation Roadmap 1. **Sprint 1 — UI-Kit-Bootstrap:** Button, Card, Input, Textarea, KeyCaret, Toast, SkeletonCard. Component-Gallery-Route. 2. **Sprint 2 — Status-Spezifika:** AmpelButton, TrendButton, AmpelBadge, PflichtMinimumIndicator. 3. **Sprint 3 — Interaktion:** Dialog, Tooltip, Select, Checkbox. 4. **Sprint 4 — Feature-Komponenten:** Puls-Module, Bereichs-Details, Tagesrhythmus-Flow. 5. **Sprint 5 — Spezialfälle:** Sales-Kanban (Drag-and-Drop via dnd-kit), Lead-Funnel. --- ## UX Consistency Patterns ### Button Hierarchy | Variant | Verwendung | Visual | |---|---|---| | **Primary** | Hauptaktion einer Seite (Einstempeln, Reflektieren, Speichern) | Schwarzer Hintergrund, weißer Text, `radius-md` | | **Secondary** | Alternative Aktion (Abbrechen mit Aktion, Sekundäre Navigation) | Transparenter Hintergrund, 1 px schwarzer Border, schwarzer Text | | **Ghost** | Tertiär (Abbrechen, Schließen, Edit-Hover-Actions) | Kein Border, kein Hintergrund, nur Text. Hover bekommt `--color-hover-overlay`. | | **Destructive** | Löschen, Archivieren | Wie Primary, aber `--color-ampel-red`-Hintergrund (selten genutzt — Cockpit kennt fast keine Lösch-Aktionen) | | **Icon-Only** | Inline-Aktionen (Edit, X) | Quadratisch 32×32, Ghost-Stil mit Lucide-Icon zentral. `aria-label` Pflicht. | **Größenstaffel:** `sm` (28 px Höhe), `md` (36 px Höhe, Default), `lg` (44 px Höhe, für Haupt-CTAs auf dem Puls). ### Feedback Patterns - **Sofortige optimistic Reaktion** bei Mutations (Checkbox abhaken, Ampel setzen). Bei Server-Fehler: Rollback + roter Toast „Speichern fehlgeschlagen — bitte nochmal versuchen.". - **Toast bei jeder Mutation** mit Voice-Anker. Toast erscheint bottom-right, 2 s sichtbar, ohne Dismiss-Button (außer Fehler-Toasts haben ein X). - **Skeleton beim Initial-Load.** Niemals leerer Bildschirm, niemals Spinner als Alleinstellungsmerkmal. - **Empty-States als Tropfen-Information:** Wenn ein Feed leer ist, nicht „Keine Daten" — sondern „Hier erscheinen die Updates des Tages, sobald jemand reflektiert hat.". Voice-konform. - **Error-States immer mit Aktion.** Statt nur „Fehler beim Laden": „Konnte Projekt nicht laden. [Erneut versuchen]". ### Form Patterns - **Labels über dem Feld**, nicht inline-floating. - **Pflichtfelder mit `*`** im Label, deutlich aber dezent. - **Validation onBlur**, nicht onChange — verhindert nervige Rotmeldungen während Tippen. - **Submit-Button disabled** während Pending-Request mit Mini-Spinner statt komplettem Loading-Overlay. - **Form-Errors unter dem Feld**, schwarzer Text, kein Rot (außer Border des Feldes wird rot). - **Eine Spalte Form-Layout**, kein Side-by-Side außer Datum/Uhrzeit-Paare. ### Navigation Patterns - **TopNav fest:** `cockpit ^` Logo links · Tabs (Puls / Entwicklung / Vertrieb / Marketing / Mein heute / Archiv) · rechts: Streak-Badge + Avatar. - **Active-Indicator:** Aktiver Tab bekommt einen 2 px dicken schwarzen Underline. Kein farbiges Highlight. - **Breadcrumbs in Detail-Views:** „Puls › Entwicklung › Projekt X" (Klickbare Pfad-Segmente). - **Browser-Back funktioniert immer.** React-Router-History-Pflege. - **Keyboard-Shortcuts:** `g p` Puls, `g h` Mein heute, `g e` Entwicklung, `g v` Vertrieb, `g m` Marketing, `g a` Archiv. `?` öffnet Cheatsheet. `n` öffnet „Neuer Blocker"-Dialog. Esc schließt. ### Additional Patterns - **Status-Pill-Konvention:** Immer als `[● Label]` formatieren — kleiner farbiger Punkt + Label, in Pill mit `radius-full`. - **Datum-Anzeige:** „Mo, 25. Mai" für Werktage; „vor 2 Tagen" für relative Zeitangaben; ISO-Format `2026-05-25` nur in technischen Audit-Anzeigen. - **EUR-Anzeige:** Tausenderpunkt + Komma + Euro-Zeichen mit Leerzeichen, z. B. `12.500,00 €`. Niemals `12500€` oder `EUR 12500`. - **Avatar-Konvention:** Initialen (max 2 Zeichen) in schwarzem Kreis mit weißer Schrift; Bilder optional aus Authentik-Profilbild Phase 2. --- ## Responsive Design & Accessibility ### Responsive Strategy - **Desktop-first** (`min-width` queries). - **Drei Sicht-Ebenen:** - **Desktop (≥ 1280 px):** Volles 3-Spalten-Layout im Puls, alle Tabs in TopNav sichtbar. - **Tablet (768–1279 px):** Puls auf 2-Spalten-Grid; TopNav klappt überlange Tabs in „Mehr"-Dropdown. - **Mobile (< 768 px):** Single-Column-Stack; TopNav wird zu Bottom-Tab-Bar mit 4 Items (Puls / Mein heute / Bereiche-Dropdown / Profil). Reflexion und Einstempeln sind **lesbar**, das Schreiben wird ausdrücklich auf Desktop empfohlen (Info-Hinweis im Mobile-Layout). ### Breakpoint Strategy | Breakpoint | Größe | Verwendung | |---|---|---| | `sm` | ≥ 640 px | Vereinzelte Layout-Anpassungen | | `md` | ≥ 768 px | Tablet-Layout aktiviert | | `lg` | ≥ 1024 px | Mehr Padding, größere Cards | | `xl` | ≥ 1280 px | Desktop-Volllayout, 3-Spalten | | `2xl` | ≥ 1536 px | Container bleibt bei 1280 px gecappt, mehr Außen-Padding | ### Accessibility Strategy - **Standard:** WCAG 2.1 AA durchgängig. - **Keyboard-First-Pflicht.** Alle interaktiven Elemente erreichbar via Tab, Aktivierung mit Enter/Space. - **Focus-Ring sichtbar:** `outline: 2px solid var(--color-ink)` + 2 px Offset auf jedem fokussierten Element. - **Skip-Link** ganz oben („Zum Hauptinhalt springen") für Screenreader. - **Heading-Hierarchie sauber:** `

` einmal pro Seite (Seitentitel), `

` für Sektionen, `

` für Sub-Sektionen. - **Live-Regionen für Toast-Notifications:** `aria-live="polite"` für Erfolg, `aria-live="assertive"` für Fehler. - **Alt-Texte** auf jedem nicht-dekorativen Bild und SVG. `