--- name: gui-gestalten description: Gestaltet, überarbeitet und prüft eigenständige, zugängliche Weboberflächen. Verwenden, wenn Seiten, Komponenten, Design-Tokens, responsive Zustände oder ein Frontend-Vertical-Slice entworfen, implementiert oder visuell beurteilt werden sollen. --- # GUI gestalten Gestalte die Oberfläche aus Nutzeraufgabe, Inhalt und visueller Richtung heraus. Eine technisch korrekte Seite ist erst fertig, wenn sie auch im Browser bewusst gestaltet, verständlich und zugänglich wirkt. ## Fachliche Grundlage - [W3C – Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) definiert prüfbare Anforderungen an wahrnehmbare, bedienbare, verständliche und robuste Weboberflächen. Strebe ohne abweichende Projektvorgabe Level AA an. - [Nuxt – Testing](https://nuxt.com/docs/4.x/getting-started/testing) beschreibt Unit-, Nuxt- und echte Browsertests mit Nuxt Test Utils und Playwright. - [Tailwind CSS – Theme variables](https://tailwindcss.com/docs/theme) beschreibt Theme-Variablen als wiederverwendbare Design-Tokens. - [Tailwind CSS – Utility classes](https://tailwindcss.com/docs/styling-with-utility-classes) beschreibt Utilities als primäre Styling-Schnittstelle. - [Tailwind CSS – Hover, focus, and other states](https://tailwindcss.com/docs/hover-focus-and-other-states) beschreibt Varianten für Zustände, Medienabfragen und strukturelle Fälle. - [Tailwind CSS – Adding custom styles](https://tailwindcss.com/docs/adding-custom-styles) beschreibt die begrenzten, erweiterbaren Ausnahmen für eigenes CSS. - [Playwright – Visual comparisons](https://playwright.dev/docs/test-snapshots) beschreibt reproduzierbare Screenshot-Vergleiche. Die Forderung, eine Oberfläche solle nicht wie generierte Standardware wirken, ist eine bewusste Gestaltungsregel dieses Templates und kein externer Standard. ## Ausgangspunkt für neue Weboberflächen Verwende, sofern das Projekt noch keinen Frontend-Stack festgelegt hat, diesen bewährten Ausgangspunkt: - Nuxt 4 mit Vue 3, Composition API und Single-File Components - TypeScript im Strict-Modus - Tailwind CSS v4 mit projektbezogenen Theme-Variablen - Vitest und Nuxt Test Utils für schnelle Logik-, SSR- und Integrationstests - Playwright für entscheidende Abläufe, Tastaturbedienung und visuelle Prüfung Behandle diesen Stack als Profil, nicht als unveränderliche Vorgabe. Prüfe vor dem Anlegen eines Webmoduls die aktuell kompatiblen Versionen. Fixiere die tatsächlich gewählten Versionen im Paketmanifest und projektprägende Laufzeiten in `TOOLS.md`. Befolge vor jeder fehlenden Installation den Skill `werkzeuge-verwalten`. Führe weder eine Komponentenbibliothek noch einen globalen Zustandsstore ohne konkreten Bedarf ein. Halte Fachlogik und Persistenz in der zuständigen API; verwende serverseitige Frontend-Routen höchstens für Rendering, Session und einen dünnen Backend-for-Frontend-Adapter. ## Verbindlicher Tailwind-Vorrang Wenn das Projekt Tailwind CSS verwendet, ist Tailwind die verbindliche Styling-Schnittstelle. Verwende für Layout, Abstände, Grössen, Typografie, Farben, Rahmen, Schatten, Responsive-Zustände, Interaktionen und Barrierefreiheitszustände zuerst: - Tailwind-Utilities direkt im Template; - Responsive-, Zustands-, Container- und Accessibility-Varianten; - projektbezogene Tokens in `@theme`; - bei einem fehlenden eingebauten Utility eine kleine eigene `@utility`. Erzeuge keine eigene CSS-Klasse oder Selektorkette, wenn dieselbe Wirkung mit Tailwind ausdrückbar ist. Verwende insbesondere keine selbstgebauten Seiten- oder Komponentenklassen wie `.hero`, `.button`, `.card` oder `.section` als Ersatz für Utility-Klassen. Kapsle wiederkehrendes Markup und wiederkehrende Utility-Zusammenstellungen in Vue-Komponenten, nicht in einer wachsenden globalen CSS-Schicht. Verwende `@apply` nicht als Standard und nicht für grosse Komponentenblöcke. Direkte Utility-Klassen im Template bleiben die bevorzugte und sichtbar änderbare Form. Eigenes CSS ist nur für einen konkret benannten Fall erlaubt, den Tailwind nicht ausdrücken kann, zum Beispiel eine Drittanbieter-Komponente oder eine technisch unvermeidbare Browser-Sonderbehandlung. Halte diese Ausnahme lokal, klein und begründet. Globales CSS darf nur Tailwind importieren, Theme-Tokens definieren oder minimale Basis- und Integrationsregeln enthalten. Bevor du eigenes CSS schreibst, prüfe in dieser Reihenfolge: 1. eingebautes Tailwind-Utility; 2. Tailwind-Variante für Responsive-, Zustands- oder Strukturfall; 3. vorhandenes Token oder neues projektweites Token in `@theme`; 4. ein einmaliger Tailwind-Arbitrary-Value; 5. eine kleine, wiederverwendbare `@utility`; 6. erst danach lokal begrenztes eigenes CSS. Beliebige Werte wie `[...]` sind nur für echte Einzelfälle zulässig. Wiederkehrende Werte gehören in `@theme`. Eine eigene globale Regel, eine neue Komponentenklasse oder mehr als wenige eigene CSS-Deklarationen sind vor der Umsetzung zu begründen; wenn dadurch die Wartbarkeit wesentlich beeinflusst wird, halte an und kläre die Ausnahme zuerst. ## Vorgehen 1. Lies `PROJECT.md`, relevante ADRs und vorhandene Oberflächen. Suche nach `docs/gui/GUI-BRIEF.md`. 2. Fehlt die visuelle Richtung, kläre nur die noch offenen Punkte aus `docs/templates/gui-brief-template.md`. Frage insbesondere nach Zielgruppe, Hauptaufgabe, gewünschter Wirkung, Referenzen und Gegenbeispielen. Stelle höchstens eine Frage auf einmal und beginne mit der Hauptaufgabe. 3. Lege das ausgefüllte Briefing als `docs/gui/GUI-BRIEF.md` ab. Erfinde keine Marke, wenn der Benutzer noch entscheiden muss. 4. Halte eine dauerhafte Stack- oder Systementscheidung als ADR fest. Ein einzelnes Layout oder eine einzelne Komponente benötigt kein ADR. 5. Baue einen kleinen vollständigen Nutzungsablauf statt vieler unfertiger Seiten. 6. Wenn Tailwind verwendet wird, setze die Oberfläche zuerst mit Utilities, Varianten und `@theme`-Tokens um. Schreibe eigenes CSS erst nach der im Abschnitt „Verbindlicher Tailwind-Vorrang“ beschriebenen Prüfung. 7. Definiere wenige wiederverwendbare Tokens für Typografie, Farbe, Abstände, Radien, Schatten und Bewegung. Übernimm nicht ungefragt die Farben oder Typografie eines anderen Projekts. 8. Gestalte reale Inhalte und alle relevanten Zustände: initial, laden, leer, Erfolg, Validierungsfehler und technischer Fehler. 9. Verwende nach `sicherheit-und-datenschutz-pruefen` datensparsame Voreinstellungen, verständliche Berechtigungen und Fehlertexte ohne interne oder personenbezogene Details. 10. Prüfe die Seite im echten Browser mindestens in einer schmalen und einer breiten Ansicht. Prüfe Informationshierarchie, Umbruch, Fokusführung, Tastaturbedienung, Kontrast und reduzierte Bewegung. 11. Sichere Fachverhalten mit schnellen Tests und den wichtigsten Nutzerweg mit einem Browsertest. Befolge dabei `testgetrieben-entwickeln`. Verwende Screenshot-Vergleiche nur für stabile, gestalterisch wichtige Ansichten. ## Eigenständig statt generisch gestalten - Leite die visuelle Sprache aus Produkt, Zielgruppe und Inhalt ab. - Verwende echte, präzise Texte statt austauschbarer Werbe- und Platzhaltertexte. - Erzeuge eine klare Hierarchie; nicht jeder Inhalt braucht eine Karte, einen Rahmen oder dasselbe visuelle Gewicht. - Wähle höchstens ein oder zwei charakteristische Gestaltungsmotive und setze sie konsequent ein. - Verwende Typografie, Weissraum und Proportion zuerst; Effekte erst danach. - Vermeide ungefragte Standardmotive wie violett-blaue Verläufe, Glasflächen, übermässig viele Pillen, Verlaufsschrift, austauschbare Kartenraster und dekorative Kennzahlen. Verwende sie nur, wenn das Briefing sie begründet. - Kopiere Vorbilder nicht. Benenne, welches Prinzip übernommen wird, etwa Informationsdichte, Rhythmus oder Navigationsform. ## Fertig, wenn - Hauptaufgabe und wichtigste Aktion ohne Erklärung erkennbar sind. - Die Oberfläche zum Projektbriefing passt und nicht wie ein neutrales Baukastentheme wirkt. - schmale und breite Ansichten sowie alle wichtigen Zustände geprüft sind. - semantisches HTML, sichtbarer Fokus und Tastaturbedienung funktionieren. - automatisierte Prüfungen erfolgreich sind und eine visuelle Prüfung tatsächlich stattgefunden hat. - bei Tailwind-Projekten alle Styling-Entscheide vorrangig mit Utilities, Varianten und Theme-Tokens umgesetzt sind. - jede verbleibende eigene CSS-Regel einen konkreten, dokumentierten Grund hat und keine vorhandene Tailwind-Funktion dupliziert. - verwendete Assets, Schriften und Vorlagen eine geklärte Lizenz besitzen.