diff --git a/.workbuddy/memory/2026-11-07.md b/.workbuddy/memory/2026-11-07.md new file mode 100644 index 0000000..c75faa5 --- /dev/null +++ b/.workbuddy/memory/2026-11-07.md @@ -0,0 +1,8 @@ +# 2026-11-07 + +## Git 仓库初始化并推送远程 + +- 首次提交 `d4743db`(chore: 初始化 NEX 设计系统规范文档),已推送到 `https://git.unissense.tech/mula/nex_design_system.git` 的 `main` 分支,已建立 upstream 跟踪。 +- 分支由默认 `master` 重命名为 `main`。 +- 本仓库提交身份(local 配置):`mula.liu `。 +- 教训:仓库此前只有暂存文件、零提交,且分支名为 master,导致 `git push origin main` 报 `src refspec main does not match any`。今后新仓库推送前先确认「有提交 + 分支名一致」。 diff --git a/AGENTS.md b/AGENTS.md index 6d1cde6..e4fe4d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,55 +1,84 @@ -# NEX Design System — Agent Entry Rules +# NEX Design System — Agent Entry Rules (0.1.2) -本项目采用 NEX Design System。开始任何前端页面、组件或样式工作前,必须先读取本文件及下列文档: +本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 `docs/`、`config/` 和 `templates/`。如果本文件被合并到项目根 `AGENTS.md`,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。 -- `docs/02-design-principles.md` -- `docs/03-design-tokens.md` -- `docs/04-layout-system.md` -- `docs/05-component-system.md` -- `docs/06-interaction-system.md` -- `docs/07-page-patterns.md` -- `docs/08-accessibility-responsive.md` -- 项目根目录的 `nex.config.yaml`(如存在) +## 1. 开始任务前必须读取 -读取 `nex.config.yaml` 时,必须同时遵守 `requirements` 与 `rules`:前者定义项目必须达到的设计/体验结果,后者定义具体实现约束。特别是 `maintain_existing_interactions: true`,表示不得在视觉改造中擅自改变既有业务操作路径;确需调整时,必须先说明影响并纳入任务验收。 +1. `docs/00-governance-and-adaptation.md` +2. `docs/02-design-principles.md` +3. `docs/03-design-tokens.md` +4. `docs/04-layout-system.md` +5. `docs/05-component-system.md` +6. `docs/06-interaction-system.md` +7. `docs/07-page-patterns.md` +8. `docs/08-accessibility-responsive.md` +9. `docs/09-agent-execution-rules.md` +10. 项目根目录 `nex.config.yaml`(如存在) +11. 项目级 UI/UX 规范(由 `nex.config.yaml` 声明;如未声明,先搜索项目现有设计文档) -任务涉及既有页面时,还必须先读取该页面现有 JSX、CSS 和所依赖的共享组件,禁止只根据需求描述重新造一套样式。 +只在任务涉及 NexDocus 历史实现或明确要求参考时,读取 `docs/01-project-audit.md` 和 `config/reference-nexdocus-profile.example.yaml`。它们不是新项目的实施基线。 -## 强制规则 +## 2. 规范层级 -1. **先复用,后新增。** 先搜索已有 NEX 组件、页面模式和设计令牌;禁止创建功能或视觉重复的组件。 -2. **不擅自改技术栈。** 项目技术栈以项目配置和 `package.json` 为准。不得借 UI 任务升级 React、替换 Ant Design、引入 Tailwind 或改变 JS/TS 方案。 -3. **禁止硬编码设计值。** 颜色、字体、间距、圆角、阴影、层级和布局尺寸必须使用 NEX token。确实属于内容本身的颜色(如 Markdown 语法高亮、第三方品牌标识)可例外,但必须限定作用域并说明原因。 -4. **禁止私自建立视觉变体。** 新增颜色、按钮尺寸、卡片样式、页头样式或交互模式前,先确认是否能映射到既有 token/variant;不能映射时先更新 NEX 规范。 -5. **页面不得绕开共享模式。** 列表页、详情页、表单页、Dashboard、设置页必须采用 `docs/07-page-patterns.md` 对应模板;特殊工作区按 `docs/04-layout-system.md` 选择专用 Shell。 -6. **交互状态完整。** 异步功能必须考虑 loading、success、empty、error、disabled 和权限不足状态;破坏性操作必须二次确认;可点击元素必须键盘可达。 -7. **不破坏工作区滚动结构。** 全屏/嵌套 Flex 或 Grid 工作区必须明确滚动容器;必要时设置 `min-width: 0`、`min-height: 0`,避免页面整体溢出或滚动穿透。 -8. **主题必须成对实现。** 任何表面、文字、边框、选中态、悬停态和状态色变更,都要检查 Light/Dark 两种主题。 -9. **不滥用局部覆盖。** 禁止在业务页用高优先级选择器、`!important` 或深层 Ant Design DOM 覆盖修补本应由 token/组件主题解决的问题。确实需要时应写明原因并尽可能限域。 -10. **先提交计划再改动。** 超过单一组件的小任务,先列出将复用/新增的组件、涉及页面、状态和验收点;不要在未梳理依赖时直接批量修改。 +遵循 NEX 三层模型: -## 标准工作流 +- **NEX Core**:跨项目质量与设计治理要求。 +- **Project Design Specification**:本项目视觉、布局、技术和交互的权威具体规范。 +- **Project Implementation**:当前主题、Token、组件和页面的真实实现。 -1. 检查现有页面、共用组件和 token。 -2. 明确页面类型、用户任务、关键状态和响应式行为。 -3. 在需要时先更新页面规格(`templates/page-spec.md`)。 -4. 优先修改共享组件/主题,再修改业务页面。 -5. 执行项目已有 lint/build/test;不得虚构项目中不存在的脚本。 -6. 做 Light/Dark、窄屏、键盘和状态检查。 -7. 汇报改动文件、复用组件、规范偏离、检查命令和未完成事项。 +NEX 示例值、NexDocus 参数、示例截图和示例组件名都不是项目默认值。项目级规范决定具体实现。NEX Core 的通用 MUST 要求不能因项目偏好而取消,但可以采用不同技术方式满足。 -## 完成定义 +## 3. 开发前审计要求 -任务只有在以下条件均满足时才可报告完成: +修改既有前端前,先检查: -- 视觉层级和布局符合 NEX 对应页面模式。 -- 使用设计 token,而非散落硬编码值。 -- 交互状态完整且行为一致。 -- 不引入重复组件或不必要依赖。 -- 亮暗主题和响应式行为已检查。 -- 可运行的质量检查已执行;无法执行的检查必须明确说明。 -- 文档与实际行为不存在明显冲突。 +- 项目技术栈和真实依赖(以锁文件、`package.json`、构建配置为证据)。 +- 项目级 UI 规范和设计决策记录。 +- Token 的单一事实来源及其派生链路(CSS、主题库、框架变量等)。 +- 已有组件、页面模式、主题机制和布局参数。 +- 现有交互路径、响应式行为、自动化检查与视觉基线。 -## 例外处理 +将发现映射为 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED` 或 `NOT_APPLICABLE`。优先使用 `templates/project-conformance-matrix.md`。如果用户要求只审计,则不得修改业务代码。 -业务需求确实要求偏离 NEX 时,先在页面规格中记录:偏离项目、原因、影响范围、是否可复用。不得把单个业务例外自动推广为全局规范。 +## 4. 强制约束 + +1. **先盘点、后复用、再新增。** 先搜索项目现有共享组件和功能等价物。已有组件能满足需求时,不新增重复组件或第二套组件库。 +2. **项目适配优先。** 不将 NEX 参考项目的技术栈、品牌色、Token 名称、Header/Sider 尺寸、断点、控件高度或页面模式套用到其他项目。 +3. **不强制 `--nex-*` 命名。** 优先沿用项目现有语义 Token 和权威主题管线。只有项目没有合理命名体系、且批准采用 NEX 前缀时才可新增命名空间。 +4. **保持 Token 单一事实来源。** 可以由一个源文件/对象/配置单向派生 CSS Variables、组件库主题或框架变量;不得为同一语义值建立彼此独立、人工维护的多份来源。禁止为追求“统一”而破坏已经验证的单向派生链路。 +5. **保护成熟实现,但不固化缺陷。** 保留已验证的视觉和交互模式。若发现可复现的功能缺陷、安全问题或可访问性缺陷,应说明证据并提出最小修复;不得以“保持现状”为由忽略缺陷。 +6. **不擅自改变业务交互。** 视觉改造不得改变用户操作路径、数据语义、默认值或业务流程,除非任务明确授权。修复可访问性时应优先保持原操作意图和鼠标行为。 +7. **不擅自改技术栈。** 不升级框架、替换 UI 库、改变 JS/TS 方案或引入新样式系统,除非用户明确批准。 +8. **页面模式按需采用。** 只为项目真实存在的页面和工作区选择模式。`NOT_APPLICABLE` 的页面、组件和工作区不应被引入。 +9. **避免无意义封装。** 不机械包装所有第三方基础组件;只封装重复、高价值、需要统一 API/状态/可访问性行为的模式。 +10. **交互状态完整。** 适用时覆盖 loading、success、empty、error、disabled、permission-denied 等状态。状态不能只靠颜色表达。 +11. **可访问性是质量底线。** 自定义交互必须支持键盘、可见焦点和可访问名称;拖拽操作必须提供非拖拽替代路径。 +12. **滚动和尺寸必须基于实际布局。** 对嵌套 Flex/Grid 工作区检查 `min-width: 0`、`min-height: 0`、滚动容器归属和溢出,不要机械添加固定尺寸或 `overflow: hidden`。 +13. **不滥用局部覆盖。** 不用大量 `!important`、高优先级选择器或深层第三方 DOM 覆盖来修补应由 Token/主题/共享组件解决的问题;需要时说明范围和原因。 +14. **范围受控。** 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。 + +## 5. 标准工作流 + +1. 读取 NEX Core、项目配置和项目级设计规范。 +2. 检查真实实现并建立符合性/差异映射。 +3. 明确任务范围、复用组件、可能受影响页面和回归面。 +4. 对跨组件或跨页面改动先提交实施计划;仅在用户已明确授权的范围内执行。 +5. 先修正 Token/主题/共享模式,再迁移具体页面;避免一次性机械替换。 +6. 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。 +7. 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。 +8. 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。 + +## 6. 例外记录 + +偏离 NEX Core 的 SHOULD 或采用不同项目实现时,记录:规则、状态(通常为 `ADAPTED` / `DEFERRED`)、原因、证据、影响范围、责任人/批准来源和复审条件。不得把单个项目的例外自动推广为全局规范。 + +## 7. 完成定义 + +只有在以下事项满足后,才能报告任务完成: + +- 项目规范与实现之间没有未说明的重大冲突。 +- 新增实现优先复用了现有组件、Token 和页面模式。 +- 没有未经授权改变技术栈、布局基线或业务交互。 +- 适用的主题、响应式、键盘和状态检查已执行。 +- 项目真实可用的质量门禁已执行;不可执行项已说明。 +- 文档、配置和代码行为保持一致。 diff --git a/AUDIT-SUMMARY.md b/AUDIT-SUMMARY.md index 1a6163f..49613c8 100644 --- a/AUDIT-SUMMARY.md +++ b/AUDIT-SUMMARY.md @@ -1,3 +1,5 @@ +> **范围声明(NEX 0.1.2):** 本文是 NexDocus 单一参考项目的历史代码审计,不是 NEX Core 规范,也不是其他项目的技术栈、Token、尺寸或页面模式基线。本文中出现的 React/Ant Design、颜色值、64px Header、260/80px 导航等,只描述该参考项目当时的实现事实。新项目必须先按 `docs/00-governance-and-adaptation.md` 完成自己的项目审计与映射。 + # 01. NexDocus 前端设计审计 ## 1. 审计范围与方法 @@ -21,7 +23,7 @@ | PDF | react-pdf / pdfjs-dist | | 语言 | JavaScript / JSX | -**重要结论:** NEX 第一版 React 参考实现应以当前 React + Ant Design 5 + 普通 CSS 的真实栈为基准,不应把 TypeScript、Tailwind 或 CSS Modules 当作这个项目已经采用的技术。 +**参考项目事实:** NexDocus 当时采用 React + Ant Design 5 + 普通 CSS;TypeScript、Tailwind 和 CSS Modules 并非该项目当时的实际技术。该事实不构成其他项目的技术栈要求。 ## 3. 值得保留的设计资产 @@ -74,13 +76,13 @@ `AppSider` 没有覆盖这两个默认值,因此 token 与页面真实值存在漂移。AI 可能读到 token 后按 56/232/64 开发,但现有 UI 实际按 64/260/80 工作。 -**NEX 决策:** 0.1 版先以当前组件真实使用的 64px / 260px / 80px 作为基线,待结合运行截图确认后再调整;不得同时保留两套互相冲突的数字。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 0.1 版先以当前组件真实使用的 64px / 260px / 80px 作为基线,待结合运行截图确认后再调整;不得同时保留两套互相冲突的数字。 ### B. CSS 与 Ant Design 主题重复维护(高优先级) 品牌色、状态色、边框色和表格颜色同时存在于 CSS Variables 与 `antdTheme.js`。两处由人工分别维护,长期容易出现亮色/暗色、按钮/表格和自定义样式不一致。 -**NEX 决策:** 设计 token 必须有单一事实来源。CSS Variables 与 Ant Design Theme 应由同一份 token 数据生成,或至少由自动化一致性检查保证一致;禁止在两处独立调整同一个语义 token。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 设计 token 必须有单一事实来源。CSS Variables 与 Ant Design Theme 应由同一份 token 数据生成,或至少由自动化一致性检查保证一致;禁止在两处独立调整同一个语义 token。 ### C. 页面级硬编码颜色较多(高优先级) @@ -94,19 +96,19 @@ - `pages/Profile/ProfilePage.css` - `pages/Login/Login.css` -**NEX 决策:** 新代码不允许新增普通 UI 颜色硬编码;旧代码分批迁移,不做一次性机械替换。语法高亮、文档内容、第三方品牌等例外必须局部隔离。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 新代码不允许新增普通 UI 颜色硬编码;旧代码分批迁移,不做一次性机械替换。语法高亮、文档内容、第三方品牌等例外必须局部隔离。 ### D. 组件与页面使用方式不够统一(高优先级) 项目已经有 `PageHeader`、`StatCard`、`ListActionBar`、`ListTable` 等共享组件,但业务页面仍大量直接组合 Ant Design 原生组件与页面私有 CSS。不同页面对搜索栏、标题区、统计卡片、表格容器和操作反馈的结构并不完全一致。 -**NEX 决策:** 建立有明确合同的页面级复合组件(例如 `NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard`),让常见业务页面调用标准组合。低频、无特殊主题的 Ant Design 基础组件不必全部二次封装。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 建立有明确合同的页面级复合组件(例如 `NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard`),让常见业务页面调用标准组合。低频、无特殊主题的 Ant Design 基础组件不必全部二次封装。 ### E. 页面标题的视觉强调不分场景(中高优先级) `PageHeader.css` 使用大面积蓝色渐变背景、装饰圆形和白色标题。它有鲜明识别度,适合欢迎页、概览页或需要强调的主页面;但若每个管理页面都使用,会让操作型页面过度强调标题、压缩有效内容空间,也容易形成“每页一个大横幅”的视觉疲劳。 -**NEX 决策:** 定义两种明确变体: +**NexDocus 参考项目当时的处理建议(非通用规则):** 定义两种明确变体: - `standard`:中性背景、清晰标题/说明/操作区,是 CRUD、设置和系统管理页的默认方式。 - `hero`:保留品牌渐变,只用于概览、欢迎或少量需要强调的页面。 @@ -115,37 +117,37 @@ `App.css` 与 `antdTheme.js` 使用的字体栈并不完全相同。部分页面还直接设置固定灰色、白色背景和固定状态色。随着暗色主题扩展,容易出现某些页面切换主题后仍保留浅色硬编码。 -**NEX 决策:** 统一一份全局字体令牌;颜色一律使用语义 token。暗色主题的覆盖必须在基础 token 层完成,而不是散落在业务 CSS 的 `body.dark` 选择器里。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 统一一份全局字体令牌;颜色一律使用语义 token。暗色主题的覆盖必须在基础 token 层完成,而不是散落在业务 CSS 的 `body.dark` 选择器里。 ### G. 部分 CSS 选择器疑似无效(需要修正) `components/ListActionBar/ListActionBar.css` 使用了 `:global(...)` 选择器,但文件是普通 `.css`,不是 CSS Module(项目也没有将该文件配置成 CSS Modules)。`:global` 是 CSS Modules 的作用域语法,不是普通浏览器 CSS 的标准伪类;相关选择器很可能不会按预期生效。 -**NEX 决策:** 普通 CSS 文件直接使用 `.list-action-bar-right .ant-space-compact ...` 等普通选择器;只有 `.module.css` 才允许使用 CSS Modules 语法。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 普通 CSS 文件直接使用 `.list-action-bar-right .ant-space-compact ...` 等普通选择器;只有 `.module.css` 才允许使用 CSS Modules 语法。 ### H. 交互元素的语义和键盘操作不足(中高优先级) 导航菜单项、Header 图标操作等位置存在使用 `div` 承载点击事件的实现。鼠标操作可用不代表键盘可访问,也不具备原生按钮/链接语义。 -**NEX 决策:** 导航用 `button` 或 `a`;动作使用 `button`;跳转使用 `Link`;需要自定义外观时用 CSS 重置原生控件,而不是把可点击 `div` 当按钮。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 导航用 `button` 或 `a`;动作使用 `button`;跳转使用 `Link`;需要自定义外观时用 CSS 重置原生控件,而不是把可点击 `div` 当按钮。 ### I. 固定高度可能限制视口适配(中优先级) `ListTable.css` 中表格容器使用固定 `height: 626px`。项目卡片使用固定高度 236px。卡片统一高度可以是有意的视觉决策,但表格容器高度应基于视口和布局弹性计算,而不是对所有显示器固定 626px。 -**NEX 决策:** 列表区域采用可伸缩高度、最大高度或父容器约束;表格滚动归属必须清楚。固定高度只有在明确的内容卡片模式中才可使用。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 列表区域采用可伸缩高度、最大高度或父容器约束;表格滚动归属必须清楚。固定高度只有在明确的内容卡片模式中才可使用。 ### J. 文档说明和当前实际依赖不一致(中优先级) `frontend/README.md` 描述 Tailwind CSS + CSS Modules,并提到 `@uiw/react-md-editor`;但当前 `package.json` 未包含 Tailwind 或该 Markdown Editor 依赖,项目样式以普通 CSS 为主,Markdown 相关实现使用 ByteMD 等依赖。 -**NEX 决策:** README、项目配置和真实依赖必须同步。Agent 不得把 README 中过期描述当作新增依赖的依据。 +**NexDocus 参考项目当时的处理建议(非通用规则):** README、项目配置和真实依赖必须同步。Agent 不得把 README 中过期描述当作新增依赖的依据。 ### K. 质量检查脚本尚未覆盖 UI 回归(中优先级) 当前 package scripts 包含 dev/build/lint/lint:strict,但没有独立的前端测试、视觉回归或主题截图检查脚本。 -**NEX 决策:** 第一阶段保留现有脚本;后续为核心共享组件加入组件测试和 Playwright 视觉基线。不得在没有安装/配置时声称这些测试已经执行。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 第一阶段保留现有脚本;后续为核心共享组件加入组件测试和 Playwright 视觉基线。不得在没有安装/配置时声称这些测试已经执行。 ## 5. 推荐处理优先级 @@ -175,4 +177,4 @@ NexDocus 已经有可复用的视觉基础和一批成熟的专业工作区组件,问题不是“没有设计”,而是**设计决策分散在 token、Ant Design 主题、共享组件和页面私有 CSS 中,且历史修正尚未沉淀为可验证的统一规则**。 -NEX 0.1 的正确工作是先提炼、校准和建立约束,再把标准落实到组件库与质量门禁,而不是先做大规模视觉翻新。 +该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e8f6468 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +## 0.1.2 — 2026-11-07 + +### Added +- NEX Core / Project Design Specification / Project Implementation 三层治理模型。 +- 规范优先级、冲突处理和项目符合性状态。 +- 新项目接入流程和项目符合性矩阵模板。 +- 键盘操作、拖拽替代路径、截断状态可访问文本等规则。 + +### Changed +- 明确 NexDocus 审计与配置仅为参考实现,不再作为跨项目默认基线。 +- 通用 `project-profile.example.yaml` 改为中性模板。 +- NexDocus 历史配置拆分为 `reference-nexdocus-profile.example.yaml`。 +- Token 文档改为语义映射和单一事实来源治理;不强制 `--nex-*` 前缀。 +- 组件规范强调复用项目现有组件,不强制独立 NEX React 组件包。 +- 布局规范取消跨项目固定 Header/Sider/断点/控件尺寸。 +- Agent 规则加入实施前审计、范围授权和阶段门禁。 + +### Fixed +- 修复 0.1.1 示例配置容易被误读为新项目默认技术栈与布局值的问题。 +- 修复参考项目的专属工作区可能被错误套用到不存在这些功能的新项目的问题。 diff --git a/README.md b/README.md index 44d217d..470adf6 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,126 @@ # NEX Design System -**版本:0.1.1(项目反向提炼版)** -**基准项目:NexDocus** -**定位:面向 AI Agent 辅助软件开发的产品设计语言、UI 组件与 UX 交互标准。** +**版本:0.1.2** +**版本定位:跨项目适配与规范治理修订版** +**设计来源:NexDocus 参考实现 + 后续项目审计反馈** -## 1. 目标 +## 1. NEX 是什么 -NEX Design System 不是一份单纯的配色说明,也不是 Ant Design 的换肤文件。它由四个层次组成: +NEX Design System 是面向 AI Agent 辅助软件开发的跨项目设计治理体系。它覆盖视觉原则、Design Tokens、布局模式、组件契约、交互规则、可访问性、项目适配和 Agent 执行流程。 -1. **Design Foundations**:视觉原则、颜色、字体、间距、圆角、层级和动效。 -2. **Layout & Patterns**:应用壳层、工作区、列表、详情、表单、Dashboard 等页面模式。 -3. **Component Contracts**:可复用组件的 API、状态和交互约定。 -4. **Agent Rules**:要求 AI 在设计、编码、修改和验收时遵循的规则。 +NEX 的目标不是让所有项目长成同一个样子,而是让不同项目在保留自身成熟设计语言的前提下,拥有一致的设计质量、可理解的规则和可验证的工程约束。 -目标是让不同模型、不同 Agent 和不同项目都能在同一设计语言下工作,减少逐页修正、重复沟通和 UI 风格漂移。 +**核心原则:统一质量与设计语法,不强制统一项目的视觉参数、技术栈、组件 API 或页面骨架。** -## 2. 本版本的边界 +## 2. 0.1.2 的关键变化 -本版本依据 NexDocus 压缩包中的前端源代码反向提炼,不修改 NexDocus 原项目代码,也不评审其后端业务逻辑。它首先定义 **React 18 + Ant Design 5** 的参考实现规范;NEX 的设计原则和交互合同可被其他前端技术栈借鉴。 +0.1.2 根据真实新项目审计反馈,修正了 0.1.1 中将 NexDocus 现状参数写得过于像通用基线的问题: -NexDocus 当前使用 JavaScript(JSX),因此本规范**不强制把现有项目迁移到 TypeScript**。新项目可以在项目配置中选择 TypeScript,但不得因为引入 NEX Design System 而擅自改变项目既定技术栈。 +1. 明确三层关系:NEX Core、Project Design Specification、Project Implementation。 +2. 建立规范优先级和冲突处理规则。项目级规范负责具体视觉/布局实现;NEX Core 负责跨项目通用质量底线。 +3. 将 NexDocus 审计和参数降级为**参考实现资料**,不再作为新项目默认值。 +4. 将通用 `project-profile.example.yaml` 改为中性模板;原 NexDocus 参数另存为 `reference-nexdocus-profile.example.yaml`。 +5. 增加项目符合性状态:`COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED`、`NOT_APPLICABLE`。 +6. 明确优先复用项目已有 Token、主题管线、组件和页面模式,不强制新增 `--nex-*` 变量层或 NEX React 组件包。 +7. 明确先审计、做差异映射、确认实施范围,再修改代码;禁止将参考项目的技术栈和尺寸机械套用到其他项目。 +8. 增加键盘可访问性与拖拽操作替代路径等规则,并强化分阶段验收和变更边界。 -本版本是源代码审计后的规范初稿。由于压缩包未包含浏览器运行截图和逐页面交互录屏,视觉判断以代码实现为依据;真实运行后的像素级视觉验收应在下一阶段结合页面截图完成。 +## 3. 三层规范模型 -## 3. 规范用语 +| 层级 | 名称 | 职责 | 示例 | +|---|---|---|---| +| L1 | **NEX Core** | 跨项目的设计质量、可访问性、交互可预期性、Token 治理和 Agent 执行底线 | 不只用颜色表达状态;交互必须键盘可达;不擅自改变技术栈 | +| L2 | **Project Design Specification** | 项目专属视觉语言、布局尺寸、断点、主题策略、组件接口和业务交互 | `docs/UI规范.md`、项目设计手册、已批准的设计决策 | +| L3 | **Project Implementation** | 当前代码中的 Token、主题、共享组件、页面和行为实现 | `theme/antd.ts`、`applyRootVars`、`@theme`、项目组件目录 | -- **MUST / 必须**:不遵守即视为违反 NEX 规范,除非项目明确记录了例外。 -- **SHOULD / 应当**:默认遵循;偏离时需要说明理由。 -- **MAY / 可以**:允许按业务场景采用。 +NEX Core 不规定所有项目必须使用同一品牌色、Header 高度、Sider 宽度、控件高度、CSS 技术或组件库。上述内容由项目级规范和经验证的实现确定。 -## 4. 文档地图 +## 4. 规范优先级与冲突处理 + +按以下顺序处理: + +1. **安全、法律、隐私和无障碍的适用底线**不得被项目偏好或历史实现绕过。 +2. **NEX Core 中标记为 MUST 的跨项目要求**必须满足;项目可以选择不同实现方式,但不能取消要求本身。 +3. **项目级设计规范**决定本项目的具体设计值、技术栈、组件接口、页面模式和业务交互路径。 +4. **已验证的项目实现**可作为项目规范的证据和实现基线;如果实现与规范不一致,必须先审计并记录,不得自动假定代码或文档哪一方正确。 +5. **NEX 参考项目、示例配置和截图**只用于解释设计意图,不具备覆盖项目规范的权力。 + +发生冲突时,Agent 必须记录冲突位置、涉及层级、影响、推荐处理方式和验证方法。不得自行将项目改成参考项目的尺寸、视觉风格或技术栈。 + +## 5. 文档地图 | 文档 | 内容 | |---|---| -| `docs/01-project-audit.md` | 从 NexDocus 提炼出的现状、优点、问题和优先级 | -| `docs/02-design-principles.md` | NEX 设计原则与产品气质 | -| `docs/03-design-tokens.md` | 颜色、字体、间距、圆角、阴影、尺寸和主题规则 | -| `docs/04-layout-system.md` | 应用壳层、导航、页面和工作区布局 | -| `docs/05-component-system.md` | 组件分层、组件契约和复用边界 | -| `docs/06-interaction-system.md` | 搜索、表格、表单、弹窗、抽屉、反馈和异步状态 | -| `docs/07-page-patterns.md` | 标准页面模板和页面组合模式 | -| `docs/08-accessibility-responsive.md` | 响应式、键盘操作、可访问性和状态呈现 | -| `docs/09-agent-execution-rules.md` | AI Agent 执行设计规范的流程和约束 | -| `docs/10-adoption-roadmap.md` | 从规范到组件库的落地顺序 | -| `templates/page-spec.md` | 页面设计规格模板 | +| `docs/00-governance-and-adaptation.md` | 三层规范、优先级、冲突处理和项目适配原则 | +| `docs/01-project-audit.md` | NexDocus 历史参考实现审计;非通用规范 | +| `docs/02-design-principles.md` | NEX Core 设计原则 | +| `docs/03-design-tokens.md` | Token 治理、语义映射和主题单一事实来源 | +| `docs/04-layout-system.md` | 布局原则与可选页面/工作区模式 | +| `docs/05-component-system.md` | 组件资产盘点、复用和封装边界 | +| `docs/06-interaction-system.md` | 常见业务交互、反馈和异步状态 | +| `docs/07-page-patterns.md` | 可选页面模式和组合建议 | +| `docs/08-accessibility-responsive.md` | 可访问性、响应式和输入方式替代 | +| `docs/09-agent-execution-rules.md` | Agent 审计、计划、实施、验收工作流 | +| `docs/10-adoption-roadmap.md` | 分阶段采用路线 | +| `docs/11-project-onboarding.md` | 新项目接入、符合性映射和例外记录 | +| `templates/page-spec.md` | 项目页面规格模板 | | `templates/ui-acceptance-checklist.md` | UI/UX 验收清单 | -| `config/project-profile.example.yaml` | 项目级 NEX 配置样例 | -| `AGENTS.md` | Agent 读取入口,可复制到项目根目录 | +| `templates/project-conformance-matrix.md` | 项目符合性映射模板 | +| `config/project-profile.example.yaml` | 中性项目配置模板,不预设某个项目的技术栈和尺寸 | +| `config/reference-nexdocus-profile.example.yaml` | NexDocus 历史参考配置,仅供比对 | +| `AGENTS.md` | NEX Agent 入口规则 | -## 5. Agent 使用方式 +## 6. 如何在项目中使用 -在使用 Codex 或其他代码 Agent 时: +建议将本目录放入项目仓库,例如: -1. 将本目录放在项目内,例如 `./standards/nex-design-system/`,或作为仓库子模块/私有包维护。 -2. 将本目录的 `AGENTS.md` 内容合并到项目根目录的 `AGENTS.md`,不要覆盖项目已有的业务约束。 -3. 在项目根目录建立 `nex.config.yaml`,从 `config/project-profile.example.yaml` 复制并填写项目差异。 -4. 开发任务先读取项目规则、NEX 规则和页面规格,再进入实现。 -5. 每次交付必须附带设计规范符合性检查结果。 +```text +project-root/ +├── AGENTS.md +├── nex.config.yaml +├── standards/ +│ └── nex-design-system/ +│ ├── AGENTS.md +│ ├── docs/ +│ ├── config/ +│ └── templates/ +├── docs/ +│ └── UI规范.md # 如项目已有,以其作为项目级规范 +└── frontend/ +``` -## 6. 项目配置字段说明 +接入步骤: -`config/project-profile.example.yaml` 是基于 NexDocus 当前实现整理的项目配置样例。复制为项目根目录的 `nex.config.yaml` 后,应先核对项目真实技术栈和布局参数,再修改项目差异;不要把其他项目的示例字段直接拼接进来。 +1. 将 ZIP 中 `NEX-Design-System-v0.1.2/` 放入项目 `standards/nex-design-system/`。 +2. 不覆盖项目已有的根 `AGENTS.md`;将 NEX 入口规则合并进去,并确保引用路径正确。 +3. 从 `config/project-profile.example.yaml` 复制为项目根目录 `nex.config.yaml`,按实际技术栈、规范文件、Token 来源和组件目录填写。 +4. 如果项目已有 `docs/UI规范.md` 或类似设计手册,保留为 Project Design Specification 的权威文件,并在配置中登记。 +5. 先执行只读审计,形成符合性映射,再批准具体实施阶段。不要直接要求 Agent 全量重构。 -配置分为四类: +**不要用 `reference-nexdocus-profile.example.yaml` 创建其他项目的配置。** 它只记录 NexDocus 的历史事实。 -- `nex`:NEX 规范名称、版本和合规要求。 -- `project` / `frontend`:项目元信息、前端技术栈、主题、布局和页面类型基线。 -- `requirements`:项目级设计与体验要求。`use_shared_components` 要求优先复用共享组件;`use_design_tokens` 要求设计值来自统一 Token;`maintain_existing_interactions` 要求改造时保持既有业务交互,除非任务明确批准变更。 -- `rules`:可供 Agent 执行和检查的具体技术约束,例如禁止硬编码设计值、保留现有技术栈、检查亮暗主题和响应式行为。 +## 7. 符合性状态 -`requirements` 与 `rules` 不是两套可任选的规则:前者表达项目必须达到的结果,后者约束实现方式。两者都必须遵守;如果具体任务需要例外,必须先记录原因、影响范围和验收方式。 +项目审计和映射必须使用以下状态: -## 7. 当前阶段的关键决策 +| 状态 | 含义 | Agent 行为 | +|---|---|---| +| `COMPLIANT` | 已满足 NEX Core 要求 | 保留;如有证据可引用 | +| `ADOPTED` | 项目决定采用 NEX 建议 | 按项目批准范围实施 | +| `ADAPTED` | 采用项目既有成熟做法实现同一原则 | 保留项目实现,记录映射关系和理由 | +| `DEFERRED` | 暂缓处理 | 记录原因、风险和复审条件 | +| `NOT_APPLICABLE` | 项目不存在该功能或场景 | 不引入无关组件/页面/约束 | -- 采用 NexDocus 已经形成的克制蓝色企业软件风格作为初始基线,不在没有视觉确认的情况下另换品牌色。 -- 保留亮色和暗色主题。 -- 保留文档工作区、聊天工作区等专用布局,不强迫所有页面都套同一个后台模板。 -- 普通业务页面优先采用中性页面标题,不把蓝色渐变 Banner 扩展为所有页面的默认页头;渐变可作为概览/欢迎等有限场景的强调样式。 -- 不强制每个 Ant Design 原生组件都再包一层。只对重复、高价值、需要统一交互的组件和模式建立 NEX 组件。 -- 规范文档、设计令牌和实际组件实现必须保持一致;不能只靠提示词约束。 +不允许把 `ADAPTED` 视为“不合规”,也不允许把 `NOT_APPLICABLE` 转化为新建功能的理由。 + +## 8. 版本和演进原则 + +- NEX Core 规则的变更应记录在 `CHANGELOG.md`。 +- 项目专属参数和组件不应未经验证就上升为 NEX Core。 +- 从多个项目反复验证、具有普遍价值的规则,才考虑纳入下一版 Core。 +- 新项目审计发现的经验先记录为候选改进;不要因单一项目反馈立刻改变所有项目的默认实现。 +- 规范、配置、代码实现和检查机制必须保持可追踪的一致关系。 --- -**维护原则:** NEX 是长期演进的产品设计资产。任何跨页面的设计变更先更新规范与组件,再迁移业务页面;不允许让单个页面通过大量局部覆盖悄悄形成新的全局标准。 +**维护目标:** NEX 应减少 Agent 的自由发挥空间,但不应抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。 diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..d917d3e --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.2 diff --git a/config/project-profile.example.yaml b/config/project-profile.example.yaml index cb38981..2f97d8b 100644 --- a/config/project-profile.example.yaml +++ b/config/project-profile.example.yaml @@ -1,65 +1,98 @@ -# NEX 项目配置样例。项目启动时复制为项目根目录 nex.config.yaml 并按实际情况修改。 +# NEX 0.1.2 中性项目配置模板 +# 复制到项目根目录为 nex.config.yaml,并根据真实代码/锁文件填写。 +# 不要保留 SET_ME 占位值;不要从 reference-nexdocus-profile.example.yaml 盲目复制项目参数。 + nex: system: NEX Design System - version: 0.1.1 + version: 0.1.2 compliance: required + profile_mode: project-adaptive project: - name: NexDocus - type: enterprise-web-app + name: SET_ME + type: SET_ME language: zh-CN + design_spec: + path: SET_ME # 例如 docs/UI规范.md;没有时写 none,并先审计现状 + authority: project-level + status: needs-audit frontend: - framework: react - framework_version: "18" - language: javascript-jsx # 当前项目事实;新项目可配置 typescript - build_tool: vite - ui_library: antd - ui_library_version: "5" - styling: css-variables-and-plain-css - router: react-router - state_management: zustand + framework: SET_ME + framework_version: SET_ME + language: SET_ME # javascript-jsx / typescript 等,以项目事实为准 + build_tool: SET_ME + ui_library: SET_ME # 没有则 none + ui_library_version: SET_ME + styling: SET_ME + router: SET_ME + state_management: SET_ME - # NEX 0.1 的项目现状对齐基线,后续如经截图验证可调整 - shell: - default: NexAppShell - header_height: 64 - sidebar_width: 260 - sidebar_collapsed_width: 80 + theme: + modes: [] # 例如 [light, dark];按项目实际填写 + switching: SET_ME - themes: - - light - - dark + tokens: + source_of_truth: SET_ME # 具体文件/对象/平台;不能只写“统一管理” + naming_convention: existing-project-convention + derived_outputs: [] # CSS vars、组件库主题、Tailwind @theme 等 + mapping_document: SET_ME - page_patterns: - - dashboard - - list - - detail - - form - - settings - - document-workspace - - conversation-workspace + components: + shared_component_paths: [] + form_component_paths: [] + layout_component_paths: [] + inventory_document: SET_ME + + layout: + shell: SET_ME + header_height: project-defined + navigation_model: SET_ME + navigation_width: project-defined + breakpoints_source: SET_ME + page_patterns: [] # 只列项目真实存在的模式 + +backend: + framework: SET_ME + language: SET_ME + modification_scope: follow-task-authorization + +database: + engine: SET_ME + modification_scope: follow-task-authorization -# 项目级设计与体验要求。Agent 必须将这些要求视为实施约束, -# 不能仅把它们当作参考建议。 requirements: - # 可复用的布局、组件和页面模式优先使用 NEX/项目现有共享实现; - # 只有在确认没有合适实现后,才允许新增组件。 + # 优先复用项目已有、能力等价且经过验证的共享组件;不要求新建 NEX 同名组件。 use_shared_components: true - # 颜色、字体、间距、圆角、阴影、层级和布局尺寸统一从 Design Tokens 获取; - # 不得在业务页面散落硬编码设计值。 + # 视觉值从项目既有权威 Token/主题来源读取;允许单一来源向多个消费层单向派生。 use_design_tokens: true - # 优化 UI/UX 时必须保留现有业务交互和用户已形成的操作路径; - # 如确需改变,必须先说明原因、影响范围和迁移方案,并通过回归验收。 + # UI 改造保留既有业务操作意图和用户路径;修复明确缺陷时做最小改动并回归。 maintain_existing_interactions: true + # 已验证的视觉/布局/交互模式优先保留,除非存在明确缺陷或用户批准改变。 + preserve_verified_patterns: true + + # 不因引入 NEX 而增加重复的 Token、主题或 UI 组件系统。 + avoid_duplicate_design_system_layers: true + rules: - hardcoded_design_values: forbidden - direct_ant_design_usage: allowed_for_low_level_components - reusable_patterns_must_use_nex: true - require_light_dark_review: true + project_spec_precedence: true + reference_profiles_are_non_normative: true + no_forced_nex_token_prefix: true + preserve_existing_stack: true + no_unapproved_business_flow_changes: true + require_audit_before_broad_refactor: true + require_scope_approval_for_cross_page_changes: true + require_theme_review_when_supported: true require_responsive_review: true require_keyboard_review: true - preserve_existing_stack: true + require_drag_alternative_when_applicable: true + do_not_invent_quality_commands: true + +quality: + commands: [] # 填写项目真实存在的命令,例如 dev/build/typecheck/preview + route_inventory: SET_ME + visual_baseline: SET_ME # 没有则写 none + regression_process: SET_ME diff --git a/config/reference-nexdocus-profile.example.yaml b/config/reference-nexdocus-profile.example.yaml new file mode 100644 index 0000000..acf1111 --- /dev/null +++ b/config/reference-nexdocus-profile.example.yaml @@ -0,0 +1,74 @@ +# NexDocus 历史参考项目配置(NEX 0.1.2) +# 仅用于理解 NEX 最初的参考实现;绝不能当作其他项目默认值。 +# 所有尺寸和技术栈字段均属于 NexDocus 的项目事实/历史记录。 + +nex: + system: NEX Design System + version: 0.1.2 + compliance: reference-only + profile_mode: reference-project + +project: + name: NexDocus + type: enterprise-web-app + language: zh-CN + design_spec: + path: not-extracted-as-single-authoritative-document + authority: needs-project-confirmation + status: reference-audit-only + +frontend: + framework: react + framework_version: "18" + language: javascript-jsx + build_tool: vite + ui_library: antd + ui_library_version: "5" + styling: css-variables-and-plain-css + router: react-router + state_management: zustand + theme: + modes: [light, dark] + switching: project-store-with-system-following + tokens: + source_of_truth: historical-token-and-antd-theme-implementation-needs-runtime-verification + naming_convention: existing-project-convention + derived_outputs: [] + mapping_document: docs/01-project-audit.md + components: + shared_component_paths: + - frontend/src/components + inventory_document: docs/01-project-audit.md + layout: + shell: existing-project-shell + header_height: 64 + navigation_model: collapsible-sidebar + navigation_width: 260 + navigation_collapsed_width: 80 + breakpoints_source: project-implementation + page_patterns: + - dashboard + - list + - detail + - form + - settings + - document-workspace + - conversation-workspace + +requirements: + use_shared_components: true + use_design_tokens: true + maintain_existing_interactions: true + preserve_verified_patterns: true + avoid_duplicate_design_system_layers: true + +rules: + project_spec_precedence: true + reference_profiles_are_non_normative: true + no_forced_nex_token_prefix: true + preserve_existing_stack: true + no_unapproved_business_flow_changes: true + require_audit_before_broad_refactor: true + require_theme_review_when_supported: true + require_responsive_review: true + require_keyboard_review: true diff --git a/docs/00-governance-and-adaptation.md b/docs/00-governance-and-adaptation.md new file mode 100644 index 0000000..164d58e --- /dev/null +++ b/docs/00-governance-and-adaptation.md @@ -0,0 +1,89 @@ +# 00. Governance & Project Adaptation + +## 1. 核心目标 + +NEX 是跨项目的设计治理框架,不是某个参考产品的像素规范。它要求不同项目在设计质量、交互可预期性、可访问性、Token 治理和工程纪律上保持一致,同时允许品牌视觉、页面骨架、技术选型和组件 API 因项目而异。 + +## 2. 三层模型 + +### L1 — NEX Core + +跨项目通用要求,包括: +- 清晰的信息层级和一致的交互语义。 +- 颜色/状态表达具有语义,不单靠颜色传达关键信息。 +- 交互控件具备正确语义、键盘可达性和可见焦点。 +- 设计值有可追踪的 Token 治理方式。 +- 组件和页面模式先复用再新增。 +- 对既有项目先审计、再变更,避免未经授权的行为/技术栈变化。 +- 测试与验收只报告实际执行的证据。 + +### L2 — Project Design Specification + +每个项目自己的权威设计规范。可表现为 `docs/UI规范.md`、设计手册、产品交互文档、Figma 规格或经确认的 ADR。它决定: +- 品牌色、字体、视觉密度和具体间距尺度。 +- Header、Sider、页面容器等布局数值。 +- 断点、移动端导航和响应式策略。 +- UI 库、样式方案和主题模式。 +- Token 名称、命名空间和派生链路。 +- 共享组件 API、页面模式和业务交互路径。 + +若项目尚无此规范,Agent 应先从成熟实现中审计提炼,再提出建议;不得直接把 NEX 参考项目的参数当作默认。 + +### L3 — Project Implementation + +真实仓库中的 Token 文件、主题适配器、组件、样式、页面和检查脚本。代码是事实证据,但代码不自动等同于正确规范:实现与文档不一致时,需要审计、测试或向用户确认。 + +## 3. 规范优先级 + +按下表处理冲突: + +| 优先级 | 来源 | 如何处理 | +|---|---|---| +| 1 | 适用的法律、安全、隐私和无障碍底线 | 必须满足,不能由项目偏好豁免 | +| 2 | NEX Core 的 MUST | 必须满足;项目可用不同实现方式满足 | +| 3 | Project Design Specification | 决定项目具体的视觉、布局、技术、组件和交互 | +| 4 | 已验证的 Project Implementation | 作为证据和回归基线;发现偏差时先判断文档或代码哪方过时 | +| 5 | NEX Reference / 示例 / 历史审计 | 仅供参考,不能覆盖项目规范 | + +注:NEX 中的 SHOULD 是默认建议,项目可以通过明确记录采用 `ADAPTED` 的方式实现不同方案。任何项目规范都不能以“历史如此”为由绕过适用的安全或可访问性底线。 + +## 4. 冲突处理流程 + +遇到冲突时,Agent 必须: + +1. 列出冲突的两条规则及其来源。 +2. 指出实际代码位置、影响范围和证据。 +3. 判断属于项目差异、文档过期、实现缺陷还是 NEX 规则不适配。 +4. 给出最小风险方案和回归方式。 +5. 在需要设计决策或超出授权时暂停并请求确认。 + +禁止采用“因为 NEX 写了某个数值,所以把项目改成该数值”的推理。 + +## 5. 五种符合性状态 + +- `COMPLIANT`:项目已满足 NEX Core 对应要求。 +- `ADOPTED`:项目明确采用该 NEX 建议,并按其执行。 +- `ADAPTED`:项目以不同但合理、成熟的方式满足同一设计目标。 +- `DEFERRED`:已识别但暂缓,需记录原因、风险和复审条件。 +- `NOT_APPLICABLE`:项目不存在相应功能或场景,不应引入对应实现。 + +状态不能作为分数或简单的通过/失败标签。例如项目没有 PDF 工作区,应标为 `NOT_APPLICABLE`,而不是要求增加 PDF 模块。 + +## 6. 参考实现边界 + +本仓库的 NexDocus 文档、配置和组件名称来自一个实际项目的反向提炼。它们只说明某个项目如何落实 NEX 设计目标: + +- React、Ant Design、Tailwind、CSS、CSS Modules 等技术选型不是 NEX Core 要求。 +- 任何颜色值、Header/Sider 尺寸、控件高度、断点、内容宽度都不是跨项目默认值。 +- `NexAppShell`、`NexPageHeader` 等名称是概念性命名,不要求项目按此命名或重建组件。 +- 项目已有的主题管线和组件体系优先保留;NEX 不要求另外建立同义的 Token 层或组件包。 + +## 7. 从项目实践反哺 NEX + +只有满足以下条件的项目经验,才建议提升为 NEX Core: + +- 在两个或更多不同项目中验证,或有充分的跨项目工程理由。 +- 解决的是通用设计/工程问题,而不是单一业务特例。 +- 有明确的 MUST/SHOULD/MAY 级别和可验证方法。 +- 不强制依赖某个框架、组件库或样式工具。 +- 已更新文档、模板和 Agent 规则,且不与现有章节矛盾。 diff --git a/docs/01-project-audit.md b/docs/01-project-audit.md index 1a6163f..49613c8 100644 --- a/docs/01-project-audit.md +++ b/docs/01-project-audit.md @@ -1,3 +1,5 @@ +> **范围声明(NEX 0.1.2):** 本文是 NexDocus 单一参考项目的历史代码审计,不是 NEX Core 规范,也不是其他项目的技术栈、Token、尺寸或页面模式基线。本文中出现的 React/Ant Design、颜色值、64px Header、260/80px 导航等,只描述该参考项目当时的实现事实。新项目必须先按 `docs/00-governance-and-adaptation.md` 完成自己的项目审计与映射。 + # 01. NexDocus 前端设计审计 ## 1. 审计范围与方法 @@ -21,7 +23,7 @@ | PDF | react-pdf / pdfjs-dist | | 语言 | JavaScript / JSX | -**重要结论:** NEX 第一版 React 参考实现应以当前 React + Ant Design 5 + 普通 CSS 的真实栈为基准,不应把 TypeScript、Tailwind 或 CSS Modules 当作这个项目已经采用的技术。 +**参考项目事实:** NexDocus 当时采用 React + Ant Design 5 + 普通 CSS;TypeScript、Tailwind 和 CSS Modules 并非该项目当时的实际技术。该事实不构成其他项目的技术栈要求。 ## 3. 值得保留的设计资产 @@ -74,13 +76,13 @@ `AppSider` 没有覆盖这两个默认值,因此 token 与页面真实值存在漂移。AI 可能读到 token 后按 56/232/64 开发,但现有 UI 实际按 64/260/80 工作。 -**NEX 决策:** 0.1 版先以当前组件真实使用的 64px / 260px / 80px 作为基线,待结合运行截图确认后再调整;不得同时保留两套互相冲突的数字。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 0.1 版先以当前组件真实使用的 64px / 260px / 80px 作为基线,待结合运行截图确认后再调整;不得同时保留两套互相冲突的数字。 ### B. CSS 与 Ant Design 主题重复维护(高优先级) 品牌色、状态色、边框色和表格颜色同时存在于 CSS Variables 与 `antdTheme.js`。两处由人工分别维护,长期容易出现亮色/暗色、按钮/表格和自定义样式不一致。 -**NEX 决策:** 设计 token 必须有单一事实来源。CSS Variables 与 Ant Design Theme 应由同一份 token 数据生成,或至少由自动化一致性检查保证一致;禁止在两处独立调整同一个语义 token。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 设计 token 必须有单一事实来源。CSS Variables 与 Ant Design Theme 应由同一份 token 数据生成,或至少由自动化一致性检查保证一致;禁止在两处独立调整同一个语义 token。 ### C. 页面级硬编码颜色较多(高优先级) @@ -94,19 +96,19 @@ - `pages/Profile/ProfilePage.css` - `pages/Login/Login.css` -**NEX 决策:** 新代码不允许新增普通 UI 颜色硬编码;旧代码分批迁移,不做一次性机械替换。语法高亮、文档内容、第三方品牌等例外必须局部隔离。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 新代码不允许新增普通 UI 颜色硬编码;旧代码分批迁移,不做一次性机械替换。语法高亮、文档内容、第三方品牌等例外必须局部隔离。 ### D. 组件与页面使用方式不够统一(高优先级) 项目已经有 `PageHeader`、`StatCard`、`ListActionBar`、`ListTable` 等共享组件,但业务页面仍大量直接组合 Ant Design 原生组件与页面私有 CSS。不同页面对搜索栏、标题区、统计卡片、表格容器和操作反馈的结构并不完全一致。 -**NEX 决策:** 建立有明确合同的页面级复合组件(例如 `NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard`),让常见业务页面调用标准组合。低频、无特殊主题的 Ant Design 基础组件不必全部二次封装。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 建立有明确合同的页面级复合组件(例如 `NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard`),让常见业务页面调用标准组合。低频、无特殊主题的 Ant Design 基础组件不必全部二次封装。 ### E. 页面标题的视觉强调不分场景(中高优先级) `PageHeader.css` 使用大面积蓝色渐变背景、装饰圆形和白色标题。它有鲜明识别度,适合欢迎页、概览页或需要强调的主页面;但若每个管理页面都使用,会让操作型页面过度强调标题、压缩有效内容空间,也容易形成“每页一个大横幅”的视觉疲劳。 -**NEX 决策:** 定义两种明确变体: +**NexDocus 参考项目当时的处理建议(非通用规则):** 定义两种明确变体: - `standard`:中性背景、清晰标题/说明/操作区,是 CRUD、设置和系统管理页的默认方式。 - `hero`:保留品牌渐变,只用于概览、欢迎或少量需要强调的页面。 @@ -115,37 +117,37 @@ `App.css` 与 `antdTheme.js` 使用的字体栈并不完全相同。部分页面还直接设置固定灰色、白色背景和固定状态色。随着暗色主题扩展,容易出现某些页面切换主题后仍保留浅色硬编码。 -**NEX 决策:** 统一一份全局字体令牌;颜色一律使用语义 token。暗色主题的覆盖必须在基础 token 层完成,而不是散落在业务 CSS 的 `body.dark` 选择器里。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 统一一份全局字体令牌;颜色一律使用语义 token。暗色主题的覆盖必须在基础 token 层完成,而不是散落在业务 CSS 的 `body.dark` 选择器里。 ### G. 部分 CSS 选择器疑似无效(需要修正) `components/ListActionBar/ListActionBar.css` 使用了 `:global(...)` 选择器,但文件是普通 `.css`,不是 CSS Module(项目也没有将该文件配置成 CSS Modules)。`:global` 是 CSS Modules 的作用域语法,不是普通浏览器 CSS 的标准伪类;相关选择器很可能不会按预期生效。 -**NEX 决策:** 普通 CSS 文件直接使用 `.list-action-bar-right .ant-space-compact ...` 等普通选择器;只有 `.module.css` 才允许使用 CSS Modules 语法。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 普通 CSS 文件直接使用 `.list-action-bar-right .ant-space-compact ...` 等普通选择器;只有 `.module.css` 才允许使用 CSS Modules 语法。 ### H. 交互元素的语义和键盘操作不足(中高优先级) 导航菜单项、Header 图标操作等位置存在使用 `div` 承载点击事件的实现。鼠标操作可用不代表键盘可访问,也不具备原生按钮/链接语义。 -**NEX 决策:** 导航用 `button` 或 `a`;动作使用 `button`;跳转使用 `Link`;需要自定义外观时用 CSS 重置原生控件,而不是把可点击 `div` 当按钮。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 导航用 `button` 或 `a`;动作使用 `button`;跳转使用 `Link`;需要自定义外观时用 CSS 重置原生控件,而不是把可点击 `div` 当按钮。 ### I. 固定高度可能限制视口适配(中优先级) `ListTable.css` 中表格容器使用固定 `height: 626px`。项目卡片使用固定高度 236px。卡片统一高度可以是有意的视觉决策,但表格容器高度应基于视口和布局弹性计算,而不是对所有显示器固定 626px。 -**NEX 决策:** 列表区域采用可伸缩高度、最大高度或父容器约束;表格滚动归属必须清楚。固定高度只有在明确的内容卡片模式中才可使用。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 列表区域采用可伸缩高度、最大高度或父容器约束;表格滚动归属必须清楚。固定高度只有在明确的内容卡片模式中才可使用。 ### J. 文档说明和当前实际依赖不一致(中优先级) `frontend/README.md` 描述 Tailwind CSS + CSS Modules,并提到 `@uiw/react-md-editor`;但当前 `package.json` 未包含 Tailwind 或该 Markdown Editor 依赖,项目样式以普通 CSS 为主,Markdown 相关实现使用 ByteMD 等依赖。 -**NEX 决策:** README、项目配置和真实依赖必须同步。Agent 不得把 README 中过期描述当作新增依赖的依据。 +**NexDocus 参考项目当时的处理建议(非通用规则):** README、项目配置和真实依赖必须同步。Agent 不得把 README 中过期描述当作新增依赖的依据。 ### K. 质量检查脚本尚未覆盖 UI 回归(中优先级) 当前 package scripts 包含 dev/build/lint/lint:strict,但没有独立的前端测试、视觉回归或主题截图检查脚本。 -**NEX 决策:** 第一阶段保留现有脚本;后续为核心共享组件加入组件测试和 Playwright 视觉基线。不得在没有安装/配置时声称这些测试已经执行。 +**NexDocus 参考项目当时的处理建议(非通用规则):** 第一阶段保留现有脚本;后续为核心共享组件加入组件测试和 Playwright 视觉基线。不得在没有安装/配置时声称这些测试已经执行。 ## 5. 推荐处理优先级 @@ -175,4 +177,4 @@ NexDocus 已经有可复用的视觉基础和一批成熟的专业工作区组件,问题不是“没有设计”,而是**设计决策分散在 token、Ant Design 主题、共享组件和页面私有 CSS 中,且历史修正尚未沉淀为可验证的统一规则**。 -NEX 0.1 的正确工作是先提炼、校准和建立约束,再把标准落实到组件库与质量门禁,而不是先做大规模视觉翻新。 +该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。 diff --git a/docs/02-design-principles.md b/docs/02-design-principles.md index a362fdb..ecc2f7c 100644 --- a/docs/02-design-principles.md +++ b/docs/02-design-principles.md @@ -1,71 +1,73 @@ -# 02. NEX Design Principles +# 02. NEX Core Design Principles -## 1. 产品气质 +## 1. 设计目标 -NEX 的默认气质定义为:**专业、克制、清晰、高信息效率、可信赖**。 +NEX 默认倡导专业、清晰、可信赖、高信息效率和可预期的产品体验,适用于企业软件、AI 平台、管理系统、内容/知识工作区和专业工具。该气质是默认方向,不是所有产品必须采用的品牌视觉;项目明确的品牌定位和用户研究可以形成不同表达。 -它主要服务于企业级后台、AI 平台、管理系统、内容/知识工作区和专业工具软件。界面应优先帮助用户理解数据、判断状态和完成任务,而不是让装饰本身成为注意力中心。 - -## 2. 六项设计原则 +## 2. 六项核心原则 ### 2.1 Clarity First — 层级先于装饰 -- 页面标题、关键数据、主要操作、辅助信息要有稳定层级。 -- 用户首先看到当前处于哪个模块、当前对象是什么、下一步能做什么。 -- 不以渐变、阴影、插画或大面积色块替代信息层级。 +- 页面标题、关键数据、主要操作和辅助信息应具有清晰层级。 +- 用户应能判断当前所在位置、当前对象和下一步可执行操作。 +- 不以渐变、阴影、插画或大面积色块替代信息架构。 ### 2.2 Density with Breathing Room — 信息密度与留白平衡 -- 专业后台允许中高信息密度,但不能拥挤。 -- 列表、数据表和配置表单优先保证可扫描性。 -- 使用统一间距节奏,而不是逐元素凭感觉设置 margin/padding。 +- 信息密度应匹配目标用户、任务频率和屏幕尺寸。 +- 数据表、配置面板和专业工作台允许较高密度,但必须可扫描、可操作。 +- 间距应来自项目定义的尺度或有语义的局部尺寸,而不是逐元素任意微调。 ### 2.3 Consistency over Novelty — 一致性优先于新奇 -- 同类页面使用相同页面模式。 -- 同一操作在不同模块中使用一致的位置、文案、状态和反馈。 -- 不为单个页面创造新的按钮、卡片或表格视觉语言。 +- 同类任务应采用一致的布局、操作位置、文案和反馈。 +- 新视觉模式必须有可复用理由,不应由单页任意创造。 +- 一致性指设计语法和交互规律,不要求所有页面结构完全相同。 ### 2.4 Functional Color — 颜色必须有语义 -- 品牌色表示主要动作、当前焦点和可交互强调。 -- 成功、警告、危险、信息色只表达对应状态。 -- 颜色不能成为状态的唯一表达方式;同时使用图标、文本或形状。 +- 品牌色、状态色、文本色、背景和边框应有明确用途。 +- 成功、警告、危险和信息状态不能只依赖颜色,还应提供文本、图标或形状线索。 +- 颜色值和语义映射由项目 Token/主题机制管理。 ### 2.5 Progressive Disclosure — 渐进呈现复杂性 -- 默认展示完成当前任务所需的信息。 -- 高级筛选、次要操作和低频配置按需展开。 -- 避免在一个视图中堆叠所有控件和辅助说明。 +- 默认展示完成当前任务所必需的信息。 +- 高级筛选、低频操作和高级配置按需出现。 +- 避免将所有控件和帮助信息同时堆叠在一个视图中。 ### 2.6 Predictable Interaction — 交互可预期 -- 用户能预测点击后发生什么、是否保存、是否可撤销。 -- 异步操作有明确的处理中、成功、失败状态。 -- 破坏性操作需要确认;成功反馈不能替代真实完成状态。 +- 用户应能预测操作结果、保存状态、可撤销性和数据影响。 +- 异步操作应有处理中、成功和失败状态。 +- 破坏性操作应有明确确认;成功提示不能替代实际持久化或业务结果。 -## 3. 视觉构成规则 +## 3. 视觉构成指导 -- 页面背景与内容表面要有足够层次差异,但不以大量阴影制造层次。 -- 卡片默认使用轻边框和低强度阴影;只有悬浮菜单、浮层等真正需要空间感的元素才使用更强阴影。 -- 主按钮应明显但不发光、不滥用渐变。 -- 图标使用统一图标库与一致尺寸;避免混用多套线性/填充风格。 -- 圆角用于表达组件层级,不应每个元素单独选择数值。 -- 动效用于反馈状态变化,不用于无意义的持续运动。 +以下是 SHOULD 级建议,不是强制主题: -## 4. 特殊页面不等于风格例外 +- 使用层次清晰的背景、表面和边界;不依赖大量阴影制造层级。 +- 主操作应清楚可辨,但不滥用渐变、发光和强装饰。 +- 图标风格、尺寸和线宽保持一致。 +- 圆角、阴影和动效应形成可复用尺度。 +- 动效用于解释状态变化,不应用于无意义的持续运动。 +- 页面装饰应服务于品牌、内容或任务,不应无理由占用工作空间。 -文档工作区、聊天工作区、流程画布、数据分析工作台可以拥有不同的布局结构,但必须共享 NEX 的字体、颜色、表面、边框、控件状态、焦点、反馈和动效规则。 +具体风格以 Project Design Specification 为准。 -**统一的是设计语言和交互语法,不是把所有页面做成同一种布局。** +## 4. 专用工作区 -## 5. 不采用的默认风格 +文档编辑器、聊天工作区、流程画布、数据分析工作台可以采用独立布局和复杂交互。它们仍应共享项目的字体、颜色语义、Token 治理、焦点状态、反馈规则和可访问性底线。 -除非业务场景明确要求,NEX 默认不采用: +只有项目确实存在某类工作区时,才创建或采用对应模式;不存在的页面类型应标记 `NOT_APPLICABLE`。 -- 每页顶部大面积渐变 Banner。 -- 大量彩色统计卡片和无语义的彩色图标。 -- 不同页面各自设置圆角、阴影和按钮高度。 -- 过度圆润的胶囊按钮与大面积玻璃拟态。 -- 仅为了“现代感”增加的复杂动画。 -- 仅凭颜色区分状态的标签和图表。 +## 5. 反模式(默认避免) + +除非品牌或业务场景明确需要,应避免: + +- 每个页面都使用大面积渐变 Banner。 +- 大量无语义彩色统计卡片或图标。 +- 各页面单独定义按钮、卡片、圆角和阴影。 +- 仅为“现代感”增加复杂动画。 +- 仅凭颜色表达状态。 +- 为统一而将不同任务的工作区强行做成同一种 CRUD 页面。 diff --git a/docs/03-design-tokens.md b/docs/03-design-tokens.md index 60a89f5..07fefa9 100644 --- a/docs/03-design-tokens.md +++ b/docs/03-design-tokens.md @@ -1,150 +1,112 @@ -# 03. NEX Design Tokens +# 03. Design Tokens & Theme Governance -## 1. 令牌治理 +## 1. 目标 -Design Token 是整个设计系统的底层合同。业务页面不得直接定义全局视觉值。 +NEX 要求项目视觉值可治理、语义清晰、主题行为可追踪;不强制项目采用某种 Token 文件格式、变量前缀、CSS 方案或组件库。 -**MUST:** +## 2. 单一事实来源(Single Source of Truth) -- 每个 token 必须有明确语义,不以 `blue1`、`gray2` 这类无语义命名作为业务接口。 -- Light/Dark 主题使用相同语义 token,不允许业务页面分别判断并重写整套颜色。 -- CSS 自定义样式与 Ant Design Theme 必须读取同一份 token 数据,或通过自动化检查保证完全一致。 -- 新增 token 时同步说明用途、主题值和替代关系。 -- 业务页面禁止直接写 `#1677ff` 这类品牌色;应使用品牌/语义 token。 +同一语义 Token 必须有一个权威来源。该来源可以是: -建议后续以 `tokens.json` 作为源文件,生成 CSS Variables 和 Ant Design Theme;在生成器完成前,至少指定一个唯一维护源,其他输出视为派生结果,禁止各自手工改值。 +- TypeScript/JavaScript Token 对象; +- CSS Variables; +- JSON/YAML Token 文件; +- 设计 Token 平台导出; +- UI 框架主题配置(若它确实是权威源)。 -## 2. 从 NexDocus 继承的初始色彩基线 +项目可以将权威源单向派生为其他消费层。例如: -以下值来自现有 `design-tokens.css` 与 `antdTheme.js`,作为 NEX 0.1 的继承基线,不代表最终视觉验收已经结束。 - -| 语义 | Light 基线 | Dark 基线 | 使用规则 | -|---|---|---|---| -| Brand / Primary | `#1677ff` | `#177ddc` | 主要操作、链接、选中和焦点 | -| Success | `#52c41a` | `#49aa19` | 完成、成功、可用 | -| Warning | `#faad14` | `#d89614` | 注意、待处理、风险 | -| Danger | `#ff4d4f` | `#dc4446` | 删除、失败、危险 | -| Text Primary | `rgba(0,0,0,.88)` | `rgba(255,255,255,.85)` | 标题和主要内容 | -| Text Secondary | `rgba(0,0,0,.65)` | `rgba(255,255,255,.65)` | 辅助描述 | -| Text Tertiary | `rgba(0,0,0,.45)` | `rgba(255,255,255,.45)` | 时间、提示、低强调信息 | -| Canvas | `#f5f5f5` | `#111111` | 应用主背景 | -| Surface | `#ffffff` | `#1f1f1f` | 卡片、面板和浮层基础表面 | -| Border | `#d9d9d9` | `#424242` | 默认边框 | - -### 2.1 语义别名 - -NEX 建议采用以下语义变量名: - -```css -:root { - --nex-color-brand: #1677ff; - --nex-color-success: #52c41a; - --nex-color-warning: #faad14; - --nex-color-danger: #ff4d4f; - - --nex-text-primary: rgba(0, 0, 0, 0.88); - --nex-text-secondary: rgba(0, 0, 0, 0.65); - --nex-text-tertiary: rgba(0, 0, 0, 0.45); - - --nex-bg-canvas: #f5f5f5; - --nex-bg-surface: #fff; - --nex-bg-elevated: #fff; - --nex-border-default: #d9d9d9; - --nex-border-subtle: #f0f0f0; -} +```text +project theme tokens + │ + ├── UI library theme adapter + │ + ├── CSS custom properties + │ + └── utility framework theme ``` -以上代码是命名和语义示例。实际值应由项目 token 数据统一输出,不要在多个文件各自重复维护。 +**单一事实来源不等于所有值必须写在一个物理文件中。** 关键是来源关系明确、方向唯一、派生层不独立人工维护,并且有可验证的映射。 -## 3. 当前旧变量兼容映射 +如果项目已有经过验证的主题管线(例如某个主题配置向 CSS/框架变量单向派生),应优先保留,不要为了套用 NEX 示例而增加第二套 Token 存储。 -迁移期间可保留旧 CSS 变量作为别名,避免一次性修改所有页面: +## 3. Token 语义分类 -| 旧变量 | NEX 语义 | -|---|---| -| `--color-primary` | `--nex-color-brand` | -| `--color-success` | `--nex-color-success` | -| `--color-warning` | `--nex-color-warning` | -| `--color-danger` | `--nex-color-danger` | -| `--text-color` | `--nex-text-primary` | -| `--text-color-secondary` | `--nex-text-secondary` | -| `--text-color-tertiary` | `--nex-text-tertiary` | -| `--bg-color-layout` / `--bg-color-secondary` | `--nex-bg-canvas`(按使用语境确认) | -| `--card-bg` / `--panel-bg` | `--nex-bg-surface` | -| `--border-color` | `--nex-border-default` | -| `--border-color-secondary` | `--nex-border-subtle` | +至少应评估以下类别是否适用于项目: -不要在没有确认语义的情况下把两个旧变量机械映射到同一个 token;例如页面背景与次级表面可能需要区分。 +| 类别 | 语义示例 | 常见消费者 | +|---|---|---| +| Color | brand、success、warning、danger、info | 按钮、标签、图表、状态 | +| Text | primary、secondary、muted、inverse | 标题、正文、说明 | +| Surface | canvas、surface、elevated、overlay | 页面、卡片、菜单、弹层 | +| Border | default、subtle、strong、focus | 面板、控件、焦点 | +| Spacing | xs、sm、md、lg 等 | 页面、组件和布局 | +| Typography | font family、size、weight、line-height | 所有文本 | +| Radius | control、card、dialog 等 | 控件和容器 | +| Elevation | base、popover、modal 等 | 浮层和层级 | +| Motion | duration、easing、reduced-motion | 过渡和动效 | +| Layout | header、navigation、content、workspace | 应用壳层和工作区 | +| Z-index | content、sticky、popover、modal 等 | 层叠上下文 | -## 4. 间距尺度 +项目不必为每一类都建立大量 Token;只有确实需要统一管理的语义才建立。 -沿用 4px 基准。允许值: +## 4. 命名和适配原则 -| Token | 值 | 常见用途 | -|---|---:|---| -| `space-1` | 4px | 图标与文字微间距、紧凑控件 | -| `space-2` | 8px | 控件内部、标签间距 | -| `space-3` | 12px | 表单项、菜单项间距 | -| `space-4` | 16px | 标准组件 padding、页面基础间距 | -| `space-6` | 24px | 区块之间、标准页面内容留白 | -| `space-8` | 32px | 大区块分隔 | -| `space-10` | 40px | 大型工作区分隔(需要时) | -| `space-12` | 48px | 页面大型留白 | +- 不强制使用 `--nex-*` 前缀。 +- 优先沿用项目现有命名和消费方式。 +- 如需把 NEX 语义映射到项目 Token,应建立“语义概念 → 现有 Token → 权威来源/派生链路 → 使用位置”映射表。 +- 只有在项目缺少可用命名体系、且确认不会冲突时,才可按项目决策新增命名空间。 +- 不要把多个语义不同的旧 Token 机械映射到同一个 Token。 -禁止通过任意 `margin: 13px`、`padding: 19px` 等值微调常规 UI;确有密集型专业组件需求时,在组件内定义有语义的局部尺寸并记录。 +映射表示例(变量名仅为示意): -## 5. 圆角尺度 +| NEX 语义 | 项目现有 Token | 权威来源 | 使用方式 | +|---|---|---|---| +| Brand | `--color-primary` | `theme/tokens.ts` | CSS 与组件库主题派生 | +| Surface | `--panel-bg` | `theme/tokens.ts` | 面板背景 | +| Text Secondary | `--text-muted` | `theme/tokens.ts` | 辅助文本 | -| Token | 值 | 用途 | -|---|---:|---| -| `radius-xs` | 4px | 小型控件、标签 | -| `radius-sm` | 6px | 紧凑输入和小面板 | -| `radius-md` | 8px | 默认按钮、输入框、常规卡片 | -| `radius-lg` | 12px | 大卡片、弹窗、导航选中项 | -| `radius-xl` | 16px | 大型工作区容器(谨慎使用) | -| `radius-pill` | 999px | 圆形头像、计数胶囊等语义场景 | +## 5. 主题治理 -## 6. 字体与字号 +- 若产品支持 Light/Dark,语义 Token 应在主题层成对定义。 +- 页面组件应消费语义 Token,不应各自重复判断主题并维护一套颜色。 +- 第三方组件库主题应与项目 Token 保持明确映射。 +- 检查弹层、Portal、图表、代码区、编辑器、选中态、禁用态和悬停态在各主题下的表现。 +- 若项目只支持单主题,不得为了形式完整而擅自引入另一套主题。 -- 全站使用一份字体栈,必须同时考虑中文与英文数字。 -- 正文默认 14px;表格和紧凑元信息可使用 12–13px;章节标题 16–18px;页面标题 20–24px;工作区欢迎标题可使用 28–32px。 -- 正文行高建议 1.5–1.7;表格和短标签行高可更紧凑。 -- 关键数字使用稳定字重和等宽数字特性(可用 `font-variant-numeric: tabular-nums`)。 -- 不允许同一页面出现多套互相冲突的字体栈。 +## 6. 设计值与硬编码 -## 7. 控件尺寸 +新代码不得在业务页面散落无语义、重复使用的设计值。以下情形可允许局部字面量: -现有 Ant Design Theme 使用 34px 标准控件高度、40px 大控件高度。NEX 0.1 先将其作为兼容基线,后续由真实页面截图决定是否调整为更适合目标产品的统一尺寸。 +- 由内容本身决定的颜色(例如语法高亮、用户生成内容、第三方品牌); +- 只在一个局部组件中使用、且没有跨场景复用价值的精确几何值; +- 由标准、协议、图表数据或媒体原始尺寸决定的数值。 -- 同一表单内输入框、选择器和按钮高度必须一致。 -- 图标按钮的可点击区域应不小于 32×32px;优先提供 36×36px 或 40×40px。 -- 不得仅通过图标大小改变点击区域。 +例外必须局部限域并说明原因;不应把所有数字/颜色字面量都误判为设计违规。旧代码分批迁移,不做未经语义核验的全局搜索替换。 -## 8. 阴影与边框 +## 7. 尺度定义 -- 默认卡片优先使用边框,阴影保持低强度。 -- 下拉菜单、Popover、Drawer、Modal 等浮层可以使用更明显的 elevation。 -- 悬停状态优先改变边框/背景,不应每个可点击元素都明显上浮。 -- 页面级大面积面板不应同时使用强边框、强阴影和大圆角。 +间距、字体、圆角、阴影、控件尺寸、断点和容器宽度由项目按用户任务、信息密度和目标设备定义。NEX 不规定跨项目统一的固定像素表。 -## 9. 布局尺寸校准 +建议: +- 为常见尺寸建立有限、可复用的尺度。 +- 区分密集数据界面和宽松内容界面。 +- 控件点击热区满足适用的可访问性与平台要求。 +- 对布局关键尺寸指定单一来源,避免 CSS、组件属性和主题配置各自维护冲突值。 -NexDocus 当前代码的实际布局尺寸与旧 token 有冲突。NEX 0.1 暂定以现有组件默认运行值为基线: +## 8. 层级与动效 -| 项目 | NEX 0.1 基线 | 来源与说明 | -|---|---:|---| -| 顶部 Header | 64px | `AppHeader.css` | -| Sidebar 展开 | 260px | `ModernSidebar.jsx` 默认值 | -| Sidebar 折叠 | 80px | `ModernSidebar.jsx` 默认值 | -| 普通页面内边距 | 16px | `MainLayout.css` | -| 普通页面最大宽度 | 1280px | 继承现有 `--page-max-width` | -| 文档阅读最大宽度 | 1100px | 继承现有 `--content-max-width` | +- 项目应建立可理解的 Z-index 层级或使用组件库的层级管理能力。 +- 不得通过不断增大数值解决未知层叠问题;先识别 stacking context、Portal 和层级归属。 +- 动效应尊重 `prefers-reduced-motion` 或目标平台等效设置。 +- 动效时长和缓动由项目设计规范决定,不规定跨项目固定毫秒值。 -**重要:** 这些是“当前实现对齐值”,并非已通过运行视觉验证的终局设计值。完成截图审查后可以调整,但必须统一修改 token、Ant Design 主题和布局组件。 +## 9. 验收要求 -## 10. 层级与动效 - -- Z-index 必须由统一层级表管理,避免 Header、Modal、Drawer、Dropdown、Tooltip 之间出现同值竞争。 -- Ant Design 自身 Portal 层级优先由 ConfigProvider 主题控制;自定义浮层不要随意设置超大 z-index。 -- 过渡动效以 120–240ms 为主,避免过度弹跳。 -- 必须尊重 `prefers-reduced-motion`。 +- [ ] 权威 Token 来源已明确。 +- [ ] 派生关系单向且可追踪。 +- [ ] 语义 Token 与实际消费位置有映射。 +- [ ] 没有未经说明的重复 Token 层。 +- [ ] 支持的主题覆盖关键组件和状态。 +- [ ] 设计值例外已限域并说明。 +- [ ] 布局尺寸没有多个互相冲突的权威定义。 diff --git a/docs/04-layout-system.md b/docs/04-layout-system.md index 3503228..a5a647b 100644 --- a/docs/04-layout-system.md +++ b/docs/04-layout-system.md @@ -1,112 +1,97 @@ -# 04. NEX Layout System +# 04. Layout System & Page Shells -## 1. 布局体系原则 +## 1. 布局治理原则 -NEX 统一设计语言,但不强制统一所有页面的骨架。页面必须先按用户主要任务选择 Shell,再在 Shell 内使用统一的页面模式。 +NEX 统一的是布局的职责分离、信息层级、响应式和交互质量,不要求所有项目使用相同导航结构或像素尺寸。具体 Shell、导航形态、Header/Sider 尺寸、内容边距、断点和滚动策略由项目规范定义。 -## 2. 标准应用壳层:NexAppShell +## 2. 页面类型识别 -用于管理后台、模型管理、用户/权限管理、数据列表等普通应用页面。 +实施前先按用户主要任务识别页面类型,例如: -### 结构 +- 管理型页面:列表、详情、编辑、设置、权限等。 +- 概览型页面:Dashboard、监控和分析。 +- 专业工作区:文档、聊天、流程、画布、IDE、媒体编辑等。 +- 独立入口:登录、分享、公开展示、向导等。 -```text -┌──────────────┬──────────────────────────────────────────┐ -│ │ Header:面包屑/工作区信息/全局操作/用户区 │ -│ Sidebar ├──────────────────────────────────────────┤ -│ │ │ -│ 分组导航 │ Main Content │ -│ 当前选中 │ PageHeader │ -│ 用户信息 │ Page Content │ -│ │ │ -└──────────────┴──────────────────────────────────────────┘ -``` +以上是分类参考,不要求项目必须拥有所有类型。不存在的类型标记 `NOT_APPLICABLE`。 -### 约束 +## 3. Shell 模式(概念性,不是组件命名要求) -- Sidebar 展开/折叠宽度由 token 提供,不得组件内各自设置。 -- Header 高度固定,由 token 提供。 -- 主内容区负责垂直滚动;Header 和 Sidebar 不随内容滚动。 -- 页面内容区默认 16px 内边距;复杂表格/宽屏 Dashboard 可按页面规格扩大。 -- 页面主体可设置最大宽度,但数据密集页面允许占满可用宽度。 -- 导航选中态、悬停态和折叠态必须一致。 +### 3.1 应用 Shell -## 3. 文档工作区:NexDocumentWorkspace +适用于需要全局导航、模块切换和统一页面容器的产品。可采用侧边导航、顶部导航、混合导航或其他经过验证的模式。 -用于文件树、文档阅读、Markdown 编辑、PDF 预览等持续工作任务。 +职责建议: +- 全局导航、当前上下文和用户入口清晰。 +- 导航区域与主内容区滚动行为明确。 +- 页面内容区域具有可预测的留白和宽度策略。 +- 导航折叠/展开状态可恢复,且键盘操作可达。 -```text -┌──────────────┬──────────────────────────────────────────┐ -│ Project │ Context Header:路径/标题/操作 │ -│ Sidebar ├──────────────────────────────────────────┤ -│ 文件树 │ │ -│ 收藏/搜索 │ Document Canvas / Editor / PDF Viewer │ -│ │ │ -└──────────────┴──────────────────────────────────────────┘ -``` +### 3.2 内容/文档工作区 -约束: +仅在产品存在文档阅读、编辑或文件管理任务时采用。 -- 使用独立的全高工作区,不再叠加普通页面的大块 padding。 -- 左侧文件树和右侧内容区各自负责自己的滚动。 -- 编辑区/预览区的阅读宽度要统一;阅读与编辑模式切换时不能突然改变正文行长。 -- 工具栏、上下文标题区与内容画布的职责分离。 -- 嵌套 Flex/Grid 必须检查 `min-width: 0`、`min-height: 0`,避免长文件名、长代码或长 Markdown 撑破布局。 -- 采用虚拟滚动的长列表/长文档必须保留稳定滚动容器,不要随意给祖先元素添加 `overflow: hidden`。 +- 文件树、工具栏、编辑区/预览区职责分离。 +- 需要独立滚动时,应明确每个滚动容器的边界。 +- 编辑与预览应保持合理一致的内容宽度和阅读节奏。 +- 嵌套 Flex/Grid 子项在需要收缩时检查 `min-width: 0`、`min-height: 0`。 -## 4. 聊天工作区:NexConversationWorkspace +### 3.3 对话工作区 -用于 AI Chat、知识检索、助手工作台等多轮交互任务。 +仅在产品存在 AI Chat 或多轮消息任务时采用。 -结构通常包含:会话历史/项目上下文面板、消息区、消息输入区、模型和工具控制区。 +- 消息历史与输入区职责分离。 +- 输入区在长消息流中保持可达。 +- 会话列表、消息区和工具面板的滚动关系明确。 +- 停止、重试、复制、引用和工具执行状态可理解。 -约束: +### 3.4 专业工作台/画布 -- 消息列表是主要滚动区;Composer 固定在消息区底部,不随历史消息一起滚出视口。 -- 会话列表滚动与消息滚动相互独立。 -- 用户消息、助手消息、引用、工具状态、错误状态必须有可区分但克制的视觉语义。 -- 停止生成、重试、复制、引用跳转等操作需要明确反馈。 -- 窄屏下会话历史改为抽屉/折叠面板,不应把两列强行压缩到不可用。 +适用于流程编辑、数据分析、多面板控制和复杂创作任务。 -## 5. 工作台/桌面:NexWorkbench +- 主工作区优先获得足够空间。 +- 可折叠/可调整面板的状态可预测。 +- 拖拽操作应有键盘或其他非拖拽替代路径。 +- 不使用普通后台页面的最大宽度限制挤压画布,除非产品规范明确要求。 -用于个人桌面、流程画布、复杂数据分析或多面板工作环境。 +### 3.5 独立页面 Shell -约束: +适用于登录、公开分享、邀请和向导等无需完整应用导航的页面。保持品牌和组件语义一致,但不强制显示全局导航。 -- 优先保证任务区可用面积。 -- 面板可以折叠/调整宽度,但状态变化必须可预测。 -- 工具面板与主工作区采用稳定分区,不用普通后台页面的最大宽度容器限制主画布。 -- 面板间距、边框、标题栏和拖拽区域采用统一 token。 +## 4. 普通业务页面的信息顺序 -## 6. 认证与分享页面:NexStandaloneShell +可按任务选择: -用于登录、分享预览、公开访问等不依赖主导航的页面。 +1. 页面上下文/标题/面包屑。 +2. 关键指标(只有帮助判断时才展示)。 +3. 搜索、筛选、视图切换或批量操作。 +4. 主内容(表格、卡片、表单、详情或图表)。 +5. 帮助、审计信息或辅助说明。 -约束: +不要为了填满空间添加没有业务价值的卡片或模块。 -- 不显示应用内部 Sidebar。 -- 品牌区域可有独立构图,但字体、按钮、输入框和状态提示仍遵循 NEX。 -- 登录/分享页面必须适配窄屏,不得依赖固定宽度导致横向滚动。 +## 5. 响应式布局 -## 7. 标准页面内容区 +- 优先复用项目已有断点和组件库响应式规则。 +- 不强制采用某一固定断点数值;新增断点必须有真实布局需求和验证依据。 +- 明确桌面、平板、窄屏下导航、表格、表单、工具栏和多栏工作区的变化。 +- 不应简单缩小桌面布局来冒充移动端体验。 +- 避免无意的整页横向滚动;宽表格可按项目设计采用横向滚动或替代呈现。 -普通管理页面内部顺序建议为: +## 6. 滚动与尺寸约束 -1. `PageHeader`:标题、描述、面包屑(如需)、主要操作。 -2. 关键指标(可选):只有确实帮助决策时才展示。 -3. 页面工具区:搜索、筛选、批量操作和视图切换。 -4. 主要内容:表格、卡片网格、表单或详情面板。 -5. 辅助区:说明、帮助链接、审计信息等。 +- 明确页面主滚动容器和嵌套工作区滚动容器。 +- 不要在多个祖先层级重复设置 `overflow: auto/hidden` 而不清楚滚动归属。 +- 检查长文本、长文件名、代码块、表格和媒体内容是否撑破布局。 +- 固定高度应有产品理由;优先使用父容器约束、弹性布局或视口计算。 +- 对 Flex/Grid 子项检查 `min-width: 0` 和 `min-height: 0`,但不要机械地全局添加。 -页面不得为了填满空间而添加无业务价值的卡片。 +## 7. 实施前必须记录 -## 8. 响应式断点 - -NEX 初始断点:576 / 768 / 992 / 1200px。具体断点与 Ant Design Grid 对齐,项目可按产品目标调整,但不得每个组件随意设置新的断点。 - -- ≥1200:完整桌面布局。 -- 992–1199:适度压缩边距、表格列和侧栏宽度。 -- 768–991:减少并排区域;双栏工作区进入窄屏模式。 -- <768:Sidebar 收入抽屉/覆盖层;工具栏换行;卡片网格单列;表格优先横向滚动或切换为卡片呈现。 -- <576:表单和操作区单列;避免小尺寸图标按钮密集排列。 +页面或 Shell 改造前,记录: +- 当前 Shell 和导航行为; +- 关键尺寸的权威来源; +- 视口变化时的布局行为; +- 滚动容器归属; +- 受影响页面清单; +- 现有视觉截图或可用回归检查。 diff --git a/docs/05-component-system.md b/docs/05-component-system.md index 0bf4b83..7ef46b1 100644 --- a/docs/05-component-system.md +++ b/docs/05-component-system.md @@ -1,131 +1,93 @@ -# 05. NEX Component System +# 05. Component System & Reuse Contracts -## 1. 组件分层 +## 1. 核心原则 -NEX 组件分成四层,避免把所有 UI 都包装成同一种组件: +NEX 不要求所有项目安装或开发一套名为 NEX 的 React 组件库。项目已有组件体系应优先作为实现载体。NEX 提供的是组件治理、复用判断和行为契约。 -| 层级 | 说明 | 典型内容 | +## 2. 先盘点现有组件 + +修改前检查项目中: + +- 基础 UI 组件; +- 表单组件和校验封装; +- 页面级复合组件; +- 布局/导航组件; +- 反馈与状态组件; +- 业务域共享组件; +- 设计系统/主题包(如有)。 + +对候选组件记录名称、路径、导出、使用次数、能力、已知限制和适用页面。不要仅根据名字判断是否等价,要核对 Props、状态和实际行为。 + +## 3. 组件复用决策 + +按此顺序判断: + +1. 项目已有组件能满足需求:直接复用。 +2. 已有组件只缺少通用能力:考虑向后兼容地扩展。 +3. 多处存在同一重复模式:抽象为项目级共享组件。 +4. 仅一个页面的特例:先保留局部实现,除非有明确复用价值。 +5. 第三方组件已足够满足需求:可以直接使用,不必机械封装。 + +不因 NEX 采用某个概念名称就新增 `Nex*` 组件。如果已有组件叫 `PageHead`、`Ctlbar`、`DataTable` 等,且契约满足要求,就继续使用现有命名。 + +## 4. 组件分层(概念模型) + +| 层级 | 职责 | 示例 | |---|---|---| -| Foundation | token 和主题基础 | 颜色、字体、间距、主题、图标尺寸 | -| Primitive | 基础交互控件(必要时封装) | Button、Input、Select、Tag、Tooltip | -| Composite | 高频复合组件 | PageHeader、SearchToolbar、DataTable、StatCard | -| Pattern | 页面级任务模式 | ListPage、DetailPage、SettingsPage、Workspace | +| Foundation | Token、主题、图标和基础样式 | 颜色语义、字体尺度、焦点样式 | +| Primitive | 基础交互控件 | Button、Input、Select、Tooltip | +| Composite | 高频复合组件 | 页面头部、搜索栏、表格工具栏、指标卡 | +| Pattern | 页面/任务模式 | 列表管理、编辑流程、专业工作区 | -## 2. 包装原则 +项目可采用不同目录结构或命名方式。 -**不需要为了“统一”而给每个 Ant Design 原生组件机械套壳。** +## 5. 常见能力合同 -以下情况应建立 NEX 封装: +以下是能力要求,不是要求必须创建这些组件: -- 组件在多个业务模块中重复使用。 -- 组件具有稳定的组合结构或业务交互。 -- 组件需要统一主题、状态或可访问性行为。 -- 直接使用 Ant Design 时经常产生大量页面级 CSS 覆盖。 +### Page Heading +- 标题、说明、面包屑和主操作层级明确。 +- 小屏下标题和操作不会互相挤压。 +- 强调型 Hero 只在项目设计规范允许的场景使用。 -低频、复杂且没有视觉分歧的 Ant Design 组件可以直接使用,但仍须遵循 token 与交互规范。 +### Search / Filter Toolbar +- 搜索、筛选、重置和应用行为可预测。 +- 已应用筛选条件可见。 +- Enter 搜索、自动搜索或显式提交按项目规范统一。 +- 批量操作仅在存在选中项时展示或启用。 -## 3. 第一批标准组件 +### Data Table / List +- 加载、空数据、错误、无权限和分页状态清晰。 +- 行点击与行内操作不互相吞事件。 +- 选择、排序、筛选和分页行为一致。 +- 长内容、窄屏和键盘导航有可用策略。 -### 3.1 NexPageHeader +### Form +- 必填、校验、错误、提交中和保存结果清晰。 +- 字段标签、帮助文案和错误信息可关联。 +- 取消/关闭时对未保存内容的行为明确。 -用途:普通业务页面的标题区。 +### Modal / Drawer / Overlay +- 容器选择符合任务复杂度和上下文需要。 +- 焦点进入、焦点返回、Esc 行为和遮罩交互合理。 +- 层级由项目层级体系/组件库管理。 -建议 API: +### Feedback / Status +- 状态同时具备文本或图标语义,不只靠颜色。 +- 长标签截断时必须提供可访问的完整文本(例如可见 Tooltip、title 或 aria-label,按控件语义选择)。 +- 通知、行内提示和页面级错误的使用场景不混淆。 -```jsx -新增用户} - variant="standard" -/> -``` +## 6. 组件变更验收 -合同: +修改共享组件时,至少检查: +- 所有已知调用方; +- 默认值和变体兼容性; +- Light/Dark(若项目支持); +- 桌面和窄屏行为; +- 键盘与可访问性; +- 空、加载、错误和禁用状态; +- 视觉回归范围。 -- `standard` 为默认变体;`hero` 仅用于概览/欢迎等少数页面。 -- 标题、描述、面包屑、主操作位置固定。 -- 不在组件内部硬编码业务图标或业务文案。 -- 小屏下操作区换行或堆叠,不与标题挤压。 +## 7. 参考命名说明 -### 3.2 NexSearchToolbar - -用途:列表页搜索、过滤、视图切换和刷新。 - -合同: - -- 搜索输入、筛选条件、清空筛选和刷新逻辑位置一致。 -- 高级筛选应显示当前已应用条件数量或明确状态。 -- Enter 可触发搜索;清空输入后是否自动搜索由页面规格决定,但同类页面必须一致。 -- 列表批量操作仅在存在选中项时出现,不与普通操作同时挤占空间。 - -### 3.3 NexDataTable - -用途:管理型数据列表。 - -合同: - -- 默认行高、字号、表头、边框、hover、selected、loading 和分页统一。 -- 行选择只有在业务需要时才启用。 -- 操作列位置和操作密度稳定;破坏性操作与普通操作视觉区分。 -- 表格高度由父布局决定,不在通用表格组件中写固定像素高度。 -- 必须处理空数据、加载、错误、权限不足和横向溢出。 -- 行点击和行内按钮不能互相吞掉事件。 - -### 3.4 NexStatCard - -用途:展示少量关键指标。 - -合同: - -- 颜色按语义选择,不允许每张卡片任意指定品牌色。 -- 指标、单位、辅助标签和趋势的层级固定。 -- 趋势颜色表达正负或状态,但需配合箭头/文本。 -- 不把统计卡片默认做成高饱和背景卡。 - -### 3.5 NexModal / NexDrawer - -用途:统一表单、详情和二次确认的容器。 - -合同: - -- 短小、单任务、可快速完成的表单优先 Modal。 -- 需要浏览较多上下文、查看详情或执行连续编辑时优先 Drawer。 -- 复杂多步骤流程、长表单、具有独立 URL/可书签的内容优先独立页面。 -- 关闭时对未保存更改进行保护。 -- Footer 的取消/确认位置固定;主操作必须明确。 - -### 3.6 NexPageState - -统一 Loading / Empty / Error / Forbidden / Not Found。 - -合同: - -- Empty 必须说明为何为空,并在可行时提供下一步动作。 -- Error 提供可理解信息和重试操作,不暴露内部堆栈。 -- Loading 避免整页无意义闪烁;长任务显示进度或阶段。 -- Forbidden 与 Not Found 不混为一谈。 - -## 4. NexDocus 现有组件的迁移映射 - -| 现有组件 | NEX 归属 | 建议 | -|---|---|---| -| `PageHeader` | Composite | 增加 standard/hero 语义变体 | -| `StatCard` | Composite | 颜色改为语义类型,不接受任意 CSS 色值 | -| `ListActionBar` | Composite | 明确筛选、批量操作和搜索状态合同 | -| `ListTable` | Composite | 取消固定高度;行选择改为可选能力 | -| `ModernSidebar` | Shell Primitive | token 化尺寸和状态;补齐键盘语义 | -| `ProjectFileTree` | Domain Composite | 保留业务组件属性,复用通用树视觉与交互规范 | -| `LargeMarkdownViewer` | Domain Component | 纳入文档工作区规范,不强制通用化全部内部逻辑 | -| `VirtualPDFViewer` | Domain Component | 保留专用滚动与虚拟化实现 | -| `FloatingToc` | Domain Component | 统一浮层、选中、焦点和主题 token | - -## 5. 组件代码约定 - -- 组件负责渲染与局部交互,不应内聚大量 API 请求和业务数据装配。 -- 复杂交互状态应通过清晰 Props/Callbacks 或项目状态层管理。 -- 组件默认样式由 NEX token 决定;业务页面只传递有语义的 variant/size/state。 -- 禁止通过 `style={{ color: '#...' }}` 为通用组件指定随意颜色。 -- 自定义 CSS 选择器必须有明确作用域,不得无边界覆盖 `.ant-*`。 -- 可交互元素使用原生按钮/链接语义,并提供 focus-visible 状态。 +`NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard` 等名称只用于表达一类能力,不构成命名要求。若项目已有等价组件,应建立映射并复用,不要为追求 NEX 命名一致而重命名或重构成熟资产。 diff --git a/docs/06-interaction-system.md b/docs/06-interaction-system.md index 189634c..a004ad0 100644 --- a/docs/06-interaction-system.md +++ b/docs/06-interaction-system.md @@ -1,3 +1,5 @@ +> **适配说明:** 本文描述跨项目交互原则和常见模式。具体组件、快捷键、反馈样式和操作路径以项目级规范及现有成熟实现为准。 + # 06. NEX Interaction System ## 1. 交互一致性 diff --git a/docs/07-page-patterns.md b/docs/07-page-patterns.md index 930501b..96261a2 100644 --- a/docs/07-page-patterns.md +++ b/docs/07-page-patterns.md @@ -1,3 +1,5 @@ +> **适配说明:** 以下页面模式是可选参考,不是功能清单。项目不存在的类型应标记 `NOT_APPLICABLE`,不得为满足文档而创建页面或组件。现有项目模式优先。 + # 07. NEX Page Patterns ## 1. Dashboard / Overview diff --git a/docs/08-accessibility-responsive.md b/docs/08-accessibility-responsive.md index d93fb30..6f7057b 100644 --- a/docs/08-accessibility-responsive.md +++ b/docs/08-accessibility-responsive.md @@ -1,47 +1,50 @@ -# 08. Accessibility & Responsive Guidelines +# 08. Accessibility & Responsive Quality -## 1. 语义化交互 +## 1. 语义优先 -- 导航跳转使用链接;触发动作使用按钮。 -- 不使用只有 `onClick` 的 `div`/`span` 作为主要交互控件。 -- 自定义按钮必须有可见键盘焦点、可读名称和 disabled 状态。 -- 图标按钮应提供 `aria-label` 或等价的可访问名称。 -- 纯装饰图标应从辅助技术阅读顺序中排除。 +- 触发动作使用原生按钮语义;页面跳转使用链接语义。 +- 避免用可点击 `div` / `span` 模拟按钮或链接,除非有充分理由且完整实现相应 ARIA、键盘和焦点行为。 +- 表单控件应有可访问名称;错误信息应能与对应控件关联。 +- 图标按钮应有可访问名称;装饰图标应避免重复朗读。 -## 2. 焦点与键盘 +## 2. 键盘和焦点 -- 所有可交互元素必须能通过键盘到达。 -- Tab 顺序应符合视觉顺序。 -- Modal/Drawer 打开时焦点进入容器;关闭后返回触发元素。 -- Escape 关闭行为符合容器类型和未保存状态保护规则。 -- 不得移除全局 `:focus-visible` 而不提供等价替代。 +- 所有核心功能应可通过键盘访问。 +- Tab 顺序应与视觉和任务顺序一致。 +- Enter / Space 的行为应符合控件语义。 +- 焦点必须清晰可见,不得通过 CSS 全局移除焦点轮廓而不提供替代样式。 +- Modal、Drawer、Popover 等浮层应正确管理焦点进入、焦点返回和关闭行为。 -## 3. 对比度与状态表达 +## 3. 拖拽和复杂指针交互 -- 普通文本和背景应满足可读性对比度要求。 -- 状态色不得作为唯一状态线索,至少同时提供文字或图标。 -- 禁用状态仍需可辨识;不要通过极低透明度让文字不可读。 -- 暗色主题需要单独检查弱边框、次级文本、选中态和错误态。 +任何依赖拖拽完成的核心操作都必须提供非拖拽替代路径,例如: -## 4. 响应式 +- 通过按钮/菜单选择“上移/下移”或目标位置; +- 通过键盘命令完成移动、排序或节点连接; +- 提供可聚焦的操作控件和明确的状态反馈。 -以 NEX 布局文档中的 576/768/992/1200px 断点为默认基线。 +不能假设 HTML5 Drag and Drop API 自身就提供完整键盘体验。画布、排序列表和流程编辑器尤其需要验证替代路径。 -- 不允许页面出现意外的整页水平滚动。 -- 表格允许在其自身容器内横向滚动,并确保操作列仍可访问。 -- 导航、操作栏和表单在窄屏下重排,而不是简单缩小全部元素。 -- 关键操作按钮不能因换行被遮挡或移出视口。 -- 对全屏工作区优先改用窄屏专用布局,不强制保留桌面双栏。 +## 4. 状态和文本 -## 5. 内容与长文本 +- 状态不能只以颜色表示。 +- 截断后的重要状态、名称和错误信息必须有可访问的完整文本渠道。 +- Tooltip 不能成为键盘/触屏用户获取关键内容的唯一方式;必要时同步提供 `aria-label`、可展开文本或其他访问方式。 +- Loading、Empty、Error、Forbidden、Disabled 等状态使用清晰且可操作的文案。 -- 所有可变文本区域需要考虑长标题、长文件名、长路径和无空格英文串。 -- 使用 `min-width: 0`、`overflow-wrap`、省略和 Tooltip 等组合处理,但不能让重要内容无处查看。 -- 代码、Markdown 表格、PDF 页面和长引用应在自己的内容容器中处理溢出。 +## 5. 响应式 -## 6. 动效与性能 +- 使用项目既有断点;新增断点应有布局证据。 +- 验证导航、工具栏、表格、表单、多栏工作区和弹层在目标视口下的可用性。 +- 交互热区应满足目标平台和适用标准;不要只缩小图标而保留过小点击区域。 +- 移动端复杂表格可采用横向滚动、列优先级或卡片替代等策略,具体由项目设计规范决定。 -- 尊重 `prefers-reduced-motion`。 -- 不使用无意义的持续动画。 -- 大量数据表格、文件树、长消息、PDF 页应评估虚拟化或分页。 -- 首屏避免同步加载所有大型工作区依赖;延续项目已有路由懒加载策略。 +## 6. 动效和偏好 + +- 尊重 `prefers-reduced-motion` 或目标平台等效设置。 +- 避免闪烁、持续运动和不必要的空间位移。 +- 动效不应造成焦点丢失、滚动位置跳变或操作延迟。 + +## 7. 建议验收 + +至少覆盖:键盘路径、可见焦点、图标名称、状态文本、拖拽替代操作、窄屏关键操作、文本溢出和减少动态效果设置。根据项目范围和技术能力选择自动化与人工检查方式。 diff --git a/docs/09-agent-execution-rules.md b/docs/09-agent-execution-rules.md index de1b0cf..61efcdd 100644 --- a/docs/09-agent-execution-rules.md +++ b/docs/09-agent-execution-rules.md @@ -1,76 +1,76 @@ # 09. Agent Execution Rules +## 1. Agent 的角色 -项目配置中的 `requirements` 和 `rules` 均为必读约束:`requirements` 定义应达到的设计与体验结果,`rules` 定义实现时必须遵守的技术规则。不得只读取其中一组。 +Agent 不应在每次任务中重新发明项目设计。它应先理解项目已有规范和资产,再在明确范围内完成实现,并提供可验证的结果。 -## 1. 设计与编码职责 +## 2. Preflight:实施前检查 -Agent 不是自由发挥的视觉设计师。Agent 的职责是根据用户需求选择正确的 NEX 页面模式、组合既有组件、实现业务特定内容,并在确有缺口时提出新的设计资产。 +任何涉及 UI/UX 的任务开始前: -## 2. 开始任务前必须完成 +1. 读取 NEX Core 与项目根 Agent 指令。 +2. 读取 `nex.config.yaml` 和项目级 UI 规范。 +3. 从真实依赖/锁文件/构建配置确认技术栈,不根据过期 README 猜测。 +4. 找到 Token 权威来源和派生链路。 +5. 盘点现有组件和同类页面。 +6. 确认主题、断点、布局尺寸和交互基线。 +7. 找到项目现有质量门禁、视觉截图和回归流程。 +8. 产出差异映射,使用 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED`、`NOT_APPLICABLE`。 -1. 读取项目 `AGENTS.md`、`nex.config.yaml` 和 NEX 相关文档。 -2. 搜索已有组件、tokens、页面模式和相似页面。 -3. 检查当前页面所属 Shell,不能擅自改变其布局模型。 -4. 明确页面状态:默认、加载、空、错误、禁用、无权限、成功。 -5. 明确设备范围和响应式变化。 +若用户要求只审计,本阶段之后停止,不得修改代码。 -## 3. 先规格后实现 +## 3. Plan:实施计划 -涉及新页面、跨页面改版或共享组件变化时,先输出简短 UI Specification: +跨组件、跨页面、主题、布局或设计 Token 的改动,先列出: +- 目标与非目标; +- 修改文件/组件/页面范围; +- 复用资产与需要新增的内容; +- 对业务交互和布局的影响; +- 风险和回滚方式; +- 质量检查和视觉验收方法。 -- 页面类型与目标用户任务。 -- 使用的 Shell 和 Page Pattern。 -- 页面主要区域顺序。 -- 复用的 NEX 组件。 -- 新增或修改的 token/组件(如有)。 -- 关键交互和异步状态。 -- 响应式行为。 -- 验收标准。 +用户已明确授权的阶段可在授权范围内执行;不得将授权自动扩展到后续阶段。 -小型 bug fix 可以不另建文档,但仍必须遵循上述规则。 +## 4. Implement:实现规则 -## 4. 实现顺序 +- 先复用项目资产,后新增;先修正权威 Token/主题或共享组件,再改页面。 +- 不机械套用参考项目的技术栈、尺寸、断点、品牌色或组件 API。 +- 不强制增加第二套 Token、主题或组件系统。 +- 不擅自修改业务交互、默认值、数据语义和用户操作路径。 +- 对真实缺陷采用最小修复;保留原有交互意图,并补充必要的可访问性行为。 +- 将项目不存在的页面/工作区标记为 `NOT_APPLICABLE`,不引入无关功能。 +- 不对页面进行无差别批量替换;先确认设计值语义和实际消费位置。 -建议顺序: +## 5. Verify:验证规则 -1. token / theme(仅当必要)。 -2. shared component(如需要)。 -3. page pattern / shell(如需要)。 -4. business page。 -5. tests / screenshot checks。 -6. docs。 +- 只运行仓库中真实存在的脚本和工具。 +- 不把启动成功当作完整 UI 验收。 +- 视觉检查范围由实际受影响路由、主题、视口和组件决定;复用项目现有回归矩阵。 +- 对无自动化覆盖的项目,明确人工检查范围和无法验证事项。 +- 比较基线时区分既有问题、此次引入问题和环境差异。 +- 对主题、键盘、拖拽替代路径、状态文本、滚动和溢出进行适用性检查。 -不要先在业务页面加入临时 CSS,最后再考虑抽象。 +## 6. Report:交付报告 -## 5. 变更边界 +至少汇报: +1. 修改摘要和文件清单; +2. 规范映射状态及偏离理由; +3. 复用/新增/调整的组件; +4. 交互和视觉变化; +5. 实际运行的命令及结果; +6. 受影响的路由、主题、视口和截图; +7. 未解决问题、风险和下一阶段建议。 -- 除非任务明确要求,不得修改后端 API、数据库结构、认证和权限逻辑。 -- 除非任务明确要求,不得升级或替换前端依赖。 -- 不得删除已有的文档工作区、聊天工作区等专用布局行为。 -- 不得通过全局选择器影响不相关页面。 -- 不得为了统一将业务差异抹平;应通过有语义的 variant 解决。 +## 7. 分阶段控制 -## 6. 验收报告格式 +建议按以下阶段推进,但项目可根据实际问题裁剪: -每次完成前输出: +- 阶段 0:规范与基线对齐(原则上只读/只改文档)。 +- 阶段 1:高优先级、可复现的视觉/状态缺陷。 +- 阶段 2:键盘和可访问性问题。 +- 阶段 3:层级、Token、主题等基础治理。 +- 阶段 4:共享组件和页面模式改进。 +- 阶段 5:分模块页面迁移。 +- 阶段 6:视觉回归和质量门禁完善。 -- **遵循的页面模式**:具体是哪一类。 -- **复用的组件**:实际复用了哪些。 -- **新增/修改资产**:token、组件、样式和文档。 -- **主题检查**:Light / Dark 是否检查。 -- **响应式检查**:检查了哪些断点。 -- **可访问性检查**:键盘、焦点、语义控件是否检查。 -- **命令结果**:真实执行的 lint/build/test 命令及结果。 -- **规范偏离**:无则写“无”;有则记录原因和范围。 -- **未完成事项**:明确说明,禁止把未验证事项写成已完成。 - -## 7. 禁止行为 - -- 看见 Ant Design 就直接自由组合所有组件,不检查 NEX 复合组件。 -- 使用新的任意蓝色、灰色、圆角、阴影和间距来“微调好看”。 -- 用 `!important` 或高特异性选择器堆叠覆盖解决主题问题。 -- 只实现默认态,不实现加载、空、失败、禁用等状态。 -- 只检查亮色主题。 -- 只在宽屏检查布局。 -- 未执行测试却声称测试通过。 +阶段不是强制顺序模板;具体由审计证据和用户授权决定。每阶段结束应形成可验收交付,不默认自动进入下一阶段。 diff --git a/docs/10-adoption-roadmap.md b/docs/10-adoption-roadmap.md index 1647c26..c0f0a38 100644 --- a/docs/10-adoption-roadmap.md +++ b/docs/10-adoption-roadmap.md @@ -1,69 +1,41 @@ -# 10. NEX Adoption Roadmap +# 10. Adoption Roadmap -## 阶段 0:规范冻结前的视觉确认 +## 1. 采用原则 -目标:从 NexDocus 已有设计中区分“明确认可的决策”和“开发过程中遗留的临时实现”。 +NEX 采用应从现有项目能力出发,而不是先建立新组件库或全面重写样式。优先解决规范冲突、可复现问题和重复维护成本。 -工作: -- 在本地启动 NexDocus。 -- 采集 Dashboard、项目列表、文档阅读、文档编辑、Chat、用户管理、登录等页面的 Light/Dark 截图。 -- 分别记录桌面宽屏、常用笔记本宽度和窄屏下的真实效果。 -- 对当前 Banner、导航尺寸、页面密度、按钮高度、表格行高和卡片圆角做确认。 +## 2. 推荐阶段 -交付:NEX Visual Baseline(截图与设计决策清单)。 +| 阶段 | 工作 | 常见产物 | 是否默认改业务代码 | +|---|---|---|---| +| 0. 规范对齐 | 审计真实技术栈、项目规范、Token、组件、布局和质量门禁;建立差异矩阵 | 项目 NEX 适配说明、配置、符合性矩阵 | 否 | +| 1. 明确缺陷 | 修复可复现且范围明确的 P1 问题 | 缺陷修复、回归证据 | 是,限授权范围 | +| 2. 可访问性 | 修复键盘语义、焦点、名称和替代输入路径 | 交互修复、键盘验收 | 是,限授权范围 | +| 3. 基础治理 | Token 映射、主题派生、Z-index、断点等 | Token/层级映射和必要修正 | 视证据和授权而定 | +| 4. 共享模式 | 评估共用组件、复合交互、页面模式 | 组件契约和兼容计划 | 视复用价值而定 | +| 5. 分模块迁移 | 在真实业务模块中渐进采用统一模式 | 页面迁移和回归 | 是,逐模块 | +| 6. 质量门禁 | 补充构建、交互、视觉、可访问性自动化 | CI/脚本/截图基线 | 是,按项目能力 | +| 7. 持续治理 | 定期审查规范漂移和 Agent 遵循情况 | 版本更新、审计报告 | 持续 | -## 阶段 1:修复规范漂移 +## 3. 阶段 0 的完成条件 -目标:让现有实现与规范一致,但不改变整体产品风格。 +- 已读取实际依赖和构建配置。 +- 已找到项目级 UI/UX 规范;没有则明确说明并提出提炼方案。 +- 已定位 Token 权威来源及派生关系。 +- 已盘点现有组件和等价能力。 +- 已记录项目布局、主题、断点和交互基线。 +- 已建立符合性矩阵和冲突清单。 +- 已标记 `NOT_APPLICABLE` 项,避免引入无关页面/组件。 +- 所有计划实施的差异都有范围和验证方式。 -建议顺序: -1. 对齐 Header/Sider 布局 token。 -2. 修复普通 CSS 中的 `:global` 选择器。 -3. 确定 token 单一来源,统一 Ant Design Theme 和 CSS Variables。 -4. 统一字体栈。 -5. 将 PageHeader 分成 standard/hero 两类。 -6. 修复明显的键盘语义问题。 -7. 更新 README 与真实技术栈。 +## 4. 阶段门禁 -交付:NEX token 1.0、主题配置、基础 Shell。 +- 不因工作量估算而承诺零风险或确定完成时间。 +- 阶段 0 的发现不能自动授权全量修改。 +- 未确认的品牌、布局、导航或交互决策应保留现状并列为待决项。 +- 每个阶段结束时提供 diff、实际测试结果和视觉证据。 +- 未通过回归的阶段不得默认推进下一个阶段。 -## 阶段 2:建立高价值共享组件 +## 5. 是否需要独立 NEX 组件库 -优先顺序: -1. PageHeader -2. SearchToolbar -3. DataTable -4. StatCard -5. Modal / Drawer / Confirm -6. PageState -7. 表单分组与详情区块 - -交付:React 组件包初版,含使用示例和 Storybook/组件演示页(如项目愿意引入)。 - -## 阶段 3:选择一个模块试点 - -建议优先用系统管理模块(用户、角色、权限)作为试点,因为它们重复使用 PageHeader、StatCard、ListTable、表单和 Modal,能快速验证标准组件的收益。 - -先改造一个完整列表页,再改造一个表单/详情流程,确认模式稳定后迁移其他页面。 - -不要第一批就重构文档编辑器或 Chat:这两个工作区的复杂度更高,应先把标准 Shell 和 token 稳定下来。 - -## 阶段 4:迁移专业工作区 - -分别处理: -- Document Workspace:抽取阅读/编辑共用的布局和内容宽度规范。 -- Conversation Workspace:稳定消息区、会话列表和 Composer 的状态与滚动规则。 -- PDF/Markdown:保留性能和专业交互,统一主题 token 与状态样式。 - -## 阶段 5:质量门禁 - -建议逐步增加: -- ESLint 规则:限制业务页硬编码颜色、禁止特定深层覆盖、检查非语义点击元素(需结合项目实际能力配置)。 -- 组件测试:核心复合组件状态和键盘行为。 -- Playwright:核心页面 Light/Dark 截图基线。 -- Visual Regression:对 token/组件大范围变更进行截图比对。 -- CI:lint/build/test 必须通过后才允许合并。 - -## 不推荐的落地方式 - -不建议一次性全站替换颜色和样式,也不建议先发布一套与现有应用脱节的组件库。先规范化真实高频页面,再抽象为 NEX 资产,风险更低、收益更快。 +只有多个项目已验证需要共享同一实现,且现有项目组件无法以轻量方式复用时,才考虑发布独立包。若项目间使用不同 UI 库,可共享设计原则、Token 语义和组件行为契约,而不必强行共享 React 实现。 diff --git a/docs/11-project-onboarding.md b/docs/11-project-onboarding.md new file mode 100644 index 0000000..ff8d88c --- /dev/null +++ b/docs/11-project-onboarding.md @@ -0,0 +1,65 @@ +# 11. Project Onboarding & Conformance Mapping + +## 1. 接入前收集的事实 + +Agent 应从仓库获取或向用户确认: + +- 项目类型、主要用户和主要工作任务; +- 前端框架、语言、UI 库、样式方案、路由和状态管理; +- 主题模式和主题切换策略; +- Token 的权威来源及派生消费者; +- Shell、导航、关键布局尺寸和响应式断点; +- 共享组件目录、组件入口和页面模式; +- 项目级 UI/UX 规范、设计稿或设计决策记录; +- 可执行脚本、自动化测试、视觉基线和发布流程。 + +以真实代码和锁文件为证据。README 可能过期,不能作为唯一依据。 + +## 2. 符合性映射 + +复制 `templates/project-conformance-matrix.md`,按 NEX Core 主题逐项记录: + +- NEX 原则/规则; +- 项目规范对应章节; +- 实现位置; +- 当前状态; +- 证据/测试; +- 差异和行动建议。 + +不要将不同设计体系的数字直接比较并判定不合规。例如 Header 64px 与 Header 56px 本身不存在跨项目的合规差异;需要判断尺寸是否符合当前项目任务、规范和真实运行效果。 + +## 3. Token 映射 + +至少记录: + +| NEX 语义 | 项目 Token | 权威来源 | 派生链路/消费者 | 状态 | +|---|---|---|---|---| +| Brand | | | | | +| Text Primary | | | | | +| Surface | | | | | +| Border | | | | | +| Spacing | | | | | +| Typography | | | | | +| Radius | | | | | +| Elevation/Z-index | | | | | + +若项目已有成熟的单向链路,不新增同义 Token 存储。记录其语义对应关系即可。 + +## 4. 组件映射 + +列出 NEX 常见能力与项目已有组件之间的对应关系。允许一项能力对应一个组件,也允许多个组件共同实现;若已有能力覆盖,应标记 `ADAPTED` 或 `COMPLIANT`,不必创建 NEX 同名组件。 + +## 5. 不适用项 + +对不存在的功能(例如项目没有 PDF、文档、AI Chat 或流程画布)标记 `NOT_APPLICABLE`。不得因为 NEX 文档包含了相应模式,就新增该功能或强制创建占位页面。 + +## 6. 批准和变更 + +审计报告中的建议不等于自动授权。对以下内容,需取得明确任务授权: + +- 修改品牌视觉或全局布局; +- 改变导航或移动端交互; +- 更换组件库、样式技术或主要架构; +- 破坏性 API/组件接口调整; +- 改变业务交互路径或数据语义; +- 大规模迁移页面或删除历史实现。 diff --git a/templates/page-spec.md b/templates/page-spec.md index 040b1bf..2ddc5d8 100644 --- a/templates/page-spec.md +++ b/templates/page-spec.md @@ -3,27 +3,28 @@ ## 1. 页面基本信息 - 页面名称: - 所属模块: -- 页面类型:Dashboard / List / Detail / Form / Settings / Document Workspace / Conversation Workspace / Other -- 使用 Shell:NexAppShell / NexDocumentWorkspace / NexConversationWorkspace / NexWorkbench / NexStandaloneShell +- 页面类型:Dashboard / List / Detail / Form / Settings / Workspace / Other +- 使用的项目 Shell / Layout: - 主要用户: - 核心任务: +- 对应项目规范章节: ## 2. 信息结构 -- 页面标题: -- 页面说明: +- 页面上下文/标题: - 主要操作: - 次要操作: - 页面主要区域及顺序: ## 3. 组件复用 -- 使用的 NEX 组件: -- 使用的 Ant Design 原生组件: -- 新增组件(如有)及复用理由: +- 已有项目组件: +- 第三方原生组件: +- 新增/扩展组件及理由: +- 对应组件契约或项目规范: ## 4. 交互规格 -| 交互 | 触发方式 | 状态变化 | 成功反馈 | 失败处理 | -|---|---|---|---|---| -| | | | | | +| 交互 | 触发方式 | 状态变化 | 成功反馈 | 失败处理 | 键盘替代 | +|---|---|---|---|---|---| +| | | | | | | ## 5. 页面状态 - Loading: @@ -34,23 +35,26 @@ - Success: ## 6. 响应式行为 -- Desktop(≥1200): -- Tablet(768–1199): -- Mobile(<768): +- 宽屏: +- 中等视口: +- 窄屏: +- 使用项目现有断点: ## 7. 主题与可访问性 -- Light: -- Dark: +- 支持主题: - Keyboard / Focus: +- 可访问名称和状态文本: - 长文本/溢出: +- 拖拽替代方式(如适用): - Reduced Motion: ## 8. 验收标准 -- [ ] 使用正确的 Shell 和 Page Pattern -- [ ] 优先复用已有 NEX 组件 -- [ ] 使用 NEX tokens -- [ ] 所有异步状态齐全 -- [ ] Light/Dark 检查完成 +- [ ] 使用项目既有 Shell 和页面模式,或记录例外 +- [ ] 优先复用已有组件 +- [ ] 使用项目 Token/主题权威来源 +- [ ] 交互和异步状态完整 +- [ ] 支持主题检查完成(如项目支持多主题) - [ ] 响应式检查完成 - [ ] 键盘与焦点检查完成 -- [ ] lint/build/test 已按项目能力执行 +- [ ] 项目实际可执行的质量检查已运行 +- [ ] 未经授权的业务交互变化为零 diff --git a/templates/project-conformance-matrix.md b/templates/project-conformance-matrix.md new file mode 100644 index 0000000..ebaae26 --- /dev/null +++ b/templates/project-conformance-matrix.md @@ -0,0 +1,60 @@ +# NEX Project Conformance Matrix + +**项目:** +**审计日期:** +**NEX 版本:** 0.1.2 +**项目级规范:** +**审计范围:** + +状态值:`COMPLIANT` / `ADOPTED` / `ADAPTED` / `DEFERRED` / `NOT_APPLICABLE` + +| NEX 主题/规则 | 项目规范章节 | 实现位置 | 状态 | 证据/测试 | 差异、风险与行动 | +|---|---|---|---|---|---| +| 设计原则与信息层级 | | | | | | +| Token 权威来源 | | | | | | +| 主题映射与派生链路 | | | | | | +| 布局与导航 | | | | | | +| 响应式断点 | | | | | | +| 共享组件资产 | | | | | | +| 主要交互模式 | | | | | | +| Loading / Empty / Error 等状态 | | | | | | +| 键盘与焦点 | | | | | | +| 拖拽替代路径(如适用) | | | | | | +| 自动化质量门禁 | | | | | | +| 视觉回归基线 | | | | | | + +## Token Mapping + +| 语义 | 项目 Token | 权威来源 | 派生链路/消费者 | 状态 | +|---|---|---|---|---| +| Brand | | | | | +| Text Primary | | | | | +| Surface | | | | | +| Border | | | | | +| Spacing | | | | | +| Typography | | | | | +| Radius | | | | | +| Elevation / Z-index | | | | | + +## Existing Component Mapping + +| NEX 能力 | 项目已有组件 | 位置 | 覆盖程度 | 状态/处理 | +|---|---|---|---|---| +| Page Heading | | | | | +| Search / Filter | | | | | +| Data Table / List | | | | | +| Form | | | | | +| Modal / Drawer | | | | | +| Empty / Loading / Error | | | | | + +## Exceptions / Decisions + +| 规则 | 状态 | 理由/证据 | 影响范围 | 批准来源 | 复审条件 | +|---|---|---|---|---|---| +| | | | | | | + +## Not Applicable + +| NEX 模式/功能 | 不适用理由 | 是否需要后续复审 | +|---|---|---| +| | | | diff --git a/templates/ui-acceptance-checklist.md b/templates/ui-acceptance-checklist.md index c02c689..056cf01 100644 --- a/templates/ui-acceptance-checklist.md +++ b/templates/ui-acceptance-checklist.md @@ -1,42 +1,50 @@ # NEX UI / UX Acceptance Checklist +## Specification & Reuse +- [ ] 已遵循 NEX Core 与项目级 UI 规范的层级关系 +- [ ] 已检查现有组件和页面模式 +- [ ] 新增组件有明确复用价值;未重复建设组件库 +- [ ] 项目特有差异已记录为适配,而非误判为不合规 + ## Visual -- [ ] 页面标题、说明和主操作层级清楚 -- [ ] 字体、颜色、间距、圆角和阴影来自 NEX tokens -- [ ] 与同类页面保持一致 -- [ ] 没有无业务价值的装饰或卡片 -- [ ] 表格、表单和卡片的信息密度合理 +- [ ] 信息层级和页面任务清楚 +- [ ] 字体、颜色、间距、圆角和阴影来自项目 Token/主题体系 +- [ ] 同类页面保持一致 +- [ ] 视觉表达符合项目品牌规范 +- [ ] 没有无业务价值的装饰或内容模块 ## Interaction - [ ] 主要动作清晰且不重复 - [ ] 搜索、筛选、重置和刷新行为明确 -- [ ] 表单校验、提交中、成功、失败状态完整 -- [ ] 删除/转移等危险动作有确认 -- [ ] Modal / Drawer / Page 容器选择合理 +- [ ] 表单校验、提交中、成功和失败状态完整 +- [ ] 破坏性动作有合理确认 +- [ ] 弹层焦点和关闭行为正确 - [ ] 空数据、加载、错误和无权限状态完整 +- [ ] 既有业务操作路径没有未经授权改变 -## Layout -- [ ] 使用正确的 NEX Shell +## Layout & Responsive +- [ ] 使用项目已有 Shell / 页面模式,或记录例外 - [ ] 没有意外的整页横向滚动 - [ ] 工作区滚动容器明确 -- [ ] 长文件名/长文本不会撑破布局 -- [ ] 关键操作在窄屏仍可访问 +- [ ] 长文本/长文件名不会撑破布局 +- [ ] 关键操作在目标视口仍可访问 ## Accessibility -- [ ] 交互元素使用 button/link 等语义元素 +- [ ] 交互元素使用适当语义 - [ ] 键盘可达且焦点可见 - [ ] 图标按钮具有可访问名称 - [ ] 状态不只依赖颜色 +- [ ] 截断的重要信息有可访问的完整文本 +- [ ] 拖拽操作有非拖拽替代路径(如适用) - [ ] 已尊重 reduced-motion ## Theme -- [ ] Light 检查通过 -- [ ] Dark 检查通过 -- [ ] 表格、浮层、代码区和选中态均检查 +- [ ] 项目支持的主题均已检查 +- [ ] 表格、弹层、图表、代码区和选中态均检查(如适用) -## Engineering -- [ ] 未引入重复组件 -- [ ] 未新增无语义硬编码颜色/间距 -- [ ] 没有不必要的 `!important` 或深层 AntD 覆盖 -- [ ] 项目可执行的 lint/build/test 已运行 -- [ ] 规范偏离和未验证事项已明确记录 +## Engineering & Evidence +- [ ] Token 权威来源和派生链路未被破坏 +- [ ] 未引入不必要重复 Token、主题或组件层 +- [ ] 项目真实可执行的质量门禁已运行 +- [ ] 视觉回归范围与本次改动影响面匹配 +- [ ] 规范偏离、无法执行的检查和遗留问题已明确记录