Hoard/GUI/style.md

# Hoard – Style Guide

## Zielbild
Hoard soll wirken wie eine ruhige, moderne Dateiverwaltung im Browser: klar, aufgeräumt, produktiv und leicht verständlich. Nicht verspielt, nicht luxuriös, nicht wie ein komplexes Notion-Klon-System. Die Oberfläche soll in erster Linie Ordnung vermitteln und den Fokus auf Dateien, Ordner, Vorschau und Markdown-Bearbeitung legen.

Die Gestaltung orientiert sich an drei Prinzipien:

1. **Dateien zuerst** – Inhalte, Dateinamen, Pfade und Aktionen stehen optisch im Vordergrund.
2. **Ruhige Oberfläche** – wenig visuelle Unruhe, viel Weißraum, zurückhaltende Farben.
3. **Grün als Identität, nicht als Dauerfeuer** – die Markenfarbe wird gezielt für Auswahl, Primäraktionen und Status genutzt, nicht flächendeckend.

## Stilrichtung
Die Seite soll sich optisch zwischen Google Drive und einer modernen self-hosted Admin-Oberfläche bewegen.

**So soll es wirken:**
- sachlich und sauber
- freundlich, aber nicht verspielt
- modern, aber bewusst einfach
- produktiv statt marketing-lastig
- leicht technisch, ohne kalt zu sein

**So soll es nicht wirken:**
- kein Neon- oder Gaming-Look
- kein Glassmorphism
- keine harten Kontraste überall
- keine überladenen Kartenlayouts
- keine bunte Mischung vieler Akzentfarben

## Visuelle Identität
Die Markenwirkung basiert auf neutralen Flächen mit einem kontrollierten Grün als Wiedererkennungsmerkmal. Das Grün kommt aus dem Logo und steht für Ablage, Struktur, Ruhe und „self-hosted tool“ statt „Social App“.

Die App soll **light-first** gestaltet werden. Ein Dark Mode kann später kommen, aber das Grunddesign wird zuerst für helle Oberflächen optimiert. Das spart Aufwand und hält die UI konsistenter.

## Farbpalette

### Primärfarben
- **Primary 700:** `#1C652F`  
  Für Primärbuttons, aktive Icons, Fokusrahmen, Links in aktiven Zuständen.
- **Primary 600:** `#2E7D32`  
  Für Hover-Zustände und aktive Navigation.
- **Primary 500:** `#3C8F42`  
  Für ausgewählte Einträge, Badges, bestätigende States.
- **Primary 300:** `#A8D5A2`  
  Für weiche Hintergründe von Auswahlflächen.
- **Primary 100:** `#EAF5E8`  
  Für sehr subtile Hervorhebungen.

### Akzentfarbe
- **Accent Lime:** `#B7E36B`  
  Nur sehr sparsam einsetzen, z. B. kleiner Glow im Logo-Bereich, leichtere Highlights, Upload-Fortschritt oder ausgewählte Illustrationsdetails. Nicht für normalen Text.

### Neutrale Farben
- **Background:** `#F6F8F5`  
  Hauptseitenhintergrund.
- **Surface 1:** `#FFFFFF`  
  Karten, Panels, Modals, Dialoge.
- **Surface 2:** `#F1F4EF`  
  Sekundäre Flächen, Toolbar-Hintergründe, Tabellenkopf.
- **Border:** `#DCE4D8`  
  Standard-Border.
- **Border Strong:** `#C7D2C2`  
  Stärkere Abgrenzung bei Panels und Inputs.

### Textfarben
- **Text Primary:** `#1F2A21`
- **Text Secondary:** `#5F6E62`
- **Text Muted:** `#7D8A80`
- **Text On Primary:** `#FFFFFF`

### Statusfarben
Schlicht halten, nicht zu bunt.
- **Success:** `#2E7D32`
- **Warning:** `#B7791F`
- **Danger:** `#C0392B`
- **Info:** `#2F6FB3`

## Typografie
Die Typografie soll neutral, gut lesbar und unauffällig modern sein. Keine dekorativen Schriften.

**Empfohlene Schriftfamilie:**
- `Inter`
- Fallback: `system-ui, sans-serif`

**Typografische Regeln:**
- normale Lesetexte: 14–15 px
- UI-Haupttext in Listen und Tabellen: 14 px
- Seitenüberschriften: 24–28 px
- Bereichsüberschriften: 18–20 px
- kleine Meta-Infos: 12–13 px
- Zeilenhöhe großzügig halten, besonders in Dateilisten und Formularen

**Schriftgewicht:**
- 400 für normalen Fließtext
- 500 für UI-Text und Labels
- 600 für Titel und aktive Elemente
- 700 nur sehr gezielt

## Layoutprinzip
Das Layout soll stark an eine Dateiverwaltung erinnern.

