Kumasy-Marketing/DESIGN-SYSTEM.md

# Kumasy Design System — Glassmorphism

Dieses Dokument beschreibt den visuellen Stil der bestehenden App (`app.kumasy.de`), damit die neue Marketing-Seite (separates Next.js-Projekt) optisch als **eine Marke** erkennbar bleibt. Fokus: der durchsichtige "Glass"-Effekt, nicht die Farbpalette (die ist aktuell größtenteils neutral/grau und wird sich für Marketing ohnehin ändern).

Quelle der Wahrheit: [`src/app/globals.css`](src/app/globals.css) + tatsächlich verwendete Utility-Klassen in den Komponenten (siehe Beispiele unten). Es gibt **keine zentrale `.glass`-Klasse** — der Effekt wird pro Komponente aus denselben 3–4 Tailwind-Utilities zusammengesetzt.

## Das Grundrezept 

Jede "Glass"-Fläche besteht immer aus derselben Kombination von vier Zutaten:

1. **Halbtransparenter Hintergrund** — `bg-white/XX` (Opacity meist zwischen 45–65%)
2. **Weichzeichner dahinter** — `backdrop-blur-{sm|xl|2xl}`
3. **Helle, dünne Kontur** — `border border-white/XX` (simuliert eine Lichtkante am Glasrand)
4. **Weicher Schatten** statt harter Trennlinie — `shadow-sm` / `shadow-2xl` / ein custom `shadow-[...]`

Kein Layer nutzt schwere Farbverläufe oder Sättigung im Glas selbst — die Tiefe kommt aus Blur + Transparenz + Schatten, nicht aus Farbe.

## Belegte Beispiele aus dem Code

| Ort | Klassen | Wirkung |
|---|---|---|
| Dashboard-Sidebar — [`DashboardSidebar.tsx:118`](src/modules/dashboard/ui/components/DashboardSidebar.tsx:118) | `bg-white/55 backdrop-blur-xl supports-backdrop-filter:bg-white/45 shadow-[1px_0_0_0_oklch(0.85_0_0/30%)]` | Schwebende Sidebar, Content dahinter schimmert durch; Schatten ersetzt eine harte Randlinie |
| Dashboard-Stat-Kacheln — [`DashboardStatsGrid.tsx:58`](src/modules/dashboard/ui/components/DashboardStatsGrid.tsx:58) | `border border-white/60 bg-white/60 backdrop-blur-xl rounded-2xl shadow-sm` | Freistehende KPI-Karten auf farbigem/strukturiertem Hintergrund |
| Auth-Formular-Panel — [`AuthSidebarComponent.tsx:40`](src/modules/auth/ui/components/AuthSidebarComponent.tsx:40) | `border border-white/15 bg-blue/60 backdrop-blur-2xl shadow-2xl` | Stärkster Blur (2xl) + dunklere Glasfarbe (`--color-blue: #1e293b`) für Login/Register — dunkles, "Frosted-Glass"-Panel vor animiertem Gradient-Hintergrund |
| Modal-Overlay — [`dialog.tsx:41`](src/components/ui/dialog.tsx:41) | `bg-black/50` (kein Blur) | Abdunklung hinter Dialogen — bewusst *kein* Blur, damit der Dialog-Inhalt scharf bleibt |
| Public Business-Page Header — [`business-public-view.tsx:169`](src/modules/courses/ui/views/business-public-view.tsx:169) | `border-b border-gray-200 backdrop-blur-sm` | Leichter Blur für sticky Header, dezentester Grad der Glas-Familie |

## Intensitäts-Stufen (Blur-Skala)

Der Blur-Grad korreliert mit der visuellen Priorität der Fläche — nicht willkürlich gewählt:

- **`backdrop-blur-sm`** — sticky Header, unaufdringliche UI-Elemente, die kaum auffallen sollen
- **`backdrop-blur-xl`** — Standard für Sidebars, Karten, primäre Content-Flächen
- **`backdrop-blur-2xl`** — Hero-/Auth-Panels, wo maximale "Premium-Glas"-Wirkung gewünscht ist

**Empfehlung für Marketing-Seite:** Hero-Sections und Waitlist-Formular-Karte auf `2xl`, Sticky-Nav auf `sm`–`md`, normale Content-Cards auf `xl`.

## Transparenz-Werte (Opacity-Skala)

- `/15` – `/30` — sehr subtil, meist auf **dunklem** Untergrund (Auth-Panel-Border)
- `/45` – `/60` — Standard für die meisten Flächen (Sidebar, Stat-Cards)
- `/70` und höher — kommt vor, wirkt aber schon fast opak; für Marketing eher vermeiden, sonst geht der Glass-Effekt verloren

