DESIGN.md git:20260511.209c652A

Immutable. This exact content is served forever at /api/v1/blob/338bc671e0bd689e.

# xopc · Design Language

## 1. Visual theme & atmosphere

xopc 是长时间驻留的 **AI 助手与工作台**：CLI、HTTP/SSE 网关（REST + Server-Sent Events），以及 **React Gateway 控制台**。界面气质 **克制、清晰、以内容为中心**——不是营销页，而是可持续使用的工具面。

**核心取向**：每一个像素都应为「用户任务与内容」服务；装饰不抢逻辑，信息不淹操作。工具型界面同样追求 **受控的留白与层级**：密的地方足够密（列表、工具栏），疏的地方足够疏（阅读区、空状态）。

**视觉原则**

- **中性色占绝对主导**：大面积浅灰分组底或深灰阶梯面，主文字与背景对比清晰（浅模式常见 `#1d1d1f` 与 `#f5f5f7` 阶），避免彩虹式界面。
- **单一彩色强调**：蓝色代表「可行动 / 智能 / 主操作」，其余状态用低饱和语义色点到为止。
- **标题紧、正文舒**：标题层级偏紧行高与 `tracking-tight`，正文与系统级 UI 行高保持长时间阅读舒适。
- **阴影克制**：层级主要靠 **表面色阶** 与 **细边框**；深色模式下 **rim light**（边缘高光感）往往比重阴影更有效。

**品牌气质：Calm Intelligence（沉静智能）**

- 界面是背景，用户的思路是主角；AI 在需要时准确出现，不需要时不抢戏。
- **优雅、智能、克制** —— 少即是多。明确拒绝：炫彩、炫动效、信息堆满、强迫复杂操作。

**关键特征（便于对齐实现）**

- 系统无衬线栈 + 系统等宽栈；大标题 `tracking-tight`，正文与 UI 字阶分离清晰。
- 浅 / 深两套表面阶梯 + 单一蓝色强调（`accent`）；语义色仅表状态。
- 应用壳靠 **色块分区**；卡片、列表、输入框用 **细边框** 编组，而非大块竖线切屏。
- 圆角偏有机；阴影种类少、对比低；深色以 **边线 + 表面差** 为主。
- 动效短、可打断；尊重 `prefers-reduced-motion`。
- 图标统一 Lucide outline；焦点始终可见（`:focus-visible`）。

---

## 2. Color palette & roles

下列 hex 与语义类名以工程主题为基准；实现时通过 CSS 变量与 Tailwind 语义色使用，避免在业务组件中散落硬编码色值。

### 2.1 表面与层级（Light）

| 语义 | 参考 Hex | 用途 |
|------|-----------|------|
| App / 分组底 | `#f5f5f7` | 全局底层、侧栏可落在此档 |
| 面板 / 卡片面 | `#ffffff` | 主阅读区、浮起的卡片 |
| Hover | `#e8e8ed` | 列表行、可点区域的悬停 |
| Active | `#dcdcde` | 按下或较强选中背景 |

### 2.2 表面与层级（Dark）

| 语义 | 参考 Hex | 用途 |
|------|-----------|------|
| App 底 | `#1c1c1e` | 避免纯黑死底 |
| 面板 / 抬升面 | `#2c2c2e` | 主内容区、卡片 |
| Hover | `#3a3a3c` | 悬停 |
| Active | `#48484a` | 激活 |

### 2.3 文本色阶

| 层级 | Light 参考 | Dark 参考 | 用途 |
|------|-------------|-----------|------|
| 主文字 | `#1d1d1f` | `#f5f5f7` | 标题、正文 |
| 次要 | `#6e6e73` | `#a1a1a6` | 说明 |
| 辅助 | `#86868b` | `#8e8e93` | 时间戳、元信息 |
| 禁用 | `#aeaeb2` | `#636366` | 不可用 |

### 2.4 边框

