lksnmnn/product-ui

Produkt-UI

Eine Anwendung ist eine Arbeitsfläche: Menschen kehren zu ihr zurück, um eine Aufgabe zu erledigen. Jedes Element verdient seinen Platz, indem es dieser Aufgabe dient. Das Ziel ist verdiente Vertrautheit — eine Person, die mit Werkzeugen dieser Kategorie vertraut ist, vertraut jedem Steuerelement auf den ersten Blick, und die Schnittstelle verschwindet in der Aufgabe.

Diese Regeln gelten für jede App. Was für ein bestimmtes Projekt spezifisch ist — Geräteziele, Designsystem, Komponenten, Richtung, bekannte Abweichungen — lebt in der Projektdatei; bauen Sie darauf auf. Bevor Sie einen Bildschirm als fertig betrachten, führen Sie review.md aus.

Die Projektdatei

Suchen Sie in dieser Reihenfolge danach: einen Pfad, der in CLAUDE.md oder AGENTS.md angegeben ist, dann .claude/product-ui.md. Wenn keine existiert, erstellen Sie .claude/product-ui.md aus templates/project.md vor dem ersten Build:

1. Finden Sie das Designsystem: Token-Dateien (CSS-Custom-Properties, ein Tailwind-Theme, ein Tokens-JSON), die Komponentenbibliothek (im Repo components/ui, shadcn, MUI, Radix, …), Story-Dateien.
2. Listen Sie die Bausteine auf, die ein Bildschirm benötigt (Seitengerüst, Tabelle, Formularfeld, leerer Zustand, Dialog, Toast, …) mit ihren Pfaden. Markieren Sie jede fehlende als fehlend; erfinden Sie niemals einen Pfad.
3. Notieren Sie die Abweichungen, die Sie auf dem Weg gesehen haben: Stellen, an denen der Code eine der folgenden Regeln bricht.
4. Fragen Sie den Benutzer nach den Gerätezielen pro App und danach, wer die visuelle Sprache besitzt (ein Designteam oder die Entwickler). Schlagen Sie Ziele aus der Absicht der App vor.

Schreiben Sie nur, was Sie überprüft haben. Weisen Sie CLAUDE.md auf die Datei, damit spätere Sitzungen sie finden.

Wenn das Projekt keine visuelle Richtung hat und die Oberfläche nicht generisch aussehen soll, führen Sie zuerst den design-direction-Skill aus; er zeichnet sein Ergebnis in derselben Datei auf.

Zweck zuerst

Bevor Sie das Layout erstellen, schreiben Sie in einer Zeile pro Punkt auf:

• die Aufgabe, die der Bildschirm erfüllt, und die Person, die sie ausführt;
• die erste Lesart: das eine, was sie sich ansehen, wenn der Bildschirm geöffnet wird;
• die primäre Aktion und wie oft sie sie wiederholen;
• die Zielgeräte: Telefon, Tablet, Laptop, großer Bildschirm, aus der Projektdatei.

Jeder Bereich auf dem Bildschirm ist einer dieser Zeilen zugeordnet. Ein Bereich, der keiner zugeordnet werden kann, wird gestrichen.

Echte Inhalte

Erstellen und bewerten Sie mit Inhalten, die wie die Produktion geformt sind: echte Namen mit realistischer Länge, der längste plausible Titel, 0, 1, 7 und 500 Elemente, ein fehlender optionaler Wert, eine Übersetzung, die 30 % länger ist als das Englische. „Max Mustermann“, „Musterfirma GmbH“, „Lorem ipsum“, „Element 1“ und runde Zahlen verstecken jedes Layoutproblem und sind das Erste, was einen Bildschirm generiert aussehen lässt. Wenn die Daten der Domäne unbekannt sind, fragen Sie nach einem Beispiel oder leiten Sie eines aus dem Schema ab.

Jede Größe

