OMD 主题、配色与背景#

文档目录 · 首次使用 · 排障

在「设置 → 外观」选择四套从零制作的完整主题：

四套主题均覆盖侧栏、对话、输入区、设置与工作台，并适配明暗和窄屏。Codex Desktop 版本为 1.0.1，其他三套为 1.0.0。早期五套视觉皮肤已移除；浏览器若仍选中已移除的内置 id，会恢复默认外观。

也可以导入 .omd-skin.json。导入同一 id 会更新原有皮肤。皮肤与降低特效选项保存在当前浏览器、当前站点；明暗模式使用 DSH 的设置，可选浅色、深色、跟随系统。皮肤包不执行 JavaScript、不需要网络。

「恢复默认主题」保留已导入的文件；「移除当前主题」删除当前皮肤并恢复默认。格式无效的导入不会替换当前皮肤；启动时损坏的记录会跳过。必要时在当前地址追加 ?omd-skin=default（已有查询参数时追加 &omd-skin=default）可临时以默认外观打开设置。

内置皮肤始终保留在列表中。同 id 的导入版本可以覆盖内置版本，移除导入版本后，列表恢复内置版本。随包字体的许可见 skin-font-licenses。

同页的「每次加载历史」提供 50、200、500 条，默认 200。初次打开对话及「加载更早」使用这个数量；不改变模型上下文，也不自动展开操作记录。插件通过客户端适配原生分页请求，卸载后恢复宿主默认数量。

独立选择配色与背景#

主题负责布局、字体、圆角、间距与材质；配色负责底色、文字和强调色。配色可选「主题默认配色」或 28 套内置配色，按色系分组；导入主题的颜色也会进入同一列表。选择其它配色不会切换布局，玻璃透明度仍由当前主题决定。浅色、深色和跟随系统继续使用 DSH 原生设置。

每套新增配色均提供独立浅色／深色基础色板，并配套正文、辅助文字、代码、状态和按钮颜色，而非只更换强调色。新增配色仅包含颜色数据，不复制布局或字体；其 palette: 前缀与导入主题的 id 隔离。旧配色 id、主题默认外观和已有背景保持不变。

背景支持选择本地 PNG、JPEG、WebP 图片，单文件不超过 15 MB、4000 万像素。图片会缩小到最长边不超过 2560 像素并重新编码，保存在当前浏览器的 IndexedDB 中，不上传服务器，也不会作为对话附件发送给模型。背景显示区域可选「整个界面」「仅会话区」「仅左侧栏」，图片按所选区域填满或完整显示；旧设置默认沿用整个界面。会话区包含对话和底部输入区，侧栏收起或窗口缩放后自动适配。另提供 0–30 px 模糊、-80% 至 80% 明暗遮罩、20% 至 100% 面板不透明度。不透明度越低壁纸越明显，100% 时面板遮住壁纸；只调整面板底色，不改变文字透明度，菜单和弹窗保持实色背景。

切换主题、恢复默认主题或改变明暗模式，都保留用户选定的独立配色和背景。「主题默认配色」仅恢复颜色；「恢复默认背景」删除本地背景图片和背景参数，不影响主题或配色。开启「降低透明与动态效果」时暂时隐藏自定义背景，关闭后恢复。窗口支持的系统降低透明度选项也会使用实色面板。

旧版本升级后默认外观不变，原 .omd-skin.json 格式和存储键继续兼容。跨标签页同步仅限同一浏览器、同一站点；浏览器清理站点数据会删除外观设置和背景，Web 与桌面端不会自动互相同步。地址中的 omd-skin=default 可暂时跳过主题、配色与背景，移除此参数后恢复保存的选择。自定义主题应通过 --omd-* 语义参数引用颜色；CSS 中写死的颜色不保证可随配色改变。

高级外观设置#

在「设置 → 外观 → 高级设置」调整标识与精细外观，所有主题共用这一入口。

• Logo 与名称：跟随 OMD 主题、固定 Oh My DSH、保留 DSH 原样，或使用自定义名称和本地图片。保留原样会释放 OMD 的品牌插槽及浏览器图标，让 DSH 或其他品牌插件接管；Claude 主题也不会强制换成终端标识。
• 浏览器标题：使用 Oh My DSH、保留 DSH 原样，或填写自定义产品名称；会话名称仍由宿主动态更新。Logo 和标题分别保存，不受精细外观开关影响。
• 页面与分区：页面、左侧栏、会话、顶栏、输入框、工作台、菜单和弹窗、代码、用户消息及工具记录的颜色。
• 文字与交互：正文、辅助文字、强调色及其文字、边框、悬停、选中、焦点与成功／警告／错误状态颜色。
• 字体与排版：界面、正文、代码三类字体，以及界面字号、对话字号、代码字号和正文行高。
• 圆角、边框与材质：控件、面板、输入框、消息圆角，边框粗细、面板模糊和阴影。

