gpui-kit-design-guides

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GPUI Kit Design Guides

GPUI Kit 设计指南

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

本指南对应文件为 references/design-guides.md。它是一项硬性要求，而非灵感参考。在开展UI工作前，请务必阅读指南文件本身。请勿基于本页面、代码库中现有界面或训练数据作答。

若文件缺失，请获取

https://gpui-kit.com/docs/design-guides.md

。本指南是该页面的逐字副本，因此其中指向

./coding-guides.md

的链接指代

gpui-kit

skill中的编码指南（或

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

Section	Read when
Design thesis	Always
Learning from Shadcn	Choosing what to borrow from web component libraries
Start from the task	Always; task hierarchy, interaction promise, what to leave out
Visual language	Color, typography, spacing, radius, borders, elevation, density, icons
Layout patterns	Window structure, sidebars, toolbars, panels, forms, resizable regions
Components and composition	Picking a component, composing parts, when to build a new one
Interaction states	Hover, focus, pressed, selected, disabled, loading, validation, danger
Feedback and overlays	Dialog, sheet, popover, menu, notification, tooltip, dismissal, focus
Motion	Any animation or transition
Designing data-heavy interfaces	Tables, lists, trees, dashboards, dense inspectors
Interface language	Any user-facing text: labels, buttons, titles, errors, empty states
Internationalization and platform fit	Multi-locale copy, Chinese terminology, macOS/Windows conventions
Guidance for AI-generated interfaces	Always when an agent produces UI
Accessibility checklist	Before finishing
Design review checklist	Before finishing; run every item against the work

针对新界面或重新设计场景，请通读完整指南。若仅进行局部修改，请先阅读“设计理念”和“从任务出发”章节，再阅读与修改内容相关的章节。各章节顺序可通过

grep -n '^## ' references/design-guides.md

查看：

章节名称	适用场景
设计理念	所有场景
从Shadcn学习	选择从Web组件库中借鉴哪些内容时
从任务出发	所有场景；任务层级、交互承诺、需省略的内容
视觉语言	颜色、排版、间距、圆角、边框、阴影层级、密度、图标
布局模式	窗口结构、侧边栏、工具栏、面板、表单、可调整大小区域
组件与组合	组件选择、组件组合、何时需构建新组件
交互状态	悬停、聚焦、按下、选中、禁用、加载、验证、危险状态
反馈与覆盖层	对话框、侧边栏弹窗、弹出框、菜单、通知、提示框、关闭、聚焦
动效	任何动画或过渡效果
数据密集型界面设计	表格、列表、树形结构、仪表盘、高密度检查器
界面语言	所有面向用户的文本：标签、按钮、标题、错误提示、空状态文案
国际化与平台适配	多语言文案、中文术语、macOS/Windows平台规范
AI生成界面指导	当Agent生成UI时必须遵循
无障碍检查清单	完成工作前
设计评审检查清单	完成工作前；对照每项内容检查工作成果

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.

这是底线要求，不能替代完整指南。

优先遵循桌面端而非Web端规范：键盘访问、窗口边框、菜单、高密度数据视图、可调整大小区域、持久化导航。
Button
与
Link
的区分：
```
Button
```
用于所有应用内操作命令，如需低调呈现可使用
```
ghost
```
或
```
outline
```
样式。
```
Link
```
仅用于外部URL和电子邮件地址。
优先使用Token而非直接值：禁止使用原始十六进制颜色或
```
rgb(...)
```
；请使用
```
cx.theme()
```
语义化Token和基于rem的辅助工具。指南中提及的任何间距数值均为当前默认比例，并非需直接复用的固定值。
状态必须可见：悬停、聚焦、选中、禁用、加载、验证和破坏性状态均需有清晰、一致的处理方式。
覆盖层规则：按下Esc键可关闭最顶层覆盖层，并将焦点返回至触发它的元素。
文案规则：需明确对象和动作：例如使用“删除「Roadmap」？”搭配
```
Delete
```
按钮，而非“你确定吗？”搭配
```
OK
```
按钮。

完成工作后，请对照设计评审检查清单进行最终检查。