| 层级 | Light 参考 | Dark 参考 | 用途 |
|------|-------------|-----------|------|
| 细 | `#ebebed` | `#3a3a3c` | 列表内分割 |
| 主 | `#d2d2d7` | `#48484a` | 卡片、输入框 |
| 强 | `#bcbcc0` | `#636366` | 需强调的容器 |

### 2.5 交互与强调色

- **主强调（蓝）**：浅色模式主按钮常见 `#2563eb`（hover `#1d4ed8`）；深色模式提亮一档（如 `#3b82f6` / hover `#2563eb`）。用于主 CTA、关键选中、链接与 AI 提示，**全屏强蓝不宜超过两三处**。
- **链接**：与主强调同系，保证与正文对比度；下划线策略以可读为准。
- **焦点环**：与 `accent` 一致，键盘可见、鼠标不扰（`:focus-visible`）。

### 2.6 语义色（状态）

成功 / 警告 / 错误 / 信息仅用于状态反馈，不作装饰；浅底深字、深底半透明底 + 提亮字（具体色阶见工程主题中的 success / danger 等）。

### 2.7 原则（必读）

- **「灰色是主角，蓝色是信号」**：约 95% 面积由中性灰阶构成。
- **语义色**不替代品牌蓝去「点缀」界面。

---

## 3. Typography

### 3.1 字体栈

- **UI 与正文**：`font-sans` — 系统无衬线栈（常见含 SF Pro Text/Display、PingFang、Segoe UI、Roboto、思源/微软雅黑等），不额外引入 UI 正文字体。
- **代码与等宽**：`font-mono` — SF Mono、Menlo、Consolas 等。

**光学尺度**：系统字体在不同字号下由 OS 负责可读性；产品侧用 **固定字阶 + 字重** 区分角色，不在同一界面混用过多相邻字号。

### 3.2 字号层级（Gateway 控制台）

| 层级 | 典型类名 | 尺寸 / 行高 | 字重 | 场景 |
|------|-----------|-------------|------|------|
| Display | `text-3xl tracking-tight` | 30px / 36px | `font-semibold` | 欢迎页、空状态大标题 |
| Title | `text-xl tracking-tight` | 20px / 28px | `font-semibold` | 页面标题、模态标题 |
| Heading | `text-base` | 16px / 24px | `font-semibold` | 卡片与区块标题 |
| Body | `text-sm leading-relaxed` | 14px / 22px | `font-normal` | 正文、文章 |
| UI | `text-sm leading-6` | 14px / 24px | `font-medium` | 按钮、输入框、列表项（最常用） |
| Caption | `text-xs leading-5` | 12px / 20px | `font-normal` | 时间戳、标签、元信息 |

**根字号**：`html` 为 16px（`rem` 基准）；`body` 默认约 15px、行高约 1.47，与常见系统 UI 接近。组件仍应用 `text-sm` / `text-base` 等显式字阶。

### 3.3 字重

- `400`：正文与说明  
- `500`：UI 操作字、次级强调  
- `600`：页面标题、关键数据  
- **避免** `700+` 作为默认，以免笨重

### 3.4 字间距

- 大标题：`tracking-tight`（约 -0.025em）  
- 正文 / UI：可配合极轻负字距（如 body `-0.006em` 量级）  
- 全大写标签：`tracking-wide`

### 3.5 排版原则

- **层级靠字阶与字重，不靠随意调色**  
- **长文左对齐**；标题可按模块居中或左对齐，与布局一致即可  
- **行高对比**：标题偏紧、正文偏松，扫描路径清晰

---

## 4. Layout & spacing

### 4.1 间距刻度

- **基准 8pt**：优先 `4、8、16、24、32、48`（`p-1`～`p-12` 体系）。  
- **密级微调**：图标与文字间可用 `4～8px`；列表行内边距宜紧，避免把行撑得过肥。  
- **区块间距**：页面级模块之间 `32～48px` 或更大，依信息密度而定。

### 4.2 栅格与宽度

