main
mula.liu 2026-11-08 20:31:12 +08:00
parent 0395c9e740
commit b76ec7cdd9
16 changed files with 350 additions and 211 deletions

View File

@ -1,4 +1,4 @@
# NEX Design System — Agent Entry Rules (0.1.5)
# NEX Design System — Agent Entry Rules (0.1.6)
本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 `docs/`、`config/` 和 `templates/`。如果本文件被合并到项目根 `AGENTS.md`,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。
@ -14,8 +14,9 @@
8. `docs/08-accessibility-responsive.md`
9. `docs/09-agent-execution-rules.md`
10. `docs/12-responsive-accessibility-quality.md`
11. 项目根目录 `nex.config.yaml`(如存在)
12. 项目级 UI/UX 规范(由 `nex.config.yaml` 声明;如未声明,先搜索项目现有设计文档)
11. `docs/14-accessibility-platform-matrix.md`
12. 项目根目录 `nex.config.yaml`(如存在)
13. 项目级 UI/UX 规范(由 `nex.config.yaml` 声明;如未声明,先搜索项目现有设计文档)
只在任务涉及 NexDocus 历史实现或明确要求参考时,读取 `docs/01-project-audit.md` 和 `config/reference-nexdocus-profile.example.yaml`。它们不是新项目的实施基线。
@ -29,7 +30,7 @@
NexDocus 参数、示例截图和示例组件名不是跨项目默认值。新项目的技术起步默认值以 `nex.config.yaml` 的 `stack` 为准;它只适用于新项目初始化,不是 NEX Core 对所有项目的强制技术栈。已有项目由项目级规范和真实实现决定。NEX Core 的通用 MUST 要求不能因项目偏好而取消,但可以采用不同技术方式满足。
## 3. 默认技术栈与自动发现(0.1.5)
## 3. 默认技术栈与自动发现(0.1.6;沿用 0.1.5 默认栈)
`config/project-profile.example.yaml` 是带有明确默认技术栈的配置模板。它不是“技术栈自动猜测模板”。
@ -82,9 +83,10 @@ Agent 仍须自动发现已有项目的实际情况,包括:
14. **响应式断点必须登记。** 新增断点应有语义名称、数值/范围、布局理由、权威来源和边界测试;不得散落增加无法追踪的媒体查询。
15. **窄屏数据必须可对账。** 隐藏列、卡片化或折叠详情不得导致重要数据无处可见;必须核验字段、记录数、顺序和动作仍可访问。
16. **图标不得污染可访问名称。** 装饰性图标应从辅助技术名称计算中排除;图标与可见文案组合时避免重复朗读;图标本身不能以内部 glyph 名称充当业务文案。
17. **真实 AT 验证不得由属性代替。** 对复杂自定义控件、拖拽替代、复合导航和关键数据交互,按目标环境执行屏幕阅读器人工验证;未执行时标记 `MANUAL_QA_REQUIRED`。
18. **样式层与性能优化必须有证据。** 不为形式一致进行全量 CSS Layer 迁移;不为消除 Bundle 警告盲目调阈值或分包。先提供级联冲突或实际加载数据,再做最小变更。
19. **范围受控。** 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。
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. 标准工作流
@ -96,7 +98,7 @@ Agent 仍须自动发现已有项目的实际情况,包括:
6. 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。
7. 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。
8. 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。
9. 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;未执行的 E3 必须标记 `MANUAL_QA_REQUIRED`。
9. 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;E3 按风险触发,不适用时记录 `E3_NOT_REQUIRED`,必要但未执行时标记 `MANUAL_QA_REQUIRED`。
## 7. 例外记录

View File

