diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md new file mode 100644 index 0000000..d62b003 --- /dev/null +++ b/STYLEGUIDE.md @@ -0,0 +1,173 @@ +# 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 `` (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(214,81,22,.40)` | akzentuierte Rahmen | +| `--accent` | `#f0a81a` | `#d65116` | **Primärakzent**: Buttons, aktive Nav, Icons, Headline-Akzent | +| `--accent-2` | `#f7dc11` | `#e4801d` | Sekundär-Akzent für Verläufe (Gelb-Glow) | +| `--accent-ink` | `#1c1100` | `#ffffff` | Textfarbe **auf** Akzentflächen | +| `--secondary` | `#2d9cce` | `#1f86b8` | **Flux-Blau**: Links + „richtig" | +| `--secondary-2` | `#5cc4e8` | `#2d9cce` | helleres Blau (Hover/Variante) | +| `--text` | `#ece3d2` | `#33271c` | Fließtext | +| `--muted` | `#8c8170` | `#8a7d6c` | gedämpfter Text, Labels, Captions | +| `--heading` | `#ffffff` | `#241a12` | Überschriften | +| `--success` | `#2d9cce` | `#1f86b8` | **„richtig"** (= Flux-Blau, bewusst kein Grün) | +| `--danger` | `#ff4d6d` | `#be123c` | **„falsch"** / Fehler / Löschen (kühles Crimson) | +| `--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`): +```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`. +- **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 `.css` mit eigenem Prefix anlegen, **nur** `var(--…)`-Tokens nutzen, +Feedback-Konvention (Blau/Rot) einhalten. + +--- + +## Do / Don't + +**Do** +- Farben/Schatten/Glow ausschließlich über Tokens. +- 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. +- Nicht die **Legacy-Dateien** als Stil-Referenz nehmen: `achievements.css`, `progress.css`, + `settings.css`, `soziales.css` (ungenutzt) sowie alte Schrift-Deklarationen + (`'Segoe UI'`/`'Poppins'`) entsprechen **nicht** dem aktuellen System. Maßgeblich ist `theme.css`. + +--- + +*Stand: 2026-06-30 · Quelle: `src/main/resources/static/css/theme.css` (BTTF-Palette, Dark/Light).*