# Desktop Principles

Desktop-specific UX principles - hover states, pointer precision, keyboard shortcuts...

- Repository: https://github.com/AThevon/genjutsu (721 stars)
- Category: Design
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AThevon/genjutsu --skill desktop-principles -g -a claude-code -y`
Codex: `npx skills add AThevon/genjutsu --skill desktop-principles -g -a codex -y`
Cursor: `npx skills add AThevon/genjutsu --skill desktop-principles -g -a cursor -y`
Gemini CLI: `npx skills add AThevon/genjutsu --skill desktop-principles -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add AThevon/genjutsu`

## Description

Desktop-specific UX principles - hover states, pointer precision, keyboard shortcuts, multi-window, focus management. Covers macOS, Windows, Linux, web desktop.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

> **Version-sensitive.** Every API name, SDK gate and browser-support claim below was
> verified on **2026-09-08** against primary sources. What against, and when, is in
> `_jutsu/VERSIONS.md`. If that date is old, re-verify before acting on a version number.

# Desktop Principles

> Desktop UX context. Loaded when desktop is detected (macOS, Windows, Linux desktop, web desktop).
> Concise rules here. Deep-dive in `references/`.

---

## Hover States Are Mandatory

Hover is the primary affordance signal on desktop, the inverse of mobile. A pointer hovering over a target without immediate visual feedback feels broken: users rely on `:hover` to confirm an element is interactive before committing to a click. Every clickable surface must have a distinct hover style, ideally with a 100-200ms transition so the change is perceptible without feeling sluggish.

**CSS - hover styles for interactive elements:**
```css
.button {
  background: var(--surface);
  transition: background 120ms ease-out, transform 120ms ease-out;
}

.button:hover {
  background: var(--surface-hover);
  transform: translateY(-1px);
}

.button:active {
  transform: translateY(0);
}
```

**SwiftUI - `.onHover` is the portable hover signal; `.hoverEffect` is iOS/iPadOS-only and must be `#if`-gated:**

| Modifier | Availability | Notes |
|---|---|---|
| `.onHover { Bool }` | iOS 13.4+, iPadOS 13.4+, Mac Catalyst 13.4+, macOS 10.15+, visionOS 1.0+ | the one that works on macOS |
| `.onContinuousHover { HoverPhase }` | iOS 17.0+, macOS 14.0+, tvOS 17.0+, visionOS 1.0+ | pointer position, not just in/out |
| `.hoverEffect(_:)` | iOS 13.4+, iPadOS 13.4+, Mac Catalyst 13.4+, tvOS 16.0+, visionOS 1.0+ - **macOS unavailable** | compile error in a macOS target |
| `.pointerStyle(_:)` | macOS 15.0+, visionOS 2.0+ | change the macOS cursor over a view |
```swift
struct ToolbarButton: View {
  @State private var hovering = false

The rest: https://github.com/AThevon/genjutsu/blob/HEAD/skills/_jutsu/desktop-principles/SKILL.md