Hermeneus Master-Style-Guide

Version 1.0 | Erstellt: 2025-11-14

Ein umfassender Design-System-Leitfaden für Frontend-Entwickler und Designer. Dieser Guide dient als zentrale "Single Source of Truth" für alle Design-Entscheidungen in der Hermeneus-App.

---

1. Einleitung und Design-Prinzipien

1.1 Überblick

Hermeneus ist eine webbasierte Lernplattform für lateinische Sprache und Textanalyse. Das Design-System folgt modernen Webstandards und legt besonderen Wert auf:

• Klarheit: Klare, lesbare Typografie und ausreichend Whitespace
• Konsistenz: Einheitliche Patterns und wiederverwendbare Komponenten
• Zugänglichkeit: WCAG AA-konforme Kontraste und barrierefreie Interaktionen
• Modularität: Komponenten-basierte Architektur mit Vue 3 und Tailwind CSS
• Bildungsfokus: Spezielle Formatierung für lateinische Texte und akademische Inhalte

1.2 Tech-Stack

• CSS-Framework: Tailwind CSS 3.4
• UI-Bibliothek: PrimeVue (angepasst)
• Frontend: Vue 3 (Options API)
• Schriftarten: Merriweather (Serif), Merriweather Sans (Sans-Serif)

1.3 Design-Philosophie

Das Hermeneus-Design folgt einem Tailwind-First-Ansatz: Alle Styles werden primär über Tailwind-Utility-Klassen definiert. Benutzerdefinierte CSS-Klassen werden nur verwendet, wenn Tailwind-Utilities nicht ausreichen.

---

2. Farbsystem

2.1 Hauptfarben

Primary (Dark Jungle Green)

Hauptfarbe der Anwendung für primäre Aktionen, aktive Zustände und Navigationselemente.

• DEFAULT: #191B28 (primary)
• Abstufungen:
  • 100: Sehr hell (Hintergründe)
  • 200-400: Hell (Hover-Zustände, Sekundär-UI)
  • 500-600: Mittel (Standard-Aktionen)
  • 700-900: Dunkel (Text, Navigation, aktive Elemente)

Verwendung: Primäre Buttons, Navigation (aktiv), Links, Fokus-Indikatoren

Secondary (Metallic Red)

Akzentfarbe für sekundäre Aktionen und Hervorhebungen.

• DEFAULT: #B22E2F (secondary-600)
• Abstufungen:
  • 50-100: Sehr hell (Hinweis-Boxen, Hintergründe)
  • 300-400: Hell (Hover-Effekte)
  • 500-700: Mittel bis dunkel (Buttons, Badges)
  • 800-900: Sehr dunkel (Text auf hellen Hintergründen)

Verwendung: Sekundäre Buttons, Badges, Kategorien-Marker

Tertiary (Ateneo Blue)

Tertiärfarbe für spezielle UI-Elemente und Kategorien.

• DEFAULT: #004563 (tertiary)
• Abstufungen:
  • 100-300: Hell (Sammlungen, Tags)
  • 400-600: Mittel (Interaktive Elemente)
  • 700-900: Dunkel (Text, Kontraste)

Verwendung: Sammlungen, spezielle Kategorien, alternative Buttons

2.2 Status-Farben

Success (Grün)

• DEFAULT: #5cb85c
• light: #caffc5 (Hintergründe)
• dark: #428542 (Text, Borders)
• contrast: Weiß (Text auf dunklem Hintergrund)

Verwendung: Erfolgsmeldungen, korrekte Antworten, positive Bestätigungen

Danger/Error (Rot)

• DEFAULT: #d9533b
• light: #f3b9b1 (Hintergründe)
• dark: #a63f3c (Text, Borders)
• contrast: Weiß (Text auf dunklem Hintergrund)
• Abstufungen 0-950: Für feine Nuancen in Fehlermeldungen

Verwendung: Fehlermeldungen, falsche Antworten, Warnungen vor destruktiven Aktionen

Warning (Gelb/Orange)

• DEFAULT: #f0ad4e
• light: #fff0c4 (Hintergründe)
• dark: #bd873c (Text, Borders)
• contrast: Schwarz (Text auf hellem Hintergrund)

Sekundäres Warning (Warning2):

• DEFAULT: #f0744e
• dark: #bd5a3c
• light: #ecbd9e

Verwendung: Warnhinweise, ausstehende Aktionen, Aufmerksamkeits-Marker

Info (Grau/Neutral)

• DEFAULT: #f0f0f0
• light: Weiß
• dark: #e0e0e0
• contrast: #777

Verwendung: Informations-Boxen, neutrale Hinweise, Hilfe-Texte

2.3 Spezialfarben

Grey (Neutral-Skala)

Primäre Grau-Skala für Hintergründe, Borders, deaktivierte Zustände und Text.

• 100: #f5f5f5 (sehr helle Hintergründe)
• 200: #eeeeee (Borders, leichte Trenner)
• 300: #dddddd (Standard-Borders)
• 400: #cccccc (deaktivierte Elemente)
• 500: #aaaaaa (Platzhalter-Text)
• 600: #999999 (sekundärer Text)
• 700: #777777 (Standard-Text)
• 800: #555555 (dunkler Text)
• 900: #333333 (primärer Text)

Spezielle UI-Farben

• paper: #ebe3ce (Papier-Hintergrund für Texte)
• paper_light: #f2eee1
• paper_dark: #e0d1a6
• background: Weiß (Haupthintergrund)
• background_primary: #f2f2f6 (Alternative Hintergründe)

Fachspezifische Farben

