主題客製

@lh-ui/react 的設計令牌全部來自 @lh-ui/share/theme，本庫不持有任何令牌副本。客製主題就是覆蓋這些 CSS 自訂屬性。

令牌層級

樣式的優先級從低到高：

1. theme.css —— @lh-ui/share 發布的基礎令牌（--lh-primary-color 等）
2. theme-dark.css —— 暗色變數（與 theme.css 互斥，二選一）
3. LhConfigProvider 的 themeVars —— 掛到包裹元素的級聯變數
4. 元件 themeVars prop —— 掛到元件根元素，覆蓋一切上級

透過 ConfigProvider 客製

最推薦的方式：在應用根部傳入 themeVars，鍵名不帶 --lh- 前綴（內部自動加）：

import { LhConfigProvider } from '@lh-ui/react'

export default function App() {
  return (
    <LhConfigProvider
      themeVars={{
        'primary-color': '#722ed1',
        'bg-color': '#faf9f7',
        'border-radius-base': '6px',
      }}
    >
      <YourApp />
    </LhConfigProvider>
  )
}

變數會渲染為包裹元素上的 style="--lh-primary-color: #722ed1; ..."，向下級聯。

可用令牌

鍵	說明
primary-color	主色
gold-color / vermilion-color / jade-color	國風專屬色（金黃 / 朱砂 / 翡翠）
bg-color / text-color / border-color	中性色
bg-pattern	花紋背景 URL（如 var(--lh-pattern-willow)）
bg-pattern-opacity / bg-pattern-color	花紋透明度與顏色
decoration-color	裝飾色

單元件客製

任何支援主題的元件都能直接收 themeVars，只影響自身：

<LhButton themeVars={{ 'primary-color': '#13c2c2' }}>青色按钮</LhButton>

也可以用 componentTheme 按元件名批次設定（鍵名與家族其他庫通用）：

<LhConfigProvider
  componentTheme={{
    button: { 'primary-color': '#722ed1' },
    input: { 'border-color': '#d9d9d9' },
  }}
>
  <YourApp />
</LhConfigProvider>

優先級：元件自身 props > componentTheme[元件名] > 全域 themeVars。

背景花紋

國風花紋背景預設關閉。透過 patternComponents 白名單開啟，只有白名單中的元件會套用全域花紋：

<LhConfigProvider
  themeVars={{ 'bg-pattern': 'var(--lh-pattern-willow)' }}
  patternComponents={['dialog', 'card']}
>
  <YourApp />
</LhConfigProvider>

元件自身透過 bgPattern prop 傳入的花紋不受白名單限制。

sx 快速版面配置

部分元件支援 sx prop，把常用的版面配置樣式寫成物件（語義同 emotion / MUI 的 sx）：

<LhButton sx={{ marginTop: 2, width: '100%' }} block>
  通栏按钮
</LhButton>

執行時切換

主題切換的本質是改 CSS 變數，因此可以是完全動態的：

import { useState } from 'react'
import { LhConfigProvider } from '@lh-ui/react'

function App() {
  const [primary, setPrimary] = useState('#1677ff')
  return (
    <LhConfigProvider themeVars={{ 'primary-color': primary }}>
      <input type="color" onChange={(e) => setPrimary(e.target.value)} />
      <YourApp />
    </LhConfigProvider>
  )
}

CSS 變數的型別斷言

原始碼裡 style="{ { '--lh-primary-color': x } }" 在 TypeScript 下會報錯（CSSProperties 不含自訂屬性鍵）。本庫用 cssVarsStyle() 工具統一處理鍵名轉換與斷言，元件內部已封裝，使用者層無需關心。