> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/02-design/ui-style-guide.md).

# UI 风格指南

项目 UI 设计的基准文档。填写完成后，将本文件内容作为 AI 生成 UI 时的上下文注入。

每次风格决策变更，同步更新此文件。

***

## 品牌调性

用一两句话描述产品的视觉性格。这是所有具体规范的出发点，当某个规范细节有争议时，回到这里判断。

> 示例：专业、克制、信息密度高，面向 B 端工具用户，对标 Linear 和 Notion。

**本项目调性**：\_\_\_\_\_

***

## 色彩

### 需要定义的内容

* **主色**：用于主操作按钮、链接、选中态，通常只有一个
* **背景色**：页面底色，通常接近白色或极浅的中性色
* **面板色**：卡片、侧边栏、弹窗的背景，略深于页面背景
* **边框色**：分割线、输入框边框
* **主文字色**：正文、标题
* **次文字色**：辅助说明、占位符
* **禁用色**：不可交互状态的文字和图标
* **语义色**：成功 / 警告 / 错误 / 信息，各一个

### 使用原则

* 颜色通过设计令牌（变量）使用，不在组件里写死色值
* 不使用渐变，除非品牌调性明确要求
* 深色模式是否支持：是 / 否（二选一，不要模糊）

***

## 字体

### 需要定义的内容

* **字体栈**：系统字体还是自定义字体？（系统字体加载最快，是大多数工具产品的选择）
* **尺寸阶梯**：通常 5–6 档，对应标注、辅助、正文、小标题、标题、大标题
* **行高**：每档字号对应的行高比例
* **字重**：正文用几，强调用几，标题用几（控制在 2–3 档以内）

### 使用原则

* 不在正文中混用超过两种字重
* 不用字号大小以外的方式表达层级（避免全大写、斜体层级）
* 字色只用色彩系统中定义的文字色，不单独指定

***

## 间距

### 需要定义的内容

* **基准单位**：4px 还是 8px？（4px 更灵活，8px 更规律）
* **组件内边距**：按钮、输入框、卡片各自的内边距
* **组件间距**：同组内元素的间距
* **区块间距**：不同功能模块之间的间距

### 使用原则

* 所有间距值必须是基准单位的整数倍
* 不使用奇数像素值

***

## 圆角

| 场景      | 圆角值     |
| ------- | ------- |
| 按钮      | \_\_\_  |
| 输入框     | \_\_\_  |
| 卡片      | \_\_\_  |
| 弹窗 / 抽屉 | \_\_\_  |
| 头像 / 徽标 | 50%（全圆） |

**调性说明**：圆角越大越柔和，越小越专业。同一产品圆角变化最好不超过 3 档。

***

## 阴影与层级

层级关系优先用边框和背景色差表达，阴影仅用于浮层（下拉菜单、Tooltip、弹窗）。

| 层级                     | 表达方式        |
| ---------------------- | ----------- |
| 普通内容                   | 无阴影，用边框区分边界 |
| 浮层（Dropdown / Tooltip） | \_\_\_      |
| 模态框                    | \_\_\_      |

***

## 图标

* **图标库**：\_\_\_\_\_（统一一套，不混用）
* **默认尺寸**：\_\_\_\_\_
* **颜色**：继承父元素文字色，不单独设置

***

## 组件状态

所有可交互组件必须明确以下状态的视觉表达：

| 状态       | 表达方式   |
| -------- | ------ |
| 默认       | \_\_\_ |
| 悬停       | \_\_\_ |
| 激活（按下）   | \_\_\_ |
| 聚焦（键盘导航） | \_\_\_ |
| 禁用       | \_\_\_ |
| 加载中      | \_\_\_ |

聚焦态是无障碍的必要项，不能省略。

***

## 动效

* **过渡时长**：\_\_\_（通常 100–200ms）
* **缓动**：\_\_\_（ease-out 适合大多数场景）
* **使用场景**：仅用于状态切换的视觉反馈
* **不使用场景**：页面加载入场、数据列表、滚动

***

## 给 AI 使用的说明

将本文件填写完整后，每次让 AI 生成 UI 时，在提示开头附上本文件内容，并加：

> 严格遵循上方风格规范。如需使用规范未涵盖的样式，先说明原因再给出代码。

具体的提示模板见 `04-prompt/design/ai-design-prompt.md`。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/02-design/ui-style-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.