主题定制

@tripo3d/design 的所有颜色、尺寸均由 CSS 变量 驱动。你可以在三个层级覆写主题:

1. 全局 — 在应用根节点上覆写 CSS 变量,影响所有组件实例
2. 局部 — 通过 UnoCSS 工具类(如 btn-bg-yellow-1)覆写单个实例
3. 内联 — 用 :style 直接写 CSS 变量,不依赖 UnoCSS

按钮主题色

Button / AnimateButton / CreditsButton 均共享一套 --btn-* CSS 变量。

CSS 变量	默认值	说明
--btn-bg-color	—	default 变体的背景色
--btn-text-color	—	default 变体的文字色
--btn-border-color	—	border 变体的边框色/文字色
--btn-hover-shadow-color	—	hover 发光颜色
--btn-glow-color	—	AnimateButton 的光晕颜色
--btn-loading-border-color	—	loading 状态边框色
--btn-loading-from / --btn-loading-via / --btn-loading-to	—	loading 状态的背景渐变
--btn-shimmer-color	—	loading 文字流光颜色
--btn-shimmer-text-base	—	loading 文字基础色

预置工具类

内置的 UnoCSS 规则可直接设置按钮 CSS 变量:

<Button class="btn-bg-yellow-1 btn-text-black">金色</Button>
<Button class="btn-border-purple-1" variant="border">紫色边框</Button>

可用的前缀:btn-bg-、btn-text-、btn-border-、btn-shadow-、btn-glow-。每个前缀支持:

• 预置调色板 key:btn-bg-yellow-1、btn-bg-purple-1
• 任意值语法:btn-bg-[#6366f1]、btn-shadow-[rgba(99,102,241,0.5)]

内联样式覆写

适合调试或组件内不便引用 UnoCSS 的场景:

<Button
  :style="{
    '--btn-bg-color': '#22c55e',
    '--btn-text-color': '#fff',
  }"
>
  绿色按钮
</Button>

全局调色板

设计包预置了一套调色板,可在 UnoCSS 中以类名使用(来自 @tripo3d/design/preset):

色系	代表色 (CSS)	说明
purple-1	rgba(80, 59, 227, 1)	品牌主色,用于 CTA、焦点态
purple-2	rgba(167, 155, 236, 1)	品牌辅助色
blue-1	rgba(89, 111, 255, 1)	链接 / 信息色
blue-2	rgba(28, 161, 241, 1)	信息辅助
green-1	rgba(63, 221, 120, 1)	成功色
yellow-1	rgba(249, 207, 0, 1)	警告色
red / red-15	rgba(255, 62, 62, 1)	危险色 / 15% 透明背景
pink-2	rgba(251, 35, 194, 1)	强调色
gray-1 ~ gray-950	(详见源码)	12 阶中性色系
black-0 ~ black-80 / white-5 ~ white-80	分级透明黑白	常用于遮罩与描边

完整定义见 preset.ts 源码。

暗色/亮色主题

当前组件默认面向暗色背景设计。如需亮色主题,通过 CSS 变量在根节点切换:

/* styles/light.css */
:root {
  --btn-bg-color: #ffffff;
  --btn-text-color: #1c1c1c;
  --btn-border-color: #e5e5e5;
  /* ... */
}

.dark {
  --btn-bg-color: #1c1c1c;
  --btn-text-color: #ffffff;
  /* ... */
}

覆盖 UnoCSS 主题

如果宿主工程需要扩展调色板,在 uno.config.ts 中传入额外 theme:

import { defineConfig } from '@tripo3d/design/config';

export default defineConfig({
  theme: {
    colors: {
      brand: {
        500: '#ff6b35',
      },
    },
  },
});

defineConfig 内部会与 preset 主题做深度 merge。

最佳实践

• 优先用工具类覆写:class="btn-bg-yellow-1" 比内联 style 更易读、被 UnoCSS AOT 编译
• 在组件外壳统一定义品牌色:把核心 CSS 变量写在一次性的 layout / root 元素,避免层层覆盖
• 避免改组件内部 class:首选通过 CSS 变量 / class prop / backgroundClass / wrapperClass 覆写