Amadeni
Werkstatt

Regelwerk

UX-Regeln für Amadeni-Anwendungen

Diese Regeln gelten für jede Oberfläche, die wir bauen, auch für die, die ein Agent baut. Jede Regel hat eine Seite in der Werkstatt der Showcase-Seite (/werkstatt), die zeigt, wie es ohne die Regel aussieht und wie mit ihr. Die Regeln sind ein erster Entwurf aus unseren Projekten und wachsen mit der Design-Zusammenarbeit weiter.

Die Bausteine, auf die R9–R13 verweisen, stehen mit Anatomie im Blöcke-Katalog (/bloecke, docs/bloecke.md).

Kurzform für Agenten: Vor dem Bauen einer Seite die passenden Regeln lesen. Weicht eine Seite bewusst ab, steht der Grund als Kommentar im Code.

R1

Meldungen verschieben keine Nachbarn

Eine Fehlermeldung oder ein Hinweis unter einem Feld darf Label und Eingabe im Nachbarfeld nicht verschieben. Der Abstand zwischen Label und Eingabe ist überall gleich.

  • FormItem und Field aus der Bibliothek halten das ein; eigene Wrapper in Formular-Grids brauchen content-start (Grid) oder eine Flex-Spalte.
  • Meldungen stehen direkt unter ihrem Feld, nicht gesammelt über dem Formular.
  • Kommt oder geht eine Meldung, bleibt das Feld dasselbe Element: Der Fokus bleibt beim Tippen erhalten. Die Bibliothek sorgt dafür, sobald error oder hint übergeben wird, auch als undefined.
In der Werkstatt: Lange Formulare im Dialog

R2

Seitenspalten bleiben stehen

Eine Spalte neben dem Hauptinhalt (Hinweise, Zusammenfassung, nächste Schritte) bleibt ab Desktop-Breite unter dem Header stehen, statt beim Scrollen eine Leerfläche zu lassen. Ist sie höher als das Fenster, scrollt sie für sich, unabhängig vom Inhalt.

  • Klassen: lg:sticky lg:top-24 lg:self-start lg:max-h-[calc(100dvh-7rem)] lg:overflow-y-auto.
  • Auf dem Handy steht die Spalte unter dem Inhalt und scrollt normal mit.

R3

Aktionen bleiben sichtbar

Speichern und Abbrechen stehen in Dialogen und langen Formularen in einer festen Fußzeile. Nur der Inhalt dazwischen scrollt. Niemand muss ans Ende scrollen, um zu speichern.

  • Die Hauptaktion steht rechts und benennt, was passiert („Anlage speichern“, nicht „OK“).
  • Ist das Formular ungültig, bleibt der Button aktiv. Klick springt zum ersten Fehler und nennt die Zahl der Fehler.
In der Werkstatt: Lange Formulare im Dialog

R4

Dialoge bleiben kurz und gegliedert

Ein Dialog mit mehr als etwa acht Feldern gliedert sie in benannte Abschnitte. Ab etwa zwanzig Feldern, Unteransichten oder eigenen Tabellen wird daraus eine eigene Seite.

  • Pflichtfelder zuerst und nie eingeklappt. Einklappen nur für wirklich Optionales.
  • Schließen mit ungespeicherten Eingaben fragt auf Deutsch nach (askBeforeClosing), aber nur, wenn wirklich etwas eingegeben wurde. Abbrechen, X und Escape laufen durch dieselbe Rückfrage (DialogClose statt open direkt zu setzen).
  • Kein Dialog öffnet einen weiteren Dialog, außer der Rückfrage selbst.
  • Ein Datumsfeld (DateInput) und ein Zahlenfeld (NumericInput) für alles, im deutschen Format.
In der Werkstatt: Lange Formulare im Dialog

R5

Eine Hauptaktion pro Eintrag

In Listen, über die entschieden wird, hat jeder Eintrag genau eine hervorgehobene Aktion: die empfohlene. Alles andere ist zurückhaltend gestaltet oder liegt im Menü.

  • Die Empfehlung steht als Satz am Eintrag („Empfehlung: bündeln mit 2 ähnlichen Befunden“), nicht nur als Farbe.
  • Gleich laute Knöpfe nebeneinander sind ein Fehler.
  • Die KI empfiehlt, ein Mensch entscheidet. Sammelaktionen übernehmen nur sichere Empfehlungen; Unsicheres bleibt zum Einzelentscheid stehen.
  • Ablehnen im Eintrag ist zurückhaltend rot (destructive), kräftiges Rot (danger) nur im Bestätigungsdialog für Endgültiges.
  • Viele Einträge mit Details: links eine Auswahlliste (SidebarList), rechts der gewählte Eintrag, statt Karten mit eigenen Knöpfen untereinander.
In der Werkstatt: Entscheidungen abarbeiten

R6

Entscheidungen zeigen Fortschritt und lassen sich zurücknehmen

Wer eine Liste abarbeitet, sieht, wie viel noch offen ist, und kann die letzte Entscheidung zurücknehmen.

  • Kopf mit Zähler („3 von 12 offen“) und Sortierung nach Dringlichkeit.
  • Nach dem Entscheiden verschwindet der Eintrag mit einem Toast samt „Rückgängig“. Nachfragen („Wirklich?“) nur bei endgültigen Aktionen.
  • Leere Liste sagt, dass alles erledigt ist, und was als Nächstes kommt.
In der Werkstatt: Entscheidungen abarbeiten

R7

Lange Läufe zeigen Schritte statt Spinner

