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

---

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