Skip to content

docs: Mint-Y/Hermes Design System, UI-Templates & Design-Roadmap #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Toqsick merged 1 commit into from
Aug 20, 2026
Merged

docs: Mint-Y/Hermes Design System, UI-Templates & Design-Roadmap #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 118 additions & 0 deletions docs/design/design-workflow-roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Design-System-Workflow & Roadmap
## Linux Assistant (Mint-Y / Hermes) – Erweiterung, Verbesserung, UI/UX-Vorschläge

---

## Teil 1: Der Workflow (End-to-End)

```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 1. AUDIT │ → │ 2. TOKENS │ → │ 3. KOMPON. │ → │ 4. DOKU │ → │ 5. QUALITÄT │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
↑ │
└────────────────── 6. RELEASE & FEEDBACK-LOOP ←─────────────────┘
```

### Phase 1 – Design-Audit (1–2 Tage)
1. **Inventarisierung:** Alle `Color(...)`, `fontSize`, `BorderRadius`, `SizedBox`, `EdgeInsets` im Code per Regex/Code-Search erfassen.
2. **Inkonsistenzen finden:** Hartcodierte Farben vs. `MintY.currentColor` markieren. Bekannte Fälle: `Colors.grey` in security_check/overview.dart, `#D3D3D3`-Track in single_bar_chart.
3. **Komponenten-Katalog:** Jede wiederverwendete Widget-Klasse in eine Tabelle (Name, Datei, Props, Zustände).
4. **Screenshot-Baseline:** Goldens/Screenshots aller Layouts als visuelle Referenz sichern.

### Phase 2 – Token-Konsolidierung (2–3 Tage)
1. **Single Source of Truth:** Neue Datei `lib/layouts/design_tokens.dart` (oder `hermes_tokens.dart` ausbauen) mit allen Werten aus `linux-assistant-design-system.md`.
2. **ThemeExtension statt statischer Klasse:** `MintY` ist aktuell eine statische Klasse mit mutablem `currentColor`. Migration zu `ThemeExtension<MintYColors>` → Hot-Switch ohne Rebuild, testbar, kein globaler State.
3. **Semantic Tokens einführen:** Nicht `Color(0xff6db443)` direkt, sondern `tokens.accent`, `tokens.surfaceRaised`, `tokens.statusDanger`. Dadurch wird Distro-Theming trivial.
4. **Token-Export automatisieren:** Generator-Skript (Python/Dart), das aus der Token-Datei CSS-Variablen + JSON + Dart-Konstanten erzeugt → Web-Doku und App nie out-of-sync.

### Phase 3 – Komponenten-Härtung (3–5 Tage)
1. **MintYButton API vereinheitlichen:** Varianten-Enum (`primary|secondary|ghost|danger`) statt frei setzbarem `color`.
2. **Zustände definieren:** Für jede Komponente: default / hover / focus / disabled / loading / selected / error.
3. **SingleBarChart & MemoryStatus:** Schwellwerte (89 %, 100 %) als Parameter statt Magic Numbers.
4. **Hermes-Widgets als offizielles Set:** `HermesCard`, `HermesStatTile`, `HermesSparkline`, `HermesBadge` dokumentieren und mit Mint-Y-Tokens verdrahten.
5. **Storybook-Äquivalent:** Flutter Widgetbook einführen → jede Komponente isoliert in allen Zuständen & beiden Themes.

### Phase 4 – Dokumentation (laufend)
1. Die mitgelieferte HTML-Datei (`linux-assistant-ui-templates.html`) als Living Styleguide ins Repo (`docs/design/`) und in CI rendern (GitHub Pages).
2. Pro Komponente: Screenshot, Props-Tabelle, Do/Don't, Code-Snippet.
3. **ADR** (Architecture Decision Record) für Token-Architektur anlegen.

### Phase 5 – Qualitätssicherung (laufend, CI)
1. **Golden Tests:** `flutter_test` Goldens für alle Screens in Light/Dark + 3 Distro-Akzenten.
2. **Kontrast-Lint:** Skript, das alle Text-/Hintergrund-Paare gegen WCAG AA (4.5:1) prüft. Achtung: `#9D9D9D` auf `#2D2D2D` erreicht nur ~3.3:1 → für Body-Text zu schwach.
3. **Custom Lint-Regel:** Verbiete `Color(0x…)` außerhalb der Token-Datei (custom_lint Plugin).
4. **Visual Regression:** Screenshots pro PR diffen (GitHub Actions + golden_toolkit).