### Grundaufbau
- **Topbar** für Logo, Breadcrumbs, Kontextaktionen, Benutzer-Menü
- **linke Sidebar** für Navigation
- **Hauptbereich** für Dateiliste oder Grid
- **rechte Vorschau / Detailansicht** optional als Panel oder getrennte Ansicht

### Seitenbreite und Abstand
- großzügige horizontale Abstände
- Hauptinhalte nicht zu schmal machen
- Panels mit genug Luft, aber ohne Dashboard-Overdesign
- Standard-Abstandssystem in 4er- oder 8er-Schritten

**Spacing-Skala:**
- 4 px
- 8 px
- 12 px
- 16 px
- 20 px
- 24 px
- 32 px
- 40 px

## Formensprache
Die Formensprache soll weich, aber nicht rundgelutscht sein.

- kleine Controls: `8px` Radius
- Panels, Inputs, Dropdowns: `10px`
- Modals und größere Karten: `14px`
- keine pillenförmigen Vollflächen als Grundstil

## Schatten und Tiefe
Sehr zurückhaltend einsetzen. Die App soll stabil und ruhig wirken, nicht schwebend.

**Standard-Schatten:**
- Panels: leichter, weicher Schatten
- Dropdowns / Modals: etwas stärker, aber nie dramatisch
- keine starken farbigen Schatten im Produktivbereich
- grüner Glow nur höchstens im Branding oder auf Marketing-/Login-Flächen

## Komponentenstil

### Topbar
Die Topbar ist ruhig und funktional.
- Höhe ca. 60–64 px
- heller Hintergrund oder leicht abgesetzte Surface-Farbe
- Logo links
- Breadcrumbs klar lesbar, nicht zu klein
- Kontextaktionen rechts davon oder am rechten Rand
- dünne Unterkante oder subtile Shadow-Abgrenzung

### Sidebar
Die Sidebar ist funktional, nicht dominant.
- feste Breite, ca. 240–280 px
- leicht abgesetzte Hintergrundfläche
- aktive Einträge mit heller grüner Fläche und dunklerem Text
- Icons schlicht und einheitlich
- Navigation in logische Gruppen, aber ohne zu viele Sektionen

### Dateiliste
Die Dateiliste ist das Herzstück der App.

**Darstellung:**
- standardmäßig Listenansicht
- klare Spalten für Name, Typ, Größe, geändert am
- Zeilenhöhe eher luftig statt kompakt gepresst
- Hover nur leicht hervorheben
- ausgewählte Zeile mit heller grüner Tönung
- Doppelklick oder klarer Primärklick zum Öffnen
- Dateisymbole farblich dezent

**Wichtig:**
Die Liste soll strukturierter und ruhiger wirken als ein typisches Admin-Grid. Nicht wie eine Datenbanktabelle, sondern wie eine echte Dateiverwaltung.

### Karten / Panels
Karten nur dort einsetzen, wo es fachlich Sinn ergibt:
- Vorschau-Panel
- Datei-Infos
- Upload-Status
- Modals

Nicht jede Seite künstlich in zehn Karten aufteilen.

### Buttons
Buttons sollen schlicht und klar sein.

**Primärbutton:**
- grüner Hintergrund
- weiße Schrift
- mittlere Höhe
- klar erkennbare Hover- und Disabled-Zustände

**Sekundärbutton:**
- helle Fläche mit Border
- dunkler Text
- kein zu aggressiver Kontrast

**Tertiärbutton / Icon-Button:**
- für Zeilenaktionen, Toolbar, Preview-Aktionen
- Hover mit leichter Surface-Abhebung

**Regel:**
Es sollte pro Bereich meist genau eine klare Primäraktion geben.

### Inputs
- weiße Fläche
- klarer Border
- Fokuszustand mit grünem Ring oder grün betonter Border
- keine dunklen, schweren Inputs
- Labels oberhalb statt Placeholder-only

### Modals und Dialoge
- kompakt und funktional
- deutlicher Titel
- klare Primär- und Sekundäraktion
- nicht zu breit
- Löschen-Aktionen visuell bewusst neutral mit Danger-Akzent nur am Button

### Dropdowns und Kontextmenüs
- schlicht, hell, sauber getrennte Einträge
- Icons optional, aber konsistent
- Hover klar sichtbar
- kritische Aktionen unten gruppieren

## Vorschau-Bereich
Der Vorschau-Bereich ist ein zentraler Teil von Hoard und soll hochwertig, aber ruhig wirken.

### PDF-Vorschau
- heller neutraler Hintergrund
- PDF sitzt auf einer weißen „Papier“-Fläche
- genug Rand um die Seite herum
- Controls minimal und funktional

### Bildvorschau
- dunklerer neutraler Viewer-Hintergrund ist okay, wenn das Bild dadurch besser wirkt
- umgebende UI trotzdem konsistent mit dem restlichen Produkt halten
- keine übertriebene Galerie-Optik