- **工作台模式**：侧栏约 **240px** + 列表列约 **320px** + 主内容区 **fluid**（典型三栏）。  
- **聚焦模式**：主列 **max-width 672px**（`max-w-2xl`）居中，上下留白加大。  
- **单块内容**：避免无意义全宽拉伸；表单与阅读列保持 **舒适行长**。

### 4.3 留白哲学（工具型）

- **组件内偏紧、模块间偏松**：列表与工具栏信息密度高，但与下方主内容之间留出呼吸感。  
- **大布局靠色面、不靠粗线**：侧栏与主区用背景色阶区分；**不在二者之间加整根竖向大边框**。

### 4.4 应用壳（Gateway）

- **左侧导航**：偏「底」的表面（如 `bg-surface-base`）。  
- **主内容区**：偏「浮」的表面（如 `bg-surface-panel`）。  
- **细线用于内层**：卡片、行、输入框、弹窗（`border-edge` / `border-edge-subtle`）。

### 4.5 侧栏列表（会话等）

- 行间距约 **`gap-1.5`（6px）** 量级；单行 `px` 略小、`py` 适中，**整行可点** 保证命中。  
- 字阶以 **UI** 行为主（`text-sm` + `leading-6`）。

---

## 5. Shape & border radius

| 类型 | 用途 |
|------|------|
| 小 (`--radius-sm` 档) | 标签、小块 |
| 中 (`--radius-lg` 档) | 小组件、部分列表项 |
| 大 (`--radius-xl` 档) | 按钮、输入框、主要容器 |
| 胶囊 `rounded-full` / `rounded-pill` | 分段控件、芯片、头像 |

控件圆角 **略大、偏有机**；矩形容器避免单角半径夸张到「胶囊混用」 unless 组件语义就是 pill。

---

## 6. Depth & elevation

| 级别 | 处理 | 用途 |
|------|------|------|
| 平面 0 | 无影，仅靠背景色 | 大面积底、静态区 |
| 轻抬升 | `shadow-surface` 类 | 内嵌卡片、输入条外框 |
| 浮层 | `shadow-elevated` / `shadow-popover` | 菜单、下拉、较大浮层 |
| 遮罩 | `bg-scrim` | 模态、抽屉背后 |
| 焦点 | `ring-2 ring-accent`（`focus-visible`） | 键盘导航 |

**阴影哲学**：种类少、对比低；多数层级靠 **表面色差 + 边框**。深色模式阴影进一步减弱，**边线**更重要。

**装饰性深度**：避免依赖重渐变；若用玻璃拟态（顶栏等），需保证对比度与性能可接受。

---

## 7. Components

组件须覆盖 **默认 / hover / active / focus-visible / disabled / loading**；禁止无故移除焦点样式。

### 7.1 按钮

- **主按钮**：每屏首要操作尽量 **一个**；`bg-accent`、白字、`rounded-xl` 档、hover 用 `accent-hover`；`transition-colors` + `active:scale-95`。  
- **次要**：`bg-surface-panel` + `border-edge`。  
- **幽灵**：弱背景或透明，hover 显 `surface-hover`。  
- **破坏**：红系，仅用于删除等；危险操作需确认。  
- **内边距参考**：约 `px-4 py-2`、`text-sm font-medium`；命中高度宜 **≥44px**（含 padding）。

### 7.2 链接

- 与主强调色同系；hover 可用下划线或明度变化；保证浅色 / 深色背景下对比度。

### 7.3 输入框

- `bg-surface-panel`、`border-edge`、`rounded-xl`；focus 时 `ring` 或边框与 `accent` 对齐；placeholder 用 `text-fg-subtle`。

### 7.4 卡片与面板

- 工具型产品 **允许** 用细边框表达卡片，不必强依赖重阴影；与背景的阶梯差要一眼可辨。

### 7.5 导航与图标

- **Lucide** outline，默认 `text-fg-subtle`，激活 `text-fg`。  
- 图标尺寸：导航约 **20px**，按钮内与列表 **16px**，空状态等 **48px** 级。