### Phase 6 – Release & Feedback-Loop
1. Design-Version ans Repo-Changelog koppeln (`version`-Datei existiert bereits).
2. Feedback-Layout der App (`lib/layouts/feedback/`) um optionalen UI-Report erweitern (Screenshot + Theme-Infos).
3. Pro Release: 1 Verbesserung aus der Roadmap (Teil 2) umsetzen.

---

## Teil 2: Was noch erweiterbar / verbesserbar ist

### 🔴 Technische Schulden (priorisiert)
| # | Befund | Problem | Lösung |
|---|--------|---------|--------|
| 1 | `MintY.currentColor` ist global mutable | Nicht testbar, kein Rebuild bei Wechsel | ThemeExtension + Provider/Riverpod |
| 2 | Light Theme ist zweitklassig | `canvasColor`/`cardColor` nur im Dark-Theme gesetzt; Light nutzt Defaults | Symmetrische Token-Sets für beide Themes |
| 3 | Magic Numbers (89 %, 100 %, 32/24/20 px) | Schwer konsistent zu ändern | Konstanten in Token-Datei |
| 4 | Farben per String-Key (`getColorByName("Green")`) | Typos crashen zur Laufzeit | Enum `MintYAccent { green, aqua, … }` |
| 5 | `Courier` als Monospace | Nicht auf jedem Linux vorhanden | Font-Fallback-Stack: `JetBrains Mono → DejaVu Sans Mono → monospace` |
| 6 | Fenster 1280×720 hart in C++ | Keine Mindestgröße, kein Resize-Verhalten | `gtk_window_set_default_size` + Min-Size + responsives Layout |

### 🟡 Architektur-Erweiterungen
- **Theme-Engine 2.0:** Distro-Erkennung + Benutzer-Override (Akzent frei wählbar aus der Mint-Y-Palette).
- **Hermes-Layer ausbauen:** Glassmorphism-Option (Blur + Translucency) als opt-in „Modern"-Preset neben klassischem Mint-Y.
- **Icon-System:** `IconLoader` um SVG-Cache und Named-Icon-Registry erweitern; Akzent-Färbung als Token statt direktem `MintY.currentColor`.
- **Motion-Spec:** Durations (`--motion-fast: 150ms`, `--motion-med: 300ms`), Curves (`easeOutCubic`) als Tokens.
- **Spacing-System:** Von {8,10,16,32} auf 4er/8er-Raster vereinheitlichen (10er-Ausreißer auf 8 oder 12 mappen).
- **i18n & RTL:** TextStyles RTL-sicher machen; `EdgeInsetsDirectional` für bidirektionales Padding.

### 🟢 Neue Bausteine
- **Empty-State-Komponente** (Icon + Text + CTA) – aktuell fehlt sie komplett.
- **Toast/Snackbar-Spec** für Erfolg/Fehler bei Command-Ausführung.
- **Skeleton-Loader** für MemoryStatus/DiskSpace während des Ladens.
- **Command-Palette-V2** (siehe UI/UX unten).
- **Design-Token-JSON** als öffentliche API, damit Community-Themes/Plugins dieselben Tokens nutzen.

---

## Teil 3: UI/UX-Vorschläge

### A. Informationsarchitektur
1. **Dashboard-first statt Search-first:** Health-Dashboard (CPU/RAM/Disk/Updates als HermesStatTiles) als Startscreen; Suche per `Ctrl+K` erreichbar.
2. **Prioritäts-Ampel konsistent nutzen:** Security-Check- und Health-Ergebnisse in drei Spalten (Kritisch / Empfohlen / Optional) statt linearer Liste.
3. **Progressive Disclosure im Greeter:** Einführungstour auf „3 Pflicht-Schritte + Rest aufklappbar" reduzieren.

