19 KiB
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:
- 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); - seine Daten aus dem bestehenden View-Model (
packages/view-models/**) beziehen, das als Prop hereingereicht wird; - 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 als app-chrome-freien Content, 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.
App-Shell-Grenze: keine rekursive Subframe-Sidebar
Die HiveGrid-App-Routes laufen bereits innerhalb der echten App-Shell mit Sidebar, Tenant-Layout und
Navigation. Deshalb dürfen Screen-Komponenten unter apps/web/app/components/screens/** keine
generierten Subframe-Page-Layouts rendern, die selbst App-Chrome enthalten, insbesondere nicht
~/ui/layouts/DefaultPageLayout. Dieses Layout bringt eine eigene Beispiel-Sidebar inklusive Logo/Nav mit
und erzeugt sonst eine doppelte Sidebar in der App. Erlaubt sind app-chrome-freie Content-Shells aus div/
section plus ~/ui-Komponenten. DialogLayout und DrawerLayout bleiben für echte Modale/Drawer erlaubt,
wenn sie nicht zusätzlich App-Navigation rendern.
Scroll-Verhalten: Dokumentfluss statt Subframe-Inner-Scroll
Subframe-Page-Exporte kommen mit einem eigenen Scroll-Gerüst: Screen-Root
h-full min-h-[0px] … overflow-hidden plus Inhaltsbereich grow shrink-0 basis-0 … overflow-y-auto.
Das funktioniert nur, wenn der Screen eine definite Höhe vom Parent erbt. Die SubframeAppShell rendert
Screens aber in ein block-level <main class="flex-1 overflow-auto"> — dort kollabiert der
basis-0-Bereich auf 0px und der komplette Inhalt ist unsichtbar (im DOM vorhanden, Höhe 0; so
geschehen bei WF-P16 S00/S02 und den Automations-Übersichten, 2026-07-10). Beim Integrieren deshalb
beide Klassen-Sets entfernen und den Screen im normalen Dokumentfluss rendern — das Scrollen
übernimmt die <main> der Shell (wie bei allen anderen App-Screens). Der Guard-Test
apps/web/app/components/screens/subframe-layout-boundary.test.ts schlägt bei dem Muster statisch fehl.
Lokales UI-Kit ≠ Cloud-Export: bekannte Prop-Abweichungen
Der Subframe-Cloud-Export nutzt teils andere Prop-APIs als das lokale Kit unter apps/web/app/ui.
Bei Unsicherheit die Komponente lesen. Real getroffen (Stand 2026-07-13):
SearchInput: flache Props (value/onChange/placeholderdirekt), KEIN<SearchInput.Input>-Child.Table.Cell: kennt nuralign-left/align-center; rechtsbündig = Default +justify-end-Div.BadgeFeedback: Farb-Prop heißtfarbe.BadgeShortcut: Props heißenicon/iconRight(Default-Icon ⌘), NICHTiconLeft1/iconLeft2aus dem Export; ⇧-Kombos als Text-Children (z. B.⇧Z).HelpCircle: hat KEINtooltipText— Tooltip viaSubframeCore.Tooltip.Root/Trigger/Portal/Content asChild+~/ui-Tooltipals Content (Muster:select-tenant.component.tsx).- Radix
SubframeCore.ContextMenu.Content: akzeptiert KEINside/align(Kontextmenüs positionieren am Pointer) — die Props aus dem Export entfernen, nurasChildbehalten.
Component-Sync: nie blind sync --all übernehmen (real getroffen 2026-07-18)
pnpm subframe:sync (@subframe/cli sync --all) schreibt den kompletten Cloud-Stand nach
apps/web/app/ui — inklusive Löschungen: lokale Komponenten ohne Cloud-Pendant
(ConfirmDialog, ResultDialog, layers.ts, …) und sogar colocated Testdateien
(Dialog.layering.test.tsx) flogen raus; parallel kamen umbenannte Duplikate (DialogFullscreen
neben FullscreenDialog) rein. Vorgehen:
- Sync laufen lassen, dann
git statussichten und nur die für das Ticket nötigen Komponenten behalten (Rest pergit stash/checkoutzurück — der volle Stand bleibt im Stash als Referenz). - Synchronisierte Komponenten auf Breaking-API prüfen (2026-07-18:
KanbanCardwechselte vonname/price/topRowauf Slot-PropstagsSlot/titleSlot/valueSlot/footer*Slot) und ALLE Konsumenten im selben PR migrieren — auch fremde Module (LeadBoard), Abhängige müssen grün bleiben. - Wrapper wie
SortableKanbanBoardforwarden neue Props nicht automatisch — Interface + Forwarding nachziehen, sonst greifen neue Defaults still (2026-07-18:showSum=falsezeigte überall „Summe gesperrt" statt der Spaltensumme).
Layer-Regeln bleiben unangetastet
Die drei Anti-Patterns (AGENTS.md) gelten weiter:
- kein
@prisma/client/~/dbinpackages/ui-app/**; - kein
packages/ui-subframe-Direktimport inapp/routes/**; - kein
useLoaderDatainpackages/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
~/uisteht (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 DavidsD-*-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 TrackeraufFertig+design/-Subframe-Links je Screen (Teamf023064a5ca0).
- VM/Loader/Route unverändert lassen.
- Internals von
<XPage>gegen Davids Subframe-Screen tauschen (gleiche~/ui-Components → meist Umstellen/Neuanordnen, kein neuer Datenpfad). - Visual-Baseline neu ziehen (Interim-Snapshot ersetzen), Smoke/Hot-Swap erneut grün.
- Plane-Label
design-nachzugentfernen; Umsetzungs-Notiz + „Dev-Nachzug"-Sektion der Ticket-Doc mit Datum + Proof ergänzen.
Pro-Ticket-Checkliste (Interim-UI)
- Interim-
<XPage>inapps/web/app/components/screens/<domain>/aus~/ui+ Layout, VM als Prop. - Route rendert
<XPage vm={} actions={} />; kein handgeschriebenes Tailwind. - Keine rekursive App-Shell: Screen-Komponenten importieren nicht
~/ui/layouts/DefaultPageLayoutund rendern keine zusätzliche Sidebar/Header-Navigation. - Kein Subframe-Inner-Scroll:
h-full/overflow-hidden-Root undbasis-0/overflow-y-auto-Inhaltsbereich aus dem Page-Export entfernt — Screen läuft im Dokumentfluss, die Shell-<main>scrollt (siehe §„Scroll-Verhalten"). - 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-nachzuggesetzt (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
/planningist führend: Der🎨 design-nachzug-Tag in.planning/ticket-docs/<ID>.mdist die autoritative Quelle. Offene Nachzüge findet man pergrep -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.pyoder manuell viaPOST /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 vorabGET users/me); Done nur mit Freigabe.
Footgun: FK-Constraints auf Tabellen unter FORCE ROW LEVEL SECURITY
Symptom. Eine Migration, die eine Foreign Key Constraint anlegt, bricht ab mit
ERROR: query would be affected by row-level security policy for table "<X>" —
obwohl der Migrator der Tabellen-Owner ist.
Ursache. Seit dem App-weiten RLS-Cutover tragen die Tabellen FORCE ROW LEVEL SECURITY, und FORCE gilt auch für den Owner. Postgres validiert eine neue
FK-Constraint mit einem internen SELECT über die betroffenen Tabellen, und
genau dieses SELECT wird von der Policy abgelehnt. Es trifft beide Seiten:
die Tabelle, die die Constraint bekommt, und die referenzierte Tabelle.
Fix. FORCE für die Dauer der Constraint-Erzeugung abschalten und sofort
wieder setzen. Die Policy selbst bleibt die ganze Zeit aktiviert, und im
Fenster steht kein DML — es ist also kein Sicherheitsloch:
ALTER TABLE "Pipeline" NO FORCE ROW LEVEL SECURITY;
ALTER TABLE "Pipeline" ADD CONSTRAINT "…_fkey" FOREIGN KEY (…) REFERENCES "Pipeline"("id") …;
ALTER TABLE "PipelineFieldGroup" ADD CONSTRAINT "…_fkey" FOREIGN KEY (…) REFERENCES "Pipeline"("id") …;
ALTER TABLE "Pipeline" FORCE ROW LEVEL SECURITY;
Merke. Mehrere FKs auf dieselbe Zieltabelle in ein Fenster packen, statt
FORCE mehrfach zu togglen. Neu angelegte Tabellen sind nicht betroffen,
solange ihre Policies erst am Ende der Migration gesetzt werden — das ist ein
weiterer Grund, den RLS-Block ans Ende des Migrationsfiles zu stellen.
Gefunden: 2026-07-28, WF-P8-Baseline (20260728120000_wf_p8_subframe_baseline).
Der Fehler erscheint erst bei verify:migrations-parity bzw. beim Replay gegen
eine leere DB, nicht beim lokalen prisma db push — der Feature-Branch-Pfad
verschleiert ihn also.
Footgun: eine neue Relation kann die Policy-Form einer bestehenden Tabelle kippen
Symptom. verify:rls-live meldet gegen die frische Migrationskette
rls_expected_policy_mismatch und rls_unexpected_policy, obwohl
verify:tenant-policy-contract --check grün ist und die Migration für jede neue
Tabelle brav eine Policy anlegt.
Ursache. Der Generator entscheidet die Form der Policies aus dem Modell:
eine Tabelle mit direktem tenantId bekommt eine FOR ALL-Policy
(hg_<T>_all), eine Tabelle mit abgeleiteter Ownership bekommt vier
Per-Command-Policies (_select/_insert/_update/_delete). Fügt man einer
bestehenden Tabelle eine Relation hinzu, kann sie dadurch zum
Derived-Ownership-Modell werden und ihre Policy-Form wechseln. Bei WF-P8 hat
genau das die Selbstrelation Pipeline.nachfolgePipelineId ausgelöst:
hg_Pipeline_all → vier Policies.
Fix. Die Policy-DDL nie von Hand schreiben, sondern wörtlich aus
prisma/rls/tenant-policy-contract-isolation.sql in die Migration kopieren —
inklusive der Tabellen, die man gar nicht angefasst zu haben glaubt. Die alte
Policy muss dabei explizit gedroppt werden:
DROP POLICY IF EXISTS "hg_Pipeline_all" ON "Pipeline";
-- danach die vier generierten Per-Command-Policies
Merke. Postgres verknüpft permissive Policies mit ODER. Eine
stehengebliebene alte Policy hebt die neue also nicht auf, sondern hält den
schwächeren Ausdruck daneben am Leben — ein stiller Sicherheitsverlust, den
kein Test bemerkt, der nur „Zeile sichtbar?" prüft. Ein git diff gegen
packages/db/src/rls-runtime-contract.generated.ts zeigt nach jeder
Schema-Änderung sofort, welche Tabellen ihre Policy-Form gewechselt haben.
Gefunden: 2026-07-28, WF-P8-Baseline. Sichtbar nur in verify:rls-live,
Database Checks und Docker Smoke — lokal auf RLS_RUNTIME_MODE=off nicht.
Footgun: ~/ui-Felder in einer umbrechenden Flex-Zeile
Symptom. Mehrere Eingabefelder nebeneinander rendern kaputt: jedes Feld steht auf einer eigenen, sehr hohen Zeile, das Label klebt weit über dem Input und kollidiert mit dem nächsten Feld. Im DOM ist die Reihenfolge korrekt — es ist rein Layout.
Ursache. Die Roots von ~/ui-TextInput/Select tragen selbst
h-full w-full … justify-center. Als Flex-Kind beansprucht ein solches Feld
damit die ganze Zeile (eine flex-wrap-Zeile bricht also nach jedem Feld
um) und dehnt sich zusätzlich auf die Zeilenhöhe, wobei justify-center den
Input in der Mitte dieser Höhe parkt.
Fix. Die Zeile als Grid auslegen, dann füllt jedes Feld seine Spur:
<div className="grid w-full items-end gap-3 sm:grid-cols-2">
<TextInput className="w-full" … />
<TextInput className="w-full" … />
</div>
Merke. className="grow" hilft nicht — es überschreibt das w-full des
Feldes nicht. Eine nicht umbrechende flex-Zeile ist dagegen unkritisch, weil
die Felder dort schlicht schrumpfen. Guard:
apps/web/app/components/screens/subframe-layout-boundary.test.ts.
Gefunden: 2026-07-29, WF-P8 „Termin erstellen" (S02-T) und S05 „Neue Feldgruppe". Nur im Browser sichtbar, nicht im Unit-Test.