开启「启用高级外观定制」后，浅色、深色可分别编辑。未修改的项目继续跟随主题；颜色修改即时生效，文字和数字在离开输入框或按 Enter 后保存。数字限制在可用范围内。关闭开关保留参数，重新开启即可恢复。各项「跟随主题」只清除该项覆盖；「恢复全部高级设置」清除全部定制和自定义标识，不影响主题、配色或壁纸。修改另一模式的颜色时，切换上方明暗模式预览效果。

本版还会在按 Escape、关闭设置或切换设置页前保存名称与数值。浏览器存储失败时，保留正在编辑的内容并显示错误；恢复存储后可重试，或把输入改回原值后退出。数值只在保存成功后调整到允许范围，逐字输入时不会提前改写。

壁纸与分区颜色可以一起使用。选定壁纸区域的底色用于给背景着色，输入框单独保留不透明度；文字保持完全不透明。开启降低透明效果时不应用面板背景模糊。自定义主题若写死某些内部控件样式，其细节未必随全局参数变化。

Logo 图片限 2 MB 的 PNG、JPEG、WebP，解码后缩至最长边 128 像素并重新编码为 PNG，只存当前浏览器；不接受远程链接和 SVG。高级参数与现有主题记录一起保存，刷新、重启和同源标签页同步均保留。?omd-skin=default 同时跳过高级定制并恢复原生标识与标题，不删除保存的记录。卸载插件后移除定制样式与标题转换。

制作与打包#

每套皮肤独立目录，包含：

• skin.json：{"schemaVersion":1,"id":"my-skin","name":"皮肤名称","version":"1.0.0"}。id 用小写字母开头，限小写字母、数字、连字符，最长 48 字符，不能为 default。
• tokens.css：下面三个参数块。它同时用于设计预览与生产打包，是两者共享的参数来源。
• native.css：可选，真实 OMD 组件的额外视觉样式。不能直接使用预览页面的类名。
• assets/：本套引用的本地图片与素材许可。
• theme.css：若存在，仅用于独立设计预览，不会打入生产皮肤包。

运行 node scripts/pack-skin.mjs <皮肤目录>，得到该目录的 deliverables/<id>.omd-skin.json。打包器将 native.css 中的 url(assets/...) 图片内嵌，支持 PNG、JPEG、WebP、GIF、SVG 和 WOFF2/WOFF/TTF/OTF 字体；包上限 1 MB。参考截图不会自动装入皮肤。字体优先系统字体栈；需要自托管字体时可在 tokens.css 或 native.css 写 @font-face，src 指向 assets/ 下的单一本地文件，附带许可和中文回退。打包后内嵌字体，不支持远程 CDN。

制作目录的独立预览不是生产界面的精确复制。打包后必须在 OMD 中导入验证；这一步验证 native.css、浏览器 CSS 值及实际组件覆盖。打包成功不代表视觉验收通过。

参数#

tokens.css 必须且只能有 .omd { ... }、.omd[data-appearance="light"] { ... }、.omd[data-appearance="dark"] { ... } 三个块；每条声明必须有分号。完整示例见 test/fixtures/skin.json 的 tokens（该文件只是测试数据）。

公共块必填：--omd-font-ui、--omd-font-body、--omd-font-mono、--omd-font-size、--omd-line-height、--omd-gap、--omd-radius-control、--omd-radius-panel、--omd-radius-composer、--omd-shadow、--omd-duration。

浅深色各自必填（均加 --omd-）：bg、surface、surface-solid、sidebar、text、muted、border、hover、selected、accent、on-accent、focus、success、warning、danger、code-bg。允许在这些必填参数之外定义本套 --omd-* 派生参数（每块最多 96 项），供 native.css 使用。必填字段使用具体 CSS 值，附加参数可用 var(--omd-本套参数) 引用已有参数，不支持缺失或循环引用；surface-solid 应为不透明表面，作为降低透明效果时的背景。

宿主颜色通过主题服务映射到 --dsw-alias-*，涵盖正文、背景、抬升表面、边框、菜单、弹窗、代码、状态与强调色；OMD 工作台参数同步映射到 --tx-* 和 --cx-*。输入框、控件、面板应用对应圆角；界面字体、输入/正文和代码字体分别使用三种字体参数。原有用户字号设置与功能布局保持由宿主管理。

原生组件样式#