@ -1,46 +1,50 @@
# NEX Design System 0.1.5 — 修订摘要
# NEX Design System 0.1.6 — 修订摘要
## 本次修正的核心问题
## 本次修订目的
0.1.4 将“减少配置填写项”错误地处理为“新项目技术栈也全部自动发现”。这对于新建空项目不合理:没有现有代码可供识别,也就失去了跨 Agent 稳定复用的技术选型基线。
0.1.5 已将真实屏幕阅读器列为 E3 证据,但容易被 Agent 理解为常规验收步骤,导致日常开发时启动 VoiceOver。0.1.6 明确:无障碍要求仍是产品质量底线,但 VoiceOver 不是唯一读屏工具,E3 也不是每次开发必做。
0.1.5 改为双模式:
## 核心决策
- 新项目:使用 `nex.config.yaml` 中明确预置的默认技术栈。
- 已有项目:从真实代码和锁文件识别当前技术栈,并保留现状,不因默认 profile 而迁移。
1. **无障碍要求不降级。** Web 产品默认以 WCAG 2.2 AA 作为工程目标;这不是仅凭自动化扫描即可宣称正式合规。
2. **日常默认 E0–E2。** 源码与语义审阅、自动化检查、浏览器键盘/指针交互作为常规流程。
3. **E3 按风险触发。** 复杂自定义控件、拖拽/排序、复合导航、关键数据表格、重要 Live Region、已发现 AT 缺陷或客户/法规要求时评估真实读屏。
4. **跨平台选择 AT。** macOS 使用 VoiceOver;Windows 使用 NVDA(必要时按项目用户群增加 JAWS/Narrator);Linux 使用 Orca。按产品支持范围选择浏览器组合,不能跨平台外推结果。
5. **保护用户环境。** Agent 不得在日常 UI 测试中自动启动读屏器。启动、关闭或切换系统 AT 前,必须获得用户对本次 E3 测试的明确授权;不得关闭用户原本开启的读屏器或修改系统级偏好。
6. **状态准确。** E3 不适用时记录 `E3_NOT_REQUIRED`;E3 必要但目标环境不可用时记录 `MANUAL_QA_REQUIRED`;只有实际执行后才能记录 `E3_PASS` / `E3_FAIL`。
## 默认技术栈
## 平台建议矩阵
- 前端: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。
| 操作系统 | 屏幕阅读器 | 建议浏览器 |
|---|---|---|
| macOS | VoiceOver | Safari;按项目支持补充 Chrome |
| Windows | NVDA;按需 JAWS / Narrator | Firefox 或 Chrome/Edge,按目标支持范围 |
| Linux | Orca | 优先 Firefox;按项目支持补充 Chromium |
依赖采用创建时兼容的稳定版本,并通过 lockfile 固定实际解析结果。
具体组合可能因版本、发行版、桌面环境和产品支持范围而异,必须在测试记录中写明实际环境。
## 配置使用方式
## 配置更新
- `project.lifecycle: auto`:根据仓库是否已有实际应用代码自动区分新项目和已有项目。
- `project.type: fullstack`:默认全栈;可改为 `frontend-only` 或 `backend-only`。
- 用户只需修改不符合项目意图的少数字段,不需要填写完整技术清单。
保留 0.1.5 的明确默认技术栈,仅在 `quality.accessibility` 中增加默认工程目标、常规证据等级、E3 风险策略、跨平台选择和启停授权要求。无需用户额外填写操作系统或读屏器;Agent 根据产品支持范围提出测试矩阵。
## 修改文件
## 新增/更新文件
- `config/project-profile.example.yaml`
- `START-HERE.md`
- `README.md`
- `AGENTS.md`
- `docs/00-governance-and-adaptation.md`
- `docs/09-agent-execution-rules.md`
- `docs/11-project-onboarding.md`
- 新增 `docs/13-project-stack-defaults.md`
- `templates/new-project-audit-prompt.md`
- `templates/project-conformance-matrix.md`
- `CHANGELOG.md`
- `VERSION`
- 更新 `docs/08-accessibility-responsive.md`
- 更新 `docs/09-agent-execution-rules.md`
- 更新 `docs/12-responsive-accessibility-quality.md`
- 新增 `docs/14-accessibility-platform-matrix.md`
- 更新 `config/project-profile.example.yaml`
- 更新 `AGENTS.md`、README、START-HERE、审计提示词和验收清单
- 更新 `templates/assistive-technology-test-record.md`
## 官方参考
- WCAG 2.2: https://www.w3.org/TR/WCAG22/
- Playwright Accessibility Testing: https://playwright.dev/docs/accessibility-testing
- Apple VoiceOver Guide: https://support.apple.com/guide/voiceover/welcome/mac
- NVDA: https://www.nvaccess.org/download/
- GNOME Orca: https://gnome.pages.gitlab.gnome.org/orca/help/introduction.html
## 使用边界
默认技术栈是新项目 starter preset,不是所有既有项目的强制技术标准。NEX Core 仍不要求所有项目统一框架、UI 库、样式方案或数据库。
本版本定义通用跨平台策略,不宣称任何具体项目、页面、操作系统或屏幕阅读器组合已经通过 E3。实际结果只能由对应项目的真实测试记录支持。

View File

@ -1,5 +1,25 @@
# Changelog
## 0.1.6 — 2026-11-08
### 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 的新项目默认技术栈、少量覆盖配置和已有项目保护机制。
### Added
- 新增 `docs/14-accessibility-platform-matrix.md`,提供 macOS/Windows/Linux 的 AT 选择、风险触发和执行边界。
- 更新真实 AT 测试记录,增加测试授权、AT 初始状态、平台版本和实际播报记录。
### Design Intent
- 无障碍质量要求是强制的;启动某个屏幕阅读器不是强制的。
- 浏览器自动化和键盘交互承担日常验证;真实读屏用于高风险、自定义交互或明确合规/用户需求场景。
- Agent 在无法访问目标平台时应诚实记录证据缺口,而不是将一种操作系统的结果外推到其他平台。
## 0.1.5 — 2026-11-08
### Changed

178
README.md
View File

