big upgrade

.kiro/specs/system-theme-detection/requirements.md

@@ -0,0 +1,80 @@
+# Anforderungsdokument – System-Theme-Erkennung (Light/Dark Mode)
+
+## Einleitung
+
+Die Webseite (React + Tailwind + shadcn/ui) verwendet aktuell ein fest eingestelltes dunkles Farbschema. Es soll eine automatische Erkennung der Betriebssystem-Einstellung (Light/Dark Mode) eingeführt werden, sodass die Webseite das passende Theme anzeigt. Zusätzlich soll der Benutzer das Theme manuell umschalten können. Die Präferenz wird im Browser gespeichert, damit sie bei erneutem Besuch erhalten bleibt.
+
+## Glossar
+
+- **Theme_Provider**: Die React-Kontextkomponente, die das aktuelle Theme verwaltet und an alle Kindkomponenten weitergibt. Basiert auf `next-themes`.
+- **Theme_Toggle**: Die UI-Komponente (Button), mit der der Benutzer manuell zwischen Light Mode, Dark Mode und System-Automatik wechseln kann.
+- **System_Theme**: Die vom Betriebssystem des Benutzers bevorzugte Farbeinstellung (hell oder dunkel), ermittelt über die CSS-Media-Query `prefers-color-scheme`.
+- **Light_Theme**: Das helle Farbschema mit CSS-Custom-Properties für helle Hintergründe und dunkle Texte.
+- **Dark_Theme**: Das dunkle Farbschema mit CSS-Custom-Properties für dunkle Hintergründe und helle Texte (aktuell als `:root`-Standard definiert).
+- **Theme_Präferenz**: Die vom Benutzer gewählte Einstellung (`light`, `dark` oder `system`), gespeichert im `localStorage`.
+
+## Anforderungen
+
+### Anforderung 1: Automatische Erkennung des System-Themes
+
+**User Story:** Als Besucher möchte ich, dass die Webseite automatisch erkennt, ob mein Betriebssystem auf hell oder dunkel eingestellt ist, damit die Seite sofort zum Erscheinungsbild meines Systems passt.
+
+#### Akzeptanzkriterien
+
+1. WHEN ein Benutzer die Webseite zum ersten Mal besucht und keine gespeicherte Theme_Präferenz vorhanden ist, THE Theme_Provider SHALL das System_Theme über die Media-Query `prefers-color-scheme` ermitteln und das entsprechende Farbschema anwenden.
+2. WHILE das System_Theme auf „dunkel" eingestellt ist und die Theme_Präferenz auf „system" steht, THE Theme_Provider SHALL das Dark_Theme anwenden.
+3. WHILE das System_Theme auf „hell" eingestellt ist und die Theme_Präferenz auf „system" steht, THE Theme_Provider SHALL das Light_Theme anwenden.
+4. WHEN der Benutzer die Betriebssystem-Einstellung von hell auf dunkel oder umgekehrt ändert und die Theme_Präferenz auf „system" steht, THE Theme_Provider SHALL das angezeigte Theme innerhalb von 1 Sekunde aktualisieren, ohne dass die Seite neu geladen werden muss.
+
+### Anforderung 2: Manuelles Umschalten des Themes
+
+**User Story:** Als Besucher möchte ich das Theme manuell zwischen Light Mode, Dark Mode und System-Automatik umschalten können, damit ich unabhängig von meiner Systemeinstellung das bevorzugte Erscheinungsbild wählen kann.
+
+#### Akzeptanzkriterien
+
+1. THE Theme_Toggle SHALL im Header der Webseite sichtbar und erreichbar platziert sein.
+2. WHEN der Benutzer den Theme_Toggle betätigt, THE Theme_Toggle SHALL die drei Optionen „Light", „Dark" und „System" zur Auswahl anbieten.
+3. WHEN der Benutzer die Option „Light" auswählt, THE Theme_Provider SHALL das Light_Theme sofort anwenden.
+4. WHEN der Benutzer die Option „Dark" auswählt, THE Theme_Provider SHALL das Dark_Theme sofort anwenden.
+5. WHEN der Benutzer die Option „System" auswählt, THE Theme_Provider SHALL das Theme gemäß dem aktuellen System_Theme anwenden.
+6. THE Theme_Toggle SHALL ein Icon anzeigen, das den aktuellen Theme-Zustand visuell darstellt (Sonne für Light, Mond für Dark, Monitor für System).
+
+### Anforderung 3: Persistenz der Theme-Auswahl
+
+**User Story:** Als wiederkehrender Besucher möchte ich, dass meine Theme-Auswahl gespeichert wird, damit ich beim nächsten Besuch nicht erneut umschalten muss.
+
+#### Akzeptanzkriterien
+
+1. WHEN der Benutzer eine Theme_Präferenz über den Theme_Toggle auswählt, THE Theme_Provider SHALL die Auswahl im localStorage des Browsers speichern.
+2. WHEN der Benutzer die Webseite erneut besucht und eine gespeicherte Theme_Präferenz vorhanden ist, THE Theme_Provider SHALL die gespeicherte Präferenz anwenden.
+3. IF der localStorage nicht verfügbar oder blockiert ist, THEN THE Theme_Provider SHALL auf die System_Theme-Erkennung zurückfallen und ohne Fehler weiterarbeiten.
+
+### Anforderung 4: Definition des Light Themes
+
+**User Story:** Als Besucher möchte ich ein visuell ansprechendes helles Farbschema sehen, das zum bestehenden Design der Webseite passt.
+
+#### Akzeptanzkriterien
+
+1. THE Light_Theme SHALL CSS-Custom-Properties für alle bestehenden Design-Token definieren (background, foreground, card, primary, secondary, muted, accent, border, input, ring, destructive, popover, sidebar, chart-1 bis chart-5).
+2. THE Light_Theme SHALL helle Hintergrundfarben und dunkle Textfarben verwenden, die einen WCAG-AA-konformen Kontrast aufweisen.
+3. THE Light_Theme SHALL die bestehenden Komponentenstile (glass-nav, card-minimal, text-gradient, btn-minimal, btn-outline, project-card) visuell korrekt darstellen.
+4. WHEN das Light_Theme aktiv ist, THE Theme_Provider SHALL die CSS-Klasse vom `<html>`-Element so setzen, dass Tailwind-Utility-Klassen mit `dark:`-Präfix korrekt reagieren.
+
+### Anforderung 5: Vermeidung von Theme-Flackern beim Laden
+
+**User Story:** Als Besucher möchte ich beim Laden der Seite kein kurzes Aufblitzen des falschen Themes sehen, damit das Erlebnis professionell wirkt.
+
+#### Akzeptanzkriterien
+
+1. THE Theme_Provider SHALL ein Inline-Script im `<head>` des HTML-Dokuments verwenden, das die gespeicherte Theme_Präferenz oder das System_Theme ausliest und die entsprechende CSS-Klasse auf das `<html>`-Element setzt, bevor der Seiteninhalt gerendert wird.
+2. WHEN die Seite geladen wird, THE Theme_Provider SHALL das korrekte Theme ohne sichtbares Flackern oder Farbwechsel anzeigen.
+
+### Anforderung 6: Barrierefreiheit des Theme-Toggles
+
+**User Story:** Als Besucher mit Einschränkungen möchte ich den Theme-Toggle per Tastatur und Screenreader bedienen können.
+
+#### Akzeptanzkriterien
+
+1. THE Theme_Toggle SHALL per Tastatur fokussierbar und bedienbar sein (Tab-Navigation und Enter/Space zum Aktivieren).
+2. THE Theme_Toggle SHALL ein `aria-label`-Attribut besitzen, das den aktuellen Zustand und die Funktion beschreibt (z. B. „Theme wechseln, aktuell: Dunkel").
+3. WHEN der Benutzer das Theme über den Theme_Toggle wechselt, THE Theme_Toggle SHALL den neuen Zustand über ein `aria-live`-Attribut oder eine gleichwertige Methode an Screenreader kommunizieren.