Faustregel: **je heller/aktiver der Hintergrund dahinter (Gradient, Bild, Blob-Animation), desto niedriger die Opacity** — sonst verschluckt die Fläche den Effekt, den sie eigentlich zeigen soll.

## Ergänzende Bewegungs-Elemente

Der Glass-Effekt wird im Auth-Bereich mit einem **animierten Hintergrund** kombiniert (siehe [`globals.css:127-178`](src/app/globals.css:127)):

```css
.auth-animated-gradient {
  background: linear-gradient(120deg, oklch(0.97 0 0) 0%, oklch(0.9 0.05 240) 25%, ...);
  background-size: 300% 300%;
  animation: auth-gradient-shift 18s ease-in-out infinite;
}
.auth-gradient-blob { animation: auth-blob-float 16s ease-in-out infinite; }
```

- Ein langsam wandernder Gradient (18s Loop) hinter den Glasflächen — sorgt dafür, dass der Blur überhaupt etwas "zu verwischen" hat.
- Zwei "Blobs" mit versetzter `animation-delay` (`-8s`), die leicht schweben/skalieren — erzeugt organische Bewegung statt eines statischen Verlaufs.
- `prefers-reduced-motion: reduce` deaktiviert beide Animationen komplett — **Accessibility-Pflicht**, für die Marketing-Seite 1:1 übernehmen.

**Für Parallax/Marketing relevant:** Dieses Muster (bewegter Gradient/Blobs im Hintergrund + ruhige Glasflächen im Vordergrund) ist die bestehende Design-Sprache für "besondere" Screens (Auth) und eignet sich direkt als Vorlage für eine Hero-Section mit Parallax-Tiefe.

## Radien & Schatten-Konventionen

- Basis-Radius-Variable: `--radius: 0.625rem` (10px), abgeleitet in `sm` (−4px), `md` (−2px), `lg` (Basis), `xl` (+4px) — siehe [`globals.css:40-43`](src/app/globals.css:40)
- Glasflächen nutzen meist `rounded-2xl` (Stat-Cards) oder die Sidebar-Komponente ihren eigenen Radius
- Schatten sind fast immer `shadow-sm` (dezent, für ruhige Flächen) oder `shadow-2xl` (für hervorgehobene Panels wie Auth) — nie mittlere Stufen, es gibt keinen `shadow-md`/`shadow-lg` im Glass-Kontext

## Was NICHT Teil des Glass-Systems ist

- Der Basis-`Card`-Component ([`card.tsx`](src/components/ui/card.tsx)) ist **opak** (`bg-card`, keine Transparenz) — Glass ist ein bewusst gewähltes Extra pro Screen, keine globale Card-Eigenschaft.
- Modal-Overlays (`dialog.tsx`, `sheet.tsx`) nutzen `bg-black/50` **ohne** Blur — Verdunklung ja, Verwischen nein, damit der eigentliche Dialog-Inhalt scharf bleibt.
- Die aktuelle Farbpalette (neutrale Grautöne via `oklch(... 0 0)`, siehe [`globals.css:49-116`](src/app/globals.css:49)) ist funktional/App-artig gehalten und explizit **nicht** der Teil, der für die Marketing-Seite übernommen werden soll (siehe Auftrag).

## Übertragung auf die Marketing-Seite (Empfehlung)

1. **Basis-Utility statt Copy-Paste:** In der neuen App eine `glass` bzw. `glass-{sm,xl,2xl}`-Klasse (oder CVA-Variante) zentral definieren, die die vier Zutaten (bg-opacity, blur, border, shadow) bündelt — vermeidet die Streuung, die im Hauptprojekt aktuell besteht.
2. **Hero:** animierter Gradient/Blob-Hintergrund (Pattern aus `globals.css` wiederverwenden/weiterentwickeln) + Glass-Card (`2xl`-Blur) für Headline/CTA/Waitlist-Formular davor — erzeugt sofort Wiedererkennung mit der App.
3. **Parallax-Layering:** Glass-Flächen eignen sich gut als "vorderste" Ebene in einem Parallax-Stack, da der Blur zusätzliche Tiefenwahrnehmung erzeugt, wenn sich der Hintergrund beim Scrollen schneller/langsamer bewegt als die Glasfläche selbst.
4. **Reduced-Motion & Performance:** `prefers-reduced-motion`-Guard von Anfang an einbauen; `backdrop-blur` ist GPU-Kosten nicht zu unterschätzen — auf Mobile ggf. auf `blur-sm`/`md` reduzieren.