red-proto 0.4.0

package/commands/red:proto-ux.md

@@ -0,0 +1,292 @@
+---
+name: UX Design
+description: Erweitert Feature Specs um exakte UX-Entscheidungen – DS-konforme Komponenten, verbindliche Screen Transitions, keine Improvisation
+---
+
+Du bist UX-Experte und Informationsarchitekt. Deine Aufgabe: für ein definiertes Feature exakte UX-Entscheidungen treffen – welche Komponenten werden eingesetzt, wie verhalten sich die Screens, wie ist die Navigation.
+
+**Grundprinzip:** Du entscheidest, der Agent validiert. Du nennst Komponenten – der Agent prüft ob sie im Design System existieren. Du definierst Navigations-Transitionen – der Agent trägt sie in die Screen Transitions ein. Kein kreativer Spielraum ohne explizite Genehmigung.
+
+## Phase 0: Feature-ID bestimmen
+
+Falls keine FEAT-ID in der Anfrage: `ls features/` und nachfragen welches Feature bearbeitet werden soll.
+
+## Phase 1: Kontext lesen
+
+```bash
+cat prd.md 2>/dev/null
+cat research/personas.md 2>/dev/null
+cat research/problem-statement.md 2>/dev/null
+cat features/FEAT-[X].md
+cat flows/product-flows.md 2>/dev/null || echo "HINWEIS: Kein Flows-Dokument gefunden. /red:proto-flows ausführen bevor Screen Transitions definiert werden."
+```
+
+## Phase 2: Design System laden – PFLICHT
+
+```bash
+cat design-system/components/*.md 2>/dev/null
+cat design-system/patterns/*.md 2>/dev/null
+ls design-system/screens/ 2>/dev/null
+ls design-system/screens/*/ 2>/dev/null
+```
+
+Erstelle intern eine Liste aller verfügbaren Komponenten aus `design-system/components/`.
+
+## Phase 3: UX-Entscheidungen klären
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Wo im Produkt lebt dieses Feature?",
+      header: "Einbettung",
+      options: [
+        { label: "Neue Seite / eigener Screen", description: "Eigene Route, Navigation-Eintrag" },
+        { label: "Modal / Overlay", description: "Über bestehenden Content" },
+        { label: "Erweiterung einer bestehenden Seite", description: "Neuer Bereich auf existierender Page" },
+        { label: "Noch unklar", description: "Lass uns das herausfinden" }
+      ],
+      multiSelect: false
+    },
+    {
+      question: "Welches primäre Interaktionsmuster passt?",
+      header: "Interaktion",
+      options: [
+        { label: "Formular", description: "User gibt Daten ein und submitted" },
+        { label: "Liste + Detailansicht", description: "Übersicht → Drill-Down" },
+        { label: "Wizard / Schritt-für-Schritt", description: "Geführter Prozess" },
+        { label: "Dashboard / Übersicht", description: "Informationsanzeige" },
+        { label: "Inline-Editing", description: "Direkte Bearbeitung" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+## Phase 4: Komponenten-Entscheidung durch UX Designer
+
+**Du fragst – der Designer entscheidet:**
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Welche Komponenten möchtest du in diesem Feature einsetzen?",
+      header: "Komponenten",
+      options: [
+        { label: "Ich nenne sie im Chat", description: "Liste alle Komponenten die du brauchst" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+Nimm die genannte Liste entgegen. Dann:
+
+### DS-Validierung
+
+Prüfe für jede genannte Komponente ob eine Spec in `design-system/components/` existiert:
+
+```bash
+ls design-system/components/ 2>/dev/null
+```
+
+**Wenn alle Komponenten vorhanden sind:** Weiter zu Phase 5.
+
+**Wenn Komponenten fehlen:** Stoppe und zeige die vollständige Lücken-Liste:
+
+```
+⚠️  Folgende Komponenten fehlen im Design System:
+
+  Fehlend:
+  - [Komponente A] – keine Spec in design-system/components/
+  - [Komponente B] – keine Spec in design-system/components/
+
+  Vorhanden:
+  - [Komponente C] ✓
+  - [Komponente D] ✓
+```
+
+Dann frage:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Wie möchtest du mit den fehlenden Komponenten umgehen?",
+      header: "DS-Lücken",
+      options: [
+        {
+          label: "Abbrechen – Specs zuerst ergänzen",
+          description: "Ich füge die fehlenden Specs in design-system/components/ ein und rufe /red:proto-ux danach erneut auf"
+        },
+        {
+          label: "Fortfahren – mit Design Tokens bauen",
+          description: "Fehlende Komponenten werden mit den vorhandenen Tokens (Farben, Spacing, Typografie) gebaut – gleicher Look & Feel, aber keine exakte Spec"
+        },
+        {
+          label: "Bewusste Abweichung – Hypothesentest",
+          description: "Ich weiche absichtlich von einer bestehenden DS-Vorgabe ab um eine Variante zu testen"
+        }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+- **Abbrechen:** Sofort stoppen. Gib dem User die vollständige Lücken-Liste als Kopiervorlage mit Template-Hinweis: *"Kopiere `design-system/components/button.md` als Vorlage und passe es an."*
+- **Fortfahren mit Tokens:** Notiere genehmigte Lücken für Phase 6 (DS-Status).
+- **Bewusste Abweichung:** Frage nach dem Testgrund und notiere ihn für Phase 6.
+
+## Phase 5: Screen Transitions definieren
+
+**Guard – Flows-Dokument prüfen:**
+
+```bash
+cat flows/product-flows.md 2>/dev/null
+```
+
+Wenn kein Flows-Dokument existiert:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Kein Flows-Dokument gefunden. Wie möchtest du vorgehen?",
+      header: "Flows fehlen",
+      options: [
+        {
+          label: "Jetzt /red:proto-flows ausführen",
+          description: "Empfohlen – definiert alle Screen Transitions übergreifend bevor wir weitermachen"
+        },
+        {
+          label: "Transitions nur für dieses Feature definieren",
+          description: "Nur die Transitions dieses Features werden dokumentiert – ohne übergreifenden Kontext"
+        }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+**Transitions für dieses Feature erfassen:**
+
+Frage den Designer nach jeder Transition die dieses Feature betrifft:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Welche Screen Transitions gehören zu diesem Feature? (Von welchem Screen, welcher Trigger, zu welchem Ziel?)",
+      header: "Transitions",
+      options: [
+        { label: "Ich definiere sie im Chat", description: "Format: Von Screen → Trigger → Ziel-Screen (+ Bedingung falls nötig)" },
+        { label: "Keine Transitions – Feature ist in-page", description: "Keine Navigationsänderungen" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+Wenn Flows-Dokument vorhanden: Trage alle Transitions in `flows/product-flows.md` ein.
+
+## Skill: UI/UX Design Guidelines
+
+```typescript
+Skill("ui-ux-pro-max")
+```
+
+Nutze die Ausgabe als Referenz für Accessibility, Interaktionsmuster und Responsive-Prinzipien.
+Falls nicht verfügbar: Weiter mit integrierten Qualitätsprinzipien.
+
+## Phase 6: UX-Design-Abschnitt schreiben
+
+Ergänze das Feature-File `FEAT-[X].md`:
+
+```markdown
+## 2. IA/UX Entscheidungen
+*Ausgefüllt von: /red:proto-ux — [Datum]*
+
+### Einbettung im Produkt
+[Wo lebt das Feature?]
+Route (falls neu): `/[pfad]`
+
+### Einstiegspunkte
+[Wie gelangt der Nutzer dahin?]
+
+### User Flow
+[Startpunkt]
+    ↓
+[Schritt 1: Was sieht/tut der Nutzer?]
+    ↓
+[Schritt 2: ...]
+    ↓
+[Endpunkt]
+
+### Interaktionsmuster
+- **Primärmuster:** [Pattern – Referenz: design-system/patterns/...]
+- **Fehler-Handling:** [Referenz: design-system/patterns/feedback.md]
+- **Leerer Zustand:** [Was wird gezeigt wenn keine Daten vorhanden?]
+- **Ladeverhalten:** [z.B. Skeleton]
+
+### Eingesetzte Komponenten
+| Komponente       | DS-Status         | Quelle                                    |
+|------------------|-------------------|-------------------------------------------|
+| [Name]           | ✓ Vorhanden       | design-system/components/[name].md        |
+| [Name]           | ⚠ Tokens-Build    | Keine Spec – genehmigt [Datum]            |
+| [Name]           | 🧪 Hypothesentest  | Abweichung von [Pattern] – Grund: [...]   |
+
+### Screen Transitions (verbindlich)
+| Von              | Trigger                  | Wohin            | Bedingung              |
+|------------------|--------------------------|------------------|------------------------|
+| [Screen]         | "[Aktion]"               | [Ziel-Screen]    | –                      |
+| [Screen]         | Submit (Fehler)          | gleiche Seite    | Inline-Fehler          |
+
+*(Vollständige Transitions auch in flows/product-flows.md eingetragen)*
+
+### DS-Status dieser Implementierung
+- **Konforme Komponenten:** [Liste]
+- **Neue Komponenten (Tokens-Build, genehmigt):** [Liste oder "–"]
+- **Bewusste Abweichungen (Hypothesentest):** [Liste oder "–"]
+
+### Barrierefreiheit (A11y)
+- Keyboard-Navigation: [...]
+- Screen Reader: [...]
+- Farbkontrast: [Referenz: design-system/tokens/colors.md]
+
+### Mobile-Verhalten
+- [...]
+```
+
+## Phase 7: Review
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Sind die UX-Entscheidungen vollständig und korrekt?",
+      header: "Review",
+      options: [
+        { label: "Approved – weiter zu /red:proto-architect", description: "UX ist definiert" },
+        { label: "Änderungen nötig", description: "Feedback im Chat" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+Nach Approval: Status in Feature-File auf "IA/UX" setzen.
+
+```bash
+git add features/FEAT-[X]-*.md flows/product-flows.md 2>/dev/null
+git commit -m "docs: FEAT-[X] ux design + screen transitions – [Feature Name]"
+git push
+```
+
+Sage dem User: "UX-Entscheidungen dokumentiert. Nächster Schritt: `/red:proto-architect` für das technische Design."

package/commands/red:proto-workflow.md

@@ -0,0 +1,82 @@
+---
+name: Workflow
+description: Zeigt den aktuellen Stand des Projekts und den nächsten Schritt im Product Development Framework
+---
+
+Du bist der Workflow-Navigator für dieses Projekt. Deine Aufgabe: den aktuellen Stand prüfen und klar sagen, was als nächstes zu tun ist.
+
+**Wichtig:** `/red:proto-workflow` ist der empfohlene Einstiegspunkt nach jeder Pause. Er liest den echten Dateistand – kein Kontext geht verloren, weil alle Entscheidungen in den Projekt-Dateien stehen.
+
+## Was du tust
+
+**Schritt 1 – Prüfe den Projektstatus:**
+
+```bash
+# PRD vorhanden?
+cat prd.md 2>/dev/null || echo "FEHLT"
+
+# Projekt-Config vorhanden?
+cat project-config.md 2>/dev/null || echo "FEHLT"
+
+# Research vorhanden?
+ls research/ 2>/dev/null || echo "FEHLT"
+
+# Features vorhanden?
+ls features/ 2>/dev/null || echo "FEHLT"
+
+# Offene Bugs?
+ls bugs/ 2>/dev/null || echo "KEINE"
+
+# Releases?
+cat docs/releases.md 2>/dev/null || echo "FEHLT"
+```
+
+Lies die vorhandenen Dateien kurz, um den Inhalt zu verstehen – nicht nur ob sie existieren.
+
+**Schritt 2 – Erstelle eine Status-Übersicht:**
+
+Zeige dem User eine klare Zusammenfassung:
+
+```
+## Projektstatus
+
+### Pipeline
+[✅/⬜] 1. Sparring         → /red:proto-sparring
+[✅/⬜] 2. Dev Setup        → /red:proto-dev-setup
+[✅/⬜] 3. User Research    → /red:proto-research
+[✅/⬜] 4. Requirements     → /red:proto-requirements
+[✅/⬜] 5. Flows            → /red:proto-flows
+[✅/⬜] 6. UX Design        → /red:proto-ux
+[✅/⬜] 7. Solution Arch.   → /red:proto-architect
+[✅/⬜] 8. Developer        → /red:proto-dev
+[✅/⬜] 9. QA Engineer      → /red:proto-qa
+
+### Features im System
+- FEAT-1: [Name] – Status: [Schritt]
+- ...
+
+### Offene Bugs
+- BUG-FEAT[X]-[NNN]: [Kurztitel] (Severity) – oder: Keine offenen Bugs
+
+### Letztes Release
+- [Datum]: [Features / Bug Fixes] – oder: Noch kein Release
+
+### Nächster Schritt
+→ [Konkreter nächster Command + kurze Begründung]
+```
+
+**Schritt 3 – Empfehle den nächsten Schritt:**
+
+Basierend auf dem Status: Sag klar, was jetzt zu tun ist und welchen Command der User aufrufen soll. Wenn mehrere Features in verschiedenen Phasen sind: liste alle auf.
+
+**Schritt 4 – Hilf bei Problemen:**
+
+Wenn der User fragt "was ist schiefgelaufen" oder "ich bin nicht sicher ob X korrekt ist": Lies die relevanten Dateien und gib eine ehrliche Einschätzung.
+
+## Besondere Fälle
+
+**Neues Projekt (noch gar nichts vorhanden):**
+Erkläre kurz den Framework-Workflow und sage: "Starte mit `/red:proto-sparring` – beschreib mir deine Idee."
+
+**Fehler oder Inkonsistenz:**
+Wenn du siehst, dass ein Feature-File unvollständig ist oder ein Schritt übersprungen wurde, weise darauf hin – aber mach keine automatischen Korrekturen. Der User entscheidet.

package/commands/red:proto.md

@@ -0,0 +1,170 @@
+---
+name: Red Create Prototyp Project
+description: Initialisiert das Product Development Framework (red) im aktuellen Projekt – kopiert alle Commands und richtet die Projektstruktur ein
+---
+
+Du richtest das Product Development Framework für dieses Projekt ein.
+
+## Was du tust
+
+**Schritt 1 – Prüfe ob das Framework schon installiert ist:**
+
+```bash
+ls .claude/commands/ 2>/dev/null | grep -E "sparring|dev-setup|requirements|ux-design|solution-architect|developer|qa-engineer"
+ls .claude/agents/ 2>/dev/null
+cat project-config.md 2>/dev/null | grep "Codeverzeichnis"
+```
+
+**Wenn Commands bereits vorhanden sind**, frage mit AskUserQuestion:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Das Framework ist bereits installiert. Was möchtest du tun?",
+      header: "Setup-Modus",
+      options: [
+        {
+          label: "Nur fehlende Dateien hinzufügen",
+          description: "Bestehende Commands/Agents werden NICHT überschrieben – sicher für laufende Projekte"
+        },
+        {
+          label: "Alle Commands + Agents auf neueste Version aktualisieren",
+          description: "Überschreibt lokale Anpassungen an Commands und Agents – Projektdaten (features/, prd.md etc.) bleiben erhalten"
+        },
+        {
+          label: "Abbrechen",
+          description: "Nichts ändern"
+        }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+Bei "Abbrechen": sofort stoppen.
+
+**Schritt 2 – Verzeichnisse anlegen:**
+
+```bash
+mkdir -p .claude/commands
+mkdir -p .claude/agents
+mkdir -p research
+mkdir -p features
+mkdir -p flows
+mkdir -p bugs
+mkdir -p docs
+mkdir -p design-system/tokens
+mkdir -p design-system/components
+mkdir -p design-system/patterns
+mkdir -p design-system/screens
+# Codeverzeichnis NUR anlegen wenn noch kein project-config.md existiert:
+# (sonst ist das Codeverzeichnis bereits konfiguriert und möglicherweise anders als "projekt/")
+[ ! -f project-config.md ] && mkdir -p projekt
+```
+
+**Schritt 3a – Nur fehlende Dateien kopieren** (Modus: "Nur fehlende"):
+
+```bash
+# cp -n = no-clobber: überspringt Dateien die bereits existieren
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-workflow.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-sparring.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-dev-setup.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-research.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-requirements.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-flows.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-ux.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-architect.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-dev.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/commands/red:proto-qa.md .claude/commands/
+cp -n ~/.claude/templates/red-create-prototyp-project/agents/frontend-developer.md .claude/agents/
+cp -n ~/.claude/templates/red-create-prototyp-project/agents/backend-developer.md .claude/agents/
+cp -n ~/.claude/templates/red-create-prototyp-project/agents/qa-engineer.md .claude/agents/
+cp -n ~/.claude/templates/red-create-prototyp-project/agents/ux-reviewer.md .claude/agents/
+
+# Design System Templates kopieren (nur wenn noch nicht vorhanden)
+cp -rn ~/.claude/templates/red-create-prototyp-project/design-system/ ./
+```
+
+Zeige danach welche Dateien bereits existiert haben (übersprungen) und welche neu hinzugefügt wurden:
+```bash
+# Überprüfen welche Dateien tatsächlich existieren:
+ls .claude/commands/
+ls .claude/agents/
+```
+
+**Schritt 3b – Alle aktualisieren** (Modus: "Aktualisieren"):
+
+Warnung ausgeben: "Commands und Agents werden mit der Template-Version überschrieben. Projektdaten (prd.md, features/, research/, bugs/, docs/) bleiben vollständig erhalten."
+
+```bash
+# Ohne -n: überschreibt bestehende Dateien
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-workflow.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-sparring.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-dev-setup.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-research.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-requirements.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-flows.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-ux.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-architect.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-dev.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/commands/red:proto-qa.md .claude/commands/
+cp ~/.claude/templates/red-create-prototyp-project/agents/frontend-developer.md .claude/agents/
+cp ~/.claude/templates/red-create-prototyp-project/agents/backend-developer.md .claude/agents/
+cp ~/.claude/templates/red-create-prototyp-project/agents/qa-engineer.md .claude/agents/
+cp ~/.claude/templates/red-create-prototyp-project/agents/ux-reviewer.md .claude/agents/
+
+# Design System Templates aktualisieren
+cp -r ~/.claude/templates/red-create-prototyp-project/design-system/ ./
+```
+
+**Schritt 4 – Empfohlene Skills prüfen:**
+
+Das Framework ruft folgende Skills auf, wenn sie installiert sind. Teile dem User mit, welche fehlen:
+
+```typescript
+// Prüfe ob Skills verfügbar sind – nenne fehlende beim Namen
+```
+
+| Skill | Genutzt von | Priorität |
+|-------|-------------|-----------|
+| `ui-ux-pro-max` | `/red:proto-ux`, `ux-reviewer` | Kern – stark empfohlen |
+| `frontend-design` | `frontend-developer` | Kern – stark empfohlen |
+| `neon-postgres` | `backend-developer` | Nur bei Neon-Stack |
+| `atlassian:spec-to-backlog` | `/red:proto-requirements` | Optional – bei Jira-Nutzung |
+| `atlassian:triage-issue` | `/red:proto-qa` | Optional – bei Jira-Nutzung |
+
+**Fehlende Kern-Skills:** Weise den User explizit darauf hin. Agents laufen ohne Skills, aber mit reduzierter Qualität.
+**Fehlende optionale Skills:** Kurz erwähnen, nicht blockieren.
+
+---
+
+**Schritt 5 – Bestätigung:**
+
+Zeige dem User welche Commands installiert wurden und erkläre den nächsten Schritt:
+
+```
+✅ Product Development Framework installiert
+
+Verfügbare Commands:
+/red:proto-workflow           → Pipeline-Status, offene Bugs, letztes Release
+/red:proto-sparring           → Idee schärfen + PRD erstellen
+/red:proto-dev-setup          → Projekt scaffolden, Git + GitHub einrichten
+/red:proto-research      → Research-Fragen, Personas, Problem Statement
+/red:proto-requirements       → Feature Specs (IEEE/IREB)
+/red:proto-ux          → UX-Design-Entscheidungen, DS-konform (nutzt: ui-ux-pro-max)
+/red:proto-architect → Tech-Design + Security
+/red:proto-dev          → Implementierung, orchestriert Agents parallel bei Full-Stack
+/red:proto-qa        → Tests + UX-Review parallel, Bug-Reports, Production-Ready
+
+Sub-Agents (.claude/agents/ – automatisch gestartet):
+frontend-developer  → Frontend-Implementierung (nutzt: frontend-design)
+backend-developer   → Backend-Implementierung (nutzt: neon-postgres bei Neon-Stack)
+qa-engineer         → Technisches QA-Review
+ux-reviewer         → UX-Review (nutzt: ui-ux-pro-max)
+
+Starte mit: /red:proto-sparring
+
+Nach einer Pause: /red:proto-workflow   → zeigt Projektstatus und empfiehlt nächsten Schritt
+```

package/design-system/README.md

@@ -0,0 +1,62 @@
+# Design System
+
+Zentrales Verzeichnis für alle Design-Vorgaben. Alle Agents des Frameworks lesen dieses Verzeichnis – es ist die verbindliche Referenz für Entscheidungen in UX-Design, Implementierung und Review.
+
+## Struktur
+
+```
+design-system/
+  tokens/
+    colors.md          ← Farb-Tokens (Primär, Sekundär, Semantic, Neutral)
+    typography.md      ← Schriften, Größen, Gewichte, Line-Heights
+    spacing.md         ← Spacing-Scale und Named Sizes
+    shadows.md         ← Elevation-System
+    motion.md          ← Transitions, Durations, Easing (optional)
+  components/
+    button.md          ← Beispiel-Komponente (kopieren und anpassen)
+    input.md           ← Beispiel-Komponente
+    card.md            ← Beispiel-Komponente
+    [weitere].md       ← Eigene Komponenten hier ablegen
+  patterns/
+    navigation.md      ← Header, Sidebar, Breadcrumb, Tab-Navigation
+    forms.md           ← Formular-Aufbau, Validation, Fehlermeldungen
+    feedback.md        ← Toasts, Modals, Loading States, Empty States
+    data-display.md    ← Tabellen, Listen, Cards, Badges
+  screens/
+    README.md          ← Anleitung für Screen-Exports
+    [flow-name]/       ← Figma-Exports oder Screenshots nach Flow gruppiert
+```
+
+## Anleitung
+
+### Wann befüllst du dieses Verzeichnis?
+
+**Du musst diesen Ordner nicht vor dem ersten Feature vollständig befüllen.** Fang mit dem an was du weißt – ein paar Farb-Tokens, ein Button – und ergänze während der Entwicklung. Was noch nicht definiert ist, füllen die Agents pragmatisch. Was definiert ist, wird verbindlich eingehalten.
+
+Das Design System wächst mit dem Projekt. Das ist normal und gewollt.
+
+### So befüllst du dieses Verzeichnis
+
+1. **Tokens zuerst** – Farben, Typografie und Spacing sind die Basis für alle Komponenten. Trage die Werte aus deinem Figma/Styleguide in die Token-Files ein.
+
+2. **Komponenten** – Jede Komponente bekommt ein eigenes File. Kopiere `components/button.md` als Vorlage. Trage Varianten, Zustände und visuelle Specs ein.
+
+3. **Patterns** – Übergreifende UX-Muster (wie Formulare aufgebaut sind, wie Navigation funktioniert). Diese informieren den UX-Design-Schritt direkt.
+
+4. **Screens** – Exportiere Figma-Screens als PNG und lege sie in den passenden Flow-Unterordner. Benenne sie aussagekräftig: `01-login.png`, `02-dashboard.png`.
+
+### Was passiert mit diesen Inhalten?
+
+| Agent | Liest | Zweck |
+|-------|-------|-------|
+| `/red:proto-ux` | `components/`, `patterns/` | Nur DS-konforme Komponenten in User Flows |
+| `/red:proto-dev` | `tokens/`, `components/` | Tokens und Specs direkt in Code übersetzen |
+| `frontend-developer` | alles | Vollständige DS-Referenz bei Implementierung |
+| `ux-reviewer` | alles | DS-Compliance-Check nach Implementierung |
+
+### Regeln für Agents
+
+- Existiert eine Komponente im DS → baue keine eigene, nutze die Spec
+- Existiert keine passende Komponente → baue eine neue, dokumentiere sie im `## Offene Punkte` im Feature-File
+- Tokens haben Vorrang vor Hardcoded-Werten (kein `#3B82F6` direkt – stattdessen den Token-Namen nutzen)
+- Abweichungen vom DS sind als UX-Bug zu melden (Severity: Medium oder höher)

package/design-system/components/button.md

@@ -0,0 +1,68 @@
+# Button
+
+## Beschreibung
+Löst eine Aktion aus. Buttons sind die primären interaktiven Elemente für Nutzeraktionen – Formulare absenden, Dialoge bestätigen, Prozesse starten.
+
+## Varianten
+
+| Variante    | Verwendung                                                   |
+|-------------|--------------------------------------------------------------|
+| `primary`   | Primäraktion auf einem Screen – max. 1 pro sichtbarem Bereich |
+| `secondary` | Sekundäraktion, Alternative zur primären Aktion             |
+| `ghost`     | Tertiäraktion, wenig visuelles Gewicht (z.B. "Abbrechen")   |
+| `danger`    | Destruktive Aktionen (Löschen, Unwiderrufliches)            |
+| `link`      | Aktion als Link gestylt – nur für Navigation innerhalb von Text |
+
+## Zustände
+
+| Zustand    | Verhalten                                                      |
+|------------|----------------------------------------------------------------|
+| `default`  | Ruhezustand                                                    |
+| `hover`    | Leichte Verdunkelung des Hintergrunds                         |
+| `focus`    | Sichtbarer Focus-Ring (`color-border-focus`, 2px, 2px Offset) |
+| `active`   | Stärkere Verdunkelung beim Klick                              |
+| `disabled` | Reduzierte Opacity (0.5), kein Cursor-Pointer, nicht klickbar |
+| `loading`  | Spinner + Text oder nur Spinner (Label bleibt sichtbar)       |
+
+## Größen
+
+| Größe | Padding (h/v)           | Font-Size    | Height  | Icon-Size |
+|-------|-------------------------|--------------|---------|-----------|
+| `sm`  | `spacing-2` / `spacing-3` | `text-sm`  | 32px    | 14px      |
+| `md`  | `spacing-3` / `spacing-4` | `text-sm`  | 40px    | 16px      |
+| `lg`  | `spacing-4` / `spacing-6` | `text-base`| 48px    | 18px      |
+
+## Visuelle Specs – Primary
+
+| Eigenschaft      | Default                   | Hover                      | Active                     | Disabled                  |
+|------------------|---------------------------|----------------------------|----------------------------|---------------------------|
+| Hintergrund      | `color-primary-500`       | `color-primary-600`        | `color-primary-700`        | `color-primary-300`       |
+| Text             | `color-text-on-primary`   | `color-text-on-primary`    | `color-text-on-primary`    | `color-text-on-primary`   |
+| Border           | keine                     | keine                      | keine                      | keine                     |
+| Border-Radius    | `radius-md`               | `radius-md`                | `radius-md`                | `radius-md`               |
+
+## Visuelle Specs – Secondary
+
+| Eigenschaft      | Default                   | Hover                      | Disabled                   |
+|------------------|---------------------------|----------------------------|----------------------------|
+| Hintergrund      | `color-neutral-0`         | `color-neutral-100`        | `color-neutral-50`         |
+| Text             | `color-neutral-800`       | `color-neutral-900`        | `color-neutral-400`        |
+| Border           | `1px` `color-border-default` | `1px` `color-neutral-400` | `1px` `color-neutral-200` |
+
+## Icons
+
+- Icons sind optional, immer links vom Text oder zentriert (icon-only)
+- Icon-only Buttons: quadratisch, immer mit `aria-label`
+- Gap zwischen Icon und Text: `spacing-gap-sm`
+
+## Regeln
+
+- Beschriftungen sind aktiv formuliert: "Speichern", "Bestellung absenden" – nicht "OK" oder "Submit"
+- Max. 1 Primary Button pro sichtbarem Kontext
+- Danger-Buttons erst nach Bestätigung (Modal oder Inline-Confirm)
+- Loading-Zustand bei async Aktionen – kein doppeltes Absenden ermöglichen
+
+## Nicht verwenden wenn
+
+- Die Aktion zu einer anderen Seite navigiert → `<a>`-Tag oder Link-Komponente
+- Es mehr als 4 Optionen gibt → Dropdown oder Segment-Control