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