red-proto 0.4.0

package/design-system/components/card.md

@@ -0,0 +1,77 @@
+# Card
+
+## Beschreibung
+Container für zusammengehörige Inhalte. Cards gruppieren verwandte Informationen und Aktionen zu einer logischen Einheit. Sie können statisch (reine Anzeige) oder interaktiv (klickbar, z.B. zu Detailansicht) sein.
+
+## Varianten
+
+| Variante      | Verwendung                                                       |
+|---------------|------------------------------------------------------------------|
+| `default`     | Statische Inhalts-Card (kein Hover-Effekt)                      |
+| `interactive` | Klickbare Card (gesamte Card ist Klickziel) mit Hover-Effekt    |
+| `compact`     | Reduziertes Padding, für Listen mit vielen Cards                |
+| `flat`        | Kein Schatten, nur Border – für Inhalte auf farbigem Hintergrund |
+| `highlight`   | Mit farbiger Leiste oder farbigem Hintergrund-Tint (Betonung)   |
+
+## Aufbau (Reihenfolge im DOM)
+
+```
+[Card-Wrapper]
+  [Card-Header]          ← Optional: Titel + Subtitle + Header-Aktion
+    [Card-Media]         ← Optional: Bild/Icon-Bereich oben
+  [Card-Body]            ← Pflicht: Hauptinhalt
+  [Card-Footer]          ← Optional: Aktionen (Buttons, Links)
+```
+
+## Zustände (nur bei Variant: interactive)
+
+| Zustand  | Verhalten                                                        |
+|----------|------------------------------------------------------------------|
+| `default`| Ruhezustand                                                      |
+| `hover`  | Leicht erhöhter Schatten, leichter Hintergrund-Tint              |
+| `focus`  | Sichtbarer Focus-Ring (Keyboard-Navigation)                      |
+| `active` | Leichter Scale-Down (0.99) oder verstärkter Schatten             |
+
+## Visuelle Specs – Default
+
+| Eigenschaft    | Wert                        |
+|----------------|-----------------------------|
+| Hintergrund    | `color-bg-surface`          |
+| Border         | `1px color-border-default`  |
+| Border-Radius  | `radius-lg`                 |
+| Schatten       | `shadow-card`               |
+| Padding Body   | `spacing-6`                 |
+| Padding Compact| `spacing-4`                 |
+
+## Visuelle Specs – Interactive (zusätzlich)
+
+| Eigenschaft       | Hover                        |
+|-------------------|------------------------------|
+| Schatten          | `shadow-lg`                  |
+| Hintergrund       | leichter `color-primary-50`  |
+| Transition        | `transition-shadow`          |
+
+## Card-Header
+
+- Titel: `style-h3` oder `style-h4` je nach Kontext
+- Subtitle: `style-body-sm`, Farbe `color-text-secondary`
+- Header-Aktion: Icon-Button rechts, oder Overflow-Menu
+
+## Card-Footer
+
+- Trennlinie oben: `1px color-border-default`
+- Padding: `spacing-4` `spacing-6`
+- Layout: Flex, Aktionen rechts-ausgerichtet
+- Max. 2 Aktionen – primary + secondary Button
+
+## Regeln
+
+- Interaktive Cards haben genau EINEN Klickbereich (die gesamte Card) – keine verschachtelten Links oder Buttons innerhalb einer klickbaren Card (Ausnahme: Overflow-Menu)
+- Wenn mehrere Aktionen nötig sind → Aktionen im Footer, Card selbst nicht klickbar
+- Bilder in Cards: immer mit alt-Text, feste Höhe (aspect-ratio), object-fit: cover
+
+## Nicht verwenden wenn
+
+- Für einzelne Kennzahlen → Stat-Komponente
+- Für Formular-Felder → Form-Group
+- Für Listen-Einträge mit vielen Zeilen → List-Item

package/design-system/components/input.md

