AionUi 主题语义 Token 权威参考：从变量契约到自定义主题实战-迪斯科星球

AionUi 主题语义 Token 权威参考：从变量契约到自定义主题实战

【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up｜Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi

AionUi 的主题系统围绕一套语义化设计 Token（CSS 自定义属性）构建：界面中的所有颜色都通过var(--token)读取，而不是硬编码值。本文以 docs/theming/tokens.md 的权威清单为主线，结合 default-color-scheme.css、tokenContract.ts、applyTheme.ts 等源码实现，完整给出每类 Token 的明暗取值、用途、覆盖机制与 UnoCSS 桥接方式，并附带可复制的主题编写示例——读完你既能读懂任意 Token 的语义，也能独立编写、调试属于自己的主题。

Token 如何生效：四层作用机制

一个Theme（定义见 packages/desktop/src/common/theme/types.ts）携带appearance（'light' | 'dark'）与两条可选的覆盖通道：结构化的tokens和原始 CSS 转义通道css。Token 最终生效依赖以下四条链路：

基线（Source of truth）：所有 Token 的默认值定义在 packages/desktop/src/renderer/styles/themes/default-color-scheme.css。:root, [data-color-scheme='default']承载亮色值；[data-color-scheme='default'][data-theme='dark']承载暗色值。主题覆盖只是在基线之上叠加，而非替换。
外观切换：激活主题的appearance会写入<html>{ "id": "violet", "name": "Violet", "appearance": "light", "builtin": false, "created_at": 0, "updated_at": 0, "tokens": { "--primary": "#7c3aed", "--bg-1": "#faf5ff", "--text-primary": "#2e1065" } }
分层形态——为明暗分别取值：
```
{ "id": "violet", "name": "Violet", "appearance": "light", "builtin": false, "created_at": 0, "updated_at": 0, "tokens": { "light": { "--primary": "#7c3aed" }, "dark": { "--primary": "#a78bfa" } } }
```
CSS 转义通道——适合字体、背景图、伪元素等结构化 Token 无法表达的场景（会自动追加!important，无需手写）：
```
{ "id": "my-skin", "name": "My Skin", "appearance": "dark", "builtin": false, "created_at": 0, "updated_at": 0, "css": ":root{ --primary: #ff85a2; } body{ font-family: 'Varela Round'; }" }
```
用户在设置 → 外观 → 手动添加中创建的主题永远是 CSS 形态（tokens省略）。终端用户的完整分步操作见 docs/guides/custom-theme.md；该指南还提供了可直接粘贴使用的完整示例 CSS、可覆盖变量清单以及常见排错建议（变量被忽略、对比度不足、暗色异常、主题分享等）。主题系统整体架构与内置主题新增流程可进一步阅读 packages/desktop/src/renderer/styles/themes/README.md，内置主题（Light/Dark）定义在 builtinThemes.ts。
编写主题的最佳实践
1. 优先tokens通道：结构化、经契约校验、可分层；css仅用于契约无法表达的装饰（字体、渐变纹理、伪元素）。
2. 明暗分层必须成对：对appearance-scoped的 Token，尽量同时提供light与dark两套值，避免暗色下借用亮色取值造成对比度问题。
3. 组件内不硬编码颜色：一律使用语义 Token/变量，自定义主题才能全面生效。
4. 保持中性背景：背景色保持中性以维持文字可读性；文字变量应满足 WCAG AA（正文至少 4.5:1）对比度。
5. 理解覆盖优先级：基线（default-color-scheme.css）→theme-tokens（结构化覆盖，特异性对齐基线并后置注入）→theme-decoration（自动!important的 CSS 转义）。后者优先级最高，可覆盖前两者。
【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up｜Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析