# Invoice Form Design Documentation
**myCRM Billing Module - UX/UI Design System**

---

## Übersicht

Diese Design-Dokumentation enthält eine umfassende UX/UI-Analyse und Verbesserungsvorschläge für das Invoice-Formular im myCRM Billing-Modul. Die Dokumentation folgt professionellen UI/UX-Design-Standards und berücksichtigt Accessibility-Anforderungen nach WCAG 2.1 AA/AAA.

---

## Dokumenten-Struktur

### 1. Hauptdokumentation

**[INVOICE_FORM_UX_DESIGN.md](./INVOICE_FORM_UX_DESIGN.md)**
- Vollständige UX/UI-Analyse des bestehenden Invoice-Formulars
- Identifizierte Probleme und Verbesserungspotenziale (P0, P1, P2)
- Design-Prinzipien und Konzepte
- Detaillierte Komponentenspezifikationen
- Accessibility-Guidelines (WCAG 2.1 AA/AAA)
- Implementierungs-Roadmap (6 Phasen)
- Testing-Strategie

**Umfang:** ~350 Zeilen | Geschätzte Lesezeit: 30-40 Minuten

### 2. Visuelle Design-Referenz

**[VISUAL_DESIGN_GUIDE.md](./VISUAL_DESIGN_GUIDE.md)**
- Farbpalette und Kontraste
- Typography-System
- Spacing-System (4px Base Unit)
- Komponent-Anatomie mit ASCII-Diagrammen
- Interaktive States (Buttons, Inputs, etc.)
- Animation und Transitions
- Responsive Breakpoints
- Iconographie
- Error Handling Patterns
- Loading & Empty States
- Print Styles

**Umfang:** ~500 Zeilen | Geschätzte Lesezeit: 20-25 Minuten

### 3. Referenz-Implementierung

**[invoice-form-improved.vue](./invoice-form-improved.vue)**
- Vollständige Vue.js 3 Komponente mit allen Verbesserungen
- PrimeVue Komponenten-Integration
- Composition API Pattern
- Verwendung von Composables (useFormValidation, useKeyboardShortcuts)
- Accessibility-Features (ARIA-Labels, Focus Management)
- Responsive Design
- Animations & Transitions

**Umfang:** ~600 Zeilen | Typ: Vue SFC (Single File Component)

### 4. CSS Design System

**[invoice-form-styles.css](./invoice-form-styles.css)**
- CSS Custom Properties (Design Tokens)
- Komponent-spezifische Styles
- Layout-Utilities
- Animation Keyframes
- Responsive Media Queries
- Dark Mode Support
- Accessibility Utilities (sr-only, focus-visible)
- Print Styles

**Umfang:** ~800 Zeilen | Typ: CSS

### 5. Composables

#### **[useFormValidation.js](./composables/useFormValidation.js)**
- Wiederverwendbare Form-Validierungslogik
- Echtzeit-Validierung
- Feld-spezifische Regeln
- Error-Tracking
- Vordefinierte Validierungsregeln (email, phone, IBAN, etc.)

**Umfang:** ~400 Zeilen | Typ: JavaScript Composable

#### **[useKeyboardShortcuts.js](./composables/useKeyboardShortcuts.js)**
- Keyboard-Shortcut-Management
- Modifier-Key-Support (Ctrl, Shift, Alt)
- Conflict-Detection
- Platform-spezifische Hints (Mac vs. Windows)
- Preset-Shortcuts für gängige Aktionen

**Umfang:** ~400 Zeilen | Typ: JavaScript Composable

---

## Quick Start Guide

### Für Designer

1. **Beginnen Sie mit:** [INVOICE_FORM_UX_DESIGN.md](./INVOICE_FORM_UX_DESIGN.md) - Executive Summary
2. **Dann:** [VISUAL_DESIGN_GUIDE.md](./VISUAL_DESIGN_GUIDE.md) - Farbpalette & Typography
3. **Zuletzt:** Komponent-Anatomie-Diagramme für Implementierungs-Übergabe

### Für Entwickler

1. **Beginnen Sie mit:** [invoice-form-improved.vue](./invoice-form-improved.vue) - Referenz-Implementierung
2. **Dann:** [invoice-form-styles.css](./invoice-form-styles.css) - Styling-Referenz
3. **Integrieren Sie:** Composables aus `./composables/` für Validierung und Shortcuts
4. **Referenzieren Sie:** [INVOICE_FORM_UX_DESIGN.md](./INVOICE_FORM_UX_DESIGN.md) - Implementierungs-Roadmap

### Für Product Owner

1. **Beginnen Sie mit:** [INVOICE_FORM_UX_DESIGN.md](./INVOICE_FORM_UX_DESIGN.md) - Executive Summary & Problemanalyse
2. **Dann:** Implementierungs-Roadmap (Phase 1-6)
3. **Priorisieren Sie:** Nach P0 (kritisch), P1 (mittel), P2 (niedrig) Tags

---

## Key Features des Design-Konzepts

### UX-Verbesserungen

