From b76ec7cdd97df5580c8b95b3369e85c79324d5b9 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Sun, 8 Nov 2026 20:31:12 +0800 Subject: [PATCH] v 0.1.6 --- AGENTS.md | 18 +- AUDIT-SUMMARY.md | 68 +++---- CHANGELOG.md | 20 ++ README.md | 178 +++++++----------- START-HERE.md | 19 +- VERSION | 1 + config/project-profile.example.yaml | 22 ++- docs/00-governance-and-adaptation.md | 2 +- docs/08-accessibility-responsive.md | 33 +++- docs/09-agent-execution-rules.md | 8 +- docs/12-responsive-accessibility-quality.md | 76 +++++--- docs/14-accessibility-platform-matrix.md | 75 ++++++++ templates/assistive-technology-test-record.md | 15 +- templates/new-project-audit-prompt.md | 17 +- templates/project-conformance-matrix.md | 2 +- templates/ui-acceptance-checklist.md | 7 +- 16 files changed, 350 insertions(+), 211 deletions(-) create mode 100644 VERSION create mode 100644 docs/14-accessibility-platform-matrix.md diff --git a/AGENTS.md b/AGENTS.md index 878da31..d1b3053 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. 例外记录 diff --git a/AUDIT-SUMMARY.md b/AUDIT-SUMMARY.md index 148a771..29521e3 100644 --- a/AUDIT-SUMMARY.md +++ b/AUDIT-SUMMARY.md @@ -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。实际结果只能由对应项目的真实测试记录支持。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b65103..90e46ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 2ee582e..5982934 100644 --- a/README.md +++ b/README.md @@ -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 的自由发挥空间,但不抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。 diff --git a/START-HERE.md b/START-HERE.md index baa52c7..77606e0 100644 --- a/START-HERE.md +++ b/START-HERE.md @@ -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`。 diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..c946ee6 --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.6 diff --git a/config/project-profile.example.yaml b/config/project-profile.example.yaml index 7c673cf..6c5abbb 100644 --- a/config/project-profile.example.yaml +++ b/config/project-profile.example.yaml @@ -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 diff --git a/docs/00-governance-and-adaptation.md b/docs/00-governance-and-adaptation.md index deba5a9..2b0e0f6 100644 --- a/docs/00-governance-and-adaptation.md +++ b/docs/00-governance-and-adaptation.md @@ -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 优化同样应基于项目自己的实际值和可复现证据,不得把参考实现或固定阈值当作通用合规标准。 diff --git a/docs/08-accessibility-responsive.md b/docs/08-accessibility-responsive.md index 09f8313..bd200b6 100644 --- a/docs/08-accessibility-responsive.md +++ b/docs/08-accessibility-responsive.md @@ -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 优化的实际证据; - 减少动态效果设置。 -自动化检查、浏览器键盘检查和真实屏幕阅读器检查必须分别记录,不得相互替代。 \ No newline at end of file +E3 仅在 `docs/12-responsive-accessibility-quality.md` 定义的风险条件满足时安排。按项目实际支持的操作系统选择 VoiceOver、NVDA、Orca 等对应工具;不得因为开发机是某个系统,就假定所有用户都使用该系统,也不得要求所有项目覆盖全部读屏器组合。 diff --git a/docs/09-agent-execution-rules.md b/docs/09-agent-execution-rules.md index 5a7bb9b..c755a5d 100644 --- a/docs/09-agent-execution-rules.md +++ b/docs/09-agent-execution-rules.md @@ -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 标签或属性字符串。自动化无法可靠判断的部分应转人工验收。 diff --git a/docs/12-responsive-accessibility-quality.md b/docs/12-responsive-accessibility-quality.md index dc0c284..31d3338 100644 --- a/docs/12-responsive-accessibility-quality.md +++ b/docs/12-responsive-accessibility-quality.md @@ -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 时序(如适用); +- 未执行项、环境限制、风险和后续复核条件。 diff --git a/docs/14-accessibility-platform-matrix.md b/docs/14-accessibility-platform-matrix.md new file mode 100644 index 0000000..6eff156 --- /dev/null +++ b/docs/14-accessibility-platform-matrix.md @@ -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 diff --git a/templates/assistive-technology-test-record.md b/templates/assistive-technology-test-record.md index a004116..b74cf4d 100644 --- a/templates/assistive-technology-test-record.md +++ b/templates/assistive-technology-test-record.md @@ -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. diff --git a/templates/new-project-audit-prompt.md b/templates/new-project-audit-prompt.md index eb6e18d..089edcc 100644 --- a/templates/new-project-audit-prompt.md +++ b/templates/new-project-audit-prompt.md @@ -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. 分阶段改进计划、风险、回滚建议和需要用户决策的事项。 diff --git a/templates/project-conformance-matrix.md b/templates/project-conformance-matrix.md index 60ecc12..d8d880c 100644 --- a/templates/project-conformance-matrix.md +++ b/templates/project-conformance-matrix.md @@ -2,7 +2,7 @@ **项目:** **审计日期:** -**NEX 版本:** 0.1.5 +**NEX 版本:** 0.1.6 **项目级规范:** **审计范围:** diff --git a/templates/ui-acceptance-checklist.md b/templates/ui-acceptance-checklist.md index 22df549..4f7d5e4 100644 --- a/templates/ui-acceptance-checklist.md +++ b/templates/ui-acceptance-checklist.md @@ -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