### B. Interaktion & Feedback
4. **Destructive Actions absichern:** Disk-Cleaner & Uninstaller: Bestätigungs-Dialog mit konkreter Folge („2,4 GB werden gelöscht") + Undo-Hinweis, Button in `--status-danger`.
5. **Lange Operationen:** RunCommandQueue sollte Live-Log + ETA + „Im Hintergrund weiterlaufen lassen" bieten.
6. **Erfolg explizit machen:** Nach abgeschlossener Aktion Success-Zusammenfassung mit Zahlen („42 Pakete aktualisiert, 1,2 GB frei").
7. **Keyboard-First:** Vollständige Tastatur-Navigation (Pfeiltasten durch ActionEntryCards, `Enter` = Run, `Esc` = Back).

### C. Visuelle Politur
8. **Kontrast-Fixes:** `--color-text-dim #9D9D9D` auf `#2D2D2D` ist unter WCAG AA → auf `#B5B5B5` anheben.
9. **Fokus-Ringe:** Sichtbarer Focus-Indicator (2px Accent-Outline) für alle interaktiven Elemente.
10. **Konsistente Radius-Sprache:** Karten 10, Panels 20, Chips 8 – in Doku festnageln und per Lint durchsetzen.
11. **Mikro-Animationen:** HaloDot pulsieren bei laufendem Prozess; Sparkline animiert einzeichnen; Card-Hover mit 150ms-Fade.
12. **Distro-Branding dezent:** Kleines Distro-Badge in der Sidebar („Erkannt: Zorin OS 17") schafft Vertrauen.

### D. Accessibility
13. **Skalierung:** UI-Skalierungs-Option (100/125/150 %) – wichtig für HiDPI und Sehbehinderung.
14. **Screenreader-Labels:** Alle Icon-Buttons mit Semantics-Label; Terminal-Output als `live region`.
15. **Reduzierte Bewegung:** `MediaQuery.disableAnimations` respektieren.
16. **Farbblindheit:** Status nie nur über Farbe codieren → Icon + Text bei Success/Warning/Danger.

### E. Gamification
17. **„System-Health-Score"** (0–100) auf dem Dashboard, mit Verlauf-Sparkline – motiviert zur regelmäßigen Pflege.
18. **Onboarding-Checkliste mit Fortschrittsbalken** im Mint-Y-Green; nach Abschluss Badge „System gewartet ✔".

---

## Anhang: Schnell-Referenz Akzent-Palette

| Green | Aqua | Blue | Teal | Purple | Pink | Red | Orange | Sand | Brown | Grey |
|---|---|---|---|---|---|---|---|---|---|---|
| #6DB443 | #6CABCD | #5B73C4 | #2AB9A4 | #8C6EC9 | #C76199 | #C15B58 | #DB9D61 | #C8AC69 | #AA876A | #9D9D9D |
203 changes: 203 additions & 0 deletions docs/design/linux-assistant-design-system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
# Linux Assistant Design System
## „Mint-Y / Hermes" – Extrahiert aus Toqsick/linux-assistant (Flutter, Material 3)

> Quelle: `lib/layouts/mint_y.dart`, `lib/main.dart`, `lib/widgets/*`, `lib/layouts/hermes_tokens.dart` (Fork),
> `linux/my_application.cc`. Alle Werte wurden direkt aus dem Code verifiziert.

---

## 1. Design-Prinzipien

1. **Distro-Adaptive Theming** – Die Akzentfarbe wechselt automatisch je nach erkannter Distribution (`setMainColor()` in `main.dart`).
2. **Material 3, dunkel zuerst** – `useMaterial3: true`, Dark-Theme ist der Standard-Zustand der App.
3. **Eine Akzentfarbe regiert alles** – `MintY.currentColor` steuert Buttons, Checkboxen, Icons, Textselektion, Fortschrittsbalken.
4. **Flache Karten, runde Ecken** – keine Schatten-Hierarchie, Tiefe entsteht über Flächenkontraste (#1F1F1F → #2D2D2D).
5. **Funktionale Statusfarben** – Rot/Orange/Grün werden *nur* für Systemzustände verwendet (Disk >89 %, CPU ≥100 %, Success/Warning).

---

## 2. Farb-Tokens

### 2.1 Kernfarben (Core)

| Token | Hex | Verwendung (verifiziert) |
|---|---|---|
| `--color-primary` | `#6DB443` | `MintY.currentColor` – Mint-Y Green, Hauptakzent |
| `--color-primary-light` | `#92B372` | Helle Green-Variante (auskommentiert im Code) |
| `--color-secondary` | `#2AB9A4` | `MintY.secondaryColor` – Teal, Sekundärakzent |
| `--color-canvas-dark` | `#1F1F1F` | `canvasColor` Dark Theme – App-Hintergrund |
| `--color-surface-dark` | `#2D2D2D` | `cardColor` Dark Theme – Karten/Panels |
| `--color-highlight` | `#FFFFFF` | `highlightColor` Dark Theme |
| `--color-text-on-dark` | `#FFFFFF` | Überschriften/Body auf dunklem Grund |
| `--color-text-on-light` | `#000000` | Überschriften/Body auf hellem Grund |

### 2.2 Akzent-Palette (Mint-Y, `getColorByName()`)

| Name | Hex | Token |
|---|---|---|
| Green | `#6DB443` | `--accent-green` |
| Aqua | `#6CABCD` | `--accent-aqua` |
| Blue | `#5B73C4` | `--accent-blue` |
| Teal | `#2AB9A4` | `--accent-teal` |
| Purple | `#8C6EC9` | `--accent-purple` |
| Pink | `#C76199` | `--accent-pink` |
| Red | `#C15B58` | `--accent-red` |
| Orange | `#DB9D61` | `--accent-orange` |
| Sand | `#C8AC69` | `--accent-sand` |
| Brown | `#AA876A` | `--accent-brown` |
| Grey | `#9D9D9D` | `--accent-grey` |
| Yellow | `#D8C15B` ⚠️ | `--accent-yellow` *(nicht im Code gefunden – Mint-Y-konform ergänzt)* |

### 2.3 Distributions-Themes (`setMainColor()` in `main.dart`)

| Distribution | Primary | Secondary |
|---|---|---|
| Linux Mint (Default) | `#6DB443` | `#2AB9A4` |
| LMDE | `#35A854` | `#238246` |
| Debian | `#D0074E` | `#2AB9A4` |
| openSUSE | `#73BA25` | `#0F5F4B` |
| KDE Neon | `#236896` | `#18A087` |

> Erweiterbar: Ubuntu `#E95420`, Fedora `#51A2DA`, Arch `#1793D1`, Pop!_OS `#48B9C7`, Manjaro `#35BF5C`, Zorin `#15A6CF`.

### 2.4 Semantische / funktionale Farben

| Token | Hex | Verwendung |
|---|---|---|
| `--status-success` | `#4CAF50` (`Colors.green`) | SuccessMessage, Icon `check` 32px |
| `--status-warning` | `#FF9800` (`Colors.orange`) | WarningMessage, Icon `warning` 32px |
| `--status-danger` | `#F44336` (`Colors.red`) | Disk >89 %, CPU ≥100 %, Clean-Icon |
| `--chart-cpu` | `#4699DD` | CPU-Balken (memory_status) |
| `--chart-ram` | `#C177F3` | RAM-Balken (memory_status) |
| `--chart-disk` | `#8D8D8D` | Disk-Balken normal |
| `--chart-track` | `#D3D3D3` | Bar-Hintergrund (single_bar_chart) |
| `--chart-fill` | `#494949` | Bar-Füllung Default |
| `--terminal-fg` | `#FFFFFF` | Konsolen-Output (`SelectableText`, Courier) |

---

## 3. Typografie

System-Font-Stack (Flutter Default = Roboto; auf Linux faktisch GTK-Systemfont). Monospace: `Courier` für Terminal-Output.

| Token | Größe | Gewicht | Variante | Mapping (TextTheme) |
|---|---|---|---|---|
| `--text-heading-1` | 32 | 500 | White / Black | displayLarge, displayMedium |
| `--text-heading-2` | 24 | 400 | White / Black | displaySmall, headlineLarge |
| `--text-heading-3` | 20 | 400 | White / Black | headlineMedium, titleLarge |
| `--text-heading-4` | 16 | 400 | White / Black | headlineSmall, **Button-Label** (`MintYButton`) |
| `--text-body` | 14 | 400 | – | bodyMedium |
| `--text-caption` | 12 | 400 | – | bodySmall, Tooltips |
| `--text-mono` | 14 | 400 | Courier | Terminal-/Log-Ausgabe |

Konvention: Jede Stufe existiert als `headingN` (schwarz, Light) und `headingNWhite` (weiß, Dark).

---

## 4. Geometry & Layout

### 4.1 Fenster
- Default-Fenstergröße: **1280 × 720** (`gtk_window_set_default_size`)
- App-Struktur: zentrierte Content-Column, Bottom-Action-Bar mit `MintYButton` (Zurück/Weiter)

### 4.2 Corner Radius

| Token | Wert | Verwendung (verifiziert) |
|---|---|---|
| `--radius-xs` | 2 | Mini-Progressbars (cleaner_select_disk, minHeight 5) |
| `--radius-sm` | 7 | Fortschrittsbalken (clean_disk, minHeight 15) |
| `--radius-md` | 8 | Info-Chips, Security-Check-Boxen (padding 8) |
| `--radius-lg` | 10 | Action-Entry-Cards / ListTiles (action_entry_card) |
| `--radius-xl` | 20 | Große Panels (flathub_permissions, padding 16) |

### 4.3 Spacing-Scale (aus SizedBox-/Padding-Mustern)

| Token | Wert | Verwendung |
|---|---|---|
| `--space-1` | 8 | Icon↔Text-Abstand, Chip-Padding |
| `--space-2` | 10 | Button-Gruppen, Element-Stacking |
| `--space-3` | 16 | Panel-Padding, Card-Content |
| `--space-4` | 32 | Sektions-Trennung, Hero-Abstände |

### 4.4 Icon-Größen
| Token | Wert | Verwendung |
|---|---|---|
| `--icon-sm` | 20 | Inline-Aktions-Icons (Clean-Icon) |
| `--icon-md` | 32 | Status-Icons (Success/Warning) |
| `--icon-lg` | 48 | Feature-/Entry-Icons (basic_entries) |
| `--icon-xl` | 64 | Settings-Hero-Icons |

Icons sind immer in `MintY.currentColor` eingefärbt; System-Icons laufen über `IconLoader` mit Fallback auf Material-Icons.

---

## 5. Komponenten (aus Code extrahiert)

| Komponente | Datei | Spezifikation |
|---|---|---|
| **MintYButton** | `mint_y.dart` | Primär-Button, `color: currentColor`, Label `heading4White`, Radius 10 |
| **MintYNextButton / BackButton** | `mint_y.dart` | Bottom-Bar-Navigation, lokalisiert |
| **ActionEntryCard** | `action_entry_card.dart` | ListTile, Radius 10, selected = `focusColor`, sonst transparent, Titel + Subtitle |
| **SingleBarChart** | `single_bar_chart.dart` | Vertikaler Balken, Track `#D3D3D3`, Tooltip weiß |
| **MemoryStatus** | `memory_status.dart` | CPU `#4699DD` / RAM `#C177F3`, rot ab Schwellwert |
| **DiskSpace** | `disk_space.dart` | Balken `#8D8D8D`, rot >89 %, Clean-Affordance |
| **SuccessMessage** | `success_message.dart` | `Icons.check` 32px grün + Text, gap 8 |
| **WarningMessage** | `warning_message.dart` | `Icons.warning` 32px orange + optional Fix-Button |
| **SystemIcon** | `system_icon.dart` | IconLoader → Cache, Akzentfarbe, Fallback Material |
| **RunCommandQueue** | `run_command_queue.dart` | Terminal-View: schwarzer Hintergrund, Courier, weiß, selektierbar |
| **GreeterCard** | `greeter/*` | Schwarzes Panel, Radius 20, Padding 16 |

### 5.1 Hermes-Layer (Fork Toqsick, `lib/widgets/hermes/`)
Neues, moderneres Component-Set des Forks – Tokens in `lib/layouts/hermes_tokens.dart` (13 KB):
`HermesCard`, `HermesBadge`, `HermesNavItem`, `HermesStatTile`, `HermesSparkline`, `HermesHaloDot`, `HermesCopyCommand`.
→ Empfehlung: Hermes als **Layer 2** des Design Systems definieren (Glass/Halo-Optik), Mint-Y bleibt **Layer 1** (Basis-Tokens).

---

## 6. Token-Exporte

### 6.1 CSS Custom Properties
```css
:root {
--color-primary: #6DB443;
--color-secondary: #2AB9A4;
--color-canvas: #1F1F1F;
--color-surface: #2D2D2D;
--color-text: #FFFFFF;
--status-success: #4CAF50;
--status-warning: #FF9800;
--status-danger: #F44336;
--radius-sm: 7px;
--radius-md: 8px;
--radius-lg: 10px;
--radius-xl: 20px;
--space-1: 8px; --space-2: 10px; --space-3: 16px; --space-4: 32px;
--font-mono: "Courier", monospace;
}
```

### 6.2 Dart (Flutter ThemeExtension-Skelett)
```dart
class MintYTokens {
static const primary = Color(0xff6db443);
static const secondary = Color(0xff2ab9a4);
static const canvasDark = Color(0xff1f1f1f);
static const surfaceDark = Color(0xff2d2d2d);
static const chartCpu = Color(0xff4699dd);
static const chartRam = Color(0xffc177f3);
static const chartDisk = Color(0xff8d8d8d);
static const radiusXs = 2.0, radiusSm = 7.0, radiusMd = 8.0;
static const radiusLg = 10.0, radiusXl = 20.0;
}
```

---

## 7. Do's & Don'ts

- ✅ Akzentfarbe ausschließlich über `currentColor`-Token setzen, niemals hardcoden
- ✅ Statusfarben nur für echte Systemzustände (Schwellwerte: Disk 89 %, CPU 100 %)
- ✅ Pro Theme-Variante White/Black-Textpaar verwenden
- ❌ Keine Schatten-Stacks – Tiefe über Flächenkontrast
- ❌ Keine Zweit-Akzentfarbe innerhalb eines Screens
- ❌ Kein Mischen mehrerer Radius-Stufen in derselben Komponente
Loading
Loading