malganiswu/red-bean-nian-gao/red-bean-nian-gao-visual-language

red-bean-nian-gao 产品视觉规范 · Quiet Tool UI

本 Skill 是产品视觉规范的唯一事实来源：视觉语言核心、布局与响应式、图标、交互与无障碍、

系统状态。代码怎么写见

`../red-bean-nian-gao-frontend-coding-conventions/SKILL.md`；

组件怎么进册、怎么验收见 `../../design-system/AGENTS.md`。

落点：可运行的规范在 design-system/src/foundations/（Philosophy、Color、Typography、Spacing、 Radius、Shadow、Conversation）与 design-system/src/showcase/；token 的单一实现源是 design-system/src/styles/design-tokens.css；design-system/src/foundations/philosophyMarkdown.ts 是可下载的文字版本。本文件与它们冲突时以可运行的页面为准。

视觉语言核心

• Light 默认、Dark 对等：纯白 #FFFFFF / 近黑 #0B0B0C 阅读面，几何和行为完全一致
• 灰阶承担层级；Light 品牌文字 #99413C、品牌图形/选择/focus #C87972，Dark 对应角色均为

#C87972；品牌色仅用于身份、交互与确认动作

• 成功绿、失败鲜红，只表达状态；状态必须同时有文字或图标
• 默认使用 canonical 的 Inter + 系统无衬线栈；等宽字体只用于工具名、行内代码及展开后的

参数/结果/错误原文，目标、耗时与状态保持无衬线；字重按角色固定

• Final 与普通段落保持裸排；标题、列表、引用和表格依靠 Markdown 排版建立层级，只有 fenced

code block 使用带语言标签和复制动作的独立弱表面；Process、Tool 保持透明，用户消息使用随内容 收缩、受最大宽度约束的 muted 表面

• Process 是连续时间线：不显示 Think / Tool / Content 分类标签；完成节点实心，唯一进行中节点轻微呼吸
• 确认问答属于原 Process；Pending 常显，回答后原地收缩为「问题 + 回答」并继续，不拆成第二个过程
• 确认按钮无填充、无常驻边框，仅使用豆沙红文字；沿用 canonical 的 6px 0 紧凑内边距
• 圆角只保留 0 / 6 / 8 / 12；默认无阴影，仅浮层使用一档 0 8px 24px 阴影

布局与响应式

Quiet Tool UI 不为移动端创建另一套视觉。页面在相同信息层级下重排、折叠或转为抽屉。 断点是验证基线，不是允许按设备写两套 DOM 的理由。

基准：

• 内容区采用流式宽度；阅读正文建议最大 760px，管理列表建议最大 920–1040px。
• 4px 为基本节奏。相邻信息优先通过间距、文字层级和细分隔线分组。
• 不用多层卡片补偿布局不清晰；只有语义独立、可操作或可折叠的对象才使用容器。
• 固定元素必须为安全区和软键盘留出空间。

断点行为：

组件规则：

• RoundNav 在窄屏隐藏；当前版本不提供「第 N / M 轮」替代控件。若要新增，必须先做交互 Mock。
• Menu、Tooltip 与 Toast 不得超出视口，优先翻转定位，再限制最大宽度。
• Markdown 表格和代码块允许自身滚动，页面主体不产生水平滚动。
• Account 行先压缩用户名，不能挤压头像和展开按钮；菜单与触发器至少保持一边对齐。
• 定时任务列表先保留标题、生命周期和最近执行结果；来源、计划和次要时间按优先级换行或隐藏。

测试尺寸：至少目视检查 360 × 800、768 × 1024、1280 × 800 和 1440 × 900，并在 200% 页面 缩放下验证导航、浮层和固定操作区。

图标

图标帮助识别动作与状态，但不代替文字含义。Quiet Tool UI 使用轻量线性图标，品牌标记是唯一常规 填充图形。

系统图标：

• 优先使用现有 Lucide 图标，不引入第二套图标库。
• 常规尺寸 14 / 16 / 18 / 20px；默认描边 1.5–1.8px，同一区域保持一致。
• 图标继承文字颜色，不硬编码色值。成功、失败只在对应状态下使用语义色。
• 单独作为按钮时必须提供 aria-label 和至少 44px 命中区；与文字重复时设置 aria-hidden="true"。

品牌图标：

• 浏览器 favicon 使用红豆形：豆沙红豆身与深色豆脐，透明背景。
• Light / Dark 可以调整语义色以保持清晰，但轮廓、比例和构图不变。
• 小于 12px 时不再附加文字或外框。
• 品牌豆沙红只表达身份，不表示任务失败、告警或未读。

状态标记：