### 7.6 分段控件

- 轨道 `rounded-full` + 灰色底；选中项 `rounded-full`、浅面 + 轻阴影，与设置类控件一致。

---

## 8. Motion

| 场景 | 时长 | 说明 |
|------|------|------|
| 颜色 / 背景 | ~150ms | `ease-out` |
| 位移 / 缩放 | ~200ms | 展开、位移 |
| 浮层 | ~300ms | 模态、抽屉 |
| 按压 | 即时 | `active:scale-95` |

- **仅动画 `transform` 与 `opacity`**  
- **禁止** `transition-all`  
- **必须** `prefers-reduced-motion: reduce` 时实质关闭动画

---

## 9. Icons & imagery

- **图标**：Lucide，outline，笔画统一；常见 **16 / 20 / 24 / 32 / 48 px**。  
- **空状态**：图标 + 标题 + 短说明 + 可选主操作；语气安慰、步骤清晰。  
- **插图**：少而中性，不破坏沉静气质。

---

## 10. Do & don’t

### Do

- 用 **中性表面 + 单一蓝色强调**；每次加色都有交互或语义理由。  
- 保持 **标题紧、正文松** 与清晰 `h1～h3` 结构。  
- 深色用 **elevated 灰 + 边框**，避免纯黑一片。  
- 全站语义 token 驱动 Light/Dark。

### Don’t

- 不要第二套品牌主色或把界面做成彩虹块。  
- 不要重阴影、强渐变背景抢内容。  
- 不要去掉 **键盘焦点** 或忽略减弱动效。  
- 不要用 **整根竖线** 切侧栏与主区；不要用粗框包整个壳。

---

## 11. Responsive & touch

### 11.1 断点（与 Tailwind 习惯一致，可按实现微调）

| 名称 | 宽度 | 说明 |
|------|------|------|
| 默认 | <640px | 窄屏：侧栏可收起或抽屉化 |
| `sm` | ≥640px | 小屏横屏 / 大手机 |
| `md` | ≥768px | 平板竖屏常见；部分布局两栏 |
| `lg` | ≥1024px | 桌面；完整工作台优先 |
| `xl` / `2xl` | ≥1280 / 1536px | 宽屏留白与列宽 |

### 11.2 触控与指针

- 主按钮与图标按钮：**最小约 44×44px** 命中（含 padding 或透明热区）。  
- 可滚动区域：`min-width: 0` 防止 flex 子项撑破布局。  
- 字号缩放：窄屏时可略降展示级标题字号，保持行高比例。

---

## 12. Agent prompt guide

### 12.1 快速色值（浅 / 深）

- 浅底：`#f5f5f7`，面板：`#ffffff`，主文：`#1d1d1f`，次要：`#6e6e73`。  
- 深底：`#1c1c1e`，面板：`#2c2c2e`，主文：`#f5f5f7`。  
- 主按钮蓝：浅约 `#2563eb`，深约 `#3b82f6`；焦点环与 accent 同系。

### 12.2 描述模板

- **Gateway 聊天区**：主列会话气泡 + 下方 composer；背景用表面阶梯；用户/助手气泡用中性面与细边，主操作仅发送等少数蓝点。  
- **设置行**：左标题右控件；行 hover `surface-hover`；开关与分段控件用胶囊形态。  
- **空状态**：`48px` 线图标 + 一句标题 + 一句说明 + 可选主按钮。

### 12.3 迭代检查清单

1. 是否只有 **一种** 饱和彩色主调（蓝）用于主交互？  
2. 浅 / 深是否都用 **表面阶梯** 而非纯黑或刺白？  
3. 字阶是否落在 **Display～Caption** 六级之一？  
4. 侧栏与主区是否 **无色块竖线分割**，仅色面？  
5. 可聚焦元素是否 **focus-visible** 可见？  
6. 动效是否可被打断，且尊重 **prefers-reduced-motion**？