main
mula.liu 2026-11-12 18:20:35 +08:00
parent b76ec7cdd9
commit 59b62d620a
45 changed files with 847 additions and 2435 deletions

BIN
.DS_Store vendored 100644

Binary file not shown.

150
AGENTS.md
View File

@ -1,116 +1,64 @@
# NEX Design System — Agent Entry Rules (0.1.6)
# NEX Design System — Agent Development Rules (0.1.7)
本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 `docs/`、`config/` 和 `templates/`。如果本文件被合并到项目根 `AGENTS.md`,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。
NEX 的目标是统一设计规范并约束 Agent 开发行为。NEX 不负责测试体系、测试覆盖率、自动化测试、质量闸门或测试报告。
## 1. 开始任务前必须读取
## 1. 每个任务的最小读取范围
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. `docs/12-responsive-accessibility-quality.md`
11. `docs/14-accessibility-platform-matrix.md`
12. 项目根目录 `nex.config.yaml`(如存在)
13. 项目级 UI/UX 规范(由 `nex.config.yaml` 声明;如未声明,先搜索项目现有设计文档)
开始任务时读取:
1. 本文件;
2. 项目根目录 `nex.config.yaml`(如存在);
3. 项目根 `AGENTS.md` 中的项目规则;
4. 项目已有的 UI/UX 规范(如存在)。
只在任务涉及 NexDocus 历史实现或明确要求参考时,读取 `docs/01-project-audit.md` 和 `config/reference-nexdocus-profile.example.yaml`。它们不是新项目的实施基线。
然后**按任务读取** NEX 文档,不得默认全量读取:
- 视觉风格/页面:`docs/01-design-principles.md`、`docs/08-page-patterns.md`;
- 颜色/主题/Token:`docs/02-design-tokens-and-theme.md`;
- 页面布局/导航/移动端:`docs/03-layout-and-responsive.md`;
- 公共组件:`docs/04-component-system.md`;
- 表单/表格/弹层/反馈:`docs/05-interaction-system.md`;
- 语义/键盘/辅助技术支持:`docs/06-accessibility-design.md`;
- 体验性能/加载呈现:`docs/07-performance-aware-design.md`;
- 新项目技术栈:`docs/10-project-stack-defaults.md`;
- 首次接入:`docs/11-project-adoption.md`。
## 2. 规范层级
## 2. 新项目与已有项目
遵循 NEX 三层模型:
- 新项目:`nex.config.yaml` 的 `stack` 是明确技术选型。按它初始化,不得自行换栈。
- 已有项目:以真实代码、依赖和锁文件为准,保留现有技术栈;不得因为 NEX 默认值不同而迁移。
- 项目具体视觉参数、Token 名称、组件 API、布局尺寸和断点以项目级 UI 规范为准。
- **NEX Core**:跨项目质量与设计治理要求。
- **Project Design Specification**:本项目视觉、布局、技术和交互的权威具体规范。
- **Project Implementation**:当前主题、Token、组件和页面的真实实现。
## 3. 开发时必须遵守
NexDocus 参数、示例截图和示例组件名不是跨项目默认值。新项目的技术起步默认值以 `nex.config.yaml` 的 `stack` 为准;它只适用于新项目初始化,不是 NEX Core 对所有项目的强制技术栈。已有项目由项目级规范和真实实现决定。NEX Core 的通用 MUST 要求不能因项目偏好而取消,但可以采用不同技术方式满足。
1. 先理解现有页面和组件,再改代码;优先复用,不重复造组件。
2. 使用项目既有 Token 和主题单一来源,不另建重复变量层。
3. 保持同类页面、组件和交互的一致性。
4. 不擅自改变业务流程、交互路径、默认值或数据语义。
5. 不擅自升级依赖、替换 UI 库、改变语言或重构目录。
6. 仅修改完成当前任务所需的范围;不顺手重构无关页面。
7. 响应式、无障碍和体验性能按对应设计规范实现;不把这些要求扩展成 NEX 自建测试流程。
8. 若项目实现与 NEX 示例不同,先判断是否是合理的项目适配,不强制套用示例尺寸或命名。
9. 设计要求有冲突时,以安全/适用规范底线、项目级 UI 规范和用户明确要求为依据;无法确定时只提出一个关键问题。
## 3. 默认技术栈与自动发现(0.1.6;沿用 0.1.5 默认栈)
## 4. 执行方式
`config/project-profile.example.yaml` 是带有明确默认技术栈的配置模板。它不是“技术栈自动猜测模板”。
默认采用轻量开发:
- 对当前需求做必要分析;
- 查找相关现有组件、Token、页面模式;
- 读取相关 NEX 章节;
- 直接实施必要修改;
- 在对话中简要汇报文件和行为变化。
- **新项目**:`project.lifecycle` 为 `new`,或 `auto` 且仓库为空/没有实际应用代码时,必须把 `stack` 中的默认技术栈作为初始化目标。不得忽略这些选型,也不得再次要求用户填写一份技术栈问卷。
- **已有项目**:`project.lifecycle` 为 `existing`,或 `auto` 且仓库已有应用代码/锁文件/构建配置时,以实际项目为准;默认技术栈仅供参考,不得据此替换、升级或迁移现有技术。
- `project.type` 默认是 `fullstack`。纯前端或纯后端项目只需覆盖该字段。
- 用户可以只覆盖 `stack` 中不符合当前项目意图的字段;未覆盖的默认值仍然有效。
只有涉及全局 Token、应用 Shell、导航体系、共享组件 API 或大范围视觉统一时,才先提交简短影响说明和实施计划。
新项目默认栈详见 `docs/13-project-stack-defaults.md`,包括 React、TypeScript、Vite、Ant Design、Tailwind CSS v4、Python、FastAPI、SQLite/PostgreSQL 等。依赖版本采用创建时兼容的稳定版本,并提交 lockfile。
## 5. NEX 的文件和工具边界
Agent 仍须自动发现已有项目的实际情况,包括:
- 项目名称、类型和主要界面语言;
- 前后端框架、语言、依赖版本、构建工具和 UI/样式方案;
- 项目 UI/UX 规范与设计决策文档;
- Token 权威来源、主题链路、共享组件目录和布局模式;
- 路由、断点、响应式规则、质量命令、视觉基线和 CI;
- 适用的辅助技术验证范围及尚未执行的人工测试。
- 普通任务不得创建阶段报告、审计报告、`reports/` 目录或截图证据目录。
- 不得为了遵守 NEX 新建 `scripts/ui/`、自定义检查脚本、自动化测试或质量闸门。
- 不得自动引入 Playwright、axe、Vitest、Pytest 或其他测试工具;它们由项目自身工程规范决定。
- 不得启动 VoiceOver、NVDA、Orca 等屏幕阅读器;NEX 不定义其测试流程。
- 不得把 NEX 规范文档复制成项目中的第二套完整 UI 规范。项目只需保留必要的项目专属设计说明。
- 只有用户明确要求,或确有长期设计决策需要留档时,才新增/更新文档。
无法发现的信息应标记 `UNKNOWN` 并说明证据缺口。不得把 `auto` 当成待用户填写的占位符,也不得为了补全配置而向用户发送长问卷。只有在信息无法从仓库确认且会影响产品选择、数据安全或高风险改动时,才提出最少量的具体问题。
## 6. 汇报要求
新项目未覆盖的 `stack` 字段采用默认技术栈。已有项目不采用默认栈迁移,而是优先保留真实、成熟的现有实现;NEX 的通用设计质量要求仍然适用。
## 4. 开发前审计要求
修改既有前端前,先检查:
- 项目技术栈和真实依赖(以锁文件、`package.json`、构建配置为证据)。
- 项目级 UI 规范和设计决策记录。
- Token 的单一事实来源及其派生链路(CSS、主题库、框架变量等)。
- 已有组件、页面模式、主题机制和布局参数。
- 现有交互路径、响应式行为、自动化检查与视觉基线。
将发现映射为 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED` 或 `NOT_APPLICABLE`。优先使用 `templates/project-conformance-matrix.md`。如果用户要求只审计,则不得修改业务代码。
## 5. 强制约束
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. **响应式断点必须登记。** 新增断点应有语义名称、数值/范围、布局理由、权威来源和边界测试;不得散落增加无法追踪的媒体查询。
15. **窄屏数据必须可对账。** 隐藏列、卡片化或折叠详情不得导致重要数据无处可见;必须核验字段、记录数、顺序和动作仍可访问。
16. **图标不得污染可访问名称。** 装饰性图标应从辅助技术名称计算中排除;图标与可见文案组合时避免重复朗读;图标本身不能以内部 glyph 名称充当业务文案。
17. **真实 AT 验证按风险触发且跨平台选择。** 日常默认 E0–E2;只有复杂自定义控件、拖拽/排序、复合导航、关键数据表格、重要 Live Region 或合同/目标用户要求触发 E3。macOS 使用 VoiceOver,Windows 使用 NVDA(必要时 JAWS/Narrator),Linux 使用 Orca。E3 不适用时记录 `E3_NOT_REQUIRED`;必要但环境不可用时标记 `MANUAL_QA_REQUIRED`。
18. **不得擅自启动屏幕阅读器。** 启动、关闭或切换 VoiceOver/NVDA/Orca 等系统 AT 前必须获得用户对本次 E3 的明确授权。记录初始状态,不得关闭用户原本启用的 AT,不得擅改系统级辅助功能设置。日常视觉、浏览器自动化和键盘验收不得启动屏幕阅读器。
19. **样式层与性能优化必须有证据。** 不为形式一致进行全量 CSS Layer 迁移;不为消除 Bundle 警告盲目调阈值或分包。先提供级联冲突或实际加载数据,再做最小变更。
20. **范围受控。** 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。
## 6. 标准工作流
1. 读取 NEX Core、项目配置和项目级设计规范。
2. 检查真实实现并建立符合性/差异映射。
3. 明确任务范围、复用组件、可能受影响页面和回归面。
4. 对跨组件或跨页面改动先提交实施计划;仅在用户已明确授权的范围内执行。
5. 先修正 Token/主题/共享模式,再迁移具体页面;避免一次性机械替换。
6. 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。
7. 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。
8. 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。
9. 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;E3 按风险触发,不适用时记录 `E3_NOT_REQUIRED`,必要但未执行时标记 `MANUAL_QA_REQUIRED`。
## 7. 例外记录
偏离 NEX Core 的 SHOULD 或采用不同项目实现时,记录:规则、状态(通常为 `ADAPTED` / `DEFERRED`)、原因、证据、影响范围、责任人/批准来源和复审条件。不得把单个项目的例外自动推广为全局规范。
## 8. 完成定义
只有在以下事项满足后,才能报告任务完成:
- 项目规范与实现之间没有未说明的重大冲突。
- 新增实现优先复用了现有组件、Token 和页面模式。
- 没有未经授权改变技术栈、布局基线或业务交互。
- 适用的主题、响应式、键盘和状态检查已执行。
- 项目真实可用的质量门禁已执行;不可执行项已说明。
- 文档、配置和代码行为保持一致。
用简洁对话汇报:完成内容、主要文件、关键设计选择、尚未解决的阻塞。除用户明确要求外,不生成长篇报告,不列出与本任务无关的测试证据。

View File

@ -1,95 +1,21 @@
# Changelog
## 0.1.6 — 2026-11-08
## 0.1.7 — Lean Design & Agent Development Rules
### Changed
- 明确 WCAG 2.2 AA 为 Web 产品默认无障碍工程目标;该目标不等于自动化扫描即可证明正式合规。
- 将日常无障碍验收默认收敛为 E0 源码/语义审阅、E1 自动化、E2 浏览器交互。
- 将 E3 真实屏幕阅读器验收调整为按风险和项目目标平台触发的专项验证,不要求每次开发、每个页面或每个项目启动读屏器。
- 明确跨平台 AT 选择:macOS VoiceOver、Windows NVDA(按需 JAWS/Narrator)、Linux Orca;测试结果仅对实际测试的 OS/浏览器/AT 组合有效。
- 明确日常 UI 测试不得自动启动屏幕阅读器;启动/关闭/切换系统 AT 前必须获得本次 E3 测试的明确授权,并保护用户原有 AT 状态和系统设置。
- 区分 `E3_NOT_REQUIRED`、`MANUAL_QA_REQUIRED`、`E3_PASS` 和 `E3_FAIL`。
- 保留 0.1.5 的新项目默认技术栈、少量覆盖配置和已有项目保护机制。
### 范围重新定义
- 将 NEX 职责收敛为:统一设计规范、约束 Agent 开发行为。
- 明确 NEX 不覆盖测试体系、测试覆盖率、自动化测试、浏览器测试流程、屏幕阅读器测试、CI 质量闸门和测试报告。
- 响应式与性能保留为设计规范内容,不再形成测试/度量/预算工作流。
- 无障碍保留为设计与实现要求,不再规定 E0–E3、AT 平台矩阵和读屏验收流程。
### Added
- 新增 `docs/14-accessibility-platform-matrix.md`,提供 macOS/Windows/Linux 的 AT 选择、风险触发和执行边界。
- 更新真实 AT 测试记录,增加测试授权、AT 初始状态、平台版本和实际播报记录。
### Agent 执行减负
- 默认按任务相关章节加载,不再每次读取全部 NEX 文档。
- 日常任务默认轻量开发;全局设计变更才需要简短影响分析。
- 普通任务默认不创建报告、阶段文件、截图证据目录或自定义检查脚本。
- 不为 NEX 引入或要求测试工具。
### Design Intent
- 无障碍质量要求是强制的;启动某个屏幕阅读器不是强制的。
- 浏览器自动化和键盘交互承担日常验证;真实读屏用于高风险、自定义交互或明确合规/用户需求场景。
- Agent 在无法访问目标平台时应诚实记录证据缺口,而不是将一种操作系统的结果外推到其他平台。
## 0.1.5 — 2026-11-08
### Changed
- 修正 0.1.4 将“减少配置填写”误处理为“新项目技术栈全部自动发现”的问题。
- 恢复明确的新项目默认全栈方案:React + TypeScript + Vite + Ant Design + Tailwind CSS v4;Python + FastAPI;开发 SQLite、生产 PostgreSQL;REST/OpenAPI;本地资源 `./data`。
- 增加 `project.lifecycle`(auto/new/existing)和 `project.type`(fullstack/frontend-only/backend-only),区分新项目初始化与已有项目适配。
- 明确新项目必须将 `stack` 作为技术选型目标;已有项目必须以真实代码为准,不得因默认栈不同而自动迁移。
- 支持只覆盖少量技术字段,不要求填写整套技术清单。
- 新增 `docs/13-project-stack-defaults.md`,统一记录默认栈、稳定版本策略、项目类型和覆盖规则。
- 更新 START-HERE、AGENTS、README、接入指南和审计提示词,确保技术栈在新项目初始化中不会被自动发现机制吞掉。
### Design Intent
- “少量填写”应来自预置明确默认值,而不是删除重要配置。
- 技术选型由 NEX 默认 profile 提供起点;Agent 自动发现的是项目事实和实现位置。
- 新项目执行默认值,已有项目保护现状;不得混用两种模式。
## 0.1.4 — 2026-11-08
### Changed
- 将新项目配置模板精简为默认可用配置,复制为 `nex.config.yaml` 后无需填写。
- 移除 `SET_ME` 和大量逐项登记要求;项目名称、技术栈、UI 规范、Token、组件、断点、质量命令和辅助技术范围由 Agent 在审计中自动发现。
- 明确 `auto` 是自动发现策略,不是要求用户替换的占位符。
- 增加 `UNKNOWN` 处理:证据不足时先记录并继续审计,仅对影响产品决策或高风险实施的未知项提问。
- 更新快速开始、Agent 入口、审计提示词和项目接入文档,统一零配置使用方式。
### Design Intent
- 降低 NEX 接入门槛,默认配置承载稳定的跨项目治理要求;项目事实由 Agent 发现,少数特殊偏好再通过可选覆盖项表达。
- 不降低规范要求,也不把技术识别责任转嫁给用户。
## 0.1.3 — 2026-11-08
### Added
- 响应式命名断点登记与断点前/处/后边界测试规则。
- 窄屏数据表格列优先级、适配策略和数据对账方法。
- 装饰性图标从辅助技术名称中排除、图标按钮命名和避免 glyph 内部名称污染的规则。
- 截断文本的辅助技术/键盘/Hover 能力检测/触屏多通道访问原则。
- 真实辅助技术验收证据等级 E0–E3,以及 `MANUAL_QA_REQUIRED` 状态。
- 导航持久偏好状态与临时交互状态的生命周期区分。
- 语义/行为质量闸要求;CSS Layer 与 Bundle 优化必须提供实际证据。
- 新增响应式断点登记和辅助技术测试记录模板。
### Changed
- 更新 Agent 执行入口、项目配置模板、符合性矩阵和验收清单。
- 明确窄屏表格必须对账记录数、关键字段、排序/筛选语义和行操作,不得只凭截图或自动化宽度闸判定通过。
- 明确 `aria-label`、`aria-keyshortcuts` 或 DOM 探针不能单独证明真实屏幕阅读器表现。
- 明确 NEX 不强制 CSS Cascade Layers,也不设跨项目通用 Bundle 字节阈值。
### Scope & Evidence Note
- 本版本吸收 NEX Phase 8.5 的跨项目方法性经验,不复制 `nex_animation` 的端口、绝对路径、提交哈希、脚本名、组件名或单项目断点数值。
- `nex_animation` 当前 N14 真实读屏验收仍未完成;本版本仅定义验收方法和证据要求,不宣称该项目或任何未实际测试的组合已通过。
- 诸如 S-2 图标名称、具体表格、特定 chunk 体积和 N9/N10/N12/N17 等单项目未完成项,只有其通用原则进入规范;项目专属修复状态仍由该项目自身跟踪。
## 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 示例配置容易被误读为新项目默认技术栈与布局值的问题。
- 修复参考项目的专属工作区可能被错误套用到不存在这些功能的新项目的问题。
### 保留
- 新项目明确的默认技术栈。
- 已有项目保留实际技术栈。
- NEX Core / 项目设计规范 / 代码实现三层关系。
- Token 单一来源、组件复用、视觉一致性、布局、交互、无障碍、响应式和体验性能设计原则。

55
CLEANUP-GUIDE.md 100644
View File

@ -0,0 +1,55 @@
# 0.1.6 → 0.1.7 清理与迁移指南
本指南用于替换 NEX 规范包,并帮助清理此前 Agent 因过重流程产生的文件。**不要把项目自身的业务报告、测试和工具全部误删。**
## A. NEX 规范包本身
如果项目当前有 `standards/nex-design-system/`:
1. 先备份该目录中项目自行添加的文件;
2. 用 0.1.7 完整替换 NEX 规范包;
3. 检查项目根 `AGENTS.md` 中的 NEX 路径;
4. 更新 `nex.config.yaml` 的 `nex.version` 为 `0.1.7`,保留你已经覆盖的 stack 字段。
不要同时保留多个版本的 NEX 规范目录供 Agent 加载。
## B. 可以从 NEX 接入流程中移除的旧规范文件
0.1.7 已不再使用以下测试治理资产。如果它们只是为了 NEX 0.1.6 而加入项目,可以从 NEX 安装目录移除:
- `docs/12-responsive-accessibility-quality.md`(旧 E0–E3 / 测试证据 / 质量流程)
- `docs/14-accessibility-platform-matrix.md`
- `templates/assistive-technology-test-record.md`
- `templates/ui-acceptance-checklist.md`(含测试与验收流程的旧版)
- `templates/responsive-breakpoint-registry.md`(若只用于断点测试记录;断点设计规则已合并到布局规范)
- `templates/new-project-audit-prompt.md`(由新的轻量 `project-setup-prompt.md` 替代)
注意:这些是旧 NEX 包内的文件,不代表项目自己建立的测试文档都应该删除。
## C. 项目根目录的 `reports/`
不要删除整个 `reports/`。先分类:
- 业务报告、用户交付物、运行记录:保留;
- NEX 阶段过程报告:先合并长期设计决策,再归档或删除;
- 临时截图、浏览器 trace、重复证据:确认不再引用后可移出 Git 或删除。
如果项目需要保留一份 NEX 设计决策摘要,建议只保留 `docs/NEX-DESIGN-DECISIONS.md`,不要继续生成每次任务一份的阶段报告。
## D. 项目 `scripts/ui/`
NEX 0.1.7 不要求创建、运行或维护 `scripts/ui/`。但这不表示可以未经检查直接删除:
1. 检查 `package.json`、CI、根 `AGENTS.md`、文档、pre-commit hooks 和其他脚本是否引用它;
2. 判断其中哪些脚本确实被项目团队使用;
3. 仅当确认脚本完全由此前 NEX 治理流程引入、无其他调用者且不再需要时,才可删除;
4. 仍有项目价值的脚本归项目自身维护,不再归 NEX 管理。
`__pycache__/` 是运行缓存,可清理,并应在 `.gitignore` 中忽略 `__pycache__/`、`*.py[cod]`。
## E. 不要删除
- 项目现有 UI 组件、Token、主题和页面代码;
- 项目自己的 `docs/UI规范.md` 或其他权威设计规范;
- 项目业务报告、业务脚本和实际运行所需工具;
- 用户明确要求保留的历史记录。

162
README.md
View File

@ -1,129 +1,79 @@
# NEX Design System
**版本:0.1.6**
**版本定位:默认技术栈 + 跨平台、按风险触发的无障碍治理版**
**核心原则:统一质量底线,不强制复制单一项目的视觉参数或技术实现。**
**版本:0.1.7 — Lean Design & Agent Development Rules**
## 0. 快速开始
NEX 的职责只有两项:
新项目先阅读 [`START-HERE.md`](START-HERE.md),复制 `config/project-profile.example.yaml` 为项目根目录 `nex.config.yaml`,然后将 [`templates/new-project-audit-prompt.md`](templates/new-project-audit-prompt.md) 交给 Agent 执行只读审计。
1. **统一软件产品的设计规范**:视觉语言、Design Tokens、布局、响应式、组件、交互、无障碍和面向用户体验的性能原则。
2. **约束 AI Agent 的开发行为**:明确技术栈默认值、优先复用项目资产、遵守项目设计规范、控制修改边界,避免擅自换栈和重复造轮子。
## 1. NEX 是什么
**NEX 不负责建立或管理测试体系。** 测试覆盖率、自动化测试框架、浏览器回归、屏幕阅读器测试流程、CI 质量闸门、测试报告和测试脚本均不属于 NEX 的规范范围。项目原有的测试实践继续由项目自身工程约定管理,不由 NEX 扩展。
NEX Design System 是面向 AI Agent 辅助软件开发的跨项目设计治理体系,覆盖视觉原则、Design Tokens、布局模式、组件契约、交互规则、无障碍、响应式、项目适配和 Agent 执行流程。
## 1. 0.1.7 的定位
NEX 不要求所有项目长成同一种样子。它统一设计质量、交互可预期性、可访问性和验证方法;项目具体视觉、布局尺寸、技术栈、组件 API 和页面模式由项目级规范决定。
0.1.7 是一次范围收敛和流程减负版本,不是增加更多治理层。相较 0.1.6:
## 2. 0.1.6 的关键变化
- 删除 E0–E3、AT 平台矩阵和读屏测试记录等测试治理内容。
- 移除自动化测试、浏览器测试矩阵、报告产出和质量闸门要求。
- 保留无障碍作为设计与实现要求,不规定屏幕阅读器测试流程。
- 将响应式与性能放回设计规范,定义界面应如何适配和保持感知性能,不建立测试/预算/度量流程。
- Agent 默认采用轻量任务模式,按当前任务读取相关规范,不要求每次加载全部文档。
- 默认不创建阶段报告、审计报告、截图证据目录或自定义检查脚本。
- 保留新项目明确的默认技术栈;已有项目继续使用其现有技术栈。
### 跨平台、按风险触发的无障碍验证
1. 将 WCAG 2.2 AA 作为 Web 产品默认工程目标;它不是仅凭自动化扫描即可宣称的正式合规认证。
2. 日常无障碍验收默认使用 E0 源码/语义审阅、E1 自动化、E2 浏览器键盘/指针交互。
3. E3 真实屏幕阅读器验证按风险和项目目标平台触发,不要求每次开发、每个页面或每个项目都启动屏幕阅读器。
4. 按操作系统选择 AT:macOS VoiceOver、Windows NVDA(按需 JAWS/Narrator)、Linux Orca。一次测试结果只适用于实际测试的 OS/浏览器/AT 组合。
5. 启动、关闭或切换系统屏幕阅读器必须取得本次 E3 测试的明确授权;Agent 不得更改用户原有 AT 状态或系统级偏好。
6. 区分 `E3_NOT_REQUIRED`、`MANUAL_QA_REQUIRED`、`E3_PASS` 和 `E3_FAIL`。
7. 新增 `docs/14-accessibility-platform-matrix.md`,说明跨平台选择、风险触发、环境不可用和启停保护规则。
## 3. 0.1.5 的关键变化
- 恢复明确的新项目默认全栈方案:React + TypeScript + Vite + Ant Design + Tailwind CSS v4;Python + FastAPI;开发 SQLite、生产 PostgreSQL;REST/OpenAPI;本地资源 `./data`。
- 使用 `project.lifecycle` 和 `project.type` 区分新项目初始化与已有项目适配。
- 新项目采用 YAML 中的 `stack` 默认值;已有项目以真实代码和锁文件为准,不得自动迁移到默认栈。
- 只需覆盖少数不符合项目意图的字段;组件目录、Token 来源、断点和质量命令由 Agent 自动发现。
## 4. 继承的核心治理原则
### 4.1 三层规范模型
## 2. NEX 的规范层级
| 层级 | 名称 | 职责 |
|---|---|---|
| L1 | **NEX Core** | 跨项目质量、可访问性、交互、Token 治理和 Agent 执行底线 |
| L2 | **Project Design Specification** | 项目专属视觉语言、布局、断点、主题、组件接口和业务交互 |
| L3 | **Project Implementation** | 当前代码中的 Token、主题、共享组件、页面和行为 |
| L1 | NEX Core | 跨项目的设计原则和 Agent 开发约束 |
| L2 | Project Design Specification | 项目自己的品牌、视觉、布局、断点、组件和业务交互规范 |
| L3 | Project Implementation | 当前项目中的主题、Token、组件和页面代码 |
### 4.2 规范优先级
具体视觉参数和业务交互由项目决定。NEX 不把 NexDocus 或任何单一项目的颜色、尺寸、断点、组件 API 当成全局标准。
1. 适用的安全、法律、隐私和无障碍底线不得由项目偏好绕过。
2. NEX Core 的 MUST 要求必须满足,但可用不同技术方式实现。
3. 项目级规范决定具体设计值、技术栈、组件 API、页面模式和业务交互。
4. 已验证的项目实现可作为证据;文档与代码冲突时先审计,不得自动假定哪一方正确。
5. NexDocus 等参考项目只用于解释设计意图,不覆盖新项目规范。
## 3. 快速开始
## 5. 文档地图
1. 将本目录放在项目 `standards/nex-design-system/`。
2. 将 `config/project-profile.example.yaml` 复制到项目根目录并命名为 `nex.config.yaml`。默认技术栈已经填写,不需要重新填写一份技术问卷。
3. 将本包 `AGENTS.md` 的入口规则合并到项目根 `AGENTS.md`,不要覆盖已有项目指令。
4. 新项目使用默认栈;已有项目保留实际技术栈。
5. 新项目首次接入时,使用 `templates/project-setup-prompt.md`;日常开发不需要重复执行接入审计。
| 文档 | 内容 |
## 4. 文档地图
| 文档 | 作用 |
|---|---|
| `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` | WCAG 工程目标、语义、名称、键盘、焦点、响应式和拖拽替代 |
| `docs/09-agent-execution-rules.md` | Agent 审计、计划、实施和验收工作流 |
| `docs/10-adoption-roadmap.md` | 分阶段采用路线 |
| `docs/11-project-onboarding.md` | 新项目接入、符合性映射和例外记录 |
| `docs/12-responsive-accessibility-quality.md` | 断点、窄屏表格、E0–E3 证据、E3 风险条件和权限规则 |
| `docs/13-project-stack-defaults.md` | 新项目默认技术栈、生命周期识别、覆盖与已有项目保护规则 |
| `docs/14-accessibility-platform-matrix.md` | macOS/Windows/Linux 的 AT 选择、E3 风险触发和启停授权 |
| `templates/assistive-technology-test-record.md` | 真实 AT 验收记录模板 |
| `templates/new-project-audit-prompt.md` | 新项目首次接入的只读审计提示词 |
| `templates/page-spec.md` | 页面规格模板 |
| `templates/ui-acceptance-checklist.md` | UI/UX 验收清单 |
| `templates/project-conformance-matrix.md` | 项目符合性映射模板 |
| `templates/responsive-breakpoint-registry.md` | 命名断点登记与边界测试模板 |
| `config/project-profile.example.yaml` | 明确默认技术栈的项目配置 |
| `config/reference-nexdocus-profile.example.yaml` | NexDocus 历史参考配置,仅供比对 |
| `AGENTS.md` | NEX Agent 入口规则 |
| `docs/00-governance.md` | NEX 职责边界、三层规范和优先级 |
| `docs/01-design-principles.md` | 产品视觉与信息设计原则 |
| `docs/02-design-tokens-and-theme.md` | Token、主题和单一事实来源 |
| `docs/03-layout-and-responsive.md` | 布局、导航、响应式设计 |
| `docs/04-component-system.md` | 组件复用和组件行为契约 |
| `docs/05-interaction-system.md` | 页面、表单、表格、弹层和状态交互 |
| `docs/06-accessibility-design.md` | 无障碍设计与实现要求,不包含测试流程 |
| `docs/07-performance-aware-design.md` | 面向体验的性能设计原则,不包含性能测试或预算体系 |
| `docs/08-page-patterns.md` | 常见页面与工作区模式 |
| `docs/09-agent-development-rules.md` | Agent 如何按需读取规范、约束代码修改 |
| `docs/10-project-stack-defaults.md` | 新项目默认技术栈与已有项目保护 |
| `docs/11-project-adoption.md` | 一次性项目接入方式 |
## 6. 如何在项目中使用
## 5. 明确不属于 NEX 的内容
建议项目结构:
以下内容由项目自身工程体系决定,不由 NEX 规定或自动生成:
```text
project-root/
├── AGENTS.md
├── nex.config.yaml
├── standards/
│ └── nex-design-system/
├── docs/
│ └── UI规范.md # 如项目已有,作为项目级规范
└── frontend/ / backend/
```
- 单元测试、集成测试、端到端测试及覆盖率目标;
- Playwright、Vitest、Pytest 等测试工具的选型、配置和执行频率;
- 浏览器路由 × 视口 × 主题的全量测试矩阵;
- VoiceOver、NVDA、Orca 等屏幕阅读器测试矩阵和证据等级;
- CI/CD、质量闸门、lint/test 命令和发布验收流程;
- `reports/` 报告目录、阶段报告和测试证据归档;
- `scripts/ui/` 自定义质量检查脚本。
1. 将 ZIP 内 `NEX-Design-System-v0.1.6/` 放入 `standards/nex-design-system/`。
2. 不覆盖项目已有根 `AGENTS.md`;合并 NEX 入口规则并修正引用路径。
3. 从 `config/project-profile.example.yaml` 复制为项目根目录 `nex.config.yaml`。新项目使用默认栈;已有项目保留真实技术栈。
4. 已有 UI 规范继续作为 Project Design Specification,不必复制成第二套重复文档。
5. 先只读审计、建立符合性矩阵并提交计划;用户批准后再实施。
NEX 仍然规定界面应具备的响应式、无障碍和性能体验,但不规定通过哪些测试来证明它们。
## 7. 符合性状态
## 6. 文件和报告原则
| 状态 | 含义 |
|---|---|
| `COMPLIANT` | 已满足 NEX Core 要求 |
| `ADOPTED` | 项目决定采用 NEX 建议 |
| `ADAPTED` | 使用项目既有成熟做法实现同一原则 |
| `DEFERRED` | 暂缓处理并记录理由/风险/复审条件 |
| `NOT_APPLICABLE` | 项目不存在该功能或场景,不应引入无关实现 |
## 8. 无障碍与质量证据边界
Web 产品默认以 WCAG 2.2 AA 作为工程目标。日常默认执行 E0–E2;真实屏幕阅读器 E3 按风险、目标用户和产品支持平台触发。macOS 使用 VoiceOver,Windows 使用 NVDA(按需 JAWS/Narrator),Linux 使用 Orca。不得把一个平台的结果外推到其他平台。
E3 不适用时记录 `E3_NOT_REQUIRED`;E3 必要但环境/权限/设备不可用时记录 `MANUAL_QA_REQUIRED`。只有真实执行并记录具体环境后才能报告 `E3_PASS` 或 `E3_FAIL`。Agent 不得未经本次 E3 测试明确授权启动、关闭或切换系统屏幕阅读器。
## 9. 版本演进原则
- NEX Core 的变更记录在 `CHANGELOG.md`。
- 单个项目的专属参数不自动升级为全局规范。
- 跨项目反复验证且具有普遍价值的规则,才考虑进入后续版本。
- 规范、配置、Agent 指令、模板和检查机制必须保持一致。
---
**维护目标:** NEX 应减少 Agent 的自由发挥空间,但不抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。
- 普通开发结果默认在 Agent 对话中简要汇报,不创建 Markdown 报告。
- 不为每次功能开发创建阶段编号、审计报告或证据目录。
- 不新增 NEX 专属测试脚本或质量检查目录。
- 只有用户明确要求,或确实需要记录长期有效的项目设计决策时,才创建/更新项目文档。
- 优先更新已有项目规范,不复制出第二份重复规范。

View File

@ -1,101 +1,47 @@
# NEX 0.1.6 — 新项目快速开始(带默认技术栈)
# NEX 0.1.7 — 快速开始
## 1. 放置规范包
## 第一步:放置规范
建议目录:
将整个 `NEX-Design-System-v0.1.7/` 放到:
```text
project-root/
├── AGENTS.md
├── nex.config.yaml
├── standards/
│ └── nex-design-system/
├── docs/
└── frontend/ / backend/ # 由项目类型和默认技术栈初始化
project-root/standards/nex-design-system/
```
将 ZIP 内 `NEX-Design-System-v0.1.6/` 的内容放入 `standards/nex-design-system/`。
## 第二步:复制配置
## 2. 复制默认配置
复制:
将 `standards/nex-design-system/config/project-profile.example.yaml` 复制到项目根目录,命名为 `nex.config.yaml`。
`standards/nex-design-system/config/project-profile.example.yaml`
**默认技术栈已经给定,不需要从零填写:**
到项目根目录并命名为:
- 前端:React + TypeScript + Vite + 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。
`nex.config.yaml`
这些是 NEX 新项目的默认起步方案。需要不同技术时,只修改 YAML 中对应字段,不必填写整份技术清单。
默认技术栈已预置。通常只需要在项目类型不是全栈,或你明确要改变默认技术时,覆盖少量字段。
### 生命周期如何处理
## 第三步:合并 Agent 入口
`project.lifecycle` 默认为 `auto`:
不要覆盖项目已有的根 `AGENTS.md`。将本包 `AGENTS.md` 中的 NEX 入口段合并进去,并把规范路径调整为实际路径。
- 空仓库/无应用代码:按新项目处理,使用上述默认技术栈。
- 已有代码、锁文件或构建配置:按已有项目处理,自动识别并保留当前技术栈,不会强行改成默认方案。
## 第四步:首次接入
如果需要明确指定,可将其改为 `new` 或 `existing`。
- 新建空项目:把 `templates/project-setup-prompt.md` 交给 Agent,让它依据配置初始化项目骨架和设计基础。
- 已有项目:同样使用该提示词,但要求 Agent 识别并保留现有技术栈、Token、组件和 UI 规范,不得迁移技术栈。
### 项目类型
首次接入完成后,日常开发不再重复执行完整接入流程。
默认 `project.type: fullstack`。纯前端项目只需改为 `frontend-only`;纯后端项目改为 `backend-only`。Agent 不应初始化不适用的部分。
## 日常开发
## 3. 合并根 AGENTS.md
直接向 Agent 描述功能需求。默认规则:
不要覆盖项目已有的根 `AGENTS.md`。合并以下规则,并按实际安装路径调整:
1. 读取项目根 `AGENTS.md`、`nex.config.yaml` 和项目级 UI 规范;
2. 只读取与当前任务相关的 NEX 章节;
3. 优先复用现有布局、Token 和组件;
4. 按项目已有的设计语言实现;
5. 不擅自升级技术栈、改变业务交互或重做无关页面;
6. 在对话中说明改了什么,不自动生成阶段报告。
```markdown
## NEX Design System
## NEX 不接管测试
本项目采用 NEX Design System 0.1.6 作为跨项目设计治理标准。
规范位于 `standards/nex-design-system/`。
UI/UX 任务开始前,读取 NEX AGENTS.md、docs/00-governance-and-adaptation.md、
docs/09-agent-execution-rules.md、docs/12-responsive-accessibility-quality.md、
docs/13-project-stack-defaults.md、docs/14-accessibility-platform-matrix.md,以及项目根目录 nex.config.yaml。
新项目按 nex.config.yaml 中的 stack 默认值初始化,不得忽略或自行替换技术选型。
已有项目自动识别实际技术栈并保留,不得因默认值不同而迁移。
先审计、建立符合性矩阵、提交计划;未经授权不得全量重构或自动进入下一阶段。
```
## 4. 首次交给 Agent
将 `templates/new-project-audit-prompt.md` 交给 Agent。
- 新项目:先核对默认技术栈与项目类型,给出目录结构、依赖和初始化计划;本轮只审计,不实际创建业务代码,除非你另行授权。
- 已有项目:从锁文件、源码、构建配置和运行结果识别真实技术栈,形成与 NEX 的差异映射;不得把默认栈当作迁移目标。
## 5. 只修改真正需要覆盖的字段
例如,若希望数据库从“开发 SQLite、生产 PostgreSQL”改为两阶段均 PostgreSQL,只修改:
```yaml
stack:
database:
development: PostgreSQL
production: PostgreSQL
```
如希望纯前端项目,只修改:
```yaml
project:
type: frontend-only
```
其余默认项保持不动。审计报告不是代码修改授权;确认实施范围后再让 Agent 开始开发。
## 6. 无障碍测试怎么执行
- 默认工程目标为 WCAG 2.2 AA;日常验收使用源码审阅、Playwright/axe 等自动化和浏览器键盘交互(E0–E2)。
- 真实屏幕阅读器(E3)仅在复杂自定义交互、关键业务流程、Live Region、复合控件或客户/法规要求等风险条件下触发,不是每次提交的必做步骤。
- 按项目目标平台选择 AT:macOS VoiceOver、Windows NVDA(必要时 JAWS/Narrator)、Linux Orca。项目不承诺的平台不强制加入测试矩阵。
- Agent 不得自动启动或关闭系统屏幕阅读器;启动/关闭前必须取得本次 E3 测试的明确授权。
- 目标环境不可用时,若 E3 已判定必要,标记 `MANUAL_QA_REQUIRED`;若风险评估不需要 E3,记录 `E3_NOT_REQUIRED`。
详见 `docs/08-accessibility-responsive.md`、`docs/12-responsive-accessibility-quality.md` 和 `docs/14-accessibility-platform-matrix.md`。
NEX 不规定测试框架、测试覆盖、浏览器测试流程、屏幕阅读器测试或质量闸门。项目原有工程规范继续负责这些内容。不要因为安装 NEX 而新增 `reports/`、`scripts/ui/` 或其他测试资产。

View File

@ -1 +1 @@
0.1.6
0.1.7

View File

@ -1,24 +1,22 @@
# NEX 0.1.6 默认项目配置
# 新项目采用明确默认技术栈;已有项目自动识别并保留现状。
# 通常无需填写。需要更换技术方案时,只修改 stack 中对应字段即可。
# NEX 0.1.7 默认项目配置
# 新项目使用明确默认栈;已有项目保留真实栈。
# 普通使用无需填写整张表,只需覆盖与项目意图不同的字段。
nex:
version: "0.1.6"
version: "0.1.7"
compliance: required
profile_mode: default_stack_with_project_adaptation
project:
name: auto
lifecycle: auto # auto | new | existing;空仓库按 new,已有代码按 existing
lifecycle: auto # auto | new | existing
type: fullstack # fullstack | frontend-only | backend-only
language: zh-CN
# 新项目默认技术栈(明确给定);已有项目不得因默认值不同而迁移。
# 仅作为新项目的默认技术方案。已有项目不得据此迁移。
stack:
preset: nex-standard-fullstack
version_policy: latest-stable-compatible
lockfile: required
frontend:
framework: React
language: TypeScript
@ -29,25 +27,22 @@ stack:
state_management: Zustand
routing: React Router
http_client: Axios
backend:
language: Python
framework: FastAPI
validation: Pydantic
orm: SQLAlchemy
migrations: Alembic
database:
development: SQLite
production: PostgreSQL
api:
style: REST
contract: OpenAPI
storage:
local_assets: ./data
# NEX 只定义设计和开发行为,不定义测试工具或质量闸门。
requirements:
use_shared_components: true
use_design_tokens: true
@ -55,32 +50,16 @@ requirements:
preserve_verified_patterns: true
preserve_existing_stack: true
avoid_duplicate_design_system_layers: true
responsive_design: required
accessibility_design: required
performance_aware_design: required
audit_before_broad_refactor: true
require_approval_for_broad_changes: true
tooling:
frontend:
lint: ESLint
format: Prettier
unit_test: Vitest
e2e_test: Playwright
backend:
test: Pytest
quality:
auto_discover_commands: true
responsive_review: true
keyboard_review: true
accessibility_naming_review: true
responsive_table_data_reconciliation: true
require_non_drag_alternative_when_applicable: true
performance_optimization_requires_measurement: true
accessibility:
engineering_target: WCAG_2_2_AA
routine_evidence_levels: [E0, E1, E2]
advanced_evidence_level: E3
real_screen_reader_testing: risk_based
screen_reader_platform_matrix: auto_by_project_support_scope
auto_start_screen_reader: false
explicit_user_approval_before_start: true
unavailable_environment_status: MANUAL_QA_REQUIRED
agent:
default_execution: lightweight
load_documents_by_task: true
create_reports_by_default: false
create_custom_check_scripts: false
add_test_frameworks: false
run_full_project_audit_for_routine_tasks: false

View File

@ -1,74 +0,0 @@
# 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

View File

@ -1,97 +0,0 @@
# 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 层或组件包。
`config/project-profile.example.yaml` 另提供了一套便于快速启动的**新项目默认技术栈**。它是可覆盖的 starter preset,不属于 NEX Core 对所有项目的强制技术规定:空仓库/新项目默认采用;已有项目不得因此迁移或替换现有技术。具体规则见 `docs/13-project-stack-defaults.md`。
## 7. 质量证据不可混用
源码中存在 ARIA 属性、静态 DOM 探针通过、浏览器键盘操作可用、屏幕阅读器实际播报正确,是不同层级的证据。日常默认执行 E0–E2;真实 AT 的 E3 按功能风险、产品支持平台和用户/合同要求触发,不是每次开发必做。E3 不适用时记录 `E3_NOT_REQUIRED`;已判定必要但未执行时标记 `MANUAL_QA_REQUIRED`。
响应式、表格、Token、CSS 层叠和 Bundle 优化同样应基于项目自己的实际值和可复现证据,不得把参考实现或固定阈值当作通用合规标准。
## 8. 从项目实践反哺 NEX
只有满足以下条件的项目经验,才建议提升为 NEX Core:
- 在两个或更多不同项目中验证,或有充分的跨项目工程理由。
- 解决的是通用设计/工程问题,而不是单一业务特例。
- 有明确的 MUST/SHOULD/MAY 级别和可验证方法。
- 不强制依赖某个框架、组件库或样式工具。
- 已更新文档、模板和 Agent 规则,且不与现有章节矛盾。

View File

@ -0,0 +1,49 @@
# 00. NEX Governance & Scope
## 1. NEX 的唯一职责
NEX 只负责两件事:
1. 统一软件产品的设计规范;
2. 约束 AI Agent 按照明确的技术栈、设计规范和项目既有资产开展开发。
NEX 不是测试框架、QA 体系、CI 平台或项目审计产品。
## 2. NEX 覆盖范围
- 设计原则与视觉语言;
- Design Tokens 与主题;
- 布局、导航与响应式界面设计;
- 组件复用与组件契约;
- 页面模式;
- 用户交互与状态反馈;
- 无障碍设计要求;
- 面向用户体验的性能设计原则;
- 默认技术栈与 Agent 开发约束。
## 3. 明确不覆盖
- 单元、集成、端到端测试及覆盖率;
- 测试框架、浏览器自动化和测试执行频率;
- 屏幕阅读器测试流程、平台矩阵和测试记录;
- CI/CD、lint/test 质量闸门、发布验收;
- 测试证据、截图归档和阶段报告;
- 自定义测试/审计脚本的建立和维护。
项目原有的测试体系继续按项目自身要求执行,NEX 不增补、不接管、不扩展。
## 4. 三层规范模型
| 层级 | 内容 | 决定什么 |
|---|---|---|
| L1 NEX Core | 跨项目设计和 Agent 开发约束 | 设计原则、复用、实现纪律 |
| L2 Project Design Specification | 项目专属规范 | 品牌、具体视觉、尺寸、断点、组件、业务交互 |
| L3 Project Implementation | 实际代码 | Token、主题、组件和页面实现 |
## 5. 冲突处理
- 用户当前明确要求优先于通用示例。
- 项目级 UI 规范决定项目具体视觉和交互。
- NEX Core 规定跨项目原则,不强制套用其他项目的像素数值、颜色、Token 前缀或组件命名。
- 已验证成熟的项目实现优先保留;发现冲突时先判断其是否为合理适配。
- 新项目技术栈按 `nex.config.yaml` 默认值;已有项目以实际代码和锁文件为准。

View File

@ -0,0 +1,46 @@
# 01. Design Principles
NEX 的默认产品气质是专业、清晰、可信赖、高信息效率和可预期。项目品牌与用户定位可调整具体表达,但不应牺牲信息清晰度和任务可用性。
## 1. Clarity First
- 页面标题、关键数据、主要操作和辅助信息层级明确。
- 用户能理解当前位置、当前对象和下一步操作。
- 不用装饰性图形替代信息架构。
## 2. Consistency over Novelty
- 同类任务采用一致的布局、操作位置、命名和反馈。
- 新视觉模式应有明确的业务或品牌理由。
- 一致性指设计语言和交互规律,不要求所有页面长得一样。
## 3. Density with Breathing Room
- 信息密度适配目标用户和使用场景。
- 专业工作台和数据页面可以高密度,但内容必须可扫描、控件必须可操作。
- 不用过度留白牺牲有效信息,也不把所有内容挤在一起。
## 4. Functional Color
- 颜色应有语义:品牌、文本、表面、边界、成功、警告、危险和信息。
- 状态不能只靠颜色区分,还应有文字、图标或形状提示。
- 颜色统一从项目主题/Token 管理。
## 5. Progressive Disclosure
- 首屏优先呈现完成当前任务必需的信息。
- 低频操作、高级筛选和复杂配置按需展开。
- 避免一次展示所有选项和辅助说明。
## 6. Predictable Interaction
- 操作结果、保存状态、撤销能力和数据影响应可预期。
- 异步操作应有清晰的处理中、成功和失败反馈。
- 破坏性操作要明确说明后果。
## 7. Visual Restraint
- 不默认给每张卡片添加阴影、渐变或彩色背景。
- 图标风格、尺寸和线宽保持一致。
- 动效用于解释状态变化,不制造无意义运动。
- 装饰必须服务品牌、内容或任务。

View File

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

View File

@ -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 页面。

View File

@ -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 不规定跨项目固定像素值。

View File

@ -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 层。
- [ ] 支持的主题覆盖关键组件和状态。
- [ ] 设计值例外已限域并说明。
- [ ] 布局尺寸没有多个互相冲突的权威定义。

View File

@ -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`。
- 固定高度应有产品理由,优先使用弹性布局和内容约束。

