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.

: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.