Skip to content

DESIGN.md

Latest commit

 

History

History
98 lines (72 loc) · 9.18 KB

DESIGN.md

File metadata and controls

98 lines (72 loc) · 9.18 KB
Raw

LambChat 前端设计系统

本文件是 LambChat 前端视觉与交互实现的项目级基线。所有新页面、组件和 UI 改动都必须先阅读本文件，并优先复用现有组件与设计 token，而不是另起一套视觉语言。

产品气质

LambChat 是面向 Agent 工作流的专业生产力产品。界面应当克制、清晰、可信，突出内容与任务状态，而不是装饰。优先级为：可读性 > 信息层级 > 操作效率 > 装饰性。

视觉原则

  • 使用现有主题 token（尤其是 --theme-primary 及相关 CSS 变量），不要在组件中硬编码品牌色。
  • 深色和浅色主题都必须可读；文字、边框、图标和状态色满足可感知对比度。
  • 通过字号、字重、间距和色彩建立层级，避免依赖大面积渐变、阴影或动画。
  • 优先使用单层容器；只有在信息结构确实需要时才使用卡片，避免嵌套卡片和重复边框。
  • 保持圆角、间距、控件高度和图标尺寸的一致性，优先复用既有 primitive。
  • Header 功能图标和文字在手机、桌面均统一为 16px，头像及品牌图形保持各自原尺寸；图标按钮点击区分别为 36px / 32px。模型名、用量等文字按钮保持内容宽度并统一高度，侧栏顶部使用同一套尺寸。所有平台的侧栏展开、收起按钮统一复用 SidebarToggleIcon，使用与其他功能按钮同套的 Lucide PanelLeft 图标，并复用 InteractiveIcon 的悬停、点击和键盘聚焦动效。
  • 密集图标操作（聊天工具栏、消息操作、面板工具栏、侧栏行内操作）在窄屏统一使用 36px 占位，避免用通配按钮规则撑到 44px；菜单行、表单主操作和搜索控件保留 44px。角落帮助入口贴近视口安全边界，桌面 32px、手机 36px，不额外叠加外边距。
  • 弹窗外壳、移动端拖拽条和底部操作区统一使用 --theme-bg-card（bg-theme-bg-card），不要再叠加写死的 dark:bg-stone-* 或半透明底色；输入框、选项和内容卡片可保留语义层次。
  • 避免无意义的 pill、侧边标签、斜体衬线标题、装饰性 emoji、自动播放动效和强烈玻璃拟态。

布局与响应式

  • 先定义内容宽度、主次栏关系和窄屏行为，再写 CSS。
  • 桌面、平板、移动端都要验证；不能只依赖桌面截图。
  • 长文本、工具结果、代码、图片和错误状态必须有明确的溢出与折行策略。
  • 交互控件必须有足够的点击区域；移动端不依赖 hover 才能完成关键操作。

交互与状态

  • 每个异步操作至少考虑 loading、success、empty、error 和 disabled 状态。
  • 状态变化应靠文字、图标或结构共同表达，不能只靠颜色。
  • 动效只用于反馈、层级变化和空间连续性；短、可打断、尊重 prefers-reduced-motion。
  • 键盘焦点必须清晰可见；弹层、折叠区和菜单需要正确的语义与关闭路径。

组件实现

  • 先搜索并复用 frontend/src/components、frontend/src/styles 和现有 token。
  • 新增组件前说明它解决的独立问题，避免为单一场景创建重复 primitive。
  • UI 文案必须进入 zh / en / ja / ko / ru 五个 locale，不在组件中散落面向用户的硬编码文本。
  • 图标使用现有 lucide 约定，保持尺寸、描边和透明度一致。可交互图标复用 InteractiveIcon 的悬停、点击和聚焦动效；无对应动效版本时保留图形并使用轻微缩放反馈。加载、展开等状态动画保留原逻辑，所有动效尊重系统减少动态效果设置。
  • 尺寸描述中的 px 为标准字号下的基准。界面图标、加载图标和相邻控件使用 rem，跟随全局字体档位缩放；Lucide 数字 size 由 icon-scale.css 兼容，新增尺寸同步该表。动效图标外层也需保持相同尺寸。头像、品牌图形、插画和图表保留各自尺寸规则。
  • 弹窗和底部弹层的右上角关闭入口复用 DialogCloseButton：18px 细线 ×，默认无底色、边框和阴影，悬停与焦点使用主题反馈；桌面点击区 32px，窄屏与触控设备 44px。复用 common.close 标签，繁忙状态保留禁用约束。
  • 组件测试优先验证用户可观察行为；复杂视觉规则可补充源码结构测试。