• sammlung: #72b4cc (Sammlungen/Collections)
• sammlung_light: #d8e9f0
• lektion: #d9534f (Lektionen)
• lektion_light: #fad9da
• satzschritte: #a135ed (Satzschritte/Sentence Steps)
• satzschritte_light: #c570fa
• annotation: Rot-Abstufungen 100-900 (Textannotationen)
• adeo: #001b9d (Spezielle Lerneinheit)

Kategorie-Farben

• uebung-classic: #2B7BB5 (Klassische Übungen)
• uebung-ludus: #9C27B0 (Spiel-Übungen)
• uebung-default: #B22E2F (Standard-Übungen)

2.4 Transparente Farben

• weiss-25: Weiß mit 25% Opazität
• weiss-50: Weiß mit 50% Opazität
• weiss-75: Weiß mit 75% Opazität

Verwendung: Overlay-Effekte, Glasmorphism, Backdrop-Filter

2.5 Farbverwendungsrichtlinien

Hintergründe:

• Haupthintergrund: bg-white oder bg-background
• Sekundäre Bereiche: bg-grey-100 oder bg-background_primary
• Karten/Cards: bg-white mit shadow-sm
• Deaktiviert: bg-grey-100 oder bg-grey-200

Borders:

• Subtil: border-grey-200
• Standard: border-grey-300
• Stark: border-grey-400
• Status-abhängig: border-success, border-danger, etc.

Text:

• Primär: text-grey-900 oder text-primary-900
• Sekundär: text-grey-700 oder text-grey-600
• Deaktiviert: text-grey-500 oder text-grey-400
• Platzhalter: text-grey-500

---

3. Typografie

3.1 Schriftarten

Sans-Serif (Standard-UI)

Merriweather Sans wird für die gesamte Benutzeroberfläche verwendet.

• Tailwind-Klasse: font-sans
• Verwendung: Buttons, Labels, Body-Text, Navigation, Formulare

Serif (Lateinische Texte)

Merriweather wird ausschließlich für lateinische Texte und Zitate verwendet.

• Tailwind-Klasse: font-serif
• KRITISCHE REGEL: Lateinische Texte MÜSSEN IMMER font-serif font-bold haben
• Verwendung: Lateinische Vokabeln, Zitate, Textbeispiele

Monospace (Code)

Menlo, Monaco, Consolas für technische Inhalte.

• Tailwind-Klasse: font-mono
• Verwendung: Code-Snippets, technische Ausgaben

3.2 Typografie-Hierarchie

Überschriften

• h1 (Seitentitel): text-4xl oder text-5xl, font-bold
• h2 (Hauptabschnitte): text-3xl, font-bold
• h3 (Unterabschnitte): text-xl, font-bold
• h4 (Kleinere Abschnitte): text-lg, font-semibold
• h5: text-base, font-semibold
• h6: text-sm, font-semibold

Body-Text

• Standard: text-base (16px)
• Groß: text-lg (18px)
• Klein: text-sm (14px)
• Sehr klein: text-xs (12px)

Spezielle Texte

• Labels: text-sm, font-medium oder font-bold
• Hinweistexte: text-sm oder text-xs, normale Schriftgewichtung
• Platzhalter: text-sm, text-grey-500
• Links: text-primary-600, hover:text-primary-700
• Grammatikalische Infos: italic, text-grey-600

3.3 Lateintext-Formatierung

ABSOLUTE REGEL: Alle lateinischen Texte MÜSSEN mit font-serif font-bold formatiert werden.

Inline-Lateintext:

• Verwendung: <span class="font-serif font-bold">arma virumque cano</span>
• Optional mit Hintergrund: bg-grey-100 px-2 py-1 rounded

Block-Lateintext:

• Zusätzliche Klassen: text-lg oder text-xl
• Zitate: border-l-4 border-grey-300 pl-4

Vokabeln in Übungen:

• Besonders groß: text-4xl font-serif font-bold
• Mit grammatikalischer Info: Zusätzlich italic text-grey-500 font-light für die Info

3.4 Zeilenhöhe und Abstände

• Überschriften: leading-tight (1.25)
• Body-Text: leading-normal (1.5) oder leading-relaxed (1.625)
• Knappe Texte: leading-snug (1.375)

Absatz-Abstände:

• Zwischen Absätzen: mb-4 oder mb-6
• Zwischen Abschnitten: mb-8

---

4. Spacing-System

4.1 Tailwind Spacing-Skala

Hermeneus verwendet die Standard-Tailwind-Spacing-Skala (1 Einheit = 0.25rem = 4px):

• 0: 0px
• 1: 4px (0.25rem)
• 2: 8px (0.5rem)
• 3: 12px (0.75rem)
• 4: 16px (1rem)
• 5: 20px (1.25rem)
• 6: 24px (1.5rem)
• 8: 32px (2rem)
• 10: 40px (2.5rem)
• 12: 48px (3rem)
• 16: 64px (4rem)

4.2 Padding-Richtlinien

Container/Cards:

• Klein: p-4 (16px)
• Standard: p-6 (24px)
• Groß: p-8 (32px)

Buttons:

• Klein: px-3 py-1.5
• Standard: px-4 py-2
• Groß: px-6 py-3

Form-Elemente:

• Inputs: p-2 oder px-3 py-2
• Textareas: p-3 oder p-4

Listen und Tabellen:

• Tabellen-Zellen: p-3 oder p-4
• Listen-Items: px-4 py-3

4.3 Margin-Richtlinien

Abschnitte:

• Zwischen Hauptabschnitten: my-8 oder mt-8 mb-8
• Zwischen Unterabschnitten: my-6 oder mt-6 mb-6

