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 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.

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.

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).

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 method that does not exist is the most common failure.
• One dependency. Applications depend on gpui-kit alone. GPUI is use gpui_kit::*;; the layers are gpui_kit::component, gpui_kit::base, gpui_kit::assets, gpui_kit::platform.
• Framework owns behavior, application owns presentation. Do not put colors, sizing, or layout in gpui-base; do not put interaction behavior in application styling code.
• Stable identity. Repeated elements need domain-derived ElementIds, not list indexes.
• No pub fields across the seam. Public data types use builders and reader methods.
• Spell Context out. cx is GPUI's; name anything else after what it holds.

Documentation

• Find a task/component page: use https://gpui-kit.com/llms.txt, then load its Markdown page.
• Full reference: https://gpui-kit.com/llms-full.txt is available when broad reference is actually needed
• Per-component API: fetch https://gpui-kit.com/component/{name}.md, e.g. button.md, input.md, select.md, dialog.md, data-table.md
• Any site page can be fetched as Markdown by appending .md to the URL

Quick Reference

Setup and examples: references/usage.md.

use gpui_kit::*;
use gpui_kit::component::Root;

gpui_kit::application()
    .with_assets(gpui_kit::assets::Assets)
    .run(|cx| {
        gpui_kit::init(cx);                       // first, before anything else
        // ... open_window(..., |window, cx| cx.new(|cx| Root::new(view, window, cx)))
    });

• Stateless (RenderOnce): build in render: Button::new("save").primary().label("Save").on_click(|_, _, _| {})
• Stateful: hold Entity<State> in the view, pass a reference in render: let input = cx.new(|cx| InputState::new(window, cx)); then Input::new(&self.input)
• Sizes: .xsmall() .small() .medium() (default) .large()
• Theme: cx.theme().primary · .background · .foreground · .border · .muted
• Overlays: window.open_dialog(...), open_sheet(...), push_notification(...) via gpui_kit::component::WindowExt

Component Catalog

Import paths are relative to gpui_kit::component::, so input::{Input, InputState} means use gpui_kit::component::input::{Input, InputState};. For the full API fetch the component's .md doc.

Input & Form

Display & Feedback

Overlay & Popups

Navigation & Layout

Data Display

Chat & Messaging

Charts

Testing

UI integration testing means rendering real components in headless windows, simulating input, and checking state, focus, layout and owner callbacks. Use #[gpui_kit::test] to run tests and gpui_kit::test to operate and inspect the UI. When asked to add component interaction coverage, describe it as UI integration testing.

For unit tests, GPUI context tests or UI integration tests, read Testing. It includes dependency setup, a complete runnable UI flow, scoped native interactions, frame/async handling and the limits of accessibility and geometry assertions. Use the production view and verify the action's outcome through normal Rust assertions.

GPUI References

Load the file for the mechanism the task touches. Each file starts with a contents line.

Deep dives, for when the topic file is not enough:

• Element trait: element-api.md (complete API, hitbox, events) · element-patterns.md (text, interactive, container, composite) · element-examples.md (full examples) · element-best-practices.md (performance, state, pitfalls) · element-advanced.md (custom layouts, async updates, virtual lists)
• Entities: entity-api.md (complete API, lifecycle) · entity-patterns.md (model-view, cross-entity, observer) · entity-best-practices.md (memory, performance) · entity-advanced.md (collections, registry, debounce, state machines)
• Testing: test-examples.md (organization, setup, assertions, running tests) · test-reference.md (re-entrancy, property tests, mocking)