nex_design_system/docs/01-project-audit.md

12 KiB
Raw Blame History

范围声明(NEX 0.1.2): 本文是 NexDocus 单一参考项目的历史代码审计,不是 NEX Core 规范,也不是其他项目的技术栈、Token、尺寸或页面模式基线。本文中出现的 React/Ant Design、颜色值、64px Header、260/80px 导航等,只描述该参考项目当时的实现事实。新项目必须先按 docs/00-governance-and-adaptation.md 完成自己的项目审计与映射。

01. NexDocus 前端设计审计

1. 审计范围与方法

本次检查了压缩包中的 frontend/,重点覆盖 package.json、全局样式、设计令牌、Ant Design 主题、主题 Store、应用路由、主布局、导航、公共组件以及 Dashboard、项目列表、聊天、文档阅读/编辑、登录和系统管理页面。

本次是静态源代码审计,不是在浏览器中逐页运行后的视觉验收。压缩包没有附带运行截图、设计稿或交互录屏,因此本报告对视觉效果的判断基于 CSS/JSX 的设计实现;响应式和真实像素观感还需在运行后确认。

2. 当前实际前端技术栈

项目 当前实现
UI 框架 React 18.2
构建工具 Vite 5
UI 组件库 Ant Design 5
路由 React Router 6
状态管理 Zustand 4
HTTP Axios
样式 普通 CSS + CSS Variables;不是 CSS Modules
Markdown ByteMD、React Markdown 等
PDF react-pdf / pdfjs-dist
语言 JavaScript / JSX

参考项目事实: NexDocus 当时采用 React + Ant Design 5 + 普通 CSS;TypeScript、Tailwind 和 CSS Modules 并非该项目当时的实际技术。该事实不构成其他项目的技术栈要求。

3. 值得保留的设计资产

3.1 已经存在基础设计令牌

src/styles/design-tokens.css 已经包含品牌色、状态色、文本、背景、边框、Markdown、间距、圆角、阴影、层级、过渡和布局尺寸,并提供 body.dark 覆盖。这是 NEX 可以直接继承的基础。

3.2 已经存在 Ant Design 主题集中配置

src/theme/antdTheme.js 对字体、主色、边框、按钮、输入框、卡片、Modal、Drawer、Table、Menu、Tag、Tooltip 和 Segmented 做了主题设置。说明项目已经有统一主题的意识。

3.3 公共页面模式已经初步形成

以下组件值得纳入 NEX 的第一批参考组件:

  • PageHeader:标题、说明、返回和操作区。
  • StatCard:指标卡片与趋势。
  • ListActionBar:操作、批量操作、搜索和筛选。
  • ListTable:表格选择、分页与选中信息。
  • ModernSidebar:可折叠导航、分组和用户区域。
  • LargeMarkdownViewer、VirtualPDFViewer、ProjectFileTree:专业工作区组件。

3.4 专业工作区有经过修正的布局经验

文档阅读、编辑和聊天页面都采用专用工作区,而不是普通滚动页面。代码中已经出现针对 Ant Design Sider/Flex 子项、内容区滚动和编辑器宽度的修复说明。NEX 必须保留这些经验:

  • 嵌套 Flex/Grid 子项在需要收缩时设置 min-width: 0 / min-height: 0。
  • 一个工作区只指定明确的主滚动容器,避免多个父子容器争抢滚动。
  • 工具栏、侧栏、编辑区和内容区的高度关系要明确。
  • 文档阅读与编辑共享同一阅读宽度规则,避免两种模式内容行长不一致。

3.5 全局可访问性基础

index.css 已提供 :focus-visible 和 prefers-reduced-motion 处理。这两项应保留并扩展,而不是在重构时删除。

4. 主要问题与规范漂移

A. 设计 token 与真实布局尺寸不一致(高优先级)

design-tokens.css 定义:

  • --header-height: 56px
  • --sider-width: 232px
  • --sider-collapsed-width: 64px

