Nex 设计规范
 
Go to file
mula.liu b76ec7cdd9 v 0.1.6 2026-11-08 20:31:12 +08:00
.workbuddy/memory v 0.1.2 2026-11-07 15:48:51 +08:00
config v 0.1.6 2026-11-08 20:31:12 +08:00
docs v 0.1.6 2026-11-08 20:31:12 +08:00
templates v 0.1.6 2026-11-08 20:31:12 +08:00
AGENTS.md v 0.1.6 2026-11-08 20:31:12 +08:00
AUDIT-SUMMARY.md v 0.1.6 2026-11-08 20:31:12 +08:00
CHANGELOG.md v 0.1.6 2026-11-08 20:31:12 +08:00
README.md v 0.1.6 2026-11-08 20:31:12 +08:00
START-HERE.md v 0.1.6 2026-11-08 20:31:12 +08:00
VERSION v 0.1.6 2026-11-08 20:31:12 +08:00

README.md

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 的关键变化

跨平台、按风险触发的无障碍验证

  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,说明跨平台选择、风险触发、环境不可用和启停保护规则。

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 规范优先级

  1. 适用的安全、法律、隐私和无障碍底线不得由项目偏好绕过。
  2. NEX Core 的 MUST 要求必须满足,但可用不同技术方式实现。
  3. 项目级规范决定具体设计值、技术栈、组件 API、页面模式和业务交互。
  4. 已验证的项目实现可作为证据;文档与代码冲突时先审计,不得自动假定哪一方正确。
  5. 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/
  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 项目不存在该功能或场景,不应引入无关实现

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 的自由发挥空间,但不抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。