@@ -0,0 +1,81 @@
+# Input / Textfeld
+
+## Beschreibung
+Einzeiliges Texteingabefeld. Verwendet für kurze Freitext-Eingaben: Name, E-Mail, Suche, Passwort, Zahlen.
+
+## Varianten
+
+| Variante    | Verwendung                                           |
+|-------------|------------------------------------------------------|
+| `default`   | Standardmäßiges Textfeld                             |
+| `search`    | Mit Lupe-Icon links, optional Clear-Button rechts   |
+| `password`  | Maskierter Text, Toggle für Sichtbarkeit             |
+| `number`    | Nur numerische Eingabe, optional Stepper-Buttons     |
+
+## Zustände
+
+| Zustand    | Verhalten                                                              |
+|------------|------------------------------------------------------------------------|
+| `default`  | Ruhezustand – Border: `color-border-default`                          |
+| `focus`    | Border: `color-border-focus` (2px), kein Box-Shadow                   |
+| `filled`   | Hat Inhalt – kein visueller Unterschied außer Content                  |
+| `error`    | Border: `color-error-500`, Fehlermeldung darunter, Error-Icon          |
+| `success`  | Border: `color-success-500`, Checkmark-Icon (optional)                |
+| `disabled` | Opacity 0.5, Background: `color-bg-muted`, kein Cursor                |
+| `readonly` | Kein Fokus möglich, Background: `color-bg-muted`, Cursor: `default`   |
+
+## Aufbau (Reihenfolge im DOM)
+
+```
+[Label]              ← <label> mit for-Attribut (PFLICHT, kein Placeholder-Ersatz)
+[Helper-Text]        ← Optional, kurze Erklärung vor dem Input
+[Input-Wrapper]
+  [Prefix-Icon]      ← Optional
+  [<input>]
+  [Suffix-Icon/Action] ← Optional (Clear, Toggle, Unit)
+[Error-Message]      ← Nur bei Fehler, mit role="alert" oder aria-live
+```
+
+## Größen
+
+| Größe | Padding (h/v)               | Font-Size    | Height |
+|-------|------------------------------|--------------|--------|
+| `sm`  | `spacing-2` / `spacing-3`   | `text-sm`    | 32px   |
+| `md`  | `spacing-3` / `spacing-4`   | `text-base`  | 40px   |
+| `lg`  | `spacing-4` / `spacing-4`   | `text-base`  | 48px   |
+
+## Visuelle Specs
+
+| Eigenschaft    | Default                    | Focus                     | Error                    |
+|----------------|----------------------------|---------------------------|--------------------------|
+| Hintergrund    | `color-neutral-0`          | `color-neutral-0`         | `color-error-100`        |
+| Border         | `1px color-border-default` | `2px color-border-focus`  | `1px color-error-500`    |
+| Border-Radius  | `radius-default`           | `radius-default`          | `radius-default`         |
+| Text           | `color-text-primary`       | `color-text-primary`      | `color-text-primary`     |
+| Placeholder    | `color-text-disabled`      | `color-text-disabled`     | `color-text-disabled`    |
+
+## Label-Regeln
+
+- Label ist immer sichtbar – kein Placeholder als Label-Ersatz
+- Pflichtfelder: Sternchen (*) im Label + aria-required="true" auf Input
+- Pflichtfeld-Hinweis am Anfang des Formulars: "* Pflichtfeld"
+
+## Fehlermeldungen
+
+- Inline direkt unter dem Input, nicht in Alerts oder Toasts
+- Text: `color-error-700`, `text-sm`
+- Kurz und präzise: "Bitte gültige E-Mail-Adresse eingeben" – nicht "Fehler"
+- ID verknüpft mit Input via `aria-describedby`
+
+## Regeln
+
+- Labels sind immer vergeben – niemals nur Placeholder
+- Fehlermeldungen sind inline, nicht in Toasts
+- Jeder Input hat ein name-Attribut
+- Autocomplete-Attribute setzen (email, name, tel etc.)
+
+## Nicht verwenden wenn
+
+- Längerer Freitext → Textarea
+- Auswahl aus Optionen → Select oder Radio/Checkbox
+- Datumsauswahl → DatePicker

package/design-system/patterns/data-display.md

