300 lines
6.9 KiB
Markdown
300 lines
6.9 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`.
|
|
|
|
---
|
|
|
|
## 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.
|