设计原则

YH-UI 的设计目标是服务真实业务系统：界面应当清晰、稳定、可预测，并且能够在不同团队、不同主题、不同框架环境中保持一致体验。

核心原则

一致性

同类信息使用同类表达，同类操作使用同类反馈。

视觉一致：颜色、圆角、间距、阴影、动效来自统一 Token。
交互一致：按钮、弹层、表单、反馈组件遵循相同的状态模型。
语言一致：文案使用明确动词，避免同一行为出现多套叫法。

可预期

用户在操作前应理解会发生什么，操作后能立即确认结果。

破坏性操作必须清楚标识，并尽量提供二次确认或撤销路径。
表单校验应在用户能修正的位置给出，不把错误只放在页面顶部。
异步操作需要 Loading、禁用态或进度反馈，避免重复提交。

高效

组件默认值应覆盖多数业务场景，让常见任务更快完成。

为表单、表格、弹层、导航提供稳定的默认布局。
支持键盘访问、批量操作、数据驱动配置和插槽扩展。
避免为了展示效果牺牲信息密度，后台/运营类页面优先可扫描性。

可组合

组件应像积木一样独立、可组合、可替换。

单个组件不隐式接管应用状态。
复杂能力通过 props、事件、插槽、组合式 API 暴露。
主题、国际化、尺寸、命名空间通过 ConfigProvider 与 CSS 变量协同。

可访问

可访问性不是发布后的补丁，而是组件行为的一部分。

交互元素必须有可见焦点。
颜色不应作为唯一信息来源。
弹层、下拉、消息、表单控件应保持合理的语义和键盘路径。
动效需要尊重 prefers-reduced-motion。

视觉系统

颜色

颜色分为品牌色、语义色、文本色、边框色、填充色和背景色。

类型	Token 示例	用途
品牌色	`--yh-color-primary`	主按钮、链接、选中态
成功	`--yh-color-success`	成功反馈、完成状态
警告	`--yh-color-warning`	风险提示、待确认状态
危险	`--yh-color-danger`	错误、删除、不可逆操作
信息	`--yh-color-info`	中性说明、辅助信息
文本	`--yh-text-color-*`	标题、正文、次要信息、禁用文本
边框	`--yh-border-color-*`	分割线、输入框、卡片边界

字体

默认字体栈优先使用系统 UI 字体，保证跨平台清晰度和加载性能。

css

--yh-font-family:
  -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans',
  sans-serif;
--yh-font-family-monospace:
  'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, Courier, monospace;

间距

YH-UI 使用 4px 基础栅格。常用间距为 4、8、12、16、20、24、32px。紧凑界面应减少外层留白而不是压缩文字行高。

圆角与阴影

圆角用于表达层级和触感，但不应削弱专业工具界面的信息密度。默认圆角保持克制，卡片和弹层可以使用更高层级阴影，但同一页面不应混用过多阴影等级。

交互原则

状态完整

每个可交互组件都应考虑：

默认态
Hover 态
Active 态
Focus 态
Disabled 态
Loading 态
Error / Warning / Success 态

反馈分层

场景	推荐组件
表单字段错误	`FormItem` 校验信息
一次性轻量反馈	`Message`
系统级通知	`Notification`
需要确认的操作	`MessageBox` / `Popconfirm`
页面级结果	`Result`
区域加载	`Loading` / `Spin`

响应式

移动端不只是缩小桌面布局。表格、筛选、操作栏、弹层在窄屏下应调整信息优先级，避免内容重叠或按钮挤压。

设计验收清单

发布或合并前建议检查：

组件是否支持暗色主题和主要语义色。
键盘能否访问主要交互路径。
长文本、空数据、加载中、错误态是否可读。
弹层是否处理滚动锁定、焦点、关闭路径和层级。
文档 Demo 是否覆盖默认、边界、业务集成三类场景。

设计原则 ​

核心原则 ​

一致性 ​

可预期 ​

高效 ​

可组合 ​

可访问 ​

视觉系统 ​

颜色 ​

字体 ​

间距 ​

圆角与阴影 ​

交互原则 ​

状态完整 ​

反馈分层 ​

响应式 ​

设计验收清单 ​

相关文档 ​