nex_design_system/README.md

4.7 KiB
Raw Blame History

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 专属测试脚本或质量检查目录。
  • 只有用户明确要求,或确实需要记录长期有效的项目设计决策时,才创建/更新项目文档。
  • 优先更新已有项目规范,不复制出第二份重复规范。