git:20260511.209c652 to git:20260617.4b7eb3f

184 added, 212 removed. Audit A to A.

- # xopc · Design Language

+ # XOPC Design Language System

- ## 1. Visual theme & atmosphere

+ Version 1.1 · Calm Intelligence

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

+ > Keep what matters moving. Every visual decision should reinforce movement, alignment, and long-term progress.

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

+ ---

- **视觉原则**

+ ## 01. Design Philosophy

- - **中性色占绝对主导**：大面积浅灰分组底或深灰阶梯面，主文字与背景对比清晰（浅模式常见 `#1d1d1f` 与 `#f5f5f7` 阶），避免彩虹式界面。

- - **单一彩色强调**：蓝色代表「可行动 / 智能 / 主操作」，其余状态用低饱和语义色点到为止。

- - **标题紧、正文舒**：标题层级偏紧行高与 `tracking-tight`，正文与系统级 UI 行高保持长时间阅读舒适。

- - **阴影克制**：层级主要靠 **表面色阶** 与 **细边框**；深色模式下 **rim light**（边缘高光感）往往比重阴影更有效。

+ XOPC is not a chatbot skin and not a generic productivity dashboard. It is a quiet operating surface for an assistant that keeps work moving.

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

+ **Core principle: the interface should be quiet.** Intelligence is embedded in the workflow and becomes visible only when it helps the next decision.

- - 界面是背景，用户的思路是主角；AI 在需要时准确出现，不需要时不抢戏。

- - **优雅、智能、克制** —— 少即是多。明确拒绝：炫彩、炫动效、信息堆满、强迫复杂操作。

+ The product should communicate:

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

+ - **Continuity** — work has context before and after the current screen.

+ - **Alignment** — signals, state, and next actions point in the same direction.

+ - **Direction** — the user always knows what can move next.

+ - **Rhythm** — repeated patterns feel stable over long sessions.

+ - **Progress** — status matters more than spectacle.

- - 系统无衬线栈 + 系统等宽栈；大标题 `tracking-tight`，正文与 UI 字阶分离清晰。

- - 浅 / 深两套表面阶梯 + 单一蓝色强调（`accent`）；语义色仅表状态。

- - 应用壳靠 **色块分区**；卡片、列表、输入框用 **细边框** 编组，而非大块竖线切屏。

- - 圆角偏有机；阴影种类少、对比低；深色以 **边线 + 表面差** 为主。

- - 动效短、可打断；尊重 `prefers-reduced-motion`。

- - 图标统一 Lucide outline；焦点始终可见（`:focus-visible`）。

+ Avoid visual metaphors of robots, magic, gamification, or “AI showing off”.

---

- ## 2. Color palette & roles

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

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

- | 语义 | 参考 Hex | 用途 |

- |------|-----------|------|

- | App / 分组底 | `#f5f5f7` | 全局底层、侧栏可落在此档 |

- | 面板 / 卡片面 | `#ffffff` | 主阅读区、浮起的卡片 |

- | Hover | `#e8e8ed` | 列表行、可点区域的悬停 |

- | Active | `#dcdcde` | 按下或较强选中背景 |

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

+ ## 02. Brand Personality

- | 语义 | 参考 Hex | 用途 |

- |------|-----------|------|

- | App 底 | `#1c1c1e` | 避免纯黑死底 |

- | 面板 / 抬升面 | `#2c2c2e` | 主内容区、卡片 |

- | Hover | `#3a3a3c` | 悬停 |

- | Active | `#48484a` | 激活 |

+ XOPC should feel:

- ### 2.3 文本色阶

+ - Calm

+ - Precise

+ - Thoughtful

+ - Systematic

+ - Future-facing

+ - Trustworthy

- | 层级 | Light 参考 | Dark 参考 | 用途 |

- |------|-------------|-----------|------|

- | 主文字 | `#1d1d1f` | `#f5f5f7` | 标题、正文 |

