# NativeDesktop

NativeDesktop is a toolkit for desktop apps written in Rust. You describe a window as a tree of
views and elements; each platform's backend turns that tree into what the OS draws for itself.

> **Example: Hello.** Source in [examples/hello](https://github.com/FormalSnake/NativeDesktop/blob/main/examples/hello). Live on the web and captured on macOS, Linux and Windows in the docs app.


The counter above is the whole of [hello](https://github.com/FormalSnake/NativeDesktop/blob/main/examples/hello/src/lib.rs): one struct, one
`render`, one button. The same code runs on every target:

- macOS: AppKit. The toolbar is an `NSToolbar`, the button an `NSButton`, a list an `NSTableView`.
  The framework adds layout (Taffy) and a retained tree on top of them.
- Linux: GPUI draws the tree with a libadwaita look. Colours come from the theme tokens and, when
  present, a matugen palette that reloads while the app runs.
- Windows: the same GPUI backend with a Fluent skin. The code is written and has not run on a
  Windows machine yet.
- Web: plain GPUI compiled to WebAssembly. `nd serve --target web` serves an app unchanged.

An app never names a backend. `scaffold()`, `toolbar()` and `button()` say what the window is, and
the backend decides how that looks on its OS. Where a platform has no native version of something,
the framework draws it from the same theme tokens.

## Built for agents

The framework is shaped so that a coding agent produces a good app on the first pass and can prove
it works. `nd new` writes a project with a `CLAUDE.md`, a tier 1 test and an appearance audit.
`nd check` fails on literal colours, text under WCAG contrast, `unwrap` and framework lints, and
`nd test` runs the same view with no window. The [agent pages](https://nativedesktop.formalsnake.dev/agents/index.md) list the patterns
to copy and the mistakes to avoid. People use the same pages; nothing in them is agent-only.

## Where to go next

1. [Getting started](https://nativedesktop.formalsnake.dev/getting-started.md): install the `nd` CLI, create an app, run it, test it.
2. [Programming model](https://nativedesktop.formalsnake.dev/concepts/programming-model.md): views, entities and the retained tree.
3. [Elements](https://nativedesktop.formalsnake.dev/concepts/elements.md), [state](https://nativedesktop.formalsnake.dev/concepts/state.md) and
   [actions and keys](https://nativedesktop.formalsnake.dev/concepts/actions-and-keys.md): the vocabulary you write every day.
4. [Components](https://nativedesktop.formalsnake.dev/components/index.md) and the [examples](https://nativedesktop.formalsnake.dev/examples.md): what ships and how it looks.