DESIGN.md git:20260905.e14599eA

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

# 太初前端设计说明

> 更新日期：2026-09-05
> 强制适用范围：太初前端视觉系统、页面布局、组件设计、交互动效、Tailwind token、shadcn/ui 二次封装和所有用户可见前端文案。

本文档是太初前端设计的强制规则源。涉及 `web/` 下页面、组件、样式、交互、动效、前端文案或视觉方案的创建、修改、评审和讨论时，必须先读取并遵循本文档。不得把本文档仅作为可选参考。

本文档只定义前端视觉与交互规则，不改变太初的产品边界：太初仍然是面向单本玄幻小说的个人 AI 写作助手，不支持多小说管理、多租户后台或通用内容平台形态。

## 1. 当前设计方向

太初当前默认前端风格为“Langbase 午夜极光控制台风格”：炭灰控制台画布、深色导航条、克制的灰阶层级、白色胶囊按钮、Geist Sans UI 字体、Geist Mono 技术读数，以及只作为装饰出现的极光渐变条。

界面应像一个午夜开发者控制台，但服务对象仍是中文玄幻小说作者。视觉重点是安静、结构清楚、边界精确、长期可读，而不是营销页、赛博霓虹或游戏化 HUD。

核心判断如下：

- 页面默认背景使用 `#232324` 炭灰控制台画布，不使用纯黑作为页面背景。
- 顶部导航使用更深的 `#0e0e10`，作为稳定的横向锚点。
- 主要文字使用接近白色的 `#fafafa`，次级说明使用 `#a1a1aa`。
- 页面层级通过留白、对齐、深浅表面、圆角容器和 4px 网格建立，不使用分割线组织内容。
- 主按钮使用白底黑字胶囊形，不使用彩色按钮。
- 极光渐变只作为少量装饰条、背景线索或 AI 状态氛围，不作为按钮、文字、边框、图标或功能状态颜色。
- 卡片使用 12px 圆角，输入框和小标签使用 4px 圆角，按钮使用全圆角。
- 页面信息结构、组件功能、路由和工作流不得因风格变化而改变。
- 所有用户可见文案必须为中文。内部组件名、token 名、接口名和文件路径可以保留英文，但不得直接暴露为界面文案。

### 1.1 信息密度与功能显隐

太初界面默认是“高密度、低干扰”的写作工作台，不是展示型产品页，也不是把每个功能都摊开的后台系统。所有前端页面必须优先减少视觉占地和认知噪音，让作者先看到当前真正要处理的内容。

强制规则：

- 信息不能臃肿。默认只展示当前任务所需的标题、状态、少量摘要和关键操作；解释、说明、长内容、原始数据和低频信息必须延后到详情、折叠区、抽屉、弹层或二级页面。
- 功能不能全部显性铺开。高频主操作可以常驻，低频操作必须收进更多菜单、行内悬浮操作、详情面板或上下文操作区，不得把每个功能都做成醒目的按钮。
- 条目和列表必须紧凑。知识条目、候选项、历史记录、章节项、资料项、设置项默认使用窄行、紧凑列表或轻量表格；不得把每个条目做成大块卡片，不得用大标题、大图标、大内边距撑高条目。
- 边框只用于输入框、按钮、弹层等需要明确交互边界的独立组件，不用于内容分组或区块分割。避免框中框、卡片套卡片、每个区块都包边框；内容层级必须使用留白、字重、对齐、圆角和灰阶表面表达。
- 禁止使用横线、竖线、`border-top`、`border-bottom`、`border-left`、`border-right`、`divide-x`、`divide-y` 或 `<hr>` 分割页面内容、消息、列表项与状态信息。导航栏与侧栏可通过不同背景形成结构边界；表格应优先使用对齐和行底色，不能默认画网格线。
- 页面不能为功能说明占用大面积空间。禁止在应用内功能页使用营销式介绍、说明卡、巨型空状态和大段“如何使用”；必要提示必须短、靠近上下文，并可关闭或折叠。
- 默认视图不要展开全文。长摘要、Prompt、模型原文、知识卡 JSON、运行日志、候选详情等必须按需查看，列表中最多保留一到两行摘要。
- 工具栏和筛选区必须克制。筛选、排序、批量操作、视图切换等控件只在当前任务需要时出现；可收起的筛选条件不得长期占据主内容宽度。
- 交付范围仅包含桌面浏览器中的网页应用。页面以 1280px 及以上的桌面可视宽度为设计与验收基准，不为手机、平板、原生 App 或窄屏重排维护专门交互。