• 完成：绿色 + 对勾或「成功 / 已完成」。
• 失败：鲜红 + 错误图标或「失败」。
• 进行中：中性灰呼吸点 + 「进行中」；减弱动效模式改为静态圆点。
• 未读：豆沙红小点 + 可被辅助技术读取的未读文本；阅读状态与执行结果分离。

交互与无障碍

本节描述行为契约，不擅自改变已确认的视觉样式。需要调整 focus 外观、对比度或组件几何时， 先在 Preview 中评审。

键盘与焦点：

• 所有按钮、链接、输入、菜单项、折叠控制和单选项必须能用键盘到达。
• 使用 :focus-visible，焦点不能只靠颜色细微变化表达，也不能被 overflow 裁切。
• 复合控件使用符合语义的键盘模型：菜单支持方向键与 Escape；单选组使用方向键；折叠控件用

Enter / Space。

• 打开浮层后焦点进入可操作内容；关闭后回到触发器。页面切换后的焦点落在主标题或主内容起点。

命中区与文字：

• 主要触控目标最小为 44 × 44px；紧凑桌面控件可以视觉更小，但需要扩展可点击区域。
• 正文和必要元信息不低于 12px。10px 只允许非必要装饰，不承载状态、时间或操作结果。
• 长路径、URL、命令与连续字符必须在容器内换行或局部滚动，不得撑破页面。
• 文本、边界和 focus 对比度应满足 WCAG 2.2 AA；最终色值变化先走 Preview。

状态与反馈：

• 成功绿只表示成功，鲜红只表示失败或破坏性结果；必须同时出现文字或图标。
• 豆沙红表示品牌、选择、focus 与确认动作，不表示错误或任务健康度。
• Loading 使用明确文本或 aria-busy；完成、失败、复制结果等动态反馈使用合适的 live region。
• Disabled 与 loading 不混用：disabled 说明不可操作，loading 说明操作已接收且正在进行。
• 尊重 prefers-reduced-motion；呼吸点和过渡在减弱动效模式下停止或改为静态状态。
• hover 与 active 只改变颜色、边框或背景，不改变元素几何位置（位移、缩放、尺寸）。

内容与隐私：

• 图标按钮必须有可读名称；装饰图标使用 aria-hidden="true"。
• Account 示例只使用虚构身份：张三、san.zhang、san.zhang@example.com。
• 错误信息描述发生了什么和下一步动作，不暴露 token、绝对本机路径、密钥或内部堆栈。
• Process 展示可验证进展，不声称展示模型原始思维。

必测路径：每个交互组件至少检查键盘顺序、可见焦点、200% 缩放、360px 宽度、Light / Dark、 减弱动效、屏幕阅读器名称以及异步状态切换。

系统状态

系统状态必须回答三个问题：正在发生什么、用户能否继续、下一步是什么。页面不能用空白代替状态。

通用状态模型：

异步动作：

• 点击后立即进入 pending，保持按钮宽度与上下文，文案改为「正在…」。
• pending 期间禁止相同动作重复触发，但不应让整个页面失去可读性。
• 成功反馈尽量原位完成；需要跨页面保留时使用 Toast 或持久状态文本。
• 失败后恢复可操作状态，保留用户输入，并给出明确重试入口。
• 后台刷新保留旧内容，不退回全屏 loading；新旧状态需要可辨认但不制造告警感。

聊天状态矩阵：

• 空会话：说明可以输入什么，不伪造历史内容。
• 首事件等待：Process 出现稳定的进行中节点，并显示已等待时间；不反复插入新占位。
• 流式输出：已有内容保持可读，停止按钮独立于发送按钮。
• 请求失败：错误位于当前回合，提供重试与关闭；历史回合不受影响。
• QuestionCard pending：保持在原 Process 中且不可折叠隐藏；另一条流收尾时锁定输入但不误报

「正在提交」。

• Answered / refused：原地压缩为原问题和用户回答，随后在同一 Process 继续。
• 移动端：侧栏成为抽屉；聊天视图与会话任务视图切换不丢失滚动和选中状态。

定时任务状态矩阵：

• 任务生命周期：active / paused / ended。
• 执行结果：pending / running / completed / failed，与生命周期正交。
• 需要关注：由最近一次执行失败派生，不新增持久化任务状态。
• 未读：由后端记录用户对执行结果的阅读状态，刷新和跨设备后仍保持一致。
• 列表覆盖首次加载、继续加载、空列表、筛选无结果和失败重试。
• 详情覆盖 loading / error；执行记录覆盖 pending 或 running 时尚无过程内容的情况。

认证与个人页：

• 登录、注册和资料保存均覆盖 idle / submitting / field error / server error / success。
• 认证恢复期间使用稳定占位，避免先渲染未登录页再跳转。
• 资料更新失败保留原输入；成功消息不替代页面标题或字段标签。
• 超长邮箱、用户名、头像加载失败与移动端布局必须纳入验证。