best-practices-kde

# KDE / QML Best Practices (Project Skill) Curated rules for writing and reviewing QML in this repo's KDE surface area (primarily `apps/horus-overlay/`). ## When to Apply Use this skill whenever you: - create or modify `.qml` files - add or change KDE Plasma integration (D-Bus, KWin scripts, global shortcuts) - design plugin UIs for the overlay system - review accessibility or keyboard navigation in QML ## Project Defaults - **Design System:** Use a `pragma Singleton` style object (e.g. `HorusStyle.qml`) — never hard-code colors, sizes, or animation durations - **Property Ordering:** Follow the canonical order (see below) - **Accessibility:** Every interactive element needs `Accessible.name`, `Accessible.role`, and `Accessible.description` - **File Size:** No QML file over **600** lines — extract delegates, sub-components, and style objects - **Effects:** `MultiEffect` / `layer.effect` only when GPU-composited; disable on software renderers ## Property Ordering (within a QML type) ```qml Item { // 1. id id: root // 2. Custom properties (readonly first, then mutable) readonly property string label: "Hello" property int count: 0 // 3. Sizing & geometry width: 200; height: 100 // 4. Anchors / Layout properties anchors.fill: parent Layout.fillWidth: true // 5. Visual properties (color, opacity, radius, clip, z, visible) color: HorusStyle.colors.bg opacity: 1.0 visible: true // 6. Behaviors & Transitions Behavior on opacity { NumberAnimation { duration: HorusStyle.anim.fast } } // 7. Signals signal clicked(string itemId) // 8. Signal handlers (on*) onVisibleChanged: { /* ... */ } // 9. Functions function doSomething() { /* ... */ } // 10. Child items (deepest nesting last) Text { text: root.label } } ``` ## Categories (priority order) 1. Correctness (CRITICAL): `correctness-` 2. Accessibility (HIGH): `a11y-` 3. Performance (HIGH): `perf-` 4. Design System (HIGH): `design-` 5. Integration (MEDIUM): `integration-` 6. Style & Maintainability (MEDIUM): `style-` ## Rules ### `design-singleton-style` **Impact: HIGH** — All colors, spacing, typography, and animation durations MUST come from the singleton design system (`HorusStyle`). Hard-coded hex colors in component files are a violation. ```qml // ❌ BAD color: "#1e293b" font.pixelSize: 14 // ✅ GOOD color: HorusStyle.colors.bgElevated font.pixelSize: HorusStyle.text.bodySize ``` ### `design-token-completeness` **Impact: MEDIUM** — When adding a new visual concept, add the token to `HorusStyle.qml` first, then reference it. Don't add ad-hoc `property color` declarations in leaf components. ### `a11y-interactive-elements` **Impact: HIGH** — Every `Button`, `MouseArea` acting as a button, `TextField`, and `ListView` MUST declare: - `Accessible.name` — concise label - `Accessible.role` — correct semantic role - `Accessible.description` — context for screen readers (optional for obvious elements) ```qml Button { Accessible.name: "Stop recording" Accessible.role: Accessible.Button Accessible.description: "Stops the current voice recording" } ``` ### `a11y-keyboard-navigation` **Impact: HIGH** — All primary flows must be operable via keyboard: - `Tab` / `Shift+Tab` for focus cycling - `Enter` / `Return` for activation - `Escape` for dismissal - Arrow keys within lists (`keyNavigationEnabled: true`) - Visible focus indicators (border or glow on `activeFocus`) ### `perf-binding-loops` **Impact: CRITICAL** — Never create circular property bindings. If the QML engine warns `"Binding loop detected"`, it's a hard error. ```qml // ❌ BAD — width depends on child, child depends on parent width width: childItem.implicitWidth + 20 // ... where childItem has: width: parent.width - 40 // ✅ GOOD — break the loop with explicit sizing or implicitWidth implicitWidth: childItem.implicitWidth + 20 ``` ### `perf-delegate-recycling` **Impact: HIGH** — `ListView` and `GridView` delegates MUST be lightweight: - No `Component.onCompleted` with heavy logic - Prefer model role bindings over imperative JS in delegates - Use `cacheBuffer` for off-screen pre-loading - Set `clip: true` on the view ### `perf-layer-effects` **Impact: MEDIUM** — `layer.enabled` and `MultiEffect` force GPU texture allocation. Guard with a condition: ```qml layer.enabled: someCondition // not always-on layer.effect: MultiEffect { shadowEnabled: true // ... } ``` ### `perf-canvas-repaint` **Impact: MEDIUM** — `Canvas.onPaint` is CPU-bound. Minimize repaints: - Only call `requestPaint()` when data actually changes - Avoid repainting on every frame (use a timer or data-change signal) ### `integration-dbus` **Impact: MEDIUM** — Use D-Bus for communication between the QML frontend and Python backend. Follow patterns: - Register well-known names under `org.openclaw.*` - Use `QDBusConnection::sessionBus()` (not system bus) for user-scope services - Expose properties via D-Bus properties interface for external tooling ### `integration-global-shortcuts` **Impact: MEDIUM** — Register global shortcuts via KGlobalAccel, not raw X11/Wayland grabs. This ensures they appear in System Settings and respect user overrides. ### `style-max-600-lines` **Impact: MEDIUM** — QML files over 600 lines should be decomposed: - Extract reusable delegates into separate `.qml` files - Extract complex sub-layouts into components - Keep the design system singleton as a separate file ### `style-signal-naming` **Impact: LOW** — Signal names should be verb phrases: `clicked`, `toggled`, `dataReceived`. Avoid noun-only signals like `data` or `result`. ### `correctness-null-guards` **Impact: HIGH** — Guard against `undefined` / `null` model data in delegates and dynamic property access: ```qml text: model.title || "" visible: (model.items && model.items.length > 0) || false ``` ## Skill-App Pattern Any skill needing a GUI beyond TUI should launch a **KDE app** matching the Tauri app's design system. This creates **agent accountability** — when the agent says "I trained the voice model," a human opens the same skill's GUI and verifies visually. The GUI is the audit surface that prevents hallucination. ### Convention - **Launch via** `./run.sh gui` — every skill with a GUI exposes this command - **Framework:** PySide6 + QML with `EmbryStyle.qml` design tokens (singleton) - **Tab-based navigation** with `tab-registry.json` (matching the Tauri `tab-registry.json` pattern) - **Keyboard shortcuts** per tab (number keys 1-9 switch tabs) - **EmbryParticles** as universal state indicator (header or sidebar) - **Accessible:** all interactive elements have `Accessible.name` + `Accessible.role` - **Agent-invocable:** `./run.sh gui --tab <id>` opens a specific panel for human review - **Two bridges pattern:** skills with multiple concerns register separate QObject bridges (e.g. `editorBridge` + `guiBridge`), each as a named context property — never merge ### File Layout ``` skill-name/ qml/ SkillNameApp.qml # ApplicationWindow with header, tab bar, StackLayout tab-registry.json # Tab config: groups, shortcuts, voice keywords EmbryStyle.qml # Symlink or copy of the shared design system PageOne.qml # Tab content pages PageTwo.qml app.py # Unified launcher (registers bridges, loads App.qml) run.sh # ./run.sh gui, ./run.sh gui --tab <id> ``` ### Shared Mic Pattern When multiple bridges need mic input, **one bridge owns pw-record** and others read from it via `set_mic_source(owner_bridge)`. This avoids duplicate PipeWire readers. ### Reference Implementation See `voice-lab/` for the canonical example: `VoiceLabApp.qml` with 4 tabs across 2 groups, shared mic meter, two coexisting bridges. ## Quick Reference (house rules) - `design-singleton-style` - `design-token-completeness` - `a11y-interactive-elements` - `a11y-keyboard-navigation` - `perf-binding-loops` - `perf-delegate-recycling` - `perf-layer-effects` - `perf-canvas-repaint` - `integration-dbus` - `integration-global-shortcuts` - `style-max-600-lines` - `style-signal-naming` - `correctness-null-guards`