187 lines
12 KiB
Markdown
187 lines
12 KiB
Markdown
# Interim-UI Design-Standards — „David-nah bauen"
|
||
|
||
**Zweck:** Damit eine Interim-UI (AD-28, `.planning/INTERIM-UI-PLAYBOOK.md`) möglichst nah an Davids
|
||
kommenden finalen Subframe-Screens landet, baut der Dev nach **denselben** Layout-/Komponenten-/State-
|
||
Standards wie David. Dann ist Davids späterer Nachzug fast nur noch Feinschliff.
|
||
|
||
**Quelle & Autorität:** Diese Werte sind ein **In-Repo-Spiegel** von Davids Wireframe-Vault
|
||
`HiveGrid-Wireframes/` (Schwester-Ordner: `../HiveGrid-Wireframes/`, Gitea `git.tool-ctrl.de/david/Hivegrid-Wireframes`).
|
||
Autoritativ ist **immer der Vault**:
|
||
- `../HiveGrid-Wireframes/04 Standards/Subframe UI Standards/Layout/README.md` (Layout-Bibel, Entscheidungen D01–D0x)
|
||
- `../HiveGrid-Wireframes/Tickets/Fertige Tickets/D-D0b Layout Standards.md` (Handoff der Layout-Standards)
|
||
- `../HiveGrid-Wireframes/01 Regeln/Wireframing Playbook.md` + `Screen Agent Workflow.md` (Bau-/State-Regeln)
|
||
- `../HiveGrid-Wireframes/02 Wireframes/Screen Paket Tracker.md` (Screen-/Flow-Liste, Subframe-Links)
|
||
|
||
Der Vault liegt nicht im Cloud-Repo (CI/andere Maschinen haben ihn evtl. nicht) — deshalb dieser Spiegel.
|
||
**Bei Zweifel/Drift den Vault lesen und diese Datei nachziehen.** Davids Werte gewinnen.
|
||
|
||
---
|
||
|
||
## 0. Grundprinzip — Component-Defaults statt manueller Tailwind-Overrides
|
||
|
||
Davids härteste Bau-Regel (Layout-README, „Nutzung bei Subframe-MCP-Arbeit"):
|
||
|
||
> Komponenten-Defaults und Varianten verwenden, wenn sie den Standard bereits korrekt abbilden. Keine
|
||
> manuellen Tailwind-Overrides für Werte, die bereits über Auto Layout, Komponenten oder Varianten
|
||
> abgedeckt sind.
|
||
|
||
Für uns: **`~/ui`-Component-Defaults sind führend.** Wenn `Button`, `TextInput`, `Table`, `Dialog`, `Card`
|
||
das Padding/Gap/die Höhe schon intern richtig haben → Component + passende Variante nutzen, **nicht**
|
||
Höhen/Paddings mit Tailwind nachbauen. Manuelle Werte nur für feste Größen, Max-Breiten, Scroll/Overflow
|
||
oder responsive Constraints. Die Zahlen unten sind zum Prüfen/Setzen dort, wo eine Komponente sie nicht
|
||
selbst mitbringt — nicht zum Überschreiben funktionierender Defaults.
|
||
|
||
---
|
||
|
||
## 1. Spacing-Skala (D01) — 8px-Rhythmus
|
||
|
||
Erlaubte Layout-Werte (px): **4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96**.
|
||
- `8` = Basislogik für normale Gaps/Paddings. `4/12/20` = kompakte Zwischenwerte (Field-Anatomy, kleine
|
||
Icon-/Text-Abstände). `2` nur für Border-/Focus-/Icon-Feintuning.
|
||
- **Nicht neu einführen:** 6, 10, 14, 28, 36, 44 — nur wenn eine bestehende Komponente/ein Token sie schon mitbringt.
|
||
|
||
## 2. Page / Card / Grid-Padding (D02)
|
||
|
||
| Rolle | Wert |
|
||
|---|---|
|
||
| Page Padding (Standard & Minimum) | **24px** (nie darunter) |
|
||
| Card / Surface Padding | **16px** |
|
||
| Detail-/Editor-Surface Padding | **16px** |
|
||
| Grid / Card Gap | **16px** (kompakter Sonderfall 12px) |
|
||
| Section Gap (größere Bereiche) | **24px** |
|
||
|
||
Kompakte Momente reduzieren **nur lokale Gaps**, nie das Page Padding. `32px` ist **kein** freier Standard
|
||
für Detail-/Editorflächen — Ausnahme: die `Dialog`-Komponente darf eine 32px-Variante haben. Mobile-Padding = Backlog.
|
||
|
||
## 3. Text-Rhythmus (D03) — nur mit 150%-Text-Tokens für beschreibende Texte
|
||
|
||
| Zwischenraum | Gap |
|
||
|---|---|
|
||
| Page Title → Page Description | **0px** |
|
||
| Page Header → erster Content | **24px** |
|
||
| Section Title → Section Description | **0px** |
|
||
| Section Description → Section Content | **12px** |
|
||
|
||
`0px` ist ein bewusster Gap (kein Auto-Layout-Abstand). Beschreibungen nutzen **150%-Line-height-Tokens**
|
||
(auch bei einer Zeile). `0`-Line-height-Token nur für garantierte Einzeiler (Button-Label, Badge, Tab,
|
||
kompakte Truncation-Zelle), **nie** für umbrechbaren Text.
|
||
|
||
## 4. Formulare & Field-Anatomy
|
||
|
||
- **Field-Gap** zwischen kompletten Feld-Komponenten: **16px** (kompakt 12px; bewusst getrennte Sections 24px).
|
||
- **Field-Anatomy** (Reihenfolge `label → helpText → Control → message`):
|
||
`label → helpText` **8px** · `helpText → Control` **6px** · `Control → message` **4px** · `message` = 12px, Medium.
|
||
- Beschreibungen/Hilfetexte über die Component-Props/Slots füllen, **nicht** als freie Textblöcke daneben bauen.
|
||
- **Feldnamen (Vokabular):** unterer Field-Text heißt immer **`message`** (nicht `label`/`helper`/`helpText`).
|
||
- Form-Input horizontales Innenpadding: **12px** (ohne Icon / Rand↔Icon), Icon↔Text **8px** (Textarea ausgenommen).
|
||
- Form-Input-Radius: **`Radius Small` = 4px**.
|
||
|
||
## 5. Control-Höhen & Radius
|
||
|
||
- **Control-Höhen (exakt):** Small **32px** · Medium **36px** · Large **48px**. **Medium ist Default**
|
||
(heißt aber `Medium`, nicht `Default`). Gilt für Button, IconButton, TextInput, NumberInput, Select,
|
||
Multiselect(+Tags), Combobox, SearchInput, DatePicker (Single), ToggleGroup, ButtonGroup.
|
||
- **Radius-Tokens:** Small **4px** · Medium **8px** · Large **12px** · Round **9999px**.
|
||
- **Button:** Default-Variante = Medium = 36px hoch. Button-Höhe/-Padding **nicht** im Screen nachbauen.
|
||
- **Table:** Row-Height/Cell-Padding/Header-Dichte über die Table-Komponente (Carbon-Referenz: Rows
|
||
xs 24 / sm 32 / md 40 / lg 48 / xl 64, Column-Padding 16). Dichte wählen statt eigene Tabellenwerte setzen.
|
||
|
||
## 6. Dialoge / Modale (D07) — echte Dialog-Struktur
|
||
|
||
**Modal = in `~/ui` immer die echte `Dialog`-Komponente** (`DialogLayout → Dialog → Dialog.Content`).
|
||
**Verboten:** Modal aus `Card`, freiem `div`, absolutem Overlay, Blur-Hintergrund oder Fullscreen-Wrapper
|
||
nur visuell nachbauen. Vor Handoff prüfen, dass `Dialog` importiert ist und `Dialog.Content` im JSX steht.
|
||
|
||
**Ort-Begriffe:** `Page` = eigener App-Ort (Settings etc.) · `Dialog` = temporäres zentriertes Overlay ·
|
||
`Fullscreen Dialog` = viewport-füllendes Overlay (nicht für dauerhafte Bereiche) · `Drawer/Side Panel` =
|
||
seitliches Overlay (eigene Breitenregel).
|
||
|
||
| Dialog-Größe | Breite | wofür |
|
||
|---|---|---|
|
||
| XS | **420px** | kurze Bestätigung / knapper Hinweis |
|
||
| S | **560px** | kleines Formular, wenige Felder |
|
||
| M | **720px** | normales Formular / kurze Section-Struktur |
|
||
| L | **1200px max** | großer Editor mit Navigation/Suche |
|
||
|
||
- **Dialog-Padding:** **16px** Default, **32px** ruhigere Variante — über die Dialog-Variante, nicht per Override.
|
||
- **Dialog-Interne Gaps:** Title→Description **8px** · Field/Form-Row **16px** · Section-Gap **24px** ·
|
||
Footer-Button-Gap **8px**. **Footer-Actions rechts** ausgerichtet.
|
||
- Breitenklasse bleibt fix (wächst nicht auf 4K mit), nur der Overlay-Rand wächst; auf kleinen Viewports
|
||
Max-Width relativ zum Viewport. Fullscreen: Rand 24px/Seite, `width: calc(100vw - 48px)`, `height: calc(100vh - 48px)`.
|
||
|
||
## 7. Zustände (D09) — inline State-Komponenten, keine eigenen Screens
|
||
|
||
**Empty / Loading / Permission-Denied sind inline State-Komponenten, keine Modale und keine eigenen Screens**,
|
||
solange sie dem Standard entsprechen. In `~/ui`: `EmptyState`, `ErrorState`, `SkeletonText`/`Loader`, plus
|
||
Permission-Denied. (Erinnerung DoD/Bauprinzip: Permission-Denied zeigt **404, nicht 403**.)
|
||
|
||
**Nur** blockierende / sicherheits- / copy-kritische Zustände bekommen eigene Screens. Ein **blockierender
|
||
Error-State** braucht: Titel/Kernaussage · Ursache in Nutzersprache · Primäraktion · Sekundäraktion (zurück/Support).
|
||
|
||
## 8. Banner / Toast / Modal / Inline / Screen — Entscheidungs-Hierarchie
|
||
|
||
| UI-Form | Wann | `~/ui` | eigener Screen? |
|
||
|---|---|---|---|
|
||
| **Inline** | betrifft genau ein Feld, dort korrigierbar (Pflichtfeld, ungültige Mail, 2FA-Code falsch) | Field-`message` | nein |
|
||
| **Screen-Banner** | betrifft aktuellen Screen/Formular (Login falsch, Speichern fehlgeschlagen, Integration getrennt) | `BannerAlert`/`Alert` | nur wenn optisch/fachlich wichtig |
|
||
| **Globaler Banner** | App/Shell/Tenant (Zahlung offen, Tenant gesperrt, Wartung) | App-Shell/D0 | D0 |
|
||
| **Toast** | kurze, nicht-blockierende Rückmeldung (gespeichert, kopiert, Export gestartet) | `Toast` | nein |
|
||
| **Modal/Dialog** | Nutzer bestätigt/entscheidet kurz, bleibt im Kontext (löschen, Rolle wechseln) | echter `Dialog` | falls eigener Entscheidmoment |
|
||
| **Eigener Screen** | Nutzer blockiert / neuer Flow-Status (Link abgelaufen, Magic-Link gesendet, Account gesperrt) | eigene Route | ja |
|
||
|
||
Faustregel: direkt im Feld korrigierbar → Inline; bleibt im Screen → Banner; kurze Rückmeldung → Toast;
|
||
muss bestätigen → Modal; blockiert → eigener Screen. Sicherheit/Zugang/Vertrauen/Recht → **eher Banner/Screen, nie Toast**.
|
||
|
||
## 9. Copy ist eine Design-Entscheidung
|
||
|
||
Bei **copy-kritischen** Zuständen (Auth, Sicherheit, Zugang, Erfolg — z.B. „Magic-Link gesendet",
|
||
„E-Mail oder Passwort ist nicht korrekt" (neutral, keine Enumeration), „Account gesperrt") den Text
|
||
**nicht selbst erfinden**. Entweder die im Screen-Paket dokumentierte Copy übernehmen oder Platzhalter-Copy
|
||
**klar als interim markieren** (i18n-Key mit `TODO`/interim-Hinweis), damit Davids Copy leicht einsetzbar ist.
|
||
Field-Validierung (Pflichtfeld, Passwort zu schwach) bleibt beim Form-Kit, kein eigener Zustand — außer fachlich/rechtlich wichtig.
|
||
|
||
## 10. Weitere Konventionen
|
||
|
||
- **Default-Ansicht = Admin**, außer der Flow braucht sichtbar eine andere Rolle (dann Variante).
|
||
- **Vokabular:** `Medium` (nicht `Default`) · `message` (nicht `label`) · `error` ≠ `destructive` (getrennt halten) ·
|
||
States `default/hover/active/focus/disabled/loading/error/selected` (`focus`≠`selected`).
|
||
- **Prop-Reihenfolge** (falls du Component-APIs baust): Zustand → Erscheinung → Größe → Layout-Sonderfälle →
|
||
Sichtbarkeit → Inhalt/Slots (Details in `07_Global-Rules.md` des Vaults).
|
||
|
||
---
|
||
|
||
## 11. Verzahnung mit Davids Screen-Format (gleiche Sprache sprechen)
|
||
|
||
Damit der spätere Swap trivial wird, benennt und strukturiert die Interim-UI wie Davids Vault:
|
||
|
||
- **Screen-IDs übernehmen:** `S` = eigener Screen · `V` = Variante · `M` = Modal · `D` = dokumentierter
|
||
Zustand (kein Frame). Namen 1:1 wie im **Screen Paket Tracker** (z.B. „S01 Login", „S04 2FA Code eingeben",
|
||
„M02 Rolle bearbeiten", „V01 Login falsche Daten"). Interim-`<XPage>`-Dateien/Komponenten nach diesen IDs benennen.
|
||
- **Join-Schlüssel `ticket: D-*`:** Davids Pakete/Screens tragen `ticket: D-P2` (usw.) im Frontmatter — das
|
||
ist die Brücke zwischen unserem Cloud-Dev-Ticket und seinen Screens. Im Interim-UI-Vermerk der Ticket-Doc
|
||
das zugehörige `D-*` nennen (steht ohnehin im „blocked-by"/Screens-Block).
|
||
- **Subframe-Links:** Sobald Davids Paket auf `In Subframe`/`Review`/`Fertig` steht, hat **jeder Screen einen
|
||
`design/`-Deep-Link** (Team `f023064a5ca0`) im Tracker + Screen-Frontmatter, das Paket einen `flow/`-Link.
|
||
Diese sind die Vorlage für die Interim-UI (annähern) und später die Quelle des finalen Nachzugs.
|
||
- **Zustände-Tabelle** je Screen (`Zustand | Beschreibung | Umsetzung` mit Kanon Leer/Laden/Fehler/Keine
|
||
Berechtigung, Umsetzung-Enum Bauen/Wiederverwenden/Nur dokumentieren/Später/Raus) übernehmen, damit klar
|
||
ist, was Interim baut vs. dokumentiert.
|
||
|
||
**Nachzug-Trigger:** Wenn Davids Handoff kommt (neue/aktualisierte Datei in
|
||
`../HiveGrid-Wireframes/Tickets/Fertige Tickets/D-*.md` + Paket-Status im Tracker auf `Fertig`), zieht der
|
||
Dev die `design/`-Screens nach (siehe Refactor-Ablauf im Playbook), setzt den `🎨 design-nachzug`-Tag auf
|
||
erledigt und zieht die Visual-Baseline neu.
|
||
|
||
---
|
||
|
||
## 12. Checkliste „David-nah" (pro Interim-Screen)
|
||
|
||
- [ ] Aus `~/ui`-Components + Layout gebaut, VM als Prop, kein handgeschriebenes Tailwind für Spacing/Höhen.
|
||
- [ ] Page 24 · Card/Surface 16 · Grid-Gap 16 · Section-Gap 24 · Field-Gap 16 · Text-Rhythmus (0/24/0/12).
|
||
- [ ] Controls: Medium(36) Default, Radius small(4) an Inputs; Button/Table-Dichte aus der Komponente.
|
||
- [ ] Modale als echter `Dialog` (`DialogLayout → Dialog → Dialog.Content`), Größe XS420/S560/M720/L1200, Padding 16/32, Footer rechts.
|
||
- [ ] Empty/Loading/Permission als inline State-Komponenten (Permission-Denied = 404), keine Extra-Screens.
|
||
- [ ] Banner/Toast/Modal/Inline/Screen nach Hierarchie (§8) gewählt.
|
||
- [ ] Copy-kritische Texte nicht erfunden — dokumentierte Copy oder interim-markierter Platzhalter.
|
||
- [ ] Screen-IDs/Namen an Davids Tracker angelehnt; `D-*`-Bezug im Interim-UI-Vermerk notiert.
|