/gpui-kit

name: gpui-kit
description: 'How to build desktop applications with GPUI Kit, the Rust framework published as the gpui-kit crate (GPUI plus gpui_kit::component, gpui_kit::base, gpui_kit::assets). Use when setting up a gpui-kit app, choosing or using a component (Button, Input, Select, Dialog, Sheet, Tabs, Sidebar, List, DataTable, Tree, Chart, etc.), handling component state, theming, or window overlays, and for GPUI mechanics: actions and keybindings, async tasks, contexts, custom elements, entities, events, focus, global state, layout and styling, ElementId, and tests including UI integration testing. Holds the normative Coding Guides: read them before any architecture, state-ownership, public API, naming, or testing decision. Pairs with the gpui-kit-design-guides skill for the Design Guides.'

GPUI Kit

Applications depend on one crate, `gpui-kit`. GPUI is `use gpui_kit::*;`, and each layer is reachable by name: `gpui_kit::component` (styled components), `gpui_kit::base` (unstyled behavior), `gpui_kit::assets` (default icons), `gpui_kit::platform`.

Start with [component-family conventions](references/conventions.md) to choose the constructor, state owner, event, and layout contract for the task. Learn the family once, then verify the specific component supports the capability.

For a complete compiled view with retained state, subscriptions, and overlay layers, read [the tested application recipe](references/recipes.md).

Read the Guides First

Two guides hold the rules this skill assumes. They are requirements, not inspiration. Read the guide file itself; do not answer from this page, from a similar file in the codebase, or from training data.

| Guide | Read before | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | Design Guides, skill `gpui-kit-design-guides` | Choosing components, layout, spacing, hierarchy, color, density, interaction states, overlays, motion, interface copy | | [Coding Guides](references/coding-guides.md) | Crate layering, `RenderOnce` vs `Entity<T>`, state ownership, `ElementId`, events, focus, async, public API, naming, testing |

Read the Design Guides first when the change has a visible surface: code structure preserves product intent, it does not replace it. If the design skill is not installed, fetch `https://gpui-kit.com/docs/design-guides.md`. The coding guide is a verbatim copy of `https://gpui-kit.com/docs/coding-guides.md`, so its links to `./design-guides.md` and `./getting-started.md` mean the design skill and `https://gpui-kit.com/docs/getting-started.md`.

Coding Guides section map

Read the whole guide for a new crate, module, or feature. For a narrow change, read "Architecture at a glance" and "Rules for coding agents" first, then the section for the change (`grep -n '^## ' references/coding-guides.md`).

| Section | Read when | | ------------------------------------ | ---------------------------------------------------------------------- | | Architecture at a glance | Always; crate layering, ownership boundary | | Bootstrap and root ownership | `main`, `init`, `Root`, window creation, app-level state | | Understand GPUI's phases and contexts | Anything touching `App`, `Window`, `Context<T>`, render vs update | | Choose the right unit | Deciding `RenderOnce` vs `Entity<T>` vs custom `Element` | | State ownership | Where a piece of state lives, who mutates it, `Entity<State>` handles | | Stable identity | `ElementId`, lists, repeated elements, keyed state | | Rendering and composition | `render`, builder chains, `when`/`map`, child composition | | Behavior and presentation boundary | `gpui-base` vs `gpui-component` vs application code | | Theme and styling | `cx.theme()`, tokens, `Styled`, sizes, variants | | Events, actions, and focus | `cx.emit`, `subscribe`, `actions!`, keybindings, `FocusHandle` | | Async work and side effects | `cx.spawn`, `background_spawn`, `Task`, I/O, timers | | Layout, measurement, and scrolling | Flex layout, sizing, `overflow`, scroll handles, measuring | | Lists, tables, and large data | `VirtualList`, `List`, `DataTable`, delegates, large collections | | Public API design | Anything `pub`: builders, private fields, setter and reader naming | | Platform and capability boundaries | macOS/Windows/Linux/wasm differences, feature gates | | File and naming conventions | New files, modules, type and method names, `Kind` suffix, `Context` | | Testing strategy | What to test, `#[gpui_kit::test]`, `TestAppContext` | | Performance rules | Render cost, allocation, re-render triggers | | Common failure modes | Before finishing; invented APIs, state in render, index ids | | Rules for coding agents | Always when an agent writes code | | Implementation checklist | Before finishing; run every item against the work |

Non-negotiables

A floor, not a substitute for the guides.

• **Never invent an API.** Search the current source for the real signature.

Do not translate a React, CSS, or older-GPUI example by analogy; a plausible-looking