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

167 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```tsx
// 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/`):
```md
**🎨 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):
```md
**🎨 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)"
```md
**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.