@@ -0,0 +1,132 @@
+# Pattern: Datenanzeige
+
+## Tabellen
+
+### Verwendung
+
+Für strukturierte, vergleichbare Daten mit mehreren Attributen pro Zeile. Nicht für einfache Listen oder Einzel-Werte.
+
+### Aufbau
+
+```
+[Table-Toolbar]         ← Optional: Suche, Filter, Bulk-Aktionen, Spalten-Konfiguration
+[Table-Header]          ← Sticky bei langen Tabellen; sortierbare Spalten mit Icon
+[Table-Body]
+  [Table-Row]           ← Hover-Highlight; selektierbar (Checkbox links)
+    [Table-Cell]
+[Table-Footer]          ← Pagination oder "Alle X Einträge laden"
+```
+
+### Regeln
+
+- Spalten-Header: `style-label`, `color-text-secondary`, sortierbar mit Up/Down-Icon
+- Zahlen: rechtsbündig, gleiche Dezimalstellen pro Spalte
+- Text: linksbündig
+- Status/Badges: zentriert (optional)
+- Leerer Zustand: Empty-State Pattern (nicht einfach leere Tabelle)
+- Mobile: Horizontales Scrollen oder Card-Ansicht als Alternative
+- Max. 6–8 Spalten sichtbar – mehr → Spalten ausblendbar
+
+### Zeilenaktionen
+
+- Hover-Aktionen: erscheinen rechts in der Zeile beim Hover (Edit, Delete)
+- Overflow-Menu: bei mehr als 2 Aktionen
+- Bulk-Aktionen: erscheinen in Toolbar wenn Zeilen selektiert
+
+---
+
+## Listen
+
+### Einfache Liste
+
+Für Elemente mit wenigen Attributen, keine komplexe Sortierung nötig.
+
+```
+[List-Item]
+  [Leading: Icon/Avatar/Thumbnail]   ← Optional
+  [Content]
+    [Primary Text]                   ← style-body, color-text-primary
+    [Secondary Text]                 ← style-body-sm, color-text-secondary
+  [Trailing: Action/Meta/Badge]      ← Optional
+```
+
+Trennlinien: `1px color-border-default` zwischen Items (nicht unter letztem Item).
+
+### Geordnete Liste / Rankings
+
+- Nummerierung: konsistent ausgerichtet (rechtsbündig, gleiche Breite)
+- Hervorhebung: Top 3 mit Badge oder Icon
+
+---
+
+## Badges / Tags
+
+### Verwendung
+
+Kurze Status-Informationen, Kategorisierungen, Zähler.
+
+### Varianten
+
+| Variante    | Verwendung                              | Farbe                      |
+|-------------|------------------------------------------|-----------------------------|
+| `success`   | Aktiv, Abgeschlossen, Online            | `color-success-*`           |
+| `warning`   | Ausstehend, In Review, Achtung          | `color-warning-*`           |
+| `error`     | Fehler, Abgelehnt, Kritisch             | `color-error-*`             |
+| `info`      | Neu, Beta, Hinweis                      | `color-primary-*`           |
+| `neutral`   | Archiviert, Inaktiv, Standard           | `color-neutral-*`           |
+
+### Regeln
+
+- Maximale Zeichenzahl: 20–25 Zeichen – mehr → Tooltip mit Volltext
+- Nicht klickbar (wenn klickbar → Filter-Tag / Chip)
+- Dot-Badge: Nur Farbe als Status-Indikator (immer mit sichtbarem Text-Label für Accessibility)
+- Zähler-Badge: Auf Icons/Avatare für ungelesene Nachrichten etc.
+
+---
+
+## Statistik / Kennzahlen (Stat Cards)
+
+### Aufbau
+
+```
+[Label / Beschreibung]    ← style-body-sm, color-text-secondary
+[Hauptwert]               ← text-3xl oder text-4xl, font-weight-bold
+[Vergleichswert / Trend]  ← Optional: +12% (grün) oder -3% (rot) + Icon
+```
+
+### Regeln
+
+- Trend-Indikatoren: Farbe PLUS Icon (nicht nur Farbe)
+- Einheiten klar kennzeichnen: €, %, Stk., ms
+- Sehr große Zahlen formatieren: 1.234.567 oder 1,2M
+- Loading: Skeleton über dem gesamten Stat-Block
+
+---
+
+## Avatar / Nutzerbilder
+
+### Varianten
+
+| Variante   | Inhalt                                          |
+|------------|-------------------------------------------------|
+| Bild       | Nutzerfoto (immer mit Fallback)                 |
+| Initials   | Fallback: Initialen auf Farbhintergrund         |
+| Icon       | Generisches User-Icon (wenn kein Name verfügbar)|
+
+### Größen
+
+| Größe | Durchmesser | Verwendung                         |
+|-------|-------------|------------------------------------|
+| `xs`  | 24px        | In Tabellenzellen, kompakte Listen |
+| `sm`  | 32px        | Kommentar-Avatare, Chips           |
+| `md`  | 40px        | Standard Avatar                    |
+| `lg`  | 48px        | Profil-Header                      |
+| `xl`  | 64px        | Profilseite, Detailansicht         |
+| `2xl` | 96px        | Große Profilseite                  |
+
+### Regeln
+
+- Border-Radius: `radius-full` (rund)
+- Fallback-Initials: 1–2 Buchstaben, konsistente Farb-Zuweisung (z.B. Hash des Namens)
+- Bild: `alt`-Attribut = Nutzername
+- Avatar-Group (mehrere): überlappend, max. 4 + "+N" Anzeige

