main
mula.liu 2026-11-08 15:37:35 +08:00
parent db52fcca17
commit 284ea53072
19 changed files with 645 additions and 45 deletions

View File

@ -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. 例外记录

View File

@ -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 测试在来源项目中仍未完成,本版本不作通过声明。

View File

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

View File

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

71
START-HERE.md 100644
View File

@ -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` 映射,再决定哪些阶段需要执行。

View File

@ -1 +1 @@
0.1.2
0.1.3

View File

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

View File

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

View File

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

View File

@ -78,6 +78,29 @@ NEX 统一的是布局的职责分离、信息层级、响应式和交互质量
- 不应简单缩小桌面布局来冒充移动端体验。
- 避免无意的整页横向滚动;宽表格可按项目设计采用横向滚动或替代呈现。
## 5.1 命名断点登记与边界测试
项目应优先使用已经存在的断点体系。若标准断点无法满足真实内容布局、信息密度或组件最小宽度要求,可以增加项目级命名断点;不应为了减少断点数量而接受明显的内容遮挡、操作挤压或不合理回退。
每个扩展断点至少登记:
- 名称和数值/范围(含 min/max 语义);
- 解决的具体布局问题和涉及组件/页面;
- 权威定义位置(例如 Tailwind theme、CSS custom properties、媒体查询注册表或设计 Token);
- 与相邻断点的行为差异;
- 断点前、断点处、断点后的验证视口;
- 负责人/批准记录和复审条件。
新增断点必须测试边界两侧,避免只在常见设备预设宽度截图而遗漏临界区间。测试宽度应由实际断点决定,并覆盖项目声明的关键视口。
## 5.2 导航状态的生命周期
不同导航状态不必合并成一个持久化 Boolean。应按状态语义区分:
- **用户偏好状态**:例如桌面端侧栏折叠/展开,可按产品规范持久化。
- **临时交互状态**:例如移动端 Drawer 当前是否打开,通常只在当前页面会话中有效,不应因刷新而自动保持打开。
- **共享导航上下文**:导航项定义、当前路由、选中状态和权限可共享;这不意味着偏好状态与临时状态必须共用同一状态变量。
状态持久化策略必须符合用户预期,避免移动端刷新后被意外遮罩,也避免桌面端偏好无故丢失。
## 6. 滚动与尺寸约束
- 明确页面主滚动容器和嵌套工作区滚动容器。

View File

@ -74,7 +74,10 @@ NEX 不要求所有项目安装或开发一套名为 NEX 的 React 组件库。
### Feedback / Status
- 状态同时具备文本或图标语义,不只靠颜色。
- 长标签截断时必须提供可访问的完整文本(例如可见 Tooltip、title 或 aria-label,按控件语义选择)。
- 长标签截断时必须提供可访问的完整文本;Tooltip 只是一个呈现渠道,不得成为键盘或触屏用户获取关键内容的唯一方式。
- 装饰性图标不得混入控件的可访问名称;图标与可见文本并列时应避免重复朗读。
- 图标按钮必须有简洁、描述动作的可访问名称;不得把图标库内部名称、字体字形名或 glyph token(例如 `upload`、`down`)拼进用户可读名称。
- 当文本本身已提供名称时,伴随图标通常应从辅助技术名称计算中隐藏;当图标承载唯一含义时,应为控件提供明确的业务名称。
- 通知、行内提示和页面级错误的使用场景不混淆。
## 6. 组件变更验收

View File

@ -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 优化的实际证据;
- 减少动态效果设置。
自动化检查、浏览器键盘检查和真实屏幕阅读器检查必须分别记录,不得相互替代。

View File

@ -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. 分阶段控制
建议按以下阶段推进,但项目可根据实际问题裁剪:

View File

@ -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/屏幕阅读器版本;
- 实际观察到的焦点、名称、状态和播报;
- 未完成项、风险和后续复核条件。

View File

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

View File

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

View File

@ -2,7 +2,7 @@
**项目:**
**审计日期:**
**NEX 版本:** 0.1.2
**NEX 版本:** 0.1.3
**项目级规范:**
**审计范围:**
@ -14,11 +14,14 @@
| Token 权威来源 | | | | | |
| 主题映射与派生链路 | | | | | |
| 布局与导航 | | | | | |
| 响应式断点 | | | | | |
| 响应式断点登记与边界测试 | | | | | |
| 窄屏表格数据完整性对账 | | | | | |
| 共享组件资产 | | | | | |
| 主要交互模式 | | | | | |
| Loading / Empty / Error 等状态 | | | | | |
| 键盘与焦点 | | | | | |
| 图标与可访问名称 | | | | | |
| 真实辅助技术验证证据等级 | | | | | |
| 拖拽替代路径(如适用) | | | | | |
| 自动化质量门禁 | | | | | |
| 视觉回归基线 | | | | | |

View File

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

View File

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