nex_design_system/README.md

7.5 KiB
Raw Blame History

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 现状参数写得过于像通用基线的问题:

  1. 明确三层关系:NEX Core、Project Design Specification、Project Implementation。
  2. 建立规范优先级和冲突处理规则。项目级规范负责具体视觉/布局实现;NEX Core 负责跨项目通用质量底线。
  3. 将 NexDocus 审计和参数降级为参考实现资料,不再作为新项目默认值。
  4. 将通用 project-profile.example.yaml 改为中性模板;原 NexDocus 参数另存为 reference-nexdocus-profile.example.yaml。
  5. 增加项目符合性状态:COMPLIANT、ADOPTED、ADAPTED、DEFERRED、NOT_APPLICABLE。
  6. 明确优先复用项目已有 Token、主题管线、组件和页面模式,不强制新增 --nex-* 变量层或 NEX React 组件包。
  7. 明确先审计、做差异映射、确认实施范围,再修改代码;禁止将参考项目的技术栈和尺寸机械套用到其他项目。
  8. 增加键盘可访问性与拖拽操作替代路径等规则,并强化分阶段验收和变更边界。

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. 规范优先级与冲突处理

按以下顺序处理:

  1. 安全、法律、隐私和无障碍的适用底线不得被项目偏好或历史实现绕过。
  2. NEX Core 中标记为 MUST 的跨项目要求必须满足;项目可以选择不同实现方式,但不能取消要求本身。
  3. 项目级设计规范决定本项目的具体设计值、技术栈、组件接口、页面模式和业务交互路径。
  4. 已验证的项目实现可作为项目规范的证据和实现基线;如果实现与规范不一致,必须先审计并记录,不得自动假定代码或文档哪一方正确。
  5. 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/

接入步骤:

  1. 将 ZIP 中 NEX-Design-System-v0.1.2/ 放入项目 standards/nex-design-system/。
  2. 不覆盖项目已有的根 AGENTS.md;将 NEX 入口规则合并进去,并确保引用路径正确。
  3. 从 config/project-profile.example.yaml 复制为项目根目录 nex.config.yaml,按实际技术栈、规范文件、Token 来源和组件目录填写。
  4. 如果项目已有 docs/UI规范.md 或类似设计手册,保留为 Project Design Specification 的权威文件,并在配置中登记。
  5. 先执行只读审计,形成符合性映射,再批准具体实施阶段。不要直接要求 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 的自由发挥空间,但不应抹平项目差异;应约束质量底线,而非强制复制某一个项目的实现。