package/design-system/patterns/feedback.md

@@ -0,0 +1,148 @@
+# Pattern: Feedback & Status-Kommunikation
+
+## Überblick
+
+| Pattern       | Wann einsetzen                                     | Persistent? | Unterbrechend? |
+|---------------|----------------------------------------------------|-------------|----------------|
+| Toast/Snackbar| Kurze Bestätigung, nicht kritisch                 | Nein (3–5s) | Nein           |
+| Alert-Banner  | Wichtige Info auf Page-Ebene, kein sofortiges Handeln | Ja (manuell) | Nein        |
+| Modal         | Bestätigung nötig, kritische Entscheidung          | Ja          | Ja             |
+| Inline-Error  | Formularfehler, kontextbezogene Fehler             | Ja          | Nein           |
+| Empty State   | Kein Inhalt vorhanden (noch nicht oder nach Filter)| Ja          | Nein           |
+| Skeleton      | Inhalt lädt, Struktur bekannt                      | Nein        | Nein           |
+| Spinner       | Kurze unbekannte Ladedauer                         | Nein        | Optional       |
+
+---
+
+## Toast / Snackbar
+
+### Verwendung
+
+Nach erfolgreichen Aktionen (Speichern, Löschen, Versenden) die keine weitere Bestätigung brauchen.
+
+### Aufbau
+
+```
+[Icon]  [Message]  [Action (optional)]  [Close]
+```
+
+### Regeln
+
+- Position: Unten rechts (Desktop), unten zentriert (Mobile)
+- Autohide: 4–5 Sekunden bei Info/Success, Fehler-Toasts manuell schließen
+- Max. 3 gleichzeitig sichtbar – ältere schieben nach oben
+- Varianten: `success`, `error`, `warning`, `info`
+- Klickbare Aktion: max. 1 (z.B. "Rückgängig"), kurzer Text
+
+### Hintergrundfarben
+
+| Variante  | Hintergrund         | Icon-Farbe          |
+|-----------|---------------------|---------------------|
+| success   | `color-neutral-900` | `color-success-500` |
+| error     | `color-error-700`   | `color-neutral-0`   |
+| warning   | `color-warning-500` | `color-neutral-900` |
+| info      | `color-neutral-900` | `color-primary-300` |
+
+---
+
+## Alert-Banner
+
+### Verwendung
+
+Für wichtige Informationen auf Seiten-Ebene: Systemwarnungen, Hinweise die für alle Nutzer relevant sind, Bestätigungen nach Redirect.
+
+### Aufbau
+
+```
+[Icon]  [Titel (optional)]  [Beschreibung]  [Aktion (optional)]  [Close (optional)]
+```
+
+### Regeln
+
+- Oben auf der Seite, direkt unter dem Header
+- Nicht zu viele gleichzeitig – max. 1 kritisches + 1 informationales Banner
+- Varianten: `success`, `error`, `warning`, `info`
+- Schließbar (X-Button) außer bei kritischen Systemmeldungen
+
+---
+
+## Modal / Dialog
+
+### Verwendung
+
+- Bestätigungen für irreversible Aktionen (Löschen, Publishen)
+- Komplexere Formulare die aus dem Kontext herausgelöst werden müssen
+- Lightboxes / Medien-Ansichten
+
+### Regeln
+
+- Fokus: wird beim Öffnen in das Modal gesetzt (erstes interaktives Element)
+- Focus-Trap: Tab navigiert nur innerhalb des Modals
+- Schließen: ESC-Taste, X-Button, optional Klick außerhalb (nicht bei kritischen Modals)
+- Beim Schließen: Fokus kehrt zum auslösenden Element zurück
+- Backdrop: semi-transparentes Overlay (`rgba(0,0,0,0.5)`)
+- Max-Breite: 480px (small), 640px (default), 800px (large)
+- Mobile: Drawer von unten (full width, 90vh max)
+
+### Bestätigungs-Modals (Danger)
+
+```
+[Titel: "X löschen?"]
+[Erklärung: "Dies kann nicht rückgängig gemacht werden."]
+[Abbrechen]  [Löschen]
+  Secondary    Danger
+```
+
+---
+
+## Empty State
+
+### Verwendung
+
+Wenn ein Listenbereich / Tabelle / Dashboard-Widget keine Inhalte hat – entweder weil noch nichts erstellt wurde oder der aktuelle Filter keine Treffer liefert.
+
+### Aufbau
+
+```
+[Illustration oder Icon]
+[Titel: "Noch keine [Objekte]"]
+[Beschreibung: Was der Nutzer tun kann]
+[Primäraktion: z.B. "Ersten X erstellen"]
+```
+
+### Regeln
+
+- Immer eine mögliche Nächste-Aktion anbieten (wenn möglich)
+- Bei leerem Filter: "Filter zurücksetzen" als Aktion
+- Icon/Illustration: passend zum Kontext, nicht generisch
+- Kein "Keine Daten gefunden" – erkläre WAS fehlt und WAS der User tun kann
+
+---
+
+## Skeleton Loader
+
+### Verwendung
+
+Wenn die Struktur des Inhalts bekannt ist und das Laden länger als 300ms dauert.
+
+### Regeln
+
+- Zeigt die Form des zukünftigen Inhalts als graue Platzhalter-Blöcke
+- Animierter Shimmer-Effekt (gradient sweep) – aber `prefers-reduced-motion` beachten
+- Für Text: Blöcke in variierender Breite (nicht alle gleich lang)
+- Für Cards: Card-Umriss mit Platzhaltern für Bild, Titel, Text
+- Kein Skeleton länger als 10 Sekunden – danach Error State
+
+---
+
+## Ladezustand (Spinner / Progress)
+
+| Typ             | Wann                                              |
+|-----------------|---------------------------------------------------|
+| Inline Spinner  | Button-Loading, kurze In-Component Aktionen       |
+| Page Spinner    | Seitenübergreifende Ladeoperationen (selten)      |
+| Progress Bar    | Upload, Prozesse mit bekannter Dauer              |
+| Skeleton        | Inhalt lädt, Struktur bekannt                     |
+
+- Page Spinner: Overlay mit Backdrop, zentrierter Spinner – NUR wenn wirklich nötig
+- Spinner-Größen: 16px (inline), 24px (component), 40px (page-level)