但当前运行组件的实际默认值是:

  • MainLayout/AppHeader.css:Header 高度 64px。
  • ModernSidebar.jsx:Sider 宽度 260px,折叠宽度 80px。

AppSider 没有覆盖这两个默认值,因此 token 与页面真实值存在漂移。AI 可能读到 token 后按 56/232/64 开发,但现有 UI 实际按 64/260/80 工作。

NexDocus 参考项目当时的处理建议(非通用规则): 0.1 版先以当前组件真实使用的 64px / 260px / 80px 作为基线,待结合运行截图确认后再调整;不得同时保留两套互相冲突的数字。

B. CSS 与 Ant Design 主题重复维护(高优先级)

品牌色、状态色、边框色和表格颜色同时存在于 CSS Variables 与 antdTheme.js。两处由人工分别维护,长期容易出现亮色/暗色、按钮/表格和自定义样式不一致。

NexDocus 参考项目当时的处理建议(非通用规则): 设计 token 必须有单一事实来源。CSS Variables 与 Ant Design Theme 应由同一份 token 数据生成,或至少由自动化一致性检查保证一致;禁止在两处独立调整同一个语义 token。

C. 页面级硬编码颜色较多(高优先级)

静态扫描 CSS(排除中央 design-tokens.css)发现约 204 处颜色字面量、约 143 种不同值,分布在 19 个样式文件中。颜色字面量并非全部错误,例如语法高亮或第三方品牌色可以保留;但品牌蓝、边框、背景、状态色和阴影不应在业务页面各自定义。

颜色字面量较多的文件包括:

  • pages/Chat/Chat.css
  • pages/ProjectList/ProjectList.css
  • components/ModeSwitch/ModeSwitch.css
  • pages/Profile/ProfilePage.css
  • pages/Login/Login.css

NexDocus 参考项目当时的处理建议(非通用规则): 新代码不允许新增普通 UI 颜色硬编码;旧代码分批迁移,不做一次性机械替换。语法高亮、文档内容、第三方品牌等例外必须局部隔离。

D. 组件与页面使用方式不够统一(高优先级)

项目已经有 PageHeader、StatCard、ListActionBar、ListTable 等共享组件,但业务页面仍大量直接组合 Ant Design 原生组件与页面私有 CSS。不同页面对搜索栏、标题区、统计卡片、表格容器和操作反馈的结构并不完全一致。

NexDocus 参考项目当时的处理建议(非通用规则): 建立有明确合同的页面级复合组件(例如 NexPageHeader、NexSearchToolbar、NexDataTable、NexStatCard),让常见业务页面调用标准组合。低频、无特殊主题的 Ant Design 基础组件不必全部二次封装。

E. 页面标题的视觉强调不分场景(中高优先级)

PageHeader.css 使用大面积蓝色渐变背景、装饰圆形和白色标题。它有鲜明识别度,适合欢迎页、概览页或需要强调的主页面;但若每个管理页面都使用,会让操作型页面过度强调标题、压缩有效内容空间,也容易形成“每页一个大横幅”的视觉疲劳。

NexDocus 参考项目当时的处理建议(非通用规则): 定义两种明确变体:

  • standard:中性背景、清晰标题/说明/操作区,是 CRUD、设置和系统管理页的默认方式。
  • hero:保留品牌渐变,只用于概览、欢迎或少量需要强调的页面。

F. 主题与字体系统存在重复定义(中高优先级)

App.css 与 antdTheme.js 使用的字体栈并不完全相同。部分页面还直接设置固定灰色、白色背景和固定状态色。随着暗色主题扩展,容易出现某些页面切换主题后仍保留浅色硬编码。

NexDocus 参考项目当时的处理建议(非通用规则): 统一一份全局字体令牌;颜色一律使用语义 token。暗色主题的覆盖必须在基础 token 层完成,而不是散落在业务 CSS 的 body.dark 选择器里。

G. 部分 CSS 选择器疑似无效(需要修正)