Elemente:

• Standard-Abstände: mb-4
• Größere Abstände: mb-6 oder mb-8
• Kleinere Abstände: mb-2 oder mb-3

Inline-Elemente:

• Icons vor Text: mr-2 oder mr-3
• Icons nach Text: ml-2 oder ml-3
• Buttons nebeneinander: mr-2 oder space-x-2

4.4 Gap (Flexbox/Grid)

Flexbox-Layouts:

• Eng: gap-2 (8px)
• Standard: gap-4 (16px)
• Weit: gap-6 (24px) oder gap-8 (32px)

Grid-Layouts:

• Standard: gap-4 oder gap-6
• Karten-Grid: gap-6 oder gap-8

Spezielle Gap-Utilities:

• space-y-4: Vertikaler Abstand zwischen Kindern
• space-x-3: Horizontaler Abstand zwischen Kindern

---

5. Responsive Design

5.1 Breakpoint-System

Hermeneus verwendet ein erweitertes Breakpoint-System mit Plus/Minus-Modifikatoren für präzise Kontrolle.

Standard-Breakpoints

• sm: 640px - 767px (Mobile Landscape)
• md: 768px - 1023px (Tablet)
• lg: 1024px - 1365px (Desktop)
• xl: 1366px - 1535px (Large Desktop)
• 2xl: 1536px - 1919px (Extra Large)
• 3xl: ab 1920px (4K und größer)

Plus-Modifikatoren (min-width)

• sm-plus: min 640px (ab Mobile Landscape)
• md-plus: min 768px (ab Tablet)
• lg-plus: min 1024px (ab Desktop)
• xl-plus: min 1366px (ab Large Desktop)

Minus-Modifikatoren (max-width)

• sm-minus: max 767px (bis Mobile Portrait)
• md-minus: max 1023px (bis Tablet)
• lg-minus: max 1365px (bis Desktop)
• xl-minus: max 1365px (bis Desktop)

5.2 Responsive Patterns

Mobile-First-Ansatz: Standard-Styles gelten für Mobile, Erweiterungen für größere Screens.

Typische Verwendung:

• Volle Breite auf Mobile, eingeschränkt auf Desktop: w-full lg:w-2/3
• Spalten anpassen: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
• Verstecken auf Mobile: hidden md:block
• Nur auf Mobile zeigen: block md:hidden

Beispiel-Layout:

• Mobile (sm-minus): Einspaltiges Layout
• Tablet (md): Zweispaltiges Layout
• Desktop (lg-plus): Dreispaltiges Layout mit Sidebar

5.3 Container-Größen

Max-Widths:

• Standard-Container: max-w-7xl (1280px)
• Schmale Container (Formulare): max-w-2xl (672px)
• Breite Container (Tabellen): max-w-full
• Benutzerdefiniert: max-w-1/3 (33%)

Responsive Container:

• Zentriert: mx-auto
• Mit Padding: px-4 md:px-6 lg:px-8

---

6. Layout-Patterns

6.1 Haupt-Layout-Typen

Dashboard-Layout

• Grid-basiert mit Karten
• Responsive Grid: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6
• Karten: bg-white rounded-lg shadow-sm border border-grey-200 p-6

Formular-Layout

• Zentrierter Container: max-w-2xl mx-auto
• Vertikale Anordnung: flex flex-col space-y-6
• Sections mit Borders: border-b border-grey-200 pb-6 mb-6

Listen/Tabellen-Layout

• Volle Breite: w-full
• Filter oben: flex flex-row justify-between items-center mb-6
• Tabelle mit Scrolling: overflow-x-auto

Detail-Seiten-Layout

• Zwei-Spalten: flex flex-row gap-8
• Haupt-Content: w-2/3
• Sidebar: w-1/3
• Responsive: Auf Mobile einspaltiges Layout

6.2 Flexbox-Patterns

Container:

• Vertikal: flex flex-col
• Horizontal: flex flex-row
• Zentriert: flex items-center justify-center

Alignment:

• Items vertikal zentriert: items-center
• Items oben: items-start
• Items unten: items-end

Justification:

• Space between: justify-between (Elemente an beiden Enden)
• Zentriert: justify-center
• Start: justify-start
• Ende: justify-end

Wrapping:

• Umbrechen erlauben: flex-wrap
• Kein Umbrechen: flex-nowrap

Growth:

• Füllen: flex-1 oder flex-grow
• Nicht schrumpfen: flex-shrink-0

6.3 Grid-Patterns

Spalten-Definitionen:

• Zwei Spalten: grid grid-cols-2
• Drei Spalten: grid grid-cols-3
• Vier Spalten: grid grid-cols-4
• Auto-fit: grid grid-cols-[repeat(auto-fit,minmax(300px,1fr))]

Responsive Grids:

• grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4

Gap:

• Standard: gap-4 oder gap-6
• Unterschiedlich: gap-x-6 gap-y-4

6.4 Container-Patterns

Standard-Card:

• Klassen: bg-white rounded-lg shadow-sm border border-grey-200 p-6
• Hover-Effekt: hover:shadow-md transition-shadow

Elevated Card:

• Klassen: bg-white rounded-lg shadow-md p-6
• Ohne Border, stärkerer Schatten

Flat Card:

• Klassen: bg-grey-50 rounded-lg p-6
• Kein Schatten, subtiler Hintergrund

Content-Wrapper:

• Klassen: w-full p-4
• Mit Max-Width: max-w-7xl mx-auto px-4

---

7. Komponenten-Übersicht

7.1 Buttons

Standard-Button:

