desktop-visual-design

Desktop Visual Design

Build system-native desktop interfaces from the visual rules already present in the user's environment. Inspect the target first, turn repeated values into semantic tokens, reuse host components, and verify the result across interaction states and theme changes. When the target has no visual contract, use the restrained terminal-first fallback defined here rather than inventing a glossy web-app style.

Installing this Pi package makes the skill available to Pi. It does not modify desktop settings, themes, or application code by itself.

When to use

Trigger for:

• Quickshell widgets, panels, bars, popups, overlays, launchers, and notifications.
• Desktop apps built with QML, Qt, GTK, Tauri, Electron, or embedded web views.
• UI reviews focused on palette, hierarchy, spacing, typography, borders, geometry, focus states, and motion.
• Requests to make a desktop interface match an existing system theme or first-party surface.

Do not trigger for server-side work, CLI output formatting, compositor configuration unrelated to application appearance, or general public-website design without a desktop-integration requirement.

Principles

1. Inspect before styling. Existing theme files, token objects, shared controls, and first-party surfaces are the source of truth.
2. Honor the active color scheme. Standalone apps must read the toolkit, portal, or host-shell light or dark preference before choosing a built-in palette. For Linux Qt apps, prefer an explicit XDG portal result at startup because Qt platform-theme environment can differ between launchers; use Qt style hints as the fallback and live-change input. Automatic mode must update when its authoritative preference changes.
3. Use semantic roles. Components depend on foreground, background, accent, urgent, muted, and named surface roles instead of literal palette colors.
4. Define every interaction state. Cover idle, hover, keyboard cursor, focus, selected, pressed, disabled, and urgent states where they apply.
5. Keep geometry stable. Reserve border and focus-ring space so interaction never shifts layout.
6. Use one scale. Derive spacing and typography from named tokens and a documented base size.
7. Retheme through one path. Parse, validate, and publish an atomic theme snapshot. Theme changes must not leave mixed old and new values on screen.
8. Match existing motion. Honor the target's motion language and reduced-motion settings. When no motion language exists, animate only short color or opacity changes.
9. Restrain decoration. Without an explicit reference, prefer opaque flat surfaces, one accent family, thin borders, square geometry, and no gradients, glow, blur, hover lift, or decorative shadows.
10. Compare relationships, not sampled pixels. A screenshot can establish palette relationships, hierarchy, composition, framing, type treatment, landmarks, and state language. It does not override project tokens with guessed colors or justify forcing its apparent color scheme.