- | 次要 | `#6e6e73` | `#a1a1a6` | 说明 |

- | 辅助 | `#86868b` | `#8e8e93` | 时间戳、元信息 |

- | 禁用 | `#aeaeb2` | `#636366` | 不可用 |

+ XOPC should not feel:

- ### 2.4 边框

+ - Playful or toy-like

+ - Noisy or colorful for its own sake

+ - Overly emotional

+ - Cyberpunk / neon / sci-fi cliché

+ - Gamified

+ - Like a chat product first

- | 层级 | Light 参考 | Dark 参考 | 用途 |

- |------|-------------|-----------|------|

- | 细 | `#ebebed` | `#3a3a3c` | 列表内分割 |

- | 主 | `#d2d2d7` | `#48484a` | 卡片、输入框 |

- | 强 | `#bcbcc0` | `#636366` | 需强调的容器 |

+ **Reference feeling:** a spacecraft dashboard designed by Apple — clear, disciplined, and quietly advanced.

- ### 2.5 交互与强调色

+ ---

- - **主强调（蓝）**：浅色模式主按钮常见 `#2563eb`（hover `#1d4ed8`）；深色模式提亮一档（如 `#3b82f6` / hover `#2563eb`）。用于主 CTA、关键选中、链接与 AI 提示，**全屏强蓝不宜超过两三处**。

- - **链接**：与主强调同系，保证与正文对比度；下划线策略以可读为准。

- - **焦点环**：与 `accent` 一致，键盘可见、鼠标不扰（`:focus-visible`）。

+ ## 03. Visual Archetype

- ### 2.6 语义色（状态）

+ **Calm workstation + directional system.**

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

+ Most tools organize information. XOPC maintains momentum. Therefore the UI should emphasize stable surfaces, clean hierarchy, and a small number of directional signals.

- ### 2.7 原则（必读）

+ Implementation cues:

- - **「灰色是主角，蓝色是信号」**：约 95% 面积由中性灰阶构成。

- - **语义色**不替代品牌蓝去「点缀」界面。

+ - Neutral surfaces dominate.

+ - Blue indicates direction, focus, and primary action.

+ - Indigo and cyan are intelligence accents, not backgrounds.

+ - Progress appears as continuous state, not celebration.

+ - Cards describe goals, state, momentum, next action, and health.

---

- ## 3. Typography

- ### 3.1 字体栈

+ ## 04. Color System

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

- - **代码与等宽**：`font-mono` — SF Mono、Menlo、Consolas 等。

+ Use color sparingly. Rough target: **90–95% neutral**, **5–10% signal color**.

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

+ ### Brand colors

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

+ |---|---|---:|---|

- | 层级 | 典型类名 | 尺寸 / 行高 | 字重 | 场景 |

- |------|-----------|-------------|------|------|

+ ### Light theme

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

+ | Role | Hex |

+ |---|---:|

+ | Background | `#FFFFFF` |

+ | Surface | `#FAFAFA` |

+ | Surface Hover | `#F4F6FF` |

+ | Surface Active | `#EEF2FF` |

+ | Border | `#ECECEC` |

+ | Strong Border | `#D8DCE8` |

+ | Primary Text | `#111111` |

+ | Secondary Text | `#666666` |

+ | Tertiary Text | `#999999` |

- ### 3.3 字重

+ ### Dark theme

- - `400`：正文与说明

- - `500`：UI 操作字、次级强调

- - `600`：页面标题、关键数据

- - **避免** `700+` 作为默认，以免笨重

+ | Role | Hex |

+ |---|---:|

+ | Background | `#0A0A0A` |

+ | Surface | `#121212` |

+ | Surface Hover | `#1A1A1A` |

+ | Surface Active | `#202020` |

+ | Border | `#222222` |

+ | Strong Border | `#333333` |

+ | Primary Text | `#F5F5F5` |

+ | Secondary Text | `#A1A1A1` |