• Primär: Dunkler Hintergrund, weißer Text, Primary-Farbe
• Sekundär: Heller Hintergrund, dunkler Text, Secondary-Farbe
• Größen: Small, Standard, Large
• Icons: Optional vor oder nach dem Text

Status-Buttons:

• Success: Grüner Hintergrund
• Danger: Roter Hintergrund
• Warning: Gelber/oranger Hintergrund

Varianten:

• Outlined: Transparenter Hintergrund, farbiger Border
• Text: Kein Hintergrund, nur Text mit Hover-Effekt
• Icon-Button: Nur Icon, meist rund oder quadratisch

Zustände:

• Hover: Dunklere Schattierung
• Focus: Ring-Effekt in Primary-Farbe
• Disabled: Reduzierte Opazität, Cursor nicht erlaubt
• Active: Leicht herunterskaliert

7.2 Form-Elemente

Input-Felder

• Standard: Heller Hintergrund, grauer Border
• Focus: Primary-Border, optionaler Ring
• Error: Danger-Border, roter Text unterhalb
• Success: Success-Border
• Disabled: Grauer Hintergrund, reduzierte Opazität

Labels

• Position: Oberhalb des Inputs
• Schriftgröße: Klein bis mittel
• Schriftgewicht: Medium oder Bold
• Pflichtfelder: Stern oder "(erforderlich)"
• Beschreibungen: Kleinerer, leichterer Text unter dem Label

Textareas

• Auto-Resize: Wächst mit Inhalt
• Min-Height: Festgelegt für initiale Darstellung
• Ansonsten wie Input-Felder

Selects/Dropdowns

• PrimeVue Select bevorzugt
• Mit Suchfunktion bei vielen Optionen
• Multi-Select mit Chips/Tags

Checkboxen und Radio-Buttons

• PrimeVue-Komponenten bevorzugt
• Mit Label rechts oder unterhalb
• Gruppierung mit Space zwischen Items

Toggle-Switches

• Für Ja/Nein-Entscheidungen
• Farbwechsel bei Aktivierung

Slider

• Für Wertebereiche
• Mit Label und aktuellem Wert

Rating

• Sterne-Rating für Bewertungen
• Read-only oder interaktiv

7.3 Navigation

Haupt-Navigation

• Dunkler Hintergrund (Primary-800 oder Primary-900)
• Weiße oder helle Text-Farbe
• Aktive Items: Primary-600 Hintergrund oder Border-Indicator
• Hover: Leicht aufgehellt

Breadcrumbs

• Klein, sekundärer Text
• Trennzeichen: Pfeil oder Slash
• Letztes Element: Nicht klickbar, fett

Tabs

• Border-Bottom-Style bevorzugt
• Aktive Tab: Farbiger Border unten, fetter Text
• Hover: Hintergrund leicht aufgehellt

Sidebar-Navigation

• Heller Hintergrund (Grey-50)
• Border rechts (bei linker Sidebar)
• Aktive Items: Primary-50 Hintergrund, Border links
• Kollapsierbare Abschnitte

7.4 Daten-Darstellung

Tabellen

• Header: Grey-100 Hintergrund, fetter Text
• Zeilen: Abwechselnd oder mit Border zwischen
• Hover: Grey-50 Hintergrund
• Sortierbar: Icon im Header
• Paginierung: Unten zentriert

Listen

• Items mit Border zwischen
• Hover: Heller Hintergrund
• Selektiert: Primary-50 Hintergrund, farbiger Border links
• Icons oder Avatare: Links am Item

Cards/Kacheln

• Für Dashboard-Elemente
• Mit Header, Body, optional Footer
• Hover-Effekt: Schatten verstärken
• Click-Area: Ganze Card oder spezifischer Button

7.5 Overlays

Dialogs/Modals

• Zentriert auf Seite
• Dunkler Backdrop (Overlay)
• Weiße Card mit Schatten
• Header mit Titel und Close-Button
• Footer mit Aktions-Buttons

Popovers

• Kontextuelle Informationen
• Pfeil zeigt auf Trigger-Element
• Leichter Schatten
• Auto-Positioning

Tooltips

• Klein, dunkel
• Weißer Text
• Kurzer Text
• Erscheint bei Hover

7.6 Feedback-Komponenten

Toast-Messages

• Position: Meist oben rechts
• Typen: Success, Error, Warning, Info
• Icon links
• Auto-Dismiss nach Zeit
• Optional mit Close-Button

Alert-Boxen

• Volle Breite oder in Container
• Farbiger Hintergrund (leicht)
• Farbiger Border
• Icon links
• Optional mit Close-Button

Loading-Indikatoren

• Loading-Dots: Mittelgroß, für Sektionen
• Loading-Dual-Ring: Klein, inline
• Loading-Comet: Groß, für ganze Seiten
• Spinner: FontAwesome Spinner mit Spin-Animation
• Skeleton: PrimeVue Skeleton für Platzhalter
• ProgressBar: PrimeVue ProgressBar für Fortschritt

Empty States

• Zentriert
• Großes Icon (oft Grau)
• Beschreibender Text
• Optional Call-to-Action Button

---

8. PrimeVue-Integration

8.1 Verwendete PrimeVue-Komponenten

Hermeneus nutzt eine Auswahl angepasster PrimeVue-Komponenten. Die vollständige Liste findet sich in der Tailwind-CSS-Konfiguration.

Form-Komponenten:

• InputText, InputNumber, Textarea
• Select, MultiSelect
• DatePicker
• RadioButton, Checkbox
• ToggleSwitch
• Slider, Rating

Button-Komponenten:

• Button, ButtonGroup

