nex_design_system/docs/10-adoption-roadmap.md

2.5 KiB
Raw Blame History

10. Adoption Roadmap

1. 采用原则

NEX 采用应从现有项目能力出发,而不是先建立新组件库或全面重写样式。优先解决规范冲突、可复现问题和重复维护成本。

2. 推荐阶段

阶段 工作 常见产物 是否默认改业务代码
0. 规范对齐 审计真实技术栈、项目规范、Token、组件、布局和质量门禁;建立差异矩阵 项目 NEX 适配说明、配置、符合性矩阵 否
1. 明确缺陷 修复可复现且范围明确的 P1 问题 缺陷修复、回归证据 是,限授权范围
2. 可访问性 修复键盘语义、焦点、名称和替代输入路径 交互修复、键盘验收 是,限授权范围
3. 基础治理 Token 映射、主题派生、Z-index、断点等 Token/层级映射和必要修正 视证据和授权而定
4. 共享模式 评估共用组件、复合交互、页面模式 组件契约和兼容计划 视复用价值而定
5. 分模块迁移 在真实业务模块中渐进采用统一模式 页面迁移和回归 是,逐模块
6. 质量门禁 补充构建、交互、视觉、可访问性自动化 CI/脚本/截图基线 是,按项目能力
7. 持续治理 定期审查规范漂移和 Agent 遵循情况 版本更新、审计报告 持续

3. 阶段 0 的完成条件

  • 已读取实际依赖和构建配置。
  • 已找到项目级 UI/UX 规范;没有则明确说明并提出提炼方案。
  • 已定位 Token 权威来源及派生关系。
  • 已盘点现有组件和等价能力。
  • 已记录项目布局、主题、断点和交互基线。
  • 已建立符合性矩阵和冲突清单。
  • 已标记 NOT_APPLICABLE 项,避免引入无关页面/组件。
  • 所有计划实施的差异都有范围和验证方式。

4. 阶段门禁

  • 不因工作量估算而承诺零风险或确定完成时间。
  • 阶段 0 的发现不能自动授权全量修改。
  • 未确认的品牌、布局、导航或交互决策应保留现状并列为待决项。
  • 每个阶段结束时提供 diff、实际测试结果和视觉证据。
  • 未通过回归的阶段不得默认推进下一个阶段。

5. 是否需要独立 NEX 组件库

只有多个项目已验证需要共享同一实现,且现有项目组件无法以轻量方式复用时,才考虑发布独立包。若项目间使用不同 UI 库,可共享设计原则、Token 语义和组件行为契约,而不必强行共享 React 实现。