Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/INTERIM-UI-PLAYBOOK.md
T
2026-07-08 16:15:37 +02:00

9.5 KiB
Raw Blame History

Interim-UI-Playbook — Vorschau-Screens aus ~/ui vor Davids Delta

Stand: 2026-07-05 · Verbindliche Grundlage: docs/ARCHITECTURE-DECISIONS.md AD-28 Verwandt: .planning/INTERIM-UI-DESIGN-STANDARDS.md (Davids Layout-/Komponenten-/State-Werte) · DESIGNER-FIRST-PLAYBOOK.md · docs/INTEGRATION-CONTRACTS.md · ticket-docs/README.md

Warum dieses Playbook

Viele Dev-Tickets (R-P8/9/11/12, R-P2, AK-P3/4/14/16/17/19/20/21, v2: VR-P22b/VR-MCP) sind serverseitig fertig, bleiben aber On Hold, weil die finale Optik an „Davids Delta" im jeweiligen D-*-Screen-Ticket hängt — und diese Screens dauern noch. Die Component-Basis liegt aber schon im Repo: apps/web/app/ui/ (Alias ~/ui/*) enthält 79 gesyncte Subframe-Components

  • die Layouts DefaultPageLayout/DrawerLayout/DialogLayout (gepflegt über .subframe/sync.json).

Statt auf David zu warten, baut der Dev jetzt aus denselben ~/ui-Components eine Interim-UI (Vorschau-Screen), stellt das Ticket damit fertig, testet es und schiebt es auf Done. Der spätere Tausch gegen Davids finalen Subframe-Screen ist ein getrackter Nachzug hinter der stabilen VM/Loader-Grenze — ein Component-Swap, kein Rewrite (Hot-Swap-Gedanke, M015/M017).

Begriff: „Interim-UI" / „Interim-Screen". Nicht verwechseln mit packages/ui-mock — das ist der M017-Hot-Swap-Drop-in (bewusst hässliches Alt-Markup zum Beweis der Austauschbarkeit), etwas völlig anderes.