Daten-Komponenten:

• Paginator

Overlay-Komponenten:

• Popover, Tooltip

Panel-Komponenten:

• Fieldset, Divider, Stepper

Sonstige:

• Badge, ProgressBar, Skeleton

8.2 PrimeVue-Anpassungen

Hermeneus verwendet ein benutzerdefiniertes Tailwind-Theme für PrimeVue. Alle Farben werden über CSS-Variablen im RGB-Format definiert.

Farbvariablen:

• Primary: --primary-50 bis --primary-950
• Secondary: --secondary-50 bis --secondary-950
• Grey/Surface: --grey-0 bis --grey-900
• Status: --success, --danger, --warning, --info

Tailwind-Klassen für PrimeVue:

• bg-primary-500, text-primary-700, etc.
• bg-surface-100, border-surface-300, etc.

Workaround-Klassen: Einige fehlende Tailwind-Definitionen wurden als Workaround in der PrimeVue-CSS definiert (z.B. min-w-2 bis min-w-13).

8.3 PrimeVue Best Practices

Bevorzugung:

• PrimeVue-Komponenten gegenüber nativen HTML-Elementen bevorzugen
• Props verwenden statt Custom-CSS
• Tailwind-Utilities über class-Prop anwenden

Severity-Prop (Buttons):

• primary, secondary, success, danger, warning, info

Size-Prop:

• small, large (Standard ist Medium)

Icons:

• FontAwesome-Klassen über icon-Prop: icon="fas fa-check"

---

9. Icon-System

9.1 FontAwesome (Primäres System)

Hermeneus nutzt FontAwesome als primäre Icon-Bibliothek.

Icon-Stile:

• Solid: fas fa-{icon-name} (Standard, gefüllt)
• Regular: far fa-{icon-name} (Outline)
• Brands: fab fa-{icon-name} (Marken-Logos)

Häufige Icons:

• Benutzer: fa-user
• Einstellungen: fa-cog
• Suche: fa-search
• Plus: fa-plus
• Check: fa-check
• X/Close: fa-times
• Pfeil rechts: fa-arrow-right
• Info: fa-info-circle
• Warnung: fa-exclamation-triangle
• Error: fa-times-circle
• Success: fa-check-circle

9.2 Hermeneus Custom Icons

Zusätzlich gibt es benutzerdefinierte Hermeneus-Icons für spezielle Anwendungsfälle.

Verwendung:

• Als Klasse: hi hi-{icon-name}
• Als Komponente: <hermeneus-icon name="hi-{icon-name}" />

Komponenten-Props:

• name: Icon-Name (z.B. "hi-uebung")
• height: Höhe in Pixel (z.B. "32", "48")
• color: Farbe (z.B. "hi-color-primary-600")

9.3 Icon-Größen

FontAwesome-Größen (über Tailwind):

• Extra Small: text-sm
• Small: text-lg oder text-xl
• Medium: text-2xl
• Large: text-3xl oder text-4xl
• Extra Large: text-5xl oder größer

Hermeneus-Icon-Größen (über height-Prop):

• Small: height="24"
• Medium: height="32"
• Large: height="48"
• Extra Large: height="72"

9.4 Icon-Farben

FontAwesome (über Tailwind):

• Klassen: text-primary-600, text-grey-500, etc.
• Kontext-abhängig: Farbklasse auf Icon oder Eltern-Element

Hermeneus-Icons (über color-Prop):

• Format: hi-color-{colorname}-{shade}
• Beispiele: hi-color-primary-600, hi-color-success-500

9.5 Icon-Spacing

Vor Text:

• Klassen: mr-2 (8px) oder mr-3 (12px)

Nach Text:

• Klassen: ml-2 oder ml-3

Standalone:

• Kein zusätzliches Spacing erforderlich
• Optional Padding für Click-Area: p-2

---

10. Animationen und Transitions

10.1 CSS-Transitions

Standard-Transition:

• Klasse: transition-all duration-200
• Verwendung: Allgemeine Hover-Effekte, Farbwechsel

Schnelle Transition:

• Klasse: transition-all duration-100
• Verwendung: Sofortiges Feedback, Button-Klicks

Langsame Transition:

• Klasse: transition-all duration-300 oder duration-500
• Verwendung: Sanfte Layout-Änderungen, Akkordions

Spezifische Transitions:

• Farben: transition-colors
• Schatten: transition-shadow
• Transform: transition-transform
• Opazität: transition-opacity

10.2 Keyframe-Animationen

Spin (Spinner):

• Animation: Rotation 360 Grad in 4 Sekunden, endlos
• Klasse: animate-spin oder .spinner
• Verwendung: Loading-Indikatoren

Fade-In:

• Animation: Opazität 0 zu 1 in 0.5s
• Klasse: fade-in oder animate-fade-in
• Verwendung: Einblenden von Elementen

Fade-Out:

• Animation: Opazität 1 zu 0 in 0.5s
• Klasse: fade-out oder animate-fade-out
• Verwendung: Ausblenden von Elementen

Bounce:

• Animation: Kurzes Auf-und-Ab in 0.5s
• Klasse: .bounce
• Verwendung: Erfolgs-Feedback, Aufmerksamkeit erregen

Slide-Down (Vue Transition):

• Name: slide-down
• Animation: Max-Height und Opazität, 0.3s
• Verwendung: Expand/Collapse-Bereiche

10.3 Transform-Effekte

Scale bei Hover:

• Klasse: hover:scale-105 oder hover:scale-102
• Verwendung: Karten, Buttons (subtiles Feedback)

Scale bei Active:

• Klasse: active:scale-95
• Verwendung: Buttons (Klick-Feedback)

Translate bei Hover:

• Klasse: hover:-translate-y-1
• Verwendung: Cards (Lift-Effekt)

Rotation:

• Klasse: hover:rotate-3 oder hover:rotate-6
• Verwendung: Icons, spielerische Elemente

10.4 Spezielle Animationen (Vokabelabfrage)

Für Vokabel-Abfrage-Komponenten existieren zusätzliche spezialisierte Animationen (siehe separaten Vokabelabfrage-Style-Guide):

• fadeInUp: Eingangsbewegung von unten
• feedbackSlideIn: Feedback-Einblendung
• successBounce: Erfolgs-Animation mit Rotation
• errorShake: Fehler-Shake-Effekt

---

11. Interaktive Zustände

11.1 Hover-Zustände

Links:

• Text-Farbe: hover:text-primary-700 (dunklere Schattierung)
• Unterstreichen: hover:underline
• Kombination: Beides möglich

Buttons:

• Hintergrund: Dunklere Schattierung (z.B. hover:bg-primary-700)
• Schatten: Verstärken (hover:shadow-md oder hover:shadow-lg)
• Transform: Leicht vergrößern (hover:scale-105)

Cards/Kacheln:

• Schatten: Verstärken (hover:shadow-md)
• Border: Farbiger Border (hover:border-primary-500)
• Transform: Leicht anheben (hover:-translate-y-1)

Listen-Items:

• Hintergrund: hover:bg-grey-50 oder hover:bg-grey-100

Icons:

• Farbe: hover:text-primary-600 (von Grau zu Primary)
• Rotation: hover:rotate-6 (spielerisch)

Transition: IMMER transition-all oder spezifische Transition hinzufügen!

11.2 Focus-Zustände

Input-Felder:

• Border: focus:border-primary-500
• Ring: focus:ring-2 focus:ring-primary-200 oder focus:ring-primary-500
• Outline: focus:outline-none (wenn Ring verwendet wird)

Buttons:

• Ring: focus:ring-2 focus:ring-primary-500
• Offset: Optional focus:ring-offset-2
• Outline: focus:outline-none

Links:

• Outline: Standard-Browser-Outline oder focus:outline-none focus:underline

Accessibility: Focus-Zustände MÜSSEN sichtbar sein für Keyboard-Navigation!

11.3 Active/Selektierte Zustände

Navigation (aktiver Link):

• Hintergrund: bg-primary-600 mit text-white
• Border: Farbiger Border (z.B. links: border-l-4 border-primary-600)
• Schrift: Fett (font-bold)

Listen-Items (selektiert):

• Hintergrund: bg-primary-50
• Border: border-l-4 border-primary-500
• Optional Icon oder Check-Mark

Tabs (aktiv):

• Border unten: border-b-2 border-primary-600
• Text: text-primary-600 font-semibold

Buttons (beim Klicken):

• Transform: active:scale-95 (kurzes Herunterskalieren)

11.4 Disabled-Zustände

Allgemein:

• Opazität: opacity-50 oder opacity-60
• Cursor: cursor-not-allowed

Buttons:

• Hintergrund: bg-grey-400 (statt Farbe)
• Text: text-grey-600
• Kein Hover-Effekt

Input-Felder:

• Hintergrund: bg-grey-100 oder bg-grey-200
• Text: text-grey-500
• Border: border-grey-300

Links:

• Text: text-grey-400
• Kein Hover oder Click

Icons:

• Farbe: text-grey-400 oder text-grey-500

---

12. Feedback-Systeme

12.1 Toast-Messages (IrisMessenger)

Verwendung:

• API: this.$IrisMessenger.bar()
• Position: Standardmäßig oben rechts

Typen:

• type: 'success': Grüner Hintergrund, Check-Icon
• type: 'error': Roter Hintergrund, X-Icon
• type: 'warning': Gelber Hintergrund, Warning-Icon
• type: 'info': Blauer Hintergrund, Info-Icon

Properties:

• message: Nachrichtentext
• duration: Anzeigedauer in Millisekunden (z.B. 4000)

Best Practices:

• Kurze, prägnante Nachrichten
• Auto-Dismiss nach 3-5 Sekunden
• Für kurzfristige Bestätigungen und Fehler

12.2 Alert-Boxen

Info-Alert:

• Hintergrund: bg-info-light
• Border: border border-info
• Text: text-info-contrast
• Icon: fa-info-circle

Success-Alert:

• Hintergrund: bg-success-light
• Border: border border-success
• Text: text-success-dark
• Icon: fa-check-circle

Warning-Alert:

• Hintergrund: bg-warning-light
• Border: border border-warning
• Text: text-warning-dark
• Icon: fa-exclamation-triangle

Error-Alert:

• Hintergrund: bg-danger-light
• Border: border border-danger
• Text: text-danger-dark
• Icon: fa-times-circle

Struktur:

• Container: rounded p-4
• Icon: Links, mr-3
• Text: Rechts davon
• Optional Close-Button: Rechts oben

Best Practices:

• Für länger angezeigte Meldungen
• Kontext-abhängig in relevanten Bereichen
• Mit Close-Button für Nutzer-Kontrolle

12.3 Loading-Indikatoren

Globale Komponenten:

• <loading-dots>: Mittelgroß, für Sektionen und Cards
• <loading-dual-ring>: Klein, inline in Buttons oder Text
• <loading-comet>: Groß, für ganze Seiten oder Overlays

FontAwesome Spinner:

• Klasse: fas fa-spinner fa-spin
• Größe: Über Tailwind (text-xl, text-2xl, etc.)
• Verwendung: Inline-Loading, Button-Icons