package/design-system/patterns/forms.md

@@ -0,0 +1,90 @@
+# Pattern: Formulare
+
+## Grundprinzipien
+
+- Ein Formular = eine Aufgabe (kein Mega-Form mit allem auf einmal)
+- Labels immer sichtbar – kein Placeholder als Label-Ersatz
+- Fehler inline, direkt bei dem Feld das betroffen ist
+- Primäraktion am Ende, Abbrechen links davon (oder als Ghost-Button)
+
+## Formular-Aufbau
+
+```
+[Form-Header]              ← Optional: Titel + Kurzbeschreibung was der User tun wird
+[Pflichtfeld-Hinweis]      ← "* Pflichtfeld" – einmalig, oben
+[Field-Groups]             ← Zusammengehörige Felder gruppiert (optional mit Überschrift)
+  [Form-Field]
+    [Label] *              ← <label> mit for-Attribut
+    [Helper-Text]          ← Optional, kurze Erklärung (max. 1 Satz)
+    [Input-Komponente]
+    [Error-Message]        ← Nur bei Fehler, aria-live="polite"
+[Form-Actions]             ← Primär-Button + Abbrechen/Zurück
+```
+
+## Feldbreiten
+
+| Typ              | Breite                   | Beispiel                          |
+|------------------|--------------------------|-----------------------------------|
+| Voller Block     | 100%                     | Nachricht, Notizen, lange Felder  |
+| Halbe Breite     | ~50%                     | Vorname + Nachname nebeneinander  |
+| Drittel / Viertel| ~33% / ~25%              | PLZ, Hausnummer                   |
+| Auto             | Passt sich Inhalt an     | Kurze Codes, Einheiten            |
+
+Auf Mobile: immer 100% Breite.
+
+## Validierung
+
+### Wann validieren?
+
+| Zeitpunkt       | Empfehlung                                                      |
+|-----------------|-----------------------------------------------------------------|
+| On Submit       | Immer – zeigt alle Fehler auf einmal nach dem Absenden         |
+| On Blur         | Für Format-Validierung (E-Mail, Datum) – nicht für Pflichtfelder|
+| On Input        | Nur für Passwort-Stärke oder Zeichenzähler – nicht für Fehler  |
+
+### Fehlermeldungen
+
+- Spezifisch: "Bitte gültige E-Mail-Adresse eingeben (z.B. name@firma.de)"
+- Nicht: "Ungültige Eingabe" oder "Fehler"
+- Auf Submit: Fokus auf erstes Fehler-Feld springen (scroll + focus)
+- Globale Fehler (Server-Fehler): Alert-Banner über dem Formular
+
+## Mehrstufige Formulare (Wizard)
+
+- Fortschrittsanzeige: Step-Indicator oben (1 von 3, 2 von 3 ...)
+- Jeder Step: eigene Validierung vor dem Weiter-Klick
+- Navigation: Zurück-Button behält Eingaben aus vorherigen Steps
+- Letzter Step: Zusammenfassung vor dem finalen Absenden (optional)
+
+## Spezielle Felder
+
+### Passwort-Felder
+
+- Immer Toggle für Sichtbarkeit (Eye-Icon rechts im Feld)
+- Anforderungen: sichtbar als Checkliste (nicht erst nach Fehler)
+- Stärken-Indikator: Progressbar, nicht nur Text
+
+### File Upload
+
+- Drag & Drop + Klick-Alternative
+- Erlaubte Dateitypen und Maximalgröße anzeigen (nicht erst als Fehler)
+- Hochgeladene Dateien: Dateiname + Lösch-Button sichtbar
+- Fortschrittsbalken bei größeren Uploads
+
+### Datum / Uhrzeit
+
+- DatePicker-Komponente, kein manuelles Texteingabe-Datum-Format
+- Wenn Range: Start + Ende visuell als zusammengehörig kennzeichnen
+- Vergangene/gesperrte Daten: im Picker disabled, nicht nur als Validierungsfehler
+
+## Formular-Aktionen
+
+```
+[Abbrechen/Zurück]    [Primäraktion]
+    Ghost-Button           Primary-Button
+```
+
+- Abbrechen links, Primäraktion rechts (westliche Konvention)
+- Abbrechen: fragt nach ungespeicherten Änderungen (Dialog) – wenn Daten verloren gehen
+- Primär-Button: Loading-Zustand beim Absenden, kein Doppelklick möglich
+- Destruktive Aktionen (Löschen, Unwiderrufliches): Danger-Button + Bestätigungsdialog

