167 lines
9.5 KiB
Markdown
167 lines
9.5 KiB
Markdown
# 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.
|