# 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.