### 1.2 当前入口策略

根路径 `/` 当前不承载独立品牌场景，访问后直接跳转到 `/home`。`/home` 使用本文定义的控制台工作台页面模式，不设置入口页视觉例外。

已停用的点云入口只作为历史快照保存，不参与前端源码检查、构建或静态资源发布，也不得作为后续页面的视觉参考或组件依赖。若未来重新启用独立入口，必须先按当时的设计目标重新评审，并同步更新本文、路由实现和前端风格说明。

## 2. 颜色 Token

当前主风格使用炭灰、近白、克制的灰阶外轮廓和少量极光色。新页面和新组件必须使用 `web/src/app/globals.css` 中已有的语义 token，不直接写死外部参考色，也不在本文复制维护 token 清单或精确赋值。

使用规则：

- `--tc-surface-page` 对应炭灰控制台画布。
- `--tc-surface-muted` 对应内凹输入区和弱表面。
- `--tc-border-subtle` 只用于输入框、按钮、弹层和其他独立交互容器的必要外边界，不得作为内容分割线。
- `--tc-text-primary` 对应主要文字，必须满足长时间阅读对比度。
- `--tc-action-primary-bg` 对应白色胶囊主按钮。
- `--tc-aurora-gradient` 只能用于装饰，不得用于功能状态。

## 3. 字体与排版

当前主风格使用 Geist Sans 作为主要 UI 字体，Geist Mono 作为展示标题、技术读数和代码感标签。

排版规则：

- 导航、按钮、正文、表单、说明文字使用 UI 字体。
- 大号展示读数、代码片段、来源编号和技术标签使用等宽字体。
- 字重以 400、500、600 为主，700 只用于少量强提示。
- 常用字号为 12px、14px、16px、18px、20px、32px、48px。
- `letter-spacing` 默认必须为 `0` 或浏览器 normal，不得使用负字距。
- 中文长文必须优先保证可读性，不能为了控制台感牺牲换行、行高和对比度。

## 4. 空间、圆角与边框

基础单位为 4px。

规则：

- 页面主体内容最大宽度默认 1200px，工作台视图可按功能扩展。
- 普通功能页区块间距默认使用 24px 到 40px；只有真正的页面大段落才允许使用 64px 到 80px。
- 普通容器内边距建议 16px；重复条目、列表行和候选项内边距建议 8px 到 12px。
- 卡片使用 12px 圆角。
- 输入框、小标签和图标容器使用 4px 圆角。
- 主按钮和次级按钮使用全圆角。
- 需要明确交互边界的独立组件可使用 1px `--tc-border-subtle` 外边框。
- 禁止用单独的横线、竖线或连续边框分割区块、消息、状态、列表项和重复内容。
- 重复内容必须通过间距、对齐、弱底色、圆角与 hover 表面建立节奏。
- 禁止厚重阴影、玻璃拟态、强发光边框和浮夸悬浮层级。
- 禁止把页面主要内容拆成大量等宽大卡片；重复内容优先使用紧凑行、留白、弱底色和可展开详情。

## 5. 页面模式

### 5.1 控制台工作台页面

适用于 `/home`、知识库、灵感、设置、AI 历史和普通功能入口。

规则：