Ein Bildschirm ist für sein primäres Gerät optimiert und funktioniert auf allen anderen Haltepunkten mit denselben Funktionen. Jede Größe erhält das Muster, das zu ihr passt, keine gequetschte Kopie des Desktops: eine Seitenleiste wird zu einem Drawer oder einer Symbolleiste, eine Tabelle wird zu einer gestapelten Liste, ein geteilter Bereich wird zu einer Seite mit einem Zurück-Schritt, Hover wird zu einem sichtbaren Steuerelement, eine dichte Symbolleiste wird zu einem Überlaufmenü. Eine Funktion, die unterhalb eines Haltepunkts verschwindet, ist ein Befund.

Nichts scrollt seitwärts bei einer Zielbreite: weder die Seite noch eine Liste innerhalb ihres eigenen Containers. Freitextspalten (Namen, Titel, E-Mails, Dateinamen) schrumpfen und kürzen ab, der vollständige Text erscheint beim Darüberfahren; nur ein wirklich breites Raster (eine Matrix, ein Zeitstrahl) darf scrollen, und das wird angezeigt.

Auf großen Monitoren behalten Inhalte ein lesbares Maß: Textblöcke bleiben unter ~75 Zeichen pro Zeile, Formulare behalten ihre Spaltenbreite, und eine Tabelle darf wachsen, während ihre Freitextspalten den Raum einnehmen.

Navigation

• Die globale Navigation listet die Bereiche der App auf und bleibt auf jedem Bildschirm gleich.
• Ein Bereich mit eigenen Unterbereichen kann eine lokale Ebene hinzufügen (eine zweite Spalte oder Registerkarten). Jede Ebene zeigt nur ihre eigene Ebene: Keine Ebene wiederholt die Einträge einer anderen, und zwei Einträge teilen sich nie eine Bezeichnung.
• Der Bereich — welche Organisation, Arbeitsbereich oder Konto der Bildschirm betrifft — wird durch einen Schalter eingestellt, einmal angezeigt.
• Jede Seite ist höchstens zwei Ebenen von der globalen Navigation entfernt, und die lokale Navigation bleibt auf dem primären Gerät sichtbar.
• Die Chrome-Elemente über dem ersten Steuerelement bleiben klein: ein Breadcrumb wiederholt nie den darunter befindlichen Seitentitel.
• Eine App mit mehr als einer Handvoll Bereichen oder vielen Datensätzen bietet eine Suchfunktion für den Sprung überall hin (⌘K / Strg+K), die Seiten und Datensätze nach Namen oder eingefügter ID findet.

Dichte

• Zeigen Sie den Arbeitsvorrat auf einmal an. Eine Liste, die eine Person scannt oder vergleicht, ist eine Tabelle mit einer Zeile pro Element; ein Kartenraster ist für wenige Elemente, deren Bild oder Vorschau den Inhalt ausmacht.

• Die Zeilenhöhe folgt dem Inhalt: einzeilige Zeilen 36–44 px, eine Zeile mit einer zweiten Zeile oder einem Thumbnail bis zu 64 px; Abstand nimmt nie mehr Höhe ein als der Inhalt.

• Der Abstand zwischen verwandten Elementen ist kleiner als der Abstand zwischen Gruppen, sodass die Gruppierung allein aus der Abständen lesbar ist.

• Jedes Element in einer Zeile verdient seinen Platz. Testen Sie jedes:

  • Aufgabe: es dient dem Finden, Vergleichen, Öffnen oder Bearbeiten des Elements für die Aufgabe dieses Bildschirms;
  • Löschen: das Entfernen verliert etwas, das die Person braucht; sonst geht es weg oder wird zur Detailansicht verschoben;
  • Redundanz: es wiederholt keine Spalte, keinen aktiven Filter und keine Seitenüberschrift;
  • Selbsterklärend: es liest sich ohne Hover, Tooltip oder Legende, und ein Status ist ein Wort, niemals die Farbe allein;
  • Reihenfolge: was das Element zuerst identifiziert, dann die Fakten, die Leute vergleichen, Aktionen zuletzt.

  Ein fehlender Fakt ist ebenfalls ein Befund: wenn Leute Element für Element öffnen, um einen Wert zu vergleichen, gehört dieser Wert in die Zeile.

