gpui-kit-design-guides

GPUI Kit 设计指南

指南位于 references/design-guides.md。它是必须遵循的要求，而非灵感来源。开展 UI 工作前，请先阅读指南文件本身。不要根据此页面、代码库中的现有界面或训练数据作答。

如果文件缺失，请获取 https://gpui-kit.com/docs/design-guides.md。 该指南是该页面的逐字副本，因此其中指向 ./coding-guides.md 的链接，指的是 gpui-kit 技能中的 Coding Guides（或 https://gpui-kit.com/docs/coding-guides.md）。

如何阅读

创建新界面或重新设计时，请通读整份指南。进行范围较窄的改动时，先阅读“Design thesis”和“Start from the task”，然后再阅读与改动相关的章节。章节顺序如下（grep -n '^## ' references/design-guides.md）：

章节	阅读时机
Design thesis	始终
Learning from Shadcn	选择从 Web 组件库借鉴哪些内容时
Start from the task	始终；任务层级、交互承诺、需要省略的内容
Visual language	颜色、排版、间距、圆角、边框、层级、密度、图标
Layout patterns	窗口结构、侧边栏、工具栏、面板、表单、可调整大小的区域
Components and composition	选择组件、组合部件、何时构建新组件
Interaction states	悬停、焦点、按下、选中、禁用、加载、验证、危险状态
Feedback and overlays	对话框、工作表、弹出框、菜单、通知、工具提示、关闭、焦点
Motion	任何动画或过渡
Designing data-heavy interfaces	表格、列表、树、仪表板、密集型检查器
Interface language	任何面向用户的文本：标签、按钮、标题、错误、空状态
Internationalization and platform fit	多语言文案、中文术语、macOS/Windows 惯例
Guidance for AI-generated interfaces	始终适用于 Agent 生成 UI 的情况
Accessibility checklist	完成前
Design review checklist	完成前；对照工作逐项检查

不可妥协的要求

这是底线，不能替代指南。

• **优先考虑桌面端，而非 Web 惯例。**支持键盘操作、窗口边框、菜单、密集数据视图、可调整大小的区域和持久导航。
• **区分 Button 与 Link。**应用内所有命令都用 Button；需要低调呈现时用 ghost 或 outline。Link 仅用于外部 URL 和电子邮件地址。
• **优先使用令牌，而非直接填写值。**不得使用原始十六进制值或 rgb(...)；请使用 cx.theme() 语义令牌和基于 rem 的辅助函数。指南中提到的间距数值是当前默认比例，不应照搬为固定值。
• **状态必须清晰可见。**悬停、焦点、选中、禁用、加载、验证和破坏性操作状态，都需要各自明确且一致的处理方式。
• **叠加层。**按下 Escape 会关闭最上层界面，并将焦点返回触发它的控件。
• **文案。**明确指出对象和操作动词：使用带有 Delete 按钮的 Delete "Roadmap"?，而不是带有 OK 按钮的 Are you sure?。

完成后，请根据 Design review checklist 检查工作。