- 页面背景使用炭灰控制台画布。
- 内容表面使用同色或内凹深色表面，通过留白、对齐和灰阶区分层级。
- 背景可使用低对比线框网格，不能使用大面积渐变。
- 卡片标题保持克制，不使用杂志式巨型标题。
- 主操作每个视图低频出现，使用白色胶囊按钮。

### 5.2 写作与编辑页面

写作页面必须优先保障长时间输入效率。

规则：

- 编辑器、章节树、工具栏、AI 辅助区使用同一套控制台表面。
- 正文输入区可使用内凹深色表面，但必须保证光标、选区、正文和占位提示足够清晰。
- AI 结果和来源证据使用弱底色、圆角容器、中文标签和明确操作，不遮挡正文输入。
- 极光装饰只能作为弱氛围或状态辅助，不得覆盖正文区域。

### 5.3 资料与知识页面

资料页应像可检索的控制台档案库，而不是普通后台表格。

规则：

- 来源、状态、章节关系和时间信息使用小字号中文标签。
- 资料条目通过留白、字重、对齐和灰阶层级表达状态。
- 不使用彩色功能标签；状态必须靠中文文字、图标和灰阶表面表达。
- 空状态、加载状态和错误状态都必须用中文说明。

### 5.4 对话与智能体协作页面

对话页必须采用现代 AI 产品的连续对话模式，而不是任务看板、日志面板或用线切开的报告页面。

强制规则：

- 用户消息右对齐并使用克制的消息气泡；助手消息左对齐，以头像、名称、气泡或自然阅读块形成清楚的对话轮次。
- 回复、运行状态、计划进度、人工确认、错误与补充问题都必须位于对话流内，作为对应助手消息的内容或附属信息展示；不得在消息之间插入横贯内容区的状态条或独立仪表盘区块。
- 消息之间只使用纵向留白、对齐、弱底色和圆角建立层级，严禁用任何横线、竖线、边框边或 `divide-*` 分割消息及消息内部内容。
- 底部输入区使用一个类似 Codex 的完整圆角组合框：文本输入、上下文入口、附加设置、停止与发送操作都收在同一个外轮廓内；组合框内部不得再用分割线切成多层。
- 对话主画布使用比底部输入组合框更深的连续表面；助手正文直接融入深色画布，输入组合框与用户消息气泡使用较亮的页面表面，形成类似 Codex 的输入与阅读层级。
- 输入框、消息气泡、弹出设置面板可以拥有完整外轮廓；外轮廓用于说明组件边界，不属于分割线。不得把多个外轮廓首尾相接伪装成表格或分栏。
- 对话正文优先保证连续阅读，不显示“助手回复”“本次任务”等报告式栏目标题；复制、计划和技术详情作为弱化的行内操作或按需展开内容出现。
- 同一对话允许连续发送多轮用户消息并展示对应回复；发送新消息不得自动新增侧栏条目。只有作者主动点击“开启新对话”时才创建新的对话，侧栏必须按对话而不是按单次运行展示。

## 6. 组件规则

### 6.1 按钮

主按钮：

- 背景使用 `--tc-action-primary-bg`。
- 文字使用 `--tc-action-primary-text`。
- 圆角使用全圆角。
- 字体使用 UI 字体，字重 500 或 600。
- 只允许非常轻的 1px 阴影，不使用发光和位移。

次级按钮：

- 透明或深色背景。
- 1px 灰色线框。
- 文字使用 `--tc-text-primary`。
- 只通过灰阶变化反馈 hover 和 focus。
- 状态操作必须根据条目当前状态显隐，不得展示会把条目重复设置为当前状态的无效按钮；状态筛选必须覆盖该页面能够产生并允许查看的全部状态。

### 6.2 导航

导航应像控制台顶部锚点：

