native-feel-cross-platform-desktop
Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/yetone-native-feel-skill)HTML
<a href="/listings/yetone-native-feel-skill"><img src="/api/listings/yetone-native-feel-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 45 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: native-feel-cross-platform-desktop
- description: Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.
- ---
- # Native-Feel Cross-Platform Desktop
- You are advising on the architecture of a cross-platform desktop app that must *feel native*. This skill captures the philosophy, architecture, and concrete pitfalls — distilled from Raycast's public technical deep-dive on their 2.0 rewrite and verified by reverse-engineering the shipping `Raycast Beta.app` binary on macOS.
- ## How to use this skill
- 1. **Start with the philosophy in `references/01-philosophy.md`.** It frames the central tension this architecture resolves — *how to get cross-platform DX and near-native performance at the same time* — and gives you eight tenets that name the structural moves. Every concrete decision later flows from one of those tenets. If the user is making a decision that contradicts a tenet, surface the tenet by number and short name and explain the trade-off.
- 2. **Match the user's question to a reference file.** Don't dump the whole skill — load only what's needed:
- - Architecture / "which layers should I have?" → `references/02-architecture.md`
- - "Why does my WebView flicker / stutter / freeze when hidden?" → `references/03-webview-survival.md` (the highest-density file — every item is a real bug with a real fix)
- - "How do I type my IPC across Rust/Swift/C#/TS?" → `references/04-ipc-contract.md`
- - "Why does Activity Monitor say 400 MB?" → `references/05-memory-truths.md`
- - "How do I make it not feel like a webpage?" → `references/06-native-conventions.md`
- - "What does Raycast actually ship?" (concrete evidence) → `references/07-evidence-raycast.md`
- 3. **Before recommending an architecture, run the decision tree in `checklists/decision-tree.md`.** It rules this stack OUT for several common project shapes — say so directly.
- 4. **Before the user claims their app "feels native", run `checklists/ship-readiness.md`.** It's a 30-item audit; most apps fail 5–10 items on first pass.
- ## The one-paragraph version
- A native-feel cross-platform desktop app is **not a web app with native hooks** and **not Electron with a custom theme**. It is a **native shell** (Swift/AppKit on macOS, C#/WPF on Windows) that owns the window, the hotkeys, the menu bar, the materials, and the lifecycle — and embeds the system WebView (WKWebView or WebView2) purely as a *rendering surface* for a shared React/TypeScript UI. Business logic lives in a long-lived Node process bundled with the app. Performance-critical subsystems (file indexing, calculation, crypto) live in Rust, shared across platforms and exposed through UniFFI-generated typed bindings. Four runtimes communicate through a single declared interface that generates typed clients for each side. The whole thing fits in ~400 MB resident memory, of which ~150 MB is the inescapable WebView+Node baseline. You pay that baseline so that one React codebase serves both OSes; you earn it back through hot-reload iteration speed and a shared extension API that already runs thousands of community plugins on both platforms.
- ## Core anti-patterns to call out immediately
- When you see the user doing any of these, stop and ask:
- - **"Let's just use Electron and theme it"** → Electron abstracts away the system WebView, window class, and material APIs you need for native feel. You cannot get Liquid Glass / acrylic / true vibrancy through Electron's abstraction without forking it. Recommend `references/02-architecture.md` instead.
- - **"Let's use Tauri — it's like Electron but lighter"** → Tauri ships its own WebView wrapper and abstracts platform APIs. Same control-loss problem as Electron, plus less mature. Acceptable for utilities; not for apps where every window animation has to match the OS.
- - **"Let's render UI in Swift/C# and share business logic"** → You will maintain two UI codebases forever. Every feature ships twice. Designers maintain two specs. Recommend WebView-as-renderer instead.
- - **"WebKit is throttling us; let's spin our own polling loop"** → No. The throttling is solvable with two specific `WKWebView` configuration flags. See `references/03-webview-survival.md` § "Hidden window throttling".
- - **"Memory is bad — we're at 400 MB"** → Probably wrong measurement. Activity Monitor double-counts shared frameworks and treats compressed pages as resident. See `references/05-memory-truths.md` before optimizing anything.
- - **"Let's hand-write the IPC types in each language"** → They will drift within a sprint. Use UniFFI (for Rust ↔ Swift/Kotlin/C#) or hand-roll a single IDL that generates clients. See `references/04-ipc-contract.md`.
- - **"Adding `cursor: pointer` to make it feel responsive"** → That's exactly what makes it feel *web*. Native UIs do not change the cursor on hoverable rows. See `references/06-native-conventions.md`.
- ## Output style
- When advising:
- - Quote the specific tenet from `references/01-philosophy.md` that applies (e.g., *"T3 — adopt the platform; don't compete with it: the OS draws blur better than you can"*).
- - Cite the file and section, not the whole skill.
- - For each recommendation, name what the user is **giving up** in exchange. There are no free wins in this architecture — the whole skill is about deliberate trade-offs.
- - If you're unsure whether the user's project should even use this architecture, run them through `checklists/decision-tree.md` before giving advice. It is okay to conclude "this skill doesn't apply — build a normal Electron app."
README.md · README · 207 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # native-feel.skill
- > *"Cross-platform development AND near-native performance — refuse the trade-off."*
- [](LICENSE)
- [](https://github.com/yetone/native-feel-skill)
- <br>
- **An Agent Skill for designing cross-platform desktop apps that feel native** — distilled from Raycast's 2.0 technical deep-dive and grounded in reverse-engineering of the shipping `Raycast Beta.app` binary.
- Two goals usually pull against each other: convenient cross-platform development, and near-native performance. This skill captures the structural choices — eight architectural tenets, a four-layer architecture, a WebKit/WebView2 survival guide, a 75-item ship audit — that let an app have both.
- <br>
- **Install** — pick one:
- </div>
- **A. With [`skills`](https://github.com/vercel-labs/skills) (any compatible agent):**
- ```bash
- npx skills add yetone/native-feel-skill -g
- ```
- The `-g` flag installs globally (user-level) so every project picks it up.
- **B. Or paste this prompt to your AI agent:**
- ```
- Install the native-feel skill for me:
- 1. Clone https://github.com/yetone/native-feel-skill into your
- user-level skills directory as `native-feel-cross-platform-desktop/`
- (whatever path your agent reads skills from on this machine — e.g.
- `~/.claude/skills/` for Claude Code).
- 2. Verify that SKILL.md plus the references/ and checklists/ subdirs
- are present.
- 3. Confirm the install path when done.
- ```
- <div align="center">
- [Use cases](#use-cases) · [What this is](#what-this-is) · [Philosophy](#philosophy) · [Layout](#layout) · [Sources](#sources)
- </div>
- ---
- ## Use cases
- Once installed, the skill activates automatically whenever the conversation touches cross-platform desktop architecture, WebView quirks, or making a UI feel native. Two common ways to use it:
- ### Case 1 — Refactor an existing app to feel more native
- You have an Electron / Tauri / web-wrapped app, and a designer (or your own eye) tells you it feels web-y. You want to know where to start and how far you can take it without a full rewrite.
- ```
- You ❯ My Electron app feels web-y on macOS — the designer says it
- doesn't pass for a real Mac app. Where do I start?
- Agent ❯ Quickest path is the 75-item native-feel audit
- (checklists/ship-readiness.md). Most Electron apps fail
- the same 6–8 items:
- - cursor:pointer on rows (item 21)
- - web-style modal overlays instead of native sheets (19)
- - hardcoded brand accent instead of system accent (33)
- - page fade-transitions (40)
- - opaque window background instead of platform material (31)
- - WebKit context menu still firing (23)
- Each is a 5-to-30-minute fix; together they move you most
- of the way to "passes the 30-second skeptical user test."
- Bigger question first: how far do you need to go? If "good
- enough" means passing that 30-second test, Electron + this
- audit gets you 80% there without rewriting. If you want
- "indistinguishable from a Mac app" — Liquid Glass materials,
- native popovers, sub-200ms launch — Electron has a ceiling
- you'll hit. Want me to run the decision tree first?
- ```
- ### Case 2 — Build a cross-platform native-feel app from scratch
- Greenfield project, must run on macOS + Windows, and the native feel is the *point* — a launcher, a productivity tool, an AI workspace your users live in all day.
- ```
- You ❯ Starting a new desktop app — macOS + Windows, native feel
- is the whole pitch. What architecture should I use?
- Agent ❯ Before architecture, the decision tree
- (checklists/decision-tree.md) rules this stack out for
- several common shapes — quick check first:
- - Cold-start budget? (<100ms → build native instead)
- - Memory floor? (<150MB → build native instead)
- - Extension ecosystem? (yes → need the Node layer)
- - Runway? (<3mo → start on Electron)
- If you pass, the four-layer architecture is:
- ┌──────────────────────────────────────────────────┐
- │ Native shell Swift/AppKit + C#/WPF │
- │ ↕ one IPC schema, codegen for all sides │
- │ System WebView WKWebView + WebView2 │
- │ running React + TypeScript, shared 1:1 │
- │ ↕ │
- │ Node backend single long-lived process │
- │ ↕ │
- │ Rust core UniFFI-bridged, sharable │
- │ with iOS and server │
- └──────────────────────────────────────────────────┘
- The expensive-to-get-wrong decisions, in order:
- 1. The IPC contract (one schema, codegen). Get this wrong
- and you rebuild it later under duress.
- 2. WebView survival flags (occlusion off, alpha-prewarm,
- _doAfterNextPresentationUpdate, font prewarming).
- 3. Memory hygiene (lazy-load extensions, tear down
- secondary windows aggressively).
- Want to start with the seam — where to draw the cross-
- platform line — or with the IPC contract, since getting
- that schema wrong means rebuilding every bridge later?
- ```
- ### Other things the skill is good for
- - **"Why is my WKWebView flickering when I hide and re-show it?"** → walks you through `references/03-webview-survival.md` (most likely A.1 throttling or A.2 startup flicker).
- - **"How should typed IPC work across Rust, Swift, and TypeScript?"** → the UniFFI-based pattern in `references/04-ipc-contract.md`, with the exact `Coordinator`/`EventHandler` shape Raycast Beta ships.
- - **"My app is at 450 MB resident, is that bad?"** → the six common Activity-Monitor mistakes and what to actually measure, in `references/05-memory-truths.md`.
- - **"Is my designer's spec ‘native enough’?"** → the 70+ item conventions audit in `references/06-native-conventions.md`.
- ---
- > *"We're not a web app with some native hooks sprinkled on top. We're a native app that uses web for its UI."* — Raycast
- ## What this is
- A reference for architects, tech leads, and engineers who must build a desktop app that:
- - runs on **macOS + Windows** (optionally Linux) from a single UI codebase,
- - launches in under 500 ms and stays under 500 MB resident,
- - is **indistinguishable from a native app** to its users (no `cursor: pointer` tell-tales, no white-flash on launch, no WebKit context menu, no smooth-scroll JS),
- - supports a **plugin/extension ecosystem** in TypeScript,
- - can share performance-critical code with iOS and a server backend.
- This is the four-layer architecture: **native shell → system WebView (WKWebView/WebView2) → Node backend → Rust core**, wired together with a single typed IPC schema that generates clients for every runtime.
- ## What this is not
- - Not for single-OS apps (just build native).
- - Not for Electron-style "good enough" apps (the polish budget here is 5–10× higher).
- - Not for apps with strict <150 MB or <100 ms cold-start budgets (the floor is real).
- - Not for games, document editors, or media players.
- Run [`checklists/decision-tree.md`](checklists/decision-tree.md) to find out if this architecture is even right for your project. It rules itself out for several common cases — saying so directly is more useful than over-fitting advice.
- ## Layout
- ```
- native-feel-skill/
- ├── SKILL.md # entry point for the agent
- ├── references/
- │ ├── 01-philosophy.md # 8 tenets that drive every decision
- │ ├── 02-architecture.md # the four-layer architecture
- │ ├── 03-webview-survival.md # WebKit/WebView2 quirks + fixes (the goldmine)
- │ ├── 04-ipc-contract.md # typed IPC across Rust/Swift/C#/TS
- │ ├── 05-memory-truths.md # why Activity Monitor lies
- │ ├── 06-native-conventions.md # 70+ items the native-feel audit checks
- │ └── 07-evidence-raycast.md # what a reverse-eng. of Raycast Beta shows
- └── checklists/
- ├── decision-tree.md # should you use this architecture?
- └── ship-readiness.md # 75-item launch audit
- ```
- ## Philosophy
- The central tension this architecture resolves: **how can a desktop app deliver convenient cross-platform development AND near-native performance, when those goals usually pull against each other?** Eight tenets name the structural moves:
- 1. **Place the seam at the rendering surface** — share above the WebView, diverge below it; this is the only altitude where both DX and native feel survive.
- 2. **One schema, many languages** — pay the polyglot tax once at the declaration, never at the call site.
- 3. **Adopt the platform; don't compete with it** — the OS draws blur, scrolling, materials, and dark mode better than you can.
- 4. **Performance is a property of perception** — what the user feels, not what Activity Monitor reports.
- 5. **The short iteration loop is the product** — 200 ms hot reload vs 30 s native rebuild is a 150× compounding advantage.
- 6. **Cross boundaries intentionally** — IPC has a cost; design every crossing as async, batched, schema-typed.
- 7. **Identity is muscle memory** — the hotkey, the rank order, the verbs are the app; everything else is implementation.
- 8. **Separate baseline from margin** — the WebView+Node floor is rented; only your dirty pages are yours to optimize.
- Read [`references/01-philosophy.md`](references/01-philosophy.md) first. Everything else is consequence.
- ## About Agent Skills
- Agent Skills are the emerging standard for packaging domain knowledge that any compatible agent (Claude Code, the Claude Agent SDK, or other Agent-Skill-aware runtimes) can discover and load. Once installed via the prompt at the top of this README, the skill activates automatically when the agent's conversation touches cross-platform desktop architecture, WebView quirks, or Raycast-style apps — the trigger conditions are declared in `SKILL.md`'s frontmatter.
- ## Sources
- - Raycast's public technical post: [A Technical Deep Dive into the New Raycast](https://www.raycast.com/blog/a-technical-deep-dive-into-the-new-raycast)
- - Reverse engineering of `Raycast Beta.app` v0.60.0 (macOS 26+ build, Xcode 17, arm64) — see [`references/07-evidence-raycast.md`](references/07-evidence-raycast.md) for what was found and how.
- ## License
- MIT — see [`LICENSE`](LICENSE).
- ## Credits
- Authored as an Agent Skill. The architecture this skill describes is Raycast's; the philosophy is the author's synthesis; the evidence is from the shipping app.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.