• Standardmäßig eine Zeile pro Zeile. Sekundäre Fakten befinden sich in ihrer eigenen Spalte oder einer gedämpften zweiten Zeile, niemals in einem Tooltip, über den die Person zum Vergleichen hovers muss.

• Überschriften, Beschreibungen und Hilfetexte sind so kurz, wie es die Aufgabe erlaubt. Eine Seitenbeschreibung, die den Titel wiederholt, wird gestrichen.

• Leerraum trennt Gruppen; er füllt niemals einen spärlichen Bildschirm, um voll auszusehen.

• Eine Box (Rand, Hintergrund, Schatten) markiert ein Objekt, auf das die Person als Einheit einwirkt. Die Gruppierung allein erfolgt durch Abstand oder eine Linie; eine Karte innerhalb einer Karte ist ein Befund.

Hierarchie

• Eine primäre Aktion pro Ansicht, visuell primär, oben rechts ihres Bereichs (Seitenkopf oder Bereichskopf). Sekundäre Aktionen sind Outline oder Ghost; destruktive sind als letzte.
• Jede Größe, jeder Abstand, jede Farbe und jeder Radius stammt aus dem Designsystem der Oberfläche und bleibt darin. Ein willkürlicher Wert (text-[10px], p-[13px], ein roher Hex-Wert) ist ein Befund; die Behebung ist der nächste Schritt, oder ein neues Token, wenn kein Schritt passt.
• Gewicht und Farbe tragen die Hierarchie vor der Größe.
• Farbe trägt Bedeutung: die Akzentfarbe markiert die primäre Aktion, Auswahl und Zustand. Statusfarbe erscheint nur, wo ein Status existiert.
• Symbole begleiten eine Bezeichnung, wo sie die Erkennung beschleunigen (Navigation, häufige Aktionen) und stehen allein nur für universelle Aktionen (Schließen, Suchen, Mehr) mit einem zugänglichen Namen. Ein Symbol auf jedem Button, jeder Überschrift oder Karte ist Dekoration.
• Ein schreibgeschützter Wert wird als Text dargestellt, niemals als Eingabefeld.
• Ein Steuerelement, das die Rolle des Betrachters nicht verwenden kann, ist ausgeblendet, entschieden durch dieselbe Fähigkeit, die der Server prüft. Wenn das Wissen um die Existenz der Aktion wichtig ist, wird sie deaktiviert mit dem Grund angezeigt („Nur Admins können einladen“).
• Kopieren Sie Namen, die Leute erkennen, nicht die dahinterstehende Infrastruktur: keine Anbieter- oder Pipeline-Namen, es sei denn, das Publikum arbeitet direkt damit. Navigation listet keine nicht gebauten oder ausgeschalteten Funktionen auf.

Texte

Schnittstellentexte sind Teil des Designs und das schnellste Anzeichen für einen generierten Bildschirm.

• Ein Button sagt, was er tut, als Verb und sein Objekt: „Mitglied einladen“, „CSV exportieren“. Niemals „Absenden“, „OK“, „Hier klicken“, „Los geht's“ in einer App.
• Der Bestätigungsbutton wiederholt das Verb der Frage: „3 Dateien löschen?“ → „Dateien löschen“.
• Satzanfang für jede Bezeichnung, Überschrift und Button. Keine Ausrufezeichen, kein „Hoppla“, kein „Erfolgreich“, kein „Bitte“.
• Feedback gibt das Ergebnis in den Worten der Person an: „Rechnung gesendet an finanz@…“, nicht „Vorgang erfolgreich abgeschlossen“.
• Ein leerer Zustand sagt, was hier hingehört und wie es hierherkommt, in ein oder zwei einfachen Sätzen. Kein Witz, keine Füllillustration, kein „Hier gibt es nichts zu sehen“.
• Keine Marketingstimme innerhalb eines Werkzeugs: Streichen Sie „nahtlos“, „mühelos“, „leistungsstark“, „freischalten“, „optimieren“, „magisch“, „KI-gestützt“ und jeden Satz, der das Produkt lobt.
• Ein Begriff pro Konzept in der gesamten App; das Glossar lebt in der Projektdatei.
• Zahlen, Daten und Einheiten folgen einem Format pro App; Zählungen verwenden den richtigen Plural („1 Datei“, „2 Dateien“).

