12 KiB
范围声明(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 等 |
| 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.csspages/ProjectList/ProjectList.csscomponents/ModeSwitch/ModeSwitch.csspages/Profile/ProfilePage.csspages/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 中,且历史修正尚未沉淀为可验证的统一规则。
该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。