# 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 bleibt **light-first**, aber Light- und Dark-Mode sind gleichwertig zu pflegen. Neue Komponenten müssen ihre Farben aus den Design-Tokens beziehen, damit beide Modi ohne Sonderlogik funktionieren. ## 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 - Schriftgrößen nicht mit Viewport-Breite skalieren; responsive Größen über feste Werte in Breakpoints setzen **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 - Hover-Lift maximal 1–2 px und nur bei klar interaktiven Flächen oder Demo-Karten ## 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. - Light- und Dark-Mode jeweils mindestens auf Desktop und Mobile prüfen. - 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.** ## Aktuelle Modernisierungsregeln - Oberflächen dürfen subtile lineare Surface-Verläufe, weichere Schatten und klare Fokusrahmen nutzen. - Route-Wechsel, Banner und wichtige Seitenbereiche dürfen kurze Fade-/Slide-Animationen verwenden. - Animationen bleiben ruhig: ca. 160–260 ms, keine dauerhaften Bewegungen, `prefers-reduced-motion` beachten. - Brand- und Navigationsbereiche dürfen etwas hochwertiger wirken, die Arbeitsflächen bleiben funktional und ruhig. - Zusätzliche UI-Elemente sind erlaubt, solange sie aus vorhandenen Daten entstehen und keine API-Calls oder Funktionen ändern. - QA immer in Light- und Dark-Mode sowie mobil prüfen; insbesondere Navigation, Formulare, Tabellen und Banner.