Listen und Tabellen

• Zahlen rechtsbündig mit tabular-nums; Text linksbündig.
• Zeitstempel verwenden ein festes Format pro App, niemals das Gebietsschema des Browsers als Standard, und werden nie abgeschnitten. Überwachungsbildschirme paaren eine relative Zeit („vor 3 Min.“) mit der absoluten beim Darüberfahren, oder umgekehrt.
• Kopfzeilen nennen die Spalte in ein oder zwei Wörtern; sortierbare Kopfzeilen sortieren beim Klicken.
• Suche, Filter, Sortierung, Seite und das geöffnete Element leben in der URL, sodass eine Ansicht Neuladen, Rückwärts und einen geteilten Link übersteht.
• Eine Zeile ist ein echter Link zu ihrem Element: Die gesamte Zeile öffnet es, und Strg-Klick öffnet einen neuen Tab.
• Jeder Verweis in einer Zeile — eine Person, eine Organisation, ein Job, eine ID — verlinkt auf seine eigene Seite.
• Aktionen pro Zeile befinden sich am Ende der Zeile in einer stabilen Spalte, sichtbar im Ruhezustand; mindestens sind sie auf Touchscreens sichtbar. Ein Steuerelement, das Klicks akzeptiert, während es unsichtbar ist, ist ein Fehler.
• Massenarbeit erhält Kontrollkästchen zur Auswahl, ein Alle-auswählen und eine Massenaktionsleiste, wenn die Person Elemente in Chargen bearbeitet.
• Paginierung oder Windowing nach ~50 Zeilen; die Anzahl ist immer sichtbar. Ein Filter, der die Menge begrenzt (ein Monatsbereich), ersetzt die Paginierung, wenn die Grenze angezeigt wird.
• Filter-Chips können Zählungen tragen; dann dienen sie als Zusammenfassung der Seite.

Formulare

• Bezeichnungen über den Feldern, eine Spalte, in der Reihenfolge, in der die Person über die Daten denkt.
• Validierung beim Verlassen des Feldes und beim Absenden; der Fehler befindet sich unter seinem Feld und sagt, wie er zu beheben ist.
• Standardwerte sind die häufigste Antwort. Optionale Felder sind als optional markiert, erforderliche nicht.
• Der Absende-Button in einem Erstellungs- oder Aktionsformular bleibt aktiviert. Das Absenden ungültiger Eingaben fokussiert das erste ungültige Feld und zeigt darunter, wie es zu beheben ist.
• Der Speicher-Button in einem Bearbeitungsformular kann deaktiviert bleiben, bis sich etwas geändert hat, da nichts darauf wartet, gespeichert zu werden; sobald sich etwas ändert, ist er aktiviert, die obige Regel gilt, und ein Hinweis „Ungespeicherte Änderungen“ daneben zeigt den Zustand an.
• Ein Speichern pro Ansicht. Das Verlassen mit ungespeicherten Änderungen fragt zuerst nach.
• Ein Steuerelement ist deaktiviert, während seine eigene Aktion aussteht, sodass es nicht zweimal ausgelöst werden kann.
• Ein kurzes Formular oder ein einzelnes Feld wird inline bearbeitet; ein Dialog ist für eine fokussierte Aufgabe, die nicht ihren Kontext verlieren darf.
• Eingaben verwenden den richtigen Typ und autocomplete (E-Mail, Tel, Einmalcode, …), sodass Telefone die richtige Tastatur anzeigen und Browser sie ausfüllen.
• Ein Datei-Upload-Trigger ist ein fokussierbarer Button, der den Dateiauswahldialog öffnet und auch einen Drop akzeptiert.
• Eine Seite, die konfiguriert, was eine andere Oberfläche zeichnet (ein Onboarding, eine Marke, eine Vorlage), zeigt eine Vorschau dieser Oberfläche neben ihren Einstellungen.

Aktionen und Feedback