- **Klarere visuelle Hierarchie** durch Sektionierung und konsistentes Spacing
- **Card-basierte Rechnungspositionen** statt komplexer DataTable
- **Echtzeit-Summenberechnung** mit sofortigem Feedback
- **Verbesserte Validierung** mit Inline-Feedback
- **Empty States** für bessere Benutzerführung
- **Context Cards** für kontextuelle Informationen (Payment Form)
- **Drag & Drop** für PDF-Upload

### Accessibility (WCAG 2.1)

- **Keyboard Navigation** mit Focus-Trapping und Shortcuts
- **ARIA-Labels** für Screen Reader Support
- **Farbkontrast** WCAG AA/AAA konform
- **Focus Management** mit sichtbaren Focus-States
- **Live Regions** für dynamische Updates

### Performance

- **Lazy Loading** von Formular-Komponenten
- **Debouncing** für Berechnungen
- **Virtual Scrolling** für lange Listen
- **Code Splitting** für optimale Bundle-Größen

### Responsive Design

- **Mobile First** Ansatz
- **Touch-friendly** Elemente (min. 44px)
- **Adaptive Layouts** für alle Bildschirmgrößen
- **Sticky Summary** auf Mobile für bessere Übersicht

---

## Implementierungs-Phasen

### Phase 1: Foundation (Woche 1-2)
**Priorität:** P0 (Kritisch)
- Styling-System aufsetzen
- Formular-Layout refactoren
- FloatLabel implementieren
- Validation Composable erstellen

**Geschätzter Aufwand:** 16-20 Stunden

### Phase 2: Invoice Items Redesign (Woche 3)
**Priorität:** P0 (Kritisch)
- Card-basierte Positions-Ansicht
- Echtzeit-Summenberechnung
- Transitions für Add/Remove
- Empty State Design

**Geschätzter Aufwand:** 12-16 Stunden

### Phase 3: Enhanced Forms (Woche 4)
**Priorität:** P1 (Mittel)
- PaymentForm Context Card
- PDF Upload Drag & Drop
- Quick Amount Buttons
- Keyboard Shortcuts

**Geschätzter Aufwand:** 10-14 Stunden

### Phase 4: UX Polish (Woche 5)
**Priorität:** P1 (Mittel)
- Loading States & Skeletons
- Micro-Interactions & Animations
- Toast-Benachrichtigungen
- Error Handling

**Geschätzter Aufwand:** 8-12 Stunden

### Phase 5: Accessibility (Woche 6)
**Priorität:** P0 (Kritisch)
- ARIA Labels hinzufügen
- Focus Management
- Keyboard Navigation
- Screen Reader Testing

**Geschätzter Aufwand:** 10-14 Stunden

### Phase 6: Testing & Optimization (Woche 7)
**Priorität:** P1 (Mittel)
- Unit Tests schreiben
- E2E Tests implementieren
- Performance Profiling
- Code Splitting optimieren

**Geschätzter Aufwand:** 12-16 Stunden

**Gesamt:** 68-92 Stunden (ca. 2-2.5 Monate für einen Entwickler)

---

## Design-Prinzipien

### 1. Progressive Disclosure
Zeige nur relevante Informationen zum richtigen Zeitpunkt. Komplexität wird schrittweise enthüllt.

**Beispiel:** Notizen-Sektion standardmäßig kollabiert, Summary Box nur wenn Items vorhanden.

### 2. Immediate Feedback
Sofortige Rückmeldung auf Benutzeraktionen. Keine verzögerten oder fehlenden Bestätigungen.

**Beispiel:** Echtzeit-Berechnung der Zwischensummen beim Eingeben, Toast-Benachrichtigungen nach Aktionen.

### 3. Error Prevention
Validierung bevor Fehler entstehen. Eingaben werden direkt beim Tippen geprüft.

**Beispiel:** Inline-Validierung, Min-Date beim Fälligkeitsdatum verhindert ungültige Daten.

### 4. Consistency
Einheitliche Nutzung von PrimeVue-Komponenten, Farben, Spacing und Patterns.

**Beispiel:** Alle Formularfelder nutzen FloatLabel, alle Buttons haben einheitliche Größen.

### 5. Accessibility First
Design und Implementierung berücksichtigen von Anfang an alle Nutzer, einschließlich Menschen mit Behinderungen.

**Beispiel:** Keyboard Navigation, Screen Reader Support, ausreichende Kontraste.

---

## Technologie-Stack

### Frontend Framework
- **Vue.js 3** (Composition API)
- **PrimeVue 4.x** (Aura Theme)
- **Tailwind CSS v4** (mit PrimeUI Plugin)

### Build & Dev Tools
- **Webpack Encore**
- **Symfony 7.1 LTS** (Backend)
- **API Platform** (REST API)

### Testing
- **Vitest** (Unit Tests)
- **Cypress/Playwright** (E2E Tests)
- **axe DevTools** (Accessibility Testing)

---

## Browser-Kompatibilität

### Unterstützte Browser
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile Safari 14+
- Chrome Android 90+