### Markdown-Ansicht / Editor
Markdown-Dateien sollen wie Arbeitsdokumente wirken, nicht wie Blogposts.

**Vorgaben:**
- gute Textbreite
- klare Hierarchie bei Überschriften
- dezente Codeblock-Gestaltung
- sehr gute Lesbarkeit
- Editor und Preview optisch zur restlichen App passend, auch wenn `md-editor-v3` eigene Defaults mitbringt

## Tabellen- und Listenverhalten
Da der Kern deiner App Listen, Dateiansichten und Metadaten sind, muss das Verhalten konsistent sein.

- Hover ist immer subtil
- Auswahl ist immer über denselben Grünton markiert
- aktive Navigation und aktive Listelemente nutzen dieselbe semantische Farbe
- Sortierung, falls später vorhanden, visuell zurückhaltend markieren
- Bulk-Actions nur anzeigen, wenn wirklich etwas ausgewählt ist

## Icons
Empfohlen ist ein schlanker, moderner Icon-Stil mit einheitlicher Konturstärke.

Geeignet wären z. B.:
- Lucide
- Heroicons

**Regeln:**
- möglichst Outline-Icons
- nur wenige gefüllte Icons
- Dateityp-Icons dürfen leicht differenziert sein, aber nicht bunt explodieren
- Ordner-Icon in gedecktem Grün oder neutralem Grau

## Status und Feedback
Feedback soll klar sein, aber nicht laut.

### Toasts
- kurze Texte
- kein unnötiger Fließtext
- success, error, info klar unterscheidbar
- am besten oben rechts oder unten rechts, aber konsistent

### Ladezustände
- Skeletons oder sehr schlichte Loader
- lieber ruhige Platzhalter statt hektische Spinner überall

### Leere Zustände
Leere Zustände sollen freundlich, aber nüchtern sein.
- kleines Icon oder einfache Illustration
- ein klarer Satz
- eine eindeutige Folgeaktion

## Login-Seite
Die Login-Seite darf minimal etwas mehr Branding zeigen als die Haupt-App.

**Empfehlung:**
- zentrierte Login-Card
- Logo sichtbar
- neutraler Hintergrund mit sehr leichter grüner Stimmung
- keine starke Hero-Sektion nötig
- Fokus auf schnellem Einstieg

## Responsive Verhalten
Desktop ist der Hauptfokus. Mobile muss funktionieren, aber nicht die Priorität des MVP sein.

### Desktop
- volle Sidebar
- großzügige Dateiliste
- Preview neben Liste möglich

### Tablet
- Sidebar einklappbar
- Preview eher als Overlay oder eigene Ansicht

### Mobile
- eher einfache Stapelansicht
- Fokus auf Navigation und Öffnen
- Bearbeitung von Markdown darf reduziert sein, solange Lesen und einfache Bedienung sauber funktionieren

### Umsetzungsstandard Responsivität (verbindlich)
Die folgenden Regeln bilden den aktuellen Responsive-Standard von Hoard und sollen bei allen kommenden UI-Aufgaben eingehalten werden.

1. **Desktop-first, Mobile-only Overrides**
- Desktop-Styles bleiben Basis.
- Mobile-Anpassungen ausschließlich in Media Queries, keine Änderungen an Desktop-Baseregeln.

2. **Breakpoints**
- `@media (width <= 960px)` für Tablet/Mobile-Umbruch (Layout-Stacks, Spacing-Reduktion, Drawer-/Footer-Verhalten).
- `@media (width <= 600px)` für Phone-Feinschliff (volle Breite für CTAs, kompaktere Typo/Abstände).

3. **Globale Responsive-Patterns zuerst nutzen**
- Wiederverwendbare Anpassungen immer zuerst in den globalen Dateien pflegen:
  - `GUI/src/global.css`
  - `GUI/src/styles/global/page-layouts.css`
  - `GUI/src/styles/global/surface-patterns.css`
- Seiten-spezifisches `scoped` CSS nur für wirklich lokale Sonderfälle.

4. **Touch-Zielgrößen und Bedienbarkeit**
- Interaktive Elemente mobil mit klarer Daumen-Bedienbarkeit:
  - Buttons mindestens `44px` Höhe.
  - Icon-Buttons mindestens `44x44px`.
  - Navigations-Listeneinträge mindestens `48px` Höhe.
- Aktionszeilen (`hoard-action-row`) auf kleinen Geräten vertikal stapeln, damit Primäraktionen gut erreichbar sind.

5. **Safe-Area-Unterstützung**
- Bei mobilen Außenabständen `env(safe-area-inset-*)` berücksichtigen (iOS/Android).
- Muster: `max(var(--space-x), env(safe-area-inset-...))` als Fallback-sicherer Abstand.
- Besonders relevant für App-Bar-Ränder, Seiten-Padding und Bottom-Bereiche (Drawer/Footer).

