aprilnea/gpui-skills

Overview

This skill captures GPUI UI framework best practices for building robust desktop applications. It condenses 40+ prioritized rules across core concepts, rendering, state, events, async, styling, components, and anti-patterns into a practical reference. Use it to speed development, avoid common pitfalls, and ensure consistent, maintainable GPUI code.

How this skill works

The skill inspects common GPUI patterns and prescribes clear, actionable rules for component design, state management, event handling, async tasks, styling, and testing. Each rule highlights the problem, shows incorrect and correct approaches, and recommends concrete APIs (Entity, Context, Render/RenderOnce, WeakEntity, background_spawn, cx.notify(), etc.). Follow the rules while writing views, components, or background tasks to reduce bugs and improve UX.

When to use it

• Writing new GPUI views or composing elements with div(), h_flex(), v_flex()
• Implementing state with Entity, Global, or keyed window state
• Handling keyboard shortcuts, focus, or bubbling event propagation
• Managing async work, debounced tasks, or CPU-bound background jobs
• Building forms, lists, dialogs, animated components, or focusable controls
• Writing tests and avoiding runtime issues like dropped tasks or silent errors

Best practices

• Respect GPUI ownership: App is the single owner; use Context<T> and Entity APIs correctly
• Always call cx.notify() after mutating state and prefer cx.observe()/subscribe() for reactions
• Choose Render for stateful components and RenderOnce (IntoElement) for simple stateless widgets
• Use WeakEntity to break reference cycles and to safely access Entities across await points
• Never drop Task or Subscription without storing or detaching; log or propagate errors instead of silencing them
• Use theme, spacing, and elevation helpers for consistent styling; prefer traits for reusable component behavior

Example use cases

• A settings panel using Entity-backed state, keyed window state, and cx.observe() to update live previews
• A file list with virtualization, builder-pattern components, and conditional rendering via .when()
• A command palette with registered actions, keyboard shortcuts, FocusHandle, and proper event.stop_propagation()
• Offloading syntax parsing to background_spawn with WeakEntity access and detach_and_log_err() for resilience
• A dialog system using WindowExt, variant enums for styles, and focus rings for accessibility