View File

@ -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*`。只在复用收益明确时抽象。

View File

@ -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 和导航行为;
- 关键尺寸的权威来源;
- 视口变化时的布局行为;
- 滚动容器归属;
- 受影响页面清单;
- 现有视觉截图或可用回归检查。

View File

@ -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 命名一致而重命名或重构成熟资产。

View File

@ -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、遮罩关闭、浏览器返回等行为符合容器用途。键盘操作不应被自定义热区破坏。

View File

@ -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 的启动、执行或记录流程;项目如有相关测试要求,由项目自己的工程规范决定。

View File

@ -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. 动效
- 动效必须解释状态变化,例如展开、收起、切换、加载完成。
- 避免对普通卡片普遍使用大幅上浮和缩放。
- 尊重减少动态效果设置。

View File

@ -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 页面
规则:
- 认证页聚焦唯一任务,不显示无关导航。
- 分享页面明确标注访问对象、权限和有效性。
- 对没有权限、链接失效、对象不存在等状态给出不同提示。

View File

@ -0,0 +1,33 @@
# 07. Performance-aware UI Design
本文件只规定与用户感知体验相关的设计和实现原则。它不定义性能测试、指标采集、预算阈值、Bundle 审计或 CI 性能闸门。
## 1. 感知性能
- 用户触发操作后,应尽快获得明确反馈,避免界面看似无响应。
- 长任务应呈现处理中状态;能分阶段呈现的内容可逐步展示。
- 内容加载时尽量保持布局稳定,避免主要区域突然跳动。
- Loading、Skeleton 等呈现方式应服务于真实加载过程,不作为装饰。
## 2. 内容与资源呈现
- 图片按实际展示尺寸提供,不在小缩略图区域加载不必要的大图。
- 视频、音频和大文件采用明确的预览/加载入口,避免进入页面就无条件加载全部资源。
- 长列表和大数据集应采用符合任务的分页、分段呈现或虚拟列表设计;选择方式应保持用户对位置和上下文的理解。
- 首屏优先展示完成当前任务所需的内容,低频模块按需呈现。
## 3. 动效与视觉开销
- 避免持续、无目的的动画和大面积高成本视觉效果。
- 状态动效应短暂、可理解,并尊重减少动态效果的系统偏好。
- 不为装饰加入影响阅读、滚动或操作响应的效果。
## 4. 交互中的性能感知
- 按钮在异步处理中应明确显示状态,避免重复点击。
- 搜索、筛选和自动保存等行为应避免不必要的频繁触发。
- 复杂工作区在加载、切换面板和切换数据时保持操作上下文清晰。
## 5. 技术选择边界
上述内容是设计层面的用户体验原则。具体代码分包、缓存、Web Vitals、Bundle 预算、性能分析和优化工具属于项目技术架构与性能工程范围,不由 NEX 规定。

View File

@ -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 等对应工具;不得因为开发机是某个系统,就假定所有用户都使用该系统,也不得要求所有项目覆盖全部读屏器组合。

View File

@ -0,0 +1,31 @@
# 08. Page Patterns
以下模式用于帮助 Agent 复用成熟的信息组织方式,不要求每个项目都拥有所有页面类型。
## 1. 数据列表
常见结构:页面标题/说明 → 搜索与筛选 → 工具栏 → 数据列表/表格 → 分页。主要操作突出,次要操作收纳;窄屏重组信息,不盲目压缩列宽。
## 2. 数据详情
常见结构:对象标题与状态 → 关键属性 → 分组详情 → 关联内容/操作。信息应按用户理解顺序组织,避免把所有字段平铺。
## 3. 数据编辑
常见结构:标题与上下文 → 分组表单 → 帮助/校验 → 明确保存与取消。复杂流程使用独立页面或步骤结构。
## 4. Dashboard
指标只呈现能支持判断的信息;指标卡、图表和明细应有明确关系。避免用大量同质卡片填满首屏。
## 5. 配置页面
按主题组织设置,当前分类和保存状态清晰。危险配置应说明影响范围。
## 6. 专业工作区
编辑器、聊天、画布、流程和媒体工作区可以采用专用布局。需要明确工具区、主工作区、属性区和滚动区职责,不强行套用 CRUD 页面。
## 7. 项目适配
如果项目已有成熟页面模式,优先复用并映射其设计意图,不为套用上述名称而重写。

View File

@ -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编写测试计划和测试报告。

View File

@ -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:视觉回归和质量门禁完善。
阶段不是强制顺序模板;具体由审计证据和用户授权决定。每阶段结束应形成可验收交付,不默认自动进入下一阶段。

View File

@ -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 实现。

View File

@ -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. 覆盖
只修改与项目意图不同的字段。不要要求用户重复填写整套技术栈。若明确需求与默认值冲突,说明冲突并提出最小调整,不得静默替换技术。

View File

@ -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 对一致性、组件复用、语义清晰和可用性的约束仍然适用。涉及用户目标不明确的产品决策时,提出一个关键问题,不要自行扩展范围。

View File

@ -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/组件接口调整;
- 改变业务交互路径或数据语义;
- 大规模迁移页面或删除历史实现。

View File

@ -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 时序(如适用);
- 未执行项、环境限制、风险和后续复核条件。

View File

@ -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 单一来源、交互一致性、可访问性、响应式和质量证据,而不要求所有项目都采用同一套框架。

View File

@ -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

View File

@ -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.

View File

@ -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. 分阶段改进计划、风险、回滚建议和需要用户决策的事项。
本轮完成审计后停止,等待用户批准具体实施范围。

View File

@ -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/主题权威来源
- [ ] 交互和异步状态完整
- [ ] 支持主题检查完成(如项目支持多主题)
- [ ] 响应式检查完成
- [ ] 键盘与焦点检查完成
- [ ] 项目实际可执行的质量检查已运行
- [ ] 未经授权的业务交互变化为零

View File

@ -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 模式/功能 | 不适用理由 | 是否需要后续复审 |
|---|---|---|
| | | |

View File

@ -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 | |
只记录影响后续开发的关键差异;不要求穷举所有规则,也不要求每个任务更新此表。

View File

@ -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/`、自动化测试或质量闸门;
- 不做无关业务功能开发;
- 不替换已有技术和组件;
- 结果简要汇报在对话中,只有用户明确要求才生成报告文件。