package/design-system/patterns/navigation.md

@@ -0,0 +1,100 @@
+# Pattern: Navigation
+
+## Globale Navigation (Header / Top-Nav)
+
+### Aufbau
+
+```
+[Header-Wrapper]                ← sticky, z-index über Content
+  [Logo / Brand]                ← Links, immer sichtbar, klickbar = Home
+  [Primary Nav]                 ← Horizontale Links (Desktop) oder Hamburger (Mobile)
+  [Secondary Actions]           ← Suche, Notifications, User-Avatar/Menu
+```
+
+### Regeln
+
+- Aktiver Navigationspunkt: `color-primary-500` Unterstrich oder Hintergrund-Tint
+- Max. 5–7 Hauptnavigationspunkte – mehr → Mega-Menu oder Sidebar
+- Mobile: Hamburger-Icon (3 Linien), öffnet Drawer von links oder oben
+- Skip-Navigation-Link: erster Element im DOM (für Keyboard/Screen Reader)
+- Sticky Header: `shadow-sticky` beim Scrollen aktivieren
+
+### Aktiver Zustand
+
+| Element         | Visual                                          |
+|-----------------|-------------------------------------------------|
+| Link            | `color-primary-600` + Unterstrichen oder Tint   |
+| Icon-Tab        | Gefülltes Icon + `color-primary-500` Label      |
+| Sidebar-Item    | `color-bg-muted` Hintergrund + `color-primary-600` Text |
+
+---
+
+## Sidebar-Navigation
+
+### Verwendung
+
+Für Anwendungen mit vielen Bereichen oder komplexer Hierarchie.
+
+### Aufbau
+
+```
+[Sidebar-Wrapper]               ← Feste Breite: 240–280px; collapsible auf 64px
+  [App Logo / Name]
+  [Navigation Groups]
+    [Group Label]               ← Optional, Uppercase, text-xs, color-text-secondary
+    [Nav-Item]                  ← Icon + Label, aktiver Zustand
+    [Nav-Item (mit Sub-Items)]  ← Aufklappbar (Accordion)
+  [Bottom-Section]              ← Settings, Logout, User-Info
+```
+
+### Regeln
+
+- Collapsible: Im Collapsed-Zustand nur Icons mit Tooltip
+- Sub-Navigation: Max. 1 Ebene Tiefe in der Sidebar
+- Scrollbar: Nur wenn mehr Items als sichtbare Höhe (overflow-y: auto)
+
+---
+
+## Breadcrumb
+
+### Verwendung
+
+Bei tiefen Hierarchien (ab 3 Ebenen). Nicht für flache Navigation.
+
+### Aufbau
+
+```
+[Home] / [Kategorie] / [Aktuelle Seite]
+```
+
+### Regeln
+
+- Trennzeichen: `/` oder `›` – konsistent
+- Aktuelle Seite: Nicht klickbar, `color-text-secondary`
+- Eltern-Seiten: Klickbar, `color-primary-600`
+- Mobil: Nur 1–2 Levels anzeigen + "..." für ausgeblendete
+
+---
+
+## Tab-Navigation
+
+### Verwendung
+
+Für die Navigation zwischen gleichwertigen Content-Bereichen innerhalb einer Seite oder eines Panels.
+
+### Regeln
+
+- Max. 5–6 Tabs sichtbar – bei mehr: scrollbar oder Overflow-Dropdown
+- Aktiver Tab: Unterstrich (`color-primary-500`, 2px) + `color-primary-600` Text
+- Tab-Panel: `role="tabpanel"`, Tab: `role="tab"`, Wrapper: `role="tablist"`
+- Keyboard: Pfeiltasten wechseln zwischen Tabs, Enter/Space aktiviert
+
+---
+
+## Back-Navigation
+
+### Regeln
+
+- "<- Zurück" nur wenn nicht aus der Hauptnavigation erreichbar
+- Immer expliziter Linktext, nicht nur ein Zurück-Pfeil (Screen Reader!)
+- Navigiert zur vorherigen Seite (nicht Browser-Back, da ggf. abweichender State)