Die goldene Regel (macht „später wenig Arbeit" real)

Ein Interim-Screen muss:

  1. aus ~/ui-Components + einem ~/ui/layouts/* komponiert sein — nie handgeschriebenes Tailwind-Markup (Negativ-Beispiel: apps/web/app/routes/app.$tenant/tasks._index.tsx, das eine handgeschriebene <table> rendert und „Subframe polish follows David's D-P4 delta" trägt);
  2. seine Daten aus dem bestehenden View-Model (packages/view-models/**) beziehen, das als Prop hereingereicht wird;
  3. alle statischen Texte über i18n-Keys (t()) auflösen.

Nur so ist Davids Delta hinterher hauptsächlich Anordnung/Feinschliff, und der Swap bleibt billig. Wird Interim-UI als handgeschriebenes Tailwind gebaut, ist der Nachzug ein Neubau — das verfehlt den ganzen Zweck und ist ein PR-Block wie ein Anti-Listen-Verstoß.

Nach Davids Standards bauen (~/ui-Defaults + Design-Werte): Damit die Interim-UI wirklich nah an Davids kommende Pages kommt, folgt der Screen denselben Layout-/Komponenten-/State-Standards, nach denen David selbst baut — festgehalten (mit exakten Werten: Page-Padding 24, Card 16, Dialog-Größen, Control-Höhen, State-Regeln, Screen-Naming) in .planning/INTERIM-UI-DESIGN-STANDARDS.md (In-Repo-Spiegel von Davids Vault ../HiveGrid-Wireframes/). Kernpunkt: ~/ui-Component-Defaults sind führend — Höhen/Paddings/ Dialog-Struktur nicht mit Tailwind nachbauen, wenn die Komponente/Variante sie schon abbildet. Modale immer als echter Dialog (DialogLayout → Dialog → Dialog.Content), nie als Card-Fake. Diese Doc vor dem Screen-Bau lesen.

Wo der Interim-Screen lebt

apps/web/app/components/screens/<domain>/<Screen>Page.tsx
  └─ export function <Screen>Page({ vm, actions }: { vm: <Screen>VM; actions: <Screen>Actions }) { … }
     komponiert ~/ui-Components + DefaultPageLayout, rendert vm.data, ruft actions.onX

Die Route bleibt beim etablierten Muster und rendert nur:

// apps/web/app/routes/app.$tenant/<modul>._index.tsx
export default function XRoute() {
  const { vm } = useLoaderData<LoaderData>();
  return <XPage vm={vm} actions={{ onEdit, onArchive }} />;
}

Das ist genau das AGENTS.md-Zielmuster <XPage vm={} actions={} /> — die Interim-UI füllt die heute fehlende „mittlere Komposition" zwischen VM und ~/ui-Primitives.

Layer-Regeln bleiben unangetastet

Die drei Anti-Patterns (AGENTS.md) gelten weiter:

  • kein @prisma/client/~/db in packages/ui-app/**;
  • kein packages/ui-subframe-Direktimport in app/routes/**;
  • kein useLoaderData in packages/ui-app/** — VM wird als Prop injiziert.

~/ui-Direktimport in apps/web/app/components/** bzw. app/routes/** ist erlaubt — er verletzt kein Anti-Pattern (die verbieten nur packages/ui-subframe-Direktimporte). Wer den formalen ui-app/ui-subframe-Adapterpfad nutzen will, kann das; für Interim-Screens ist die direkte ~/ui-Komposition der pragmatische, schnellere Weg.

Done-Semantik (AD-28)

Ein UI-lastiges Ticket ist Done-fähig, sobald:

  • Dev-DoD 100 % (alle nicht-Optik-Punkte grün) und
  • Interim-Screen aus ~/ui steht (goldene Regel erfüllt) und
  • Tests grün (siehe DoD-Mapping unten).

Die finale Subframe-Optik ist dann kein Done-Blocker mehr, sondern ein getrackter Nachzug. /planning bleibt die Single Source of Truth — der Nachzug wird zuerst in der Ticket-Doc markiert, Plane spiegelt nur:

  • .planning/ticket-docs/<ID>.md (führend): der standardisierte 🎨 design-nachzug-Tag direkt unter der Header-Tabelle (Format unten) plus der ausführliche Interim-UI-Vermerk in der Sektion „Dev-Nachzug (nach Davids D-*-Delta)" (Muster unten),
  • Plane-Label design-nachzug (spiegelt die Doc): nur für Board-Queries; wird aus dem Doc-Tag abgeleitet, nie umgekehrt,
  • die Interim-Visual-Baseline ist als „interim" markiert und wird beim Nachzug neu gezogen.

Header-Tag in der Ticket-Doc (Single Source of Truth)

Direkt unter die Header-Tabelle der Ticket-Doc, damit /planning per grep autoritativ auswertbar ist (grep -rl "design-nachzug: offen" .planning/ticket-docs/):

**🎨 design-nachzug: offen** (seit YYYY-MM-DD) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-<XXX>` ausstehend.

Beim David-Nachzug wird der Tag auf erledigt gesetzt (Historie bleibt in der Doc):

**🎨 design-nachzug: erledigt** (YYYY-MM-DD) — finale `D-<XXX>`-Optik integriert, Visual-Baseline neu gezogen.

Done setzen weiterhin nur mit expliziter Freigabe und nach dem Abschluss-Audit (plan-ticket §8).

DoD-Mapping — was Interim-UI erfüllt vs. was Nachzug bleibt

DoD Punkt Mit Interim-UI
B 6–10 Sidebar · Permission-Gate · Route · Breadcrumbs · i18n jetzt erfüllbar
B 11/12 Mobile-Tab-Bar · Customer-Portal nur „falls relevant"; bei PWA-only (AD-17) i. d. R. Nachzug/deferred
D 18 VM-Unit-Test jetzt erfüllbar (reine Funktion)
D 19 Smoke-Test e2e/smoke/<modul>.spec.ts jetzt erfüllbar gegen Interim-Screen
D 20 Hot-Swap-Drill (packages/ui-mock) jetzt erfüllbar
D 21 Visual-Regression (M016) gegen Interim-Baseline erfüllbar; Re-Baseline-Pflicht beim David-Nachzug
— finale Subframe-Optik Nachzug (Label design-nachzug)

Refactor-Ablauf, wenn Davids Delta landet

Davids Delta erscheint als: neue/aktualisierte Datei in ../HiveGrid-Wireframes/Tickets/Fertige Tickets/D-*.md

  • Paket-Status im Screen Paket Tracker auf Fertig + design/-Subframe-Links je Screen (Team f023064a5ca0).
  1. VM/Loader/Route unverändert lassen.
  2. Internals von <XPage> gegen Davids Subframe-Screen tauschen (gleiche ~/ui-Components → meist Umstellen/Neuanordnen, kein neuer Datenpfad).
  3. Visual-Baseline neu ziehen (Interim-Snapshot ersetzen), Smoke/Hot-Swap erneut grün.
  4. Plane-Label design-nachzug entfernen; Umsetzungs-Notiz + „Dev-Nachzug"-Sektion der Ticket-Doc mit Datum + Proof ergänzen.

Pro-Ticket-Checkliste (Interim-UI)

  • Interim-<XPage> in apps/web/app/components/screens/<domain>/ aus ~/ui + Layout, VM als Prop.
  • Route rendert <XPage vm={} actions={} />; kein handgeschriebenes Tailwind.
  • Davids Design-Standards befolgt (.planning/INTERIM-UI-DESIGN-STANDARDS.md): Spacing/Padding/ Dialog-Struktur/Control-Höhen/States aus ~/ui-Defaults; Screen-IDs/Naming an Davids Tracker angelehnt.
  • Reachability B 6–10 verdrahtet (Sidebar/Permission/Route/Breadcrumb/i18n).
  • Tests: VM-Unit (18) · Smoke (19) · Hot-Swap (20) · Visual-Regression gegen Interim-Baseline (21).
  • Ticket-Doc (führend): 🎨 design-nachzug: offen-Tag unter der Header-Tabelle und Interim-UI-Vermerk in der „Dev-Nachzug"-Sektion (Muster unten).
  • Plane-Label design-nachzug gesetzt (spiegelt den Doc-Tag).
  • Done nur bei Dev-DoD 100 % + Interim-UI + Tests grün + Freigabe.

Muster: Interim-UI-Vermerk in „Dev-Nachzug (nach Davids D-*-Delta)"

**Interim-UI (Vorschau, Stand YYYY-MM-DD):** Screen aus `~/ui` gebaut —
`apps/web/app/components/screens/<domain>/<Screen>Page.tsx`. Proof: Smoke `e2e/smoke/<modul>.spec.ts`,
Hot-Swap-Drill grün, Interim-Visual-Baseline `<pfad>` (als interim markiert).
Refactor-Nachzug offen: finale Subframe-Optik aus `D-<XXX>` (Plane-Label `design-nachzug`).

Nachzug-Tracking

  • /planning ist führend: Der 🎨 design-nachzug-Tag in .planning/ticket-docs/<ID>.md ist die autoritative Quelle. Offene Nachzüge findet man per grep -rl "design-nachzug: offen" .planning/ticket-docs/ — unabhängig von Plane und ohne API-Zugang.
  • Plane spiegelt: Das Plane-Label design-nachzug (anlegbar über .planning/plane-sync/scrub_plane.py oder manuell via POST /labels/) wird aus dem Doc-Tag abgeleitet und dient nur der Board-Sicht — nie umgekehrt. Divergiert Plane vom Doc, gewinnt das Doc.
  • Es gibt kein Skript, das Plane-Kommentare postet. Kommentar/Status weiter manuell via API (POST /issues/{iid}/comments/, Identität vorab GET users/me); Done nur mit Freigabe.