.omd [data-omd-part="composer"] {
  background: var(--omd-surface);
  backdrop-filter: blur(18px);
  box-shadow: var(--omd-shadow);
}
.omd[data-appearance="dark"] [data-omd-part="sidebar"] {
  background-color: var(--omd-sidebar);
}
.omd [data-omd-part="button"]:focus-visible {
  outline: 2px solid var(--omd-focus);
}

data-omd-part 是皮肤编译器的选择器别名，不保证是实际 DOM 属性。维护者集中映射宿主版本变化，制作者不用写宿主构建后的随机类名。

选择器接受 .omd、可选的 [data-appearance="light|dark"]、可选的组件别名与选中状态（见下文），以及 :hover、:active、:focus-visible、:focus-within、:disabled、:checked 之一。可使用逗号分组、@media 和 @supports；不支持嵌套规则、除 @font-face 以外的其他 at-rule、伪元素或 !important。

允许属性：背景及背景图片/尺寸/位置/重复、文字颜色、边框及颜色/宽度/样式/圆角、阴影、背景模糊、字体族/字重/字距、outline 及颜色/宽度/样式/偏移。不得改 display、position、尺寸、overflow、pointer-events 等功能布局。完整字段由 src/client/skins/format.mjs 定义。

需要完整布局时，元数据可选 "layout": "ios-liquid"、"layout": "codex-desktop"、"layout": "claude-cli-terminal" 或 "layout": "google-material-expressive"，启用由插件内置、随宿主版本验证的布局适配器。它覆盖桌面侧栏、导航、输入区、设置与工作台，并提供对应的窄屏导航；Google Material 在 840px 以下使用模态导航和独立设置分类页，600px 以下使用顶栏菜单。同一布局可由不同皮肤复用。导入的 CSS 仍不能提供任意布局规则或代码；未知布局会被拒绝。恢复默认、切换到未指定布局的皮肤或卸载时，会移除布局样式，导航监听器停止接管。此字段需要包含该适配器的新版插件；不认识该布局的旧版会拒绝导入。

降低特效会移除背景模糊与动画，并为主要面板使用 solid 背景；系统减少动态效果设置始终生效。不要给真实文件内容或电脑截图添加整体滤镜。

验证#

至少检查两种明暗、系统模式切换、导入更新、刷新保存、默认恢复、390px 窄窗、菜单/弹窗、代码/文件与电脑预览、长文字/禁用/焦点/运行/失败状态，并保留实际 OMD 截图。色彩和排版可读性需要逐套检查，接口验证无法证明任意设计都没有视觉问题。

原生组件补充（1.1 制作接口）#

保留原有别名及 schemaVersion 1。皮肤组件规则优先于宿主的默认视觉样式；映射中的选择器使用统一优先级，同一组件命中多个规则时遵循 CSS 顺序。布局、隐藏和事件仍归宿主。

通用 button 和 code 继续覆盖全部按钮、pre/code；应只放确实通用的样式。code-block 只到 pre，不包括宿主代码语言标题栏。图标别名只涵盖当前明确映射的入口，不能假定所有小按钮都命中。设置只设容器背景不代表内部控件已覆盖。原生 select 展开的系统菜单保留系统行为；文件选择按钮由宿主统一使用当前皮肤的表面、边框与圆角，皮肤不需要伪元素。

可以在部件后添加 [data-omd-state="selected|checked|disabled"]（每次一个），由宿主映射真实 aria/checked 状态；其后可再加一个受支持的伪类。例：

.omd [data-omd-part="settings-nav-item"][data-omd-state="selected"] {
  background: var(--omd-selected);
  color: var(--omd-text);
}
.omd [data-omd-part="switch"][data-omd-state="checked"] {
  background: var(--omd-switch-on);
}
.omd [data-omd-part="input"] { background: transparent; border: 0; }

新增可用属性：accent-color、caret-color、font-variant-numeric；新增 :active 和 :checked。不开放任意属性选择器或布局属性。

可选参数：--omd-user-bg（用户气泡，默认 selected）、--omd-button-bg / --omd-button-fg / --omd-button-hover（主要按钮，默认 accent/on-accent/混色悬停）、--omd-switch-on（开关和复选框开启色，默认 accent）。按外观分别填写具体值；其它派生 token 只有被 native.css 引用才产生效果。这些新参数不是必填项，旧包继续可用。

开启降低特效时，页头、侧栏、输入外壳、工作台、设置弹窗、菜单均使用不透明背景。真实截图、文件内容不得被皮肤滤镜改变。

制作验收以真实 OMD 为准：至少逐项打开通用、模型、内置插件、外观、Oh My DSH（全部子页）、推荐插件、Agent 预设，以及宿主侧栏的归档会话入口，检查浅深色、选中/焦点/禁用/开关、下拉和菜单、导入/默认恢复与 390px 窄窗。仅预览截图不算生产通过。