Markdown 阅读排版

  • 聊天和文件预览复用 MarkdownContent，正文排版集中在 frontend/src/styles/markdown.css 的 .markdown-prose，不要在节点里叠加独立颜色、字重和间距。
  • 正文沿用无衬线字体，桌面 15px、移动端（≤640px）16px，行高 1.75／1.7；正文、用户消息和输入框共用 --chat-font-size，字号使用 rem，跟随全局字体缩放。
  • H1–H6 使用 24／20／18／16／15／14px，字重 600；强调文字同样为 600，其余正文为 400。标题上方 0.75em、下方 0.375em，首个标题无顶部留白。
  • 正文、表格、行内代码统一使用主题次级文字色；链接使用可辨识的主题信息色和下划线。深浅色与暖色主题使用同一语义规则。
  • 行内代码保持紧凑灰底、小圆角和单层内边距，使用等宽字体、正文的 0.9em 与正常字重；代码块使用 13px，保留语法高亮、搜索与复制。
  • 表格正文 14px、表头 13px／500，首列不自动加粗；数字遵守 Markdown 列对齐，窄屏在表格内横向滚动。
  • 列表标记在正文外侧，换行保持对齐并保留起始编号；引用使用细边线，不强制斜体或彩色底；分隔线使用主题边框色。

交付检查

提交前逐项检查：

  1. 是否沿用了 DESIGN.md、PRODUCT.md 和现有组件，而不是重新发明视觉系统？
  2. 浅色/深色主题、窄屏、长文本和空/错/加载状态是否可用？
  3. 键盘焦点、语义标签、对比度和 reduced motion 是否处理？
  4. 是否避免不必要的渐变、嵌套卡片、过度圆角和无目的动效？
  5. 是否同步五种 locale，并运行前端测试、lint 和 build？
  6. 若已安装 Impeccable，是否运行对应检查器并修复报告的问题？

Impeccable 使用约定

优先使用 Impeccable 的项目级设计指导和检查器：

npx impeccable install
/impeccable init
npx impeccable update

网络或运行环境不允许时，以本文件和 PRODUCT.md 为准，使用上面的交付检查清单完成等价人工检查。Impeccable 是辅助工具，不替代项目现有的 TypeScript、测试、lint、无障碍和构建门禁。

Panel 组件约定

  • 页头复用 PanelHeader，标题、搜索、筛选和主操作保持同一层级。窄屏将辅助操作收进菜单，保留搜索；菜单支持 Escape 关闭并归还焦点。

  • 资源卡片复用 SkillBaseCard / scb 样式，以现有名称配色作为轻量底色和图标识别；状态、描述、标签与操作分层，长标题允许两行。文件、表格、统计图保留适合内容的呈现形式。

  • 列表统一使用 Pagination 和 panel-pagination 页脚。前端全量列表复用 useClientPagination；服务端分页沿用接口页尺寸。文件按会话分组分页，不拆散同组文件。

  • 筛选变化回到第一页；总数减少时收敛到有效页。不要在调用方根据总数卸载 Pagination，由组件隐藏单页导航并完成页码校正。翻页回到内容顶部。

  • 分页随容器宽度切换：宽面板显示数量范围和页码，窄面板显示当前页/总页数与上一页、下一页，触控区域至少 44px。

  • 滚动内容与页脚分离，父级使用 min-h-0 / min-w-0，避免页面底部操作被长列表挤出视口。

  • 本地大数据量走查入口与状态切换见 frontend/scripts/PANEL_PREVIEW.md。

  • 面板列表的空状态统一复用 common/EmptyState，调用方只提供图标、文案和可选操作，不另写图标容器或标题/说明间距。图标统一 20px、容器 40px；标题与图标相隔 16px，说明沿用共享样式。

Panel 间距与边界

  • 页面左右留白由 --panel-inset 统一控制：面板可用宽度小于 640px 时 12px、640–1023px 时 20px、1024px 起 28px；以面板容器宽度判断，不以窗口宽度推断。

  • 正文使用 panel-body，不要叠加各页的 px-* / py-*；工具栏、分组行复用 panel-inset。常规列表和卡片间距在窄面板为 8px、640px 起为 12px（panel-stack），独立内容分组分别为 16px / 20px（panel-sections）。

  • 页头、分页、卡片操作区优先用留白分层，不重复画横线。表格行、独立编辑区域及有语义的分组边界可以保留必要分隔。

  • 卡片列宽不得超过可用空间；窄面板菜单行和搜索控件至少 44px，图标菜单入口 36px，设置页在可用宽度小于 800px 时使用分类选择器。

  • Header、正文、分页必须共享同一左右边界。独立滚动正文使用稳定滚动条槽，由 observePanelWidths 测量原生滚动条宽度并同步到同级页头和页脚；不要硬编码滚动条像素宽度。新增独立滚动区域使用 panel-body overflow-y-auto 或 panel-scroll。

  • 工具栏到正文的留白由固定页头或工具栏底部的 --panel-gap 提供，正文不重复添加顶部 padding；滚动后仍保留这段留白，分行页头只在最后一行下方保留。