View File

@ -0,0 +1,55 @@
# [项目名称] UI/UX 设计规范
> 本文件定义本项目的具体设计选择。NEX Core 提供通用原则,不覆盖本文件中的项目专属值。
## 1. 产品定位与视觉方向
- 产品类型:
- 目标用户与主要任务:
- 品牌/视觉关键词:
- 参考产品或视觉参考(可选):
## 2. 技术与 UI 基础
- 前端框架/语言:
- UI 组件库:
- 样式方案:
- 主题模式:
- Token 权威来源:
## 3. 设计语言
- 主色与状态色语义:
- 字体与文字层级:
- 间距尺度:
- 圆角/边框/阴影:
- 图标风格:
## 4. 布局与响应式
- 主 Shell:
- 导航模式:
- Header / Sidebar / Content 关键尺寸:
- 内容最大宽度:
- 断点定义及行为:
- 窄屏表格与复杂工作区策略:
## 5. 组件约定
- 必须复用的项目共享组件:
- 表格/表单/弹层约定:
- 空、加载、错误和无权限状态:
- 不应新增的重复组件:
## 6. 交互约定
- 主次操作:
- 搜索/筛选:
- 编辑/保存/取消:
- 危险操作:
- 导航与状态持久化:
## 7. 无障碍与体验性能
- 键盘交互约定:
- 名称/图标/焦点约定:
- 动态状态与减少动效:
- 图片、长列表、加载和动效的体验原则:
## 8. 项目例外
- NEX 原则:
- 项目做法:
- 原因:

View File

@ -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 |
|---|---|---|---|---|---|
| | | | | | |

View File

@ -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 性能结论有测量数据,不只依据构建警告
- [ ] 规范偏离、无法执行的检查和遗留问题已明确记录