502 lines
14 KiB
Markdown
502 lines
14 KiB
Markdown
# UI Guidelines
|
||
|
||
Qualitätsregeln für Benutzeroberflächen. Keine Designvorgaben.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
Diese Datei definiert **Qualitätsanforderungen** für:
|
||
- Accessibility (Barrierefreiheit)
|
||
- Responsive Design (Mobile-First)
|
||
- Performance-Budgets
|
||
- SEO-Grundlagen
|
||
- GEO/AI-Search-Optimierung
|
||
- Interaktionsqualität
|
||
|
||
**Geltungsbereich:** Gilt global für jedes Projekt. Definiert WIE UI gebaut wird, nicht WIE sie aussieht.
|
||
|
||
---
|
||
|
||
## Read Order
|
||
|
||
Diese Datei wird nach `SYSTEM_SKILLS.md` gelesen:
|
||
|
||
1. `skills/SYSTEM_SKILLS.md`
|
||
2. `skills/UI_GUIDELINES.md` (diese Datei)
|
||
3. `skills/DEFINITION_OF_DONE.md`
|
||
4. `skills/CLIENT_OVERRIDES.md`
|
||
5. Projekt-Specs
|
||
|
||
---
|
||
|
||
## Non-Goals
|
||
|
||
Diese Datei definiert **NICHT**:
|
||
- Welche Farben verwendet werden (kommt aus Tokens)
|
||
- Welche Schriftarten verwendet werden (kommt aus Tokens)
|
||
- Welche Layouts oder Sections erstellt werden (kommt aus ProjectSpec)
|
||
- Konkrete visuelle Gestaltung
|
||
- UI-Templates oder Komponenten-Vorlagen
|
||
|
||
**Regel:** Alle visuellen Entscheidungen kommen aus `design_tokens.json` und `stylesheet.css`.
|
||
|
||
---
|
||
|
||
## Stil-Adjektive & Stil-Verbote
|
||
|
||
Die visuellen Grundprinzipien werden durch Kategorie F definiert.
|
||
|
||
### Stil-Adjektive (styleAdjectives)
|
||
|
||
Maximal 5 Wörter, die den visuellen Charakter definieren (z.B. "modern", "sportlich", "seriös", "elegant", "minimalistisch").
|
||
|
||
**Pflicht:** Bei JEDER visuellen Entscheidung prüfen:
|
||
- Passt diese Entscheidung zu den definierten Adjektiven?
|
||
- Verstärkt sie den gewünschten Charakter?
|
||
|
||
### Stil-Verbote (styleProhibitions)
|
||
|
||
Definieren No-Gos (z.B. "verspielt", "comic", "laut", "kitschig").
|
||
|
||
**Pflicht:** Keine Designentscheidung darf gegen ein Stil-Verbot verstoßen.
|
||
|
||
### Prüfschema
|
||
|
||
Vor jeder UI-Entscheidung:
|
||
1. ✓ Passt es zu den Stil-Adjektiven?
|
||
2. ✓ Verstößt es gegen kein Stil-Verbot?
|
||
3. ✓ Ist es konsistent mit bisherigen Entscheidungen?
|
||
|
||
---
|
||
|
||
## Adaptive Layout-Regeln nach Interaktionsniveau
|
||
|
||
Das Layout passt sich dem definierten Interaktionsniveau aus Kategorie G an.
|
||
|
||
### Level: ruhig
|
||
|
||
- Maximale visuelle Ruhe
|
||
- Große Whitespace-Blöcke (min. `--spacing-2xl` zwischen Sections)
|
||
- Keine Animationen
|
||
- Maximal 1 CTA pro Viewport
|
||
- Keine Sticky-Elemente außer minimaler Header
|
||
- Klare vertikale Rhythmik
|
||
- Keine Parallax-Effekte
|
||
|
||
### Level: moderat
|
||
|
||
- Ausgewogenes Layout
|
||
- Dezente Hover-Effekte (opacity, subtle scale)
|
||
- IntersectionObserver-basierte Fade-Ins
|
||
- Moderate Whitespace (`--spacing-xl` bis `--spacing-2xl`)
|
||
- CTAs dürfen wiederholt werden, aber nicht aufdringlich
|
||
- Subtile Scroll-Progress-Indikatoren erlaubt
|
||
|
||
### Level: dynamisch
|
||
|
||
- Scroll-triggered Animationen erlaubt
|
||
- Parallax-Effekte möglich
|
||
- Interaktive Elemente (Hover-Reveals, Micro-Interactions)
|
||
- Sticky CTAs auf Mobile
|
||
- Stagger-Animationen für Listen
|
||
- Visuelle Überraschungsmomente erlaubt
|
||
|
||
---
|
||
|
||
## Conversion-optimiertes Layout
|
||
|
||
Das Layout richtet sich nach dem Seiten-Zweck aus Kategorie E.
|
||
|
||
### Seiten mit purpose: konvertieren
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Hero mit primärem CTA above-the-fold │
|
||
├─────────────────────────────────────┤
|
||
│ Trust-Section (direkt unter Hero) │
|
||
│ - Bewertungen, Zertifikate, Logos │
|
||
├─────────────────────────────────────┤
|
||
│ Nutzen / USPs │
|
||
├─────────────────────────────────────┤
|
||
│ Einwand-Entkräftung │
|
||
│ - FAQ oder "Häufige Fragen" │
|
||
├─────────────────────────────────────┤
|
||
│ Kontaktformular / Buchung │
|
||
│ - Mit sekundärem CTA │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
- Above-the-fold CTA mit primärer Handlungsaufforderung
|
||
- Trust-Section direkt unter dem Hero
|
||
- Einwand-Entkräftung vor dem Kontaktformular
|
||
- Sticky CTA-Bar auf Mobile
|
||
|
||
### Seiten mit purpose: informieren
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Klare H1 + Einleitung │
|
||
├─────────────────────────────────────┤
|
||
│ Inhaltsverzeichnis (bei langen │
|
||
│ Seiten > 3 Sections) │
|
||
├─────────────────────────────────────┤
|
||
│ Content-Sections mit H2-Struktur │
|
||
│ - Scanbare Absätze │
|
||
│ - Listen und Tabellen │
|
||
├─────────────────────────────────────┤
|
||
│ CTA am Ende (nicht dominant) │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
- Klare H2-Struktur für Scanability
|
||
- Inhaltsverzeichnis bei langen Seiten (>3 Sections)
|
||
- CTAs am Ende von Sektionen, nicht dominant
|
||
- Fokus auf Lesbarkeit und Navigation
|
||
|
||
### Seiten mit purpose: ueberzeugen
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Problem-Statement (Identifikation) │
|
||
├─────────────────────────────────────┤
|
||
│ Lösung präsentieren │
|
||
│ - USP-Cards / Feature-Grid │
|
||
├─────────────────────────────────────┤
|
||
│ Beweis (Social Proof) │
|
||
│ - Testimonials, Case Studies │
|
||
│ - Zahlen und Fakten │
|
||
├─────────────────────────────────────┤
|
||
│ CTA mit klarer Handlungsaufforderung │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
- Problem → Lösung → Beweis → CTA Flow
|
||
- USP-Cards/Feature-Grid prominent
|
||
- Social Proof zwischen Content-Sections
|
||
- Emotionale + rationale Argumentation
|
||
|
||
---
|
||
|
||
## Ansprache-konsistente UI-Texte
|
||
|
||
Alle UI-Texte müssen die Ansprache aus Kategorie C widerspiegeln.
|
||
|
||
### Ansprache: du
|
||
|
||
| Element | Beispiel |
|
||
|---------|----------|
|
||
| Button | "Jetzt starten", "Schick uns eine Nachricht" |
|
||
| Formular-Label | "Dein Name", "Deine E-Mail" |
|
||
| Placeholder | "Wie können wir dir helfen?" |
|
||
| Microcopy | "Wir melden uns bei dir zurück" |
|
||
| Fehlertext | "Bitte gib deine E-Mail an" |
|
||
| Erfolgstext | "Danke! Wir haben deine Nachricht erhalten." |
|
||
|
||
### Ansprache: sie
|
||
|
||
| Element | Beispiel |
|
||
|---------|----------|
|
||
| Button | "Jetzt starten", "Senden Sie uns eine Nachricht" |
|
||
| Formular-Label | "Ihr Name", "Ihre E-Mail" |
|
||
| Placeholder | "Wie können wir Ihnen helfen?" |
|
||
| Microcopy | "Wir melden uns bei Ihnen" |
|
||
| Fehlertext | "Bitte geben Sie Ihre E-Mail an" |
|
||
| Erfolgstext | "Vielen Dank! Wir haben Ihre Nachricht erhalten." |
|
||
|
||
### Konsistenz-Regel
|
||
|
||
**Pflicht:** Die gewählte Ansprache muss auf ALLEN Seiten und in ALLEN UI-Elementen konsistent sein. Mischformen sind verboten.
|
||
|
||
---
|
||
|
||
## Responsive Breakpoints
|
||
|
||
### Konkrete Viewports
|
||
|
||
| Viewport | Bereich | Verhalten |
|
||
|----------|---------|-----------|
|
||
| Mobile | 320px – 767px | Hamburger Navigation, Stack-Layout, Touch-Targets 44×44px |
|
||
| Tablet | 768px – 1023px | Collapsed Navigation erlaubt, 2-Column-Grids |
|
||
| Desktop | 1024px+ | Full Navigation, bis zu 4-Column-Grids |
|
||
|
||
### Mobile (320px – 767px)
|
||
|
||
- Hamburger-Navigation mit Slide-Out oder Fullscreen-Overlay
|
||
- Einspaltiges Layout (Stack)
|
||
- Touch-Targets mindestens 44×44px
|
||
- Keine Hover-Only-Interaktionen
|
||
- Sticky Header (optional, je nach Interaktionsniveau)
|
||
- Bottom-Sticky CTAs bei Conversion-Seiten
|
||
|
||
### Tablet (768px – 1023px)
|
||
|
||
- Navigation kann collapsed bleiben oder aufklappen
|
||
- 2-Column-Grids möglich
|
||
- Touch und Hover coexistieren
|
||
- Seitlicher Padding erhöht
|
||
|
||
### Desktop (1024px+)
|
||
|
||
- Volle Navigation sichtbar
|
||
- Bis zu 4-Column-Grids
|
||
- Hover-Effekte aktiv
|
||
- Container-Max-Width greift
|
||
|
||
---
|
||
|
||
## Accessibility (Barrierefreiheit)
|
||
|
||
### WCAG 2.1 Level AA
|
||
|
||
Jede UI muss mindestens WCAG 2.1 Level AA erfüllen:
|
||
|
||
| Anforderung | Kriterium |
|
||
|-------------|-----------|
|
||
| Kontrast (normaler Text) | mindestens 4.5:1 |
|
||
| Kontrast (großer Text) | mindestens 3:1 |
|
||
| Kontrast (UI-Elemente) | mindestens 3:1 |
|
||
| Fokus-Indikator | sichtbar für alle interaktiven Elemente |
|
||
| Tastatur-Navigation | vollständig ohne Maus bedienbar |
|
||
| Screen Reader | alle Inhalte zugänglich |
|
||
|
||
### Semantisches HTML
|
||
|
||
```html
|
||
<!-- Korrekt -->
|
||
<button type="button">Aktion ausführen</button>
|
||
<a href="/kontakt">Zum Kontaktformular</a>
|
||
<nav aria-label="Hauptnavigation">...</nav>
|
||
|
||
<!-- Falsch -->
|
||
<div onclick="...">Aktion ausführen</div>
|
||
<span class="link">Zum Kontaktformular</span>
|
||
<div class="nav">...</div>
|
||
```
|
||
|
||
### ARIA-Attribute
|
||
|
||
- ARIA nur verwenden, wenn natives HTML nicht ausreicht
|
||
- `aria-label` für Icons ohne sichtbaren Text
|
||
- `aria-expanded`, `aria-hidden` für dynamische Inhalte
|
||
- `aria-live` für dynamische Updates (z.B. Fehlermeldungen)
|
||
- `role` nur wenn semantisches HTML keine Option ist
|
||
|
||
### Formulare
|
||
|
||
- Jedes Eingabefeld braucht ein sichtbares `<label>`
|
||
- Fehlermeldungen sind klar, hilfreich und programmatisch verknüpft
|
||
- Pflichtfelder sind gekennzeichnet (`aria-required`)
|
||
- Validierung sowohl visuell als auch für Screenreader
|
||
- Autofill-Attribute (`autocomplete`) wo sinnvoll
|
||
|
||
### Nicht nur Farbe
|
||
|
||
- Informationen nie nur durch Farbe vermitteln
|
||
- Zusätzliche Indikatoren: Icons, Text, Muster, Unterstreichungen
|
||
|
||
---
|
||
|
||
## Responsive Design
|
||
|
||
### Mobile-First Pflicht
|
||
|
||
Basis-Styles gelten für Mobile. Erweiterungen für größere Screens:
|
||
|
||
```css
|
||
/* Basis: Mobile (< 640px) */
|
||
.element {
|
||
flex-direction: column;
|
||
padding: var(--spacing-sm);
|
||
}
|
||
|
||
/* Tablet und größer */
|
||
@media (min-width: 768px) {
|
||
.element {
|
||
flex-direction: row;
|
||
padding: var(--spacing-md);
|
||
}
|
||
}
|
||
```
|
||
|
||
### Breakpoints
|
||
|
||
Breakpoints aus `design_tokens.json` verwenden:
|
||
|
||
| Token | Wert | Gerät |
|
||
|-------|------|-------|
|
||
| `sm` | 640px | Große Smartphones |
|
||
| `md` | 768px | Tablets |
|
||
| `lg` | 1024px | Kleine Laptops |
|
||
| `xl` | 1280px | Desktop |
|
||
| `2xl` | 1536px | Große Screens |
|
||
|
||
### Prüfpflicht
|
||
|
||
- Minimum: 320px (kleine Smartphones)
|
||
- Maximum: unbegrenzt (fluid bis Container-Max)
|
||
- Keine horizontalen Scrollbars
|
||
- Keine abgeschnittenen Inhalte
|
||
- Touch-Targets: mindestens 44x44px
|
||
|
||
### Fluid Typography
|
||
|
||
Schriftgrößen skalieren responsiv (wenn in Tokens definiert):
|
||
|
||
```css
|
||
font-size: clamp(1rem, 2vw + 0.5rem, 1.5rem);
|
||
```
|
||
|
||
---
|
||
|
||
## SEO Basics
|
||
|
||
### Pflicht-Elemente pro Seite
|
||
|
||
- [ ] Eindeutiger `<title>` (50-60 Zeichen)
|
||
- [ ] Meta-Description (150-160 Zeichen)
|
||
- [ ] Korrekte Heading-Hierarchie (`h1` > `h2` > `h3`, nur ein `h1` pro Seite)
|
||
- [ ] Alt-Texte für alle informativen Bilder
|
||
- [ ] Open Graph Tags (`og:title`, `og:description`, `og:image`)
|
||
- [ ] Canonical URL (bei Duplicate Content)
|
||
|
||
### Strukturierte Inhalte
|
||
|
||
- Semantische HTML-Elemente verwenden
|
||
- Strukturierte Daten (JSON-LD) wo sinnvoll:
|
||
- Organization
|
||
- LocalBusiness
|
||
- FAQ
|
||
- BreadcrumbList
|
||
- Article
|
||
|
||
### Technisches SEO
|
||
|
||
- Sprechende URLs
|
||
- `robots.txt` vorhanden
|
||
- `sitemap.xml` generiert
|
||
- Keine Duplicate Content ohne Canonical
|
||
- Keine Blocking-Resources im Critical Path
|
||
|
||
---
|
||
|
||
## GEO / AI-Search-Optimierung
|
||
|
||
### Klare Informationsarchitektur
|
||
|
||
- Prägnante, gut strukturierte Abschnitte
|
||
- Klare Überschriften, die den Inhalt beschreiben
|
||
- Faktenbasierte, zitierbare Aussagen
|
||
- Keine Marketing-Floskeln ohne Substanz
|
||
|
||
### FAQ wo sinnvoll
|
||
|
||
- FAQ-Schema für häufige Fragen
|
||
- Klare Frage-Antwort-Struktur
|
||
- Direkte, hilfreiche Antworten
|
||
|
||
### Zitierbarkeit
|
||
|
||
- Unique Content mit klarem Mehrwert
|
||
- Quellenangaben wo relevant
|
||
- Autorenschaft und Expertise zeigen (E-E-A-T)
|
||
|
||
---
|
||
|
||
## Performance Budget
|
||
|
||
### Core Web Vitals Ziele
|
||
|
||
| Metrik | Ziel | Beschreibung |
|
||
|--------|------|--------------|
|
||
| LCP | < 2.5s | Largest Contentful Paint |
|
||
| INP | < 200ms | Interaction to Next Paint |
|
||
| CLS | < 0.1 | Cumulative Layout Shift |
|
||
|
||
### Asset-Limits
|
||
|
||
| Asset-Typ | Maximum |
|
||
|-----------|---------|
|
||
| JavaScript Bundle (gzip) | < 100kb |
|
||
| CSS Bundle (gzip) | < 30kb |
|
||
| Einzelbild | < 200kb |
|
||
| Gesamte Seite | < 1.5MB |
|
||
|
||
### Optimierungspflichten
|
||
|
||
- Bilder: WebP/AVIF, responsive `srcset`, Lazy Loading
|
||
- Fonts: Subset, `display: swap`, Preload für kritische Fonts
|
||
- JavaScript: Code-Splitting, Tree-Shaking, defer/async
|
||
- CSS: Kritisches CSS inline, Rest async laden
|
||
|
||
---
|
||
|
||
## Interaktionen
|
||
|
||
### Feedback-Pflicht
|
||
|
||
- Hover-States für alle klickbaren Elemente
|
||
- Focus-States sichtbar und deutlich
|
||
- Loading-States für asynchrone Aktionen
|
||
- Erfolgs- und Fehlermeldungen klar kommunizieren
|
||
|
||
### Animationen
|
||
|
||
- Subtil und zweckmäßig (nicht dekorativ)
|
||
- `prefers-reduced-motion` respektieren
|
||
- UI-Feedback-Animationen < 300ms
|
||
- Keine automatisch startenden Videos/Animationen
|
||
|
||
```css
|
||
@media (prefers-reduced-motion: reduce) {
|
||
*,
|
||
*::before,
|
||
*::after {
|
||
animation-duration: 0.01ms !important;
|
||
transition-duration: 0.01ms !important;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Typografie (Qualität, nicht Design)
|
||
|
||
### Lesbarkeit
|
||
|
||
- Zeilenlänge: 45-75 Zeichen optimal
|
||
- Zeilenabstand: 1.4-1.6 für Fließtext
|
||
- Ausreichende Absatzabstände
|
||
|
||
### Hierarchie
|
||
|
||
- Klare visuelle Hierarchie durch Größen/Gewichte
|
||
- Konsistente Heading-Levels
|
||
- Logische Informationsstruktur
|
||
|
||
**Hinweis:** Konkrete Schriftarten, -größen und -farben kommen aus `design_tokens.json`.
|
||
|
||
---
|
||
|
||
## Farben (Qualität, nicht Design)
|
||
|
||
### Kontrastprüfung
|
||
|
||
Alle Farbkombinationen müssen geprüft werden:
|
||
- Tool: WebAIM Contrast Checker oder ähnlich
|
||
- Dokumentierte Ausnahmen sind möglich, aber selten
|
||
|
||
### Herkunft
|
||
|
||
- Alle Farben kommen aus `design_tokens.json` oder `stylesheet.css`
|
||
- Keine hardcodierten Hex/RGB-Werte im Code
|
||
- CSS-Variablen verwenden
|
||
|
||
---
|
||
|
||
## Zusammenfassung
|
||
|
||
> UI muss zugänglich, responsive, performant und suchmaschinenoptimiert sein.
|
||
> Diese Guidelines definieren Qualitätsstandards, nicht visuelles Design.
|
||
> Design-Entscheidungen kommen aus den Projekt-Specs.
|