6. **App-Shell-Muster**
- Mobile Navigation bleibt als Bottom-Sheet-Drawer.
- Desktop-Navigation bleibt unverändert (keine visuelle Regression auf großen Viewports).
- Footer-Links auf kleinen Screens umbauen (Wrap/Grid), mit ausreichend großen Tap-Flächen.

7. **Seiten-Muster**
- Content-Änderungen vermeiden; nur Layout/Bedienung anpassen.
- Karten-/Grid-Bereiche bei `<= 960px` in Einspalten-Layout überführen.
- Primäre CTAs bei `<= 600px` in voller Breite anzeigen.

8. **Responsive QA vor Abschluss**
- Pflicht-Viewports: `360x800`, `390x844`, `768x1024`, `1024x768`, `>=1280`.
- Prüfen: Navigation, Scroll-Verhalten, CTA-Erreichbarkeit, Formular-Bedienbarkeit.
- Desktop-Regression-Check: bei `>=1024` darf sich das gewollte Desktop-Erscheinungsbild nicht ändern.

## Interaktionsprinzipien
- Primäraktionen immer klar sichtbar
- destruktive Aktionen nie zu nah an Standardaktionen
- Dateizeilen sollen sich klickbar anfühlen, ohne wie Buttons auszusehen
- Hover, Active und Selected Zustände deutlich unterscheiden
- Fokuszustände für Tastaturbedienung sauber sichtbar machen

## Stil für konkrete Bereiche

### Ordnernavigation
- Breadcrumbs schlicht, klickbar, gut lesbar
- aktueller Ordner klar markiert
- Pfad nie visuell dominanter als der Inhalt

### Upload-Bereich
- Uploads funktional anzeigen, nicht dramatisch
- Fortschritt mit ruhiger grüner Progressbar
- Fehlerfälle klar lesbar
- Upload-Liste eher kompakt halten

### Datei-Details
- Metadaten in sauberem Zwei-Spalten-Raster oder kompakter Liste
- Labels und Werte klar unterscheidbar
- Aktionen wie Download, Umbenennen, Löschen klar getrennt

## Designregeln für die Umsetzung

### Immer tun
- viel Weißraum lassen
- Grün nur gezielt einsetzen
- Borders und Surface-Unterschiede subtil halten
- Listen und Dateiansichten priorisieren
- Text gut lesbar und eher neutral halten

### Vermeiden
- zu viele Karten
- zu viele Farbflächen
- übertriebene Animationen
- mehrere konkurrierende Akzentfarben
- rein dekorative UI-Elemente ohne Nutzen

## Beispiel für Design Tokens
Diese Tokens können später direkt in CSS-Variablen oder ein Theme übernommen werden.

```css
:root {
  --color-bg: #F6F8F5;
  --color-surface: #FFFFFF;
  --color-surface-alt: #F1F4EF;
  --color-border: #DCE4D8;
  --color-border-strong: #C7D2C2;

  --color-text: #1F2A21;
  --color-text-secondary: #5F6E62;
  --color-text-muted: #7D8A80;

  --color-primary-700: #1C652F;
  --color-primary-600: #2E7D32;
  --color-primary-500: #3C8F42;
  --color-primary-300: #A8D5A2;
  --color-primary-100: #EAF5E8;
  --color-accent-lime: #B7E36B;

  --color-success: #2E7D32;
  --color-warning: #B7791F;
  --color-danger: #C0392B;
  --color-info: #2F6FB3;

  --radius-sm: 8px;
  --radius-md: 10px;
  --radius-lg: 14px;

  --shadow-sm: 0 1px 2px rgba(16, 24, 18, 0.06);
  --shadow-md: 0 6px 18px rgba(16, 24, 18, 0.08);

  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
}
```

## Abschlussentscheidung für Hoard
Für Hoard ist ein **ruhiger, light-first, dateiorientierter Produktivstil mit neutralen Flächen und kontrolliertem Grün als Markenfarbe** die passendste Richtung.

Das passt zur Produktidee, weil:
- die App primär eine Dateiverwaltung ist
- Markdown-Bearbeitung und Vorschau im Vordergrund stehen
- die Oberfläche einfach und wartbar bleiben soll
- der Stil gut allein umsetzbar ist
- die UI professionell wirkt, ohne nach großem SaaS-Produkt aussehen zu müssen

## Kurzfassung als Design-Leitlinie
Wenn du bei einer UI-Entscheidung unsicher bist, gilt:

**Lieber schlichter als spektakulär. Lieber Google-Drive-artig als Dashboard-artig. Lieber ruhige Flächen und klare Listen als visuelle Effekte. Grün ist Identität, nicht Dekoration.**