+ | Tertiary Text | `#666666` |

- ### 3.4 字间距

+ ### Signature gradient

- - 大标题：`tracking-tight`（约 -0.025em）

- - 正文 / UI：可配合极轻负字距（如 body `-0.006em` 量级）

- - 全大写标签：`tracking-wide`

+ Only for brand assets, empty-state illustration details, or rare hero moments. Never use it as the primary application background.

- ### 3.5 排版原则

+ `#3A6BFF → #5B57FF → #2ED8FF`

- - **层级靠字阶与字重，不靠随意调色**

- - **长文左对齐**；标题可按模块居中或左对齐，与布局一致即可

- - **行高对比**：标题偏紧、正文偏松，扫描路径清晰

+ The gradient should imply flow, direction, movement, and loop continuity.

---

- ## 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`）居中，上下留白加大。

- - **单块内容**：避免无意义全宽拉伸；表单与阅读列保持 **舒适行长**。

+ ## 05. Typography

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

+ ### Font stack

- - **组件内偏紧、模块间偏松**：列表与工具栏信息密度高，但与下方主内容之间留出呼吸感。

- - **大布局靠色面、不靠粗线**：侧栏与主区用背景色阶区分；**不在二者之间加整根竖向大边框**。

+ - English primary: Inter / system UI

+ - English secondary display: SF Pro Display where available

+ - Chinese primary: PingFang SC

+ - Chinese secondary: HarmonyOS Sans where available

+ - Code: SF Mono / Menlo / Consolas / monospace

- ### 4.4 应用壳（Gateway）

+ ### Typography philosophy

- - **左侧导航**：偏「底」的表面（如 `bg-surface-base`）。

- - **主内容区**：偏「浮」的表面（如 `bg-surface-panel`）。

- - **细线用于内层**：卡片、行、输入框、弹窗（`border-edge` / `border-edge-subtle`）。

+ - Large titles, few words.

+ - Clear hierarchy, generous spacing.

+ - Titles are tight; body copy is comfortable.

+ - Use weight and spacing before using color.

+ - Avoid heavy default bold; `600` is usually enough.

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

+ ### UI scale

- - 行间距约 **`gap-1.5`（6px）** 量级；单行 `px` 略小、`py` 适中，**整行可点** 保证命中。

- - 字阶以 **UI** 行为主（`text-sm` + `leading-6`）。

+ | Level | Typical size | Use |

+ |---|---:|---|

+ | Display | 30–36px | Welcome, empty state, major product moments |

+ | Title | 20–24px | Page titles, dialogs |

+ | Heading | 16px / 600 | Cards, panels, sections |

+ | Body | 14–15px | Reading and long-lived UI |

+ | Caption | 12px | Metadata, timestamps, chips |

---

- ## 5. Shape & border radius

+ ## 06. Layout Principles

- | 类型 | 用途 |

- |------|------|

- | 小 (`--radius-sm` 档) | 标签、小块 |

- | 中 (`--radius-lg` 档) | 小组件、部分列表项 |

- | 大 (`--radius-xl` 档) | 按钮、输入框、主要容器 |

- | 胶囊 `rounded-full` / `rounded-pill` | 分段控件、芯片、头像 |

+ 1. **Whitespace creates trust.** Let important decisions breathe.

+ 2. **One screen = one decision.** Every screen should have an obvious next action or state.

+ 3. **Remove non-essential elements.** Density is allowed only when it increases clarity.

+ 4. **Progress beats information volume.** Show momentum, health, and next action before raw detail.

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

+ Recommended structure:

- ---

+ - Application shell: stable navigation + calm work surface.

+ - Focus screens: centered readable column with generous top/bottom space.

+ - Dense screens: compact rows inside clearly bounded panels.

+ - Settings screens: grouped cards, short labels, explicit saved / error state.

- ## 6. Depth & elevation

+ ---

- | 级别 | 处理 | 用途 |

