mindflux/STYLEGUIDE.md

Mindflux – Style Guide

Verbindliche Design-Referenz für Mindflux. Single Source of Truth ist src/main/resources/static/css/theme.css – diese Datei dokumentiert nur, was dort definiert ist. Bei Änderungen immer zuerst theme.css anpassen und diese Datei nachziehen.

Grundregel: Niemals Hex-/RGBA-Werte hart in Templates oder Spiele-CSS schreiben. Immer die Tokens (var(--accent), var(--surface) …) verwenden, damit Dark/Light und künftige Palettenwechsel automatisch greifen.

Theme-Umschaltung: über das Attribut <html data-theme="dark|light"> (gesetzt/persistiert von theme.js; injiziert auch den mobilen Off-Canvas-Drawer). Dark ist Default.

---

Farbkonzept – „Back to the Future"

• Primärakzent = Feuer-Amber (Dark #f0a81a / Light #d65116) + Gelb-Glow (--accent-2) für Verläufe und Leuchten.
• Zweitakzent = Flux-Blau (#2d9cce) – für Links und das Spiel-Feedback „richtig".
• Warmer Bernstein-Glow statt Matrix-Grün; dunkler bzw. sehr heller Grund je Theme.
• Kein Grün im Erfolgs-Feedback: richtig = Blau ✓, falsch = Rot ✗ (Rot ist ein kühles Crimson, damit es sich klar vom orangen Akzent abhebt – v. a. im Light-Mode).

---

Token-Referenz (aus theme.css)

Token	Dark	Light	Verwendung
--bg	#0a0806	#fbf6ec	Seitenhintergrund (unter --bg-glow)
--bg-glow	radial rgba(240,168,26,.10)	radial rgba(214,81,22,.10)	weicher Lichtschein oben
--panel	#13100b	#ffffff	Sidebar, Topbar, Footer
--panel-2	#171209	#fdf7ea	Panel-Variante
--surface	#120f0a	#ffffff	Karten / Panels / Eingaben (Grundfläche)
--surface-2	#1b1610	#fbf4e6	erhöhte Fläche, Hover, Felder
--border	#2a2117	#ece1cf	Standard-Rahmen
--line	#221b12	#f1e8d8	feine Linien, Scrollbar, Chart-Achsen
--border-accent	rgba(240,168,26,.45)	rgba(194,65,12,.40)	akzentuierte Rahmen
--accent	#f0a81a	#c2410c	Primärakzent: Buttons, aktive Nav, Icons, Headline-Akzent
--accent-2	#f7dc11	#b45309	Sekundär-Akzent für Verläufe (Gelb-Glow)
--accent-ink	#1c1100	#ffffff	Textfarbe auf Akzentflächen
--secondary	#2d9cce	#146b96	Flux-Blau: Links + „richtig"
--secondary-2	#5cc4e8	#0f5a80	helleres Blau (Hover/Variante)
--text	#ece3d2	#33271c	Fließtext
--muted	#8c8170	#6b5f4c	gedämpfter Text, Labels, Captions
--heading	#ffffff	#241a12	Überschriften
--success	#2d9cce	#146b96	„richtig" (= Flux-Blau, bewusst kein Grün)
--danger	#ff4d6d	#be123c	„falsch" / Fehler / Löschen (kühles Crimson)
--warn	#edcb4c	#8a6a06	„eingeschränkt" / Warnstatus (Light-Wert WCAG-AA)
--glow-s	rgba(240,168,26,.55)	rgba(214,81,22,.40)	starker Glow (Text-/Drop-Shadow auf Akzent)
--glow-w	rgba(240,168,26,.16)	rgba(214,81,22,.12)	weicher Ambient-Glow
--g-soft	0 0 18px var(--glow-w)	0 6px 18px var(--glow-w)	Standard-Panel-Schatten

Semantik kurz

• Akzent (Amber/Orange): alles Primäre/Interaktive. Text auf Akzent immer --accent-ink.
• --accent + --accent-2 zusammen ergeben die typischen Verläufe (linear-gradient(…,var(--accent),var(--accent-2))).
• Blau (--secondary / --success): Links und Erfolg.
• Rot (--danger): Fehler, Löschen-Buttons, „falsch".

---

Spiele-Feedback (verbindlich)

In allen Spielen (FinalFlux, MindMatch, TechTacular, Syntax Saga) gilt einheitlich:

• richtig → var(--success) (Blau) + Häkchen ✓
• falsch → var(--danger) (Rot) + Kreuz ✗
• aufgelöst/neutral (Syntax Saga) → var(--secondary)

Muster (siehe z. B. syntaxsaga.css / techtacular.css):

.x-feedback.correct { color: var(--success); }
.x-feedback.correct::before { content: "\2713  "; }
.x-feedback.wrong   { color: var(--danger); }
.x-feedback.wrong::before   { content: "\2717  "; }

---

Typografie

• UI/Fließtext: "Inter","Segoe UI",system-ui,-apple-system,Roboto,sans-serif
• Code/Monospace: "JetBrains Mono","Fira Code","Consolas","Courier New",monospace
• Überschriften: font-weight:800, Farbe --heading.
• Eyebrow/Labels (.mf-eyebrow, Panel-h4): --accent, text-transform:uppercase, letter-spacing:.08–.12em, kleine Schrift.

---

Glow, Schatten & Radien

• Glow stark --glow-s: text-shadow/drop-shadow auf leuchtenden Akzentelementen.
• Glow weich --glow-w: dezenter Schein um Panels/Buttons.
• Panel-Schatten: box-shadow: var(--g-soft).
• Radien (Konvention): Badges/Buttons ~7–9px, Inputs/Icon-Buttons 10px, Nav 11px, Panels 13–14px, Standalone-Karten 16–18px, Pills/Bars 99px.
• Header-Icon-Buttons (.mf-iconbtn, .mf-theme, .mf-a11y-trigger, .ft-trigger): einheitlich 42×42px, Radius 10px, Outline-Stil (Surface-Fill, 1px Border, Akzent nur über color/border-color), Glyphe 20×20px. Der .mf-theme-Toggle behält Akzentfarbe + Glow als Erkennungsmerkmal.
• Spielkarten (.mf-card) haben eine abgeschrägte Ecke via clip-path (--n:18px) statt rundem Radius – ein bewusstes „HUD"-Detail.

---

Layout-Shell & Responsivität

App-Seiten nutzen das Grid .mf-shell (definiert in theme.css):

┌── Sidebar 264px ──┬─────── Topbar (Spalte 2–3) ───────┐
│                   ├──── Main 1fr ────┬─ Rightbar 332px ┤
└───────────────────┴──────────────────┴─────────────────┘

• .mf-shell.no-right → nur 264px | 1fr (ohne rechte Spalte).
• Breakpoints: ≤1180px rechte Spalte aus, 2-spaltig · ≤820px Shell stapelt, Sidebar wird zum Off-Canvas-Drawer (Hamburger + Backdrop, via theme.js) · ≤560px Spielkarten-Grid 1-spaltig.
• Spielseiten (MindMatch/TechTacular/Syntax Saga) haben eigene, schlankere Shells, nutzen aber dieselben Tokens und sind ebenfalls mobil-tauglich.

---

Komponenten-Cheatsheet (.mf-* aus theme.css)

Klasse	Zweck
.mf-btn	Primär-Button (Akzent). Varianten: .outline, .ghost, .danger
.mf-panel	Karte/Box; .accent = akzentuierter Rahmen + Glow
.mf-card / .mf-grid	HUD-Spielkarte (abgeschrägte Ecke) im 3er-Grid
.mf-input, .mf-select, textarea.mf-input	Formularfelder (Fokus = Akzentrahmen + Glow)
.mf-field, .mf-label	Formular-Zeile + Label
.mf-table	Tabellen (Kopf in Akzent, mobil horizontal scrollbar)
.mf-badge	kleines Status-Label
.mf-eyebrow	Kicker/Overline über Headlines
.mf-nav / .mf-sidebar	linke Navigation (aktiv = Akzent-Verlauf)
.mf-bar + > i	Fortschrittsbalken
.mf-center / .mf-cardbox	zentrierte Standalone-Karte (Login/Rechtsseiten)
.mf-container, .mf-page-head, .mf-back	einfache Inhaltsseiten + Zurück-Link
.mf-footer	globale Fußzeile
.mf-theme / .mf-theme-float	Dark/Light-Umschalter (Logik in theme.js)

---

Pro-Spiel-CSS

Jedes Spiel hat eine eigene CSS-Datei mit eigenem Klassen-Prefix, die ausschließlich Theme-Tokens verwendet (keine eigenen Farbwerte):

Spiel	Datei	Prefix
MindMatch	mindmatch.css	mm-
TechTacular	techtacular.css	tt-
Syntax Saga	syntaxsaga.css	ss-
FinalFlux	finalflux.css	finalflux-

Neues Spiel → neue <spiel>.css mit eigenem Prefix anlegen, nur var(--…)-Tokens nutzen, Feedback-Konvention (Blau/Rot) einhalten.

---

Do / Don't

Do

• Farben, Schatten und Effekte ausschließlich über Tokens. Für Effekte die Primitives --g-text, --g-icon, --g-strong, --g-amb, --g-card, --g-card-hover, --g-overlay und --g-focus verwenden; keine direkten Glow-Geometrien in Komponenten schreiben.
• Auf Akzentflächen Text in --accent-ink.
• Erfolg = Blau, Fehler = Rot (nie Grün/Orange für „richtig/falsch").
• Neue Komponenten an den .mf-*-Bausteinen orientieren.

Don't

• Keine hart kodierten Hex-/RGBA-Werte in Templates oder Spiele-CSS.
• Keine direkten 0 0 … var(--glow-*)-, text-shadow- oder drop-shadow-Werte in Komponenten. Maßgeblich ist theme.css.

---

Stand: 2026-06-30 · Quelle: src/main/resources/static/css/theme.css (BTTF-Palette, Dark/Light).