PrimeVue Skeleton:

• Komponente: <Skeleton>
• Props: height, width, borderRadius, animation
• Verwendung: Platzhalter für Inhalte während Ladezeit

PrimeVue ProgressBar:

• Komponente: <ProgressBar>
• Props: value (0-100), showValue, mode (determinate/indeterminate)
• Verwendung: Fortschrittsanzeige bei längeren Prozessen

Best Practices:

• Sofortiges Feedback bei Aktion
• Klarer Hinweis auf Lade-Status
• Skeleton für Content-Heavy-Bereiche

12.4 Empty States

Struktur:

• Container: Zentriert, text-center py-12
• Icon: Groß, Grau (text-6xl text-grey-400)
• Überschrift: text-xl font-semibold text-grey-700 mb-2
• Beschreibung: text-grey-600
• Optional: Call-to-Action Button

Verwendung:

• Leere Listen oder Tabellen
• Keine Suchergebnisse
• Fehlende Daten

Best Practices:

• Freundlicher, hilfreicher Ton
• Aktion anbieten (z.B. "Erstellen Sie Ihren ersten Eintrag")
• Passendes Icon zum Kontext

---

13. Accessibility (Barrierefreiheit)

13.1 Fokus-Management

Keyboard-Navigation:

• Alle interaktiven Elemente MÜSSEN mit Tastatur erreichbar sein
• Tab-Reihenfolge logisch und nachvollziehbar
• Focus-Trap in Modals (Fokus bleibt im Dialog)

Focus-Indikatoren:

• IMMER sichtbare Focus-Indikatoren bereitstellen
• Mindestens Ring oder Border bei Fokus
• Kontrast: Ausreichend zum Hintergrund

TabIndex:

• Native interaktive Elemente haben automatisch TabIndex
• Custom-Komponenten: tabindex="0" für fokussierbar
• tabindex="-1" für programmatisches Fokussieren ohne Tab-Erreichbarkeit

13.2 Farb-Kontraste

WCAG AA Standards:

• Normal-Text (unter 18px): Mindestens 4.5:1 Kontrast
• Großer Text (ab 18px oder 14px fett): Mindestens 3:1 Kontrast
• UI-Komponenten: Mindestens 3:1 Kontrast

Hermeneus Kontraste:

• Primary-900 auf Weiß: Ausreichend
• Grey-700 auf Weiß: Ausreichend
• Status-Farben (dark) auf hell: Geprüft und konform

Nicht nur Farbe:

• Informationen NICHT ausschließlich über Farbe vermitteln
• Zusätzlich Icons, Text oder Patterns verwenden
• Beispiel: Fehlermeldungen mit rotem Border UND Icon

13.3 Screen Reader Support

Semantische HTML-Elemente:

• <button> für Buttons (nicht <div>)
• <a> für Links
• <nav> für Navigation
• <main>, <header>, <footer>, <article>, <section>

Labels und Alt-Texte:

• Alle Formular-Elemente mit <label> verknüpfen
• Bilder mit aussagekräftigem alt-Attribut
• Icons: Wenn dekorativ, aria-hidden="true"; wenn funktional, aria-label

ARIA-Attribute:

• aria-label: Beschreibung für Screen Reader
• aria-labelledby: Referenz auf beschreibendes Element
• aria-describedby: Zusätzliche Beschreibung
• aria-live: Für dynamische Inhalte (z.B. Toast-Messages)
• role: Für nicht-semantische Elemente (z.B. role="button")

Best Practices:

• ARIA sparsam einsetzen (HTML-Semantik bevorzugen)
• Beschreibungen klar und prägnant
• Interaktive Elemente ankündigen (z.B. "Button: Speichern")

13.4 Weitere Accessibility-Richtlinien

Textgröße:

• Benutzer sollten Text bis 200% vergrößern können
• Layout sollte nicht brechen

Animationen:

• Respekt vor prefers-reduced-motion Media Query
• Reduzierte Animationen für Nutzer mit Motion-Sensitivität

Tastatur-Shortcuts:

• Dokumentiert und logisch
• Keine Konflikte mit Browser-Shortcuts
• Hinweise für Nutzer (z.B. mit <kbd> Tag)

---

14. Styling-Konventionen

14.1 Tailwind-First-Ansatz

Grundprinzip: Tailwind-Utility-Klassen sind die primäre Styling-Methode.

Wann Tailwind:

• Alle Standard-Styles (Farben, Spacing, Typography, etc.)
• Layout (Flexbox, Grid)
• Responsive Design
• Interaktive Zustände (Hover, Focus)

Wann Custom-CSS:

• Komplexe Animationen (Keyframes)
• Sehr spezifische Komponenten-Styles
• Wiederholte, komplexe Style-Kombinationen (besser als Komponente)

14.2 CSS-Scoping

Scoped Styles (Vue):

• Verwendet für Komponenten-spezifische Styles
• Vermeidet globale Konflikte
• Nur wenn Tailwind nicht ausreicht

Globale Styles:

• Für app-weite Definitionen
• Basis-Styles, Resets, Fonts
• In resources/css/app.css und Unterordnern

Naming:

• BEM-Konvention (Block-Element-Modifier) für Custom-Klassen
• Beispiel: .card__header--highlighted

14.3 Code-Organisation

Klassen-Gruppierung:

• Layout zuerst (Flexbox, Grid, Positioning)
• Größen (Width, Height, Padding, Margin)
• Typografie (Font, Text)
• Farben (Background, Text, Border)
• Effekte (Shadow, Rounded, Opacity)
• Interaktive Zustände (Hover, Focus)

