主题与定制

三层令牌

所有视觉值收敛在三层结构中，换肤只改中间一层：

L1 原始值        --sr-blue-500: #4f7cff
   ↓
L2 语义令牌      --sr-color-primary: var(--sr-blue-500)     ← 换肤只改这里
   ↓
L3 组件令牌      --sr-btn-bg: var(--sr-color-primary)

组件样式只允许引用 L2 / L3，不得出现裸色值。这条约束保证了「改一处、全站生效」。

切换主题

主题通过根元素的 data-theme 属性控制。未设置时即为亮色，因此首屏无闪烁：

import { useTheme } from '@starriver/ui'

const { theme, mode, setTheme, toggle } = useTheme('auto')

模式	行为
light	固定亮色
dark	固定暗色
auto	跟随系统 prefers-color-scheme，并监听其变化

useTheme 的状态是模块级单例，因此可以在布局、页面、任意组件中重复调用而不会出现状态分歧。

跟随项目自身的主题

如果宿主已有自己的主题机制，直接改属性即可，无需引入 useTheme：

document.documentElement.dataset.theme = 'dark'

定制品牌色

覆盖 L2 语义令牌。在引入组件库样式之后声明：

:root {
  --sr-color-primary: #7c3aed;
  --sr-color-primary-hover: #6d28d9;
  --sr-color-primary-bg: rgba(124, 58, 237, 0.12);
  --sr-gradient-primary: linear-gradient(135deg, #a78bfa 0%, #7c3aed 100%);
}

[data-theme='dark'] {
  --sr-color-primary: #a78bfa;
}

调整玻璃质感

玻璃拟态由四个参数控制，全部是令牌：

:root {
  --sr-glass-bg: rgba(255, 255, 255, 0.55);   /* 半透明底 */
  --sr-glass-border: rgba(255, 255, 255, 0.6); /* 细描边 */
  --sr-glass-blur: 18px;                       /* 模糊半径 */
  --sr-glass-saturate: 1.5;                    /* 饱和度增强 */
}

性能提示

backdrop-filter 在低端设备上开销明显。小屏上同屏玻璃容器过多时，可降低 --sr-glass-blur，或直接用 .sr-card() 配方（实底、无模糊）替代。

页面背景

玻璃效果的前提是背景有内容可透。组件库的 global.less 会为 body 设置 --sr-bg-gradient 渐变背景。

如果宿主已有自己的背景，改为只引入 styles/core.less，就不会覆盖：

import '@starriver/styles/core.less'

--sr-bg-gradient 使用 background-attachment: fixed，滚动时不跟随，玻璃观感才稳定。