# Anweisungen an Claude Design — GUI-System für Steve-TradingBot

**Briefing-Datum:** 2026-05-09
**Auftraggeber:** KW Baustoffe (Operator), Steve-TradingBot
**Quell-Commit:** `1fdeec8` (GUI-DESIGN-PREFLIGHT)
**Empfänger:** Claude Design / Figma-Designer

---

## 1. Mission

Du baust ein **vollständiges, professionelles Design-System** für die existierende Filament-v4-GUI eines Trading-Bots. Die Architektur ist bereits stabil (525/525 Tests grün, T-SPLIT-Stack komplett, Runtime-Apply/Clear live verifiziert). Dein Auftrag ist die **visuelle + interaktive Schicht**: Component-Library, Screens, Operator-Flows, Mobile-Variants, Banner-Hierarchie.

**Was du NICHT tust:** Code schreiben. Bot-Logik anfassen. DB-Schema ändern. Mainnet aktivieren. Naming-Cleanup auf der Code-Ebene durchführen.

---

## 2. Quellen (Single Source of Truth)

Dein gesamter Input liegt in drei Dateien. Lies sie als kanonische Wahrheit. Bei Konflikt zwischen diesen Files und externer Annahme: **diese Files gewinnen.**

| Datei | Format | Größe | Zweck |
|---|---|---|---|
| `docs/gui/gui_design_preflight.md` | Markdown | 58 706 bytes | Primärer Bericht — 10 Sektionen A–J, lies zuerst |
| `docs/gui/gui_design_preflight.json` | JSON | 19 759 bytes | Strukturiert für Figma-Plugin / programmatische Ingestion |
| `docs/gui/gui_design_preflight.txt` | Plain | 56 392 bytes | Markdown-stripped für Plain-Reader |

**Auch konsumieren:**
- `docs/roadmap/t_split_roadmap.md` — kanonische Phase-Übersicht
- `docs/ops/g10_runtime_config_operator_runbook.md` — Operator-Workflows für Apply/Clear
- `trading/SAFETY_FILTERS.md` — durable Safety-Layer

---

## 3. Was du zu liefern hast (Acceptance-Criteria)

Eine Figma-Datei (oder gleichwertiges Design-Artefakt), die folgendes enthält:

### 3.1 Design-Tokens

- **Colors:** primary (sky-600), success (emerald-500), danger (rose-500), warning (amber-500), info (blue-500), gray (slate-500) — mit 50/500/700/900-Stufen
- **Typography:** Sans-Stack + Mono-Stack, Sizes h1–caption (siehe preflight §F.2.2)
- **Spacing:** 4 / 8 / 12 / 16 / 24 / 32 / 48
- **Breakpoints:** sm 640 / md 768 / lg 1024 / xl 1280 / 2xl 1536 + **xs 480** als neuer Mobile-Breakpoint
- **Shadows:** sm / md / lg
- **Border-radius:** 4 / 8 / 12

### 3.2 Component-Library (20 Komponenten aus Preflight §F.1.1–F.1.20)

Pro Komponente eine Figma-Variant-Komponente mit:
- alle Varianten (z.B. KPI-Card: default / with-trend / with-badge / disabled-look / clickable)
- alle Zustände (z.B. loaded / loading / empty / stale / error)
- Mobile-Variant (kompakt) wo Preflight es fordert
- Dark-Mode-Variant (Filament v4 unterstützt nativ)

**Pflicht-Komponenten:**
1. KPI Card · 2. Stat Card · 3. Runtime Panel · 4. Status Chip · 5. Badge · 6. Chart (5 Sub-Variants) · 7. Table · 8. Filter · 9. Tabs · 10. Empty State · 11. Warning Panel · 12. Alert Banner · 13. Audit Timeline · 14. Position Card · 15. Strategy Card · 16. Risk Panel · 17. Capital Panel · 18. Apply/Clear Panel · 19. Command Queue Panel · 20. Notification

