Claude-skill-registry gpui-patterns

GPUI framework patterns for Script Kit. Use when writing UI code, handling keyboard events, managing state, or working with layouts. Covers layout chains, lists, themes, events, focus, and window management.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/gpui-patterns" ~/.claude/skills/majiayu000-claude-skill-registry-gpui-patterns && rm -rf "$T"

manifest: skills/data/gpui-patterns/SKILL.md

GPUI Patterns

Essential patterns for building UI with GPUI in Script Kit.

Quick Reference (Things That Break Most Often)

Layout chain order: Layout (
```
flex*
```
) → Sizing (
```
w/h
```
) → Spacing (
```
px/gap
```
) → Visual (
```
bg/border
```
)
Lists:
```
uniform_list
```
(fixed height 52px) +
```
UniformListScrollHandle
```
Theme colors: use
```
theme.colors.*
```
(never
```
rgb(0x...)
```
)
Focus colors: use
```
theme.get_colors(is_focused)
```
; re-render on focus change
State updates: after render-affecting changes, must
```
cx.notify()
```
Keyboard: use
```
cx.listener()
```
; coalesce rapid events (20ms)
Arrow keys: match both
```
"up"|"arrowup"
```
,
```
"down"|"arrowdown"
```
, etc.

Keyboard Key Names (CRITICAL)

GPUI often sends short arrow keys on macOS. Always match both:

match key.as_str() {
  "up" | "arrowup" => self.move_up(),
  "down" | "arrowdown" => self.move_down(),
  "left" | "arrowleft" => self.move_left(),
  "right" | "arrowright" => self.move_right(),
  _ => {}
}

Also handle:

"enter"|"Enter"

"escape"|"Escape"

"tab"|"Tab"

Layout System

Chain in order: layout → sizing → spacing → visual → children.

div().flex().flex_row().items_center().gap_2();
div().flex().flex_col().w_full();
div().flex().items_center().justify_center();
div().flex_1(); // fill remaining space

Conditional rendering:

div().when(is_selected, |d| d.bg(selected)).when_some(desc, |d, s| d.child(s));

List Virtualization

Use

uniform_list

with fixed-height rows (~52px):

uniform_list("script-list", filtered.len(), cx.processor(|this, range, _w, _cx| {
  this.render_list_items(range)
}))
.h_full()
.track_scroll(&self.list_scroll_handle);

Scroll to item:

self.list_scroll_handle.scroll_to_item(selected_index, ScrollStrategy::Nearest);

Theme System

let colors = &self.theme.colors;
div().bg(rgb(colors.background.main)).border_color(rgb(colors.ui.border));

Focus-aware:

compute

is_focused = self.focus_handle.is_focused(window)

if changed: update state +
```
cx.notify()
```

use

let colors = self.theme.get_colors(is_focused);

For closures: extract copyable structs like

colors.list_item_colors()

Events + Focus

let focus_handle = cx.focus_handle();
focus_handle.focus(window);

window.on_key_down(cx.listener(|this, e: &KeyDownEvent, window, cx| {
  let key = e.key.as_ref().map(|k| k.as_str()).unwrap_or("");
  match key {
    "up"|"arrowup" => this.move_up(cx),
    "escape"|"Escape" => this.cancel(cx),
    _ => {}
  }
}));

State Management

After any state mutation affecting rendering:

cx.notify()

Shared state:

Arc<Mutex<T>>

or channels; for async, use

mpsc

sender → UI receiver.

References

Anti-Patterns - Common mistakes that cause bugs
Smart Pointers - Arc, Rc, Mutex patterns
Window Management - Multi-monitor, floating panels
Scroll Performance - Rapid-key coalescing
Testing Patterns - GPUI test organization