80 lines
4.7 KiB
Markdown
80 lines
4.7 KiB
Markdown
# NEX Design System
|
||
|
||
**版本:0.1.7 — Lean Design & Agent Development Rules**
|
||
|
||
NEX 的职责只有两项:
|
||
|
||
1. **统一软件产品的设计规范**:视觉语言、Design Tokens、布局、响应式、组件、交互、无障碍和面向用户体验的性能原则。
|
||
2. **约束 AI Agent 的开发行为**:明确技术栈默认值、优先复用项目资产、遵守项目设计规范、控制修改边界,避免擅自换栈和重复造轮子。
|
||
|
||
**NEX 不负责建立或管理测试体系。** 测试覆盖率、自动化测试框架、浏览器回归、屏幕阅读器测试流程、CI 质量闸门、测试报告和测试脚本均不属于 NEX 的规范范围。项目原有的测试实践继续由项目自身工程约定管理,不由 NEX 扩展。
|
||
|
||
## 1. 0.1.7 的定位
|
||
|
||
0.1.7 是一次范围收敛和流程减负版本,不是增加更多治理层。相较 0.1.6:
|
||
|
||
- 删除 E0–E3、AT 平台矩阵和读屏测试记录等测试治理内容。
|
||
- 移除自动化测试、浏览器测试矩阵、报告产出和质量闸门要求。
|
||
- 保留无障碍作为设计与实现要求,不规定屏幕阅读器测试流程。
|
||
- 将响应式与性能放回设计规范,定义界面应如何适配和保持感知性能,不建立测试/预算/度量流程。
|
||
- Agent 默认采用轻量任务模式,按当前任务读取相关规范,不要求每次加载全部文档。
|
||
- 默认不创建阶段报告、审计报告、截图证据目录或自定义检查脚本。
|
||
- 保留新项目明确的默认技术栈;已有项目继续使用其现有技术栈。
|
||
|
||
## 2. NEX 的规范层级
|
||
|
||
| 层级 | 名称 | 职责 |
|
||
|---|---|---|
|
||
| L1 | NEX Core | 跨项目的设计原则和 Agent 开发约束 |
|
||
| L2 | Project Design Specification | 项目自己的品牌、视觉、布局、断点、组件和业务交互规范 |
|
||
| L3 | Project Implementation | 当前项目中的主题、Token、组件和页面代码 |
|
||
|
||
具体视觉参数和业务交互由项目决定。NEX 不把 NexDocus 或任何单一项目的颜色、尺寸、断点、组件 API 当成全局标准。
|
||
|
||
## 3. 快速开始
|
||
|
||
1. 将本目录放在项目 `standards/nex-design-system/`。
|
||
2. 将 `config/project-profile.example.yaml` 复制到项目根目录并命名为 `nex.config.yaml`。默认技术栈已经填写,不需要重新填写一份技术问卷。
|
||
3. 将本包 `AGENTS.md` 的入口规则合并到项目根 `AGENTS.md`,不要覆盖已有项目指令。
|
||
4. 新项目使用默认栈;已有项目保留实际技术栈。
|
||
5. 新项目首次接入时,使用 `templates/project-setup-prompt.md`;日常开发不需要重复执行接入审计。
|
||
|
||
## 4. 文档地图
|
||
|
||
| 文档 | 作用 |
|
||
|---|---|
|
||
| `docs/00-governance.md` | NEX 职责边界、三层规范和优先级 |
|
||
| `docs/01-design-principles.md` | 产品视觉与信息设计原则 |
|
||
| `docs/02-design-tokens-and-theme.md` | Token、主题和单一事实来源 |
|
||
| `docs/03-layout-and-responsive.md` | 布局、导航、响应式设计 |
|
||
| `docs/04-component-system.md` | 组件复用和组件行为契约 |
|
||
| `docs/05-interaction-system.md` | 页面、表单、表格、弹层和状态交互 |
|
||
| `docs/06-accessibility-design.md` | 无障碍设计与实现要求,不包含测试流程 |
|
||
| `docs/07-performance-aware-design.md` | 面向体验的性能设计原则,不包含性能测试或预算体系 |
|
||
| `docs/08-page-patterns.md` | 常见页面与工作区模式 |
|
||
| `docs/09-agent-development-rules.md` | Agent 如何按需读取规范、约束代码修改 |
|
||
| `docs/10-project-stack-defaults.md` | 新项目默认技术栈与已有项目保护 |
|
||
| `docs/11-project-adoption.md` | 一次性项目接入方式 |
|
||
|
||
## 5. 明确不属于 NEX 的内容
|
||
|
||
以下内容由项目自身工程体系决定,不由 NEX 规定或自动生成:
|
||
|
||
- 单元测试、集成测试、端到端测试及覆盖率目标;
|
||
- Playwright、Vitest、Pytest 等测试工具的选型、配置和执行频率;
|
||
- 浏览器路由 × 视口 × 主题的全量测试矩阵;
|
||
- VoiceOver、NVDA、Orca 等屏幕阅读器测试矩阵和证据等级;
|
||
- CI/CD、质量闸门、lint/test 命令和发布验收流程;
|
||
- `reports/` 报告目录、阶段报告和测试证据归档;
|
||
- `scripts/ui/` 自定义质量检查脚本。
|
||
|
||
NEX 仍然规定界面应具备的响应式、无障碍和性能体验,但不规定通过哪些测试来证明它们。
|
||
|
||
## 6. 文件和报告原则
|
||
|
||
- 普通开发结果默认在 Agent 对话中简要汇报,不创建 Markdown 报告。
|
||
- 不为每次功能开发创建阶段编号、审计报告或证据目录。
|
||
- 不新增 NEX 专属测试脚本或质量检查目录。
|
||
- 只有用户明确要求,或确实需要记录长期有效的项目设计决策时,才创建/更新项目文档。
|
||
- 优先更新已有项目规范,不复制出第二份重复规范。
|