From 59b62d620aefb5328adb14ad617e899409fae111 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Thu, 12 Nov 2026 18:20:35 +0800 Subject: [PATCH] v 0.1.7 --- .DS_Store | Bin 0 -> 6148 bytes AGENTS.md | 150 +++++--------- CHANGELOG.md | 106 ++-------- CLEANUP-GUIDE.md | 55 +++++ README.md | 162 +++++---------- START-HERE.md | 106 +++------- VERSION | 2 +- config/project-profile.example.yaml | 55 ++--- .../reference-nexdocus-profile.example.yaml | 74 ------- docs/00-governance-and-adaptation.md | 97 --------- docs/00-governance.md | 49 +++++ docs/01-design-principles.md | 46 +++++ docs/01-project-audit.md | 180 ---------------- docs/02-design-principles.md | 73 ------- docs/02-design-tokens-and-theme.md | 44 ++++ docs/03-design-tokens.md | 112 ---------- docs/03-layout-and-responsive.md | 42 ++++ docs/04-component-system.md | 49 +++++ docs/04-layout-system.md | 120 ----------- docs/05-component-system.md | 96 --------- docs/05-interaction-system.md | 55 +++++ docs/06-accessibility-design.md | 55 +++++ docs/06-interaction-system.md | 83 -------- docs/07-page-patterns.md | 81 -------- docs/07-performance-aware-design.md | 33 +++ docs/08-accessibility-responsive.md | 132 ------------ docs/08-page-patterns.md | 31 +++ docs/09-agent-development-rules.md | 53 +++++ docs/09-agent-execution-rules.md | 107 ---------- docs/10-adoption-roadmap.md | 41 ---- docs/10-project-stack-defaults.md | 43 ++++ docs/11-project-adoption.md | 31 +++ docs/11-project-onboarding.md | 81 -------- docs/12-responsive-accessibility-quality.md | 192 ------------------ docs/13-project-stack-defaults.md | 116 ----------- docs/14-accessibility-platform-matrix.md | 75 ------- templates/assistive-technology-test-record.md | 52 ----- templates/new-project-audit-prompt.md | 102 ---------- templates/page-spec.md | 60 ------ templates/project-conformance-matrix.md | 63 ------ templates/project-design-map-template.md | 14 ++ templates/project-setup-prompt.md | 27 +++ templates/project-ui-spec-template.md | 55 +++++ templates/responsive-breakpoint-registry.md | 22 -- templates/ui-acceptance-checklist.md | 60 ------ 45 files changed, 847 insertions(+), 2435 deletions(-) create mode 100644 .DS_Store create mode 100644 CLEANUP-GUIDE.md delete mode 100644 config/reference-nexdocus-profile.example.yaml delete mode 100644 docs/00-governance-and-adaptation.md create mode 100644 docs/00-governance.md create mode 100644 docs/01-design-principles.md delete mode 100644 docs/01-project-audit.md delete mode 100644 docs/02-design-principles.md create mode 100644 docs/02-design-tokens-and-theme.md delete mode 100644 docs/03-design-tokens.md create mode 100644 docs/03-layout-and-responsive.md create mode 100644 docs/04-component-system.md delete mode 100644 docs/04-layout-system.md delete mode 100644 docs/05-component-system.md create mode 100644 docs/05-interaction-system.md create mode 100644 docs/06-accessibility-design.md delete mode 100644 docs/06-interaction-system.md delete mode 100644 docs/07-page-patterns.md create mode 100644 docs/07-performance-aware-design.md delete mode 100644 docs/08-accessibility-responsive.md create mode 100644 docs/08-page-patterns.md create mode 100644 docs/09-agent-development-rules.md delete mode 100644 docs/09-agent-execution-rules.md delete mode 100644 docs/10-adoption-roadmap.md create mode 100644 docs/10-project-stack-defaults.md create mode 100644 docs/11-project-adoption.md delete mode 100644 docs/11-project-onboarding.md delete mode 100644 docs/12-responsive-accessibility-quality.md delete mode 100644 docs/13-project-stack-defaults.md delete mode 100644 docs/14-accessibility-platform-matrix.md delete mode 100644 templates/assistive-technology-test-record.md delete mode 100644 templates/new-project-audit-prompt.md delete mode 100644 templates/page-spec.md delete mode 100644 templates/project-conformance-matrix.md create mode 100644 templates/project-design-map-template.md create mode 100644 templates/project-setup-prompt.md create mode 100644 templates/project-ui-spec-template.md delete mode 100644 templates/responsive-breakpoint-registry.md delete mode 100644 templates/ui-acceptance-checklist.md diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..731e5a5d036aca3158461a2095e1a1042b0ef36c GIT binary patch literal 6148 zcmeHK%T59@6g@?v;3Hw_#$ zpbGpp1!V75(Lft5^pV@Y%h@ztPT49)LxWy_x5k>p8kitKmyAR1`3X+=YhZ};&;4KE zzXtqW9HYbhz8$xR0nwiud7e24cs25RoT)G;IOW)FVwW>%t>c##0e=%SEOCcx++fj7 z3u8S8xn<0mJHtbe_ZH+;xoVkFLIu{&f^EP{PQ5)UHfD5a)$5QYJ*-(jM7KP%ibq`W ze7#4COIr_TCyM16TR5}*kEqfB{a`J!=6p6k)&7kFytBnBI}Wu}1yli5;7b8HA0oP7 z>@jm_j}8|02|z3}Y>jpK!yufe_R-}?UjUnJ?5DxeDdDFsY986{0F$=|Iji<7%H sqF>O(BrkJlDJ=YTY%6jV@6)ZZEs_c`_Lw **范围声明(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 中,且历史修正尚未沉淀为可验证的统一规则**。 - -该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。 diff --git a/docs/02-design-principles.md b/docs/02-design-principles.md deleted file mode 100644 index ecc2f7c..0000000 --- a/docs/02-design-principles.md +++ /dev/null @@ -1,73 +0,0 @@ -# 02. NEX Core Design Principles - -## 1. 设计目标 - -NEX 默认倡导专业、清晰、可信赖、高信息效率和可预期的产品体验,适用于企业软件、AI 平台、管理系统、内容/知识工作区和专业工具。该气质是默认方向,不是所有产品必须采用的品牌视觉;项目明确的品牌定位和用户研究可以形成不同表达。 - -## 2. 六项核心原则 - -### 2.1 Clarity First — 层级先于装饰 - -- 页面标题、关键数据、主要操作和辅助信息应具有清晰层级。 -- 用户应能判断当前所在位置、当前对象和下一步可执行操作。 -- 不以渐变、阴影、插画或大面积色块替代信息架构。 - -### 2.2 Density with Breathing Room — 信息密度与留白平衡 - -- 信息密度应匹配目标用户、任务频率和屏幕尺寸。 -- 数据表、配置面板和专业工作台允许较高密度,但必须可扫描、可操作。 -- 间距应来自项目定义的尺度或有语义的局部尺寸,而不是逐元素任意微调。 - -### 2.3 Consistency over Novelty — 一致性优先于新奇 - -- 同类任务应采用一致的布局、操作位置、文案和反馈。 -- 新视觉模式必须有可复用理由,不应由单页任意创造。 -- 一致性指设计语法和交互规律,不要求所有页面结构完全相同。 - -### 2.4 Functional Color — 颜色必须有语义 - -- 品牌色、状态色、文本色、背景和边框应有明确用途。 -- 成功、警告、危险和信息状态不能只依赖颜色,还应提供文本、图标或形状线索。 -- 颜色值和语义映射由项目 Token/主题机制管理。 - -### 2.5 Progressive Disclosure — 渐进呈现复杂性 - -- 默认展示完成当前任务所必需的信息。 -- 高级筛选、低频操作和高级配置按需出现。 -- 避免将所有控件和帮助信息同时堆叠在一个视图中。 - -### 2.6 Predictable Interaction — 交互可预期 - -- 用户应能预测操作结果、保存状态、可撤销性和数据影响。 -- 异步操作应有处理中、成功和失败状态。 -- 破坏性操作应有明确确认;成功提示不能替代实际持久化或业务结果。 - -## 3. 视觉构成指导 - -以下是 SHOULD 级建议,不是强制主题: - -- 使用层次清晰的背景、表面和边界;不依赖大量阴影制造层级。 -- 主操作应清楚可辨,但不滥用渐变、发光和强装饰。 -- 图标风格、尺寸和线宽保持一致。 -- 圆角、阴影和动效应形成可复用尺度。 -- 动效用于解释状态变化,不应用于无意义的持续运动。 -- 页面装饰应服务于品牌、内容或任务,不应无理由占用工作空间。 - -具体风格以 Project Design Specification 为准。 - -## 4. 专用工作区 - -文档编辑器、聊天工作区、流程画布、数据分析工作台可以采用独立布局和复杂交互。它们仍应共享项目的字体、颜色语义、Token 治理、焦点状态、反馈规则和可访问性底线。 - -只有项目确实存在某类工作区时,才创建或采用对应模式;不存在的页面类型应标记 `NOT_APPLICABLE`。 - -## 5. 反模式(默认避免) - -除非品牌或业务场景明确需要,应避免: - -- 每个页面都使用大面积渐变 Banner。 -- 大量无语义彩色统计卡片或图标。 -- 各页面单独定义按钮、卡片、圆角和阴影。 -- 仅为“现代感”增加复杂动画。 -- 仅凭颜色表达状态。 -- 为统一而将不同任务的工作区强行做成同一种 CRUD 页面。 diff --git a/docs/02-design-tokens-and-theme.md b/docs/02-design-tokens-and-theme.md new file mode 100644 index 0000000..8f481a9 --- /dev/null +++ b/docs/02-design-tokens-and-theme.md @@ -0,0 +1,44 @@ +# 02. Design Tokens & Theme + +## 1. 单一事实来源 + +同一语义设计值只能有一个权威来源。权威源可以是 TS/JS Token 对象、CSS Variables、JSON/YAML、主题平台导出或 UI 框架主题配置。 + +允许从权威源单向派生到 CSS、组件库主题或样式框架。禁止多个层分别人工维护同一语义值。 + +## 2. Token 语义 + +按项目需要定义: +- Color:brand、success、warning、danger、info; +- Text:primary、secondary、muted、inverse; +- Surface:canvas、surface、elevated、overlay; +- Border/Focus:default、subtle、strong、focus; +- Spacing、Typography、Radius、Elevation、Motion、Layout、Z-index。 + +不要求每个项目建立全部类别,不要求统一物理文件格式。 + +## 3. 命名和适配 + +- 不强制 `--nex-*` 前缀。 +- 优先沿用项目现有变量、主题和命名。 +- 需要映射时,记录设计语义到项目 Token 的对应关系。 +- 不为追求统一建立第二套 Token 层。 + +## 4. 主题 + +- 项目支持 Light/Dark 时,语义 Token 应覆盖两种主题。 +- 页面组件消费语义 Token,不在页面里分散维护主题颜色。 +- 第三方组件库主题应从项目权威 Token 派生。 +- Portal、图表、编辑器、选中态、禁用态和悬浮层应遵循同一主题语义。 +- 单主题项目不必为了规范形式增加另一套主题。 + +## 5. 设计值 + +- 新页面避免散落重复的硬编码设计值。 +- 内容决定的颜色、一次性局部几何值、媒体/图表原始值可合理保留。 +- 例外应局部化,避免把所有数字字面量都当成违规。 +- 旧页面逐步治理,不进行没有语义判断的全局替换。 + +## 6. 尺度 + +字号、间距、圆角、阴影、控件高度、内容宽度和导航尺寸由项目按品牌与任务定义。NEX 不规定跨项目固定像素值。 diff --git a/docs/03-design-tokens.md b/docs/03-design-tokens.md deleted file mode 100644 index 07fefa9..0000000 --- a/docs/03-design-tokens.md +++ /dev/null @@ -1,112 +0,0 @@ -# 03. Design Tokens & Theme Governance - -## 1. 目标 - -NEX 要求项目视觉值可治理、语义清晰、主题行为可追踪;不强制项目采用某种 Token 文件格式、变量前缀、CSS 方案或组件库。 - -## 2. 单一事实来源(Single Source of Truth) - -同一语义 Token 必须有一个权威来源。该来源可以是: - -- TypeScript/JavaScript Token 对象; -- CSS Variables; -- JSON/YAML Token 文件; -- 设计 Token 平台导出; -- UI 框架主题配置(若它确实是权威源)。 - -项目可以将权威源单向派生为其他消费层。例如: - -```text -project theme tokens - │ - ├── UI library theme adapter - │ - ├── CSS custom properties - │ - └── utility framework theme -``` - -**单一事实来源不等于所有值必须写在一个物理文件中。** 关键是来源关系明确、方向唯一、派生层不独立人工维护,并且有可验证的映射。 - -如果项目已有经过验证的主题管线(例如某个主题配置向 CSS/框架变量单向派生),应优先保留,不要为了套用 NEX 示例而增加第二套 Token 存储。 - -## 3. 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 等 | 层叠上下文 | - -项目不必为每一类都建立大量 Token;只有确实需要统一管理的语义才建立。 - -## 4. 命名和适配原则 - -- 不强制使用 `--nex-*` 前缀。 -- 优先沿用项目现有命名和消费方式。 -- 如需把 NEX 语义映射到项目 Token,应建立“语义概念 → 现有 Token → 权威来源/派生链路 → 使用位置”映射表。 -- 只有在项目缺少可用命名体系、且确认不会冲突时,才可按项目决策新增命名空间。 -- 不要把多个语义不同的旧 Token 机械映射到同一个 Token。 - -映射表示例(变量名仅为示意): - -| NEX 语义 | 项目现有 Token | 权威来源 | 使用方式 | -|---|---|---|---| -| Brand | `--color-primary` | `theme/tokens.ts` | CSS 与组件库主题派生 | -| Surface | `--panel-bg` | `theme/tokens.ts` | 面板背景 | -| Text Secondary | `--text-muted` | `theme/tokens.ts` | 辅助文本 | - -## 5. 主题治理 - -- 若产品支持 Light/Dark,语义 Token 应在主题层成对定义。 -- 页面组件应消费语义 Token,不应各自重复判断主题并维护一套颜色。 -- 第三方组件库主题应与项目 Token 保持明确映射。 -- 检查弹层、Portal、图表、代码区、编辑器、选中态、禁用态和悬停态在各主题下的表现。 -- 若项目只支持单主题,不得为了形式完整而擅自引入另一套主题。 - -## 6. 设计值与硬编码 - -新代码不得在业务页面散落无语义、重复使用的设计值。以下情形可允许局部字面量: - -- 由内容本身决定的颜色(例如语法高亮、用户生成内容、第三方品牌); -- 只在一个局部组件中使用、且没有跨场景复用价值的精确几何值; -- 由标准、协议、图表数据或媒体原始尺寸决定的数值。 - -例外必须局部限域并说明原因;不应把所有数字/颜色字面量都误判为设计违规。旧代码分批迁移,不做未经语义核验的全局搜索替换。 - -## 7. 尺度定义 - -间距、字体、圆角、阴影、控件尺寸、断点和容器宽度由项目按用户任务、信息密度和目标设备定义。NEX 不规定跨项目统一的固定像素表。 - -建议: -- 为常见尺寸建立有限、可复用的尺度。 -- 区分密集数据界面和宽松内容界面。 -- 控件点击热区满足适用的可访问性与平台要求。 -- 对布局关键尺寸指定单一来源,避免 CSS、组件属性和主题配置各自维护冲突值。 - -## 8. 层级与动效 - -- 项目应建立可理解的 Z-index 层级或使用组件库的层级管理能力。 -- 不得通过不断增大数值解决未知层叠问题;先识别 stacking context、Portal 和层级归属。 -- 动效应尊重 `prefers-reduced-motion` 或目标平台等效设置。 -- 动效时长和缓动由项目设计规范决定,不规定跨项目固定毫秒值。 - -## 9. 验收要求 - -- [ ] 权威 Token 来源已明确。 -- [ ] 派生关系单向且可追踪。 -- [ ] 语义 Token 与实际消费位置有映射。 -- [ ] 没有未经说明的重复 Token 层。 -- [ ] 支持的主题覆盖关键组件和状态。 -- [ ] 设计值例外已限域并说明。 -- [ ] 布局尺寸没有多个互相冲突的权威定义。 diff --git a/docs/03-layout-and-responsive.md b/docs/03-layout-and-responsive.md new file mode 100644 index 0000000..d9cefb0 --- /dev/null +++ b/docs/03-layout-and-responsive.md @@ -0,0 +1,42 @@ +# 03. Layout, Navigation & Responsive Design + +## 1. 布局原则 + +NEX 统一布局职责、信息层级和跨尺寸体验,不统一具体 Shell、导航形态、像素尺寸或断点。项目级 UI 规范决定具体实现。 + +## 2. 页面与工作区类型 + +按项目实际需要选择: +- 管理页面:列表、详情、编辑、设置; +- 概览页面:Dashboard、监控、分析; +- 专业工作区:文档、聊天、流程、画布、IDE、媒体编辑; +- 独立入口:登录、公开分享、邀请、向导。 + +项目不存在的页面类型不需要引入模板。 + +## 3. Shell 与导航 + +- 当前所在模块、路由和用户上下文清楚。 +- 导航区与内容区的滚动职责明确。 +- 桌面导航偏好与移动端临时 Drawer 状态可以采用不同生命周期。 +- 小屏导航应为内容保留空间,不应简单缩小桌面侧栏。 +- 当前选中状态和菜单名称清楚,关键导航可通过键盘操作。 + +## 4. 响应式设计 + +- 优先沿用项目已有断点体系。 +- 断点由内容和组件最小可用宽度决定,不按设备型号机械划分。 +- 如需增加断点,采用语义化命名并集中登记;不得在页面随意散落互不关联的媒体查询。 +- 小屏重新组织信息和操作,不只是缩小桌面布局。 +- 工具栏应允许折行、收纳次要操作或转为菜单。 +- 表格应按数据任务选择:保留关键列、折叠次要信息、横向滚动、卡片化或详情展开。不得让关键字段和行操作在窄屏消失。 +- 长文本、长文件名、代码块和媒体内容不得撑破主布局。 +- 复杂工作区应明确主滚动容器、面板收缩和溢出处理。 + +## 5. 布局尺寸与滚动 + +- Header、Sider、内容留白、最大宽度和控件尺寸以项目规范为准。 +- 关键尺寸应有清晰来源,避免 CSS、组件属性和主题配置互相冲突。 +- 复杂 Flex/Grid 区域合理处理 `min-width: 0`、`min-height: 0`。 +- 避免在多个祖先层级无理由叠加 `overflow: auto/hidden`。 +- 固定高度应有产品理由,优先使用弹性布局和内容约束。 diff --git a/docs/04-component-system.md b/docs/04-component-system.md new file mode 100644 index 0000000..6868462 --- /dev/null +++ b/docs/04-component-system.md @@ -0,0 +1,49 @@ +# 04. Component System & Reuse + +## 1. 原则 + +NEX 不要求安装或开发名为 NEX 的 UI 组件库。项目已有组件体系是优先实现载体。NEX 约束的是复用方式、组件职责和对用户可见的行为。 + +## 2. 先复用再新增 + +开发前查看已有基础组件、表单组件、布局组件、反馈组件、复合组件和业务组件。 + +决策顺序: +1. 现有组件能力满足:直接复用; +2. 缺少通用能力:向后兼容扩展; +3. 多处重复出现且接口稳定:抽象共享组件; +4. 单页特例:保留局部实现; +5. 第三方组件已足够:不机械包装。 + +## 3. 组件职责 + +- Foundation:Token、主题、字体、图标、焦点样式; +- Primitive:Button、Input、Select 等基础控件; +- Composite:页面标题、筛选栏、数据工具栏、统计区; +- Pattern:列表、编辑流程、工作区等页面组合。 + +以上是职责分类,不要求固定目录、命名或必须全部实现。 + +## 4. 常见组件设计契约 + +### Page Heading +标题、说明、导航上下文和主操作层级明确;窄屏下不能相互挤压。 + +### Search / Filter +搜索、筛选、重置和应用行为一致;已应用条件可见;批量操作只在有选中项时呈现。 + +### Data Table / List +列优先级清晰;行点击与行内操作不冲突;分页、排序、选择行为符合项目约定;窄屏保留关键数据和操作。 + +### Form +标签、必填、帮助信息和错误信息关系清楚;提交中避免重复触发;取消时明确未保存内容处理方式。 + +### Modal / Drawer / Overlay +根据任务复杂度选择容器;焦点进入与返回、关闭方式和层级行为符合交互语义。 + +### Feedback / Status +状态不只依赖颜色;截断的重要内容应有可获取的完整名称;装饰图标不混入可访问名称;图标按钮使用描述动作的业务名称,不暴露内部 glyph 名。 + +## 5. 避免重复抽象 + +不要仅为统一命名把已有 `PageHead`、`Ctlbar`、`DataTable` 重命名为 `Nex*`。只在复用收益明确时抽象。 diff --git a/docs/04-layout-system.md b/docs/04-layout-system.md deleted file mode 100644 index 2372c74..0000000 --- a/docs/04-layout-system.md +++ /dev/null @@ -1,120 +0,0 @@ -# 04. Layout System & Page Shells - -## 1. 布局治理原则 - -NEX 统一的是布局的职责分离、信息层级、响应式和交互质量,不要求所有项目使用相同导航结构或像素尺寸。具体 Shell、导航形态、Header/Sider 尺寸、内容边距、断点和滚动策略由项目规范定义。 - -## 2. 页面类型识别 - -实施前先按用户主要任务识别页面类型,例如: - -- 管理型页面:列表、详情、编辑、设置、权限等。 -- 概览型页面:Dashboard、监控和分析。 -- 专业工作区:文档、聊天、流程、画布、IDE、媒体编辑等。 -- 独立入口:登录、分享、公开展示、向导等。 - -以上是分类参考,不要求项目必须拥有所有类型。不存在的类型标记 `NOT_APPLICABLE`。 - -## 3. Shell 模式(概念性,不是组件命名要求) - -### 3.1 应用 Shell - -适用于需要全局导航、模块切换和统一页面容器的产品。可采用侧边导航、顶部导航、混合导航或其他经过验证的模式。 - -职责建议: -- 全局导航、当前上下文和用户入口清晰。 -- 导航区域与主内容区滚动行为明确。 -- 页面内容区域具有可预测的留白和宽度策略。 -- 导航折叠/展开状态可恢复,且键盘操作可达。 - -### 3.2 内容/文档工作区 - -仅在产品存在文档阅读、编辑或文件管理任务时采用。 - -- 文件树、工具栏、编辑区/预览区职责分离。 -- 需要独立滚动时,应明确每个滚动容器的边界。 -- 编辑与预览应保持合理一致的内容宽度和阅读节奏。 -- 嵌套 Flex/Grid 子项在需要收缩时检查 `min-width: 0`、`min-height: 0`。 - -### 3.3 对话工作区 - -仅在产品存在 AI Chat 或多轮消息任务时采用。 - -- 消息历史与输入区职责分离。 -- 输入区在长消息流中保持可达。 -- 会话列表、消息区和工具面板的滚动关系明确。 -- 停止、重试、复制、引用和工具执行状态可理解。 - -### 3.4 专业工作台/画布 - -适用于流程编辑、数据分析、多面板控制和复杂创作任务。 - -- 主工作区优先获得足够空间。 -- 可折叠/可调整面板的状态可预测。 -- 拖拽操作应有键盘或其他非拖拽替代路径。 -- 不使用普通后台页面的最大宽度限制挤压画布,除非产品规范明确要求。 - -### 3.5 独立页面 Shell - -适用于登录、公开分享、邀请和向导等无需完整应用导航的页面。保持品牌和组件语义一致,但不强制显示全局导航。 - -## 4. 普通业务页面的信息顺序 - -可按任务选择: - -1. 页面上下文/标题/面包屑。 -2. 关键指标(只有帮助判断时才展示)。 -3. 搜索、筛选、视图切换或批量操作。 -4. 主内容(表格、卡片、表单、详情或图表)。 -5. 帮助、审计信息或辅助说明。 - -不要为了填满空间添加没有业务价值的卡片或模块。 - -## 5. 响应式布局 - -- 优先复用项目已有断点和组件库响应式规则。 -- 不强制采用某一固定断点数值;新增断点必须有真实布局需求和验证依据。 -- 明确桌面、平板、窄屏下导航、表格、表单、工具栏和多栏工作区的变化。 -- 不应简单缩小桌面布局来冒充移动端体验。 -- 避免无意的整页横向滚动;宽表格可按项目设计采用横向滚动或替代呈现。 - -## 5.1 命名断点登记与边界测试 - -项目应优先使用已经存在的断点体系。若标准断点无法满足真实内容布局、信息密度或组件最小宽度要求,可以增加项目级命名断点;不应为了减少断点数量而接受明显的内容遮挡、操作挤压或不合理回退。 - -每个扩展断点至少登记: -- 名称和数值/范围(含 min/max 语义); -- 解决的具体布局问题和涉及组件/页面; -- 权威定义位置(例如 Tailwind theme、CSS custom properties、媒体查询注册表或设计 Token); -- 与相邻断点的行为差异; -- 断点前、断点处、断点后的验证视口; -- 负责人/批准记录和复审条件。 - -新增断点必须测试边界两侧,避免只在常见设备预设宽度截图而遗漏临界区间。测试宽度应由实际断点决定,并覆盖项目声明的关键视口。 - -## 5.2 导航状态的生命周期 - -不同导航状态不必合并成一个持久化 Boolean。应按状态语义区分: -- **用户偏好状态**:例如桌面端侧栏折叠/展开,可按产品规范持久化。 -- **临时交互状态**:例如移动端 Drawer 当前是否打开,通常只在当前页面会话中有效,不应因刷新而自动保持打开。 -- **共享导航上下文**:导航项定义、当前路由、选中状态和权限可共享;这不意味着偏好状态与临时状态必须共用同一状态变量。 - -状态持久化策略必须符合用户预期,避免移动端刷新后被意外遮罩,也避免桌面端偏好无故丢失。 - -## 6. 滚动与尺寸约束 - -- 明确页面主滚动容器和嵌套工作区滚动容器。 -- 不要在多个祖先层级重复设置 `overflow: auto/hidden` 而不清楚滚动归属。 -- 检查长文本、长文件名、代码块、表格和媒体内容是否撑破布局。 -- 固定高度应有产品理由;优先使用父容器约束、弹性布局或视口计算。 -- 对 Flex/Grid 子项检查 `min-width: 0` 和 `min-height: 0`,但不要机械地全局添加。 - -## 7. 实施前必须记录 - -页面或 Shell 改造前,记录: -- 当前 Shell 和导航行为; -- 关键尺寸的权威来源; -- 视口变化时的布局行为; -- 滚动容器归属; -- 受影响页面清单; -- 现有视觉截图或可用回归检查。 diff --git a/docs/05-component-system.md b/docs/05-component-system.md deleted file mode 100644 index b63dbb3..0000000 --- a/docs/05-component-system.md +++ /dev/null @@ -1,96 +0,0 @@ -# 05. Component System & Reuse Contracts - -## 1. 核心原则 - -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、Tooltip | -| Composite | 高频复合组件 | 页面头部、搜索栏、表格工具栏、指标卡 | -| Pattern | 页面/任务模式 | 列表管理、编辑流程、专业工作区 | - -项目可采用不同目录结构或命名方式。 - -## 5. 常见能力合同 - -以下是能力要求,不是要求必须创建这些组件: - -### Page Heading -- 标题、说明、面包屑和主操作层级明确。 -- 小屏下标题和操作不会互相挤压。 -- 强调型 Hero 只在项目设计规范允许的场景使用。 - -### Search / Filter Toolbar -- 搜索、筛选、重置和应用行为可预测。 -- 已应用筛选条件可见。 -- Enter 搜索、自动搜索或显式提交按项目规范统一。 -- 批量操作仅在存在选中项时展示或启用。 - -### Data Table / List -- 加载、空数据、错误、无权限和分页状态清晰。 -- 行点击与行内操作不互相吞事件。 -- 选择、排序、筛选和分页行为一致。 -- 长内容、窄屏和键盘导航有可用策略。 - -### Form -- 必填、校验、错误、提交中和保存结果清晰。 -- 字段标签、帮助文案和错误信息可关联。 -- 取消/关闭时对未保存内容的行为明确。 - -### Modal / Drawer / Overlay -- 容器选择符合任务复杂度和上下文需要。 -- 焦点进入、焦点返回、Esc 行为和遮罩交互合理。 -- 层级由项目层级体系/组件库管理。 - -### Feedback / Status -- 状态同时具备文本或图标语义,不只靠颜色。 -- 长标签截断时必须提供可访问的完整文本;Tooltip 只是一个呈现渠道,不得成为键盘或触屏用户获取关键内容的唯一方式。 -- 装饰性图标不得混入控件的可访问名称;图标与可见文本并列时应避免重复朗读。 -- 图标按钮必须有简洁、描述动作的可访问名称;不得把图标库内部名称、字体字形名或 glyph token(例如 `upload`、`down`)拼进用户可读名称。 -- 当文本本身已提供名称时,伴随图标通常应从辅助技术名称计算中隐藏;当图标承载唯一含义时,应为控件提供明确的业务名称。 -- 通知、行内提示和页面级错误的使用场景不混淆。 - -## 6. 组件变更验收 - -修改共享组件时,至少检查: -- 所有已知调用方; -- 默认值和变体兼容性; -- Light/Dark(若项目支持); -- 桌面和窄屏行为; -- 键盘与可访问性; -- 空、加载、错误和禁用状态; -- 视觉回归范围。 - -## 7. 参考命名说明 - -`NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard` 等名称只用于表达一类能力,不构成命名要求。若项目已有等价组件,应建立映射并复用,不要为追求 NEX 命名一致而重命名或重构成熟资产。 diff --git a/docs/05-interaction-system.md b/docs/05-interaction-system.md new file mode 100644 index 0000000..0c06a1e --- /dev/null +++ b/docs/05-interaction-system.md @@ -0,0 +1,55 @@ +# 05. Interaction System + +## 1. 一致性 + +同类操作应保持一致的触发方式、位置、状态变化、反馈和异常处理。NEX 不要求不同业务页面采用完全相同的操作流程。 + +## 2. 操作层级 + +- Primary:当前页面最重要的操作,避免同一视图出现多个竞争性主按钮。 +- Secondary:辅助操作。 +- Destructive:删除、移交等高风险操作,明确说明后果。 +- Contextual:行内或对象级动作,不与主要动作争夺注意力。 + +## 3. 表单 + +- 标签清楚,校验信息靠近字段。 +- 提交中明确呈现状态并避免重复触发。 +- 成功后按任务流关闭弹层或跳转。 +- 取消时对未保存内容的处理明确。 +- 长表单按业务主题分组,不为视觉分段而过度使用卡片。 + +## 4. 搜索与筛选 + +- 简单搜索和高级筛选分层呈现。 +- Enter、自动搜索或显式提交按项目规范统一。 +- 已应用条件可见;重置和刷新含义不同。 +- 批量操作应呈现选中数量和适用条件。 + +## 5. 表格 + +- 排序、筛选、分页和选择状态清晰。 +- 行点击与行内动作互不误触。 +- 破坏性操作有明确确认。 +- 长文本截断时提供适当的完整内容获取方式。 +- 窄屏按项目的数据任务组织列、卡片和操作,不盲目隐藏信息。 + +## 6. 容器选择 + +| 场景 | 常见选择 | +|---|---| +| 简短确认、少量字段 | Modal | +| 详情、侧向编辑、保留列表上下文 | Drawer | +| 长表单、多步骤、复杂向导 | 独立页面 | +| 阅读、编辑、PDF、媒体工作 | 专用工作区 | +| 持续多轮交流 | 对话工作区 | + +这些是建议,不替代项目既有模式。 + +## 7. 状态反馈 + +交互应有清晰的默认、处理中、成功、失败、空、禁用和无权限状态。反馈文案应说明发生了什么以及用户下一步能做什么。状态提示不得仅依赖颜色。 + +## 8. 导航与焦点 + +弹层打开后,焦点进入合理位置;关闭后返回触发点或合理后续位置。Escape、遮罩关闭、浏览器返回等行为符合容器用途。键盘操作不应被自定义热区破坏。 diff --git a/docs/06-accessibility-design.md b/docs/06-accessibility-design.md new file mode 100644 index 0000000..fbd655f --- /dev/null +++ b/docs/06-accessibility-design.md @@ -0,0 +1,55 @@ +# 06. Accessibility as a Design Requirement + +本文件定义产品界面应如何设计和实现无障碍体验。它不是屏幕阅读器测试手册、测试矩阵或质量验收流程。 + +## 1. 设计目标 + +默认以 WCAG 2.2 AA 作为 Web 产品的设计参考目标;具体法规、合同或客户要求优先。采用 NEX 不代表自动取得合规认证。 + +## 2. 语义结构 + +- 使用符合意图的原生 HTML:按钮用 `button`,导航用 `nav`,链接用 `a`,表单控件使用适当原生元素。 +- 不把普通 `div` 当作交互控件,除非确实需要自定义复合控件并补齐语义与键盘行为。 +- 标题层级表达内容结构,不因视觉大小跳过语义层级。 +- 表单标签与控件建立明确关联;分组字段使用合适的语义分组。 + +## 3. 名称与图标 + +- 每个交互控件都要有准确、简洁、可理解的可访问名称。 +- 图标旁已有可见文本时,装饰图标通常不参与名称计算,避免重复朗读。 +- 图标按钮应提供描述实际动作的业务名称。 +- 不将图标字体、glyph token 或内部图标库名称作为用户文案。 +- 重要截断文本必须有键盘、触屏和辅助技术均可获取的完整信息;不能只依赖 Hover Tooltip。 + +## 4. 键盘与焦点 + +- 核心功能应可通过键盘完成。 +- Tab 顺序应符合视觉与任务顺序;焦点必须清晰可见。 +- 自定义控件应采用用户熟悉的键盘交互模式。 +- 拖拽排序、画布移动等操作应提供非拖拽替代路径,例如上移/下移按钮或其他等效操作。 +- 弹层、菜单和复合组件应明确焦点进入、移动、退出和返回方式。 + +## 5. 状态与动态内容 + +- 状态不只依赖颜色,还应提供文本、图标或形状线索。 +- 错误信息应指出问题和修正方向。 +- 动态结果、保存状态和重要反馈应采用合适的语义表达;避免对每次细微变化都造成过量播报。 +- 仅在必要时使用 Live Region,并让提示内容简洁、时机合理。 + +## 6. 视觉可读性 + +- 文本和交互元素与背景保持足够对比。 +- 不仅用颜色区分状态、图表系列或错误。 +- 字体大小、行高和内容宽度应支持长时间阅读。 +- 焦点、选中、禁用和悬停状态应有可辨识差异。 + +## 7. 动效与输入方式 + +- 尊重 `prefers-reduced-motion` 或目标平台等效设置。 +- 关键操作不能只依赖 Hover。 +- 触控目标应有合理尺寸和间距,避免相邻操作误触。 +- 为拖拽、滑动或复杂手势提供其他可用操作方式。 + +## 8. 适用性 + +上述要求适用于项目真实存在的页面和控件。NEX 不要求每个项目都建立屏幕阅读器测试环境,也不规定 VoiceOver、NVDA、Orca 的启动、执行或记录流程;项目如有相关测试要求,由项目自己的工程规范决定。 diff --git a/docs/06-interaction-system.md b/docs/06-interaction-system.md deleted file mode 100644 index a004ad0..0000000 --- a/docs/06-interaction-system.md +++ /dev/null @@ -1,83 +0,0 @@ -> **适配说明:** 本文描述跨项目交互原则和常见模式。具体组件、快捷键、反馈样式和操作路径以项目级规范及现有成熟实现为准。 - -# 06. NEX Interaction System - -## 1. 交互一致性 - -NEX 把交互视为产品合同。同一种操作在不同模块中应保持相同触发方式、位置、状态变化、反馈和异常处理。 - -## 2. 页面操作层级 - -- **Primary Action**:当前页面最重要的一个操作,通常位于 PageHeader 右侧或表单 Footer。 -- **Secondary Action**:辅助操作,采用次级按钮或文字按钮。 -- **Destructive Action**:删除、撤销、转移所有权等不可逆/高风险操作,采用危险色并要求确认。 -- **Contextual Action**:行内、卡片或对象级动作,默认不与主操作争夺视觉注意力。 - -同一视图原则上只设一个明显的主要动作;避免多个同等级实心主按钮并排。 - -## 3. 表单交互 - -- 标签清晰,必填标识一致;校验信息靠近对应字段。 -- 校验既要在客户端进行,也要正确展示服务端错误。 -- 提交期间禁用重复提交,并显示 Loading。 -- 成功后给出明确反馈,并按照任务流关闭 Modal/Drawer 或跳转。 -- 取消时若有未保存改动,必须确认或提供保留草稿机制。 -- 长表单按业务主题分组;不要仅为视觉分段而过度使用 Card。 - -## 4. 搜索与筛选 - -- 简单搜索与高级筛选分层呈现。 -- 搜索框位置、宽度策略、清空按钮和 Enter 行为在同类页面保持一致。 -- 已应用筛选条件应可见;清空筛选要能恢复默认结果。 -- 批量操作只在选择状态出现,并显示选中数量。 -- 刷新与重置不是同一行为:刷新重新加载当前条件结果,重置清除条件。 - -## 5. 表格交互 - -- 列排序、筛选、分页和行选择必须有明确的状态反馈。 -- 行点击用于进入详情时,行内菜单/按钮必须阻止事件冒泡,避免误跳转。 -- 分页变更后是否保留选择需按数据类型明确规定;不得出现隐式丢失选择。 -- 删除等危险操作不能仅依赖行内图标,必须有可理解的确认文案。 -- 长文本显示省略时,需提供 Tooltip、详情或复制能力。 - -## 6. Modal / Drawer / Page 选择 - -| 场景 | 默认容器 | -|---|---| -| 简短确认、1–5 个字段的小表单 | Modal | -| 查看对象详细信息、侧向编辑、需要保留列表上下文 | Drawer | -| 长表单、多步骤流程、复杂向导、独立 URL | 独立页面 | -| 文件阅读、Markdown 编辑、PDF 预览 | 专用 Workspace | -| 需要持续对话的 AI 交互 | Conversation Workspace | - -不要仅因为页面已经存在 Modal 组件,就把所有编辑功能塞入 Modal。 - -## 7. 反馈状态 - -每个异步交互至少考虑: - -- Idle:默认状态。 -- Loading:正在处理,防止重复触发。 -- Success:成功结果和后续动作。 -- Error:失败原因与恢复方式。 -- Empty:没有数据或没有匹配结果。 -- Disabled:明确不可用原因(必要时 Tooltip/帮助文本)。 - -反馈选择: - -- 短暂、非阻塞操作:Message/Toast。 -- 需要用户理解结果或采取动作:Notification 或页面内状态。 -- 长时间后台任务:任务状态区域/进度视图,不只弹一个 Toast。 -- 删除/权限等风险确认:Modal Confirm。 - -## 8. 主题切换 - -- 主题切换不应丢失当前页面上下文和输入状态。 -- 所有自定义表面、文字、边框、悬停、选中、代码区和图表都要检查暗色主题。 -- 禁止业务 CSS 为了暗色主题重新写一套与基础 token 不同的语义。 - -## 9. 动效 - -- 动效必须解释状态变化,例如展开、收起、切换、加载完成。 -- 避免对普通卡片普遍使用大幅上浮和缩放。 -- 尊重减少动态效果设置。 diff --git a/docs/07-page-patterns.md b/docs/07-page-patterns.md deleted file mode 100644 index 96261a2..0000000 --- a/docs/07-page-patterns.md +++ /dev/null @@ -1,81 +0,0 @@ -> **适配说明:** 以下页面模式是可选参考,不是功能清单。项目不存在的类型应标记 `NOT_APPLICABLE`,不得为满足文档而创建页面或组件。现有项目模式优先。 - -# 07. NEX Page Patterns - -## 1. Dashboard / Overview - -组成:PageHeader(可用 Hero)→ 关键指标 → 趋势/图表 → 最近活动或重点数据。 - -规则: -- 只展示可帮助决策的指标;指标卡建议控制在一行可读范围内。 -- 指标卡使用统一网格;屏幕变窄时逐级降列。 -- 图表、表格和指标使用一致的数据时间范围与筛选上下文。 -- 页面不应堆叠没有业务关联的多个卡片。 - -## 2. Data List / 列表页 - -推荐结构: - -```text -PageHeader(标题、说明、主操作) -SearchToolbar(搜索、筛选、重置、刷新、视图) -SelectionToolbar(仅有选中数据时显示) -DataTable 或 CardGrid -Pagination(如不由 DataTable 承载) -``` - -规则: -- 列表页标题和搜索操作不要混为一个视觉层级。 -- 过滤器位置和展开方式稳定。 -- 表格滚动由页面可用空间决定,不能写死统一像素高度。 -- 卡片网格可以用于对象浏览,但必须定义卡片信息优先级和统一高度策略。 -- 空数据、首次创建和搜索无结果是不同状态,不能用同一种 Empty 文案。 - -## 3. Detail / 详情页 - -组成:返回/面包屑 → 对象标题与状态 → 主要操作 → 摘要信息 → Tabs/分区详情 → 审计/关联信息。 - -规则: -- 先说明“这是哪个对象、处于什么状态”,再展示详细字段。 -- 重要状态始终可见;危险操作收纳在次级操作菜单或明确危险区域。 -- 长详情使用分区,不要把所有字段放入单张长表格。 - -## 4. Form / 创建与编辑页 - -规则: -- 标题表达当前任务(创建/编辑具体对象)。 -- 字段按用户心智模型分组,而非按数据库字段顺序排列。 -- 主操作与取消始终固定在一致位置。 -- 保存失败保留用户已输入数据。 -- 需要复杂帮助或动态配置时使用分步/分组,不应把长表单压进窄 Modal。 - -## 5. Settings / 配置页 - -规则: -- 分类导航与配置内容分区清晰。 -- 每个配置组有标题、用途说明和独立保存边界(如适用)。 -- 破坏性/高风险配置与普通偏好设置分离。 -- 未保存状态需要可见。 - -## 6. Document Workspace - -规则: -- 文件树、文档上下文、正文画布、工具栏职责清楚。 -- 正文宽度和行长稳定;代码、表格、图片等可在画布内滚动。 -- 阅读模式与编辑模式共享字体、标题层级、列表、表格和代码样式。 -- 目录定位、搜索高亮、滚动恢复等专业行为要有稳定状态。 - -## 7. Conversation Workspace - -规则: -- 会话历史与当前消息区分区明确。 -- 输入区域固定;附件、模型、项目、发送/停止状态集中组织。 -- 引用来源与普通正文有明显层级,但不抢占正文阅读。 -- 助手生成中、工具调用中、失败和可重试状态可区分。 - -## 8. Auth / Share 页面 - -规则: -- 认证页聚焦唯一任务,不显示无关导航。 -- 分享页面明确标注访问对象、权限和有效性。 -- 对没有权限、链接失效、对象不存在等状态给出不同提示。 diff --git a/docs/07-performance-aware-design.md b/docs/07-performance-aware-design.md new file mode 100644 index 0000000..7777915 --- /dev/null +++ b/docs/07-performance-aware-design.md @@ -0,0 +1,33 @@ +# 07. Performance-aware UI Design + +本文件只规定与用户感知体验相关的设计和实现原则。它不定义性能测试、指标采集、预算阈值、Bundle 审计或 CI 性能闸门。 + +## 1. 感知性能 + +- 用户触发操作后,应尽快获得明确反馈,避免界面看似无响应。 +- 长任务应呈现处理中状态;能分阶段呈现的内容可逐步展示。 +- 内容加载时尽量保持布局稳定,避免主要区域突然跳动。 +- Loading、Skeleton 等呈现方式应服务于真实加载过程,不作为装饰。 + +## 2. 内容与资源呈现 + +- 图片按实际展示尺寸提供,不在小缩略图区域加载不必要的大图。 +- 视频、音频和大文件采用明确的预览/加载入口,避免进入页面就无条件加载全部资源。 +- 长列表和大数据集应采用符合任务的分页、分段呈现或虚拟列表设计;选择方式应保持用户对位置和上下文的理解。 +- 首屏优先展示完成当前任务所需的内容,低频模块按需呈现。 + +## 3. 动效与视觉开销 + +- 避免持续、无目的的动画和大面积高成本视觉效果。 +- 状态动效应短暂、可理解,并尊重减少动态效果的系统偏好。 +- 不为装饰加入影响阅读、滚动或操作响应的效果。 + +## 4. 交互中的性能感知 + +- 按钮在异步处理中应明确显示状态,避免重复点击。 +- 搜索、筛选和自动保存等行为应避免不必要的频繁触发。 +- 复杂工作区在加载、切换面板和切换数据时保持操作上下文清晰。 + +## 5. 技术选择边界 + +上述内容是设计层面的用户体验原则。具体代码分包、缓存、Web Vitals、Bundle 预算、性能分析和优化工具属于项目技术架构与性能工程范围,不由 NEX 规定。 diff --git a/docs/08-accessibility-responsive.md b/docs/08-accessibility-responsive.md deleted file mode 100644 index bd200b6..0000000 --- a/docs/08-accessibility-responsive.md +++ /dev/null @@ -1,132 +0,0 @@ -# 08. Accessibility & Responsive Quality - -## 0. 无障碍基线与适用范围 - -NEX 将 **WCAG 2.2 Level AA** 作为 Web 产品默认的工程设计目标。项目如受法律、合同、采购规范或行业标准约束,应采用其中更严格或更具体的要求。此目标是工程基线,不代表仅凭自动化扫描即可宣称整站符合 WCAG,也不替代正式合规评估。 - -无障碍是产品质量要求,不是某一种屏幕阅读器或操作系统的专属功能。所有项目都应按适用性处理可感知、可操作、可理解和健壮性要求;具体实现可以使用原生 HTML、ARIA、组件库或项目既有机制。 - -日常开发和每轮变更的默认验收方式是: - -1. E0 源码/语义审阅; -2. E1 自动化可访问性与行为测试; -3. E2 浏览器键盘/指针交互验证。 - -E3 真实屏幕阅读器测试是**按风险和目标平台选择的专项验证**,不是每次代码修改、每个页面或每个项目都必须启动的常规步骤。E3 的操作系统与读屏器组合见 `docs/14-accessibility-platform-matrix.md`。Agent 未获明确授权,不得自行启动、关闭或更改用户的屏幕阅读器设置。 - -## 1. 语义优先与可访问名称 - -- 触发动作使用原生按钮语义;页面跳转使用链接语义。避免用可点击 `div` / `span` 模拟按钮或链接,除非有充分理由且完整实现相应 ARIA、键盘和焦点行为。 -- 表单控件必须有准确、稳定的可访问名称;错误信息应与对应控件建立程序化关联。 -- 图标按钮必须有描述动作的可访问名称,名称应使用用户熟悉的业务语言。 -- **纯装饰图标必须从辅助技术名称计算中排除。** 对 SVG/图标组件/图标字体等,使用项目适当的机制(例如 `aria-hidden="true"`),并防止图标内部字形名或组件名泄漏到可访问名称。 -- 图标与可见文本并列时,通常由可见文本提供名称,装饰图标不应重复朗读。只有图标本身承载唯一语义时,才为控件提供明确的可访问名称。 -- 不要把 `upload`、`down`、`chevron-right` 等图标库内部名称、字体字形名或代码标识直接拼进用户可读名称。 - -## 2. 截断文本和完整名称的多通道可用性 - -重要项目名称、状态、错误文本和关键字段即使视觉上截断,也必须保留完整内容,并按交互形态提供适当渠道: - -1. **辅助技术名称/文本:** 完整内容应存在于可访问树或可展开内容中,不得只保留省略后的短文本。 -2. **键盘通道:** 对可聚焦控件,Focus 时应能获取完整内容;非交互文本可按需提供可聚焦详情或相邻说明,不要无意义地让所有文本进入 Tab 顺序。 -3. **指针 Hover 通道:** 仅在设备确实支持悬停时启用 Hover Tooltip。可用 `@media (hover: hover) and (pointer: fine)` 或项目等效能力检测,不能把 Hover 当作触屏能力。 -4. **触屏通道:** 触屏用户应能通过点击、详情面板或其他明确方式获取完整内容,不能要求 Hover。 - -避免重复播报:如果可访问名称已经包含完整文本,不要再把 Tooltip 内容机械追加成第二份重复名称。`title`、Tooltip、`aria-label` 应根据元素语义选择,不应互相堆叠。 - -## 3. 键盘和焦点 - -- 所有核心功能应可通过键盘访问。 -- Tab 顺序应与视觉和任务顺序一致;焦点必须清晰可见。 -- Enter / Space 的行为应符合控件语义。 -- 不得通过 CSS 全局移除焦点轮廓而不提供替代样式。 -- Modal、Drawer、Popover 等浮层应正确管理焦点进入、焦点返回和关闭行为。 -- 自定义快捷键应避开常见浏览器和辅助技术冲突;不能仅通过声明 `aria-keyshortcuts` 就认为用户已获得操作能力或读屏软件一定会播报。 - -## 4. 拖拽和复杂指针交互 - -任何依赖拖拽完成的核心操作都必须提供非拖拽替代路径,例如: - -- 通过按钮/菜单选择“上移/下移”或目标位置; -- 通过键盘命令完成移动、排序或节点连接; -- 提供可聚焦的操作控件和明确的状态反馈。 - -不能假设 HTML5 Drag and Drop API 自身就提供完整键盘体验。替代路径必须在功能上等价,不能只增加一个没有实际行为的快捷键说明。 - -对复杂排序、画布、流程编辑器和其他自定义复合控件,先通过 E0–E2 验证语义、键盘路径和操作结果;只有符合风险触发条件时,再安排 E3 真实屏幕阅读器验证。无法执行已判定必要的 E3 时,标记 `MANUAL_QA_REQUIRED`,不得宣称该 AT 组合已通过。 - -## 5. 响应式断点治理 - -- 优先复用项目既有断点和组件库响应式规则。 -- 新增断点必须有真实布局需求,不得只为绕过单页 CSS 问题而临时散落媒体查询。 -- 允许项目定义超出基础断点阶梯的命名断点。每个断点必须在项目断点登记表中记录名称、数值/范围、用途、权威来源、受影响页面/组件和边界测试。 -- 必须测试断点前、断点处和断点后;具体视口由实际断点决定,不强制所有项目使用同一组设备宽度。 -- 不应简单缩小桌面布局来冒充移动端体验。导航、标题、工具栏、表格、表单和多栏工作区应按任务设计变形。 -- 避免无意的整页横向滚动;只有宽数据集、时间线或画布确有需要时,才在明确容器内横向滚动。 - -## 6. 窄屏数据表格治理 - -窄屏下表格不得仅靠扩大外层容器或隐藏任意列来“通过”检查。应先按数据任务识别列的重要性: - -- **Primary:** 识别记录和完成核心任务所必需的字段;不得无说明地隐藏。 -- **Secondary:** 影响判断但非首屏必须的字段;可移入展开详情、次级面板或按需查看区域。 -- **Tertiary:** 辅助、低频或装饰性字段;可在窄屏降级展示,但必须保留合理获取方式。 -- **Actions:** 行级操作;评估是否收纳为操作菜单,避免动作簇挤占数据列。 - -可按表格特点选择: - -1. 保留核心列并将次要信息移入行详情/展开区; -2. 对键值型或对象摘要型数据改为卡片/记录列表; -3. 对需要横向比较的密集数据保留局部横向滚动,并提供明确的滚动线索; -4. 对重要标识列使用固定列,但必须检查窄屏剩余可视宽度; -5. 将多个行内动作合并为菜单或次级操作区; -6. 对长文本使用合理换行、截断加完整内容通道或详情查看。 - -每个表格必须单独选择策略。保留语义化表格时,应检查表头关联、行列阅读顺序、排序/选择状态和滚动容器;卡片化时,应保证每条记录的字段标签、值和操作关系仍然清楚。 - -### 6.1 数据对账(必须) - -响应式改造后必须进行数据对账,不能只看截图或 `tableaudit` 是否通过: - -- 使用同一组代表性数据对比宽屏和窄屏视图; -- 核对记录数量、关键字段值、字段与记录对应关系、排序/筛选结果; -- 对隐藏或折叠字段确认存在可达的完整查看路径; -- 核对每行操作是否仍可访问且操作对象正确; -- 检查长文本、空值、极值、状态标签和权限差异; -- 对屏幕阅读器检查表头/标签、单元格或卡片阅读顺序,避免重复或丢失信息。该项进入 E3 的条件由风险和平台支持范围决定,不要求每次表格样式调整都启动读屏器。 - -检查脚本可以辅助发现宽度、溢出和结构问题,但不得因测试规则不适配就放宽规则掩盖数据缺失。 - -## 7. 导航状态生命周期 - -桌面折叠偏好与移动端 Drawer 打开状态通常属于不同状态:前者可持久化,后者是临时交互状态。可以共享路由、导航定义和当前选中项,但不要求共用一个状态变量或持久化策略。刷新页面后移动端抽屉通常应关闭。 - -## 8. CSS 层叠与性能优化的边界 - -- NEX 不强制项目使用 CSS Cascade Layers,也不要求将所有自绘样式迁入某个 `@layer`。 -- 对未分层样式、utility class 和媒体查询之间的优先级,应先记录实际层叠模型。只有存在可复现的冲突、回归或维护成本时,才做针对性治理;不得为形式统一进行全量迁移。 -- Bundle 或 CSS Chunk 体积应结合初始加载路径、路由、压缩后大小、缓存和实际性能预算评估。 -- 不得仅为消除构建警告而提高阈值;也不得在没有依赖分析和加载证据时盲目配置分包。 -- 优先识别可延迟加载的路由/模块,并比较优化前后的初始资源和实际行为。 - -## 9. 动效和偏好 - -- 尊重 `prefers-reduced-motion` 或目标平台等效设置。 -- 避免闪烁、持续运动和不必要的空间位移。 -- 动效不应造成焦点丢失、滚动位置跳变或操作延迟。 - -## 10. 建议验收 - -日常 UI/UX 变更按适用性优先执行 E0、E1、E2: -- 交互语义、可访问名称和装饰图标是否被正确隐藏; -- Playwright/axe 等自动化可检测问题(若项目工具链支持); -- 键盘路径、可见焦点、焦点进入/返回; -- 截断内容的辅助技术文本、键盘、Hover 能力检测和触屏渠道; -- 拖拽替代路径; -- 自定义断点登记及边界测试; -- 窄屏表格数据对账; -- 导航状态持久化行为; -- CSS Layer/Bundle 优化的实际证据; -- 减少动态效果设置。 - -E3 仅在 `docs/12-responsive-accessibility-quality.md` 定义的风险条件满足时安排。按项目实际支持的操作系统选择 VoiceOver、NVDA、Orca 等对应工具;不得因为开发机是某个系统,就假定所有用户都使用该系统,也不得要求所有项目覆盖全部读屏器组合。 diff --git a/docs/08-page-patterns.md b/docs/08-page-patterns.md new file mode 100644 index 0000000..fed96e0 --- /dev/null +++ b/docs/08-page-patterns.md @@ -0,0 +1,31 @@ +# 08. Page Patterns + +以下模式用于帮助 Agent 复用成熟的信息组织方式,不要求每个项目都拥有所有页面类型。 + +## 1. 数据列表 + +常见结构:页面标题/说明 → 搜索与筛选 → 工具栏 → 数据列表/表格 → 分页。主要操作突出,次要操作收纳;窄屏重组信息,不盲目压缩列宽。 + +## 2. 数据详情 + +常见结构:对象标题与状态 → 关键属性 → 分组详情 → 关联内容/操作。信息应按用户理解顺序组织,避免把所有字段平铺。 + +## 3. 数据编辑 + +常见结构:标题与上下文 → 分组表单 → 帮助/校验 → 明确保存与取消。复杂流程使用独立页面或步骤结构。 + +## 4. Dashboard + +指标只呈现能支持判断的信息;指标卡、图表和明细应有明确关系。避免用大量同质卡片填满首屏。 + +## 5. 配置页面 + +按主题组织设置,当前分类和保存状态清晰。危险配置应说明影响范围。 + +## 6. 专业工作区 + +编辑器、聊天、画布、流程和媒体工作区可以采用专用布局。需要明确工具区、主工作区、属性区和滚动区职责,不强行套用 CRUD 页面。 + +## 7. 项目适配 + +如果项目已有成熟页面模式,优先复用并映射其设计意图,不为套用上述名称而重写。 diff --git a/docs/09-agent-development-rules.md b/docs/09-agent-development-rules.md new file mode 100644 index 0000000..1f4f583 --- /dev/null +++ b/docs/09-agent-development-rules.md @@ -0,0 +1,53 @@ +# 09. Agent Development Rules + +## 1. 默认工作方式:轻量开发 + +每个日常任务只做必要的理解和修改: +1. 阅读项目根 `AGENTS.md`、`nex.config.yaml` 和项目 UI 规范; +2. 按任务读取相关 NEX 章节; +3. 找到已有页面模式、Token 和共享组件; +4. 在明确范围内实现需求; +5. 在对话中简要说明改动。 + +不得把每个功能任务都转化为全项目审计、分阶段专项或规范升级。 + +## 2. 规范加载 + +- 始终读取:本文件、项目根 Agent 指令、项目配置和项目 UI 规范。 +- 视觉原则:按需读 `01`;Token/主题:读 `02`;布局/响应式:读 `03`;组件:读 `04`;交互:读 `05`;无障碍:读 `06`;体验性能:读 `07`;页面模式:读 `08`;技术栈:新项目/技术初始化时读 `10`。 +- 不得默认读取全部 NEX 文档。 + +## 3. 先复用再实现 + +先查看现有布局、组件、Token、主题和相邻页面。已有实现能满足需求时不重复建设。仅当重复模式稳定且有实际复用价值时才抽象共享组件。 + +## 4. 变更范围 + +- 只修改完成当前任务所需的代码和文档。 +- 不顺手整理无关 CSS、重命名组件或重构其他页面。 +- 不因 NEX 示例而更换颜色、尺寸、断点、组件库或目录结构。 +- 不擅自改业务流程、数据语义和用户操作路径。 +- 涉及全局 Token、应用 Shell、共享组件契约或大范围视觉语言变更时,先用简短说明告知影响范围,再实施。 + +## 5. 技术栈约束 + +- 新项目按 `nex.config.yaml` 的默认 `stack` 创建。 +- 已有项目以真实代码和锁文件为准,保留现有技术栈。 +- 不擅自升级框架、替换 UI 库、迁移 JavaScript/TypeScript 或改变数据库。 + +## 6. 文档与辅助文件约束 + +- 普通任务结果在对话中汇报,不自动创建 Markdown 报告。 +- 不创建阶段编号报告、`reports/` 目录或证据截图目录。 +- 不创建 NEX 专属测试脚本、`scripts/ui/` 或额外检查工具。 +- 不为 NEX 引入测试依赖或测试框架。 +- 不复制整套 NEX 文档到项目 `docs/` 形成重复规范。 +- 长期有效的项目设计决策应更新已有 UI 规范;确需新增文件时,先确认没有合适的现有文档。 + +## 7. 任务说明与完成汇报 + +普通任务不要求先提交长计划。复杂变更用简短文字说明:改哪些区域、复用哪些组件、主要设计选择。完成后用对话汇报:改动摘要、主要文件、重要设计决定和未解决阻塞。不自动生成长报告。 + +## 8. NEX 不定义测试流程 + +是否运行项目测试、使用什么工具、覆盖哪些场景,由用户指令和项目自身工程规则决定。NEX 不要求 Agent 每次运行测试、浏览器自动化、读屏器或全站视觉回归;也不要求 Agent编写测试计划和测试报告。 diff --git a/docs/09-agent-execution-rules.md b/docs/09-agent-execution-rules.md deleted file mode 100644 index c755a5d..0000000 --- a/docs/09-agent-execution-rules.md +++ /dev/null @@ -1,107 +0,0 @@ -# 09. Agent Execution Rules - -## 0. 默认技术栈与自动发现(NEX 0.1.6,沿用 0.1.5 默认栈) - -NEX 配置包含明确的新项目默认技术栈。减少配置填写项,不代表移除技术选型。 - -- 新项目(`project.lifecycle: new`,或 `auto` 且仓库为空/没有实际应用代码):将 `nex.config.yaml` 的 `stack` 作为明确的初始化目标。不要再次要求用户提供技术栈清单,也不要擅自替换默认方案。 -- 已有项目(`project.lifecycle: existing`,或 `auto` 且已经存在应用代码/锁文件/构建配置):以真实项目为准,自动发现并记录技术栈;不得将项目迁移到默认栈。 -- `project.type` 默认 `fullstack`;纯前端/纯后端项目只需覆盖该字段。 -- 用户只需修改不符合意图的 stack 字段;未修改的默认值仍然有效。 - -组件目录、Token 权威来源、主题链路、页面模式、断点、质量命令和辅助技术现状仍由 Agent 从项目中发现。无法确认的已有项目事实记录为 `UNKNOWN`。只有当未知信息会改变产品决策或高风险实施时,才提出必要澄清。 - -## 1. Agent 的角色 - -Agent 不应在每次任务中重新发明项目设计。它应先理解项目已有规范和资产,再在明确范围内完成实现,并提供可验证的结果。 - -## 2. Preflight:实施前检查 - -任何涉及 UI/UX 的任务开始前: - -1. 读取 NEX Core 与项目根 Agent 指令。 -2. 读取 `nex.config.yaml` 和项目级 UI 规范。 -3. 从真实依赖/锁文件/构建配置确认技术栈,不根据过期 README 猜测。 -4. 找到 Token 权威来源和派生链路。 -5. 盘点现有组件和同类页面。 -6. 确认主题、断点、布局尺寸和交互基线。 -7. 找到项目现有质量门禁、视觉截图和回归流程。 -8. 产出差异映射,使用 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED`、`NOT_APPLICABLE`。 - -若用户要求只审计,本阶段之后停止,不得修改代码。 - -## 3. Plan:实施计划 - -跨组件、跨页面、主题、布局或设计 Token 的改动,先列出: -- 目标与非目标; -- 修改文件/组件/页面范围; -- 复用资产与需要新增的内容; -- 对业务交互和布局的影响; -- 风险和回滚方式; -- 质量检查和视觉验收方法。 - -用户已明确授权的阶段可在授权范围内执行;不得将授权自动扩展到后续阶段。 - -## 4. Implement:实现规则 - -- 先复用项目资产,后新增;先修正权威 Token/主题或共享组件,再改页面。 -- 不机械套用参考项目的技术栈、尺寸、断点、品牌色或组件 API。 -- 不强制增加第二套 Token、主题或组件系统。 -- 不擅自修改业务交互、默认值、数据语义和用户操作路径。 -- 对真实缺陷采用最小修复;保留原有交互意图,并补充必要的可访问性行为。 -- 将项目不存在的页面/工作区标记为 `NOT_APPLICABLE`,不引入无关功能。 -- 不对页面进行无差别批量替换;先确认设计值语义和实际消费位置。 - -## 5. Verify:验证规则 - -- 只运行仓库中真实存在的脚本和工具。 -- 不把启动成功当作完整 UI 验收。 -- 视觉检查范围由实际受影响路由、主题、视口和组件决定;复用项目现有回归矩阵。 -- 对无自动化覆盖的项目,明确人工检查范围和无法验证事项。 -- 比较基线时区分既有问题、此次引入问题和环境差异。 -- 对主题、键盘、拖拽替代路径、状态文本、滚动和溢出进行适用性检查。 - -## 6. 证据等级与不可夸大原则 - -按实际执行情况分别记录以下证据,不得跨级推断: - -| 等级 | 证据类型 | 可以证明 | 不能单独证明 | -|---|---|---|---| -| E0 | 源码/配置审阅 | 代码中存在预期结构或属性 | 浏览器实际行为、读屏播报 | -| E1 | 静态/自动化闸 | 已覆盖规则的自动化条件通过 | 未覆盖的语义、键盘和真实 AT 表现 | -| E2 | 浏览器人工键盘/指针验证 | 目标浏览器中的操作路径和焦点行为 | 屏幕阅读器实际播报 | -| E3 | 真实辅助技术验证 | 指定 OS、浏览器、屏幕阅读器组合中的实际结果 | 未测试的其他环境组合 | - -日常开发默认执行 E0–E2。E3 真实屏幕阅读器验证按风险和产品支持平台选择,不是每次修改的必做步骤。对自定义拖拽/排序、复杂复合控件、复合导航、关键数据表格、重要 Live Region 或明确的合同/用户支持要求,应评估是否触发 E3。经评估无需 E3 时记录 `E3_NOT_REQUIRED`;已判定必要但环境不可用时标记 `MANUAL_QA_REQUIRED`。不能因存在 `aria-label`、`aria-keyshortcuts` 或自动化通过而报告真实读屏已通过。 - -E3 屏幕阅读器按目标操作系统选择:macOS 使用 VoiceOver;Windows 使用 NVDA(必要时按用户群增加 JAWS 或 Narrator);Linux 使用 Orca。具体浏览器组合见 `docs/14-accessibility-platform-matrix.md`。不得要求所有项目覆盖全部 OS,也不得把一个 OS 的测试结果外推到其他平台。 - -日常开发、Playwright 自动化和 Computer Use 视觉检查不得自动启动屏幕阅读器。启动/关闭/切换任何系统 AT 前必须获得用户对本次 E3 测试的明确授权;记录测试前状态,不得关闭用户原本已启用的 AT,不得修改系统级偏好。 - -语义质量闸应尽可能检查角色、可访问名称、状态、键盘行为和实际反馈,而不仅是 DOM 标签或属性字符串。自动化无法可靠判断的部分应转人工验收。 - -## 7. Report:交付报告 - -至少汇报: -1. 修改摘要和文件清单; -2. 规范映射状态及偏离理由; -3. 复用/新增/调整的组件; -4. 交互和视觉变化; -5. 实际运行的命令及结果; -6. 受影响的路由、主题、视口和截图; -7. 未解决问题、风险和下一阶段建议; -8. 自动化、键盘和真实 AT 证据等级及未执行项目。 - -## 8. 分阶段控制 - -建议按以下阶段推进,但项目可根据实际问题裁剪: - -- 阶段 0:规范与基线对齐(原则上只读/只改文档)。 -- 阶段 1:高优先级、可复现的视觉/状态缺陷。 -- 阶段 2:键盘和可访问性问题。 -- 阶段 3:层级、Token、主题等基础治理。 -- 阶段 4:共享组件和页面模式改进。 -- 阶段 5:分模块页面迁移。 -- 阶段 6:视觉回归和质量门禁完善。 - -阶段不是强制顺序模板;具体由审计证据和用户授权决定。每阶段结束应形成可验收交付,不默认自动进入下一阶段。 diff --git a/docs/10-adoption-roadmap.md b/docs/10-adoption-roadmap.md deleted file mode 100644 index c0f0a38..0000000 --- a/docs/10-adoption-roadmap.md +++ /dev/null @@ -1,41 +0,0 @@ -# 10. Adoption Roadmap - -## 1. 采用原则 - -NEX 采用应从现有项目能力出发,而不是先建立新组件库或全面重写样式。优先解决规范冲突、可复现问题和重复维护成本。 - -## 2. 推荐阶段 - -| 阶段 | 工作 | 常见产物 | 是否默认改业务代码 | -|---|---|---|---| -| 0. 规范对齐 | 审计真实技术栈、项目规范、Token、组件、布局和质量门禁;建立差异矩阵 | 项目 NEX 适配说明、配置、符合性矩阵 | 否 | -| 1. 明确缺陷 | 修复可复现且范围明确的 P1 问题 | 缺陷修复、回归证据 | 是,限授权范围 | -| 2. 可访问性 | 修复键盘语义、焦点、名称和替代输入路径 | 交互修复、键盘验收 | 是,限授权范围 | -| 3. 基础治理 | Token 映射、主题派生、Z-index、断点等 | Token/层级映射和必要修正 | 视证据和授权而定 | -| 4. 共享模式 | 评估共用组件、复合交互、页面模式 | 组件契约和兼容计划 | 视复用价值而定 | -| 5. 分模块迁移 | 在真实业务模块中渐进采用统一模式 | 页面迁移和回归 | 是,逐模块 | -| 6. 质量门禁 | 补充构建、交互、视觉、可访问性自动化 | CI/脚本/截图基线 | 是,按项目能力 | -| 7. 持续治理 | 定期审查规范漂移和 Agent 遵循情况 | 版本更新、审计报告 | 持续 | - -## 3. 阶段 0 的完成条件 - -- 已读取实际依赖和构建配置。 -- 已找到项目级 UI/UX 规范;没有则明确说明并提出提炼方案。 -- 已定位 Token 权威来源及派生关系。 -- 已盘点现有组件和等价能力。 -- 已记录项目布局、主题、断点和交互基线。 -- 已建立符合性矩阵和冲突清单。 -- 已标记 `NOT_APPLICABLE` 项,避免引入无关页面/组件。 -- 所有计划实施的差异都有范围和验证方式。 - -## 4. 阶段门禁 - -- 不因工作量估算而承诺零风险或确定完成时间。 -- 阶段 0 的发现不能自动授权全量修改。 -- 未确认的品牌、布局、导航或交互决策应保留现状并列为待决项。 -- 每个阶段结束时提供 diff、实际测试结果和视觉证据。 -- 未通过回归的阶段不得默认推进下一个阶段。 - -## 5. 是否需要独立 NEX 组件库 - -只有多个项目已验证需要共享同一实现,且现有项目组件无法以轻量方式复用时,才考虑发布独立包。若项目间使用不同 UI 库,可共享设计原则、Token 语义和组件行为契约,而不必强行共享 React 实现。 diff --git a/docs/10-project-stack-defaults.md b/docs/10-project-stack-defaults.md new file mode 100644 index 0000000..8802cc3 --- /dev/null +++ b/docs/10-project-stack-defaults.md @@ -0,0 +1,43 @@ +# 10. Project Stack Defaults + +## 1. 原则 + +新项目需要明确的默认技术选型,Agent 不应自行猜测。已有项目则必须保留真实技术栈,不得为了符合默认值而迁移。 + +## 2. 新项目默认全栈方案 + +| 层次 | 默认技术 | +|---|---| +| 前端框架 | React | +| 前端语言 | TypeScript | +| 构建工具 | Vite | +| 包管理器 | npm | +| UI 组件库 | Ant Design | +| 样式 | Tailwind CSS v4 + CSS Variables | +| 状态管理 | Zustand | +| 路由 | React Router | +| HTTP | Axios | +| 后端语言 | Python | +| 后端框架 | FastAPI | +| 校验 | Pydantic | +| ORM | SQLAlchemy | +| 数据库迁移 | Alembic | +| 开发数据库 | SQLite | +| 生产数据库 | PostgreSQL | +| API | REST + OpenAPI | +| 本地静态资源 | `./data` | + +具体依赖版本按初始化时的兼容稳定版本选择,并保持 lockfile。此处定义的是新项目起点,不是所有项目的强制技术栈。 + +## 3. 项目类型与生命周期 + +- `project.type: fullstack`:前后端均适用; +- `frontend-only`:仅初始化前端; +- `backend-only`:仅初始化后端; +- `project.lifecycle: auto`:空项目按 new,已有应用代码按 existing; +- `new`:默认 stack 是初始化目标; +- `existing`:以代码、依赖和锁文件为准。 + +## 4. 覆盖 + +只修改与项目意图不同的字段。不要要求用户重复填写整套技术栈。若明确需求与默认值冲突,说明冲突并提出最小调整,不得静默替换技术。 diff --git a/docs/11-project-adoption.md b/docs/11-project-adoption.md new file mode 100644 index 0000000..33ab266 --- /dev/null +++ b/docs/11-project-adoption.md @@ -0,0 +1,31 @@ +# 11. Project Adoption + +## 1. 新项目 + +1. 读取 `nex.config.yaml`; +2. 按默认 stack 和 `project.type` 初始化技术骨架; +3. 建立一份项目级 UI 规范,明确品牌方向、主题、布局/导航、组件使用约定、关键页面模式和特殊交互; +4. 先复用 NEX 的通用原则,不要为项目创建重复的 NEX 组件包; +5. 普通开发直接按 Agent 轻量流程推进。 + +## 2. 已有项目 + +1. 识别当前技术栈、项目 UI 规范、主题/Token 来源和共享组件; +2. 保留已验证成熟的设计和交互; +3. 将项目差异视为项目适配,不机械迁移到 NEX 示例; +4. 仅记录会影响后续开发的关键差异,不做大规模审计报告; +5. 用户明确提出全局规范整理时,才制定单独计划。 + +## 3. 符合性映射(可选) + +如果需要记录项目与 NEX 的关系,可在一份现有 UI 规范中加入简短映射: +- ADOPTED:直接采用 NEX 原则; +- ADAPTED:采用项目成熟实现; +- DEFERRED:暂不处理; +- NOT_APPLICABLE:项目不存在此类场景。 + +不要求每个新项目生成完整矩阵或长期维护逐条审计台账。 + +## 4. 冲突 + +NEX 原则与项目视觉选择冲突时,优先保留合理的项目设计;NEX 对一致性、组件复用、语义清晰和可用性的约束仍然适用。涉及用户目标不明确的产品决策时,提出一个关键问题,不要自行扩展范围。 diff --git a/docs/11-project-onboarding.md b/docs/11-project-onboarding.md deleted file mode 100644 index 505af7a..0000000 --- a/docs/11-project-onboarding.md +++ /dev/null @@ -1,81 +0,0 @@ -# 11. Project Onboarding & Conformance Mapping - -## 1. 项目类型与技术栈确认 - -NEX 0.1.5 采用“新项目明确默认技术栈、已有项目自动识别”的双模式,避免 0.1.4 将自动发现错误地应用于新项目技术选型。 - -### 新项目 - -默认 `project.type: fullstack`,采用 `config/project-profile.example.yaml` 中的默认栈: - -- 前端:React、TypeScript、Vite、npm、Ant Design、Tailwind CSS v4、Zustand、React Router、Axios; -- 后端:Python、FastAPI、Pydantic、SQLAlchemy、Alembic; -- 数据库:开发 SQLite、生产 PostgreSQL; -- API:REST + OpenAPI; -- 本地资源目录:`./data`; -- 工具:ESLint、Prettier、Vitest、Playwright、Pytest。 - -新项目 Agent 必须遵循这些明确选型。若用户只需纯前端/纯后端,只修改 `project.type`。若要更换某项技术,只修改 `stack` 的对应字段。 - -### 已有项目 - -以真实代码、锁文件、构建配置、CI 和运行结果为证据,自动识别: - -- 前后端框架、语言、依赖版本、构建工具和 UI/样式方案; -- 项目 UI/UX 规范与设计决策文档; -- Token 权威来源、主题链路、共享组件目录和布局模式; -- 路由、断点、响应式规则、质量命令、视觉基线和 CI; -- 适用的辅助技术验证范围及尚未执行的人工测试。 - -已有项目的默认技术栈只用于对比,不是迁移目标。不得因默认栈不同而升级框架、替换 UI 库或迁移数据库。需要迁移时必须取得单独授权。 - -`project.lifecycle: auto` 根据仓库情况自动识别:空仓库按新项目处理;已存在应用代码、锁文件或构建配置按已有项目处理。仓库状态模糊且会影响技术决策时,先进行只读检查,再提出一个具体问题。 - -## 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/docs/12-responsive-accessibility-quality.md b/docs/12-responsive-accessibility-quality.md deleted file mode 100644 index 31d3338..0000000 --- a/docs/12-responsive-accessibility-quality.md +++ /dev/null @@ -1,192 +0,0 @@ -# 12. Responsive, Accessibility & Quality Evidence Governance - -## 1. 本文目的 - -本文将 NEX 的响应式、可访问性和质量闸要求转化为可登记、可测试、可审计的项目规则。它不指定统一像素断点、屏幕阅读器、CSS 技术或 Bundle 阈值;项目应依据用户群、支持平台和实际实现确定具体值。 - -## 2. 响应式断点注册机制 - -### 2.1 基本原则 - -- 先复用项目现有断点体系。 -- 仅当真实布局约束无法通过现有断点合理表达时,才新增命名断点。 -- 命名断点应表达布局状态或设计意图,而不只是设备名称(例如 `compact-workspace` 优于 `iphone-width`)。 -- 断点定义必须集中在项目认可的权威位置;组件级例外应登记,不得散落为不可追踪的媒体查询。 -- 不为减少断点数量而接受内容遮挡、字段丢失、操作不可达或明显不合理的视觉回退。 - -### 2.2 登记字段 - -每个断点记录: - -1. 名称; -2. CSS 条件和值(min-width/max-width/范围/容器查询); -3. 解决的问题与设计理由; -4. 影响的 Shell、页面和组件; -5. 权威定义文件/Token/主题位置; -6. 与相邻断点的布局差异; -7. 断点前、断点处、断点后的测试宽度; -8. 证据、批准来源和复审条件。 - -### 2.3 边界测试 - -若断点条件为 `min-width: X`,至少覆盖 X 前一个有效 CSS 像素、X 和 X 后一个有效 CSS 像素;若为区间或 max-width,也应覆盖两侧边界。还应覆盖实际用户常见宽度、浏览器缩放和长内容/长标签等压力数据。 - -不要只测试 390/768/1024/1440 等设备预设宽度而遗漏项目自己的临界区间。 - -## 3. 窄屏表格与数据完整性 - -### 3.1 列优先级 - -每张表格应先把列分为 Primary、Secondary、Tertiary 和 Actions。优先级依据用户任务和数据决策价值,不得由实现方便程度决定。 - -### 3.2 响应策略 - -可选择一种或组合多种策略: -- 保留关键列,次要字段进入行详情/展开区; -- 对对象摘要或键值数据使用卡片/记录视图; -- 对横向比较数据使用容器内滚动; -- 对稳定识别字段使用固定列; -- 将密集行内动作收纳为操作菜单; -- 对长文本使用换行、截断+完整内容或详情入口。 - -不能把“增加容器宽度”作为默认解决方案,也不能无说明地隐藏核心数据。 - -### 3.3 数据对账方法 - -在相同测试数据集下比较宽屏与窄屏: -- 记录总数一致; -- 关键字段值和字段归属一致; -- 排序、筛选和分页语义一致; -- 所有隐藏/折叠字段可通过明确路径查看; -- 行操作仍作用于正确记录; -- 空值、长文本、极值、状态、权限和异常数据有代表性覆盖。 - -对卡片化视图,核对每条记录显示的标签和值;对表格视图,核对表头关联、列顺序、滚动和操作区域。 - -### 3.4 屏幕阅读器阅读顺序 - -- 表格保留适当的行/列标题关联,不用纯视觉布局模拟数据表格。 -- 响应式切换为卡片后,应为每个值提供清晰字段标签和逻辑阅读顺序。 -- 避免对每个单元格重复朗读冗长上下文,必要时调整可访问名称或结构。 -- 排序、选择、展开详情和操作菜单状态应可感知。 -- 横向滚动容器应有合理名称/提示,并能通过目标输入方式访问。 - -## 4. 可访问名称和图标 - -### 4.1 装饰图标 - -当图标仅用于视觉装饰,或与相邻可见文本重复表达同一含义时,应从辅助技术名称计算中排除。使用项目适当的方式(如 `aria-hidden="true"`),并确认图标字体/glyph 内部名称不会被读屏软件当成内容。 - -### 4.2 图标按钮 - -图标按钮必须有清楚的可访问名称,例如“导入脚本”“导出”“关闭面板”。名称必须描述动作或对象,不能直接暴露 `upload`、`down`、`trash-2` 等内部图标命名。 - -### 4.3 截断与完整名称 - -重要文本被视觉截断时,保留完整可访问文本。Tooltip 应按设备能力提供:在支持 Hover 的精确指针设备启用 Hover;键盘用户使用 Focus;触屏用户通过点击或详情方式获得全文。若元素已经有完整可访问名称,不要造成重复朗读。 - -## 5. 导航状态模型 - -按生命周期管理导航状态: -- 共享状态:路由、导航配置、选中项、权限。 -- 可持久用户偏好:例如桌面侧栏折叠状态。 -- 临时 UI 状态:例如移动端 Drawer 开关,通常不持久化。 - -不要求将这些状态合并为同一个变量或存储机制。状态应按平台预期初始化、关闭和恢复。 - -## 6. CSS Cascade Layers 与样式治理 - -NEX 不要求所有项目使用 CSS Cascade Layers。若项目同时使用 utility classes、普通 CSS、CSS Modules、组件库样式或 `@layer`,先绘制实际优先级关系并识别是否存在可复现冲突。 - -只有在发现覆盖失效、断点规则被压制、主题回归或长期维护问题时,才按最小范围治理。大规模迁移必须有影响清单、回归矩阵和回滚方案。禁止仅为了让所有样式“形式上都在 layer 内”进行全量重写。 - -## 7. Bundle 与 CSS 性能治理 - -性能判断应结合项目预算和用户路径,不设跨项目通用的 chunk 字节阈值。分析至少包括: -- 初始入口和路由依赖关系; -- 大型依赖和重复打包; -- 原始、Gzip/Brotli 体积(若工具支持); -- 首屏是否加载非首屏模块; -- 路由级懒加载是否有真实收益; -- CSS 是否阻塞关键渲染或包含大量非首屏样式; -- 优化前后加载行为和缓存影响。 - -不得只为消除警告提高阈值,也不得没有分析就手工拆成大量 chunk。每项优化需记录数据和回归结果。 - -## 8. 语义与行为质量闸 - -质量探针不应只检查 DOM 标签或属性字符串。适用时至少检查: -- role / native semantics; -- accessible name; -- state(expanded、selected、checked、disabled、current 等); -- keyboard action; -- focus visibility/order/return; -- interaction result and status feedback; -- responsive visibility and access path。 - -静态探针可以验证源代码约束,但不能单独证明浏览器可访问树或实际读屏输出。优先采用浏览器可访问性树、自动化行为、键盘人工检查和真实 AT 记录组合验证。 - -## 9. 质量证据等级与日常默认流程 - -NEX 将无障碍验证分为四个证据等级,但**四个等级不代表每次开发都必须逐级执行**: - -| 等级 | 名称 | 最低证据 | 可报告结论 | -|---|---|---|---| -| E0 | Source Reviewed | 源码、配置、HTML/ARIA 和组件实现审阅 | 实现中存在预期结构/属性;不能证明运行时表现 | -| E1 | Automated Checked | 实际运行的 Playwright、axe-core、单元/集成测试或语义探针结果 | 已覆盖规则的自动化检查通过;不能证明真实读屏体验 | -| E2 | Browser Interaction Verified | 指定浏览器中的键盘、指针/触屏实际操作记录 | 指定浏览器中的交互路径、焦点和反馈可用 | -| E3 | Assistive Technology Verified | 指定 OS + 浏览器 + 屏幕阅读器的真实操作与实际播报记录 | 仅该测试组合和测试范围中的 AT 体验通过 | - -**日常开发默认执行 E0–E2。** E3 是按风险和产品支持平台选择的专项测试,不要求每次代码修改、每个页面或每个项目都启动屏幕阅读器。浏览器自动化可以验证可访问树、名称/角色/状态、键盘脚本和 Live Region DOM 更新,但不能完整证明真实 AT 的播报、导航模式或快捷键处理。真实 AT 测试也不能替代 E0–E2 的常规回归。 - -E3 状态应明确区分: -- `E3_NOT_REQUIRED`:完成风险评估后,当前功能/改动无需真实读屏验证,并记录理由; -- `MANUAL_QA_REQUIRED`:E3 已被判定必要,但当前环境、权限或设备不可用; -- `E3_PASS` / `E3_FAIL`:只在记录的真实环境中执行后填写。 - -不得因没有运行 E3 就将所有普通页面判为未验收;也不得对已判定 E3 必要的高风险交互,仅凭 ARIA 属性或自动化通过宣称无障碍验收完整。 - -## 10. E3 风险触发条件 - -优先评估以下场景是否需要 E3: -- 自定义拖拽、排序、画布、节点连接或复杂复合控件; -- 自定义 Tabs、菜单、复合导航、Tree/Grid 等键盘模型; -- 关键业务流程中使用复杂 ARIA 状态或自定义控件; -- 依赖 Live Region 完成重要异步反馈、任务进度或排序结果通知; -- 复杂数据表格、响应式表格转卡片后存在阅读顺序/关联风险; -- 已发现浏览器可访问树与实际播报可能不一致的问题; -- 项目明确声明支持特定辅助技术,或合同/法规/客户验收要求真实 AT 证据。 - -普通静态内容、原生 HTML 控件、低风险样式调整和没有改变可访问交互行为的常规代码修改,通常通过 E0–E2 即可。风险评估应考虑功能复杂度、用户影响、变更范围、已有缺陷和目标用户群,不能仅由 Agent 为减少工作量而跳过。 - -## 11. 跨操作系统屏幕阅读器选择 - -E3 应按产品真实支持范围选择操作系统、浏览器和屏幕阅读器组合,不得把 VoiceOver 当作唯一方案,也不得要求所有项目覆盖全部平台: - -- **macOS:** VoiceOver;通常优先 VoiceOver + Safari,项目主要支持 Chrome 时按需增加 Chrome。 -- **Windows:** NVDA;按产品支持范围选择 Firefox 或 Chrome/Edge。企业用户或合同有要求时可增加 JAWS;Narrator 可作为系统内置抽查工具。 -- **Linux:** Orca;优先选择项目实际支持的 GNOME/AT-SPI + Firefox 组合;若 Chromium 是正式目标浏览器,再增加对应测试。 - -这些是测试选择建议,不表示不同 OS/浏览器/AT 组合等价。测试人员必须记录实际 OS/发行版/桌面环境、浏览器及 AT 版本。一次测试结果只对该组合有效。 - -如果 Agent 当前运行在 Windows 或 Linux,不应尝试启动 macOS VoiceOver;应根据目标平台选择可用的 NVDA 或 Orca。若环境没有相应 AT,完成可执行的 E0–E2,并将必要的 E3 标记为 `MANUAL_QA_REQUIRED`,由目标平台的测试机/人工 QA 完成。平台矩阵详见 `docs/14-accessibility-platform-matrix.md`。 - -## 12. 屏幕阅读器启停与用户授权 - -- 日常 UI 验收、Playwright 测试和页面巡检不得自动启动屏幕阅读器。 -- 启动、关闭或切换 VoiceOver、NVDA、Orca 等系统辅助技术前,必须获得用户对本次 E3 测试的明确授权;一般的开发或 Computer Use 授权不自动包含这项授权。 -- 测试前记录 AT 初始状态。若用户在测试前已启用屏幕阅读器,Agent 不得擅自关闭。 -- 只可在用户授权范围内清理本次由 Agent 启动的 AT 状态;不得更改用户系统级偏好、自动启动设置、语音或快捷键。 -- 如果无法确认当前状态或安全恢复,停止自动启停,改由用户/测试人员手动操作。 - -## 13. 报告要求 - -每次相关改造至少记录: -- 规则/组件/页面与风险评估理由; -- 目标平台、浏览器和视口; -- 测试数据集与数据对账结果(如适用); -- E0–E3 实际执行等级; -- 自动化命令和结果; -- E3 的 OS/发行版/桌面环境、浏览器、AT 名称及版本; -- 实际焦点路径、快捷键处理、真实播报内容和 Live Region 时序(如适用); -- 未执行项、环境限制、风险和后续复核条件。 diff --git a/docs/13-project-stack-defaults.md b/docs/13-project-stack-defaults.md deleted file mode 100644 index ae5d9c9..0000000 --- a/docs/13-project-stack-defaults.md +++ /dev/null @@ -1,116 +0,0 @@ -# 13. Project Stack Defaults - -## 1. 目的 - -NEX 0.1.5 修正 0.1.4 的一个问题:降低配置填写量,不等于移除新项目的技术选型。 - -新项目需要有明确、可执行的技术栈默认值。Agent 不应在空项目中自行猜测前后端框架、数据库或 UI 组件库;也不应要求用户从零填写整张技术清单。 - -因此,NEX 采用两种不同策略: - -- **新项目(New)**:`nex.config.yaml` 中的默认技术栈就是默认实施目标。只有用户明确覆盖时才使用其他选型。 -- **已有项目(Existing)**:真实代码、锁文件和构建配置代表当前技术事实。默认技术栈仅供参考,不得据此擅自迁移或替换现有技术。 - -## 2. 默认全栈方案 - -`config/project-profile.example.yaml` 提供以下默认方案: - -| 层次 | 默认技术 | 用途 | -|---|---|---| -| 前端框架 | React | Web UI | -| 前端语言 | TypeScript | 类型安全 | -| 构建工具 | Vite | 开发与构建 | -| 包管理器 | npm | 依赖管理 | -| UI 组件库 | Ant Design | 企业级基础组件 | -| 样式方案 | Tailwind CSS v4 + CSS Variables | 布局工具类与语义化设计变量 | -| 状态管理 | Zustand | 跨组件状态 | -| 路由 | React Router | 前端路由 | -| HTTP 客户端 | Axios | API 通信 | -| 后端语言 | Python | 服务端开发 | -| 后端框架 | FastAPI | REST API | -| 数据校验 | Pydantic | 请求/响应模型 | -| ORM | SQLAlchemy | 数据访问 | -| 数据库迁移 | Alembic | Schema 版本管理 | -| 开发数据库 | SQLite | 本地开发与轻量部署 | -| 生产数据库 | PostgreSQL | 生产持久化 | -| API 风格 | REST + OpenAPI | 接口契约 | -| 本地静态资源 | `./data` | 媒体及文件资源 | -| 前端质量工具 | ESLint、Prettier、Vitest、Playwright | 代码、格式、单测和端到端测试 | -| 后端测试 | Pytest | 后端测试 | - -具体依赖版本采用创建时兼容的稳定版本,并必须提交 lockfile。不得使用无版本约束的通配符依赖;具体版本选择应考虑所选框架、组件库和插件之间的兼容性。 - -## 3. 项目类型 - -默认 `project.type: fullstack`。 - -如项目不是全栈,只需修改一个字段: - -```yaml -project: - type: frontend-only -``` - -或: - -```yaml -project: - type: backend-only -``` - -不适用的部分不应初始化。例如 `frontend-only` 不应创建无用的 FastAPI 服务;`backend-only` 不应创建 React 前端。 - -## 4. 生命周期自动识别 - -默认 `project.lifecycle: auto`: - -- 空仓库或尚无实际应用代码:按 `new` 处理,采用默认技术栈。 -- 已存在可识别的应用代码、锁文件或构建配置:按 `existing` 处理,以当前代码为准。 -- 仓库状态模糊且会影响是否创建/迁移技术栈时,先进行只读检查;必要时提出一个明确问题,不得擅自覆盖。 - -也可以手动设置 `new` 或 `existing`。 - -## 5. 覆盖默认技术栈 - -用户不需要填写整套配置。只需修改不符合当前项目意图的字段。例如希望使用 PostgreSQL 作为开发数据库: - -```yaml -stack: - database: - development: PostgreSQL - production: PostgreSQL -``` - -例如希望采用其他 UI 方案: - -```yaml -stack: - frontend: - ui_library: None - styling: Tailwind CSS v4 + CSS Variables -``` - -实际修改时应保留完整 YAML 层级,并仅覆盖有意变更的值。Agent 不得将未修改字段理解为“未指定”。 - -## 6. 新项目与已有项目的执行规则 - -### New - -- 将 `stack` 视为技术选型约束,不要自行替换。 -- 根据 `project.type` 初始化对应层次。 -- 在创建代码前确认依赖兼容性、目录结构和本地运行方式。 -- 可以提出必要的安全/部署问题,但不要重复询问配置里已经明确给出的技术选型。 -- 如发现某项默认方案与明确需求冲突,先说明冲突并提出最小调整,不得静默改变栈。 - -### Existing - -- 以锁文件、依赖清单、源码、构建配置和运行结果确认当前技术栈。 -- 将自动发现结果写入审计报告,并与默认 profile 对比。 -- 不因默认方案与现状不同而升级、替换或迁移。 -- 只有用户明确授权技术迁移时,才制定单独迁移方案。 - -## 7. NEX 不统一项目技术栈的边界 - -以上是新项目的默认起步方案,不是对所有项目的强制技术栈。 - -用户可以通过少量字段覆盖默认值;已有项目可以完整保留自己的技术选型。NEX Core 仍然约束设计质量、组件复用、Token 单一来源、交互一致性、可访问性、响应式和质量证据,而不要求所有项目都采用同一套框架。 diff --git a/docs/14-accessibility-platform-matrix.md b/docs/14-accessibility-platform-matrix.md deleted file mode 100644 index 6eff156..0000000 --- a/docs/14-accessibility-platform-matrix.md +++ /dev/null @@ -1,75 +0,0 @@ -# 14. Cross-platform Assistive Technology Test Matrix - -## 1. 目的 - -本文件定义 NEX 项目如何选择真实辅助技术(AT)验证环境。**VoiceOver 不是跨平台唯一方案,也不是日常开发的默认工具。** Agent 必须根据产品声明支持的操作系统、浏览器和用户群选择匹配的测试组合。 - -## 2. 平台建议矩阵 - -| 目标平台 | 优先考虑的屏幕阅读器 | 建议浏览器组合 | 适用说明 | -|---|---|---|---| -| macOS | VoiceOver(系统内置) | Safari;如产品主要支持 Chrome,也增加 Chrome 组合 | 验证 macOS 原生辅助技术与 Web 内容的实际交互 | -| Windows | NVDA(免费) | Firefox 或 Chrome/Edge,按产品支持范围选择 | 可按企业客户/用户群补充 JAWS;可用 Narrator 做系统内置辅助抽查 | -| Linux | Orca(GNOME 常见读屏器) | 优先 Firefox;若产品明确支持 Chromium,再补充该组合 | 需记录发行版、桌面环境、AT-SPI 支持和浏览器版本;不同桌面/浏览器组合能力可能不同 | - -这些是建议起点,不是宣称所有版本和组合都等价或完全兼容。测试报告必须记录真实 OS、发行版/桌面环境、浏览器、屏幕阅读器及版本。不得把 macOS VoiceOver 结果外推为 Windows NVDA 或 Linux Orca 结果。 - -## 3. 如何选择需要测试的平台 - -1. 先读取产品支持平台、部署环境、用户群和客户合同/无障碍要求。 -2. 只对产品实际支持或明确承诺的平台建立 AT 测试矩阵;不因 NEX 本身而强制测试所有桌面操作系统。 -3. 普通页面、静态内容和常规原生控件优先通过 E0–E2 日常验证;不要求每个提交都执行 E3。 -4. 自定义复合控件、拖拽/排序、复杂 Tabs/菜单/导航、动态 Live Region、复杂数据表格、关键流程或已有 AT 缺陷,按风险触发 E3。 -5. 对高风险功能,选择实际用户占比最高或合同明确要求的代表性平台/AT;若产品承诺跨平台且交互实现存在平台差异,应增加对应组合。 -6. 若受法规、招标、客户验收或无障碍声明约束,按明确要求增加测试矩阵,不以本文件的建议组合替代合同要求。 - -## 4. 平台不可用时的处理 - -- Agent 不得在 Windows/Linux 上尝试启动 macOS VoiceOver;不得在 macOS 上假定已安装 NVDA 或 Orca。 -- 若当前工作环境没有目标操作系统、浏览器或屏幕阅读器,先完成可执行的 E0–E2,不得伪造 E3 结果。 -- E3 被风险判断为必要但环境不可用时,状态标记为 `MANUAL_QA_REQUIRED`,同时记录所需组合、未验证行为、风险和建议测试责任人/设备。 -- 若经风险评估 E3 不适用,应记录 `E3_NOT_REQUIRED` 及理由,不需要为了形式完整而开启屏幕阅读器。 -- 可在专用测试机、用户提供的设备、人工 QA 或经授权的远程环境完成 E3;不得默认将不同 OS 的读屏器行为视为一致。 - -## 5. 屏幕阅读器启停与用户环境保护 - -启动屏幕阅读器可能产生语音输出、改变键盘交互并影响用户当前工作环境,因此: - -1. 日常开发、页面巡检和普通浏览器自动化不得自动启动屏幕阅读器。 -2. 启动、关闭或切换系统屏幕阅读器前,必须有用户对本次 E3 测试的明确授权;一般开发授权不自动包含这项授权。 -3. 测试前记录屏幕阅读器初始状态。若它在测试开始前已由用户开启,Agent 不得擅自关闭。 -4. 只有 Agent 在本次已获授权测试中亲自启动的实例,才可在用户授权范围内按约定恢复;不得更改用户的全局辅助功能偏好、语音、快捷键或自动启动设置。 -5. 无法安全确认启停状态时,停止自动启停操作,改为由用户/测试人员手动控制并记录。 - -## 6. 各层测试职责 - -| 级别 | 默认工具/方式 | 验证范围 | 是否常规 | -|---|---|---|---| -| E0 | 源码、HTML/ARIA、组件 API 审阅 | 语义、名称、状态、结构和实现意图 | 是 | -| E1 | Playwright、axe-core、测试框架 | 自动可检测规则、可访问名称/角色断言、键盘脚本、Live Region DOM 更新等 | 是,按项目支持 | -| E2 | 浏览器 + 键盘/指针/触屏实际操作 | 真实焦点顺序、可操作性、可见焦点、交互结果与反馈 | 是,按影响面 | -| E3 | VoiceOver / NVDA / Orca 等实际 AT | 真实朗读、AT 导航模式、快捷键冲突、Live Region 播报时序和实际用户体验 | 否,按风险触发 | - -浏览器自动化可以验证可访问树、DOM 状态和部分交互,但不能完整模拟或证明屏幕阅读器实际播报、阅读模式、快捷键分发和用户听到的内容。反过来,E3 也不取代 E0–E2 的高频回归。 - -## 7. E3 记录的最低要求 - -真实 AT 测试记录必须包含: -- 风险理由及被测用户任务; -- OS/发行版/桌面环境、浏览器和 AT 的名称及版本; -- 输入方式、键盘布局、视口和缩放; -- 预期 role/name/state 与预期播报; -- 实际焦点路径和实际听到的播报(关键内容尽量逐字记录); -- 快捷键是否冲突、Live Region 是否播报及播报时序; -- 失败步骤、复现方法、证据和未覆盖的其他组合。 - -一次 E3 通过只对记录的 OS + 浏览器 + AT 组合和测试范围有效,不自动代表其他平台通过。 - -## 8. 参考资料 - -- W3C — WCAG 2.2: https://www.w3.org/TR/WCAG22/ -- W3C — WCAG Overview: https://www.w3.org/WAI/standards-guidelines/wcag/ -- Playwright — Accessibility testing: https://playwright.dev/docs/accessibility-testing -- Apple — VoiceOver User Guide: https://support.apple.com/guide/voiceover/welcome/mac -- NV Access — NVDA download and supported Windows versions: https://www.nvaccess.org/download/ -- GNOME — Orca Screen Reader: https://gnome.pages.gitlab.gnome.org/orca/help/introduction.html diff --git a/templates/assistive-technology-test-record.md b/templates/assistive-technology-test-record.md deleted file mode 100644 index b74cf4d..0000000 --- a/templates/assistive-technology-test-record.md +++ /dev/null @@ -1,52 +0,0 @@ -# Assistive Technology Test Record - -## 1. Test Context -- Project / version: -- Feature / component: -- User task: -- E3 risk trigger / reason: -- Test date: -- Tester: -- User authorization for starting/stopping AT (reference or explicit instruction): - -## 2. Environment -- OS / distribution / desktop environment and version: -- Browser and version: -- Screen reader / assistive technology and version: -- Input method (keyboard / touch / switch / voice): -- Viewport / zoom: -- AT state before test (already enabled / disabled / unknown): -- AT state after test (unchanged / agent-started instance stopped with authorization / manual cleanup): - -## 3. Expected Behavior -- Accessible role: -- Accessible name: -- State and state changes: -- Keyboard commands: -- Focus entry / order / return: -- Expected announcement: -- Cancel / recovery behavior: - -## 4. Test Results -| Step | User action | Expected result / announcement | Actual result / announcement | Pass | Notes | -|---|---|---|---|---|---| -| | | | | | | - -Record actual speech/announcement for critical interactions; do not infer it from DOM or ARIA values. - -## 5. Evidence Level -- [ ] E0 Source Reviewed -- [ ] E1 Automated Checked -- [ ] E2 Browser Interaction Verified -- [ ] E3 Assistive Technology Verified -- [ ] E3_NOT_REQUIRED (include risk rationale) -- [ ] MANUAL_QA_REQUIRED (include target platform and blocker) - -## 6. Issues / Follow-up -| Issue | Severity | Workaround | Owner | Status | -|---|---|---|---|---| -| | | | | | - -**Final status:** PASS / PARTIAL / FAIL / E3_NOT_REQUIRED / MANUAL_QA_REQUIRED / NOT_TESTED - -Do not mark E3 or final AT pass unless the named OS + browser + AT environment was actually used and observed. One platform's result does not prove another platform's result. diff --git a/templates/new-project-audit-prompt.md b/templates/new-project-audit-prompt.md deleted file mode 100644 index 089edcc..0000000 --- a/templates/new-project-audit-prompt.md +++ /dev/null @@ -1,102 +0,0 @@ -# NEX 0.1.6 项目接入:只读审计与技术栈确认 - -本项目采用 NEX Design System 0.1.6。请先阅读: - -- `standards/nex-design-system/AGENTS.md` -- `standards/nex-design-system/README.md` -- `standards/nex-design-system/docs/00-governance-and-adaptation.md` -- `standards/nex-design-system/docs/02-design-principles.md` -- `standards/nex-design-system/docs/03-design-tokens.md` -- `standards/nex-design-system/docs/04-layout-system.md` -- `standards/nex-design-system/docs/05-component-system.md` -- `standards/nex-design-system/docs/06-interaction-system.md` -- `standards/nex-design-system/docs/08-accessibility-responsive.md` -- `standards/nex-design-system/docs/09-agent-execution-rules.md` -- `standards/nex-design-system/docs/11-project-onboarding.md` -- `standards/nex-design-system/docs/12-responsive-accessibility-quality.md` -- `standards/nex-design-system/docs/14-accessibility-platform-matrix.md` -- `standards/nex-design-system/docs/13-project-stack-defaults.md` -- 项目根目录 `nex.config.yaml` -- 项目已有 UI/UX 规范(如存在) - -## 一、先判断项目生命周期 - -读取 `nex.config.yaml` 中的 `project.lifecycle`: - -- `new`:明确的新项目,`stack` 是技术选型目标;按默认值制定初始化计划。 -- `existing`:已有项目,以真实代码、锁文件、构建配置和运行结果为技术事实;不得按默认栈迁移。 -- `auto`:若仓库为空或无实际应用代码,按 `new`;若已有应用代码、锁文件或构建配置,按 `existing`。证据不充分时先完成只读检查,只有会影响技术决策时才提出一个具体问题。 - -## 二、新项目的默认技术栈 - -对于 `new` 项目,必须将 `nex.config.yaml` 中的 `stack` 视为已确定的技术选型,不要将它当成待自动发现的未知信息,也不要再次要求用户填写技术栈。 - -默认全栈方案: -- 前端:React + TypeScript + Vite + npm + Ant Design + Tailwind CSS v4 + CSS Variables + Zustand + React Router + Axios。 -- 后端:Python + FastAPI + Pydantic + SQLAlchemy + Alembic。 -- 数据库:开发 SQLite,生产 PostgreSQL。 -- API:REST + OpenAPI。 -- 本地静态资源:`./data`。 -- 工具:ESLint、Prettier、Vitest、Playwright、Pytest。 - -若 `project.type` 为 `frontend-only` 或 `backend-only`,只规划对应部分,不要生成无用服务。 - -具体依赖版本使用创建时兼容的稳定版本并提交 lockfile。若依赖之间存在兼容性冲突,先列出证据和最小调整建议,不得静默替换技术选型。 - -## 三、已有项目的技术栈识别 - -对于 `existing` 项目,从 `package.json`、锁文件、Python 依赖清单、源码、构建配置、容器配置和 CI 确认真实技术栈。README 不能作为唯一证据。 - -将实际技术栈与默认 profile 对比,但默认 profile 不是迁移目标。不得擅自升级框架、替换 UI 库、改变 JavaScript/TypeScript 方案或迁移数据库。 - -## 四、审计内容 - -1. 确认项目生命周期、项目类型和技术栈来源。 -2. 找出项目级 UI/UX 规范、设计决策和权威性。 -3. 追踪 Token 单一事实来源、主题适配器和派生消费者。 -4. 盘点基础、表单、布局、复合和业务共享组件,识别等价能力。 -5. 识别 Shell、导航模型、持久偏好状态和临时 UI 状态。 -6. 盘点响应式断点及其权威来源;标记未登记的局部断点。 -7. 对数据表格评估窄屏策略、列优先级、行内动作和数据完整性。 -8. 检查交互语义、可访问名称、装饰图标、键盘、焦点、截断文本和拖拽替代路径。 -9. 默认以 E0 源码审阅、E1 自动化、E2 浏览器键盘/指针交互完成日常无障碍验收;按风险判断 E3 是否需要,不得将 E3 设为每次开发必做。 -10. 识别项目实际支持的操作系统、浏览器和用户群;仅对支持范围内的高风险交互选择匹配的 AT:macOS VoiceOver、Windows NVDA(必要时 JAWS/Narrator)、Linux Orca。 -11. 不得自动启动或关闭屏幕阅读器。若审计阶段没有真实启动 AT 的授权,不执行 E3;记录 `E3_NOT_REQUIRED` 或 `MANUAL_QA_REQUIRED`,不得宣称真实读屏通过。 -12. 盘点 CSS Layer/级联模型、Bundle/CSS 体积和现有性能预算;不得只凭警告数字判定缺陷。 -13. 找出现有 dev/build/typecheck/test/lint/视觉/可访问性脚本,只记录真实存在的命令。 -14. 识别不存在的页面和工作区并标记 `NOT_APPLICABLE`,不得为了满足规范新增功能。 - -## 五、符合性状态 - -每项使用: -- `COMPLIANT`:已符合; -- `ADOPTED`:项目决定采用 NEX 建议; -- `ADAPTED`:采用项目既有成熟做法实现同一原则; -- `DEFERRED`:暂缓并记录原因/风险/复审条件; -- `NOT_APPLICABLE`:项目不存在该场景。 - -## 六、禁止事项 - -- 本轮不修改业务代码、CSS、配置或依赖。 -- 不把新项目默认技术栈错误地用于已有项目迁移。 -- 不忽略新项目 YAML 中已经明确给出的技术栈。 -- 不创建 NEX 同名组件包或重复 Token 层。 -- 不把参考项目的颜色、尺寸、断点和组件名称当成本项目默认值。 -- 不自动修复审计过程中发现的问题。 -- 不将审计报告视为后续开发授权。 - -## 七、交付物 - -1. 项目生命周期判断及证据; -2. 新项目的默认技术栈确认,或已有项目的真实技术栈清单; -3. 项目 UI/UX 规范现状; -4. NEX 符合性矩阵; -5. Token/主题/组件/页面模式映射; -6. 真实缺陷清单(位置、严重程度、证据、影响); -7. 响应式断点登记建议; -8. 窄屏表格策略及数据对账计划(如适用); -9. 可访问性证据等级、E3 风险触发评估和目标 OS/浏览器/AT 组合建议; -10. 质量门禁与视觉基线清单; -11. 分阶段改进计划、风险、回滚建议和需要用户决策的事项。 - -本轮完成审计后停止,等待用户批准具体实施范围。 diff --git a/templates/page-spec.md b/templates/page-spec.md deleted file mode 100644 index 2ddc5d8..0000000 --- a/templates/page-spec.md +++ /dev/null @@ -1,60 +0,0 @@ -# UI Page Specification - -## 1. 页面基本信息 -- 页面名称: -- 所属模块: -- 页面类型:Dashboard / List / Detail / Form / Settings / Workspace / Other -- 使用的项目 Shell / Layout: -- 主要用户: -- 核心任务: -- 对应项目规范章节: - -## 2. 信息结构 -- 页面上下文/标题: -- 主要操作: -- 次要操作: -- 页面主要区域及顺序: - -## 3. 组件复用 -- 已有项目组件: -- 第三方原生组件: -- 新增/扩展组件及理由: -- 对应组件契约或项目规范: - -## 4. 交互规格 -| 交互 | 触发方式 | 状态变化 | 成功反馈 | 失败处理 | 键盘替代 | -|---|---|---|---|---|---| -| | | | | | | - -## 5. 页面状态 -- Loading: -- Empty: -- Error: -- Forbidden: -- Disabled: -- Success: - -## 6. 响应式行为 -- 宽屏: -- 中等视口: -- 窄屏: -- 使用项目现有断点: - -## 7. 主题与可访问性 -- 支持主题: -- Keyboard / Focus: -- 可访问名称和状态文本: -- 长文本/溢出: -- 拖拽替代方式(如适用): -- Reduced Motion: - -## 8. 验收标准 -- [ ] 使用项目既有 Shell 和页面模式,或记录例外 -- [ ] 优先复用已有组件 -- [ ] 使用项目 Token/主题权威来源 -- [ ] 交互和异步状态完整 -- [ ] 支持主题检查完成(如项目支持多主题) -- [ ] 响应式检查完成 -- [ ] 键盘与焦点检查完成 -- [ ] 项目实际可执行的质量检查已运行 -- [ ] 未经授权的业务交互变化为零 diff --git a/templates/project-conformance-matrix.md b/templates/project-conformance-matrix.md deleted file mode 100644 index d8d880c..0000000 --- a/templates/project-conformance-matrix.md +++ /dev/null @@ -1,63 +0,0 @@ -# NEX Project Conformance Matrix - -**项目:** -**审计日期:** -**NEX 版本:** 0.1.6 -**项目级规范:** -**审计范围:** - -状态值:`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/project-design-map-template.md b/templates/project-design-map-template.md new file mode 100644 index 0000000..9938a2e --- /dev/null +++ b/templates/project-design-map-template.md @@ -0,0 +1,14 @@ +# NEX 项目设计映射(可选) + +| 设计领域 | NEX 原则 | 项目现有实现/文档 | 处理方式 | 备注 | +|---|---|---|---|---| +| 视觉语言 | | | ADOPTED / ADAPTED | | +| Design Tokens | | | ADOPTED / ADAPTED | | +| 布局与导航 | | | ADOPTED / ADAPTED | | +| 组件复用 | | | ADOPTED / ADAPTED | | +| 交互模式 | | | ADOPTED / ADAPTED | | +| 无障碍设计 | | | ADOPTED / ADAPTED / DEFERRED | | +| 响应式设计 | | | ADOPTED / ADAPTED | | +| 体验性能 | | | ADOPTED / ADAPTED | | + +只记录影响后续开发的关键差异;不要求穷举所有规则,也不要求每个任务更新此表。 diff --git a/templates/project-setup-prompt.md b/templates/project-setup-prompt.md new file mode 100644 index 0000000..015c7bc --- /dev/null +++ b/templates/project-setup-prompt.md @@ -0,0 +1,27 @@ +# NEX 项目初始化提示词 + +本项目采用 NEX Design System 0.1.7。请阅读项目根 `nex.config.yaml`、项目根 `AGENTS.md` 和 `standards/nex-design-system/AGENTS.md`。 + +## 任务 + +请按项目生命周期初始化或适配工程,并落实 NEX 的设计规范和 Agent 开发约束。 + +### 如果是新项目 +- 将 `nex.config.yaml` 的 `stack` 作为明确技术选型,不要重新询问技术栈; +- 按 `project.type` 初始化对应前后端; +- 建立简洁的项目 UI 规范,说明品牌/视觉方向、Token 主题来源、布局导航、组件原则和主要页面模式; +- 不生成 NEX 组件库,除非项目本身确有独立发布组件包的需求。 + +### 如果是已有项目 +- 识别并保留真实技术栈; +- 找出现有 UI 规范、Token/主题来源、共享组件和布局模式; +- 不套用 NEX 示例项目的固定尺寸、颜色或组件命名; +- 仅说明需要纳入后续开发约束的关键适配,不做无关全面审计。 + +## 执行边界 + +- 本任务关注技术起点、设计规范和 Agent 开发约束,不建立测试体系; +- 不新增 `reports/`、`scripts/ui/`、自动化测试或质量闸门; +- 不做无关业务功能开发; +- 不替换已有技术和组件; +- 结果简要汇报在对话中,只有用户明确要求才生成报告文件。 diff --git a/templates/project-ui-spec-template.md b/templates/project-ui-spec-template.md new file mode 100644 index 0000000..1bbbe9c --- /dev/null +++ b/templates/project-ui-spec-template.md @@ -0,0 +1,55 @@ +# [项目名称] UI/UX 设计规范 + +> 本文件定义本项目的具体设计选择。NEX Core 提供通用原则,不覆盖本文件中的项目专属值。 + +## 1. 产品定位与视觉方向 +- 产品类型: +- 目标用户与主要任务: +- 品牌/视觉关键词: +- 参考产品或视觉参考(可选): + +## 2. 技术与 UI 基础 +- 前端框架/语言: +- UI 组件库: +- 样式方案: +- 主题模式: +- Token 权威来源: + +## 3. 设计语言 +- 主色与状态色语义: +- 字体与文字层级: +- 间距尺度: +- 圆角/边框/阴影: +- 图标风格: + +## 4. 布局与响应式 +- 主 Shell: +- 导航模式: +- Header / Sidebar / Content 关键尺寸: +- 内容最大宽度: +- 断点定义及行为: +- 窄屏表格与复杂工作区策略: + +## 5. 组件约定 +- 必须复用的项目共享组件: +- 表格/表单/弹层约定: +- 空、加载、错误和无权限状态: +- 不应新增的重复组件: + +## 6. 交互约定 +- 主次操作: +- 搜索/筛选: +- 编辑/保存/取消: +- 危险操作: +- 导航与状态持久化: + +## 7. 无障碍与体验性能 +- 键盘交互约定: +- 名称/图标/焦点约定: +- 动态状态与减少动效: +- 图片、长列表、加载和动效的体验原则: + +## 8. 项目例外 +- NEX 原则: +- 项目做法: +- 原因: diff --git a/templates/responsive-breakpoint-registry.md b/templates/responsive-breakpoint-registry.md deleted file mode 100644 index 44824d9..0000000 --- a/templates/responsive-breakpoint-registry.md +++ /dev/null @@ -1,22 +0,0 @@ -# Responsive Breakpoint Registry - -**Project:** -**Source of truth:** -**Owner:** -**Last reviewed:** - -| Name | Condition / CSS value | Layout problem / rationale | Affected pages/components | Authoritative definition | Before / at / after test widths | Evidence | Status / review condition | -|---|---|---|---|---|---|---|---| -| | | | | | | | | - -## Boundary Test Record - -| Breakpoint | Width before | Width at | Width after | Expected behavior | Actual result | Screenshot / test reference | Pass | -|---|---:|---:|---:|---|---|---|---| -| | | | | | | | | - -## Exceptions - -| Local exception | Reason | Why existing breakpoints are insufficient | Scope | Approval | Revisit condition | -|---|---|---|---|---|---| -| | | | | | | diff --git a/templates/ui-acceptance-checklist.md b/templates/ui-acceptance-checklist.md deleted file mode 100644 index 4f7d5e4..0000000 --- a/templates/ui-acceptance-checklist.md +++ /dev/null @@ -1,60 +0,0 @@ -# NEX UI / UX Acceptance Checklist - -## Specification & Reuse -- [ ] 已遵循 NEX Core 与项目级 UI 规范的层级关系 -- [ ] 已检查现有组件和页面模式 -- [ ] 新增组件有明确复用价值;未重复建设组件库 -- [ ] 项目特有差异已记录为适配,而非误判为不合规 - -## Visual -- [ ] 信息层级和页面任务清楚 -- [ ] 字体、颜色、间距、圆角和阴影来自项目 Token/主题体系 -- [ ] 同类页面保持一致 -- [ ] 视觉表达符合项目品牌规范 -- [ ] 没有无业务价值的装饰或内容模块 - -## Interaction -- [ ] 主要动作清晰且不重复 -- [ ] 搜索、筛选、重置和刷新行为明确 -- [ ] 表单校验、提交中、成功和失败状态完整 -- [ ] 破坏性动作有合理确认 -- [ ] 弹层焦点和关闭行为正确 -- [ ] 空数据、加载、错误和无权限状态完整 -- [ ] 既有业务操作路径没有未经授权改变 - -## Layout & Responsive -- [ ] 使用项目已有 Shell / 页面模式,或记录例外 -- [ ] 项目新增断点已登记,断点前/处/后已验证 -- [ ] 窄屏表格的数据字段/记录数/动作已对账 -- [ ] 没有意外的整页横向滚动 -- [ ] 工作区滚动容器明确 -- [ ] 长文本/长文件名不会撑破布局 -- [ ] 关键操作在目标视口仍可访问 - -## Accessibility -- [ ] 以 WCAG 2.2 AA 作为默认工程目标;项目更严格要求已登记 -- [ ] 交互元素使用适当语义 -- [ ] 键盘可达且焦点可见 -- [ ] 图标按钮具有准确的可访问名称 -- [ ] 装饰性图标不会被重复朗读或暴露内部 glyph 名称 -- [ ] 状态不只依赖颜色 -- [ ] 截断的重要信息有可访问的完整文本 -- [ ] 拖拽操作有非拖拽替代路径(如适用) -- [ ] 日常无障碍验收已完成 E0–E2(按受影响范围) -- [ ] 已评估复杂交互是否触发 E3;不适用时记录 E3_NOT_REQUIRED -- [ ] E3 必要但当前平台/设备不可用时标记 MANUAL_QA_REQUIRED -- [ ] 若执行 E3,已按目标 OS 选择 VoiceOver / NVDA / Orca 等,并记录真实播报 -- [ ] 未经本次 E3 明确授权,没有启动/关闭系统屏幕阅读器 -- [ ] 已尊重 reduced-motion - -## Theme -- [ ] 项目支持的主题均已检查 -- [ ] 表格、弹层、图表、代码区和选中态均检查(如适用) - -## Engineering & Evidence -- [ ] Token 权威来源和派生链路未被破坏 -- [ ] 未引入不必要重复 Token、主题或组件层 -- [ ] 项目真实可执行的质量门禁已运行 -- [ ] 视觉回归范围与本次改动影响面匹配 -- [ ] Bundle/CSS 性能结论有测量数据,不只依据构建警告 -- [ ] 规范偏离、无法执行的检查和遗留问题已明确记录