### Polyfills
- Intl.NumberFormat (bereits vorhanden)
- CSS Custom Properties (nativ unterstützt)

---

## Design-Assets

### Farbpalette
Siehe [VISUAL_DESIGN_GUIDE.md - Section 1](./VISUAL_DESIGN_GUIDE.md#1-farbpalette--kontraste)

### Icons
**PrimeIcons** (pi-*) - Vollständige Icon-Bibliothek integriert
- ~250 Icons verfügbar
- SVG-basiert, skalierbar
- Konsistenter Stil

### Typography
**System Font Stack** für optimale Performance:
```css
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
             'Helvetica Neue', Arial, sans-serif;
```

### Illustrations
Optional für Empty States: **unDraw** (lizenzfrei)

---

## Testing-Strategie

### Unit Tests
- Validierungs-Logik testen
- Berechnungs-Funktionen testen
- Composables isoliert testen

### Integration Tests
- Formular-Submission testen
- API-Integration testen
- State-Management testen

### E2E Tests
- Komplette User-Flows testen
- Rechnungserstellung Ende-zu-Ende
- Zahlungserfassung testen

### Accessibility Tests
- axe DevTools Audit
- NVDA/VoiceOver Screen Reader Testing
- Keyboard-Navigation manuell testen
- Farbkontrast-Validierung

### Performance Tests
- Lighthouse Audit (Score > 90)
- Bundle-Size-Analyse
- Time to Interactive < 3s
- First Contentful Paint < 1.5s

---

## Häufige Fragen (FAQ)

### Warum FloatLabel statt normale Labels?

**Antwort:** FloatLabel bietet mehrere Vorteile:
- Moderneres, aufgeräumteres Design
- Platzsparend (kein separater Label-Space)
- Bessere visuelle Hierarchie
- Klarer Fokus-Zustand
- Bereits in PrimeVue integriert

### Warum Cards statt DataTable für Invoice Items?

**Antwort:** Cards bieten bessere UX:
- Einfacheres Inline-Editing
- Bessere mobile Darstellung
- Klare visuelle Trennung
- Flexiblere Layouts
- Bessere Accessibility

### Wie wird Dark Mode unterstützt?

**Antwort:**
- PrimeVue Aura Theme hat nativen Dark Mode Support
- CSS Custom Properties passen sich automatisch an
- Spezielle Dark Mode Overrides wo nötig (siehe invoice-form-styles.css)
- App-Toggle über `.app-dark` CSS-Klasse

### Ist das Design responsive?

**Antwort:** Ja, vollständig:
- Mobile First Ansatz
- 5 Breakpoints (< 576px bis > 1920px)
- Touch-friendly Elemente (min. 44px)
- Adaptive Layouts für alle Größen
- Stack-Layout auf Mobile

### Wie werden Fehler behandelt?

**Antwort:**
- Inline-Validierung (on blur)
- Submit-Validierung (alle Felder)
- Toast-Benachrichtigungen für System-Fehler
- Visuelle Error-States (rote Border + Message)
- ARIA Live Regions für Screen Reader

---

## Nächste Schritte

### Sofort umsetzbar (Quick Wins)

1. FloatLabel für alle Formular-Felder einführen
2. Status-Tag in Formular-Header einbauen
3. Verbesserter Kunden-Dropdown mit Icons
4. Echtzeit-Summenberechnung implementieren
5. Quick Amount Buttons im PaymentForm

**Aufwand:** ~8 Stunden | **Impact:** Hoch

### Mittelfristig (1-2 Sprints)

1. Card-basiertes Positions-Management
2. Comprehensive Validation Composable
3. Keyboard Shortcuts System
4. Loading States & Skeletons

**Aufwand:** ~30 Stunden | **Impact:** Sehr hoch

### Langfristig (2+ Sprints)

1. Drag & Drop PDF Upload
2. Vollständige WCAG AAA Konformität
3. PWA Features (Offline Support)
4. Advanced Analytics Integration

**Aufwand:** ~50 Stunden | **Impact:** Mittel-Hoch

---

## Mitwirkende

**Design & Konzeption:**
- Claude (UX Designer Agent) - Initial Design & Dokumentation

**Review & Feedback:**
- [Ihr Team hier eintragen]

**Implementierung:**
- [Entwickler hier eintragen]

---

## Änderungshistorie

| Version | Datum      | Autor          | Änderungen                         |
|---------|------------|----------------|------------------------------------|
| 1.0     | 2025-12-12 | Claude (UX)    | Initiale Dokumentation erstellt    |

---

## Lizenz & Copyright

© 2025 myCRM Project
Interne Dokumentation - Vertraulich

---

## Kontakt & Support

Bei Fragen zur Design-Dokumentation:
- Erstellen Sie ein Issue im Repository
- Kontaktieren Sie das Design-Team
- Schlagen Sie Verbesserungen via Pull Request vor

---

**Letzte Aktualisierung:** 2025-12-12
**Dokument-Version:** 1.0
**Status:** In Review ✓