Beispiel:

flex items-center justify-between
w-full px-4 py-2
text-lg font-bold
bg-primary-600 text-white border border-primary-700
rounded-lg shadow-sm
hover:bg-primary-700 focus:ring-2 focus:ring-primary-500

Multi-Line bei vielen Klassen:

• Bei mehr als 5-7 Utility-Klassen: Zeilenumbruch für Lesbarkeit

14.4 Komponenten-Extraktion

Wann Komponente erstellen:

• Wiederholte Style-Kombinationen (mehr als 3x)
• Komplexe Logik + Styling
• Isolierte Funktionalität

Wann Tailwind-Klassen wiederholen:

• Einfache, gelegentliche Wiederholung
• Kontext-spezifisches Styling

Component Props:

• Varianten über Props steuern (z.B. severity, size)
• Tailwind-Klassen über class-Prop ergänzen

14.5 Spezielle Konventionen

Lateintext:

• IMMER font-serif font-bold
• Keine Ausnahmen

Config-Properties (Backend):

• Prefix cfg_ für Konfigurations-Felder in Datenbank-Tabellen

Module-Aliases:

• Immer kebab-case (z.B. uebung-bedeutungen-zuordnen)

Komponenten-Dateien:

• Vue-Komponenten: PascalCase mit Component.vue Endung
• Beispiel: UebungActivitasComponent.vue

Pinia Stores:

• camelCase mit Store.js Suffix
• Beispiel: uebungActivitasCreateStore.js

---

15. Best Practices

15.1 Konsistenz

Design Tokens verwenden:

• Niemals Arbitrary Values (z.B. w-[243px])
• Immer definierte Farben, Spacing, etc. aus dem Design-System
• Ausnahmen nur nach Rücksprache

Patterns wiederholen:

• Etablierte Patterns für ähnliche Komponenten übernehmen
• Nicht jede Komponente neu "erfinden"
• Beispiele in Nachbar-Komponenten suchen

Spacing konsistent halten:

• Gleiche Abstände für gleiche Elemente
• Spacing-Hierarchie beachten (Groß für Sections, Klein für Elemente)

15.2 Performance

Tailwind Purging:

• In Produktion: Nur verwendete Klassen im Build
• safelist für dynamisch generierte Klassen

Lazy Loading:

• Schwere Komponenten (z.B. Charts, große Listen) lazy laden
• Vue's defineAsyncComponent verwenden

Asset-Optimierung:

• Bilder komprimiert und in modernen Formaten (WebP)
• Icons als SVG oder Icon-Fonts (statt PNG)
• Fonts: Nur benötigte Weights und Subsets laden

CSS-Performance:

• Scoped Styles sparsam einsetzen
• Vermeiden von tiefen Selektoren
• Tailwind JIT-Modus für schnellere Builds

15.3 Wartbarkeit

Dokumentation:

• Komplexe Komponenten dokumentieren
• Props und Events beschreiben
• Verwendungsbeispiele bereitstellen

Kommentare:

• Warum, nicht Was (Code zeigt das Was)
• Magic Numbers erklären
• Workarounds kennzeichnen

Refactoring:

• Wiederholten Code in Komponenten extrahieren
• Große Komponenten in kleinere aufteilen
• Regelmäßig Code-Reviews

15.4 Entwicklungs-Workflow

Pattern-Recherche:

• Vor neuer Implementierung: Nachbar-Dateien prüfen
• Bestehende Patterns wiederverwenden
• Bei Unklarheiten: Team fragen

Testing:

• Visuelles Testing in verschiedenen Viewports
• Accessibility-Testing (Keyboard, Screen Reader)
• Cross-Browser-Testing

Design-System-Updates:

• Neue Patterns dokumentieren
• Bei Änderungen: Bestehende Nutzungen prüfen
• Style-Guide aktuell halten

15.5 Häufige Fehler vermeiden

Inline-Styles vermeiden:

• Kein style-Attribut in Templates
• Tailwind oder Scoped CSS verwenden

!important vermeiden:

• Nur in absoluten Ausnahmefällen
• Meist Zeichen für schlechte Struktur

Zu viele Custom-Klassen:

• Tailwind bevorzugen
• Custom-Klassen nur wenn nötig

Inkonsistente Spacing:

• Nicht wild mischen (z.B. p-3 und p-5 nebeneinander)
• System einhalten

Fehlende Responsiveness:

• Immer Mobile-First denken
• Breakpoints testen

Accessibility ignorieren:

• Von Anfang an mitdenken
• Nicht "später hinzufügen"

---

16. Schlusswort

Dieser Master-Style-Guide ist ein lebendiges Dokument und sollte regelmäßig aktualisiert werden, wenn neue Patterns etabliert oder bestehende verfeinert werden. Bei Fragen oder Unklarheiten konsultiere bestehende Komponenten oder sprich mit dem Team.

Wichtigste Prinzipien:

1. Tailwind-First
2. Konsistenz über alles
3. Accessibility von Anfang an
4. Lateintext immer Serif + Bold
5. PrimeVue bevorzugen

Weitere Ressourcen:

• Hermeneus Application Style Guide (detaillierte Komponenten-Beispiele)
• Style-Guide für Vokabelabfrage-Komponenten (spezialisiert)
• Coding-Style Guide (Backend-Konventionen)
• Tailwind CSS Dokumentation
• PrimeVue Dokumentation

---

Versionierung:

• v1.0: Initial Release (2025-11-14)

Kontakt: Bei Fragen zum Design-System wende dich an das Frontend-Team.