Tokens

组件库的单一事实源是 packages/ui/core/src/styles/tokens.css：纯 :root 自定义属性 + 明暗 / 对比度 / 尺寸维度的重定义块。组件内 var(--ui-*) 不写内联 fallback，全局调整只改这里。

色彩

派生值

跟随 primary / danger 自动换主题，宿主一般不需要单独覆写：

尺寸

控件尺寸标尺（mini / small / medium(默认) / large / super）以 --ui-size-<size>-<维度> 形式集中定义（高度 / 水平内边距 / 字号 / 圆角四维度），组件只消费下面这组 --ui-control-*（默认 medium 档）：

五档标尺值见 tokens.css 的 --ui-size-*；data-size="small" 环境与组件 size prop 共用同一套值。

叠放层级

按用途预分档，组件只引用 token、不写数字。同一档里后打开的在上面（浮层都 portal 到 body，按 DOM 顺序叠），所以可交互的层共用一档：对话框里打开的菜单、菜单里打开的对话框，两个方向的嵌套都对。

用法：class="z-(--ui-z-layer)"。组件内部的局部层级（表格吸顶表头）不走这里。

四维适配

全部通过重定义 token 实现，组件代码零分支。本站「调试面板」可实时切换验证：

• 主题色：全仓默认品牌只在 tokens.css 定义；强调渐变由 --ui-primary → --ui-secondary 自动生成。确有独立品牌的宿主才在 app 级入口覆写主题色、次级色及各自前景色（见开始使用），不在页面级 style 里写。
• 明暗：[data-theme="dark"] 下使用 zinc 基调，并把品牌色收敛为低亮度铜棕 #9b6a48 → #7b482f，避免琥珀铜在暗色背景上过度抢眼；html 标属性即启用。
• 对比度：@media (prefers-contrast: more) 下加深边框，并把 --ui-fg-subtle 与 --ui-fg-muted 并成同一档——本体是媒体查询，不占 html 属性；本站调试面板以 data-contrast="more" 强制预览同一组值。默认档（不开高对比）本身就要达标：四档文字在 --ui-bg / --ui-surface / --ui-surface-muted 上都过 WCAG AA 的 4.5:1，由 scripts/gate/ui-token-contrast.test.mts 钉住。
• 尺寸：[data-size="small"]（全局紧凑）切换控件尺寸组；组件 size prop 做实例级覆盖（mini / small / medium / large / super）。

换色

画大面积色块的组件都接 color，换色逻辑全库只有 colorVariables 一份：主色实底与渐变按钮（XButton）、开关（XSwitch）、勾选（XCheckbox / XRadioGroup）、滑条（XSlider）、进度（XProgress）、工具组配方的选中块（XSegmented / XToggle / XToggleGroup）。

• 取值：primary（缺省，沿用宿主主色）/ danger / success / warning / info 换成对应语义 token，跟着明暗档走；十六进制走品牌色算法（与 useBrandColor 同一套：前景按对比度选、副色降一档），明暗共用。其余 CSS 写法不认、不改写：前景色要在服务端也算得出来。
• 改写的是组件根上的一族变量：--ui-primary / -fg / --ui-secondary / -fg，外加渐变、焦点环、主色阴影这几个派生值（PRIMARY_DERIVED_VARIABLES）。自定义属性在声明它的元素上求值，:root 上的派生值已按根的主色算好，子树里只改 --ui-primary 它们不跟着变，所以在同一处重新声明。组件内部照旧只画 --ui-primary 一族，没有 color === 'danger' 这类分支。
• 工具组配方的项缺省灰底（主色留给导航与主按钮），给了 color（含 primary）才换成该颜色的主色版。
• 小面积的强调（徽标 XBadge 的语义档、链接色、焦点描边）不在此列：它们是语义档位本身，不是「同一块换个颜色」。

宿主自写有主色实底的组件时同样继承 ColorProps、根上绑 colorVariables(color)：

<script setup lang="ts">
import { colorVariables, type ColorProps } from '@xwink/ui'

const props = defineProps<ColorProps>()
</script>

<template>
  <span :style="colorVariables(props.color)" class="bg-(--ui-primary) text-(--ui-primary-fg)">
    <slot />
  </span>
</template>

状态过渡

悬停、按下、选中、聚焦、展开这类状态变化全库用一个默认 TRANSITION（ui-transition duration-150 ease-out）。ui-transition 是 tailwind.css 里的 @utility：过渡颜色类、透明度、阴影、位移与滤镜；减弱动效只留颜色类——这个偏好针对的是运动，变色不晃也不移，全关反而让切换生硬。150ms ease-out 是跟手与看得出过渡之间的取值。

• 不写 Tailwind 的 transition-* 原子类：它们都写 transition-property，后写的整串替换前面的，叠在默认上不是追加而是互相覆盖（经 cn() 时 twMerge 也只留最后一个）。要多过渡的属性追加进变量：cn(TRANSITION, '[--ui-transition-extra:width]')，多个用逗号。
• 时长、缓动只写各自的属性，经 cn() 后写的赢：duration-300、按下更跟手的 active:duration-75。
• 入场、呼吸这类展示动效是关键帧，不走它。

消费方式

组件用 Tailwind 箭头变量原子类直接引用 token——刻意不用包级 @theme 注册，layer 归属永远跟宿主 utilities 走：

<div class="bg-(--ui-surface) text-(--ui-fg) border border-(--ui-border)">
  <span class="text-(--ui-fg-muted)">次要文字</span>
</div>

宿主写自己的样式时照同样方式引用，四维适配自动继承。