From 284ea5307273ecaec65ba1701e191c907f39a010 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Sun, 8 Nov 2026 15:37:35 +0800 Subject: [PATCH] v 0.1.3 --- AGENTS.md | 15 +- AUDIT-SUMMARY.md | 18 ++ CHANGELOG.md | 23 +++ README.md | 39 ++++- START-HERE.md | 71 ++++++++ VERSION | 2 +- config/project-profile.example.yaml | 38 ++++- .../reference-nexdocus-profile.example.yaml | 2 +- docs/00-governance-and-adaptation.md | 8 +- docs/04-layout-system.md | 23 +++ docs/05-component-system.md | 5 +- docs/08-accessibility-responsive.md | 113 ++++++++++--- docs/09-agent-execution-rules.md | 22 ++- docs/12-responsive-accessibility-quality.md | 160 ++++++++++++++++++ templates/assistive-technology-test-record.md | 45 +++++ templates/new-project-audit-prompt.md | 70 ++++++++ templates/project-conformance-matrix.md | 7 +- templates/responsive-breakpoint-registry.md | 22 +++ templates/ui-acceptance-checklist.md | 7 +- 19 files changed, 645 insertions(+), 45 deletions(-) create mode 100644 START-HERE.md create mode 100644 docs/12-responsive-accessibility-quality.md create mode 100644 templates/assistive-technology-test-record.md create mode 100644 templates/new-project-audit-prompt.md create mode 100644 templates/responsive-breakpoint-registry.md diff --git a/AGENTS.md b/AGENTS.md index e4fe4d3..e727c22 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# NEX Design System — Agent Entry Rules (0.1.2) +# NEX Design System — Agent Entry Rules (0.1.3) 本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 `docs/`、`config/` 和 `templates/`。如果本文件被合并到项目根 `AGENTS.md`,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。 @@ -13,8 +13,9 @@ 7. `docs/07-page-patterns.md` 8. `docs/08-accessibility-responsive.md` 9. `docs/09-agent-execution-rules.md` -10. 项目根目录 `nex.config.yaml`(如存在) -11. 项目级 UI/UX 规范(由 `nex.config.yaml` 声明;如未声明,先搜索项目现有设计文档) +10. `docs/12-responsive-accessibility-quality.md` +11. 项目根目录 `nex.config.yaml`(如存在) +12. 项目级 UI/UX 规范(由 `nex.config.yaml` 声明;如未声明,先搜索项目现有设计文档) 只在任务涉及 NexDocus 历史实现或明确要求参考时,读取 `docs/01-project-audit.md` 和 `config/reference-nexdocus-profile.example.yaml`。它们不是新项目的实施基线。 @@ -55,7 +56,12 @@ NEX 示例值、NexDocus 参数、示例截图和示例组件名都不是项目 11. **可访问性是质量底线。** 自定义交互必须支持键盘、可见焦点和可访问名称;拖拽操作必须提供非拖拽替代路径。 12. **滚动和尺寸必须基于实际布局。** 对嵌套 Flex/Grid 工作区检查 `min-width: 0`、`min-height: 0`、滚动容器归属和溢出,不要机械添加固定尺寸或 `overflow: hidden`。 13. **不滥用局部覆盖。** 不用大量 `!important`、高优先级选择器或深层第三方 DOM 覆盖来修补应由 Token/主题/共享组件解决的问题;需要时说明范围和原因。 -14. **范围受控。** 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。 +14. **响应式断点必须登记。** 新增断点应有语义名称、数值/范围、布局理由、权威来源和边界测试;不得散落增加无法追踪的媒体查询。 +15. **窄屏数据必须可对账。** 隐藏列、卡片化或折叠详情不得导致重要数据无处可见;必须核验字段、记录数、顺序和动作仍可访问。 +16. **图标不得污染可访问名称。** 装饰性图标应从辅助技术名称计算中排除;图标与可见文案组合时避免重复朗读;图标本身不能以内部 glyph 名称充当业务文案。 +17. **真实 AT 验证不得由属性代替。** 对复杂自定义控件、拖拽替代、复合导航和关键数据交互,按目标环境执行屏幕阅读器人工验证;未执行时标记 `MANUAL_QA_REQUIRED`。 +18. **样式层与性能优化必须有证据。** 不为形式一致进行全量 CSS Layer 迁移;不为消除 Bundle 警告盲目调阈值或分包。先提供级联冲突或实际加载数据,再做最小变更。 +19. **范围受控。** 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。 ## 5. 标准工作流 @@ -67,6 +73,7 @@ NEX 示例值、NexDocus 参数、示例截图和示例组件名都不是项目 6. 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。 7. 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。 8. 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。 +9. 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;未执行的 E3 必须标记 `MANUAL_QA_REQUIRED`。 ## 6. 例外记录 diff --git a/AUDIT-SUMMARY.md b/AUDIT-SUMMARY.md index 49613c8..d2dab79 100644 --- a/AUDIT-SUMMARY.md +++ b/AUDIT-SUMMARY.md @@ -178,3 +178,21 @@ NexDocus 已经有可复用的视觉基础和一批成熟的专业工作区组件,问题不是“没有设计”,而是**设计决策分散在 token、Ant Design 主题、共享组件和页面私有 CSS 中,且历史修正尚未沉淀为可验证的统一规则**。 该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。 + + +## 0.1.3 增补:Phase 8.5 实践反馈的规范化处理 + +本版本吸收了一个复杂前端项目的阶段 8.5 响应式 UX 与质量收口经验。仅将可跨项目复用的方法抽象为 NEX 规则: + +- 装饰图标与业务文案的可访问名称分离; +- 截断信息按辅助技术、键盘、设备 Hover 能力和触屏提供完整内容; +- 自定义断点登记并执行边界测试; +- 窄屏数据表格按字段重要性选择呈现方式,并通过数据对账验证信息完整; +- 桌面用户偏好状态与移动端临时交互状态分离; +- 语义/行为检查不止停留在 DOM 形态; +- 真实屏幕阅读器测试与源码/自动化检查分级记录; +- CSS Layer 与 Bundle 优化按真实级联/加载证据决定,不机械重写。 + +### 不纳入 NEX Core 的项目专属事实 + +项目绝对路径、端口、Git 提交哈希、脚本名、组件名、具体断点数值、特定表格数量、特定 chunk 体积、特定问题编号和未完成状态均不构成跨项目规范。N14 真实 AT 测试在来源项目中仍未完成,本版本不作通过声明。 diff --git a/CHANGELOG.md b/CHANGELOG.md index e8f6468..1ea82bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,28 @@ # Changelog +## 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 diff --git a/README.md b/README.md index 470adf6..fb4ebd7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # NEX Design System -**版本:0.1.2** -**版本定位:跨项目适配与规范治理修订版** -**设计来源:NexDocus 参考实现 + 后续项目审计反馈** +**版本:0.1.3** +**版本定位:响应式、可访问性与质量证据治理增强版** +**设计来源:NexDocus 参考实现 + 多项目审计 + NEX Phase 8.5 实践反馈** + +## 0. 快速开始 + +新项目接入请先阅读 [`START-HERE.md`](START-HERE.md),并将 [`templates/new-project-audit-prompt.md`](templates/new-project-audit-prompt.md) 交给 Agent 做只读审计。 ## 1. NEX 是什么 @@ -12,7 +16,20 @@ NEX 的目标不是让所有项目长成同一个样子,而是让不同项目 **核心原则:统一质量与设计语法,不强制统一项目的视觉参数、技术栈、组件 API 或页面骨架。** -## 2. 0.1.2 的关键变化 +## 2. 0.1.3 的关键变化 + +0.1.3 根据多项目实施与 NEX Phase 8.5 实践反馈,进一步强化“规范可适配、规则可验证、验收有证据”的治理要求: + +1. 增加响应式断点登记机制:允许项目在基础断点之外增加有理由的命名断点,并要求测试断点前、断点处和断点后。 +2. 增加窄屏数据表格治理:按信息重要性选择隐藏/详情、卡片、横向滚动、固定列和操作菜单等策略,并通过数据对账确认没有信息丢失。 +3. 强化可访问名称规则:装饰性图标不得混入控件名称;图标与可见文字并列时应避免重复朗读;重要截断信息必须有键盘、触屏和辅助技术可用的完整内容渠道。 +4. 增加真实辅助技术验收分级:源码检查、自动化、键盘验证和真实屏幕阅读器验证是不同证据等级;不能仅凭 ARIA 属性或 DOM 形态宣称读屏验收通过。 +5. 明确导航偏好状态与临时交互状态可以分开管理,例如桌面导航折叠偏好可持久化,移动端 Drawer 打开状态通常不持久化。 +6. 明确 CSS Layer 迁移、样式层叠治理和 Bundle 拆分必须基于实际冲突或性能证据,不得为形式统一进行大规模重写。 +7. 增加语义/行为质量闸、读屏测试记录模板和响应式断点登记模板。 +8. 将单一项目的未完成事项保留为项目级待办;不把未完成或未验证的实现误写成 NEX 已验证能力。 + +### 0.1.2 已有治理原则继续有效 0.1.2 根据真实新项目审计反馈,修正了 0.1.1 中将 NexDocus 现状参数写得过于像通用基线的问题: @@ -63,9 +80,13 @@ NEX Core 不规定所有项目必须使用同一品牌色、Header 高度、Side | `docs/09-agent-execution-rules.md` | Agent 审计、计划、实施、验收工作流 | | `docs/10-adoption-roadmap.md` | 分阶段采用路线 | | `docs/11-project-onboarding.md` | 新项目接入、符合性映射和例外记录 | +| `docs/12-responsive-accessibility-quality.md` | 断点登记、窄屏表格、可访问名称、语义/行为质量闸、真实 AT 验收和性能证据 | | `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` | 中性项目配置模板,不预设某个项目的技术栈和尺寸 | | `config/reference-nexdocus-profile.example.yaml` | NexDocus 历史参考配置,仅供比对 | | `AGENTS.md` | NEX Agent 入口规则 | @@ -91,7 +112,7 @@ project-root/ 接入步骤: -1. 将 ZIP 中 `NEX-Design-System-v0.1.2/` 放入项目 `standards/nex-design-system/`。 +1. 将 ZIP 中 `NEX-Design-System-v0.1.3/` 放入项目 `standards/nex-design-system/`。 2. 不覆盖项目已有的根 `AGENTS.md`;将 NEX 入口规则合并进去,并确保引用路径正确。 3. 从 `config/project-profile.example.yaml` 复制为项目根目录 `nex.config.yaml`,按实际技术栈、规范文件、Token 来源和组件目录填写。 4. 如果项目已有 `docs/UI规范.md` 或类似设计手册,保留为 Project Design Specification 的权威文件,并在配置中登记。 @@ -113,7 +134,13 @@ project-root/ 不允许把 `ADAPTED` 视为“不合规”,也不允许把 `NOT_APPLICABLE` 转化为新建功能的理由。 -## 8. 版本和演进原则 +## 8. 质量证据与验收边界 + +NEX 区分源码审阅、自动化检查、浏览器键盘验证和真实辅助技术验证。自动化通过不等于真实读屏通过;ARIA 属性存在也不等于辅助技术一定按预期播报。涉及复杂自定义控件、拖拽排序、复合导航和数据密集交互时,应根据目标用户环境安排真实 AT 验收。尚未执行的人工验证必须标记为 `MANUAL_QA_REQUIRED`,不得报告为完全验收通过。 + +NEX 也不强制所有项目采用相同的断点、表格响应式方案、CSS Layer 或代码分包策略。项目必须登记自己的设计决定,并用视口边界、数据对账、语义/行为和性能数据验证结果。 + +## 9. 版本和演进原则 - NEX Core 规则的变更应记录在 `CHANGELOG.md`。 - 项目专属参数和组件不应未经验证就上升为 NEX Core。 diff --git a/START-HERE.md b/START-HERE.md new file mode 100644 index 0000000..2e032f7 --- /dev/null +++ b/START-HERE.md @@ -0,0 +1,71 @@ +# NEX 0.1.3 — 新项目接入快速开始 + +## 1. 放置规范包 + +建议目录: + +```text +project-root/ +├── AGENTS.md # 已有则合并,不要覆盖 +├── nex.config.yaml # 从本包 config 模板复制并填写 +├── standards/ +│ └── nex-design-system/ # 解压本规范包内容 +├── docs/ # 项目自己的规范/文档 +└── frontend/ # 实际前端目录(按项目而定) +``` + +将 ZIP 内 `NEX-Design-System-v0.1.3/` 的内容放入 `standards/nex-design-system/`。 + +## 2. 创建项目配置 + +复制: + +`standards/nex-design-system/config/project-profile.example.yaml` + +到项目根目录: + +`nex.config.yaml` + +填写真实信息: +- 技术栈以锁文件、依赖清单和构建配置为准; +- 有项目级 UI 规范时登记其路径; +- 没有规范时,将 `design_spec.path` 设为 `none`,`status` 保持 `needs-audit`; +- Token、组件、断点和质量命令必须填写真实来源,不要保留 `SET_ME`; +- `quality.accessibility` 中按目标用户填写实际支持的辅助技术,不要凭空承诺测试覆盖。 + +## 3. 合并根 AGENTS.md + +不要覆盖项目现有 `AGENTS.md`。合并以下指令,并按实际安装目录调整路径: + +```markdown +## NEX Design System + +本项目采用 NEX Design System 0.1.3 作为跨项目设计治理标准。 +NEX 规范位于 `standards/nex-design-system/`。 +涉及 UI/UX 的任务开始前,必须读取该目录中的 `AGENTS.md`、 +`docs/00-governance-and-adaptation.md`、`docs/08-accessibility-responsive.md`、 +`docs/09-agent-execution-rules.md`、`docs/12-responsive-accessibility-quality.md`, +以及项目根目录 `nex.config.yaml` 和项目级 UI 规范。 +NEX 不覆盖项目已经验证的技术栈、视觉参数、Token、组件和业务交互。 +先审计、建立符合性矩阵、提交实施计划;未经授权不得全量重构或自动进入下一阶段。 +``` + +## 4. 第一次只做审计 + +将 `templates/new-project-audit-prompt.md` 的内容交给 Agent。第一次任务应为只读审计,不修改业务代码。 + +审计至少产出: +1. 实际技术栈和目录结构; +2. 项目 UI/UX 规范现状; +3. Token 单一来源和派生链路; +4. 共享组件与页面模式盘点; +5. 主题、导航、断点和滚动行为; +6. 窄屏表格策略和数据完整性风险(如适用); +7. 键盘、可访问名称、图标语义和辅助技术验证现状; +8. 项目质量命令与视觉回归基线; +9. NEX 符合性矩阵; +10. 分阶段建议和需用户决策的事项。 + +## 5. 审计后再授权实施 + +审计报告不是代码修改授权。先检查 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED`、`NOT_APPLICABLE` 映射,再决定哪些阶段需要执行。 diff --git a/VERSION b/VERSION index d917d3e..b1e80bb 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.2 +0.1.3 diff --git a/config/project-profile.example.yaml b/config/project-profile.example.yaml index 2f97d8b..20f641d 100644 --- a/config/project-profile.example.yaml +++ b/config/project-profile.example.yaml @@ -1,10 +1,10 @@ -# NEX 0.1.2 中性项目配置模板 +# NEX 0.1.3 中性项目配置模板 # 复制到项目根目录为 nex.config.yaml,并根据真实代码/锁文件填写。 # 不要保留 SET_ME 占位值;不要从 reference-nexdocus-profile.example.yaml 盲目复制项目参数。 nex: system: NEX Design System - version: 0.1.2 + version: 0.1.3 compliance: required profile_mode: project-adaptive @@ -77,6 +77,21 @@ requirements: # 不因引入 NEX 而增加重复的 Token、主题或 UI 组件系统。 avoid_duplicate_design_system_layers: true + # 装饰图标不得把内部 glyph 名称混入读屏名称。 + decorative_icons_excluded_from_accessible_name: true + + # 被截断的重要名称/状态必须通过适用的辅助技术、键盘和触屏渠道获得全文。 + truncated_important_text_has_full_access_path: true + + # 响应式表格不得无声丢失重要字段,必须执行数据对账。 + responsive_data_preserves_information: true + + # 自定义断点需要登记并执行边界测试。 + register_custom_breakpoints: true + + # 复杂拖拽/自定义交互必须有非拖拽替代路径。 + require_non_drag_alternative_when_applicable: true + rules: project_spec_precedence: true reference_profiles_are_non_normative: true @@ -90,9 +105,28 @@ rules: require_keyboard_review: true require_drag_alternative_when_applicable: true do_not_invent_quality_commands: true + semantic_probes_check_role_name_state_and_behavior: true + do_not_claim_at_pass_from_aria_attributes_alone: true + css_layer_migration_requires_reproducible_evidence: true + bundle_optimization_requires_measurement: true quality: commands: [] # 填写项目真实存在的命令,例如 dev/build/typecheck/preview route_inventory: SET_ME visual_baseline: SET_ME # 没有则写 none regression_process: SET_ME + + responsive: + breakpoint_registry: standards/nex-design-system/templates/responsive-breakpoint-registry.md + require_boundary_tests: true + table_data_reconciliation: true + + accessibility: + evidence_levels: [E0, E1, E2, E3] + target_assistive_technologies: [] # 按项目用户群填写,例如 NVDA/VoiceOver + manual_at_required_for: [] # 按项目复杂交互填写,例如 drag-sort/custom-grid + at_test_record_template: standards/nex-design-system/templates/assistive-technology-test-record.md + + performance: + budget_source: project-defined + require_before_after_measurement: true diff --git a/config/reference-nexdocus-profile.example.yaml b/config/reference-nexdocus-profile.example.yaml index acf1111..9a050d7 100644 --- a/config/reference-nexdocus-profile.example.yaml +++ b/config/reference-nexdocus-profile.example.yaml @@ -20,7 +20,7 @@ project: frontend: framework: react framework_version: "18" - language: javascript-jsx + language: typescript build_tool: vite ui_library: antd ui_library_version: "5" diff --git a/docs/00-governance-and-adaptation.md b/docs/00-governance-and-adaptation.md index 164d58e..ca236b0 100644 --- a/docs/00-governance-and-adaptation.md +++ b/docs/00-governance-and-adaptation.md @@ -78,7 +78,13 @@ NEX 是跨项目的设计治理框架,不是某个参考产品的像素规范 - `NexAppShell`、`NexPageHeader` 等名称是概念性命名,不要求项目按此命名或重建组件。 - 项目已有的主题管线和组件体系优先保留;NEX 不要求另外建立同义的 Token 层或组件包。 -## 7. 从项目实践反哺 NEX +## 7. 质量证据不可混用 + +源码中存在 ARIA 属性、静态 DOM 探针通过、浏览器键盘操作可用、屏幕阅读器实际播报正确,是不同层级的证据。项目不得将低等级证据描述为高等级验收结论。对于复杂自定义交互和关键用户任务,应明确目标辅助技术组合并保留人工记录;没有完成真实 AT 测试时,必须标记 `MANUAL_QA_REQUIRED`。 + +响应式、表格、Token、CSS 层叠和 Bundle 优化同样应基于项目自己的实际值和可复现证据,不得把参考实现或固定阈值当作通用合规标准。 + +## 8. 从项目实践反哺 NEX 只有满足以下条件的项目经验,才建议提升为 NEX Core: diff --git a/docs/04-layout-system.md b/docs/04-layout-system.md index a5a647b..2372c74 100644 --- a/docs/04-layout-system.md +++ b/docs/04-layout-system.md @@ -78,6 +78,29 @@ NEX 统一的是布局的职责分离、信息层级、响应式和交互质量 - 不应简单缩小桌面布局来冒充移动端体验。 - 避免无意的整页横向滚动;宽表格可按项目设计采用横向滚动或替代呈现。 +## 5.1 命名断点登记与边界测试 + +项目应优先使用已经存在的断点体系。若标准断点无法满足真实内容布局、信息密度或组件最小宽度要求,可以增加项目级命名断点;不应为了减少断点数量而接受明显的内容遮挡、操作挤压或不合理回退。 + +每个扩展断点至少登记: +- 名称和数值/范围(含 min/max 语义); +- 解决的具体布局问题和涉及组件/页面; +- 权威定义位置(例如 Tailwind theme、CSS custom properties、媒体查询注册表或设计 Token); +- 与相邻断点的行为差异; +- 断点前、断点处、断点后的验证视口; +- 负责人/批准记录和复审条件。 + +新增断点必须测试边界两侧,避免只在常见设备预设宽度截图而遗漏临界区间。测试宽度应由实际断点决定,并覆盖项目声明的关键视口。 + +## 5.2 导航状态的生命周期 + +不同导航状态不必合并成一个持久化 Boolean。应按状态语义区分: +- **用户偏好状态**:例如桌面端侧栏折叠/展开,可按产品规范持久化。 +- **临时交互状态**:例如移动端 Drawer 当前是否打开,通常只在当前页面会话中有效,不应因刷新而自动保持打开。 +- **共享导航上下文**:导航项定义、当前路由、选中状态和权限可共享;这不意味着偏好状态与临时状态必须共用同一状态变量。 + +状态持久化策略必须符合用户预期,避免移动端刷新后被意外遮罩,也避免桌面端偏好无故丢失。 + ## 6. 滚动与尺寸约束 - 明确页面主滚动容器和嵌套工作区滚动容器。 diff --git a/docs/05-component-system.md b/docs/05-component-system.md index 7ef46b1..b63dbb3 100644 --- a/docs/05-component-system.md +++ b/docs/05-component-system.md @@ -74,7 +74,10 @@ NEX 不要求所有项目安装或开发一套名为 NEX 的 React 组件库。 ### Feedback / Status - 状态同时具备文本或图标语义,不只靠颜色。 -- 长标签截断时必须提供可访问的完整文本(例如可见 Tooltip、title 或 aria-label,按控件语义选择)。 +- 长标签截断时必须提供可访问的完整文本;Tooltip 只是一个呈现渠道,不得成为键盘或触屏用户获取关键内容的唯一方式。 +- 装饰性图标不得混入控件的可访问名称;图标与可见文本并列时应避免重复朗读。 +- 图标按钮必须有简洁、描述动作的可访问名称;不得把图标库内部名称、字体字形名或 glyph token(例如 `upload`、`down`)拼进用户可读名称。 +- 当文本本身已提供名称时,伴随图标通常应从辅助技术名称计算中隐藏;当图标承载唯一含义时,应为控件提供明确的业务名称。 - 通知、行内提示和页面级错误的使用场景不混淆。 ## 6. 组件变更验收 diff --git a/docs/08-accessibility-responsive.md b/docs/08-accessibility-responsive.md index 6f7057b..09f8313 100644 --- a/docs/08-accessibility-responsive.md +++ b/docs/08-accessibility-responsive.md @@ -1,21 +1,35 @@ # 08. Accessibility & Responsive Quality -## 1. 语义优先 +## 1. 语义优先与可访问名称 -- 触发动作使用原生按钮语义;页面跳转使用链接语义。 -- 避免用可点击 `div` / `span` 模拟按钮或链接,除非有充分理由且完整实现相应 ARIA、键盘和焦点行为。 -- 表单控件应有可访问名称;错误信息应能与对应控件关联。 -- 图标按钮应有可访问名称;装饰图标应避免重复朗读。 +- 触发动作使用原生按钮语义;页面跳转使用链接语义。避免用可点击 `div` / `span` 模拟按钮或链接,除非有充分理由且完整实现相应 ARIA、键盘和焦点行为。 +- 表单控件必须有准确、稳定的可访问名称;错误信息应与对应控件建立程序化关联。 +- 图标按钮必须有描述动作的可访问名称,名称应使用用户熟悉的业务语言。 +- **纯装饰图标必须从辅助技术名称计算中排除。** 对 SVG/图标组件/图标字体等,使用项目适当的机制(例如 `aria-hidden="true"`),并防止图标内部字形名或组件名泄漏到可访问名称。 +- 图标与可见文本并列时,通常由可见文本提供名称,装饰图标不应重复朗读。只有图标本身承载唯一语义时,才为控件提供明确的可访问名称。 +- 不要把 `upload`、`down`、`chevron-right` 等图标库内部名称、字体字形名或代码标识直接拼进用户可读名称。 -## 2. 键盘和焦点 +## 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 顺序应与视觉和任务顺序一致。 +- Tab 顺序应与视觉和任务顺序一致;焦点必须清晰可见。 - Enter / Space 的行为应符合控件语义。 -- 焦点必须清晰可见,不得通过 CSS 全局移除焦点轮廓而不提供替代样式。 +- 不得通过 CSS 全局移除焦点轮廓而不提供替代样式。 - Modal、Drawer、Popover 等浮层应正确管理焦点进入、焦点返回和关闭行为。 +- 自定义快捷键应避开常见浏览器和辅助技术冲突;不能仅通过声明 `aria-keyshortcuts` 就认为用户已获得操作能力或读屏软件一定会播报。 -## 3. 拖拽和复杂指针交互 +## 4. 拖拽和复杂指针交互 任何依赖拖拽完成的核心操作都必须提供非拖拽替代路径,例如: @@ -23,28 +37,81 @@ - 通过键盘命令完成移动、排序或节点连接; - 提供可聚焦的操作控件和明确的状态反馈。 -不能假设 HTML5 Drag and Drop API 自身就提供完整键盘体验。画布、排序列表和流程编辑器尤其需要验证替代路径。 +不能假设 HTML5 Drag and Drop API 自身就提供完整键盘体验。替代路径必须在功能上等价,不能只增加一个没有实际行为的快捷键说明。 -## 4. 状态和文本 +对于复杂排序、画布、流程编辑器和其他自定义复合控件,应在目标屏幕阅读器环境中验证焦点、操作结果、位置播报和取消/恢复行为。无法执行真实 AT 测试时,必须标记 `MANUAL_QA_REQUIRED`,不得宣称完整无障碍验收通过。 -- 状态不能只以颜色表示。 -- 截断后的重要状态、名称和错误信息必须有可访问的完整文本渠道。 -- Tooltip 不能成为键盘/触屏用户获取关键内容的唯一方式;必要时同步提供 `aria-label`、可展开文本或其他访问方式。 -- Loading、Empty、Error、Forbidden、Disabled 等状态使用清晰且可操作的文案。 +## 5. 响应式断点治理 -## 5. 响应式 +- 优先复用项目既有断点和组件库响应式规则。 +- 新增断点必须有真实布局需求,不得只为绕过单页 CSS 问题而临时散落媒体查询。 +- 允许项目定义超出基础断点阶梯的命名断点。每个断点必须在项目断点登记表中记录名称、数值/范围、用途、权威来源、受影响页面/组件和边界测试。 +- 必须测试断点前、断点处和断点后;具体视口由实际断点决定,不强制所有项目使用同一组设备宽度。 +- 不应简单缩小桌面布局来冒充移动端体验。导航、标题、工具栏、表格、表单和多栏工作区应按任务设计变形。 +- 避免无意的整页横向滚动;只有宽数据集、时间线或画布确有需要时,才在明确容器内横向滚动。 -- 使用项目既有断点;新增断点应有布局证据。 -- 验证导航、工具栏、表格、表单、多栏工作区和弹层在目标视口下的可用性。 -- 交互热区应满足目标平台和适用标准;不要只缩小图标而保留过小点击区域。 -- 移动端复杂表格可采用横向滚动、列优先级或卡片替代等策略,具体由项目设计规范决定。 +## 6. 窄屏数据表格治理 -## 6. 动效和偏好 +窄屏下表格不得仅靠扩大外层容器或隐藏任意列来“通过”检查。应先按数据任务识别列的重要性: + +- **Primary:** 识别记录和完成核心任务所必需的字段;不得无说明地隐藏。 +- **Secondary:** 影响判断但非首屏必须的字段;可移入展开详情、次级面板或按需查看区域。 +- **Tertiary:** 辅助、低频或装饰性字段;可在窄屏降级展示,但必须保留合理获取方式。 +- **Actions:** 行级操作;评估是否收纳为操作菜单,避免动作簇挤占数据列。 + +可按表格特点选择: + +1. 保留核心列并将次要信息移入行详情/展开区; +2. 对键值型或对象摘要型数据改为卡片/记录列表; +3. 对需要横向比较的密集数据保留局部横向滚动,并提供明确的滚动线索; +4. 对重要标识列使用固定列,但必须检查窄屏剩余可视宽度; +5. 将多个行内动作合并为菜单或次级操作区; +6. 对长文本使用合理换行、截断加完整内容通道或详情查看。 + +每个表格必须单独选择策略。保留语义化表格时,应检查表头关联、行列阅读顺序、排序/选择状态和滚动容器;卡片化时,应保证每条记录的字段标签、值和操作关系仍然清楚。 + +### 6.1 数据对账(必须) + +响应式改造后必须进行数据对账,不能只看截图或 `tableaudit` 是否通过: + +- 使用同一组代表性数据对比宽屏和窄屏视图; +- 核对记录数量、关键字段值、字段与记录对应关系、排序/筛选结果; +- 对隐藏或折叠字段确认存在可达的完整查看路径; +- 核对每行操作是否仍可访问且操作对象正确; +- 检查长文本、空值、极值、状态标签和权限差异; +- 对屏幕阅读器检查表头/标签、单元格或卡片阅读顺序,避免重复或丢失信息。 + +检查脚本可以辅助发现宽度、溢出和结构问题,但不得因测试规则不适配就放宽规则掩盖数据缺失。 + +## 7. 导航状态生命周期 + +桌面折叠偏好与移动端 Drawer 打开状态通常属于不同状态:前者可持久化,后者是临时交互状态。可以共享路由、导航定义和当前选中项,但不要求共用一个状态变量或持久化策略。刷新页面后移动端抽屉通常应关闭。 + +## 8. CSS 层叠与性能优化的边界 + +- NEX 不强制项目使用 CSS Cascade Layers,也不要求将所有自绘样式迁入某个 `@layer`。 +- 对未分层样式、utility class 和媒体查询之间的优先级,应先记录实际层叠模型。只有存在可复现的冲突、回归或维护成本时,才做针对性治理;不得为形式统一进行全量迁移。 +- Bundle 或 CSS Chunk 体积应结合初始加载路径、路由、压缩后大小、缓存和实际性能预算评估。 +- 不得仅为消除构建警告而提高阈值;也不得在没有依赖分析和加载证据时盲目配置分包。 +- 优先识别可延迟加载的路由/模块,并比较优化前后的初始资源和实际行为。 + +## 9. 动效和偏好 - 尊重 `prefers-reduced-motion` 或目标平台等效设置。 - 避免闪烁、持续运动和不必要的空间位移。 - 动效不应造成焦点丢失、滚动位置跳变或操作延迟。 -## 7. 建议验收 +## 10. 建议验收 -至少覆盖:键盘路径、可见焦点、图标名称、状态文本、拖拽替代操作、窄屏关键操作、文本溢出和减少动态效果设置。根据项目范围和技术能力选择自动化与人工检查方式。 +至少按项目适用性覆盖: +- 交互语义、可访问名称和装饰图标是否被正确隐藏; +- 键盘路径和可见焦点; +- 截断内容的辅助技术、键盘、Hover 能力和触屏渠道; +- 拖拽替代路径和关键复合控件的真实 AT 验证; +- 自定义断点登记及断点边界; +- 窄屏表格的数据对账和屏幕阅读器阅读顺序; +- 导航状态持久化行为; +- CSS Layer/Bundle 优化的实际证据; +- 减少动态效果设置。 + +自动化检查、浏览器键盘检查和真实屏幕阅读器检查必须分别记录,不得相互替代。 \ No newline at end of file diff --git a/docs/09-agent-execution-rules.md b/docs/09-agent-execution-rules.md index 61efcdd..61e423c 100644 --- a/docs/09-agent-execution-rules.md +++ b/docs/09-agent-execution-rules.md @@ -50,7 +50,22 @@ Agent 不应在每次任务中重新发明项目设计。它应先理解项目 - 比较基线时区分既有问题、此次引入问题和环境差异。 - 对主题、键盘、拖拽替代路径、状态文本、滚动和溢出进行适用性检查。 -## 6. Report:交付报告 +## 6. 证据等级与不可夸大原则 + +按实际执行情况分别记录以下证据,不得跨级推断: + +| 等级 | 证据类型 | 可以证明 | 不能单独证明 | +|---|---|---|---| +| E0 | 源码/配置审阅 | 代码中存在预期结构或属性 | 浏览器实际行为、读屏播报 | +| E1 | 静态/自动化闸 | 已覆盖规则的自动化条件通过 | 未覆盖的语义、键盘和真实 AT 表现 | +| E2 | 浏览器人工键盘/指针验证 | 目标浏览器中的操作路径和焦点行为 | 屏幕阅读器实际播报 | +| E3 | 真实辅助技术验证 | 指定 OS、浏览器、屏幕阅读器组合中的实际结果 | 未测试的其他环境组合 | + +对拖拽替代、复杂自定义控件、复合导航和关键数据表格,应根据目标用户环境安排 E3 验证。未执行的项目标记 `MANUAL_QA_REQUIRED`,不能因存在 `aria-label`、`aria-keyshortcuts` 或自动化通过而报告完整读屏验收。 + +语义质量闸应尽可能检查角色、可访问名称、状态、键盘行为和实际反馈,而不仅是 DOM 标签或属性字符串。自动化无法可靠判断的部分应转人工验收。 + +## 7. Report:交付报告 至少汇报: 1. 修改摘要和文件清单; @@ -59,9 +74,10 @@ Agent 不应在每次任务中重新发明项目设计。它应先理解项目 4. 交互和视觉变化; 5. 实际运行的命令及结果; 6. 受影响的路由、主题、视口和截图; -7. 未解决问题、风险和下一阶段建议。 +7. 未解决问题、风险和下一阶段建议; +8. 自动化、键盘和真实 AT 证据等级及未执行项目。 -## 7. 分阶段控制 +## 8. 分阶段控制 建议按以下阶段推进,但项目可根据实际问题裁剪: diff --git a/docs/12-responsive-accessibility-quality.md b/docs/12-responsive-accessibility-quality.md new file mode 100644 index 0000000..dc0c284 --- /dev/null +++ b/docs/12-responsive-accessibility-quality.md @@ -0,0 +1,160 @@ +# 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. 质量证据等级 + +| 等级 | 名称 | 最低证据 | 可报告结论 | +|---|---|---|---| +| E0 | Source Reviewed | 源码、配置和实现路径审阅 | 实现中存在预期代码/属性 | +| E1 | Automated Checked | 实际运行的静态/自动化闸及输出 | 已覆盖的自动化规则通过 | +| E2 | Browser Interaction Verified | 指定浏览器中键盘/指针人工操作 | 该浏览器中的交互路径可用 | +| E3 | Assistive Technology Verified | 指定 OS + 浏览器 + 屏幕阅读器的实际操作与播报记录 | 该测试组合中的 AT 体验通过 | + +不同证据等级不能相互替代。`aria-label` 或 `aria-keyshortcuts` 存在,不等于 E3。若因设备或环境不足无法完成 E3,必须标记 `MANUAL_QA_REQUIRED`,并记录测试矩阵、未验证风险和负责人/后续安排。 + +## 10. 建议需要真实 AT 验证的场景 + +按产品支持范围和风险至少评估: +- 自定义拖拽、排序和画布操作; +- 复合导航、菜单、Tabs 和状态切换; +- 具有复杂行列关系的数据表格; +- 需要 Live Region 播报的异步任务; +- 关键业务流程中的自定义控件。 + +不要求每个简单静态页面在所有读屏软件上做全量矩阵,但不能对高风险自定义交互仅凭自动化属性检查宣称 AT 通过。 + +## 11. 报告要求 + +每次相关改造至少记录: +- 规则/组件/页面; +- 目标平台和视口; +- 测试数据集与数据对账结果; +- 检查等级 E0–E3; +- 工具/浏览器/OS/屏幕阅读器版本; +- 实际观察到的焦点、名称、状态和播报; +- 未完成项、风险和后续复核条件。 diff --git a/templates/assistive-technology-test-record.md b/templates/assistive-technology-test-record.md new file mode 100644 index 0000000..a004116 --- /dev/null +++ b/templates/assistive-technology-test-record.md @@ -0,0 +1,45 @@ +# Assistive Technology Test Record + +## 1. Test Context +- Project / version: +- Feature / component: +- User task: +- Risk level: +- Test date: +- Tester: + +## 2. Environment +- OS and version: +- Browser and version: +- Screen reader / assistive technology and version: +- Input method (keyboard / touch / switch / voice): +- Viewport / zoom: + +## 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 | +|---|---|---|---|---|---| +| | | | | | | + +## 5. Evidence Level +- [ ] E0 Source Reviewed +- [ ] E1 Automated Checked +- [ ] E2 Browser Interaction Verified +- [ ] E3 Assistive Technology Verified + +## 6. Issues / Follow-up +| Issue | Severity | Workaround | Owner | Status | +|---|---|---|---|---| +| | | | | | + +**Final status:** PASS / PARTIAL / FAIL / MANUAL_QA_REQUIRED / NOT_TESTED + +Do not mark E3 or final AT pass unless the named environment was actually used and observed. diff --git a/templates/new-project-audit-prompt.md b/templates/new-project-audit-prompt.md new file mode 100644 index 0000000..09fd33c --- /dev/null +++ b/templates/new-project-audit-prompt.md @@ -0,0 +1,70 @@ +# 新项目 NEX 接入:只读审计任务 + +本项目采用 NEX Design System 0.1.3。请先阅读: + +- `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` +- 项目根目录 `nex.config.yaml`(如存在) +- 项目已有 UI/UX 规范(如存在) + +## 任务目标 + +对当前项目进行 NEX 适配审计,判断现有设计、组件和交互如何满足 NEX Core,并识别真实缺陷和规范冲突,为后续实施制定计划。 + +## 审计内容 + +1. 以 package/lock/build 配置确认真实技术栈,不根据 README 单独推断。 +2. 找出项目级 UI/UX 规范、设计决策和权威性。 +3. 追踪 Token 单一事实来源、主题适配器和派生消费者。 +4. 盘点基础、表单、布局、复合和业务共享组件,识别等价能力。 +5. 识别 Shell、导航模型、持久偏好状态和临时 UI 状态。 +6. 盘点响应式断点及其权威来源;标记未登记的局部断点。 +7. 对数据表格评估窄屏策略、列优先级、行内动作和数据完整性。 +8. 检查交互语义、可访问名称、装饰图标、键盘、焦点、截断文本和拖拽替代路径。 +9. 区分源码审阅、自动化、浏览器键盘检查和真实屏幕阅读器验证证据;未执行真实 AT 时不得宣称读屏通过。 +10. 盘点 CSS Layer/级联模型、Bundle/CSS 体积和现有性能预算;不得只凭警告数字判定缺陷。 +11. 找出现有 dev/build/typecheck/test/lint/视觉/可访问性脚本,只记录真实存在的命令。 +12. 识别不存在的页面和工作区并标记 `NOT_APPLICABLE`,不得为了满足规范新增功能。 + +## 符合性状态 + +每项使用: +- `COMPLIANT`:已符合; +- `ADOPTED`:项目决定采用 NEX 建议; +- `ADAPTED`:现有成熟方式达到相同目标; +- `DEFERRED`:暂缓并记录原因/风险/复审条件; +- `NOT_APPLICABLE`:项目不存在该场景。 + +## 禁止事项 + +- 不修改业务代码、CSS、配置或依赖; +- 不升级/替换技术栈或 UI 组件库; +- 不创建 NEX 同名组件包或重复 Token 层; +- 不把参考项目的颜色、尺寸、断点和组件名称当成本项目默认值; +- 不自动修复审计过程中发现的问题; +- 不将审计报告视为后续开发授权。 + +## 交付物 + +1. 项目现状和技术栈报告; +2. 项目级规范权威性判断; +3. NEX 符合性矩阵; +4. Token/主题/组件/页面模式映射; +5. 真实缺陷清单(位置、严重程度、证据、影响); +6. 响应式断点登记建议; +7. 窄屏表格策略及数据对账计划(如适用); +8. 可访问性证据等级和需要真实 AT 验证的项目; +9. 质量门禁与视觉基线清单; +10. 分阶段改进计划、风险、回滚建议和需要用户决策的事项。 + +本轮完成审计后停止,等待用户批准具体实施范围。 diff --git a/templates/project-conformance-matrix.md b/templates/project-conformance-matrix.md index ebaae26..cab4222 100644 --- a/templates/project-conformance-matrix.md +++ b/templates/project-conformance-matrix.md @@ -2,7 +2,7 @@ **项目:** **审计日期:** -**NEX 版本:** 0.1.2 +**NEX 版本:** 0.1.3 **项目级规范:** **审计范围:** @@ -14,11 +14,14 @@ | Token 权威来源 | | | | | | | 主题映射与派生链路 | | | | | | | 布局与导航 | | | | | | -| 响应式断点 | | | | | | +| 响应式断点登记与边界测试 | | | | | | +| 窄屏表格数据完整性对账 | | | | | | | 共享组件资产 | | | | | | | 主要交互模式 | | | | | | | Loading / Empty / Error 等状态 | | | | | | | 键盘与焦点 | | | | | | +| 图标与可访问名称 | | | | | | +| 真实辅助技术验证证据等级 | | | | | | | 拖拽替代路径(如适用) | | | | | | | 自动化质量门禁 | | | | | | | 视觉回归基线 | | | | | | diff --git a/templates/responsive-breakpoint-registry.md b/templates/responsive-breakpoint-registry.md new file mode 100644 index 0000000..44824d9 --- /dev/null +++ b/templates/responsive-breakpoint-registry.md @@ -0,0 +1,22 @@ +# Responsive Breakpoint Registry + +**Project:** +**Source of truth:** +**Owner:** +**Last reviewed:** + +| Name | Condition / CSS value | Layout problem / rationale | Affected pages/components | Authoritative definition | Before / at / after test widths | Evidence | Status / review condition | +|---|---|---|---|---|---|---|---| +| | | | | | | | | + +## Boundary Test Record + +| Breakpoint | Width before | Width at | Width after | Expected behavior | Actual result | Screenshot / test reference | Pass | +|---|---:|---:|---:|---|---|---|---| +| | | | | | | | | + +## Exceptions + +| Local exception | Reason | Why existing breakpoints are insufficient | Scope | Approval | Revisit condition | +|---|---|---|---|---|---| +| | | | | | | diff --git a/templates/ui-acceptance-checklist.md b/templates/ui-acceptance-checklist.md index 056cf01..22df549 100644 --- a/templates/ui-acceptance-checklist.md +++ b/templates/ui-acceptance-checklist.md @@ -24,6 +24,8 @@ ## Layout & Responsive - [ ] 使用项目已有 Shell / 页面模式,或记录例外 +- [ ] 项目新增断点已登记,断点前/处/后已验证 +- [ ] 窄屏表格的数据字段/记录数/动作已对账 - [ ] 没有意外的整页横向滚动 - [ ] 工作区滚动容器明确 - [ ] 长文本/长文件名不会撑破布局 @@ -32,10 +34,12 @@ ## Accessibility - [ ] 交互元素使用适当语义 - [ ] 键盘可达且焦点可见 -- [ ] 图标按钮具有可访问名称 +- [ ] 图标按钮具有准确的可访问名称 +- [ ] 装饰性图标不会被重复朗读或暴露内部 glyph 名称 - [ ] 状态不只依赖颜色 - [ ] 截断的重要信息有可访问的完整文本 - [ ] 拖拽操作有非拖拽替代路径(如适用) +- [ ] 复杂交互已记录 E0–E3 证据等级;未执行真实 AT 时标记 MANUAL_QA_REQUIRED - [ ] 已尊重 reduced-motion ## Theme @@ -47,4 +51,5 @@ - [ ] 未引入不必要重复 Token、主题或组件层 - [ ] 项目真实可执行的质量门禁已运行 - [ ] 视觉回归范围与本次改动影响面匹配 +- [ ] Bundle/CSS 性能结论有测量数据,不只依据构建警告 - [ ] 规范偏离、无法执行的检查和遗留问题已明确记录