components/ListActionBar/ListActionBar.css 使用了 :global(...) 选择器,但文件是普通 .css,不是 CSS Module(项目也没有将该文件配置成 CSS Modules)。:global 是 CSS Modules 的作用域语法,不是普通浏览器 CSS 的标准伪类;相关选择器很可能不会按预期生效。

NexDocus 参考项目当时的处理建议(非通用规则): 普通 CSS 文件直接使用 .list-action-bar-right .ant-space-compact ... 等普通选择器;只有 .module.css 才允许使用 CSS Modules 语法。

H. 交互元素的语义和键盘操作不足(中高优先级)

导航菜单项、Header 图标操作等位置存在使用 div 承载点击事件的实现。鼠标操作可用不代表键盘可访问,也不具备原生按钮/链接语义。

NexDocus 参考项目当时的处理建议(非通用规则): 导航用 button 或 a;动作使用 button;跳转使用 Link;需要自定义外观时用 CSS 重置原生控件,而不是把可点击 div 当按钮。

I. 固定高度可能限制视口适配(中优先级)

ListTable.css 中表格容器使用固定 height: 626px。项目卡片使用固定高度 236px。卡片统一高度可以是有意的视觉决策,但表格容器高度应基于视口和布局弹性计算,而不是对所有显示器固定 626px。

NexDocus 参考项目当时的处理建议(非通用规则): 列表区域采用可伸缩高度、最大高度或父容器约束;表格滚动归属必须清楚。固定高度只有在明确的内容卡片模式中才可使用。

J. 文档说明和当前实际依赖不一致(中优先级)

frontend/README.md 描述 Tailwind CSS + CSS Modules,并提到 @uiw/react-md-editor;但当前 package.json 未包含 Tailwind 或该 Markdown Editor 依赖,项目样式以普通 CSS 为主,Markdown 相关实现使用 ByteMD 等依赖。

NexDocus 参考项目当时的处理建议(非通用规则): README、项目配置和真实依赖必须同步。Agent 不得把 README 中过期描述当作新增依赖的依据。

K. 质量检查脚本尚未覆盖 UI 回归(中优先级)

当前 package scripts 包含 dev/build/lint/lint:strict,但没有独立的前端测试、视觉回归或主题截图检查脚本。

NexDocus 参考项目当时的处理建议(非通用规则): 第一阶段保留现有脚本;后续为核心共享组件加入组件测试和 Playwright 视觉基线。不得在没有安装/配置时声称这些测试已经执行。

5. 推荐处理优先级

优先级 问题 处理方式
P0 token 与真实布局尺寸冲突 统一 Header/Sider 尺寸事实来源
P0 CSS 与 AntD 主题重复维护 建立单一 token 来源
P0 普通 CSS 中的 :global 改成有效的普通 CSS 选择器
P1 业务页颜色硬编码 建立语义 token,分批迁移
P1 共享页面模式未全面采用 先统一列表/表单/详情复合组件
P1 点击 div 的键盘可达性 更换为语义化 button/link
P1 标题 Banner 使用范围不清 标准页头与 Hero 页头分离
P2 固定表格高度与响应式细节 结合视口和真实页面调整
P2 README 与依赖漂移 修订项目文档和 Agent 入口
P2 缺少视觉回归 建立核心页面截图基线

6. 本次不建议做的事情

  • 不建议把所有页面统一改成相同的卡片堆叠样式。
  • 不建议把文档编辑器、聊天工作区强制改造成普通后台表格页面。
  • 不建议仅凭源代码就擅自换掉目前的品牌蓝和整体视觉路线。
  • 不建议为了“统一”而给每个 Ant Design 原生组件都创建一层无差异的包装。
  • 不建议一次性替换所有 CSS 颜色;应先确定 token 语义再迁移。
  • 不建议在 NEX 规范确立前直接重写整个前端。

7. 总体判断

NexDocus 已经有可复用的视觉基础和一批成熟的专业工作区组件,问题不是“没有设计”,而是设计决策分散在 token、Ant Design 主题、共享组件和页面私有 CSS 中,且历史修正尚未沉淀为可验证的统一规则。

该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。