Alles, was länger als etwa drei Sekunden dauert, zeigt benannte Schritte, die vergangene Zeit und eine Erwartung („dauert meist 1 bis 2 Minuten“).

  • Der Lauf gehört dem Server, nicht dem Browser-Tab. Die Seite darf verlassen werden; der Stand ist beim Wiederkommen noch da.
  • Eingaben bleiben während des Laufs sichtbar und werden nicht gesperrt, wenn der Lauf sie nicht braucht.
In der Werkstatt: Lange Läufe im Hintergrund

R8

Fehler sagen, was passiert ist und was man tun kann

Eine Fehlermeldung nennt in einem Satz, was nicht geklappt hat, ob Eingaben erhalten sind und was man jetzt tun kann. „Server Error“ allein ist nie eine Meldung.

  • Fachliche Fehler (ConvexError mit data) zeigen den Text aus data. Technische Details stehen eingeklappt darunter.
  • Immer ein nächster Schritt: „Erneut versuchen“, „Entwurf behalten und später weitermachen“ oder ein Kontakt. Eingaben gehen bei einem Fehler nie verloren.
  • Ein Fehler bleibt dort, wo er entsteht: am Feld, am Eintrag, am Bild. Der Rest der Seite bleibt bedienbar.
  • Meldungen im Fluss sind getönte Alerts (destructive, warning, success, info), keine selbst gebauten farbigen Kästen.
In der Werkstatt: Lange Läufe im Hintergrund

R9

Nichts sendet sich selbst

Was das Haus verlässt (an Kundinnen, an KI-Modelle, an Dritte), geht erst auf einen ausdrücklichen Klick raus. Der Sendeschritt nennt, was rausgeht, an wen und was vorher verändert wurde.

  • Der Knopf benennt die Folge („Zustimmen und an die KI übermitteln“), nicht „Weiter“.
  • Prüfungen dürfen im Hintergrund vorlaufen, während jemand schreibt; das Senden selbst passiert nie automatisch.
  • Vorher steht da, was übermittelt wird: Empfänger, Inhalte, Schwärzungen.
In der Werkstatt: Lange Läufe im Hintergrund

R10

Objektseiten haben einen leichten Kopf

Eine Seite zu einem Objekt (Projekt, Abrechnung, Objektakte) zeigt oben nur, was man zum Orientieren braucht, und gibt den Platz den Tabs und dem Inhalt.

  • Kopf in einer Zeile: Zurück, Titel, ein Status, eine Hauptaktion; alles Weitere im Menü ⋯. Metadaten und Kennzahlen gehören in einen Tab.
  • Tabs als waagerecht scrollende Zeile (ScrollRow), die oben stehen bleibt; der aktive Tab steht in der URL. Keine Tabs in Tabs.
  • Ein Zeitraum (Monat, Jahr) steht nur im Kopf, wenn er für jeden Tab gilt. Sonst steht er im Tab, der ihn braucht.
  • Ein Tab beginnt mit seinem Inhalt oder seiner Werkzeugleiste, nicht mit einer Überschrift, die das Tab-Label wiederholt.
  • Referenz: src/app/[locale]/werkstatt/objektseite/soll.tsx.
In der Werkstatt: Objektseiten mit Tabs

R11

Datenlisten tragen ihre Werkzeuge an der Tabelle

Eine Liste mit vielen Einträgen hat genau eine Werkzeugleiste, direkt über der Tabelle, und sagt ehrlich, wie viel sie zeigt.

  • Werkzeugleiste: Suche, Filter, Ansicht, Export, rechts die Hauptaktion. Aktive Filter stehen als entfernbare Chips darunter.
  • Kennzahlen nur, wenn sie etwas anderes sagen als die Liste. Status-Zähler sind Segmente, die zugleich filtern, keine Kacheln darüber.
  • Checkboxen nur mit Sammelaktion. Bei Auswahl wird die Werkzeugleiste zur Sammelleiste („3 gewählt: Als versendet markieren“).
  • Nie still abschneiden: „100 von 340 · Mehr laden“.
  • Auf dem Handy wird jede Zeile ein Listeneintrag (Titel, eine Zahl, Status); alles Weitere zeigt das Detail.
  • Referenz: src/app/[locale]/werkstatt/datenliste/soll.tsx.
In der Werkstatt: Datenlisten mit Filtern

R12

Eine Seite beantwortet eine Frage

Seiten, auf denen sich Karten mit eigenen Filtern und Knöpfen stapeln, werden aufgeteilt, bevor sie unübersichtlich werden.

  • Hat ein Block eigene Filter, eine eigene Liste oder eigene Aktionen, ist er ein eigener Tab oder eine eigene Seite, keine Karte.
  • Ein Filterbereich oben gilt für alles darunter.
  • Abschnitte sind Überschrift plus Inhalt, ohne Rahmen um Rahmen; keine Karte in einer Karte.
  • Kennzahlen als eine ruhige Zahlenzeile, nicht als Kachelraster.
  • Referenz: src/app/[locale]/werkstatt/sammelseite/soll.tsx.
In der Werkstatt: Seiten voller Karten

R13

Auf dem Handy eine App, keine geschrumpfte Website

Unter 640 px verhält sich jede Anwendung wie eine App.

  • Kompakte Kopfzeile: Zurück, Titel, höchstens eine Aktion. Keine Hero-Blöcke, keine Kennzahlenkarten vor dem Inhalt.
  • Hauptnavigation unten in Daumenreichweite (höchstens fünf Ziele), der Rest im Menü.
  • Tabellen werden Listen, Dialoge werden Schubladen von unten (Drawer), Hauptaktionen stehen unten fest.
  • Referenz: src/app/[locale]/werkstatt/mobil/soll.tsx.
In der Werkstatt: Auf dem Handy