# 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 `` 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//Page.tsx └─ export function Page({ vm, actions }: { vm: VM; actions: Actions }) { … } komponiert ~/ui-Components als app-chrome-freien Content, rendert vm.data, ruft actions.onX ``` Die Route bleibt beim etablierten Muster und rendert nur: ```tsx // apps/web/app/routes/app.$tenant/._index.tsx export default function XRoute() { const { vm } = useLoaderData(); return ; } ``` Das ist genau das AGENTS.md-Zielmuster `` — 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 `
` — 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 `
` 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`/`placeholder` direkt), KEIN ``-Child. - `Table.Cell`: kennt nur `align-left`/`align-center`; rechtsbündig = Default + `justify-end`-Div. - `BadgeFeedback`: Farb-Prop heißt `farbe`. - `BadgeShortcut`: Props heißen `icon`/`iconRight` (Default-Icon ⌘), NICHT `iconLeft1`/`iconLeft2` aus dem Export; ⇧-Kombos als Text-Children (z. B. `⇧Z`). - `HelpCircle`: hat KEIN `tooltipText` — Tooltip via `SubframeCore.Tooltip.Root/Trigger/Portal/Content asChild` + `~/ui`-`Tooltip` als Content (Muster: `select-tenant.component.tsx`). - Radix `SubframeCore.ContextMenu.Content`: akzeptiert KEIN `side`/`align` (Kontextmenüs positionieren am Pointer) — die Props aus dem Export entfernen, nur `asChild` behalten. ### 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: 1. Sync laufen lassen, dann `git status` sichten und **nur die für das Ticket nötigen Komponenten behalten** (Rest per `git stash`/`checkout` zurück — der volle Stand bleibt im Stash als Referenz). 2. Synchronisierte Komponenten auf **Breaking-API** prüfen (2026-07-18: `KanbanCard` wechselte von `name`/`price`/`topRow` auf Slot-Props `tagsSlot`/`titleSlot`/`valueSlot`/`footer*Slot`) und ALLE Konsumenten im selben PR migrieren — auch fremde Module (LeadBoard), Abhängige müssen grün bleiben. 3. Wrapper wie `SortableKanbanBoard` forwarden neue Props **nicht** automatisch — Interface + Forwarding nachziehen, sonst greifen neue Defaults still (2026-07-18: `showSum=false` zeigte überall „Summe gesperrt" statt der Spaltensumme). ### 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/.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-` ausstehend. ``` Beim David-Nachzug wird der Tag auf erledigt gesetzt (Historie bleibt in der Doc): ```md **🎨 design-nachzug: erledigt** (YYYY-MM-DD) — finale `D-`-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/.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 `` 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-`` in `apps/web/app/components/screens//` aus `~/ui` + Layout, VM als Prop. - [ ] Route rendert ``; kein handgeschriebenes Tailwind. - [ ] Keine rekursive App-Shell: Screen-Komponenten importieren nicht `~/ui/layouts/DefaultPageLayout` und rendern keine zusätzliche Sidebar/Header-Navigation. - [ ] Kein Subframe-Inner-Scroll: `h-full`/`overflow-hidden`-Root und `basis-0`/`overflow-y-auto`-Inhaltsbereich aus dem Page-Export entfernt — Screen läuft im Dokumentfluss, die Shell-`
` 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-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//Page.tsx`. Proof: Smoke `e2e/smoke/.spec.ts`, Hot-Swap-Drill grün, Interim-Visual-Baseline `` (als interim markiert). Refactor-Nachzug offen: finale Subframe-Optik aus `D-` (Plane-Label `design-nachzug`). ``` ## Nachzug-Tracking - **`/planning` ist führend:** Der `🎨 design-nachzug`-Tag in `.planning/ticket-docs/.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. ## 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 ""` — 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: ```sql 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__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: ```sql 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: ```tsx
``` **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.