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

187 lines
12 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 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.