nex_design_system/docs/11-project-onboarding.md

2.4 KiB
Raw Blame History

11. Project Onboarding & Conformance Mapping

1. 接入前收集的事实

Agent 应从仓库获取或向用户确认:

  • 项目类型、主要用户和主要工作任务;
  • 前端框架、语言、UI 库、样式方案、路由和状态管理;
  • 主题模式和主题切换策略;
  • Token 的权威来源及派生消费者;
  • Shell、导航、关键布局尺寸和响应式断点;
  • 共享组件目录、组件入口和页面模式;
  • 项目级 UI/UX 规范、设计稿或设计决策记录;
  • 可执行脚本、自动化测试、视觉基线和发布流程。

以真实代码和锁文件为证据。README 可能过期,不能作为唯一依据。

2. 符合性映射

复制 templates/project-conformance-matrix.md,按 NEX Core 主题逐项记录:

  • NEX 原则/规则;
  • 项目规范对应章节;
  • 实现位置;
  • 当前状态;
  • 证据/测试;
  • 差异和行动建议。

不要将不同设计体系的数字直接比较并判定不合规。例如 Header 64px 与 Header 56px 本身不存在跨项目的合规差异;需要判断尺寸是否符合当前项目任务、规范和真实运行效果。

3. Token 映射

至少记录:

NEX 语义 项目 Token 权威来源 派生链路/消费者 状态
Brand
Text Primary
Surface
Border
Spacing
Typography
Radius
Elevation/Z-index

若项目已有成熟的单向链路,不新增同义 Token 存储。记录其语义对应关系即可。

4. 组件映射

列出 NEX 常见能力与项目已有组件之间的对应关系。允许一项能力对应一个组件,也允许多个组件共同实现;若已有能力覆盖,应标记 ADAPTED 或 COMPLIANT,不必创建 NEX 同名组件。

5. 不适用项

对不存在的功能(例如项目没有 PDF、文档、AI Chat 或流程画布)标记 NOT_APPLICABLE。不得因为 NEX 文档包含了相应模式,就新增该功能或强制创建占位页面。

6. 批准和变更

审计报告中的建议不等于自动授权。对以下内容,需取得明确任务授权:

  • 修改品牌视觉或全局布局;
  • 改变导航或移动端交互;
  • 更换组件库、样式技术或主要架构;
  • 破坏性 API/组件接口调整;
  • 改变业务交互路径或数据语义;
  • 大规模迁移页面或删除历史实现。