package/design-system/screens/README.md

@@ -0,0 +1,45 @@
+# Screen-Referenzen
+
+Hier kommen Figma-Exports oder Screenshots deines Design Systems als visuelle Referenz für die Agents.
+
+## Ordner-Struktur
+
+Lege Screens nach User-Flows / Bereichen in Unterordnern ab:
+
+```
+screens/
+  onboarding/
+    01-landing.png
+    02-registration.png
+    03-email-verification.png
+  dashboard/
+    01-overview.png
+    02-empty-state.png
+  [feature-name]/
+    01-list.png
+    02-detail.png
+    03-create-form.png
+```
+
+## Benennungs-Konvention
+
+- Numerisches Präfix für die Reihenfolge: `01-`, `02-` ...
+- Beschreibender Name: was ist auf dem Screen zu sehen?
+- Kein CamelCase, kein Leerzeichen: `kebab-case.png`
+
+## Dateiformat
+
+- **PNG bevorzugt** – verlustfreie Qualität für UI-Details
+- **JPG** – akzeptabel für bildlastige Screens
+- Mindestauflösung: 1440px Breite für Desktop-Screens
+- Mobile-Screens: 375px oder 390px Breite
+
+## Was die Agents damit machen
+
+- `/red:proto-ux` liest die Screens als visuelle Referenz für User Flows und Komponentenstruktur
+- `frontend-developer` nutzt Screens als Implementierungs-Referenz
+- `ux-reviewer` vergleicht implementierte Screens mit den Referenz-Screens
+
+## Hinweis
+
+Screens sind **Referenz**, kein Pixel-Perfect-Vorgabe. Die Agents sollen die Struktur, Hierarchie und das Layout verstehen – nicht jeden Pixel nachbauen. Abweichungen in der technischen Umsetzung sind okay, solange sie dem Design-Prinzip folgen.