s2f/cursor-rules/ui-components-standard.md

UI/UX 与公共组件规范

本规则用于指导 UI/UX 设计、公共组件抽取和组件登记管理。

UI/UX 设计原则

• 禁止使用 emoji 作为 UI 图标。
• 首选专业图标库：Lucide Icons，其次 Feather Icons；Ant Design 项目可使用 Ant Design Icons。
• 禁止使用中文拼音缩写表达业务含义；优先使用英文、中文全称或清晰的领域命名。
• UI 实现应关注一致性、可访问性、响应式布局和错误状态。
• 页面设计应先确定信息架构，再确定视觉样式：导航、页面标题、主操作区、筛选区、内容区、分页区、反馈区。
• 表单必须明确必填、校验、错误提示、提交中、提交成功、提交失败和取消路径。
• 列表和表格必须明确加载、空数据、错误、筛选无结果、分页、排序和批量操作状态。
• 时间、金额、状态、权限、危险操作等高频模式必须统一呈现，不允许每个页面各自发挥。

公共组件抽取原则

• 同一交互或视觉模式在两个及以上页面出现，优先抽取公共组件。
• 即使只出现一次，但包含复杂状态、权限、时间段、分页、筛选、表格联动等逻辑，也应优先抽取为领域组件或组合组件。
• 公共组件 API 应表达业务语义，不暴露页面内部状态细节。
• 公共组件应保持稳定输入输出：value、onChange、loading、disabled、error、empty、pagination 等状态显式建模。
• 不把页面特有文案、接口请求、路由跳转硬塞进基础公共组件；这些应留在页面层或领域组合层。

优先沉淀的组件类型

• 页面布局：PageLayout、PageHeader、ContentCard、ActionBar。
• 查询筛选：FilterBar、SearchInput、TimeRangePicker、DateRangePreset。
• 数据展示：DataTable、Pagination、EmptyState、LoadingState、ErrorState。
• 表单交互：FormField、FormSection、SubmitBar、ConfirmDialog。
• 反馈与状态：StatusBadge、PermissionGate、Toast、ResultPanel。
• 业务高频组件：根据项目领域沉淀，不提前抽象不存在的业务概念。

页面实现顺序

• 先定义页面布局和数据流，再实现页面。
• 先抽取公共组件，再堆页面细节。
• 先覆盖加载、空态、错误、分页和权限状态，再补视觉细节。
• 当组件参数开始膨胀时，优先评估是否应拆成基础组件、领域组件和页面容器三层。

UI 公共组件登记表

• 一旦项目出现可复用 UI 组件，必须创建或更新 pmdocs/ui-components.md。
• pmdocs/ui-components.md 用于记录组件沉淀情况，避免重复造分页、时间段、筛选栏、表格、表单等组件。
• 组件登记表至少包含：组件名、组件类型、适用场景、输入状态、输出事件、使用页面、维护状态。
• 推荐格式：

组件	类型	适用场景	输入状态	输出事件	使用页面	状态
Pagination	基础组件	列表/表格分页	page / pageSize / total	onChange	用户列表、订单列表	稳定
TimeRangePicker	组合组件	时间范围筛选	start / end / preset	onChange	数据看板、订单筛选	稳定
FilterBar	组合组件	列表筛选栏	filters / onFilterChange	onChange / onReset	用户列表、订单列表	稳定
DataTable	基础组件	数据表格	columns / data / loading / pagination	onPageChange / onSort	用户列表、订单列表	稳定

• 公共组件新增、重命名、废弃或职责变化时，必须同步更新组件登记表。
• 组件登记表只记录复用组件，不记录一次性页面局部元素。

组件参数膨胀应对策略

当组件参数超过 10 个，或出现以下情况时，应重新评估组件边界：

• 参数包含页面特定文案、路由、接口请求
• 参数包含复杂业务规则或权限判断
• 参数存在互斥或复杂依赖关系
• 不同使用场景需要不同参数子集

应对策略：

1. 拆成基础组件 + 领域组件 + 页面容器三层
2. 使用组合模式而不是配置模式
3. 使用 Render Props 或 Slots 传递复杂逻辑
4. 使用 Context 或状态管理隔离跨层状态