Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/INTERIM-UI-DESIGN-STANDARDS.md
T
raffaelandClaude Opus 5.5 d09f79b673 chore(infra): Gitea-Host auf git.hg-int.dev umstellen
Gitea läuft seit 2026-11-11 auf hivegrid-control (git.hg-int.dev);
git.tool-ctrl.de wird abgeschaltet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:53:32 +01:00

12 KiB
Raw Blame History

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.hg-int.dev/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.