### 3.3 Screens (Page-Templates)

| Screen | Variants nötig | Quelle |
|---|---|---|
| Login | branded vs filament-default | preflight §A.2 |
| MonitoringDashboard | desktop + mobile + dark | preflight §C.6 |
| Resource-List (× 7) | compact + detailed + mobile-toggleable | preflight §A.8 |
| Resource-View Detail (× 7) | desktop + mobile | preflight §A.5 |
| ConfigProfile-Detail (mit 8 Header-Actions) | desktop only — mobile collapse | preflight §A.5 |
| Modal-Patterns | normal-confirm + hard-confirm + form | preflight §A.6 |
| Audit-Timeline-View | vertical desktop + vertical mobile | preflight §F.1.13 |
| Strategy-Stats Detail mit Period-Tabs | desktop-first | preflight §A.1 |
| Empty-State-Catalog | 4 Varianten | preflight §F.1.10 |
| Banner-Hierarchy | CRITICAL/HIGH/MID/LOW | preflight §F.1.12 |

### 3.4 Operator-Flows (interactive Prototypes)

Modelliere die folgenden 8 Flows als klickbare Prototypes:

1. **Login → Dashboard** (Operator-First-View)
2. **Day-Start Health-Check** (Banner → KPIs → Errors)
3. **Risk-Tweak** (Configuration → Profile → Risk-Edit → Apply mit hard-confirm → Worker-Hint → CommandBus → Verify)
4. **Rollback** (Profile → Clear → Worker-Hint → Verify)
5. **Forensik** (DecisionLog → Filter → Single Decision → Metadata)
6. **Strategy-Performance-Drill** (StrategyStat → Period-Tab → Top-N → Drill-in)
7. **Crash-Recovery** (Bot-PID-Alert → Health-Card → Errors → Log → CommandBus-Replay)
8. **Mobile Status-Sweep** (kompakte Mobile-Variante des Day-Start)

### 3.5 Banner-Severity-System

Komponente "Alert Banner" mit 4 Severity-Stufen + spezifische Trigger:

| Severity | Trigger | Visual |
|---|---|---|
| CRITICAL | Mainnet-Path detected (NIE), CHECK-Constraint-Violation, Bot-PID-Crash-Loop (3× in 60min) | rot, sticky-top, optional pulsing |
| HIGH | failed/rolled_back command, manual_intervention_required, errors.log new traceback, Snapshot-stale + override active | rose-mid |
| MID | no_effect apply (operator-Fehleinschätzung), Legacy >90% nach T-SPLIT-2 (= emit broken), cycle frequency <0.5/min | amber |
| LOW | dry-run failed, empty-state no_data_yet | slate |

### 3.6 Strategy-Group-Color-Map (durable)

| Group | Tone | Color |
|---|---|---|
| `t1_core` | info | sky |
| `t2_pump_dump` | warning | amber |
| `t3_copy_trading` | gray (planned/disabled) | slate |
| `legacy_unknown` | gray | slate |

Diese Map ist **durable** (T-SPLIT-3 Konvention). Nicht ändern.

### 3.7 Mobile-Strategie

Per Persona/Use-Case:

| Device | Use-Cases | Design-Approach |
|---|---|---|
| **Mobile (xs/sm)** | Day-Start Health, Status-Check, T1/T2-KPIs, Errors-Detection | mobile-first, reduzierte Tabellen, KPI-Cards stacken |
| **Tablet (md)** | Operator Apply/Clear-Flow mit hard-confirm | hybrid, Modal vollbreit |
| **Desktop (lg/xl/2xl)** | Forensik, Resource-Tables, G3-Aggregator-Detail | desktop-first, alle Features |

**Pflicht:** PositionSnapshot (14 Spalten) bekommt eine mobile-toggleable-Variante mit priority-1 columns (symbol/PnL/PnL%/quantity), rest hidden by default.

### 3.8 Naming-Konvention (display-only)

**Wichtig — NICHT ändern in der DB!** Das ist Display-only:

- DB-Wert `mode='paper'` → Display-Label "TESTNET" (warning-Badge)
- DB-Wert `mode='paper' + environment='mainnet'` (zukünftig) → "MAINNET (paper-sim)" (danger-Badge)
- Strategy-Group-Labels: T1 Standard / T2 Pump & Dump / T3 Copy Trading / Legacy / Unknown

Begründung: durable rule per `feedback_testnet_permanent_paper_rename.md` — TESTNET bleibt dauerhaft erhalten; Bot-side Code-Rename ist eigene spätere Phase.

### 3.9 Operator-Personas

| Persona | Rechte | Surfaces |
|---|---|---|
| **Admin** | full (Apply, Clear, Risk-Edit, Profile-CRUD, Cancel/Retry) | alle |
| **Operator** | view + audit | Dashboard, Resources read-only, CommandBus |
| **Viewer** | read-only | Dashboard, Resources |

Designe **alle** Action-Buttons mit `visible(role)`-Logik im Hinterkopf — d.h. Mobile-Variants müssen für read-only-User noch funktional sein.

### 3.10 Future-Phase-Anchors

Berücksichtige in der Component-Library Platzhalter / Reservierungen für:

- **CAP-1 Profit-Reinvestment** → Capital-Panel-Komponente bereits in #17 vorgesehen
- **T-SPLIT-5 T2 Operator-View** → eigene Sub-Page unter Trading-Group; T2-Activity-Stream + Pump-Source-Live-Feed
- **T-SPLIT-6 T3 Planning-Marker** → eigene Sub-Page; planned/disabled-Banner
- **T3-EXECUTION** (eigene Folgephase) → Source-allowlist UI, Kill-Switch, Audit-Trail
- **Naming-Cleanup paper → TESTNET/MAINNET** → ModeLabels-Service-Display
- **Worker-Daemon Activation** → Worker-Daemon-Status-Card auf Dashboard
- **Mainnet-Cutover** (durably blocked heute) → rote Banner-Klasse, double-confirm-modal pattern

---

## 4. Hand-Off-Format

### 4.1 Figma-Datei-Struktur (erwartet)

```
📄 Steve-TradingBot Design System
├── 🎨 Foundations
│   ├── Colors
│   ├── Typography
│   ├── Spacing
│   ├── Breakpoints
│   ├── Shadows
│   └── Border-radius
├── 🧩 Components (20)
│   ├── KPI-Card (with all variants + states)
│   ├── Stat-Card …
│   └── … alle 20
├── 📐 Patterns
│   ├── Modal-Confirmation-Hard
│   ├── Modal-Confirmation-Normal
│   ├── Banner-Severity-Classes
│   └── Empty-State-Catalog
├── 🖼️ Screens
│   ├── Login (Desktop / Mobile / Dark)
│   ├── MonitoringDashboard …
│   └── …
├── 🎬 Flows (clickable Prototypes)
│   ├── Day-Start Health-Check
│   ├── Risk-Tweak with Apply
│   └── …
└── 📋 Hand-Off-Notes
    ├── Filament v4 anchor-Komponenten
    ├── Tailwind-Klassen-Mapping
    └── Implementation-priorities
```

### 4.2 Pro Component-Spec

- Name (matches preflight §F.1.x ID)
- Props/Slots (analog zu Filament-API)
- Variants
- States
- Token-Mapping (welche Design-Tokens werden genutzt)
- Mobile-Verhalten
- Anchor zu Filament v4 base component (z.B. `Filament\Forms\Components\TextInput`)

### 4.3 Implementation-Priority-Matrix

Pro Komponente klassifiziere:
- **P0** (sofort umsetzen — kritischer Mehrwert für Operator)
- **P1** (im nächsten Sprint umsetzen)
- **P2** (later — z.B. T-SPLIT-5/6 / CAP-1 Anchor-Komponenten)

---

## 5. Boundaries (durable, alle Phasen des Design-Builds)

