|
|
||
|---|---|---|
| .workbuddy/memory | ||
| config | ||
| docs | ||
| templates | ||
| AGENTS.md | ||
| AUDIT-SUMMARY.md | ||
| CHANGELOG.md | ||
| README.md | ||
| VERSION | ||
README.md
NEX Design System
版本:0.1.2
版本定位:跨项目适配与规范治理修订版
设计来源:NexDocus 参考实现 + 后续项目审计反馈
1. NEX 是什么
NEX Design System 是面向 AI Agent 辅助软件开发的跨项目设计治理体系。它覆盖视觉原则、Design Tokens、布局模式、组件契约、交互规则、可访问性、项目适配和 Agent 执行流程。
NEX 的目标不是让所有项目长成同一个样子,而是让不同项目在保留自身成熟设计语言的前提下,拥有一致的设计质量、可理解的规则和可验证的工程约束。
核心原则:统一质量与设计语法,不强制统一项目的视觉参数、技术栈、组件 API 或页面骨架。
2. 0.1.2 的关键变化
0.1.2 根据真实新项目审计反馈,修正了 0.1.1 中将 NexDocus 现状参数写得过于像通用基线的问题:
- 明确三层关系:NEX Core、Project Design Specification、Project Implementation。
- 建立规范优先级和冲突处理规则。项目级规范负责具体视觉/布局实现;NEX Core 负责跨项目通用质量底线。
- 将 NexDocus 审计和参数降级为参考实现资料,不再作为新项目默认值。
- 将通用
project-profile.example.yaml改为中性模板;原 NexDocus 参数另存为reference-nexdocus-profile.example.yaml。 - 增加项目符合性状态:
COMPLIANT、ADOPTED、ADAPTED、DEFERRED、NOT_APPLICABLE。 - 明确优先复用项目已有 Token、主题管线、组件和页面模式,不强制新增
--nex-*变量层或 NEX React 组件包。 - 明确先审计、做差异映射、确认实施范围,再修改代码;禁止将参考项目的技术栈和尺寸机械套用到其他项目。
- 增加键盘可访问性与拖拽操作替代路径等规则,并强化分阶段验收和变更边界。
3. 三层规范模型
| 层级 | 名称 | 职责 | 示例 |
|---|---|---|---|
| L1 | NEX Core | 跨项目的设计质量、可访问性、交互可预期性、Token 治理和 Agent 执行底线 | 不只用颜色表达状态;交互必须键盘可达;不擅自改变技术栈 |
| L2 | Project Design Specification | 项目专属视觉语言、布局尺寸、断点、主题策略、组件接口和业务交互 | docs/UI规范.md、项目设计手册、已批准的设计决策 |
| L3 | Project Implementation | 当前代码中的 Token、主题、共享组件、页面和行为实现 | theme/antd.ts、applyRootVars、@theme、项目组件目录 |
NEX Core 不规定所有项目必须使用同一品牌色、Header 高度、Sider 宽度、控件高度、CSS 技术或组件库。上述内容由项目级规范和经验证的实现确定。
4. 规范优先级与冲突处理
按以下顺序处理:
- 安全、法律、隐私和无障碍的适用底线不得被项目偏好或历史实现绕过。
- NEX Core 中标记为 MUST 的跨项目要求必须满足;项目可以选择不同实现方式,但不能取消要求本身。
- 项目级设计规范决定本项目的具体设计值、技术栈、组件接口、页面模式和业务交互路径。
- 已验证的项目实现可作为项目规范的证据和实现基线;如果实现与规范不一致,必须先审计并记录,不得自动假定代码或文档哪一方正确。
- NEX 参考项目、示例配置和截图只用于解释设计意图,不具备覆盖项目规范的权力。
发生冲突时,Agent 必须记录冲突位置、涉及层级、影响、推荐处理方式和验证方法。不得自行将项目改成参考项目的尺寸、视觉风格或技术栈。
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 |
可访问性、响应式和输入方式替代 |
docs/09-agent-execution-rules.md |
Agent 审计、计划、实施、验收工作流 |
docs/10-adoption-roadmap.md |
分阶段采用路线 |
docs/11-project-onboarding.md |
新项目接入、符合性映射和例外记录 |
templates/page-spec.md |
项目页面规格模板 |
templates/ui-acceptance-checklist.md |
UI/UX 验收清单 |
templates/project-conformance-matrix.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/
│ ├── AGENTS.md
│ ├── docs/
│ ├── config/
│ └── templates/
├── docs/
│ └── UI规范.md # 如项目已有,以其作为项目级规范
└── frontend/
接入步骤:
- 将 ZIP 中
NEX-Design-System-v0.1.2/放入项目standards/nex-design-system/。 - 不覆盖项目已有的根
AGENTS.md;将 NEX 入口规则合并进去,并确保引用路径正确。 - 从
config/project-profile.example.yaml复制为项目根目录nex.config.yaml,按实际技术栈、规范文件、Token 来源和组件目录填写。 - 如果项目已有
docs/UI规范.md或类似设计手册,保留为 Project Design Specification 的权威文件,并在配置中登记。 - 先执行只读审计,形成符合性映射,再批准具体实施阶段。不要直接要求 Agent 全量重构。
不要用 reference-nexdocus-profile.example.yaml 创建其他项目的配置。 它只记录 NexDocus 的历史事实。
7. 符合性状态
项目审计和映射必须使用以下状态:
| 状态 | 含义 | Agent 行为 |
|---|---|---|
COMPLIANT |
已满足 NEX Core 要求 | 保留;如有证据可引用 |
ADOPTED |
项目决定采用 NEX 建议 | 按项目批准范围实施 |
ADAPTED |
采用项目既有成熟做法实现同一原则 | 保留项目实现,记录映射关系和理由 |
DEFERRED |
暂缓处理 | 记录原因、风险和复审条件 |
NOT_APPLICABLE |
项目不存在该功能或场景 | 不引入无关组件/页面/约束 |
不允许把 ADAPTED 视为“不合规”,也不允许把 NOT_APPLICABLE 转化为新建功能的理由。
8. 版本和演进原则
- NEX Core 规则的变更应记录在
CHANGELOG.md。 - 项目专属参数和组件不应未经验证就上升为 NEX Core。
- 从多个项目反复验证、具有普遍价值的规则,才考虑纳入下一版 Core。
- 新项目审计发现的经验先记录为候选改进;不要因单一项目反馈立刻改变所有项目的默认实现。
- 规范、配置、代码实现和检查机制必须保持可追踪的一致关系。
维护目标: NEX 应减少 Agent 的自由发挥空间,但不应抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。