- |------|------|------|

- | 平面 0 | 无影，仅靠背景色 | 大面积底、静态区 |

- | 轻抬升 | `shadow-surface` 类 | 内嵌卡片、输入条外框 |

- | 浮层 | `shadow-elevated` / `shadow-popover` | 菜单、下拉、较大浮层 |

- | 遮罩 | `bg-scrim` | 模态、抽屉背后 |

- | 焦点 | `ring-2 ring-accent`（`focus-visible`） | 键盘导航 |

+ ## 07. Core Visual Motif: The Loop

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

+ The Loop is not a circle, infinity symbol, or arrow. It is a continuous flowing path.

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

+ It represents:

- ---

+ - Direction

+ - Action

+ - Feedback

+ - Alignment

+ - Returning to direction again

- ## 7. Components

+ Use the Loop as a conceptual motif in product language and brand assets. In UI components, express it through continuity: connected steps, persistent session state, health rings, and next-action surfaces.

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

+ ---

- ### 7.1 按钮

+ ## 08. Motion Language

- - **主按钮**：每屏首要操作尽量 **一个**；`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）。

+ Motion should communicate progress, not excitement.

- ### 7.2 链接

+ | Speed | Duration | Use |

+ |---|---:|---|

+ | Fast | 120–180ms | Hover, pressed, small reveals |

+ | Standard | 220–320ms | Panel transitions, route-level soft changes |

+ | Slow | 400–600ms | Rare page-level or brand moments |

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

+ Preferred motion types:

- ### 7.3 输入框

+ - Flow

+ - Alignment

+ - Expansion

+ - Reveal

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

+ Never use bounce, elastic, cartoon-like motion, or animation that delays the task. Always respect `prefers-reduced-motion`.

- ### 7.4 卡片与面板

+ ---

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

+ ## 09. Product Components

- ### 7.5 导航与图标

+ ### Loop Card

- - **Lucide** outline，默认 `text-fg-subtle`，激活 `text-fg`。

- - 图标尺寸：导航约 **20px**，按钮内与列表 **16px**，空状态等 **48px** 级。

+ A primary work object card. It should answer:

- ### 7.6 分段控件

+ - Goal

+ - Current state

+ - Momentum

+ - Next action

+ - Health

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

+ ### Loop Feed Item

- ---

+ A feed object for system intelligence. It may contain:

- ## 8. Motion

+ - Insight

+ - Recommendation

+ - Reflection

+ - Decision

+ - Opportunity

- | 场景 | 时长 | 说明 |

- |------|------|------|

- | 颜色 / 背景 | ~150ms | `ease-out` |

- | 位移 / 缩放 | ~200ms | 展开、位移 |

- | 浮层 | ~300ms | 模态、抽屉 |

- | 按压 | 即时 | `active:scale-95` |

+ ### Loop Health Indicator

- - **仅动画 `transform` 与 `opacity`**

- - **禁止** `transition-all`

- - **必须** `prefers-reduced-motion: reduce` 时实质关闭动画

+ Health is `0–100`, but the visual should be a **continuous ring**, not a progress bar alone. Use text only as a supplement.

---

- ## 9. Icons & imagery

+ ## 10. Icon Language

- - **图标**：Lucide，outline，笔画统一；常见 **16 / 20 / 24 / 32 / 48 px**。

- - **空状态**：图标 + 标题 + 短说明 + 可选主操作；语气安慰、步骤清晰。

- - **插图**：少而中性，不破坏沉静气质。

+ - Linear outline icons

+ - 2px stroke

+ - Rounded corners and caps

+ - Minimal detail

+ - Consistent optical size

- ---

+ Core icon concepts: Direction, Loop, Alignment, Momentum, Feedback, Signal, Insight, Agent, Review, Health.

- ## 10. Do & don’t

+ ---

- ### Do

+ ## 11. AI Expression

- - 用 **中性表面 + 单一蓝色强调**；每次加色都有交互或语义理由。

- - 保持 **标题紧、正文松** 与清晰 `h1～h3` 结构。

- - 深色用 **elevated 灰 + 边框**，避免纯黑一片。

- - 全站语义 token 驱动 Light/Dark。

+ Do not make intelligence feel like a separate character. Avoid labels such as “AI generated this”. Prefer embedded, operational language:

- ### Don’t

+ - Suggested Next Step

+ - Recommended

+ - Detected Pattern

+ - Observed Change

+ - Alignment Risk

+ - Momentum Opportunity

- - 不要第二套品牌主色或把界面做成彩虹块。

- - 不要重阴影、强渐变背景抢内容。

- - 不要去掉 **键盘焦点** 或忽略减弱动效。

- - 不要用 **整根竖线** 切侧栏与主区；不要用粗框包整个壳。

+ The system should feel supportive, not performative.

---

- ## 11. Responsive & touch

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

+ ## 12. Web UI Theme Implementation

- | 名称 | 宽度 | 说明 |

- |------|------|------|

- | 默认 | <640px | 窄屏：侧栏可收起或抽屉化 |

- | `sm` | ≥640px | 小屏横屏 / 大手机 |

- | `md` | ≥768px | 平板竖屏常见；部分布局两栏 |

- | `lg` | ≥1024px | 桌面；完整工作台优先 |

- | `xl` / `2xl` | ≥1280 / 1536px | 宽屏留白与列宽 |

+ The default Web UI theme uses semantic tokens in `web/src/styles/globals.css`:

- ### 11.2 触控与指针

+ - `surface-*` for quiet layered surfaces

+ - `fg-*` for text hierarchy

+ - `edge-*` for borders and separators

+ - `accent` for Loop Blue primary interaction

+ - semantic `success / warning / danger` only for state

- - 主按钮与图标按钮：**最小约 44×44px** 命中（含 padding 或透明热区）。

- - 可滚动区域：`min-width: 0` 防止 flex 子项撑破布局。

- - 字号缩放：窄屏时可略降展示级标题字号，保持行高比例。

+ Do not hardcode brand colors inside feature components unless the component is itself a brand asset. Prefer Tailwind semantic utilities such as `bg-surface-panel`, `text-fg-muted`, `border-edge`, `bg-accent`, and `text-accent-fg`.

---

- ## 12. Agent prompt guide

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

- - 浅底：`#f5f5f7`，面板：`#ffffff`，主文：`#1d1d1f`，次要：`#6e6e73`。