### Erlaubt

- Figma-Datei + Hand-Off-Notes
- Asset-Files (Logo, Favicon, Illustrations für Empty-States)
- Design-Token-Definition + JSON-Export
- Interactive Prototypes
- Mobile-Variants
- Dark-Mode-Variants
- Diskussion / Q-Ping mit Operator vor finalem Hand-Off

### Nicht erlaubt

- Code (PHP / Python / JS / TS)
- DB-Migrations
- Bot-Logik-Änderungen
- Filament-Resource-Refactor
- Mainnet-Pfade einzeichnen ohne explizites Mainnet-Cutover-Briefing
- T3-Copy-Trading als „aktiv" rendern (durable rule: T3 ist planned/disabled bis T3-EXECUTION-Phase)
- DB-Werte vorschlagen die existing CHECK-Constraints brechen würden (z.B. neue strategy_group-Werte)
- Naming-Cleanup vorgreifen (mode='paper' → 'testnet' Migration ist eigene spätere Phase)

---

## 6. Spezifische Operator-Schmerzpunkte (Schwerpunkt setzen)

Aus Preflight §I — diese 3 sind **CRITICAL** und sollten höchste Design-Aufmerksamkeit bekommen:

| ID | Schmerz | Designer-Aufgabe |
|---|---|---|
| **C-1** | Kein dedizierter Mainnet-Block-Banner | Designe permanent sticky-top Banner "TESTNET · Mainnet durably blocked" — sichtbar auf jeder Page, nicht dismissible. Operator soll Mainnet-Status NIE übersehen können. |
| **C-2** | Live-Apply-Progress fehlt | Designe Apply/Clear-Panel mit Progress-States (pending / running / succeeded / failed / rolled_back / no_effect) inkl. Live-Polling-Indicator. Operator sieht in Echtzeit was passiert. |
| **C-3** | rolled_back / manual_intervention_required ohne UI-Highlight | Designe ein dezidiertes Critical-Alert mit `manual_intervention_required` als prominentem CTA. ListCommands-Row mit rolled_back-Status muss visuell sofort erkennbar sein. |

---

## 7. Was du gebrauchen kannst (Component-Anchors zur Filament-v4-Realität)

| Filament v4 Komponente | Dein Design-Equivalent |
|---|---|
| `Filament\Widgets\Widget` (Custom-Blade) | KPI Card / Runtime Panel / Strategy Card |
| `Filament\Widgets\StatsOverviewWidget` | Stat Card |
| `Filament\Widgets\ChartWidget` (Chart.js eingebaut) | Chart-Komponenten — verwende eingebaute Chart.js Layer, kein extra Lib |
| `Filament\Resources\Resource Table` | Table-Komponenten |
| `Filament\Tables\Filters\SelectFilter` | Filter-Component (Select-Variant) |
| `Filament\Forms\Components\TextInput` | Form-Inputs |
| `Filament\Actions\Action` (mit `requiresConfirmation()` + `schema()`) | Modal-Patterns (Confirmation-Normal + Hard) |
| `Filament\Notifications\Notification` | Toast (auto-dismiss); persistent-Inbox ist neu zu designen |

---

## 8. Erwartetes Lieferdatum + Iterations-Loop

- **Iteration 1:** Foundations + 5 wichtigste Komponenten (KPI Card, Status Chip, Banner, Modal-Confirmation-Hard, Apply/Clear-Panel) + Dashboard-Mockup
- **Iteration 2:** restliche 15 Komponenten + alle Screens
- **Iteration 3:** Operator-Flows als Prototypes + Mobile-Variants + Dark-Mode
- **Iteration 4:** Hand-Off-Notes + Implementation-Priority-Matrix + Q-Adressierung

Pro Iteration: kurzer Sync mit Operator (KW Baustoffe) zur Validierung. **Niemals direkt in den Code-Build springen** — Hand-Off ist klar getrennt.

---

