nex_design_system/docs/05-component-system.md

4.2 KiB
Raw Blame History

05. Component System & Reuse Contracts

1. 核心原则

NEX 不要求所有项目安装或开发一套名为 NEX 的 React 组件库。项目已有组件体系应优先作为实现载体。NEX 提供的是组件治理、复用判断和行为契约。

2. 先盘点现有组件

修改前检查项目中:

  • 基础 UI 组件;
  • 表单组件和校验封装;
  • 页面级复合组件;
  • 布局/导航组件;
  • 反馈与状态组件;
  • 业务域共享组件;
  • 设计系统/主题包(如有)。

对候选组件记录名称、路径、导出、使用次数、能力、已知限制和适用页面。不要仅根据名字判断是否等价,要核对 Props、状态和实际行为。

3. 组件复用决策

按此顺序判断:

  1. 项目已有组件能满足需求:直接复用。
  2. 已有组件只缺少通用能力:考虑向后兼容地扩展。
  3. 多处存在同一重复模式:抽象为项目级共享组件。
  4. 仅一个页面的特例:先保留局部实现,除非有明确复用价值。
  5. 第三方组件已足够满足需求:可以直接使用,不必机械封装。

不因 NEX 采用某个概念名称就新增 Nex* 组件。如果已有组件叫 PageHead、Ctlbar、DataTable 等,且契约满足要求,就继续使用现有命名。

4. 组件分层(概念模型)

层级 职责 示例
Foundation Token、主题、图标和基础样式 颜色语义、字体尺度、焦点样式
Primitive 基础交互控件 Button、Input、Select、Tooltip
Composite 高频复合组件 页面头部、搜索栏、表格工具栏、指标卡
Pattern 页面/任务模式 列表管理、编辑流程、专业工作区

项目可采用不同目录结构或命名方式。

5. 常见能力合同

以下是能力要求,不是要求必须创建这些组件:

Page Heading

  • 标题、说明、面包屑和主操作层级明确。
  • 小屏下标题和操作不会互相挤压。
  • 强调型 Hero 只在项目设计规范允许的场景使用。

Search / Filter Toolbar

  • 搜索、筛选、重置和应用行为可预测。
  • 已应用筛选条件可见。
  • Enter 搜索、自动搜索或显式提交按项目规范统一。
  • 批量操作仅在存在选中项时展示或启用。

Data Table / List

  • 加载、空数据、错误、无权限和分页状态清晰。
  • 行点击与行内操作不互相吞事件。
  • 选择、排序、筛选和分页行为一致。
  • 长内容、窄屏和键盘导航有可用策略。

Form

  • 必填、校验、错误、提交中和保存结果清晰。
  • 字段标签、帮助文案和错误信息可关联。
  • 取消/关闭时对未保存内容的行为明确。

Modal / Drawer / Overlay

  • 容器选择符合任务复杂度和上下文需要。
  • 焦点进入、焦点返回、Esc 行为和遮罩交互合理。
  • 层级由项目层级体系/组件库管理。

Feedback / Status

  • 状态同时具备文本或图标语义,不只靠颜色。
  • 长标签截断时必须提供可访问的完整文本;Tooltip 只是一个呈现渠道,不得成为键盘或触屏用户获取关键内容的唯一方式。
  • 装饰性图标不得混入控件的可访问名称;图标与可见文本并列时应避免重复朗读。
  • 图标按钮必须有简洁、描述动作的可访问名称;不得把图标库内部名称、字体字形名或 glyph token(例如 upload、down)拼进用户可读名称。
  • 当文本本身已提供名称时,伴随图标通常应从辅助技术名称计算中隐藏;当图标承载唯一含义时,应为控件提供明确的业务名称。
  • 通知、行内提示和页面级错误的使用场景不混淆。

6. 组件变更验收

修改共享组件时,至少检查:

  • 所有已知调用方;
  • 默认值和变体兼容性;
  • Light/Dark(若项目支持);
  • 桌面和窄屏行为;
  • 键盘与可访问性;
  • 空、加载、错误和禁用状态;
  • 视觉回归范围。

7. 参考命名说明

NexPageHeader、NexSearchToolbar、NexDataTable、NexStatCard 等名称只用于表达一类能力,不构成命名要求。若项目已有等价组件,应建立映射并复用,不要为追求 NEX 命名一致而重命名或重构成熟资产。