- - 深底：`#1c1c1e`，面板：`#2c2c2e`，主文：`#f5f5f7`。

- - 主按钮蓝：浅约 `#2563eb`，深约 `#3b82f6`；焦点环与 accent 同系。

- ### 12.2 描述模板

+ ## 13. Emotional Goal

- - **Gateway 聊天区**：主列会话气泡 + 下方 composer；背景用表面阶梯；用户/助手气泡用中性面与细边，主操作仅发送等少数蓝点。

- - **设置行**：左标题右控件；行 hover `surface-hover`；开关与分段控件用胶囊形态。

- - **空状态**：`48px` 线图标 + 一句标题 + 一句说明 + 可选主按钮。

+ When users open XOPC they should feel:

- ### 12.3 迭代检查清单

+ - Calm

+ - Clear

+ - Supported

+ - Moving forward

- 1. 是否只有 **一种** 饱和彩色主调（蓝）用于主交互？

- 2. 浅 / 深是否都用 **表面阶梯** 而非纯黑或刺白？

- 3. 字阶是否落在 **Display～Caption** 六级之一？

- 4. 侧栏与主区是否 **无色块竖线分割**，仅色面？

- 5. 可聚焦元素是否 **focus-visible** 可见？

- 6. 动效是否可被打断，且尊重 **prefers-reduced-motion**？

+ Never overwhelmed. Never rushed. Never distracted.