• Eine Aktion mit einem Rückweg (Wiederherstellen, Archivierung rückgängig machen, Reaktivieren) wird sofort ausgeführt und bietet Rückgängig, ohne zusätzliche Bestätigung. Ein Umschalter ist sein eigenes Rückgängig und benötigt nur sofortiges Feedback.
• Eine Aktion ohne Rückweg erhält eine Bestätigung, die benennt, was verloren geht („3 Dokumente löschen“). Eine Aktion, die reversibel aussieht, aber keine Umkehrung hat, wird als irreversibel behandelt, bis die Umkehrung existiert.
• Jede Aktion antwortet innerhalb von 100 ms: optimistisches Update, ausstehender Zustand auf dem Steuerelement oder ein Skelett an der Stelle, an der der Inhalt landen wird.
• Arbeiten, die länger als ein paar Sekunden dauern, laufen im Hintergrund mit sichtbarem Fortschritt und überstehen Navigation.
• Fehler sagen, was passiert ist und was als Nächstes zu tun ist, neben dem Ort, wo es passiert ist.

Die Zustandsmatrix

Jede Ansicht liefert alle ihre Zustände, entworfen, nicht standardmäßig:

Zustand	Form
laden	ein Skelett im Layout, das der Inhalt später einnehmen wird
leer	sagt, was hier hingehört, und bietet die Aktion, es hinzuzufügen
gefiltert-leer	sagt, der Filter hat nichts gefunden, und bietet an, ihn zu löschen
teilweise	die geladenen Teile rendern; der fehlgeschlagene Teil zeigt seinen eigenen Fehler, nie eine Null
kein Zugriff	sagt, wer dies sehen kann und wie man Zugriff erhält, und bietet einen Weg weiter
Fehler	was fehlgeschlagen ist, einen Wiederholungsversuch, der Rest des Bildschirms bleibt nutzbar
voll	die echten Inhalte in realistischer Menge, mit langen Namen und vielen Zeilen

Jedes interaktive Steuerelement hat Standard, Hover, Focus-Visible, Aktiv, Deaktiviert und Ausstehend.

Auf einem Dashboard besitzen jede Kachel und jedes Diagramm ihre eigenen Zustände: ein fehlgeschlagener Lesevorgang zeigt seinen eigenen Fehler, nie eine Null oder ein leeres Diagramm. Ein Dashboard öffnet sich mit dem, was Aufmerksamkeit erfordert, nicht mit einer Reihe von Metrikkarten; eine Zahl erscheint nur mit dem Vergleich, der sie bedeutungsvoll macht (Ziel, letzter Zeitraum) und einer Definition, auf die sich das Team geeinigt hat. Diagramme folgen dem dataviz-Skill, wenn er installiert ist.

Barrierefreiheit und Themes

• Der Textkörper erfüllt 4,5:1 Kontrast, großer Text und Steuerelementgrenzen 3:1, in jedem Theme. Gedämpftes Grau auf Grau ist der häufigste Fehler.
• Der Fokus ist immer sichtbar und nie abgeschnitten; der Fokusring ist entworfen, nicht der Standard des Browsers entfernt.
• Jedes Steuerelement hat einen zugänglichen Namen; ein nur aus Symbol bestehender Button erhält aria-label. Orientierungspunkte (nav, main) und ein h1 pro Seite.
• Text kann auf 200 % vergrößert werden, und das Layout hält.
• Wenn die App ein dunkles Theme unterstützt, ist es entworfen: seine eigenen Oberflächenstufen und eine neu abgestimmte Akzentfarbe, nicht invertierte Farben. Überprüfen Sie jeden Bildschirm in beiden.

Ergonomie

• Die primäre Aufgabe ist über die Tastatur abschließbar: Die Tab-Reihenfolge folgt der Lesereihenfolge, Enter sendet, Escape schließt, der Fokus kehrt zurück, woher er kam.
• Klickziele sind mindestens 24 × 24 px groß, häufige größer, 44 px auf Touch; der Trefferbereich deckt die gesamte Zeile oder Bezeichnung ab, nicht nur das Symbol.
• Häufige Aktionen befinden sich in der Nähe dessen, worauf sie einwirken. Entfernung und Klick

…

[für die Übersetzung gekürzt]