@ -1,87 +1,55 @@
# NEX Design System
**版本:0.1.5**
**版本定位:默认技术栈 + 响应式、可访问性与质量证据治理版**
**设计来源:NexDocus 参考实现 + 多项目审计 + NEX Phase 8.5 实践反馈**
**版本:0.1.6**
**版本定位:默认技术栈 + 跨平台、按风险触发的无障碍治理版**
**核心原则:统一质量底线,不强制复制单一项目的视觉参数或技术实现。**
## 0. 快速开始
新项目接入请先阅读 [`START-HERE.md`](START-HERE.md),并将 [`templates/new-project-audit-prompt.md`](templates/new-project-audit-prompt.md) 交给 Agent 做只读审计。
0.1.5 修正了 0.1.4 的过度“零配置”问题:减少填写项不等于移除新项目技术选型。现在采用“明确默认技术栈 + 项目事实自动识别”的双模式:
1. 新项目有明确默认技术栈:React + TypeScript + Vite + Ant Design + Tailwind CSS v4;Python + FastAPI;开发 SQLite、生产 PostgreSQL;REST/OpenAPI;本地资源 `./data`。
2. 默认配置可原样复制,不需要填写整套技术清单;只需修改不符合项目意图的少数技术字段。
3. `project.lifecycle: auto` 自动区分空仓库/新项目与已有项目。
4. 新项目采用 YAML 中的 `stack` 默认值作为初始化目标;已有项目以真实代码和锁文件为准,不得自动迁移到默认栈。
5. Agent 自动发现组件目录、Token 来源、断点、现有质量命令和项目级 UI 规范等代码库事实。
新项目先阅读 [`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. NEX 是什么
NEX Design System 是面向 AI Agent 辅助软件开发的跨项目设计治理体系。它覆盖视觉原则、Design Tokens、布局模式、组件契约、交互规则、可访问性、项目适配和 Agent 执行流程。
NEX Design System 是面向 AI Agent 辅助软件开发的跨项目设计治理体系,覆盖视觉原则、Design Tokens、布局模式、组件契约、交互规则、无障碍、响应式、项目适配和 Agent 执行流程。
NEX 的目标不是让所有项目长成同一个样子,而是让不同项目在保留自身成熟设计语言的前提下,拥有一致的设计质量、可理解的规则和可验证的工程约束。
NEX 不要求所有项目长成同一种样子。它统一设计质量、交互可预期性、可访问性和验证方法;项目具体视觉、布局尺寸、技术栈、组件 API 和页面模式由项目级规范决定。
**核心原则:统一质量与设计语法,不强制统一项目的视觉参数、技术栈、组件 API 或页面骨架。**
## 2. 0.1.6 的关键变化
## 2. 0.1.5 的关键变化
### 跨平台、按风险触发的无障碍验证
### 0.1.5:明确默认技术栈,区分新项目与已有项目
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`,说明跨平台选择、风险触发、环境不可用和启停保护规则。
1. 默认配置恢复明确的全栈技术方案,避免“零配置”导致新项目失去技术选型。
2. 新项目使用默认栈;已有项目自动识别并保护现状,不因默认栈不同而迁移。
3. 通过 `project.lifecycle` 和 `project.type` 区分项目生命周期及前后端范围。
4. 允许只覆盖少量 stack 字段,不要求填写完整技术问卷。
5. 增加 `docs/13-project-stack-defaults.md`,记录默认栈、版本策略和覆盖规则。
## 3. 0.1.5 的关键变化
### 0.1.3:响应式、可访问性与质量证据治理
- 恢复明确的新项目默认全栈方案:React + TypeScript + Vite + Ant Design + Tailwind CSS v4;Python + FastAPI;开发 SQLite、生产 PostgreSQL;REST/OpenAPI;本地资源 `./data`。
- 使用 `project.lifecycle` 和 `project.type` 区分新项目初始化与已有项目适配。
- 新项目采用 YAML 中的 `stack` 默认值;已有项目以真实代码和锁文件为准,不得自动迁移到默认栈。
- 只需覆盖少数不符合项目意图的字段;组件目录、Token 来源、断点和质量命令由 Agent 自动发现。
根据多项目实施与 NEX Phase 8.5 实践反馈,进一步强化“规范可适配、规则可验证、验收有证据”的治理要求:
## 4. 继承的核心治理原则
1. 增加响应式断点登记机制:允许项目在基础断点之外增加有理由的命名断点,并要求测试断点前、断点处和断点后。
2. 增加窄屏数据表格治理:按信息重要性选择隐藏/详情、卡片、横向滚动、固定列和操作菜单等策略,并通过数据对账确认没有信息丢失。
3. 强化可访问名称规则:装饰性图标不得混入控件名称;图标与可见文字并列时应避免重复朗读;重要截断信息必须有键盘、触屏和辅助技术可用的完整内容渠道。
4. 增加真实辅助技术验收分级:源码检查、自动化、键盘验证和真实屏幕阅读器验证是不同证据等级;不能仅凭 ARIA 属性或 DOM 形态宣称读屏验收通过。
5. 明确导航偏好状态与临时交互状态可以分开管理,例如桌面导航折叠偏好可持久化,移动端 Drawer 打开状态通常不持久化。
6. 明确 CSS Layer 迁移、样式层叠治理和 Bundle 拆分必须基于实际冲突或性能证据,不得为形式统一进行大规模重写。
7. 增加语义/行为质量闸、读屏测试记录模板和响应式断点登记模板。
8. 将单一项目的未完成事项保留为项目级待办;不把未完成或未验证的实现误写成 NEX 已验证能力。
### 4.1 三层规范模型
### 0.1.2 已有治理原则继续有效
| 层级 | 名称 | 职责 |
|---|---|---|
| L1 | **NEX Core** | 跨项目质量、可访问性、交互、Token 治理和 Agent 执行底线 |
| L2 | **Project Design Specification** | 项目专属视觉语言、布局、断点、主题、组件接口和业务交互 |
| L3 | **Project Implementation** | 当前代码中的 Token、主题、共享组件、页面和行为 |
0.1.2 根据真实新项目审计反馈,修正了 0.1.1 中将 NexDocus 现状参数写得过于像通用基线的问题:
### 4.2 规范优先级
1. 明确三层关系:NEX Core、Project Design Specification、Project Implementation。
2. 建立规范优先级和冲突处理规则。项目级规范负责具体视觉/布局实现;NEX Core 负责跨项目通用质量底线。
3. 将 NexDocus 审计和参数降级为**参考实现资料**,不再作为新项目默认值。
4. 将通用 `project-profile.example.yaml` 改为中性模板;原 NexDocus 参数另存为 `reference-nexdocus-profile.example.yaml`。
5. 增加项目符合性状态:`COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED`、`NOT_APPLICABLE`。
6. 明确优先复用项目已有 Token、主题管线、组件和页面模式,不强制新增 `--nex-*` 变量层或 NEX React 组件包。
7. 明确先审计、做差异映射、确认实施范围,再修改代码;禁止将参考项目的技术栈和尺寸机械套用到其他项目。
8. 增加键盘可访问性与拖拽操作替代路径等规则,并强化分阶段验收和变更边界。
## 3. 三层规范模型
| 层级 | 名称 | 职责 | 示例 |
|---|---|---|---|
| L1 | **NEX Core** | 跨项目的设计质量、可访问性、交互可预期性、Token 治理和 Agent 执行底线 | 不只用颜色表达状态;交互必须键盘可达;不擅自改变技术栈 |
| L2 | **Project Design Specification** | 项目专属视觉语言、布局尺寸、断点、主题策略、组件接口和业务交互 | `docs/UI规范.md`、项目设计手册、已批准的设计决策 |
| L3 | **Project Implementation** | 当前代码中的 Token、主题、共享组件、页面和行为实现 | `theme/antd.ts`、`applyRootVars`、`@theme`、项目组件目录 |
NEX Core 不规定所有项目必须使用同一品牌色、Header 高度、Sider 宽度、控件高度、CSS 技术或组件库。上述内容由项目级规范和经验证的实现确定。
## 4. 规范优先级与冲突处理
按以下顺序处理:
1. **安全、法律、隐私和无障碍的适用底线**不得被项目偏好或历史实现绕过。
2. **NEX Core 中标记为 MUST 的跨项目要求**必须满足;项目可以选择不同实现方式,但不能取消要求本身。
3. **项目级设计规范**决定本项目的具体设计值、技术栈、组件接口、页面模式和业务交互路径。
4. **已验证的项目实现**可作为项目规范的证据和实现基线;如果实现与规范不一致,必须先审计并记录,不得自动假定代码或文档哪一方正确。
5. **NEX 参考项目、示例配置和截图**只用于解释设计意图,不具备覆盖项目规范的权力。
发生冲突时,Agent 必须记录冲突位置、涉及层级、影响、推荐处理方式和验证方法。不得自行将项目改成参考项目的尺寸、视觉风格或技术栈。
1. 适用的安全、法律、隐私和无障碍底线不得由项目偏好绕过。
2. NEX Core 的 MUST 要求必须满足,但可用不同技术方式实现。
3. 项目级规范决定具体设计值、技术栈、组件 API、页面模式和业务交互。
4. 已验证的项目实现可作为证据;文档与代码冲突时先审计,不得自动假定哪一方正确。
5. NexDocus 等参考项目只用于解释设计意图,不覆盖新项目规范。
## 5. 文档地图
@ -93,27 +61,28 @@ NEX Core 不规定所有项目必须使用同一品牌色、Header 高度、Side
| `docs/03-design-tokens.md` | Token 治理、语义映射和主题单一事实来源 |
| `docs/04-layout-system.md` | 布局原则与可选页面/工作区模式 |
| `docs/05-component-system.md` | 组件资产盘点、复用和封装边界 |
| `docs/06-interaction-system.md` | 常见业务交互、反馈和异步状态 |
| `docs/06-interaction-system.md` | 业务交互、反馈和异步状态 |
| `docs/07-page-patterns.md` | 可选页面模式和组合建议 |
| `docs/08-accessibility-responsive.md` | 可访问性、响应式和输入方式替代 |
| `docs/09-agent-execution-rules.md` | Agent 审计、计划、实施、验收工作流 |
| `docs/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` | 断点登记、窄屏表格、可访问名称、语义/行为质量闸、真实 AT 验收和性能证据 |
| `docs/12-responsive-accessibility-quality.md` | 断点、窄屏表格、E0–E3 证据、E3 风险条件和权限规则 |
| `docs/13-project-stack-defaults.md` | 新项目默认技术栈、生命周期识别、覆盖与已有项目保护规则 |
| `templates/page-spec.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` | 项目命名断点登记与边界测试模板 |
| `templates/assistive-technology-test-record.md` | 屏幕阅读器/辅助技术人工验收记录模板 |
| `templates/new-project-audit-prompt.md` | 新项目首次接入的只读审计提示词 |
| `config/project-profile.example.yaml` | 含明确默认技术栈的项目配置;新项目采用,已有项目保护现状 |
| `templates/responsive-breakpoint-registry.md` | 命名断点登记与边界测试模板 |
| `config/project-profile.example.yaml` | 明确默认技术栈的项目配置 |
| `config/reference-nexdocus-profile.example.yaml` | NexDocus 历史参考配置,仅供比对 |
| `AGENTS.md` | NEX Agent 入口规则 |
## 6. 如何在项目中使用
建议将本目录放入项目仓库,例如:
建议项目结构:
```text
project-root/
@ -121,53 +90,40 @@ project-root/
├── nex.config.yaml
├── standards/
│ └── nex-design-system/
│ ├── AGENTS.md
│ ├── docs/
│ ├── config/
│ └── templates/
├── docs/
│ └── UI规范.md # 如项目已有,以其作为项目级规范
└── frontend/
│ └── UI规范.md # 如项目已有,作为项目级规范
└── frontend/ / backend/
```
接入步骤:
1. 将 ZIP 中 `NEX-Design-System-v0.1.5/` 放入项目 `standards/nex-design-system/`。
2. 不覆盖项目已有的根 `AGENTS.md`;将 NEX 入口规则合并进去,并确保引用路径正确。
3. 从 `config/project-profile.example.yaml` 复制为项目根目录 `nex.config.yaml`。新项目按其中默认技术栈初始化;已有项目由 Agent 自动识别真实技术栈并保留现状。组件目录、Token 来源、断点和质量命令等事实由 Agent 自动发现。
4. 如果项目已有 `docs/UI规范.md` 或类似设计手册,保留为 Project Design Specification 的权威文件,并在配置中登记。
5. 先执行只读审计,形成符合性映射,再批准具体实施阶段。不要直接要求 Agent 全量重构。
**不要用 `reference-nexdocus-profile.example.yaml` 创建其他项目的配置。** 它只记录 NexDocus 的历史事实。
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. 先只读审计、建立符合性矩阵并提交计划;用户批准后再实施。
## 7. 符合性状态
项目审计和映射必须使用以下状态:
| 状态 | 含义 |
|---|---|
| `COMPLIANT` | 已满足 NEX Core 要求 |
| `ADOPTED` | 项目决定采用 NEX 建议 |
| `ADAPTED` | 使用项目既有成熟做法实现同一原则 |
| `DEFERRED` | 暂缓处理并记录理由/风险/复审条件 |
| `NOT_APPLICABLE` | 项目不存在该功能或场景,不应引入无关实现 |
| 状态 | 含义 | Agent 行为 |
|---|---|---|
| `COMPLIANT` | 已满足 NEX Core 要求 | 保留;如有证据可引用 |
| `ADOPTED` | 项目决定采用 NEX 建议 | 按项目批准范围实施 |
| `ADAPTED` | 采用项目既有成熟做法实现同一原则 | 保留项目实现,记录映射关系和理由 |
| `DEFERRED` | 暂缓处理 | 记录原因、风险和复审条件 |
| `NOT_APPLICABLE` | 项目不存在该功能或场景 | 不引入无关组件/页面/约束 |
## 8. 无障碍与质量证据边界
不允许把 `ADAPTED` 视为“不合规”,也不允许把 `NOT_APPLICABLE` 转化为新建功能的理由。
Web 产品默认以 WCAG 2.2 AA 作为工程目标。日常默认执行 E0–E2;真实屏幕阅读器 E3 按风险、目标用户和产品支持平台触发。macOS 使用 VoiceOver,Windows 使用 NVDA(按需 JAWS/Narrator),Linux 使用 Orca。不得把一个平台的结果外推到其他平台。
## 8. 质量证据与验收边界
E3 不适用时记录 `E3_NOT_REQUIRED`;E3 必要但环境/权限/设备不可用时记录 `MANUAL_QA_REQUIRED`。只有真实执行并记录具体环境后才能报告 `E3_PASS` 或 `E3_FAIL`。Agent 不得未经本次 E3 测试明确授权启动、关闭或切换系统屏幕阅读器。
NEX 区分源码审阅、自动化检查、浏览器键盘验证和真实辅助技术验证。自动化通过不等于真实读屏通过;ARIA 属性存在也不等于辅助技术一定按预期播报。涉及复杂自定义控件、拖拽排序、复合导航和数据密集交互时,应根据目标用户环境安排真实 AT 验收。尚未执行的人工验证必须标记为 `MANUAL_QA_REQUIRED`,不得报告为完全验收通过。
## 9. 版本演进原则
NEX 也不强制所有项目采用相同的断点、表格响应式方案、CSS Layer 或代码分包策略。项目必须登记自己的设计决定,并用视口边界、数据对账、语义/行为和性能数据验证结果。
## 9. 版本和演进原则
- NEX Core 规则的变更应记录在 `CHANGELOG.md`。
- 项目专属参数和组件不应未经验证就上升为 NEX Core。
- 从多个项目反复验证、具有普遍价值的规则,才考虑纳入下一版 Core。
- 新项目审计发现的经验先记录为候选改进;不要因单一项目反馈立刻改变所有项目的默认实现。
- 规范、配置、代码实现和检查机制必须保持可追踪的一致关系。
- NEX Core 的变更记录在 `CHANGELOG.md`。
- 单个项目的专属参数不自动升级为全局规范。
- 跨项目反复验证且具有普遍价值的规则,才考虑进入后续版本。
- 规范、配置、Agent 指令、模板和检查机制必须保持一致。
---
**维护目标:** NEX 应减少 Agent 的自由发挥空间,但不应抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。
**维护目标:** NEX 应减少 Agent 的自由发挥空间,但不抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。

View File

@ -1,4 +1,4 @@
# NEX 0.1.5 — 新项目快速开始(带默认技术栈)
# NEX 0.1.6 — 新项目快速开始(带默认技术栈)
## 1. 放置规范包
@ -14,7 +14,7 @@ project-root/
└── frontend/ / backend/ # 由项目类型和默认技术栈初始化
```
将 ZIP 内 `NEX-Design-System-v0.1.5/` 的内容放入 `standards/nex-design-system/`。
将 ZIP 内 `NEX-Design-System-v0.1.6/` 的内容放入 `standards/nex-design-system/`。
## 2. 复制默认配置
@ -51,11 +51,11 @@ project-root/
```markdown
## NEX Design System
本项目采用 NEX Design System 0.1.5 作为跨项目设计治理标准。
本项目采用 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,以及项目根目录 nex.config.yaml。
docs/13-project-stack-defaults.md、docs/14-accessibility-platform-matrix.md,以及项目根目录 nex.config.yaml。
新项目按 nex.config.yaml 中的 stack 默认值初始化,不得忽略或自行替换技术选型。
已有项目自动识别实际技术栈并保留,不得因默认值不同而迁移。
@ -88,3 +88,14 @@ project:
```
其余默认项保持不动。审计报告不是代码修改授权;确认实施范围后再让 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`。

1
VERSION 100644
View File

@ -0,0 +1 @@
0.1.6

View File

@ -1,9 +1,9 @@
# NEX 0.1.5 默认项目配置
# 原则:新项目直接采用明确的默认技术栈;已有项目自动识别并保留现状。
# NEX 0.1.6 默认项目配置
# 新项目采用明确默认技术栈;已有项目自动识别并保留现状。
# 通常无需填写。需要更换技术方案时,只修改 stack 中对应字段即可。
nex:
version: "0.1.5"
version: "0.1.6"
compliance: required
profile_mode: default_stack_with_project_adaptation
@ -13,8 +13,7 @@ project:
type: fullstack # fullstack | frontend-only | backend-only
language: zh-CN
# 新项目默认技术栈(明确给定,不再要求 Agent 自行猜选型)
# lifecycle=new 时作为脚手架和实现目标;lifecycle=existing 时仅作参考,不得据此迁移现有技术栈。
# 新项目默认技术栈(明确给定);已有项目不得因默认值不同而迁移。
stack:
preset: nex-standard-fullstack
version_policy: latest-stable-compatible
@ -49,7 +48,6 @@ stack:
storage:
local_assets: ./data
# 跨项目工程要求
requirements:
use_shared_components: true
use_design_tokens: true
@ -60,7 +58,6 @@ requirements:
audit_before_broad_refactor: true
require_approval_for_broad_changes: true
# 新项目按默认工具链初始化;已有项目只发现现有命令,不得为匹配此处而强行替换工具。
tooling:
frontend:
lint: ESLint
@ -77,6 +74,13 @@ quality:
accessibility_naming_review: true
responsive_table_data_reconciliation: true
require_non_drag_alternative_when_applicable: true
evidence_levels: [E0, E1, E2, E3]
manual_at_for_complex_interactions: 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

View File

@ -82,7 +82,7 @@ NEX 是跨项目的设计治理框架,不是某个参考产品的像素规范
## 7. 质量证据不可混用
源码中存在 ARIA 属性、静态 DOM 探针通过、浏览器键盘操作可用、屏幕阅读器实际播报正确,是不同层级的证据。项目不得将低等级证据描述为高等级验收结论。对于复杂自定义交互和关键用户任务,应明确目标辅助技术组合并保留人工记录;没有完成真实 AT 测试时,必须标记 `MANUAL_QA_REQUIRED`。
源码中存在 ARIA 属性、静态 DOM 探针通过、浏览器键盘操作可用、屏幕阅读器实际播报正确,是不同层级的证据。日常默认执行 E0–E2;真实 AT 的 E3 按功能风险、产品支持平台和用户/合同要求触发,不是每次开发必做。E3 不适用时记录 `E3_NOT_REQUIRED`;已判定必要但未执行时标记 `MANUAL_QA_REQUIRED`。
响应式、表格、Token、CSS 层叠和 Bundle 优化同样应基于项目自己的实际值和可复现证据,不得把参考实现或固定阈值当作通用合规标准。

View File

@ -1,5 +1,19 @@
# 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、键盘和焦点行为。
@ -39,7 +53,7 @@
不能假设 HTML5 Drag and Drop API 自身就提供完整键盘体验。替代路径必须在功能上等价,不能只增加一个没有实际行为的快捷键说明。
对于复杂排序、画布、流程编辑器和其他自定义复合控件,应在目标屏幕阅读器环境中验证焦点、操作结果、位置播报和取消/恢复行为。无法执行真实 AT 测试时,必须标记 `MANUAL_QA_REQUIRED`,不得宣称完整无障碍验收通过。
对复杂排序、画布、流程编辑器和其他自定义复合控件,先通过 E0–E2 验证语义、键盘路径和操作结果;只有符合风险触发条件时,再安排 E3 真实屏幕阅读器验证。无法执行已判定必要的 E3 时,标记 `MANUAL_QA_REQUIRED`,不得宣称该 AT 组合已通过。
## 5. 响应式断点治理
@ -79,7 +93,7 @@
- 对隐藏或折叠字段确认存在可达的完整查看路径;
- 核对每行操作是否仍可访问且操作对象正确;
- 检查长文本、空值、极值、状态标签和权限差异;
- 对屏幕阅读器检查表头/标签、单元格或卡片阅读顺序,避免重复或丢失信息。
- 对屏幕阅读器检查表头/标签、单元格或卡片阅读顺序,避免重复或丢失信息。该项进入 E3 的条件由风险和平台支持范围决定,不要求每次表格样式调整都启动读屏器。
检查脚本可以辅助发现宽度、溢出和结构问题,但不得因测试规则不适配就放宽规则掩盖数据缺失。
@ -103,15 +117,16 @@
## 10. 建议验收
至少按项目适用性覆盖:
日常 UI/UX 变更按适用性优先执行 E0、E1、E2:
- 交互语义、可访问名称和装饰图标是否被正确隐藏;
- 键盘路径和可见焦点;
- 截断内容的辅助技术、键盘、Hover 能力和触屏渠道;
- 拖拽替代路径和关键复合控件的真实 AT 验证;
- 自定义断点登记及断点边界;
- 窄屏表格的数据对账和屏幕阅读器阅读顺序;
- Playwright/axe 等自动化可检测问题(若项目工具链支持);
- 键盘路径、可见焦点、焦点进入/返回;
- 截断内容的辅助技术文本、键盘、Hover 能力检测和触屏渠道;
- 拖拽替代路径;
- 自定义断点登记及边界测试;
- 窄屏表格数据对账;
- 导航状态持久化行为;
- CSS Layer/Bundle 优化的实际证据;
- 减少动态效果设置。
自动化检查、浏览器键盘检查和真实屏幕阅读器检查必须分别记录,不得相互替代。
E3 仅在 `docs/12-responsive-accessibility-quality.md` 定义的风险条件满足时安排。按项目实际支持的操作系统选择 VoiceOver、NVDA、Orca 等对应工具;不得因为开发机是某个系统,就假定所有用户都使用该系统,也不得要求所有项目覆盖全部读屏器组合。

View File

@ -1,6 +1,6 @@
# 09. Agent Execution Rules
## 0. 默认技术栈与自动发现(NEX 0.1.5)
## 0. 默认技术栈与自动发现(NEX 0.1.6,沿用 0.1.5 默认栈)
NEX 配置包含明确的新项目默认技术栈。减少配置填写项,不代表移除技术选型。
@ -72,7 +72,11 @@ Agent 不应在每次任务中重新发明项目设计。它应先理解项目
| E2 | 浏览器人工键盘/指针验证 | 目标浏览器中的操作路径和焦点行为 | 屏幕阅读器实际播报 |
| E3 | 真实辅助技术验证 | 指定 OS、浏览器、屏幕阅读器组合中的实际结果 | 未测试的其他环境组合 |
对拖拽替代、复杂自定义控件、复合导航和关键数据表格,应根据目标用户环境安排 E3 验证。未执行的项目标记 `MANUAL_QA_REQUIRED`,不能因存在 `aria-label`、`aria-keyshortcuts` 或自动化通过而报告完整读屏验收。
日常开发默认执行 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 标签或属性字符串。自动化无法可靠判断的部分应转人工验收。

View File

@ -126,35 +126,67 @@ NEX 不要求所有项目使用 CSS Cascade Layers。若项目同时使用 utili
静态探针可以验证源代码约束,但不能单独证明浏览器可访问树或实际读屏输出。优先采用浏览器可访问性树、自动化行为、键盘人工检查和真实 AT 记录组合验证。
## 9. 质量证据等级
## 9. 质量证据等级与日常默认流程
NEX 将无障碍验证分为四个证据等级,但**四个等级不代表每次开发都必须逐级执行**:
| 等级 | 名称 | 最低证据 | 可报告结论 |
|---|---|---|---|
| E0 | Source Reviewed | 源码、配置和实现路径审阅 | 实现中存在预期代码/属性 |
| E1 | Automated Checked | 实际运行的静态/自动化闸及输出 | 已覆盖的自动化规则通过 |
| E2 | Browser Interaction Verified | 指定浏览器中键盘/指针人工操作 | 该浏览器中的交互路径可用 |
| E3 | Assistive Technology Verified | 指定 OS + 浏览器 + 屏幕阅读器的实际操作与播报记录 | 该测试组合中的 AT 体验通过 |
| E0 | Source Reviewed | 源码、配置、HTML/ARIA 和组件实现审阅 | 实现中存在预期结构/属性;不能证明运行时表现 |
| E1 | Automated Checked | 实际运行的 Playwright、axe-core、单元/集成测试或语义探针结果 | 已覆盖规则的自动化检查通过;不能证明真实读屏体验 |
| E2 | Browser Interaction Verified | 指定浏览器中的键盘、指针/触屏实际操作记录 | 指定浏览器中的交互路径、焦点和反馈可用 |
| E3 | Assistive Technology Verified | 指定 OS + 浏览器 + 屏幕阅读器的真实操作与实际播报记录 | 仅该测试组合和测试范围中的 AT 体验通过 |
不同证据等级不能相互替代。`aria-label` 或 `aria-keyshortcuts` 存在,不等于 E3。若因设备或环境不足无法完成 E3,必须标记 `MANUAL_QA_REQUIRED`,并记录测试矩阵、未验证风险和负责人/后续安排。
**日常开发默认执行 E0–E2。** E3 是按风险和产品支持平台选择的专项测试,不要求每次代码修改、每个页面或每个项目都启动屏幕阅读器。浏览器自动化可以验证可访问树、名称/角色/状态、键盘脚本和 Live Region DOM 更新,但不能完整证明真实 AT 的播报、导航模式或快捷键处理。真实 AT 测试也不能替代 E0–E2 的常规回归。
## 10. 建议需要真实 AT 验证的场景
E3 状态应明确区分:
- `E3_NOT_REQUIRED`:完成风险评估后,当前功能/改动无需真实读屏验证,并记录理由;
- `MANUAL_QA_REQUIRED`:E3 已被判定必要,但当前环境、权限或设备不可用;
- `E3_PASS` / `E3_FAIL`:只在记录的真实环境中执行后填写。
按产品支持范围和风险至少评估:
- 自定义拖拽、排序和画布操作;
- 复合导航、菜单、Tabs 和状态切换;
- 具有复杂行列关系的数据表格;
- 需要 Live Region 播报的异步任务;
- 关键业务流程中的自定义控件。
不得因没有运行 E3 就将所有普通页面判为未验收;也不得对已判定 E3 必要的高风险交互,仅凭 ARIA 属性或自动化通过宣称无障碍验收完整。
不要求每个简单静态页面在所有读屏软件上做全量矩阵,但不能对高风险自定义交互仅凭自动化属性检查宣称 AT 通过。
## 10. E3 风险触发条件
## 11. 报告要求
优先评估以下场景是否需要 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;
- 工具/浏览器/OS/屏幕阅读器版本;
- 实际观察到的焦点、名称、状态和播报;
- 未完成项、风险和后续复核条件。
- 规则/组件/页面与风险评估理由;
- 目标平台、浏览器和视口;
- 测试数据集与数据对账结果(如适用);
- E0–E3 实际执行等级;
- 自动化命令和结果;
- E3 的 OS/发行版/桌面环境、浏览器、AT 名称及版本;
- 实际焦点路径、快捷键处理、真实播报内容和 Live Region 时序(如适用);
- 未执行项、环境限制、风险和后续复核条件。

View File

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

@ -4,16 +4,19 @@
- Project / version:
- Feature / component:
- User task:
- Risk level:
- E3 risk trigger / reason:
- Test date:
- Tester:
- User authorization for starting/stopping AT (reference or explicit instruction):
## 2. Environment
- OS and version:
- 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:
@ -29,17 +32,21 @@
|---|---|---|---|---|---|
| | | | | | |
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 / MANUAL_QA_REQUIRED / NOT_TESTED
**Final status:** PASS / PARTIAL / FAIL / E3_NOT_REQUIRED / MANUAL_QA_REQUIRED / NOT_TESTED
Do not mark E3 or final AT pass unless the named environment was actually used and observed.
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,6 +1,6 @@
# NEX 0.1.5 项目接入:只读审计与技术栈确认
# NEX 0.1.6 项目接入:只读审计与技术栈确认
本项目采用 NEX Design System 0.1.5。请先阅读:
本项目采用 NEX Design System 0.1.6。请先阅读:
- `standards/nex-design-system/AGENTS.md`
- `standards/nex-design-system/README.md`
@ -14,6 +14,7 @@
- `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 规范(如存在)
@ -58,10 +59,12 @@
6. 盘点响应式断点及其权威来源;标记未登记的局部断点。
7. 对数据表格评估窄屏策略、列优先级、行内动作和数据完整性。
8. 检查交互语义、可访问名称、装饰图标、键盘、焦点、截断文本和拖拽替代路径。
9. 区分源码审阅、自动化、浏览器键盘检查和真实屏幕阅读器验证证据;未执行真实 AT 时不得宣称读屏通过。
10. 盘点 CSS Layer/级联模型、Bundle/CSS 体积和现有性能预算;不得只凭警告数字判定缺陷。
11. 找出现有 dev/build/typecheck/test/lint/视觉/可访问性脚本,只记录真实存在的命令。
12. 识别不存在的页面和工作区并标记 `NOT_APPLICABLE`,不得为了满足规范新增功能。
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`,不得为了满足规范新增功能。
## 五、符合性状态
@ -92,7 +95,7 @@
6. 真实缺陷清单(位置、严重程度、证据、影响);
7. 响应式断点登记建议;
8. 窄屏表格策略及数据对账计划(如适用);
9. 可访问性证据等级和需要真实 AT 验证的项目;
9. 可访问性证据等级、E3 风险触发评估和目标 OS/浏览器/AT 组合建议;
10. 质量门禁与视觉基线清单;
11. 分阶段改进计划、风险、回滚建议和需要用户决策的事项。

View File

@ -2,7 +2,7 @@
**项目:**
**审计日期:**
**NEX 版本:** 0.1.5
**NEX 版本:** 0.1.6
**项目级规范:**
**审计范围:**

View File

@ -32,6 +32,7 @@
- [ ] 关键操作在目标视口仍可访问
## Accessibility
- [ ] 以 WCAG 2.2 AA 作为默认工程目标;项目更严格要求已登记
- [ ] 交互元素使用适当语义
- [ ] 键盘可达且焦点可见
- [ ] 图标按钮具有准确的可访问名称
@ -39,7 +40,11 @@
- [ ] 状态不只依赖颜色
- [ ] 截断的重要信息有可访问的完整文本
- [ ] 拖拽操作有非拖拽替代路径(如适用)
- [ ] 复杂交互已记录 E0–E3 证据等级;未执行真实 AT 时标记 MANUAL_QA_REQUIRED
- [ ] 日常无障碍验收已完成 E0–E2(按受影响范围)
- [ ] 已评估复杂交互是否触发 E3;不适用时记录 E3_NOT_REQUIRED
- [ ] E3 必要但当前平台/设备不可用时标记 MANUAL_QA_REQUIRED
- [ ] 若执行 E3,已按目标 OS 选择 VoiceOver / NVDA / Orca 等,并记录真实播报
- [ ] 未经本次 E3 明确授权,没有启动/关闭系统屏幕阅读器
- [ ] 已尊重 reduced-motion
## Theme