SkeletonMan/telenetsystems-2026-02-05-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c7ae06e58f3284c3eaa621d7d1be0ce55bc8c64
telenetsystems-2026-02-05-v1/skills/UI_GUIDELINES.md

14 KiB
Raw Blame History

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

<!-- 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:

/* 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):

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

Reference in New Issue View Git Blame Copy Permalink