simply-ehis Desktop UI Foundations
This is the entry point for a family of skills that design and review desktop application interfaces — not websites, not mobile apps. Read this one first. It sets the philosophy and the shared vocabulary (tokens) that every other skill in the family builds on:
desktop-ui-buttons-controls · desktop-ui-icons · desktop-ui-color-system · desktop-ui-layout-navigation · desktop-ui-surfaces-overlays · desktop-ui-spacing-sizing · desktop-ui-motion · desktop-ui-text-inputs · desktop-ui-feedback-messaging · desktop-ui-scrolling-navigation · desktop-ui-panels-boards · desktop-ui-grids-layout · desktop-ui-style-direction · desktop-ui-domain-components · desktop-ui-ai-workspaces · desktop-ui-coding-workspaces · desktop-ui-settings-layout · desktop-ui-export-import · desktop-installer-design · desktop-ui-accessibility-i18n
This family is inspired by the general shape of community "design taste" skills (e.g. the publicly shared, MIT-licensed emilkowalski/skills collection for web UI/motion), but rewritten from scratch for desktop software specifically: real windows, real title bars, resizable viewports, keyboard-first power users, and hardware that isn't always a $3,000 MacBook. Nothing here is copied from any source — it's an original set of desktop-specific rules.
Why this exists
Two failure modes, and this skill family exists to kill both at once:
- Looks AI-generated. Recognizable, generic, could be any of a thousand other "vibe-coded" apps. This is the bigger risk right now — most AI-assisted UI converges on the same handful of patterns because it's the path of least resistance for a model to take.
- Looks bad on its own merits. Cramped, inconsistent, no hierarchy, breaks when the window resizes, ignores platform conventions.
Fixing #2 alone isn't enough — you can build something clean and still have it read as generic AI output because of a few unmistakable tells. Fixing #1 alone isn't enough either — you can avoid every AI cliché and still ship something ugly. Every skill in this family checks for both.
Core philosophy
Taste is a checklist you can learn, not a gift you either have or don't. Every rule below exists because it's been observed, over and over, to separate software that feels considered from software that feels assembled. Apply them mechanically until they become instinct.
Unseen details compound. No single spacing value, easing curve, or icon choice will make or break an app. But get twenty small decisions right and the whole thing reads as "someone cared." Get twenty wrong — even ones a user could never individually name — and it reads as "thrown together," even if they can't say why.
Constraints are part of the brief, not an excuse to skip taste. Establish the product's actual constraints — including offline use, modest hardware, security posture, accessibility, localization, and platform conventions — before choosing effects. Cheap-to-render solid surfaces and transform/opacity animation often make a calmer, more credible product than blur-heavy glass, animated gradient meshes, or decorative particles.
A desktop app is not a landing page in a window. It's used for hours at a time by someone who wants information density, keyboard access, and predictability more than they want marketing-site delight. Design for the 500th use, not the first screenshot.
The anti-AI-slop checklist
Run every screen against this before calling it done. Each of these, individually, is a fast way for a trained eye (or another AI) to clock a UI as generated rather than designed.
| Tell | What it looks like | Do this instead |
|---|---|---|
| The gradient | Purple-to-pink or blue-to-violet gradient background/hero/button, "AI startup" gradient text on headings | Solid, deliberate brand color. If you use a gradient, make it subtle (two adjacent hues, low-contrast) and use it in exactly one place, on purpose |
| Card soup | Every piece of content in a rounded-2xl card with a soft drop shadow, no distinction between primary and secondary surfaces |
Use surface hierarchy (see desktop-ui-color-system) — flat background for most content, elevation reserved for things that are actually floating above it |
| Glass-everywhere | backdrop-blur on every panel "for depth," frosted glass on non-glass platforms |
Reserve blur for true overlays (menus, popovers) that sit above content; use it sparingly and cheaply (see desktop-ui-motion performance section) |
| Icon-in-tinted-square | Identical rounded-square-with-tinted-background icon wrapper repeated for every feature/list item | Vary icon treatment by actual meaning; don't apply a template to every row just because it fills space |
| Unconsidered default iconography | A mismatched stock icon set repeated without adapting its stroke, optical size, or platform context | See desktop-ui-icons — choose and normalize an icon system that fits the product instead of letting a library dictate its visual identity |
| Emoji as icon | 🚀 ✨ 🎉 used as functional icons or heading decoration | Real icons or none. Emoji render inconsistently across OS/fonts and read as unserious in a tool |
| Fake centering | Every screen is a single centered column with a huge CTA button and generic subtext ("Welcome to [App] — the best way to [thing]") | Desktop layouts should use the width they have — sidebars, multi-pane layouts, information density appropriate to the task |
| Uniform button weight | Every button the same size, color, and visual weight, no primary/secondary/tertiary distinction | Establish a clear hierarchy (see desktop-ui-buttons-controls) |
| Happy-path only | No empty state, no error state, no loading state — only the "everything worked" screenshot exists | Design all four states for every view that can have them (see desktop-ui-feedback-messaging) |
| Browser-in-a-box | Native-looking browser scrollbars, default browser focus rings, no integration with the OS window chrome, hamburger menu instead of a real menu bar | See desktop-ui-layout-navigation and desktop-ui-scrolling-navigation for window-chrome and scroll-styling rules |
| One weight, one size | All text the same font-weight and barely-differentiated size, no real typographic hierarchy | Establish at minimum 4 distinct text roles (see spacing/sizing skill) with real weight and size contrast |
| Isometric blob decoration | Abstract gradient blobs or generic 3D-render illustrations with no relationship to what the app does | Skip decoration that doesn't carry meaning. If you need visual interest, use the product's own content or a motif tied to the brand |
| Breaks under high contrast | Focus rings, borders, or state indicators vanish entirely when Windows High Contrast or macOS Increase Contrast is turned on | Test with the OS setting on; never let an important boundary depend on a subtle color alone (see desktop-ui-accessibility-i18n) |
| No room to translate | Buttons and labels sized to fit the English string exactly; hardcoded date/number formats | Build headroom into labels for 30–40% text expansion; use locale-aware formatting APIs (see desktop-ui-accessibility-i18n) |
If a screen trips three or more of these, stop and redo it before moving on to polish.
Design tokens (shared vocabulary)
Every other skill in this family refers back to these. Define them once per app (as CSS custom properties, a theme file, or your engine's equivalent) rather than hardcoding values inline.
Spacing scale (4px base unit — use multiples of it, nothing in between):
2, 4, 8, 12, 16, 24, 32, 48, 64 px
Radius scale (pick 3, not 8):
sm: 4px (inputs, small controls) · md: 8px (buttons, cards) · lg: 12px (modals, large panels). Avoid rounded-2xl/rounded-3xl (16px+) as a default — heavy rounding on everything is one of the fastest ways to look like a template.
Elevation scale (3 levels, via shadow + optional subtle border, never blur alone):
raised (buttons, inputs at rest) · floating (dropdowns, tooltips, popovers) · modal (dialogs, command palettes). Each level should be achievable with a cheap box-shadow — no real-time blur required.
Type scale (minimum 4 roles, real contrast between them):
display (rare, section-defining) · heading · body · caption/label. Jump ratio between adjacent roles should be at least 1.25×, ideally closer to 1.4–1.5× — a heading that's barely bigger than body text reads as an oversight, not a choice.
Motion tokens: see desktop-ui-motion for the full duration/easing scale — it's large enough to need its own skill.
Platform awareness
Before designing anything, know which of these you're building for, because the right answer changes:
- Cross-platform custom-chrome app (Electron/Tauri with a fully custom title bar): you own 100% of the visual language, but you still owe the user standard window behaviors — drag region on the title bar, working minimize/maximize/close, correct traffic-light or Win-caption-button placement per OS, resize handles on every edge.
- Native-feeling per-platform app: follow the host platform's own conventions (menu bar location, keyboard shortcut idioms, native context menus) rather than importing patterns from the other OS.
- Game-engine desktop app (e.g. Godot standalone): the token system above still applies conceptually (spacing, color roles, elevation, type scale) even though the implementation is scene/theme-resource based rather than CSS.
Never let an app read as "a website that got wrapped in a desktop shell." That's the single most common way desktop apps fail this whole checklist at once.
Accessibility and internationalization are part of the craft floor
They're not a compliance pass bolted on at the end. A UI that can't be operated by keyboard, doesn't survive the OS's high-contrast mode, or breaks the moment a label gets translated isn't finished — it's a screenshot that only works for one user, one input method, one language. Read desktop-ui-accessibility-i18n alongside this skill on any real project, not just when someone explicitly asks for an accessibility review.
How to use this skill family on a real project
- Brand-new app or major redesign? Read
desktop-ui-style-directionfirst, before this section's tokens get filled with specific values — decide the app's own personality before locking in a palette. - Start here for philosophy and tokens, and read
desktop-ui-accessibility-i18nalongside it — treat both as the shared baseline, not optional extras. - Pull in the specific area skill(s) that match the task (a button review only needs
desktop-ui-buttons-controls; a full pass touches most of them). SeeREADME.mdat the root of this skill package for a one-line index of what each skill covers. - Run the anti-AI-slop checklist above against the result before calling anything finished.
- When reviewing existing UI (not building new), use the Before/After/Why table format from each sub-skill so the reasoning is explicit and the fix is concrete, not just "make it nicer."