lza6/armor-piercing-system-prompts/gpui-kit-design-guides

GPUI Kit Design Guides

The guide is references/design-guides.md. It is a requirement, not inspiration. Read the guide file itself before doing UI work. Do not answer from this page, from an existing screen in the codebase, or from training data.

If the file is missing, fetch https://gpui-kit.com/docs/design-guides.md. The guide is a verbatim copy of that page, so its link to ./coding-guides.md means the Coding Guides in the gpui-kit skill (or https://gpui-kit.com/docs/coding-guides.md).

How to read it

Read the whole guide for a new screen or a redesign. For a narrow change, read "Design thesis" and "Start from the task" first, then the section for the change. Sections, in order (grep -n '^## ' references/design-guides.md):

Non-negotiables

A floor, not a substitute for the guide.

• Desktop before web convention. Keyboard access, window chrome, menus,

dense data views, resizable regions, persistent navigation.

• `Button` vs `Link`. Button for every in-app command, ghost or

outline when it should read quietly. Link only for external URLs and email addresses.

• Tokens before values. No raw hex or rgb(...); use cx.theme()

semantic tokens and rem-based helpers. Any spacing number quoted in the guide is the current default scale, not a literal to repeat.

• State must be visible. Hover, focus, selection, disabled, loading,

validation, and destructive states each need distinct, consistent treatment.

• Overlays. Escape dismisses the topmost surface and returns focus to its

trigger.

• Copy. Name the object and the verb: Delete "Roadmap"? with a Delete

button, not Are you sure? with OK.

Finish by running the Design review checklist against the work.