Wuu 设计系统
Wuu 用柔和的中性外框包围不透明的阅读画布：浅色为柔白（#fcfcfd），深色为炭灰。常规字重的系统字体、清楚的灰色选中态、圆角控件和轻阴影服务于长时间阅读与高频操作。设置和扩展页面在次级画布上使用分组卡片。可选的外壳皮肤与内容主题保持独立。
这份规范与配套图版共同维护桌面端的设计基础，供设计、开发和 AI 编码使用。它不是产品换肤方案，也不表示现有每个界面都已符合规范。原生手机端遵循相同的信息与交互原则，但不直接照搬桌面的像素尺寸。
图版按「色彩」「间距、圆角与层级」「排版」组织，使用 Wuu 的实际变量，不采用外部参考图的配色或字体。每类提供浅色和深色两张高清 PNG，中英文标注共用一份资产。
| 图版 | 浅色 | 深色 |
|---|---|---|
| 色彩 | 查看原图 | 查看原图 |
| 间距、圆角与层级 | 查看原图 | 查看原图 |
| 排版 | 查看原图 | 查看原图 |
图版展示内置主题、标准密度与当前默认字体设置。色值来自浏览器计算结果；透明色标出不透明度，必须结合所在背景理解。文字示例和间距方块放大两倍以便观察，旁边标注的是实际 CSS 尺寸，不是图片像素。图版自身的标题、边距和画布不构成产品 token。
规范与实现的关系
Section titled “规范与实现的关系”用角色，不复制图中的数值。 Token（设计变量）是有明确用途的命名值，例如 --ink-soft 表示次要文字；组件通过 var(...) 使用它。主题或用户偏好可以改变最终数值，但不应改变该角色的含义。
| 来源 | 负责内容 |
|---|---|
| base.css | 颜色角色、浅色默认值、圆角、阴影、字重与动效 |
| theme.css | 深色覆盖，包括文字、表面和阴影配方 |
| spacing.css | 间距角色、密度边界、窄屏内缩与触控尺寸下限 |
| appearance.css | 实际 UI 字号比例、独立代码字号与图标尺寸 |
| AppearancePreferences.ts、protocol | 字体、字号偏好与运行时默认值 |
| 共享组件与预览 | 控件行为、键盘操作、真实状态与验收入口 |
这些是内部 renderer 角色，不是全部对外承诺的 API。扩展作者使用公开主题契约，不要把内部变量当成稳定扩展接口。文档描述用途，代码定义数值，图版是代码的可再生视图；三者发生差异时先核实实际级联和用户设置，再同步修正，不能只改图上的标签。
提供完整的选择，不把视觉细节变成调参面板。用户选择外壳皮肤（皮肤能显示图片时可选本地图片）、内容主题、深浅模式与可读的字体；没有安装额外内容主题时隐藏对应选择器。模糊、图片浓度、裁切位置、材质、圆角与阴影由产品设计统一决定。已保存的图片采用当前处理方式。无障碍偏好保持独立。
品牌识别与强调
Section titled “品牌识别与强调”Wuu 以黑白与中性色为品牌基础，不强制指定一种标志性色相。黑白应用图标、统一的形状、排版和留白共同建立识别。中性不意味着把界面铺成一片灰：通过清晰的明暗对比和信息层级保持可读，浅色与深色主题表达相同的角色。
外框与收起、展开的 ribbon 共用一张连续皮肤。内部圆角画布默认保持不透明：导航、对话和工作区在浅色模式共用 #fcfcfd，深色模式共用炭灰。外壳皮肤也可以把图片铺入画布——侧栏与对话区域在任何状态下都透出同一层遮罩，其他目的地各自决定透出多少图片，浮动面板使用宿主玻璃材质。相邻的大面积区域保持连续，由抬升的内容与内嵌分组建立明暗层次。内容导航使用中性填充选中态，标签保持常规字重。皮肤的色彩和图片不侵入内容主题；自定义主题仍可通过公开变量覆盖颜色与控件外观。
浅色表面使用略带冷调的画布与中性的辅助色阶：#fcfcfd 纸面（--paper，使用 --gray-25）、#ffffff 抬升阅读表面（--surface-raised）、#f5f5f5 次级表面和 #151515 强文字。深色使用 #191a1c 纸面、逐级变亮的炭灰表面和 #e0e1e3 强文字。深色文字不逼近纯白：正文约为 #cbccd0，次要文字约为 #adaeb2，避免浅色字形在炭灰画布上发晕、压缩层级。浅色选中态单独使用略冷的 #d9dce1，让导航位置明确，而不为整个阅读画布染色。
本地壁纸是图片而不是皮肤：默认外框和接受它的皮肤会用它替换自带图片。每种摆放方式各有一套统一处理：外框中居中铺满、高斯模糊，并自动适配深浅模式的对比度；画布中保持清晰，只做较宽松的亮度约束，格点网格由皮肤决定。原色已能承载清晰文字时予以保留。图片在 worker 中处理，原生 ribbon 复用外框使用的同一栅格。插件皮肤提供完成后的图片与前景配色；没有图片时，默认外框也应完整可用。
导航栏中的选中是唯一的位置信号，标签保持常规字重；两种主题都使用与导航底色明确区分的填充行。工具选择列表仅在悬停或按下时填充背景。用户自己的消息与对话输入框共用抬升阅读表面。消息通过细边线与短而轻的 --shadow-soft 阴影和画布区分；输入框保留自己的 --shadow-composer 层级。通栏消息卡片及其内联编辑框使用共享面板圆角，让已发送的问题保持清晰，又不形成厚重的灰色条带；主题仍可覆盖消息的底色、边框、阴影与圆角。回答中的代码是比画布低一级色调的嵌入区域，不加边框；在填充之上再加边框会把同一条边界画两次。行内代码在回答和用户消息里都使用同一级色调的小底块，这样标识符在中文正文里仍然好找；只换成等宽字体的文字，看起来像字体回退。工具行的动词使用 --ink-tertiary，对象（文件、搜索词或命令）介于它和正文墨色之间，一串工具行按“动了什么”扫读，又不会和回答争夺注意力。
品牌识别、操作强调和状态表达是三件不同的事。主要操作可以通过前景与背景的强对比突出，不必使用高饱和品牌色填充。链接、键盘焦点和选中需要明确的交互提示；成功、警告和危险需要不同的含义。颜色服务于这些用途，不为每个标题或选中项增加装饰。必要的区别不能只依赖颜色。
输入框保持稳定的纸色。次要按钮使用 --control-secondary-bg 和轻控件阴影，悬停使用 --control-secondary-hover-bg。菜单、提示和浮动面板共用 --menu-bg、接近不透明的 --surface-floating 与 --surface-blur。内容卡片和阅读区域保持不透明。轻量文字操作和图标操作在交互前保持无容器。宿主与扩展控件使用同一组角色。
| 角色 | 变量 | 使用规则 |
|---|---|---|
| 画布与表面 | --paper、--surface-raised、--surface-1 至 --surface-4 | 区分阅读底色、抬升的消息和输入框、次级与强调表面；表面编号不等于阴影高度 |
| 文字 | --ink-strong、--ink、--ink-soft | 重要信息、正文、次要说明；正文保持易读，不把所有文字加粗 |
| 弱化文字 | --ink-tertiary、--ink-muted、--ink-faint | --ink-tertiary 是文字可用的最弱一档，对比度保持在 4.5:1 以上；--ink-muted 用于图标、箭头和禁用标记，--ink-faint 用于不承载信息的标记；不能用弱对比解决布局拥挤 |
| 占位符 | --placeholder-ink | 输入框里的示例文字，由 ::placeholder 统一设置，字段不再各自取色；区别于已输入的文字和标签，对比度在 4.5:1 以上 |
| 三档线条 | --hairline-soft、--hairline、--hairline-strong | 同一表面内分隔、独立容器边界、较强控件边界；不为每条线创建灰色 |
| 功能边界与焦点 | --control-boundary、--focus-ring | 表达可操作边界和键盘焦点，与装饰分隔线区分 |
| 选中 | --selection-surface | 使用明确的选中底色，不借用警告或成功色 |
| 状态 | --success、--warning、--danger、--info | 成功、注意、危险和信息；配合文字或图标，不只靠颜色区分。所有界面里的 diff 新增与删除都取自 --success 和 --danger |
成功、警告和危险的轻底色分别为 --success-soft、--warning-soft、--danger-soft。状态色不是通用正文色，也不保证在任意填充背景上可读。彩色填充上的文字使用适用的 --ink-on-accent 等角色，并检查实际组合。深色主题不是把浅色反相：它单独调整表面、文字和状态色。
当前实现的强调色
Section titled “当前实现的强调色”Renderer 默认采用中性强调色：--wuu-accent 跟随主题的强正文色（浅色主题为深色，深色主题为浅色），--wuu-accent-press 向画布色混合。滑块通过 --interaction-accent 使用同一强调色。扩展主题仍可覆盖公开的强调色、按下态和强调色表面内容色变量。
--info 和焦点环共用一种蓝色：macOS 链接色，即平台自身可用于文字的蓝色（两种主题下在画布和用户气泡上均不低于 4.5:1）。它是默认内容界面的交互色相；外壳图片可采用自己的配色。
渲染后的 Markdown（回答、用户消息和文件预览）中，链接使用蓝色信息角色和轻下划线，悬停时强化下划线。颜色与下划线共同让正文中的链接易于辨认。链接前的文件、网站或站点图标使用 --ink-muted，与文字留出小间距，下划线不会延伸到图标下方。主题仍可通过 --wuu-color-link 为链接着色。
强调色与状态语义分开。TODO 进度使用正文色和不同形状的标记，上下文高占用使用警告色。成功、警告、危险及焦点保留各自的语义颜色，不随强调色一起变成中性色。
使用系统 UI 字体及中文回退；允许用户选择字体。正文字体默认跟随界面，也可单独用于消息、草稿与 Markdown 预览，不改变导航和控件字体。代码、编辑器和 diff 保持独立的等宽字体与字号，不按 UI 字号机械放大。不要为标题、正文和数字引入互不相关的字体体系；对齐数字时按场景选择等宽数字或等宽字体。
当前运行时 UI 默认值为 15px，代码为 13px。appearance.css 的比例分母是 14，因此 14px 是比例参考点，不等于当前启动默认值。已有字号偏好优先；文档不要求把用户设置重置为默认值。
| 角色 | 变量 | 与 UI 基线 U 的关系 | U = 15px 时取值 |
|---|---|---|---|
| 大标题 | --font-hero | round(U × 32 / 14) | 34px |
| 展示标题 | --font-display | round(U × 24 / 14) | 26px |
| 分区标题 | --font-heading | round(U × 20 / 14) | 21px |
| 小节标题 | --font-title | round(U × 16 / 14) | 17px |
| 界面与正文 | --font-ui、--font-body、--font-content | U | 15px |
| 菜单 | --font-menu | U | 15px |
| 紧凑文字 | --font-sm | round(U × 13 / 14) | 14px |
| 辅助信息 | --font-xs | max(12px, round(U × 12 / 14)) | 13px |
| 代码 | --appearance-code-size | 独立偏好 | 13px |
派生角色取整到整数像素。保存的 UI 字号可以是半像素档位，但派生出的小数字号会让行框和 1px 边线落在设备像素之间。
常规文字和菜单选项用 400，必要的标题与强调选择 500 或 600；700 留给少量强强调。消息内强调使用 600。macOS 默认采用系统字体平滑，外观设置可切换为灰度平滑。增加强调字重前，先检查两种主题下常规文字的效果。基础行高角色为 UI 1.45、正文 1.55、辅助信息 1.6；具体阅读面可有自己的语义行高，不代表所有组件强制使用同一行高。对话阅读与过程记录的行高是由消息字号派生的整数像素长度（均为 1.6 倍，取整到 2px），相邻行与卡片因此共享边线。输入框草稿与已发送的提问、回答使用同一阅读行高，文字发送前后保持相同的节奏。消息内标题依次为正文的 1.5、1.25、1.1 倍并取整，层级不只依赖字重。默认对话正文为 15px/24px，段距为 16px；段距使用下文按基础模数对齐的一个字宽间距角色。围栏代码、悬浮 diff 与代码编辑器共用独立代码字号，行高为其 1.5 倍并取整到 1px，默认为 13px/20px。行内代码保持所在正文字号的 0.92 倍。保留字体自然字距，不缩字或压字距来补救布局。
最新的活动过程标签使用随主题变化的淡色，首次延迟 600ms 后，在每四秒周期内扫光一秒；装饰高光下的底字始终可见。摘要不再处于活动状态后使用稳定的 --ink-tertiary。减少动态效果、后台会话和流式跟随时隐藏高光；结果正文保持原有对比度。
间距模数取已保存 UI 字号的四分之一，四舍五入到整数像素，再乘以密度得到 --space-1。默认 15px 字号下仍为 4px，阶梯为 4、8、12、16、20、24、32px，对应 --space-1/2/3/4/5/6/8；20px 字号下模数为 5px。主题仍可显式指定 --wuu-space-unit。半字、一字、两字的间距关系因此共用一套网格。优先选择语义角色；判断可见留白时，应计入行框的上下留白和控件的真实占位。
| 关系 | 变量 | 标准密度 |
|---|---|---|
| 面板边缘到首尾字形 | --pane-inset | 20px |
| 页面内缩 | --page-padding | 32px |
| 分组到分组，包括最新一轮对话到输入框 | --section-gap | 32px |
| 标题到内容 | --section-heading-gap | 12px |
| 卡片、面板内缩 | --card-padding、--panel-padding | 16px、20px |
| 紧凑区域纵向、横向内缩 | --compact-padding-block、--compact-padding-inline | 8px、12px |
| 控件纵向、横向内缩 | --control-padding-block、--control-padding-inline | 4px、12px |
| 菜单内缩、选项间距 | --menu-inset、--menu-item-gap | 6px、8px |
响应式布局保留这些间距角色，并根据面板的可用宽度重排内容与控件。表单和菜单行的共享高度下限为 36px，粗指针下为 44px，并向上取整到 4px 网格。字号或内容增长时，实际高度应继续增长，不能用固定高度裁字。以上是共享字段与菜单行的尺寸角色，并非所有图标按钮的统一尺寸。
侧栏同级行之间使用一个模数，标题到内容使用两个模数，功能组之间使用六个模数。置顶组末尾的拖放区独占组间留白，不再额外叠加。对话段落之间使用四个模数，列表项、标题到内容使用两个模数，新标题或下一轮对话使用八个模数。处理状态标题到首条详情使用两个模数，过程记录与最终回答之间使用六个模数。消息框和输入框共用文字内缩与阅读行高。设置页标题到内容使用三个模数，设置行上下内缩使用四个模数，标签到说明使用一个模数，分区之间使用八个模数。设置导航复用同级行间距；导航自身的顶部外边距为两个模数，导航组之间为六个模数。已连接服务的名称到说明、服务目录的行间距均使用一个模数，目录选项上下内缩也使用一个模数。
设置分区分别管理标题和内容：标题到内容使用三个模数，内容内部的同级块使用四个模数。主题预览与背景控件、字体控件与字体平滑控件因此既保持关联，又不会挤在一起。内联表单的字段到提交操作使用四个模数。服务目录和订阅卡片的内缩、块间距使用四个模数，标签到字段使用两个模数。用量表格复用设置行内缩，模型名、归档标题与各自说明之间使用一个模数。用量表格在不足 36 个 UI 字宽时折行，使大字号也有同样的阅读空间。已连接服务与服务目录共用八个模数的图标占位、三个模数的图文间距（模数为 4px 时分别为 32px 和 12px）。图形本身独立随 UI 字号缩放，让增加的空间保留为留白。已连接行使用八个模数的水平内缩。推荐服务目录先将内容宽度等分为最多三列，再为每格设置四个模数的左右内缩，由格内留白承担列间距。每列的图标与文字起点固定，不随名称长度或末行条目不足而移动。目录内容宽度不足 39、26 个 UI 字宽时，分别切换为两列、一列。两个分区共用图文比例，在各自的可用区域内排布，通过行高与次要文字表达不同的信息密度。图表单元的几何关系和图标的光学补偿仍由各自角色管理。
看起来对齐的边，必须来自同一个共享角色，而不是几个分别调过、恰好接近的数值。
- 面板边缘。 侧栏行、标题栏、标签栏等界面框架行中，首尾可见字形距离面板边缘
--pane-inset。侧栏贴着窗口边缘时再增加一个间距模块，因为方正的中文字形侧面留白很小；导航栏占据该边缘时，紧凑的次级面板沿用基础缩进。对齐的是字形，不是按钮盒：按钮盒大于字形的控件要减去自己的光学偏移，例如工具栏按钮使用--control-toolbar-glyph-offset。侧栏、工作区标签、文件树、审查列表和工具列表中悬浮在面板内的行，由列表内边距和行自身内边距共同组成这段缩进：悬停底色与边缘留出间距，字形仍落在面板边缘缩进上。 - 阅读列。 无框内容（段落、标题、列表、过程记录、回答操作）共用阅读列的起始边。消息表格没有左右边框，首尾列文字也从这条边开始。
- 带框内容。 代码块、输入框、消息气泡和阅读卡片中，文字与图标字形距离外边缘
--card-padding；边框计入这段距离。因此代码块的语言标签、代码与输入框文字共用同一条轴。紧凑入口卡片采用下文的密度角色。提问气泡与输入框草稿在文字上下也保持这段距离：纵向内边距扣除行高带来的半行距（不小于 8px），任何字号下字形到边框的距离都一致。 - 附属操作列。 侧栏尾部大小不同的附属操作共用一条中心轴。分组标题无论是否带操作，都预留操作的占位，分组间距不因哪些标题有「+」而变化。
同级标签、图标列、尾部操作对齐；缩进表达层级，不因运行或未读状态改变。给状态标记、操作按钮及阅读间隙预留真实空间。每一段间距只由一层负责，避免 wrapper、子元素 margin、空拖拽区重复叠加。阅读列使用适用的最大宽度角色（如 --content-column-width），不是让所有页面强制同宽。
| 角色 | 变量 | 默认值 |
|---|---|---|
| 内层高亮、菜单行、紧凑芯片、媒体 | --radius-xs、--radius-media | 6px |
| 控件 | --radius-sm | 10px |
| 面板、消息流内嵌卡片 | --radius-md、--message-flow-card-radius | 12px |
| 大面积表面 | --radius-lg | 20px |
| 窗口内衬画布 | --conversation-canvas-radius | 原生窗口圆角 − 画布内缩；macOS：约 16pt − 4.8pt = 11.2pt |
| 会话输入区 | --session-composer-radius | 24px |
| 紧凑菜单外壳 | --menu-shell-radius | 内层圆角 + 菜单内缩，标准为 12px |
| 面板式浮层、对话框 | --menu-radius | 默认跟随面板，主题可覆盖 |
| 胶囊、圆形 | --radius-pill、--radius-circle | 999px、50% |
圆角随占位大小分工：普通字段和按钮用 10px，分组卡片用 12px，大面积阅读表面用更大的圆角。紧凑菜单外壳由 6px 行圆角和 6px 内缩组成。macOS 桌面端以实测约 16pt 的原生外角为基准，取其中 30% 作为边带，得到 4.8pt 内缩和 11.2pt 画布圆角。两个 CSS 长度都除以页面缩放比例，使大字号和窄窗口保留这一几何关系。右上、右下角在相邻两边内缩相等时与原生外角近似同心；导航栏使左边缘有更大的偏移，因此不能将同心关系概括到窗口四角。保留现有 1px 画布细线、外壳材质和原生窗口形状。这是窗口几何，不是产品圆角角色；系统窗口样式变化时应通过原生截图重新核对约 16pt 的轮廓。会话输入区使用完整的圆角面板，在所有宽度下都保持文字在上、工具栏在下；草稿随内容增长，到可用高度上限后内部滚动。空白首页将吉祥物和系统字体问候语居中放在同一输入区上方。胶囊适用于开关轨道和徽标，圆形适用于头像、圆点和旋钮。
层级按用途选择 --shadow-soft（轻控件）、--shadow-card（卡片）、--shadow-composer（输入区）、--shadow-pop（浮层）、--shadow-modal（对话框）。贴边托盘和抽屉使用有方向的角色。浅色使用克制的环境阴影；深色在控件和输入区结合轻微的上缘高亮与短黑色阴影，浮层保留更宽的环境阴影。悬停、聚焦和展开不自动升级阴影；平面内容不为了「卡片感」到处加阴影。
关联会话入口、生成文件和回合末尾的产物摘要共用 --message-flow-card-* 圆角、边框、表面与悬停角色。外框使用轻量的 1px 边线，不额外抬高层级；媒体仍使用原有媒体圆角。横向内缩复用紧凑间距，前导图标使用 --icon-size-xl。为尾部操作预留空间，长名称截断时不挤动入口。
密度随内容决定。会话入口为单行，保留 roomy 控件的最小高度；消息正文独立阅读和选择。文件以 UI 字体的文件名为主标题，下一行显示简短格式与已知字节大小，两行间保持小间距。缺失大小时直接省略，不猜测。单文件及不超过三个文件的组不重复显示标题。更大的文件组每次展示三行，在列表底部显示总数和未展开数，每次展开最多增加三个文件。箭头进入内部预览或工作区视图。托管文件的右键菜单提供原生文件操作：macOS 关联应用、另存为，以及在文件管理器显示导出的副本。外部编辑器不会直接修改不可变的交付快照。
图标、动效与控件
Section titled “图标、动效与控件”控件复用 WuuIcons，不混用另一套线条风格。标准图形基于 24 单位画布与 1.75 描边；尺寸使用 --icon-size-* 角色并随字号有限增长，并取整到偶数像素，使字形在偶数尺寸的控件中居中。UI 参考值 14px 时，各档为 12、14、16、18、20px；默认 15px 时为 12、16、18、20、22px；视觉尺寸、居中与线条密度仍需实际检查。
动效服务于反馈和位置变化：--motion-fast 120ms 用于即时反馈，--motion-base 180ms 用于菜单与内容切换，--motion-slow 280ms 用于结构位移，--motion-slower 440ms 用于较大的折叠。入场以 --ease-out 减速进入，退出以 --ease-in 加速离开，且比入场更短。优先使用已有语义别名，以及桌面 UI 维护中介绍的共享入场、退出 keyframe。系统设置与应用内“动态效果”偏好都会减少动态效果，且效果相同。不要让高频操作等待装饰动画，也不要自行覆盖组件中已有的专用动效契约。
复用现有 SelectMenu、SettingsRow、Modal 和对应样式；设置页由 SettingsPageHeader、SettingsSection、SettingsGroup 与 SettingsEmptyState 组合而成：列表为空时在卡片内渲染空状态——说明这里会出现什么、可选地说明它如何出现、以及填满它的那一个操作——而不是加边框的占位块或一行灰字；共享按钮、输入框使用既有样式角色，不复制一份私有实现。控件必须有可访问名称，并按用途支持悬停、按下、选中、禁用、键盘焦点和错误状态；加载状态保留位置与尺寸。相应状态只能在语义适用时组合，不能把选中和按下混为一谈。
键盘焦点使用共享的 2px --focus-ring 机制，鼠标点击不额外增加一圈边框。菜单应支持键盘移动、选择、退出和焦点返回；对话框使用共享焦点管理。错误提示靠近对应字段并说明恢复办法；图标不能代替必要的文字说明。
普通文字以至少 4.5:1、大字至少 3:1、必要的控件边界与状态指示至少 3:1 为对比度验收目标；装饰分隔线不等同于功能边界。图版列出实际 token，不代表每个颜色配对都已达到该目标，也不构成全产品无障碍认证。
修改组件后，按桌面 UI 维护检查浅深主题、默认与大字号、宽窄窗口、长与空内容、滚动、固定区域及共存状态；检查截断、重叠、点击目标和键盘焦点。静态图版用于沟通基础，不替代真实组件与交互验收。
更新基础变量时，同时维护两种语言的规范与图版。在仓库根目录运行：
node desktop/scripts/generate-design-system.cjsmake docs-policy-checkmake build-docs生成器使用已安装的桌面 Electron 与 esbuild，加载四个基础样式层，并从运行时代码应用默认字号与字体。它使用临时 profile，不读取产品账户或保存个人偏好。生成的六张 PNG 保存在 docs/en/assets/design-system/，两种语言共同引用；不要直接涂改图中的数值。需要图形环境，字体字形会受生成平台影响，因此应在同一平台检查再生差异。
新增组件先找现有角色和共享实现，只有重复出现且语义不同的需求才增加变量。评审依据是用途、用户偏好、实际状态与可读性，而不是是否与某张参考图像素相同。