nex_design_system/docs/05-component-system.md

97 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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 命名一致而重命名或重构成熟资产。