## 9. Out-of-Scope (explizit, damit du es nicht versehentlich machst)

- Implementierung in PHP / Blade / Tailwind-Code
- DB-Schema-Vorschläge die Migration brauchen
- Bot-Trading-Logik
- Strategy-Decisions-Algorithmus
- Risk-Limits-Festlegung (das ist G9-Phase-2-Territorium, nicht Design)
- Mainnet-Cutover-Pfade (durable blocked)
- T3-Copy-Trading-Execution-Design (eigene Phase nach T3-EXECUTION-Preflight)
- Worker-Daemon-Aktivierung (eigene Deploy-Phase)
- Naming-Cleanup `paper → testnet` Code-Refactor (eigene spätere Phase)

---

## 10. Q&A-Erwartung an dich (Claude Design)

Stelle Fragen wenn unklar — bevor du designst. Beispiele für legitime Fragen:

- „Soll T3-Card im Mobile-Layout ausgeblendet werden oder als gedämpfter Platzhalter erhalten bleiben?"
- „Hat KW Baustoffe ein Brand-Logo / Brand-Color den ich als Override für `primary` benutzen soll?"
- „Wie ausführlich soll Audit-Timeline auf Mobile sein? Compact-Steps oder eingeklappt?"
- „Soll die Banner-Severity CRITICAL Sound-Alert / Vibration triggern?"

**NICHT-fragen-Beispiele** (Antwort bereits im Preflight):
- ~„Welche Strategie-Gruppen gibt es?" → §D, vier durable Werte~
- ~„Welche Polling-Cadence?" → §A.10, 30s Standard~
- ~„Welche Operator-Personas?" → §J.7, drei Personas~

---

## 11. Akzeptanz-Kriterien (Designer-Done-Definition)

Hand-Off ist akzeptiert, wenn:

- [ ] Alle 20 Komponenten in Figma als Variant-Component mit allen States existieren
- [ ] Alle 9 Screen-Templates für Desktop + Mobile + Dark-Mode existieren
- [ ] Alle 8 Operator-Flows als interactive Prototypes existieren
- [ ] Design-Tokens als Figma-Variables / Style-Library exportierbar sind
- [ ] CRITICAL-Schmerzpunkte (C-1/C-2/C-3) sichtbar adressiert sind
- [ ] Mainnet-Block-Banner permanent sticky vorhanden
- [ ] Strategy-Group-Color-Map durable angewendet
- [ ] Mobile-Strategie für PositionSnapshot 14-col Tabelle gelöst
- [ ] Naming-Konvention `paper`→TESTNET (display-only) konsistent
- [ ] Future-Phase-Anchors (CAP-1 / T-SPLIT-5/6 / Naming-Cleanup) berücksichtigt
- [ ] Implementation-Priority-Matrix (P0/P1/P2) per Komponente vorhanden

---

## 12. Sicherheits-Reminder (durable rules)

- **Mainnet bleibt blockiert** — durable per G10-4.0 / B-FEE-FIX / B-OUTAGE-RESILIENCE-1 / Operator-Drill 502 / `Settings.BINANCE_TESTNET=True`
- **Niemals Display einer Mainnet-Active-Variante** ohne ausdrückliches Mainnet-Cutover-Briefing
- **Niemals T3 als „aktiv" rendern** — T3-Card bleibt `planned · disabled`
- **Niemals neue strategy_group-Werte erfinden** — die 4 in §3.6 sind durch Postgres-CHECK-Constraint hardcoded
- **TESTNET bleibt dauerhaft** auch nach einer eventuellen Mainnet-Aktivierung — Design muss diese Dauerhaftigkeit reflektieren

---

*Briefing erstellt 2026-05-09 19:45 UTC. Kanonisch hinterlegt unter `docs/gui/claude_design_instructions.md` (committed) und veröffentlicht unter `http://81.169.213.37/shares/claude-design-instructions-<TS>.md`. Quell-Preflight: Commit `1fdeec8`.*