跳转至

Web UI 设计语言总览

本文档定义 TTD Web App 在 light-first 阶段的统一 UI 设计语言。目标不是重新发明一套与现有实现割裂的视觉系统，而是在现有 Next.js + Tailwind v4 + Radix/shadcn 架构之上，建立一套可复用、可治理、可持续演进的设计标准，消除 landing、auth、chat、admin 与 legacy 页面之间的视觉漂移。

文档状态

  • 状态：Draft v1
  • 适用范围：Web App 内部界面（auth、chat、admin、sessions/results）
  • 当前阶段：Light-first 设计系统落地
  • 非目标：本轮不重做 landing page，也不在首期重构 dark mode

1. 文档定位

本篇是 Web Design System 的总览文档，回答三个问题：

  1. 为什么需要统一设计语言。
  2. 新的设计语言想解决什么问题。
  3. 各子规范与现有代码结构如何对应。

它不替代具体 token、组件、页面模板和代码治理文档，而是作为这些子文档的索引与原则来源。

2. 为什么需要统一设计语言

当前系统已经具备较完整的前端能力，但视觉语言存在明显漂移：

  1. landing page、auth 页面与内部 app shell 的色彩和表面层级并未完全收敛到同一套语义 token。
  2. 页面层存在硬编码品牌色、局部焦点态、局部阴影和页面自定义按钮/输入框样式。
  3. 高密度分析页面中出现了较多 text-[10px]、text-[11px] 一类的局部微排版，缺少统一的 typography contract。
  4. 相同语义的卡片、标签、状态条、面板标题在不同页面中表现不完全一致。

这会带来三个直接问题：

  1. 用户感知上，系统不像一个统一产品，更像多个独立页面拼装而成。
  2. 开发实现上，视觉决策不断在页面级重复发生，导致新功能持续复制旧漂移。
  3. 治理上，代码评审缺少明确标准，只能依赖个体经验判断样式是否“差不多”。

3. 体验目标与设计原则

3.1 体验目标

新的 Web UI 设计语言需要同时满足以下目标：

  1. 冷静：适合数据分析与多任务工作流，不制造不必要的视觉噪声。
  2. 数据原生：让图表、表格、状态、指标与解释块天然成为界面的中心。
  3. 可感知的 agentic：保留智能体执行、规划、结果汇总的品牌气质，但不牺牲可读性。
  4. 高密度但不拥挤：在 admin、chat、results 等高信息量页面中保持结构清晰。
  5. 实现可治理：设计语言必须能映射到现有代码层，而不是只停留在视觉描述。

3.2 设计原则

  1. Semantic over literal：页面代码优先消费语义 token，而不是字面量色值或局部视觉技巧。
  2. Primitive first：按钮、输入框、卡片、表格、导航等基础组件统一在共享原语层维护。
  3. Readability first：分析页面的可读性和信息层级优先于装饰效果。
  4. Motion for orientation：动画用于引导注意力和表达状态，而不是营造表演感。
  5. Consistency as release criteria：视觉一致性与无障碍要求是交付标准，不是附加优化。

4. 适用范围与非目标

4.1 当前适用范围

本轮设计系统首期覆盖以下内部 Web App 界面：

  1. 认证界面：/login、/signup
  2. 主应用壳层：/(chat) 路由组
  3. 聊天与分析界面：chat home、conversation detail、thinking/result blocks
  4. 管理台界面：dashboard、list/detail、settings、evaluation 等
  5. legacy sessions/results 界面

4.2 非目标

以下内容不在本轮文档的首期约束范围：

  1. landing page 的整体重设计
  2. dark mode 的完整视觉衍生体系
  3. 独立于现有技术栈的全新组件系统
  4. 营销页、活动页、实验性 showcase 页面

5. 设计语言摘要

5.1 视觉方向

设计语言以当前 landing page 和参考稿中的 light theme 为母版，统一提炼为一套适合 Web App 内部界面的控制台视觉系统：

  1. 以浅雾感 periwinkle 画布作为背景基调。
  2. 以深海军蓝文本作为主要阅读层。
  3. 以高对比但收敛的品牌蓝作为主交互强调色。
  4. 以白色或近白色的面板承担信息承载层。
  5. 以轻玻璃感、柔和阴影和少量辉光表达层级，而不是通过大量边框堆叠层次。

5.2 字体层级

  1. 默认 UI 与正文：DM Sans
  2. 高强调展示标题：Fraunces
  3. 技术标签、SQL、指标、系统状态：Mono 字体层

5.3 动效语言

  1. 微交互应控制在短时长内完成，不影响工作流。
  2. 模块入场与分组 reveal 仅用于改善感知层级。
  3. 高密度数据区域避免过度动画。

5.4 数据表达母题

允许保留数据网络、sparkline、mono 技术标签和轻量状态脉冲等视觉母题，但使用范围应被严格控制在：

  1. auth 页面
  2. 空状态与 onboarding
  3. overview/summary 卡片
  4. 高价值分析摘要面板

6. 与现有代码结构的映射

设计语言并不独立于实现而存在，而是要映射到现有前端结构中。

规范层 代码落点 说明
Token 层 web/app/globals.css 颜色、字体、阴影、圆角、动画、断点的语义入口
主题入口 web/app/layout.tsx 字体加载、全局 body 语义、主题边界
Provider 层 web/components/ui/providers.tsx 主题和全局上下文入口
原语层 web/components/ui/ Button、Input、Card、Sidebar、DataTable 等共享组件
页面模板层 web/app/(auth)、web/app/(chat)、web/app/sessions 页面区域和信息架构的主要实现入口
业务组合层 web/components/chat/、web/components/results/、web/components/session/ 由原语组合而成的高频业务模块

7. 关联规范

Web Design System 首期由以下 4 篇执行文档组成：

  1. Design Tokens 规范
  2. 组件规范
  3. 页面模板规范
  4. 代码治理与评审约束

阅读顺序建议如下：

  1. 先读本篇，理解设计目标与边界。
  2. 再读 token 文档，明确视觉语义来源。
  3. 再读组件与模板文档，明确页面如何组合。
  4. 最后读治理文档，明确实现和评审边界。

8. 设计系统治理模型

8.1 设计系统的 Source of Truth

  1. 视觉语义的源头在 token 文档和 web/app/globals.css
  2. 共享交互与视觉实现的源头在 web/components/ui/
  3. 页面文件只负责组合，不应成为新的视觉源头

8.2 变更治理

以下变更需要进入设计系统层级进行治理，而不是仅在页面中局部修改：

  1. 品牌色、语义背景、边框、阴影、圆角发生变化
  2. 共享原语新增变体或修改交互态
  3. 页面模板新增大区块或改变主次层级
  4. 组件密度与排版规则发生结构性变化

9. 实施阶段摘要

首期实施顺序遵循“先基础，后页面”的原则：

  1. 统一 token 与字体、阴影、圆角、动效语义
  2. 刷新共享原语层
  3. 收敛 app shell、auth、chat、results、admin
  4. 以治理规则固化设计语言

详细迁移约束与评审标准见 代码治理与评审约束。