设计体系

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

这一册收什么

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

三条底线

一份真源。 设计规则的真源是仓库里的 component-design.md，这一册是它的面向读者的版本；两者冲突时以真源为准，改规则先改真源。

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

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

与指南一册的关系

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