- 背景使用 `#0e0e10`。
- 导航与页面主体使用不同背景自然分层，不添加底部分割线。
- 当前项使用内凹深色表面和白色文字。
- 导航文字必须为中文。
- 导航以桌面浏览器的可视宽度为准，不为手机端横向滚动、折叠菜单或触控交互维护额外方案。

### 6.3 卡片

卡片不是默认容器，只用于必须被明确框定的功能入口、AI 结果、模态内容和少量设置分组。资料条目、知识条目、候选项、历史记录和章节项默认使用紧凑列表行，不使用大卡片。

- 背景使用 `--tc-surface-card`。
- 圆角 12px。
- 只有需要明确独立边界时才使用 1px 完整外边框；普通内容卡片优先无边框。
- 默认无阴影。
- 不使用彩色卡片背景。
- 不嵌套卡片，不把卡片当作页面分区外壳，不用大内边距制造展示感。
- 重复条目的高度必须由内容需要决定，默认只保留标题、一到两行摘要、少量状态标签和必要行内操作。

### 6.4 标签与徽标

- 标签必须配中文文字，不得只靠颜色表达状态。
- 普通标签使用透明或内凹深色背景。
- 普通图标使用中性单色线性图标；运行调用记录可以按 6.5 节为不同动作类型使用稳定的低饱和语义色。
- 普通标签禁止建立多色状态体系，成功、警告、错误默认通过文字、图标和边框表达；运行调用记录仅允许使用 6.5 节定义的窄范围语义色。
- 具有稳定语义字段的明细展开（例如收件箱「系统问题与改进项记录」）可为字段小标题和圆点使用低饱和语义色，已处理状态可使用绿色辅助扫读。颜色只能用于小范围文字和圆点，必须同时保留中文字段名与状态文字，不得扩展为彩色卡片、背景色块、分割线或全局多色标签体系。

### 6.5 执行动作与调用记录

智能体监控、节点详情和运行追踪中的工具、专业智能体与模型调用，允许使用“有颜色、有状态、中文简洁”的紧凑动作行。这是运行可观测场景的专用模式，不得扩展为普通资料列表、导航或全局彩色标签体系。

强制规则：

- 每条记录采用紧凑横向结构：左侧为动作类型图标，中部为动作名称和耗时，右侧为中文执行状态。不得把单次调用做成大卡片或多层嵌套面板。
- 主文案使用“中文动作类型 · 中文能力名称”，例如“工具 · 搜索正文证据”“模型 · 小说事实取证”；不得直接展示内部能力标识、枚举值或英文状态。
- 工具使用低饱和青色线性图标，模型使用低饱和琥珀色线性图标，专业智能体使用低饱和紫色线性图标。同一动作类型在所有监控页面必须保持相同图标与颜色语义。
- 状态必须在右侧显示中文文字，并可使用小范围语义色辅助扫读：运行中使用蓝色，成功使用绿色，等待或需作者处理使用橙色，失败或超时使用红色，未开始或已跳过使用灰色。
- 颜色只能辅助表达，不能成为唯一信息来源。动作类型必须同时具有图标和中文名称，执行结果必须同时具有中文状态文字。
- 图标颜色只用于图标及其低对比圆形底，状态颜色只用于状态文字或极小状态点；列表行背景保持中性深色，不使用彩色卡片背景、彩色边框、渐变或发光。
- 监控与评测入口的颜色必须表达稳定的业务归属，不得按“监控”“评测”等动作各自分配颜色。同一业务组在同页和跨页必须复用同一个低饱和语义图标色：知识沉淀监控与知识沉淀评测统一使用 `--tc-monitor-knowledge`，通用写作智能体监控与评测统一使用 `--tc-monitor-general-agent`，RAG 建模监控使用 `--tc-monitor-rag`；不同业务组之间必须保持可辨认。精确色值只在主题 token 中维护。
- 业务组的颜色区分只能作用于小范围图标及其低对比背景，不能扩展到卡片背景、边框或标题。颜色不得成为唯一辨识手段，每个入口仍必须同时使用对应图标和明确中文名称。
- 耗时、调用数量等辅助信息使用次级灰色文字，不与动作名称和状态争夺视觉层级；无数据时使用简短中文说明。
- 默认只展示作者能够理解的动作摘要。Token、模型标识、输入输出字符数、调用链标识和错误类型等技术记录必须放入折叠区、抽屉或二级详情。
- 动作行可以承担查看详情的点击入口；可点击时必须提供完整行 hover、键盘焦点和明确的中文可访问名称，不额外堆叠醒目按钮。
- 执行轨迹采用全宽连续账本：顶部紧凑工具栏与输入、模型、工具三条微型时间轨，下方为约 40px 的单行事件。工具输入与输出以箭头并列，详情按需打开，不常驻左右证据侧栏，不按页切断事件流。
- 仅在执行轨迹中，时间轨可将既有动作类型色用于微型时长条；输入标记使用低饱和绿色。助手与结构化输出可使用小范围低饱和紫色角色文字和弱底色，工具文字可沿用青色。每条轨道、角色与状态仍须有中文名称；记录底色保持中性，不能用彩色边框或内容分割线模拟参考图。

