diff --git a/docs/design/design-workflow-roadmap.md b/docs/design/design-workflow-roadmap.md new file mode 100644 index 00000000..9ba52d7f --- /dev/null +++ b/docs/design/design-workflow-roadmap.md @@ -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` → 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 | diff --git a/docs/design/linux-assistant-design-system.md b/docs/design/linux-assistant-design-system.md new file mode 100644 index 00000000..3c18d556 --- /dev/null +++ b/docs/design/linux-assistant-design-system.md @@ -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 diff --git a/docs/design/linux-assistant-ui-templates.html b/docs/design/linux-assistant-ui-templates.html new file mode 100644 index 00000000..da6d928b --- /dev/null +++ b/docs/design/linux-assistant-ui-templates.html @@ -0,0 +1,345 @@ + + + + + +Linux Assistant – UI Templates (Mint-Y / Hermes Design System) + + + + + +
Template 1 · App-Shell (1280×720, Bottom-Bar)
+
+ +
+
+

Willkommen zurück

+

Dein System ist aktuell. 3 Empfehlungen verfügbar.

+
+
+
CPU
+
23 %
+
+ +
+
+
+
RAM
+
6.2 / 16 GB
+
+ +
+
+
+
Disk /
+
91 %
+
+
+
+
+
+ + +
+
+
+ + +
Template 2 · Buttons (MintYButton)
+
+
+ + + + + +
+
+ + +
Template 3 · Cards (ActionEntryCard / Hero)
+
+
+
+

🔄 System aktualisieren

+

Alle Pakete über den Paketmanager aktualisieren.

+
+
+

🧹 Speicher bereinigen

+

Ausgewählt – 2,4 GB können freigegeben werden.

+
+
+

🛡️ Security Check

+

Hero-Card (Radius 20, schwarz).

+ Geschützt +
+
+
+ + +
Template 4 · Badges & Status-Messages
+
+
+ Erfolgreich + Warnung + Kritisch + Empfohlen +
+
✔Firewall ist aktiv und korrekt konfiguriert.
+
+ ⚠Automatische Updates sind deaktiviert. + +
+
+ + +
Template 5 · Terminal & Copy-Command
+
+
$ sudo apt update && sudo apt full-upgrade -y +✔ 42 Pakete aktualisiert +⚠ Kernel-Update: Neustart erforderlich +$ _
+
+ sudo apt install timeshift + +
+
+ + +
Template 6 · Formulare
+
+ + +
+ + +
+
+ + +
Template 7 · Distro-Adaptive Akzente (JS-Switch)
+
+
+
+

Akzent-Vorschau

+
+ +
+
+ + + +