OpenHuman 主题系统与 Theme Studio 完全指南运行时换肤、CSS Token 体系与源码解析【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman本文以 OpenHuman 桌面端Mac / Windows / Linux的主题能力为主线系统讲解内置主题家族、Light/Dark/Auto 三态切换、可视化 Theme Studio 的完整操作以及驱动这一切的 CSS 自定义属性Token体系与 Redux 持久化机制。读完本文你将掌握如何在 OpenHuman 中挑选、定制、导出并分享主题同时理解ThemeProvider、themeSlice与tokens.css之间的运行时协作原理能够基于这套体系为组件编写符合规范的主题化代码。内置主题家族OpenHuman 出厂自带五个主题家族Family每个家族同时提供Light亮色与Dark暗色两个变体覆盖从默认观感到高对比度终端的多种风格取向家族风格定位ClassicOpenHuman 的默认外观Light/Dark 均为空覆盖集完全依赖tokens.css的默认调色板Ocean以#4A83DD蓝色为主色调的清爽冷色系Sepia温暖、纸张质感护眼柔和Matrix黑底绿字的高对比度终端风格HAL 9000深黑背景搭配红色强调色致敬经典科幻这五个家族在源码中定义于 presets.ts 的THEME_FAMILIES数组中。每个家族是一个ThemeFamily对象持有light/dark两个变体主题与一个defaultVariant未指定变体时的默认值。从源码结构看classic、ocean、sepia的默认变体是light而matrix与hal9000默认变体是dark——因为这两个家族的核心身份就是深色系。各家族的实现细节很有代表性均位于 presets.tsOcean用一组R G B通道三元组覆盖surface-canvas233 242 252、surface-chrome、line、content等基础面并把primary-500设为74 131 221即文档所述的#4A83DD。Sepia除了暖色表面surface: 250 244 233外还把body与heading字体角色指向衬线字体栈Newsreader, Georgia, Cambria, ...营造纸书质感。Matrix覆盖整个primary色阶50950为一套荧光绿 ramp并把body/heading换成等宽字体栈JetBrains Mono, ...。HAL 9000用一套红色 ramp 替换primary全套色阶暗色变体下content-inverted被调深以保证白字按钮标签的对比度。注意预设中整条primary-*ramp 的覆盖是有意为之——组件大量使用dark:text-primary-300、bg-primary-600等不同色阶若主题只覆盖 500700 三档其余色阶会回落为默认蓝导致换肤不完整。这一点在 presets.ts 的注释中有明确说明。Light / Dark / Auto 三态切换每个家族都可以以Light、Dark或Auto三种方式应用Light / Dark固定使用该家族的亮色或暗色变体Auto跟随操作系统的prefers-color-scheme设置系统在亮/暗之间切换的瞬间应用无需刷新即实时跟随。Auto 的实时跟随由 ThemeProvider.tsx 实现当themeVariant system且当前选中了某个主题家族时组件通过window.matchMedia((prefers-color-scheme: dark))注册change监听器OS 切换时立即用resolveFamilyVariant(family, dark|light)重新解析并应用对应变体同时保留了addListener回退以兼容 Safari 14 以下的旧实现。在状态层themeVariant与简单的 Appearance 开关通过setThemeVariant/setThemeMode两个 reducer 保持同步二者互相镜像见 themeSlice.ts。Theme Studio可视化主题编辑器打开Settings → Theme Studio面板组件位于 ThemeStudioPanel.tsx你可以获得一个完整的可视化主题编辑器能力包括挑选家族从主题瓷砖画廊中选取内置家族或你自己的自定义主题调整每一个颜色 Tokensurface表面、text文本、border边框与 accent ramp强调色阶都配有原生取色器当文字与背景的亮度对比跌破可读阈值时界面会给出实时的对比度警告按角色切换字体title、heading、body、mono、serif 五种角色可分别使用不同字体族配置背景层Backdrop可选动画 WebGL 网格、纯色或自定义图片并可叠加可选的点阵覆盖层管理自定义主题创建、编辑、重置、删除以及导出 / 导入 JSON与他人分享。颜色 Token 编辑器Theme Studio 的颜色编辑分组定义在 tokens.ts 的COLOR_GROUPS中共四组分组编辑的 Token对应 Tailwind 工具类Surfaces表面surface、surface-canvas、surface-muted、surface-subtle、surface-strong、surface-hover、surface-overlay、surface-chromebg-surface、bg-surface-muted、…Text文本content、content-secondary、content-muted、content-faint、content-invertedtext-content、text-content-muted、…Borders边框line、line-strong、line-subtle、line-chromeborder-line、border-line-strong、…Accents强调色primary/sage/amber/coral四个家族的-500基色更多色阶通过“高级”展开器访问bg-primary-500、text-coral-600、…UI 边界处的取色器使用 hex而存储使用R G B通道三元组二者通过 color.ts 的hexToChannels/channelsToHex转换channelLuminance则计算 WCAG 相对亮度供对比度警告使用。字体角色FONT_ROLES [title, heading, body, mono, serif]是五种可独立设置的字体角色tokens.ts。Theme Studio 的字体选择器基于FONT_CHOICES预设项Inter、Cabinet Grotesk、System UI、Newsreader衬线、Georgia衬线、JetBrains Mono每项对应一组完整的 CSSfont-family回退栈写入--font-role变量。Backdrop 背景层背景层支持三种BackdropKindtypes.tsmesh启用动画 WebGL 网格渐变。实现位于 MeshGradient.tsx——它的四个渐变停靠点从活动主题的primaryramp 与surfacetoken 派生读取解析后的 CSS 变量转 hex因此背景会跟随 Matrix 绿、HAL 红、Ocean 蓝等主题自动变色同时它会优雅捕获 WebGL 错误Tauri WebView 可能缺少 GPU 上下文并只在窗口可见且聚焦时运行动画。solid纯色/渐变画布默认。image以 cover 方式铺满自定义图片需要提供imageUrl。此外主题还可携带gradient.canvas整段 CSSbackground值通过--app-gradient变量作用于应用背景。注意内置预设目前不再携带画布渐变源码注释记录了这一决策——渐变与半透明surface-chrome蒙层叠加后会导致窗口上下颜色不一致但能力本身保留用户自定义主题仍可设置。编辑预设自动 ForkAuto-Fork在 Theme Studio 中修改任意内置预设的 token会透明地派生出一个全新的自定义主题原预设保持原样不被改动。你可以从 Ocean 出发微调同时保留 Ocean 与你的定制版本。该机制在状态层由ensureEditableCustom实现themeSlice.ts当activeThemeId指向一个内置预设或旧版 id时它会把“当前生效主题”复制为custom-sourceId命名的自定义主题、写入customThemes并设为活动主题再返回给编辑操作。基于同一源主题重复编辑是幂等的复用已存在的custom-sourceId不会产生重复副本。派生主题会记录basedOn: base.id因此“重置覆盖”时可以恢复预设的原始调色板resetActiveThemereducer而不是泛泛的 Light/Dark 默认值。导出与导入 JSON自定义主题以 JSON 形式导出/导入ThemeStudioPanel的导出区会把当前生效主题序列化为美化 JSON 供复制导入区接受粘贴的 JSON解析失败会给出错误提示。Theme类型本身是“部分覆盖集”——colors与fonts只记录被改动的 tokentypes.ts因此导出的 JSON 体积小、可读性强导入后自动成为一个新的自定义主题。分享主题的完整链路就是导出 JSON → 发送 → 对方粘贴导入。状态存储Redux redux-persist主题状态活动主题、Light/Dark/Auto 变体、全部自定义主题存放在 Redux 的themeslice 中并通过redux-persist持久化到localStorage因此应用重启后主题依然保留且按用户作用域隔离。REHYDRATE时会做一次旧版本兼容迁移把早期持久化的mode字段映射为新的themeVariant。themeSlice.ts 的核心状态字段包括字段含义activeThemeId当前选中的家族 idclassic/ocean/matrix/hal9000/sepia或自定义主题 idthemeVariant/modelight/dark/system三态二者互为镜像customThemes用户创作的主题数组部分或全部 token 覆盖fontSize全局字号预设small(14px) /medium(16px) /large(18px) /xlarge(20px)customFontSizePx字号微调px范围 1228非空时覆盖预设issue #4246tabBarLabels、agentMessageViewMode、developerMode、hideAgentInsights其余外观/调试偏好selectEffectiveTheme负责把状态解析为要应用的具体Theme自定义主题直接返回否则解析家族 变体system变体通过resolveTheme咨询prefers-color-scheme非 DOM 环境如 SSR 回落为 light。旧版持久化的ocean/midnight等 id 也会被规范化ocean→ 按变体映射到 Ocean 家族、midnight→ Ocean Dark保证老用户升级后主题选择依然生效。底层原理CSS Token 体系Token 与 RGB 通道三元组一切换肤都建立在 CSS 自定义属性变量之上。app/src/styles/tokens.css是所有可换肤颜色与字体的唯一事实来源每个颜色 token 以空格分隔的 RGB 通道三元组存储例如--surface: 255 255 255;、--primary-500: 47 110 244;Light 调色板定义在:rootDark 调色板定义在:root.dark字体角色变量为--font-title/--font-heading/--font-body/--font-mono/--font-serif。通道三元组格式是强制要求而非风格选择Tailwind 通过rgb(var(--token) / alpha-value)包装这些变量正是这个格式让bg-surface/50、bg-primary-500/10这类透明度修饰符继续工作。tokens.css头注释明确指出一旦换成 hex/var 混写会静默破坏全部约 640 个带透明度后缀的工具类。旧版--cmd-*与--color-*变量集合只是这些规范 token 的薄别名新增颜色不应再写入它们。token 的完整分类与 Tailwind 工具类对应关系亦见 gitbooks/developing/theming.md组TokenTailwind 工具类表面surface、surface-canvas、surface-muted、surface-subtle、surface-strong、surface-hover、surface-overlay、surface-chromebg-surface、bg-surface-muted、…文本content、content-secondary、content-muted、content-faint、content-invertedtext-content、text-content-muted、…边框line、line-strong、line-subtleborder-line、border-line-strong、…强调色primary-*、sage-*、amber-*、coral-*色阶 50…950bg-primary-500、text-coral-600、…变量支撑、可换肤、名字不变字体font-title、font-heading、font-body、font-mono、font-seriffont-title、font-heading、font-body、…Tailwind v4 接线本仓库当前使用 Tailwind v4package.json中为tailwindcss ^4.3.3接线位于 index.css 的theme块例如--color-surface: rgb(var(--surface))、--color-primary-500: rgb(var(--primary-500))、--font-body: var(--font-body)等把 token 暴露为bg-surface、text-primary-500、font-body等工具类同时用custom-variant dark (:is(.dark *))定义暗色变体。这样组件里写bg-surface、text-content、border-line时换肤只需改 token 值组件代码零改动。ThemeProvider运行时应用ThemeProvider.tsx 负责把“选中的主题”落到 DOM解析出当前生效的Theme通过selectEffectiveTheme把每个颜色 token 覆盖写成html上的内联--key变量、每个字体角色写成--font-role根据theme.isDark切换html的.darkclass并同步设置root.style.colorScheme清理机制记录上一次写入的变量清单切换主题时新主题未包含的旧变量会被移除避免“上一个主题的残留覆盖”泄漏fall-through主题未指定的 token 自动落到tokens.css的 Light/Dark 默认值——因此内置 Light/Dark 预设CLASSIC_LIGHT/CLASSIC_DARK的colors和fonts是空对象纯粹靠isDark生效额外处理--app-gradient主题的画布渐变以及根字号customFontSizePx微调覆盖fontSize预设写入html的font-size所有基于 rem 的 Tailwind 文本工具类随之缩放。在写入前withDerivedChromechrome.ts会为“染色但未命名窗口边框”的主题补齐surface-chrome与line-chrome两个 token亮色按画布亮度约 13% 变暗214/245暗色在画布基础上 10 偏移line-chrome直接跟随line-strong。显式指定值永远优先于派生值。这样即使主题只改了画布色侧边栏所在的窗口边框RootShellLayout以 /30 透明度铺在内容卡片外侧的蒙层也能与主题同色系而不是残留默认灰。对比度门禁仓库对每个内置暗色预设设定了 WCAG AA 门禁测试presets.contrast.test.ts 会把每个预设的覆盖合并到:root.dark默认值之上与 ThemeProvider 运行时分层一致验证正文 4.5:1、大文本/UI 3:1 的可读性且覆盖所有可能的文字落点表面含 hover/pressed/overlay同时有一个“DARK_BASE 一致性”测试解析tokens.css确保 JS 中的镜像基准与 CSS 事实来源不漂移。测试还带有一份“允许清单”记录了刻意豁免的 token 与原因。这也是 Theme Studio 中对比度警告的判定依据来源。组件编写规范与“四 Ramp 天花板”面向贡献者的规范详见 gitbooks/developing/theming.md中性表面/文本/边框一律使用语义工具类bg-surface、text-content、border-line而不是bg-white dark:bg-neutral-900之类的写死搭配——token 会替你翻转明暗几乎不需要dark:变体语义色使用四个可换肤 rampprimary/sage/amber/coral避免在className或内联style中写死 hex那会绕过主题系统。代码库中存在大量“用颜色回答这是谁”的查找表技能分类、事件日志域、通知提供方、目录来源等。规范有一条硬性约束可换肤 ramp 恰好只有四个primary、sage、amber、coralTailwind 默认调色板里的emerald、violet、sky、teal、indigo、cyan、rose、pink、purple等都会解析为固定 oklch 值完全无视当前主题。因此同色阶映射到主题等价物red → coral、green/emerald → sage、orange → amber、blue → primary没有等价物的色相不给新 rampviolet不是“接近 primary”不要发明第五个 ramp也不要复用--accent-lavender这类固定 hex超过四色相时多余行归入表格自带的“未知/其他”中性对如bg-surface-subtle text-content-secondary绝不让两行撞同一个 ramp按“读者会依据哪个区分采取行动”来分配颜色徽章通常自带文字标签颜色只是扫描辅助把四个 ramp 花在改变行为的读取上其余走中性coral语义上是“失败”把普通行涂成 coral 会让正常状态看起来像故障。仓库中的实操范例均见 gitbooks/developing/theming.md表格行数保留色相理由skills/skillIcons.tsxCATEGORY_META9Built-in(primary)、Productivity(sage)、Social(coral)、Tools Automation(amber)Channels/Chat/Platform与All/Other共用中性skills/SkillsExplorerTab.tsxSOURCE_COLORS6built-in(sage)、optional(primary)四个远端目录自带名称来源层级才是关键区分settings/panels/EventLogPanel.tsxDOMAIN_BADGE_COLORS11tool(primary)、agent(sage)、approval(amber)谁执行了动作、什么在等人coral 刻意空缺品牌色与 Primitive 变体第三方品牌色Telegram#249CD8、Discord#5865F2、iMessage#34C759刻意保留为 hex因为压平为bg-surface-subtle会把它们抹进旁边泛型徽章里给它们主题化归属意味着“新增品牌 token”属于产品决策而非清理工作。不要重绘 primitive 的变体Button variantprimary classNamebg-violet-500会冻结颜色并破坏 hover/focus/disabled 状态同步——应改染其周围的表面并去掉覆盖。迁移 Codemod把旧的dark:配对折叠成语义工具类仓库提供幂等的自动化迁移工具scripts/theme-codemod/把已审计的light dark:Tailwind 配对折叠为语义工具类node scripts/theme-codemod/migrate.mjs # dry-run 报告 node scripts/theme-codemod/migrate.mjs --write # 实际应用 node scripts/theme-codemod/migrate.mjs --selftest # 夹具断言它只重写相邻配对绝不触碰带透明度后缀的工具类与测试文件映射表位于scripts/theme-codemod/map.mjs。更多参考Theming贡献者参考token 体系、Tailwind 接线、迁移 codemod 的完整规范Realtime MascotOpenHuman“个性”的另一大块——实时吉祥物主题相关测试ThemeProvider.test.tsx、MeshGradient.test.tsx、presets.contrast.test.ts可作为理解运行期行为的可执行文档。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考