组件设计系统总览
组件设计系统说明业务开发者如何在页面中一致地使用 DirectSurface UI 的主题、颜色、密度、状态和交互模式。它面向组件使用者和界面设计人员，不包含框架组件的实现流程或仓库维护规范。
这套标准不是单个视觉主题，也不是组件使用手册。它回答的是：
- 业务页面应该从哪些 token 选择颜色、尺寸和字体。
- 同一种状态在不同组件里应该如何表达。
- 传统后台管理系统默认应该采用什么信息密度。
- 鼠标、键盘、焦点、popup、拖拽等交互应该遵守什么模式。
- 页面组合如何避免跳动、遮挡、溢出和交互不一致。
标准目录
| 层级 | 文档 | 解决的问题 |
|---|---|---|
| Design Tokens | Design Tokens 标准 | 颜色、字体、间距、圆角、边框、焦点、动效从哪里来。 |
| Color Usage | 颜色使用模式 | 背景、标题、hover、pressed、selected、rail、guide 等具体场景如何选 token。 |
| Information Density | 信息密度标准 | 后台管理系统、工作台、查询维护页和高密表单应如何控制 padding、margin、行高和主内容面积。 |
| Component States | 组件状态标准 | normal、hovered、pressed、focused、selected、disabled、readonly、loading、error 等状态如何定义和组合。 |
| Interaction Patterns | 组件交互模式 | pointer、keyboard、focus、popup、tooltip、drag、context menu 的统一行为。 |
与现有文档的关系
组件设计系统补充现有核心概念文档：
- 主题与状态：解释
ThemeData和状态的基础概念。 - 组件基础状态契约：定义
visible、disabled、readonly的业务语义。 - 绘制与命中测试：解释 RenderObject 的绘制和 hit test 机制。
- 焦点与输入：解释焦点系统和输入路由。
具体组件的参数和行为以组件手册为准；公共 API 和 RenderObject 生命周期以核心概念与 API 参考为准。
适用范围
建议统一遵守：
- 查询、维护、录入、审阅等正式业务页面。
- 多页面工作台、弹窗、浮层和导航区域。
- 需要在多个业务模块保持一致的状态与交互。
- 对主题切换、键盘操作或信息密度有明确要求的页面。
可以按场景裁剪：
- 一次性原型页面可以保持轻量，但进入正式业务前应统一主题、状态和键盘行为。
- 品牌化、登录、营销或特定业务页面可以有独立视觉，但通用控件仍应复用组件 token 和状态契约。
- 业务调试工具可以降低装饰性要求，但不能破坏焦点、禁用、命中测试和布局稳定性。
DirectSurface UI 默认服务传统后台管理系统和桌面式 Web 工作台。除登录、欢迎页、品牌页等明确例外，正式业务页面应优先遵守 信息密度标准，避免把查询维护、表格录入、审计和调试页面做成低密度展示页。
业务页面设计顺序
推荐顺序：
- 明确页面任务：输入、查询、命令、导航、数据维护、浮层或可视化。
- 从组件清单选择公共组件，复用已有 token、状态和交互模式。
- 明确默认密度：后台工作页默认 dense，低频配置或欢迎页才考虑 comfortable。
- 使用布局组件组织页面，不用固定坐标模拟结构布局。
- 接入业务状态、命令、焦点和页面生命周期。
- 验证主题、密度、键盘、窄尺寸和大数据边界。
不要在业务页面中硬编码一套独立的颜色和尺寸。这样会让页面与主题、状态契约和其他业务模块逐渐分离。
页面验收口径
验收业务页面时，优先检查这些问题：
- 页面与组件组合是否复用了已有 token，而不是局部硬编码颜色、圆角和间距。
- 背景、标题、hover、pressed、selected 是否能从颜色使用模式中找到选择依据。
- 间距、行高、padding 和默认页面结构是否符合后台管理系统的信息密度。
- hover、pressed、focused、selected、disabled 是否和同类组件一致。
- 键盘是否能完成核心操作。
- 文字和图标是否在最窄合理尺寸下仍可读，或者有明确降级策略。
- popup、tooltip、context menu、drag overlay 是否使用公共浮层能力。
- 状态变化是否避免不必要的页面布局跳动和全量数据重建。
- 页面是否对空态、加载、错误、禁用和只读状态给出清晰反馈。