来源：https://ui.docs.xihanfun.com/design/

# 设计体系

XiHan.UI 的设计不是一套画好的稿子，而是一组写进代码、由门禁守着的规则：组件行为住在框架无关的 Headless 层，颜色、间距、圆角、阴影、动效全部是 DTCG 令牌，皮肤只消费语义令牌与部件角色。Vue、React 与 Web Components 三个适配器画出来的是同一份 CSS。这一册讲的是这些规则本身——为什么是 4 / 8 / 12 三档圆角、为什么只有 Button 缺省品牌实心、字段为什么不填底、明暗两套主题怎么从同一批语义令牌翻出来。

## 这一册收什么

| 页 | 讲什么 |
| --- | --- |
| [设计原则](/design/principles) | 行为归属、一个部件一个身份、边界只由描边承担、颜色只走令牌、缺省克制——所有页面共同遵守的几条 |
| [色彩](/design/colors) | OKLCH 色彩模型、十二色相基础色板、中性色板、品牌色派生、功能色、语义角色、语气轴与对比度判据 |
| [布局](/design/layout) | 4px 网格与间距阶梯、控件高度与密度、字段缺省宽、断点、布局组件与表单排布 |
| [字体](/design/typography) | 字族、字号阶梯、字重、行高与排版角色 |
| [图标](/design/icons) | 首方图标集、控件内图标随尺寸档、兜底字形、换用第三方图标集 |
| [形状与边界](/design/shape) | 圆角三档与身份表、描边宽度、边界三选一、控件盒不填底 |
| [阴影与材质](/design/shadow) | 海拔角色、四档材质配方、磨砂面的使用范围、深色档的投影 |
| [暗黑模式](/design/dark) | 明暗与其余六条环境轴、语义令牌怎么翻、高对比、强制色与打印 |
| [动效](/design/motion) | 时长与缓动、按压触感时间线、浮层进出场、减弱动效 |
| [组件家族与模式](/design/patterns) | 六个家族的边界、七个组件分类怎么选、示例与总览的写法 |

## 三条底线

**一份真源。** 设计规则的真源是仓库里的 [`component-design.md`](https://github.com/XiHanFun/XiHan.UI/blob/dev/.agents/skills/component-design/references/component-design.md)，这一册是它的面向读者的版本；两者冲突时以真源为准，改规则先改真源。

**规则可验证。** 每条视觉规则都对应一张门禁（`pnpm gate`）：圆角只能取语义档、描边宽度只能走令牌、根面边界只能取描边 / 淡底 / 无壳之一、控件高度锚在控件尺度令牌上、字段缺省宽走 `--xh-control-w`。写进文档却没有门禁的规则，会被当成待补的欠账而不是例外。

**环境轴一起审。** 亮色、暗色、comfortable / compact 两档密度、RTL、粗指针、减弱动效、减少透明度、强制色与打印是同一份皮肤的九个切面，任何一条视觉决定都要在这九个切面下成立，文档里的每张表也按这个口径写。

## 与指南一册的关系

[指南](/guide/anatomy)讲怎么用：令牌怎么引入、皮肤怎么覆盖、主题控制器怎么接、图标集怎么转换。这一册讲为什么这样定。两册互相链接，实现细节不在这里重复。