### 6.6 输入框与表单

- 普通输入框使用 `#181818` 内凹深色背景、浅色文字和 1px 灰色边框；对话页底部完整输入组合框按 5.4 节使用较亮页面表面，内部文本区域保持透明。
- 聚焦状态使用白色边框或轮廓，不使用发光。
- 占位、错误和帮助文字必须为中文。
- 低频设置页必须清楚说明设置影响范围。

## 7. 动效规则

动效只用于状态反馈和层级说明。

- 常规 hover、focus、popover 出现使用 120ms 到 200ms。
- 风格切换只改变视觉 token，不改变布局结构。
- 尊重 `prefers-reduced-motion`。
- 极光效果只能弱动效或静态，不得持续强闪烁。
- 禁止粒子、霓虹、旋转装饰和大面积渐变动画。

## 8. 多风格切换边界

太初允许在固定信息结构下切换多套视觉风格。本文档定义强制边界，`docs/前端风格/` 只保存主题说明，不是第二套规则源。主题清单和默认值以 `web/src/components/theme/theme-registry.ts` 为准，精确 token 以 `web/src/app/globals.css` 为准。

允许每套风格改变：

- 颜色。
- 字体。
- 圆角。
- 边框。
- 阴影。
- 局部动效强度。

不允许每套风格改变：

- 页面信息结构。
- 组件功能。
- 路由与工作流。
- 用户可见中文文案规则。
- 单本玄幻小说写作助手的产品边界。

当前默认主题 ID 为 `langbase-midnight-console`。其他可切换风格必须通过语义 token 映射实现，不能在组件中硬编码风格名称。

## 9. 明确禁止项

太初当前前端不得使用以下方向：

- 已废弃的 Axiom 纯黑橙色终端风格作为默认主风格。
- 旧版奶油纸张编辑出版风格作为默认主风格。
- 游戏 UI。
- 赛博霓虹。
- 普通后台管理系统。
- 多色高饱和按钮体系。
- 把极光渐变作为功能色、按钮色、文字色或边框色。
- 玻璃拟态和强发光卡片。
- 生活方式摄影、客户 logo 墙或与写作无关的营销素材。
- 英文内部字段名直接作为用户可见文案。
- 使用横线、竖线、边框边或 `divide-*` 分割内容区块、对话消息、状态信息和列表项。

最终判断标准：

```text
打开太初时，用户看到的是一个炭灰、克制、层级清楚的中文写作控制台。
开始写作时，界面优先服务章节编辑、资料检索和 AI 协作。
极光只提供少量情绪装饰，不能抢走写作工作台的功能焦点。
切换风格时，页面看起来可以完全不同，但页面有什么、功能怎么工作不能改变。
```