AionUi 主题色迁移指南从硬编码 Hex 到 UnoCSS 语义化原子类与 CSS 变量【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi导读本指南面向 AionUi Desktop 渲染层的前端开发与主题定制者系统讲解如何将组件中硬编码的颜色值如bg-#EFF0F6、text-#1D2129迁移到语义化的 UnoCSS 原子类或 CSS 变量体系。通过本文你可以掌握 AionUi 基于 uno.config.ts 的完整语义色板、明暗双主题的 CSS 变量映射关系以及一套可复制、可验证的四步迁移流程让界面颜色自动跟随明暗主题与用户自定义主题。为什么需要迁移从固定色到主题令牌AionUi 的界面采用统一的主题系统所有颜色最终都由 CSS 自定义属性CSS Variables承载并随data-themelight/dark与data-color-scheme属性切换。如果组件里直接写死十六进制颜色就会出现两类问题明暗主题无法自适应硬编码的浅色背景在暗色模式下仍然保持原色造成刺眼或不可读。用户自定义主题失效AionUi 支持通过「设置 → 外观」添加自定义主题详见 docs/guides/custom-theme.md自定义主题只覆盖契约内的 CSS 变量硬编码颜色永远不会被覆盖。从源码结构看迁移的核心是packages/desktop/src/renderer/styles/目录下的三份基线文件themes/default-color-scheme.css明暗两套 CSS 变量AOU 品牌色、背景、文字、边框、语义色等的定义源头themes/base.css与主题无关的基础样式与动画themes/index.css主题系统入口依次import上述两份文件。一、使用方式1. UnoCSS 原子类推荐UnoCSS 原子类在编译期解析类名即颜色语义最简洁直观// ✅ 背景色 - 简洁直观 div classNamebg-base // 主背景 (白色/黑色) div classNamebg-1 // 次级背景 (#F7F8FA) div classNamebg-2 // 三级背景 (#F2F3F5) div classNamebg-brand // 品牌色背景 (#7583B2) // ✅ 文本色 - 语义化 div classNametext-t-primary // 主要文字 (#1D2129) div classNametext-t-secondary // 次要文字 (#86909C) div classNametext-brand // 品牌色文字 // ✅ 边框色 div classNameborder-b-base // 基础边框 (#E5E6EB) div classNameborder-b-light // 浅色边框 // ✅ 品牌色系列 div classNamebg-aou-1 // AOU 色板 1-10 div classNamehover:bg-brand-hover // 品牌色悬停2. 内联样式CSS 变量当必须使用内联样式例如动态计算颜色、非布局类样式时直接引用语义化 CSS 变量div style{{ backgroundColor: var(--bg-base) }} div style{{ color: var(--text-primary) }} div style{{ borderColor: var(--border-base) }} div style{{ backgroundColor: var(--brand) }}需要动态读取变量计算值时可使用 styles/colors.ts 中提供的getCSSVar辅助函数内部通过getComputedStyle(document.documentElement).getPropertyValue(...)取值。二、常见颜色映射表下表是迁移时最常用的对照依据完整覆盖了 MIGRATION 指南中列出的全部映射关系旧值 (Hex)UnoCSS 类CSS 变量说明#FFFFFFbg-basevar(--bg-base)主背景#F7F8FAbg-1var(--bg-1)次级背景/填充色#F2F3F5bg-2var(--bg-2)三级背景#E5E6EBbg-3或border-b-basevar(--border-base)边框/分隔线#7583B2bg-brand/text-brandvar(--brand)品牌色#EFF0F6bg-aou-1/bg-brand-lightvar(--aou-1)品牌浅色背景#E5E7F0bg-aou-2var(--aou-2)AOU 色板 2#1D2129text-t-primaryvar(--text-primary)主要文字#86909Ctext-t-secondary/bg-6var(--text-secondary)次要文字#165DFFbg-primary/text-primaryvar(--primary)主色调说明colors.ts中同时维护了一份colorMapping常量含大小写两种形式如#EFF0F6/#eff0f6可用于编写自动化迁移脚本时的程序化查表。三、迁移步骤迁移遵循「搜索 → 查表 → 替换 → 测试」的四步流程搜索硬编码颜色在packages/desktop/src/renderer下搜索bg-#、text-#、color-#、border-#等模式查表对照上文「常见颜色映射表」找到对应的主题变量替换改写为 UnoCSS 语义化原子类推荐或 CSS 变量测试在明暗主题下分别切换验证重点检查背景与文字对比度、边框可见性以及自定义主题下的生效情况。从当前仓库的搜索现状看迁移仍在推进中pages/conversation/Messages/components/MessageToolCall.tsx、MessageToolGroupSummary.tsx与pages/conversation/GroupedHistory/ConversationRow.tsx中仍残留少量bg-#/border-#模式的硬编码新代码应一律使用语义化写法。四、迁移示例Before硬编码div classNamebg-#EFF0F6 hover:bg-#E5E7F0 span classNametext-#1D2129文本/span div classNameborder border-#E5E6EB/div /divAfter主题变量div classNamebg-aou-1 hover:bg-aou-2 span classNametext-t-primary文本/span div classNameborder border-b-base/div /div常见模式对照// ❌ 不推荐 div classNamebg-#F7F8FA text-#86909C border-#E5E6EB // ✅ 推荐 div classNamebg-1 text-t-secondary border-b-base五、源码级原理uno.config.ts 中的语义色板迁移的目标类名并非约定俗成而是由 uno.config.ts 中的 UnoCSS 主题配置严格定义。理解这张类名 → CSS 变量的映射表才能写出与主题系统完全一致的代码语义化文字色textColorst-primary→var(--text-primary)、t-secondary→var(--text-secondary)、t-tertiary→var(--bg-6)、t-disabled→var(--text-disabled)语义状态色semanticColorsprimary/success/warning/danger/info一组可同时作用于bg-*、text-*、border-*前缀背景色系统backgroundColors数字键1~10含base、hover、active同时支持bg-*和border-*两种前缀例如bg-1与border-1都指向var(--bg-1)边框色borderColorsborder-b-base、border-b-light、border-b-1~border-b-3品牌色brandColorsbrand、brand-light、brand-hoverAOU 品牌色系aouColorsaou-1~aou-10十个色阶是 AionUi 的品牌紫灰色调色板组件专用色componentColorsmessage-user、message-tips、workspace-btn分别指向消息气泡、提示、工作区按钮背景。此外uno.config.ts 还通过自定义rules桥接了 Arco Design 官方色板可混用text-1~text-4Arco 文字色、bg-fill-1~bg-fill-4填充色、border-arco-1~border-arco-4Arco 边框色、bg-primary-light-1~-light-4浅色系、bg-primary-1~-9官方色阶以及bg-popup、bg-color-white/bg-color-black等。六、明暗两套变量从哪来default-color-scheme.css所有var(--xxx)变量的实际取值定义在 themes/default-color-scheme.css 中同一套变量名在亮色与暗色下拥有不同值亮色基线:root, [data-color-schemedefault]AOU 色板--aou-1: #eff0f6→--aou-10: #0d101c背景--bg-base: #ffffff、--bg-1: #f9fafb、--bg-2: #f2f3f5、--bg-3: #e5e6eb文字--text-primary: #000000、--text-secondary: #454d5f、--text-disabled: #c9cdd4语义色--primary: #165dff、--success: #00b42a、--warning: #ff7d00、--danger: #f53f3f暗色基线[data-color-schemedefault][data-themedark]AOU 色板整体反转--aou-1: #2a2a2a→--aou-10: #eff0f6背景--bg-base: #0e0e0e、--bg-1: #1a1a1a、--bg-2: #262626、--bg-3: #333333文字--text-primary: #ffffff、--text-secondary: #ced3da语义色替换为适合暗背景的亮色变体如--primary: #4d9fff、--danger: #f76560。这正是迁移后颜色能自动适配明暗主题的根本原因组件只写语义类名/变量名具体取哪个十六进制值由主题系统在运行时决定。七、主题覆盖与 token 契约自定义主题为何能生效迁移的意义最终要落到可被用户主题覆盖上。AionUi 的主题模型见 common/theme/types.ts由appearance加两层覆盖通道组成结构化tokens与原始css。其中结构化 tokens 受 common/theme/tokenContract.ts 约束——这是哪些 CSS 变量可被覆盖的唯一事实来源包含--bg-base、--text-primary、--border-base、--primary、--brand、--message-user-bg等契约内变量按appearance-scoped随明暗变化与appearance-invariant明暗一致两种作用域声明。底层落盘逻辑在 renderer/utils/theme/tokensToCss.tstokensToCss会静默丢弃不在契约中的 key因此拼写错误的变量名不会污染 DOM同时它刻意使用:root[data-themelight|dark]特异性 0,2,0选择器才能压过基线暗色块[data-color-schemedefault][data-themedark]同为 0,2,0保证暗色模式下 token 覆盖不失效。主题的实际应用由 renderer/utils/theme/applyTheme.ts 完成一次调用同时写入html上的data-theme属性与body上的arco-theme属性并把 tokens 样式与装饰性 css 以#theme-tokens、#theme-decoration两个style追加到head末尾。这意味着只要组件使用契约内的语义变量任何自定义主题都能立即作用于全应用而硬编码颜色则会被永久隔离在主题体系之外。八、快速参考迁移时可直接对照这份速查清单背景bg-base,bg-1,bg-2,bg-3文字text-t-primary,text-t-secondary,text-t-disabled边框border-b-base,border-b-light品牌bg-brand,bg-brand-light,bg-brand-hover状态bg-primary,bg-success,bg-warning,bg-dangerAOU色板bg-aou-1~bg-aou-10结语AionUi 的主题色迁移本质上是把固定值替换为语义引用通过 uno.config.ts 定义的原子类与 themes/default-color-scheme.css 定义的 CSS 变量组件颜色自动获得明暗自适应与用户主题可覆盖两项能力。遵循本文的映射表、迁移步骤与源码级原理解析即可在新增页面和存量代码中写出真正主题化的界面相关主题系统的完整架构说明可进一步参考 themes/README.md。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AionUi 主题色迁移指南：从硬编码 Hex 到 UnoCSS 语义化原子类与 CSS 变量
AionUi 主题色迁移指南从硬编码 Hex 到 UnoCSS 语义化原子类与 CSS 变量【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi导读本指南面向 AionUi Desktop 渲染层的前端开发与主题定制者系统讲解如何将组件中硬编码的颜色值如bg-#EFF0F6、text-#1D2129迁移到语义化的 UnoCSS 原子类或 CSS 变量体系。通过本文你可以掌握 AionUi 基于 uno.config.ts 的完整语义色板、明暗双主题的 CSS 变量映射关系以及一套可复制、可验证的四步迁移流程让界面颜色自动跟随明暗主题与用户自定义主题。为什么需要迁移从固定色到主题令牌AionUi 的界面采用统一的主题系统所有颜色最终都由 CSS 自定义属性CSS Variables承载并随data-themelight/dark与data-color-scheme属性切换。如果组件里直接写死十六进制颜色就会出现两类问题明暗主题无法自适应硬编码的浅色背景在暗色模式下仍然保持原色造成刺眼或不可读。用户自定义主题失效AionUi 支持通过「设置 → 外观」添加自定义主题详见 docs/guides/custom-theme.md自定义主题只覆盖契约内的 CSS 变量硬编码颜色永远不会被覆盖。从源码结构看迁移的核心是packages/desktop/src/renderer/styles/目录下的三份基线文件themes/default-color-scheme.css明暗两套 CSS 变量AOU 品牌色、背景、文字、边框、语义色等的定义源头themes/base.css与主题无关的基础样式与动画themes/index.css主题系统入口依次import上述两份文件。一、使用方式1. UnoCSS 原子类推荐UnoCSS 原子类在编译期解析类名即颜色语义最简洁直观// ✅ 背景色 - 简洁直观 div classNamebg-base // 主背景 (白色/黑色) div classNamebg-1 // 次级背景 (#F7F8FA) div classNamebg-2 // 三级背景 (#F2F3F5) div classNamebg-brand // 品牌色背景 (#7583B2) // ✅ 文本色 - 语义化 div classNametext-t-primary // 主要文字 (#1D2129) div classNametext-t-secondary // 次要文字 (#86909C) div classNametext-brand // 品牌色文字 // ✅ 边框色 div classNameborder-b-base // 基础边框 (#E5E6EB) div classNameborder-b-light // 浅色边框 // ✅ 品牌色系列 div classNamebg-aou-1 // AOU 色板 1-10 div classNamehover:bg-brand-hover // 品牌色悬停2. 内联样式CSS 变量当必须使用内联样式例如动态计算颜色、非布局类样式时直接引用语义化 CSS 变量div style{{ backgroundColor: var(--bg-base) }} div style{{ color: var(--text-primary) }} div style{{ borderColor: var(--border-base) }} div style{{ backgroundColor: var(--brand) }}需要动态读取变量计算值时可使用 styles/colors.ts 中提供的getCSSVar辅助函数内部通过getComputedStyle(document.documentElement).getPropertyValue(...)取值。二、常见颜色映射表下表是迁移时最常用的对照依据完整覆盖了 MIGRATION 指南中列出的全部映射关系旧值 (Hex)UnoCSS 类CSS 变量说明#FFFFFFbg-basevar(--bg-base)主背景#F7F8FAbg-1var(--bg-1)次级背景/填充色#F2F3F5bg-2var(--bg-2)三级背景#E5E6EBbg-3或border-b-basevar(--border-base)边框/分隔线#7583B2bg-brand/text-brandvar(--brand)品牌色#EFF0F6bg-aou-1/bg-brand-lightvar(--aou-1)品牌浅色背景#E5E7F0bg-aou-2var(--aou-2)AOU 色板 2#1D2129text-t-primaryvar(--text-primary)主要文字#86909Ctext-t-secondary/bg-6var(--text-secondary)次要文字#165DFFbg-primary/text-primaryvar(--primary)主色调说明colors.ts中同时维护了一份colorMapping常量含大小写两种形式如#EFF0F6/#eff0f6可用于编写自动化迁移脚本时的程序化查表。三、迁移步骤迁移遵循「搜索 → 查表 → 替换 → 测试」的四步流程搜索硬编码颜色在packages/desktop/src/renderer下搜索bg-#、text-#、color-#、border-#等模式查表对照上文「常见颜色映射表」找到对应的主题变量替换改写为 UnoCSS 语义化原子类推荐或 CSS 变量测试在明暗主题下分别切换验证重点检查背景与文字对比度、边框可见性以及自定义主题下的生效情况。从当前仓库的搜索现状看迁移仍在推进中pages/conversation/Messages/components/MessageToolCall.tsx、MessageToolGroupSummary.tsx与pages/conversation/GroupedHistory/ConversationRow.tsx中仍残留少量bg-#/border-#模式的硬编码新代码应一律使用语义化写法。四、迁移示例Before硬编码div classNamebg-#EFF0F6 hover:bg-#E5E7F0 span classNametext-#1D2129文本/span div classNameborder border-#E5E6EB/div /divAfter主题变量div classNamebg-aou-1 hover:bg-aou-2 span classNametext-t-primary文本/span div classNameborder border-b-base/div /div常见模式对照// ❌ 不推荐 div classNamebg-#F7F8FA text-#86909C border-#E5E6EB // ✅ 推荐 div classNamebg-1 text-t-secondary border-b-base五、源码级原理uno.config.ts 中的语义色板迁移的目标类名并非约定俗成而是由 uno.config.ts 中的 UnoCSS 主题配置严格定义。理解这张类名 → CSS 变量的映射表才能写出与主题系统完全一致的代码语义化文字色textColorst-primary→var(--text-primary)、t-secondary→var(--text-secondary)、t-tertiary→var(--bg-6)、t-disabled→var(--text-disabled)语义状态色semanticColorsprimary/success/warning/danger/info一组可同时作用于bg-*、text-*、border-*前缀背景色系统backgroundColors数字键1~10含base、hover、active同时支持bg-*和border-*两种前缀例如bg-1与border-1都指向var(--bg-1)边框色borderColorsborder-b-base、border-b-light、border-b-1~border-b-3品牌色brandColorsbrand、brand-light、brand-hoverAOU 品牌色系aouColorsaou-1~aou-10十个色阶是 AionUi 的品牌紫灰色调色板组件专用色componentColorsmessage-user、message-tips、workspace-btn分别指向消息气泡、提示、工作区按钮背景。此外uno.config.ts 还通过自定义rules桥接了 Arco Design 官方色板可混用text-1~text-4Arco 文字色、bg-fill-1~bg-fill-4填充色、border-arco-1~border-arco-4Arco 边框色、bg-primary-light-1~-light-4浅色系、bg-primary-1~-9官方色阶以及bg-popup、bg-color-white/bg-color-black等。六、明暗两套变量从哪来default-color-scheme.css所有var(--xxx)变量的实际取值定义在 themes/default-color-scheme.css 中同一套变量名在亮色与暗色下拥有不同值亮色基线:root, [data-color-schemedefault]AOU 色板--aou-1: #eff0f6→--aou-10: #0d101c背景--bg-base: #ffffff、--bg-1: #f9fafb、--bg-2: #f2f3f5、--bg-3: #e5e6eb文字--text-primary: #000000、--text-secondary: #454d5f、--text-disabled: #c9cdd4语义色--primary: #165dff、--success: #00b42a、--warning: #ff7d00、--danger: #f53f3f暗色基线[data-color-schemedefault][data-themedark]AOU 色板整体反转--aou-1: #2a2a2a→--aou-10: #eff0f6背景--bg-base: #0e0e0e、--bg-1: #1a1a1a、--bg-2: #262626、--bg-3: #333333文字--text-primary: #ffffff、--text-secondary: #ced3da语义色替换为适合暗背景的亮色变体如--primary: #4d9fff、--danger: #f76560。这正是迁移后颜色能自动适配明暗主题的根本原因组件只写语义类名/变量名具体取哪个十六进制值由主题系统在运行时决定。七、主题覆盖与 token 契约自定义主题为何能生效迁移的意义最终要落到可被用户主题覆盖上。AionUi 的主题模型见 common/theme/types.ts由appearance加两层覆盖通道组成结构化tokens与原始css。其中结构化 tokens 受 common/theme/tokenContract.ts 约束——这是哪些 CSS 变量可被覆盖的唯一事实来源包含--bg-base、--text-primary、--border-base、--primary、--brand、--message-user-bg等契约内变量按appearance-scoped随明暗变化与appearance-invariant明暗一致两种作用域声明。底层落盘逻辑在 renderer/utils/theme/tokensToCss.tstokensToCss会静默丢弃不在契约中的 key因此拼写错误的变量名不会污染 DOM同时它刻意使用:root[data-themelight|dark]特异性 0,2,0选择器才能压过基线暗色块[data-color-schemedefault][data-themedark]同为 0,2,0保证暗色模式下 token 覆盖不失效。主题的实际应用由 renderer/utils/theme/applyTheme.ts 完成一次调用同时写入html上的data-theme属性与body上的arco-theme属性并把 tokens 样式与装饰性 css 以#theme-tokens、#theme-decoration两个style追加到head末尾。这意味着只要组件使用契约内的语义变量任何自定义主题都能立即作用于全应用而硬编码颜色则会被永久隔离在主题体系之外。八、快速参考迁移时可直接对照这份速查清单背景bg-base,bg-1,bg-2,bg-3文字text-t-primary,text-t-secondary,text-t-disabled边框border-b-base,border-b-light品牌bg-brand,bg-brand-light,bg-brand-hover状态bg-primary,bg-success,bg-warning,bg-dangerAOU色板bg-aou-1~bg-aou-10结语AionUi 的主题色迁移本质上是把固定值替换为语义引用通过 uno.config.ts 定义的原子类与 themes/default-color-scheme.css 定义的 CSS 变量组件颜色自动获得明暗自适应与用户主题可覆盖两项能力。遵循本文的映射表、迁移步骤与源码级原理解析即可在新增页面和存量代码中写出真正主题化的界面相关主题系统的完整架构说明可进一步参考 themes/README.md。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
