ThemeForge：一个无需额外设置即可使用的CSS主题系统，AI代理能一键完成安装。
- 发布日期
- 2026年10月5日
- 更新日期
- 2026年10月6日
- 作者
- Jacob Lloyd —— 项目完成后，在 AI 协助下撰写
- 阅读时长
- 约 53 分钟阅读
简单来说： ThemeForge是一个免费的CSS资源包，其中还包含一段小型脚本。它能为任何网页应用添加主题选择器功能，提供十种配色方案，以及一系列现成的按钮、输入框、卡片和对话框组件。其设计初衷就是为了让AI编程助手能够通过一行代码将其集成到应用中：该助手只需读取代码库中的简短说明文件，应用便能获得一个可正常使用的主题选择器、符合系统规范的默认设置，以及用于界面设计的各种样式参数。
大多数网页应用最终都会出现三种主题，它们分别写在三个不同的地方：主 CSS 文件里的 :root 块、@media (prefers-color-scheme: dark) 下的第二个块，以及开发者为了实现主题选择器而手动添加的第三个块。结果总是一样：主页上的控件呈现一种样式，设置页上又是另一种样式；而在问题跟踪器里则总有人发问：为什么深色主题会让页脚变成蓝色？我编写了 ThemeForge，就是为了防止这类问题的发生。它仅包含一个名为 ui-theme/ 的文件夹，里面有运行时脚本、基础层代码、各类组件样式、全部十个主题的配色参数、主题选择器，还有可选的 Tailwind 与 Quasar 适配器，以及为 AI 编程助手准备的简短说明文档 AGENTS.md。只需把该文件夹引入项目，再在页面头部添加四行代码，应用就能拥有可用的主题选择器，并自动遵循系统的深色/浅色模式设置。安装过程仅需一条命令即可完成；本文其余部分则是为那些想要深入了解其运作原理的人准备的。
本文将带您逐一了解：该文件夹里究竟有什么、十个主题各自的作用、对比度方面的考量，以及文中后续会作为参考资料提供的各类设计参数与组件样式。后半部分特意设计成了便于快速查阅的参考手册形式——每一个参数、每一种组件、每一个公开方法都一一列出，方便编程助手（或是未来的您）直接照搬使用。
简而言之：
- 获取方式： github.com/LaserLloyd/ThemeForge —— MIT 许可，完全免费；下方下载区也提供了源码压缩包。
- 功能简介： 仅一个文件夹
ui-theme/，将其嵌入任意网页应用后即可获得十个配色主题、一个主题选择器、约250个设计参数、基础元素层、文本样式标准，以及完整的组件样式集合（按钮、输入框、开关、卡片、对话框、提示框、表格及应用外壳）。仅需纯 CSS 与一段小型脚本即可运行。无需构建步骤、无需 Node.js，也没有任何依赖项。 - 一键安装指令（直接摘自 README）：
python3 -c "import urllib.request as u,sys;sys.argv=['update.py','--dest','static/ui-theme'];exec(u.urlopen('https://raw.githubusercontent.com/LaserLloyd/ThemeForge/main/ui-theme/update.py').read())" - 头部代码顺序（顺序很重要）： 先引入
ui-theme.js（传统同步加载方式，绝不可设为defer或module），随后是ui-theme-base.css与ui-components.css，接着是应用自身的 CSS，最后才是ui-theme.css，这样主题参数才能生效。 - 主题选择器： 仅需一个元素：
<select class="ui-select" data-ui-theme-picker aria-label="Theme"></select>。它会自动填充选项，且能在多个标签页间保持同步。 - 十个主题： 六个核心主题（紫色、午夜金、冰川色、森林绿、纸白、日光色），外加四个可选主题（电光黄、LaserLloyd、LaserLloyd Light、夜红）。所有主题均顺利通过对比度检测，无任何不合格项。
- 对比度标准： 正文文字对比度为7:1，次要文字为6:1；所有界面上的文字层级对比度均达到4.5:1；控件边缘及开/关状态对比度则为3:1。判断状态主要依据形状与填充色，而非单纯颜色。
- 专为 AI 助手设计： AGENTS.md 以文字形式描述了完整的安装流程——任何编程助手只需读取该文件即可一步完成主题选择器的配置。该仓库自身的 CI 系统（GitHub Actions，共三项任务）可确保代码克隆、对比度检测、
node --check对每份 JS 文件的校验，以及无头 Chrome 环境下的运行时测试均能顺利通过。
如何获取
该工具托管于一个 MIT 许可的开源仓库：github.com/LaserLloyd/ThemeForge。其中 AGENTS.md 为安装指南，对比度检测报告则详细说明了各主题的合规情况。若您更喜欢直接下载压缩包，本页底部的下载区提供了完整源码；网站上的 下载页面同样列有相关文件。如果您的机器上未安装 Python，README 中还提供了 git clone --depth 1、npx degit 两种方案，以及指向 <script> 标签的 jsDelivr 链接，该链接被固定在了 @v1.0.0 版本，适合快速制作原型之用。
最终效果
用户只需简单操作即可获得心仪的界面风格：页面顶部有一个已预置全部主题选项的主题选择器；系统还会自动根据操作系统的设置应用深色或浅色主题。您只需在代码里加入一行 CSS：<code>background: var(--surface-2)</code> 代替原本的 <code>#1d1d39</code> 即可。选定主题并刷新页面后，界面不会出现任何突兀变化——运行时脚本会在 <head> 内同步执行，从标签中读取自身的 data-* 配置参数，并在首次渲染前完成主题设置。即便在两个标签页中分别打开主题选择器并更改各自的主题，另一页面也会自动随之更新（这得益于 storage 事件监听机制）。若需要打印深色或 OLED 主题的文档，运行时脚本会在打印期间自动切换为浅色主题模式，或者根据 data-print-theme 的设置隐藏导航栏，确保打印出的内容在纸张上清晰可辨；打印浅色主题时则维持原样输出。
ui-app、ui-card、ui-btn、ui-switch 以及各类 --surface-* / --text-* / --accent 参数共同构建而成。主题选择器仅需一个 <select data-ui-theme-picker> 元素——运行时脚本会自动填充并同步各选项。上图即为页面内的演示效果，并非独立文件的截图。完整的示例页面——包含所有主题下的各类组件——位于仓库中的 specimen/index.html 文件里（可通过运行 python3 -m http.server 后访问 /specimen/ 查看）。
各部分如何协同工作
运行时脚本仅为一个小型 JS 文件，即 ui-theme.js（大小约23 KB，共575行代码），它按以下顺序完成三项任务。首先，它从自身所在的 <script> 标签里读取 data-* 属性值（这些设置随文件一同加载）；接着检查 localStorage 中的记录及操作系统的深色/浅色模式偏好；最后在首次渲染前将选定的主题写入 <html data-palette> 属性，并将当前使用的主题类型（amoled、dark 或 light）写入 <html data-theme>。随后，脚本会遍历整个文档，查找所有 <select data-ui-theme-picker> 元素，并用当前启用的主题列表填充它们（同时监听后续由其他框架动态生成的同类控件）。最后，脚本会向全局暴露 window.UITheme 对象；当 ui-components.js 文件被加载后，还会生成 window.UIComponents 对象，并注册一个 storage 事件监听器以确保多个标签页间的状态同步。CSS 部分则相对简单：ui-theme-base.css 负责设置页面文字、链接、焦点环、滚动条以及减少动画效果等基础样式；ui-components.css 则绘制各类按钮、输入框、开关、卡片、对话框、提示框及表格的视觉形态；唯一会随主题变化而变动的文件是 ui-theme.css——它借助 [data-palette="…"] 选择器为全部十个主题逐一定义各自的配色、字体、间距、圆角、阴影及动画参数。紫色主题因对应 :root，故无需设置 data-palette 属性即可生效。运行时脚本负责选定主题，而 CSS 则负责将相应样式呈现给用户。
最让人惊喜的部分就是操作系统主题的自动适配机制：data-default="auto"会在每次页面加载时读取prefers-color-scheme的值，运行时再将其与用户已保存的选择项（或是data-default-dark及data-default-light）相结合来决定最终主题。只要更改操作系统主题并刷新页面，界面风格也会随之变化。若用户通过选择器手动指定了某个主题，该设置将一直生效，直至用户将其清除（或调用UITheme.reset()）。此外，运行时还会触发storage事件，确保同一应用的两个打开标签页能够保持同步，而无需与服务器进行通信。
安装
该仓库中的 AGENTS.md 提供了完整的操作指南；简版内容则仅为下面这一行文字以及一个包含四个标签的头部块。从应用的根目录出发：
python3 -c "import urllib.request as u,sys;sys.argv=['update.py','--dest','static/ui-theme'];exec(u.urlopen('https://raw.githubusercontent.com/LaserLloyd/ThemeForge/main/ui-theme/update.py').read())"
它会下载安装程序，该程序会获取最新版本，将每个文件与 files.json 中的 SHA-256 列表进行比对，然后创建相应文件夹。在 Windows 系统中，请使用 python 或 py 来代替 python3；在 PowerShell、cmd 和 bash 中命令格式完全相同。每个页面中的四行代码位于 <head> 内：
<script src="/static/ui-theme/ui-theme.js"
data-themes="紫色,午夜金色,冰川蓝,森林绿,纸张白,日光黄"
data-default="自动" data-default-dark="午夜金色" data-default-light="日光黄"
data-storage-key="myapp.theme"></script>
<link rel="stylesheet" href="/static/ui-theme/ui-theme-base.css">
<link rel="stylesheet" href="/static/ui-theme/ui-components.css">
<!-- 您自己的样式表 -->
<link rel="stylesheet" href="/static/ui-theme/ui-theme.css">
三条规则，各有其用。ui-theme.js脚本属于传统类型且会阻塞页面渲染——它绝不会使用 type="module"、defer 或 async 属性，因为它需要从自身的标签中读取配置信息（即 document.currentScript，该值在模块脚本中值为 null），并确保在页面首次渲染前完成主题设置。基础层与组件层会在应用的CSS之前加载，这样即便两者的优先级相同，应用自身的规则也能生效。ui-theme.css则在之后加载，如此一来旧版应用中的变量便无法覆盖主题令牌了。主题选择器只需一行代码即可实现：<select class="ui-select" data-ui-theme-picker aria-label="Theme"></select>。通过脚本可调用 UITheme.set('glacier')、UITheme.current() 以及 UITheme.onChange(fn)。根据 AGENTS.md 中的说明，整个安装过程大约需要五分钟。
在真实的应用程序中，完成这一操作的智能代理是这样工作的：人类用户要求一个AI编程代理为应用添加深色模式以及主题选择器。该代理先读取了 AGENTS.md 文件，随后将一条命令执行于 static/ui-theme/ 目录下；接着把四个头部代码块粘贴到基础模板中，并将其中两个颜色值分别替换为 var(--surface-2) 和 var(--text-secondary)。最后，它还将主题选择器添加到了页眉位置。整个修改过程仅涉及六行代码变更，且没有任何新的依赖项被引入。由于对比度检查机制本就涵盖了组件可能呈现的所有颜色组合，运行时也会自动遵循操作系统的设置；因此，未来唯一需要由代码检查步骤捕捉的异常情况，就是那些直接硬编码颜色的代码提交了。
主题介绍
前六种是应用默认提供的基础主题；另外四种则需用户主动选择后才会显示。所有主题均通过了对比度审核（docs/contrast-report.md）：正文文本的对比度为7:1，次要文本在所有界面上的对比度均为6:1；其他各类文本的对比度均达到4.5:1。各控制元素的边缘及开关状态在任意主题下的对比度也均满足3:1的标准；此外，在任何主题中，通过形状和颜色即可识别出处于“开启/选中/当前”状态的控件。完整列表如下：
| 主题 | 类别 | 背景 | 描述 |
|---|---|---|---|
| 紫色 | 核心主题 | 深色 | 深靛蓝色背景下搭配紫罗兰色点缀与柔和的淡紫色文字。这是基础主题，其属性值即为 :root 的默认值。 |
| 午夜金 | 核心主题 | OLED | 纯黑色背景下呈现温暖的金色调，专为 OLED 屏幕设计。 |
| 冰川 | 核心主题 | OLED | 纯黑色背景下为冰蓝色文字与标志，并辅以深青绿色点缀。 |
| 森林 | 核心主题 | OLED | 纯黑色背景下为淡鼠尾草绿与地衣色，搭配棕褐色色调。 |
| 纸张 | 核心主题 | 浅色 | 温暖的羊皮纸色调，墨棕色文字；配有衬线字体用于正文书写，另有一抹红色作为点缀。 |
| 日光 | 核心主题 | 浅色 | 纯净的白色背景搭配蓝色点缀。 |
| 电光黄 | 可选主题 | 深色 | 石墨色背景下为鲜艳的酸黄色，具有圆润的边角与清晰的线条设计。 |
| LaserLloyd | 可选主题 | 深色 | 近乎黑色的石墨色背景下呈现激光蓝色调，源自作者官网；可与 LaserLloyd Light 搭配使用。 |
| LaserLloyd Light | 可选主题 | 浅色 | LaserLloyd 的浅色版本。 |
| 夜色红 | 可选主题 | OLED | 低蓝光夜间主题：纯黑色背景下为暗红色文字，整体结构亦为红色；完全不含任何蓝色成分。 |
四个可选主题中，有三个是特意设计得色彩鲜明一些的。Electric Yellow是我在黑暗环境中审查CSS代码时使用的主题——它能让页面显得比代码编辑器更醒目；LaserLloyd则与该网站的蓝灰色调相匹配，从而确保网站与我正在开发的应用程序风格一致；Night Red是一个独立的“夜间模式”主题。对比度检测工具会针对一组包含171行的文本样本（即标准用的147行文本加上为低光环境额外添加的若干行）来测试该主题；在该模式下，调色板里的每个颜色在蓝色通道上的数值均为零。（相关说明参见：docs/contrast-report.md中的“零蓝色值检测”；README.md中的“Night Red”章节；以及docs/THEMES.md中的“Night Red”部分。）
注意事项/易错点
- CSS中硬编码的颜色才是问题所在，而非主题本身。 代码审查仅检查相关标记；例如代码中的
<code>color: #fff</code>在任何主题下都会显示为白色。tools/lint_colors.py（位于代码库中）以及 AGENTS.md 第8节中的 grep 命令能检测出此类问题；CI流程中的代码检查并未执行该步骤，因此合并前请务必在本地运行它。 <code>ui-theme.js</code>必须置于<code><head></code>的最前端，且不能使用<code>defer</code>或<code>module</code>属性。使用模块脚本时无法获取<code>document.currentScript</code>，而运行时正是通过该标签读取自身的<code>data-*</code>数据。此类情况会导致页面先显示错误的主题，随后才切换为正确主题。<code>ui-theme.css</code>必须在应用的CSS之后加载。 正确的加载顺序为：基础样式 → 组件样式 → 应用自身样式 → 主题标记。若某个应用规则与主题标记具有相同的优先级却加载得更晚，则该规则会被忽略。<code>data-themes</code>决定了主题选择器可显示的选项。 若某个已保存的主题其标识名不在<code>data-themes</code>列表中，该主题在下一次加载时将被忽略（此时系统会回退至默认主题）。若要移除某个主题，只需添加<code>data-legacy-key</code>与<code>data-legacy-map</code>属性即可完成旧数据的迁移。- 安装后 Tailwind的
<code>rounded-md</code>与<code>font-sans</code>设置会发生变化。 这是正常现象：主题本身定义了<code>--radius-*</code>与<code>--font-*</code>标记，其设定的值会覆盖原有配置。无需强行干预。 - Next.js的 hydration相关警告处理。 在
<code><html></code>标签中加入<code>suppressHydrationWarning</code>属性即可；同时需对<head>区块禁用<code>no-sync-scripts</code>代码检查规则——因为运行时会在React完成渲染前为<code><html></code>添加相应属性。 - 其他库也会读取
<code><html></code>中的<code>data-theme</code>值（如daisyUI、Pico）。 运行时会将该属性设为<code>data-theme="amoled\|dark\|light"</code>；请确认相关库不会对该值产生反应。若确实存在此类情况，可通过<code>data-mirror-attr</code>属性为其指定其他属性名即可。 - 切勿修改
<code>ui-theme/</code>目录下的任何内容。 该目录会在更新时被覆盖；代码检查也会检测到人工编辑行为，此时安装程序会拒绝覆盖此类文件。如有调整需求，请直接在应用的CSS中修改。 - 主题预设的字体并未被打包进应用。 所有预设样式都会回退至系统默认字体；若需使用 Inter、JetBrains Mono、Space Grotesk 或 Archivo 等字体，需自行引入（相关集成说明文档提供了可直接复制使用的
<code><link></code>代码）。 - 设置
<code>prefers-contrast: more</code>会加粗线条并提升文字对比度。 无需额外配置主题标记；运行时会自动响应该设置并调整CSS表现。<code>high-contrast</code>标记组则是实现相同效果的旧版手动启用方式。
这让我处于什么境地
我想要的是一种能为我开发的所有应用都提供主题系统的方案，而无需每次都从零开始编写。ThemeForge正是我愿意长期使用的版本。我现在把相关文件放入应用中的目录名为 ui-theme/，再配上应用自身的功能模块即可；无论使用哪种框架，那四个头部块标签以及主题选择器都是一样的。负责安装的程序会读取 AGENTS.md 文件，而非Slack消息。对比度检查、无头版Chrome运行时测试，以及对每个发布的JS文件执行 node --check 检测——正是这些机制让我有勇气继续推进开发工作。目前版本号为1.0.0：因为主题令牌属于公开API，而修改令牌名称即属于重大版本更新；每次发布都会打上git标签，VERSION 文件夹内容与之对应，且所有JSON文件均通过与 update.py 校验用的同一份校验值列表进行签名验证。该代码库的CI在Linux、Windows及Python 3.9环境下均显示正常；即便在这台机器上重新克隆代码库，各项检查也全部顺利通过。
参考信息（供AI代理使用）
本文的剩余部分是一份参考手册，供编程助手（或是未来的我）直接照搬使用。前文为普通文字描述；后文则经过结构化处理，便于快速浏览，也适合工具读取。下方列出了所有相关信息：每一个标记、每一个组件类、window.UITheme与window.UIComponents上的每个公开方法、每一种主题、每个script标签的配置项、每个适配器、完整的安装路径、对比度规范以及版本信息。
文件清单
这个代码库中有两个重要的部分：一个是应用程序会直接复制使用的软件包，另一个则是用于构建该软件包的设计与工具。本文讨论的就是这个软件包。
即插即用包 —— 应用会复制的内容（ui-theme/）：
| 文件 | 大小 | 行数 | 用途说明 |
|---|---|---|---|
ui-theme.js |
23,515 字节 | 575 | 运行时功能：在页面首次渲染前应用保存的主题；通过 data-default="auto" 自动匹配系统的浅色/深色模式；填充主题选择器内容、同步标签页状态，并暴露 window.UITheme 接口 |
ui-theme-base.css |
13,255 字节 | — | 基础样式定义：页面文本、链接、标题、代码显示效果、焦点轮廓、滚动条样式、减少动画设置、文本层级样式，以及 .ui-markdown 和 highlight.js 的高亮配色 |
ui-components.css |
51,344 字节 | — | 组件样式定义：按钮、输入框、复选框、单选按钮、开关控件、卡片、徽章、提示框、标签页、分段控制器、表格、对话框、菜单、工具提示、消息提示、进度条、代码块以及应用外壳布局 |
ui-theme.css |
86,389 字节（压缩后 21,197 字节） | — | 包含所有十个主题的样式变量，压缩后大小约为 20 KB |
ui-components.js |
5,441 字节 | 135 | 可选功能：提供带主题样式的 confirm()、alert()、prompt() 及 toast() 函数 |
ui-theme.d.ts |
2,841 字节 | — | window.UITheme 与 window.UIComponents 的 TypeScript 类型声明文件 |
update.py |
16,081 字节 | — | 用于安装与更新工具包；会校验每个文件的 SHA-256 哈希值以确保完整性 |
themes.json |
4,089 字节 | — | 主题配置列表：包含主题名称、所属系列、基础配色、预设样式集、调色板及字体信息 |
files.json |
1,401 字节 | — | 供 update.py 校验用的文件哈希值清单 |
VERSION |
30 字节 | — | 工具包版本信息（示例：ThemeForge 1.0.0 3db64d9f574f） |
README.md |
6,342 字节 | — | 工具包的使用说明文档 |
adapters/quasar.css |
24,997 字节 | — | NiceGUI 与 Quasar 框架的样式映射配置 |
adapters/quasar.js |
1,468 字节 | 40 | NiceGUI 与 Quasar 框架间的 JavaScript 桥接代码 |
adapters/tailwind.css |
4,399 字节 | — | Tailwind CSS v4 的 @theme inline 样式映射配置 |
adapters/tailwind-v3.preset.js |
2,915 字节 | 54 | Tailwind CSS v3 的主题预设配置文件 |
用于构建包的设计与工具（不会被复制到应用中）：
| 文件 | 大小 | 说明 |
|---|---|---|
README.md |
6,592 B | 仓库说明文档 |
AGENTS.md |
19,063 B | 供 AI 代理使用的安装指南 |
CHANGELOG.md |
4,425 B | 版本历史记录（1.0.0为首个发布版） |
CLAUDE.md |
1,498 B | 针对 Claude 的使用规范 |
CONTRIBUTING.md |
4,476 B | 主题开发相关指南 |
LICENSE |
1,067 B | MIT许可协议；版权所有 © 2026（上游文件中使用作者真实姓名；网站上显示的是品牌名称；实际文本内容见上游 LICENSE 文件）；不包含在下载包中（上游文件中的版权声明使用了作者真实姓名，网站的内容审核机制将其视为未经许可的身份信息泄露） |
docs/TOKENS.md |
15,391 B | 按分组列出的所有令牌 |
docs/COMPONENTS.md |
13,889 B | 所有组件类及其对应的标记代码 |
docs/THEMES.md |
8,081 B | 各类主题说明、设计要点及添加新主题的方法 |
docs/INTEGRATIONS.md |
10,604 B | 各框架下的安装步骤 |
docs/TEXT.md |
5,465 B | 文本层级划分与 Markdown 格式规范 |
docs/UPDATING.md |
4,134 B | 更新流程、版本锁定、缓存机制以及校验和的作用 |
docs/contrast-report.md |
124,372 B | 对比度检测报告（涵盖10个主题，每行数据对应一个主题） |
docs/theme-template.css |
9,854 B | 供 tools/sync_theme.py 使用的空白主题模板 |
tokens/<theme>.json |
每个约57 KB | 各主题对应的 W3C DTCG JSON 格式令牌数据 |
examples/static-html/ |
3,731 B（含索引文件） | 纯 HTML/CSS/JS 示例 |
examples/fastapi-jinja/ |
2,172 B（含 app.py 文件） | FastAPI + Jinja 示例 |
specimen/index.html |
17,721 B | 本地运行的各主题及组件预览页面 |
tools/check_contrast.py |
43,171 B | 对比度检测脚本（在 CI 流程中运行） |
tools/lint_colors.py |
22,711 B | 用于检查 CSS 代码中颜色值的脚本 |
tools/sync_theme.py |
41,671 B | 根据 src/css/*.css 重新生成 ui-theme.css、tokens/*.json 以及 docs/contrast-report.md |
tools/update.py |
16,081 B | 安装与验证脚本（功能与 ui-theme/update.py 相同） |
tools/screenshots.py |
3,273 B | 用于生成主题预览图并保存至 docs/images/ 的脚本 |
tests/test_tools.py |
17,606 B | Python 单元测试代码（此版本共32个测试，其中1个被跳过） |
tests/run_browser_tests.py |
3,570 B | 针对运行环境的无头 Chrome 浏览器测试脚本 |
tests/runtime.html |
24,930 B | 浏览器测试所需的测试框架文件 |
.github/workflows/ci.yml |
— | CI 配置：执行对比度检测、node --check 检查、单元测试、浏览器测试以及 CRLF 格式检查；支持 Linux、Windows 及 Python 3.9 环境 |
该代码库的 CI 流程包含三个任务：在 Ubuntu 上使用 Python 3.12 执行 checks 任务；在 Windows 上使用 Python 3.11 执行 tools-on-windows 任务；在 Ubuntu 上使用 Python 3.9 执行 updater-on-oldest-python 任务。本地克隆版本中，每个已发布的 JS 文件都能通过 node --check 检查；对比工具也能正确生成审计结果中的所有十行内容；单元测试同样全部通过（在 Linux 系统、Python 3.14 环境下，测试耗时 1.212 秒，共 32 项测试通过，1 项被跳过；测试日期为 2026年10月05日）。
设计令牌（分组、作用、示例值）
每个主题都会解析所有的令牌。下面的数值为 Purple 主题的默认值（即 :root 基值）；其他主题各自的解析值则保存在 tokens/<theme>.json 文件中（DTCG JSON格式）。使用令牌时需采用 var(--名称) 的形式。切勿在应用的 CSS 中重新定义令牌——应为应用变量添加应用前缀（如 --myapp-sidebar-w），或为令牌创建别名（如 --myapp-brand: var(--accent)）。来源：docs/TOKENS.md。
| 分组 | Token | 作用 | 示例（紫色） |
|---|---|---|---|
| 表面色 | --surface-void |
比页面背景更暗（全屏背景色） | #08080f |
| 表面色 | --surface-0 |
页面背景色 | #0e0e1b |
| 表面色 | --surface-1 |
导航栏背景色 | #14142a |
| 表面色 | --surface-2 |
卡片背景色 | #1d1d39 |
| 表面色 | --surface-3 |
悬停状态背景色 | #232342 |
| 表面色 | --surface-4 |
激活状态背景色 | #262648 |
| 表面色 | --surface-sunken |
凹陷区域背景色 | #0a0a14 |
| 表面色 | --surface-overlay |
菜单、弹出层背景色 | #1d1d39 |
| 表面色 | --glass-1/2/3 |
半透明玻璃面板 | rgba(29,29,57,.72/.84/.92) |
| 表面色 | --glass-highlight |
玻璃光泽效果 | rgba(255,255,255,.055) |
| 表面色 | --code-bg |
代码块背景色 | #0b0b16 |
| 文本色 | --text-primary |
主要文本颜色 | #e8e8f0 |
| 文本色 | --text-secondary |
标签、描述文字颜色 | #a0a0bd |
| 文本色 | --text-tertiary |
提示信息、时间戳颜色 | #8d8db0 |
| 文本色 | --text-disabled |
禁用状态下的文本颜色 | #717195 |
| 文本色 | --text-inverse |
浅色背景上的文本颜色 | #0e0e1b |
| 文本色 | --text-link / --text-link-hover |
链接及强调文本颜色 | #a78bfa / #c4b5fd |
| 文本色 | --on-accent / --on-danger / --on-success / --on-warning / --on-media / --on-media-muted |
填充背景上的文本颜色 | #ffffff / #2a0808 / … |
| 强调色 | --accent / --accent-hover / --accent-pressed |
品牌强调色、主要操作按钮颜色 | #7c3aed / #8250f0 / #6d28d9 |
| 强调色 | --accent-subtle / --accent-muted / --accent-glow |
淡色背景、柔和填充色、发光效果 | rgba(124,58,237,.16/.26/.35) |
| 强调色 | --accent-rgb |
供 JavaScript 使用，可生成 rgba(var(--accent-rgb), .2) |
124,58,237 |
| 强调色 | --accent-2 / --accent-2-subtle |
次要强调色 | #5eead4 |
| 操作按钮色 | --cta / --cta-hover / --cta-pressed / --on-cta |
重要操作按钮颜色 | #7c3aed / #8250f0 / #6d28d9 / #ffffff |
| 操作按钮色 | --cta-shadow / --cta-shadow-hover |
按钮的阴影效果 | 0 6px 20px rgba(124,58,237,.28) / .38 |
| 操作按钮色 | --highlight / --highlight-subtle / --on-highlight |
标记、提示信息的颜色 | #fcd34d / rgba(252,211,77,.12) / #251a00 |
| 线条色 | --border-subtle / --border / --border-strong |
表单控件边框颜色，其中 --border-strong 的对比度为 3:1 |
#21213b / #292945 / #6f6f9c |
| 线条色 | --divider |
细分割线颜色 | #21213b |
| 线条色 | --focus-ring / --focus-ring-width / --focus-ring-offset |
焦点环相关属性 | #a78bfa / 2px / 2px |
| 线条色 | --glass-stroke / --glass-stroke-strong |
玻璃面板边框颜色 | rgba(255,255,255,.08/.16) |
| 控件状态 | --selected / --on-selected |
选中/已勾选/激活状态 | 依主题而定 |
| 控件状态 | --unselected-border / --unselected-fg |
未选中状态下的轮廓与文字颜色，对比度均为 3:1 | 依主题而定 |
| 状态色 | --success / --warning / --danger / --info |
各种状态对应的圆点、条形或填充色 | 依主题而定 |
| 状态色 | --success-text / --warning-text / --danger-text / --info-text |
各状态对应的文本颜色 | 依主题而定 |
| 状态色 | --success-subtle / --warning-subtle / --danger-subtle / --info-subtle |
各状态对应的淡色背景 | 依主题而定 |
| 状态色 | --success-border / --warning-border / --danger-border / --info-border |
各状态对应的边框颜色 | 依主题而定 |
| 状态色 | --idle / --idle-text / --idle-subtle / --idle-border / --idle-hover |
中性状态相关颜色 | 依主题而定 |
| 状态色 | --live / --live-text / --live-subtle / --live-border / --live-hover |
“正在运行”状态的指示色 | 依主题而定 |
| 代码/语法高亮 | --syn-bg / --syn-fg / --syn-comment / --syn-keyword / --syn-string / --syn-number / --syn-function / --syn-attr / --syn-tag / --syn-builtin / --syn-type / --syn-variable / --syn-literal / --syn-operator / --syn-title / --syn-addition |
语法高亮配色方案 | 依主题而定 |
| 代码/语法高亮 | --code-header-bg / --code-stroke |
代码块的外框样式（所有主题下均为深色） | 依主题而定 |
| 图表色 | --cat-1 … --cat-12 |
各数据系列的颜色，对比度至少为 3:1 | 依主题而定 |
| 图表色 | --seq-1 … --seq-5 |
从低到高的渐变色彩 | 依主题而定 |
| 图表色 | --div-1 … --div-5 |
分别表示不良、中性、良好状态 | 依主题而定 |
| 图表色 | --chart-grid / --chart-axis |
图表的网格线与坐标轴颜色 | 依主题而定 |
| 聊天气泡 | --bubble-user-text / --bubble-assistant-text / --bubble-user-bg / --bubble-assistant-bg |
用户/助手聊天气泡的颜色 | 依主题而定 |
| 聊天气泡 | --rp-speech / --rp-thought / --rp-shout / --rp-whisper / --rp-ooc / --rp-action / --rp-critical |
角色扮演场景中的气泡颜色 | 依主题而定 |
| 差异对比 | --diff-add-bg / --diff-add-text / --diff-remove-bg / --diff-remove-text |
代码差异对比视图的颜色 | 依主题而定 |
| 字体大小 | --fs-xs / --fs-sm / --fs-md / --fs-lg / --fs-xl / --fs-2xl |
各种字体大小设置 | 依主题而定 |
| 字体粗细 | --fw-medium / --fw-semibold / --fw-bold |
字体粗细等级 | 依主题而定 |
| 字体类型 | --font-sans / --font-mono / --font-display |
不同字体类型集合 | 依主题而定 |
| 间距设置 | --space-1 … --space-8 |
4–64像素的间距值 | 依主题而定 |
| 圆角大小 | --radius-sm / --radius-md / --radius-lg / --radius-pill |
各种控件的圆角尺寸 | 依主题而定 |
| 阴影效果 | --shadow-1 / --shadow-2 / --shadow-3 / --shadow-4 |
不同强度的阴影效果 | 依主题而定 |
| 层级关系 | --z-modal / --z-toast / --z-popover / --z-nav |
各元素的堆叠层级 | 依主题而定 |
| 动画速度 | --motion-fast / --motion-med / --motion-slow / --easing-standard |
动画持续时间设置；启用“减少动画”模式后会停止循环动画 | 依主题而定 |
| Markdown样式 | --md-bold / --md-italic / --md-bolditalic / --md-bolditalic-glow |
Markdown文本样式 | 依主题而定 |
| 其他功能 | --mark-bg / --selection-text / --selection-bg / --media-filter / --quote-bar / --heartbeat-text / --heartbeat-hover / --offline-text / --on-offline / --canvas-handle |
各类小功能相关的颜色设置 | 依主题而定 |
来源：docs/TOKENS.md（共22个分组，约270个Token；执行 grep -oE '\| \(--[a-zA-Z][a-zA-Z0-9-]*)` |' docs/TOKENS.md | sort -u | wc -l可得到272个唯一的Token名称；共有22个## ` 分组）。
组件类（每个修饰符占一行）
状态信息取自原生属性（disabled、checked、aria-pressed、aria-selected、aria-current、aria-invalid、aria-busy），不会额外添加其他类。大多数选择器仅使用一个类，这样后加载的同等优先级应用规则也能生效。所有属性均遵循逻辑属性规范（支持从右向左阅读）。“已选中/已勾选/激活”状态对应 --selected 类；未选中状态表现为轮廓线样式；禁用状态则显示为虚线且无填充效果。来源：docs/COMPONENTS.md。
| 类名 | 修饰符/组成部分 | 说明 |
|---|---|---|
ui-stack |
— | 纵向排列的容器，间距为 --space-3 |
ui-row |
— | 可换行的横向排列容器，内容居中，间距为 --space-2 |
ui-grid |
--ui-grid-min |
自动填充列数的网格布局，min值需在元素上自行设置 |
ui-container |
— | 居中的容器，最大宽度为 --content-max |
ui-spacer |
— | 将行内其余内容推至最右侧 |
ui-app |
__header __nav __main |
应用外壳结构（包含页头、侧边导航与主内容区）；侧边导航在宽度小于760像素时会隐藏 |
ui-brand |
— | 页头处的应用标题 |
ui-nav |
__label __item |
侧边导航菜单 |
ui-title / ui-heading / ui-subheading / ui-lead / ui-kicker / ui-small / ui-mono / ui-num / ui-kbd / ui-code / ui-divider |
— | 文本样式集合（<hr>标签对应 .ui-divider类） |
ui-text-primary / -secondary / -tertiary / -disabled / -link |
— | 不同层级的文本样式类（新代码开发时请使用对应的Token值） |
ui-markdown |
— | 用于承载渲染后的Markdown内容的容器；详情参见 docs/TEXT.md |
ui-btn |
--primary --ghost --outline --danger --cta --sm --lg --icon --block |
按钮样式；同样适用于 <a>标签；可与 aria-pressed、aria-busy、disabled属性搭配使用 |
ui-btn-group |
— | 相邻按钮共享圆角边缘 |
ui-field |
— | 表单字段容器（包含标签、控件及说明文字） |
ui-label |
— | 字段标签 |
ui-input |
--sm |
文本输入框 |
ui-select |
— | 自定义样式的 <select>下拉框；data-ui-theme-picker属性可触发主题选择器 |
ui-textarea |
— | 自定义样式的 <textarea>多行文本框 |
ui-help |
— | 字段说明文字（通过 aria-describedby属性关联相关控件） |
ui-error |
— | 字段错误提示信息（同样通过 aria-describedby属性关联）；仅在 aria-invalid="true"时显示 |
ui-input-group |
— | 输入框与按钮的组合结构（如搜索框组件） |
ui-check |
— | 复选框/单选框/开关的排列容器 |
ui-checkbox |
— | 样式化的原生 <input type="checkbox">复选框 |
ui-radio |
— | 样式化的原生 <input type="radio">单选框 |
ui-switch |
— | 以 role="switch"属性标记的、样式化后的复选框，用于实现开关效果 |
ui-switch-state |
data-on data-off |
“开启/关闭”状态标签（对屏幕阅读器隐藏；开关本身会广播其当前状态） |
ui-range |
— | 原生范围滑块控件，其颜色由 --slider-color属性决定 |
ui-segmented |
— | 功能类似单选按钮组的按钮组 |
ui-tabs |
ui-tab |
标签页组件（链接型标签页使用 <a aria-current="page">标签）；键盘交互逻辑需由应用自行实现 |
ui-card |
__header __title __footer --raised --interactive |
卡片样式；当卡片处于选中状态时，aria-selected或aria-current属性会生成对应的轮廓线 |
ui-well |
— | 凹陷式区域容器（用于展示日志、预览内容或其他次要信息） |
ui-stat |
__label __value |
标签与数值的配对显示结构 |
ui-badge |
--success --warning --danger --info --live --accent --neutral |
圆形徽章样式 |
ui-dot |
--success --warning --danger --info --live --neutral |
状态指示圆点 |
ui-count |
--accent --danger |
计数提示标签 |
ui-callout |
--info --success --warning --danger __title |
带颜色的提示框（出现错误时可设置 role="alert"属性） |
ui-table-wrap |
— | 用于包裹 <table class="ui-table">标签的容器，可实现表头固定及滚动效果 |
ui-table |
--hover --compact td.num |
表格样式配置 |
ui-dialog |
— | 自定义样式的 <dialog>弹窗 |
ui-drawer |
— | 基于 <dialog>实现的侧边抽屉面板 |
ui-menu |
__item |
菜单列表结构 |
[data-ui-tooltip] |
data-ui-tooltip-side="bottom" |
任意元素上的提示框工具 |
ui-progress |
— | 线性进度条样式 |
ui-spinner |
— | 加载转圈动画 |
ui-skeleton |
— | 内容加载时的占位骨架样式 |
ui-breadcrumbs |
— | 面包屑导航列表 |
ui-pagination |
— | 分页组件 |
ui-avatar |
— | 圆形头像样式 |
ui-chip |
__remove |
可移除/可选中的标签样式 |
ui-details |
— | 基于 <details>标签实现的折叠面板 |
ui-fieldset |
— | 带说明标题的表单字段组 |
ui-codeblock |
__bar |
<figure>容器，内部包含 <figcaption class="ui-codeblock__bar">说明文字与 <pre>代码块 |
ui-empty |
— | 空状态提示样式 |
ui-bubble |
--user --assistant |
聊天气泡样式 |
window.UITheme与window.UIComponents的公共方法
来源：ui-theme/ui-theme.d.ts（两个全局对象的TypeScript声明文件）。
window.UITheme（UIThemeApi）：
| 成员 | 类型 | 功能说明 |
|---|---|---|
version |
string（只读） |
文件夹版本，例如 "1.0.0" |
config |
对象（只读） | { themes, default, auto, storageKey, families, printTheme } |
current() |
() => string |
当前激活的主题标识 |
theme([slug]) |
(slug?) => UIThemeInfo \| null |
某个主题的相关信息（若未指定则返回当前主题） |
list() |
() => UIThemeInfo[] |
所有已启用的主题列表 |
set(slug) |
(slug) => string |
切换到指定主题；返回该主题的标识 |
reset() |
() => string |
恢复为默认主题；返回该主题的标识 |
partner([slug]) |
(slug?) => string \| null |
同一系列中的亮色/暗色对应主题（如 laserlloyd ↔ laserlloyd-light） |
toggleFamily() |
() => string \| null |
在系列内切换至对应主题；返回新的主题标识 |
onChange(listener) |
(fn) => () => void |
订阅主题变化事件；返回取消订阅的函数；打印模式下 detail.print 值为 true |
token(name, [el]) |
(name, element?) => string |
获取某个颜色标记的原始值（如 "#7c3aed"） |
tokens(names, [el]) |
(names, element?) => Record<name, string> |
批量获取多个颜色标记的值 |
color(name) |
(name) => string |
获取适用于画布的 rgb() 格式颜色值 |
colors(names) |
(names) => Record<name, string> |
批量获取适用于画布的颜色值 |
mountPicker(target, [opts]) |
(elOrSel, options?) => HTMLSelectElement \| null |
在指定位置创建主题选择器；options 参数格式为 { label, coreLabel, optInLabel, systemLabel } |
当主题发生变化时，document 上会触发 ui-theme-change 事件，事件数据包含 { slug, theme, previous, print }。
window.UIComponents（UIComponentsApi）：（需引入 ui-components.js）
| 方法 | 签名 | 功能说明 |
|---|---|---|
confirm |
(opts: UIDialogOptions \| string) => Promise<boolean> |
带主题样式的确认对话框；选项包括 { title, message, label, confirmLabel, cancelLabel, danger } |
alert |
(opts: UIDialogOptions \| string) => Promise<void> |
带主题样式的提示框 |
prompt |
(opts: UIPromptOptions \| string) => Promise<string \| null> |
带主题样式的输入对话框；用户取消时返回 null；额外选项有 { value, placeholder, type } |
toast |
(message, { kind?, timeout? }) => HTMLElement |
显示提示信息，类型可为 info / success / warning / danger；返回生成的 DOM 元素 |
window.UI_THEME_MANIFEST（可选，优先级高于脚本标签设置）：{ themes, default, defaultDark, defaultLight, storageKey, families, legacy, mirrorAttr, fontsHref, printTheme }。其中 themes 可传入数组或以逗号分隔的字符串。
脚本标签参数（<script> 标签上的 data-* 属性）
| 属性 | 默认值 | 功能说明 |
|---|---|---|
data-themes |
六个核心主题（purple,midnight-gold,glacier,forest,paper,daylight） |
以逗号分隔的已启用主题列表；决定选择器显示哪些主题以及哪些存储值有效。若未设置该属性，ui-theme.js 会默认启用这六个主题，且 set==="core"（ui-theme.js:147-149）。 |
data-default |
第一个启用的主题（即 data-themes 中的首个标识；若无任何主题被启用且非 auto 模式则默认为 purple） |
默认主题标识；设为 auto 则可跟随操作系统设置。字符串 auto 会启用基于 prefers-color-scheme 的自动适配功能（ui-theme.js:164）；若属性缺失或为空，则使用第一个启用的主题（ui-theme.js:177-179）。 |
data-default-dark |
第一个非亮色系的已启用主题（即 data-themes 中 ground !== "light" 的首个标识；若无此类主题则取第一个启用的主题；若仍无则默认为 purple） |
auto 模式下的暗色主题。当操作系统偏好暗色模式且未指定其他值时，ui-theme.js:168-175 会选用此主题。 |
data-default-light |
第一个亮色系的已启用主题（即 data-themes 中 ground === "light" 的首个标识；若无此类主题则取第一个启用的主题；若仍无则默认为 purple） |
auto 模式下的亮色主题。逻辑实现与暗色版一致（ui-theme.js:168-175）。 |
data-storage-key |
ui-theme |
用户所选主题的本地存储键名（ui-theme.js:185）。按照 AGENTS.md §3 的建议，建议设置为 <应用名>.theme，以防同一域名下多个 ThemeForge 应用产生冲突。 |
data-families |
false |
是否在主题选择器中按系列对主题进行分组 |
data-print-theme |
auto |
打印时的主题设置：若当前主题为暗色或 OLED 模式，auto 会自动切换为该系列的亮色对应主题（或首个启用的亮色主题，若无则使用 daylight）；指定具体标识则会直接使用该主题；设为 none 则不进行任何切换；若当前主题为亮色，则按原样打印（ui-theme.js:474-490）。 |
data-legacy-key |
— | 用于一次性迁移的旧版存储键名（需配合 data-legacy-map 使用） |
data-legacy-map |
— | 旧值到新值的映射表，格式为 JSON 对象 |
data-mirror-attr |
— | 将当前主题信息同步至其他属性中（供特定库读取使用） |
data-fonts-href |
— | 用于加载对应主题字体集的样式表链接 |
相关代码来源：ui-theme.js:147-149, 164, 168-174, 185, 474-490（运行时默认值）以及 AGENTS.md §3、§12（推荐设置方式——例如将 data-themes 设为六个核心主题、data-default="auto"、data-storage-key="<应用名>.theme"）。
适配器
| 适配框架 | 对应文件 | 功能说明 |
|---|---|---|
| NiceGUI / Quasar | adapters/quasar.js + adapters/quasar.css |
在引入 ui-theme.js 之后加载 adapters/quasar.js，并在加载 ui-theme.css 后加载 adapters/quasar.css（通过 ui.add_head_html 实现）。Quasar 中的切换开关、复选框及单选按钮均遵循控制状态设计；处于禁用状态的控件会以虚线形式呈现且透明度为 100%。请移除所有 ui.dark_mode() 调用——该适配器会自动处理相关逻辑。 |
| Tailwind CSS v4 | adapters/tailwind.css |
在 @import "tailwindcss"; 之后添加 @import "./<路径>/ui-theme/adapters/tailwind.css";。该适配器提供了 bg-surface-2、text-fg、text-fg-muted、bg-accent、text-on-accent、border-line 等样式变量。因 Tailwind 自带文本尺寸类，故文本相关属性统一使用 fg-* 前缀。 |
| Tailwind CSS v3 | adapters/tailwind-v3.preset.js |
配置方式：presets: [require('./<路径>/ui-theme/adapters/tailwind-v3.preset.js')]。该适配器提供的样式变量与 v4 版完全一致，只是以 v3 预设格式呈现。 |
Tailwind 适配器负责映射主题标记值；Quasar 适配器则负责映射组件样式类。二者均非强制要求，即便不使用它们，整个包的核心功能仍可正常运行。
完整安装流程（原文照录，出自 AGENTS.md 的安装说明）
AGENTS.md 是一份专为 AI 编程助手编写的安装指南。下文完整引用了前两个章节的内容——AI 助手需按此提示执行操作。字符转义规则遵循 article-forge 技能 §8 的要求：原始 <blockquote> 标签内的内容会直接作为 Markdown 渲染，因此 <、>、& 需分别转义为 <、>、&。
## 1. 前期决策 | 问题 | 默认答案 | |---|---| | 文件夹应放置于何处？ | 置于应用的静态资源目录中并原样提供：如 `static/ui-theme/`（Flask、FastAPI、Django）、`public/ui-theme/`（Vite、Next.js、Create React App）、`app/static/ui-theme/`；若仅为独立网页，亦可置于 `index.html` 同级目录下。 | | 需要哪些主题？ | 六个核心主题：`purple,midnight-gold,glacier,forest,paper,daylight`。仅当用户明确要求时方可添加可选主题（`night-red`、`electric-yellow`、`laserlloyd`、`laserlloyd-light`）。 | | 默认主题应如何设置？ | 设为 `auto`：即跟随用户的操作系统亮色/暗色设置，直至用户自行选定主题（`data-default-dark="midnight-gold"`，`data-default-light="daylight"`）。 | | 存储键名如何设定？ | 使用 `<应用名>.theme`，例如 `notes.theme`。 | ## 2. 执行安装 在应用根目录下运行命令（需 Python 3.9 或更高版本；请将 `static/ui-theme` 替换为您选定的文件夹路径）：在 Windows 系统中请使用 `python` 或 `py` 替代 `python3`；该命令在 PowerShell、cmd 及 bash 环境下均可执行。该命令会下载安装程序，后者会从 GitHub 获取最新发布包，比对各文件的校验值后写入目标文件夹。后续更新只需运行 `python3 static/ui-theme/update.py` 即可。离线安装时：先在其他位置下载发布压缩包（`.tar.gz`），随后通过 `python3 update.py --source <压缩包路径> --dest static/ui-theme` 指令执行安装，所用 `update.py` 文件位于压缩包的 `ui-theme/` 目录内。 若环境中无 Python，也可采用以下方式： - **Git：** `git clone --depth 1 https://github.com/LaserLloyd/ThemeForge.git ut-tmp`，将 `ut-tmp/ui-theme` 复制到应用目录后删除 `ut-tmp` 文件夹即可。 - **Node.js：** 使用 `npx degit LaserLloyd/ThemeForge/ui-theme#v1.0.0 static/ui-theme` 命令实现。 - **无安装流程（原型开发或单页 HTML 文件）：** 直接从 jsDelivr 加载所需文件，并锁定至指定版本：`https://cdn.jsdelivr.net/gh/LaserLloyd/ThemeForge@v1.0.0/ui-theme/ui-theme.js`（各 CSS 文件亦采用相同路径）。切勿使用 `@main` 作为版本标识——CDN 会将其缓存最长达 12 小时。若要更新内容，只需修改版本号即可；此时无需执行 `update.py` 及下文第 8.5、9、10 条操作。python3 -c "import urllib.request as u,sys;sys.argv=['update.py','--dest','static/ui-theme'];exec(u.urlopen('https://raw.githubusercontent.com/LaserLloyd/ThemeForge/main/ui-theme/update.py').read())"
AGENTS.md 的其余章节（第 3 至 12 节）依次介绍了头部代码块的配置方式、主题选择器的实现、基于颜色标记生成样式的方法、各类设计规则、图表绘制说明、校验流程，以及如何在应用自身的 AGENTS.md 中加入指定语句以确保后续 AI 助手能延续既定规范；此外还给出了更新指令、故障排查表及上文提及的各项参考信息。
对比度审核结果（各主题汇总）
每次代码提交时，tools/check_contrast.py 脚本都会在 CI 环境中运行。完整报告位于 docs/contrast-report.md，文件大小约 124 KB；内容包含每个主题的详细检测数据及整体总结，其中摘要如下：
| 主题 | 所属集合 | 测试配置 | 检测项总数 | 未达标项 |
|---|---|---:|---:|
| purple | 核心主题 | 标准配置 | 147 | 0 |
| midnight-gold | 核心主题 | 标准配置 | 147 | 0 |
| glacier | 核心主题 | 标准配置 | 147 | 0 |
| forest | 核心主题 | 标准配置 | 147 | 0 |
| paper | 核心主题 | 标准配置 | 147 | 0 |
| daylight | 核心主题 | 标准配置 | 147 | 0 |
| electric-yellow | 可选主题 | 标准配置 | 147 | 0 |
| laserlloyd | 可选主题 | 标准配置 | 147 | 0 |
| laserlloyd-light | 可选主题 | 标准配置 | 147 | 0 |
| night-red | 可选主题 | 夜间模式 | 171 | 0 |
所有主题均需符合的规范： 正文文本对比度需达 7:1，次级文本为 6:1（即 docs/contrast-report.md 中所称的“6:1 标准承诺”；该文档中所有 text-secondary on surface-2 相关记录均以此表述标注）；任意表面上所有文本层级的对比度均须不低于 4.5:1；禁用状态的控件对比度需达 3:1；位于 on-accent 或 on-status 状态下的文本对比度亦须为 4.5:1；各类状态文本在其对应着色背景下的对比度同样需满足 4.5:1；处于选中状态的文本对比度也须达到 4.5:1；任意表面上未选中与已选中控件、边框及前景色的对比度均需为 3:1；强边框、控制轨道及焦点环的对比度亦须达 3:1；在 --syn-bg 背景下的语法高亮颜色对比度需为 4.5:1（注释类文本则要求 3.5:1）。开关控件形态规则： “开启”状态控件以 --selected 色填充；“关闭”状态控件仅呈现 --unselected-border 轮廓；切换开关的“开启”态会在旋钮上添加横条，“关闭”态则呈现环形轮廓。禁用状态处理： 即便处于开启状态，禁用状态的控件也会显示为虚线且无填充效果。
各框架适配说明
依据 docs/INTEGRATIONS.md 所述：可适配的框架包括 纯 HTML · FastAPI、Flask、Starlette（Jinja 模板） · Django · Vite、Vue、Svelte、SvelteKit、Astro · Next.js（应用路由模式） · NiceGUI（Quasar） · Tailwind CSS · Electron、Tauri、pywebview · 字体配置 · 图表绘制 · 内容安全策略。各框架下的操作方式一致：将 ui-theme/ 文件夹置于静态资源目录中，按 AGENTS.md §3 要求的顺序插入头部代码块，并确保该文件夹启用无缓存机制（或对 URL 进行版本控制），如此方可确保更新内容及时生效。仓库内提供了两个具体示例：examples/static-html/（单页示例）以及 examples/fastapi-jinja/（FastAPI + Jinja 实现，其 app.py 文件大小仅为 2,172 字节）。
-
打印功能 —
data-print-theme参数用于控制打印时所使用的主题（ui-theme.js:474-490）：当当前主题为深色模式或 OLED 模式时，若设为auto，则会自动切换为该主题对应的浅色版本（即该系列中的第一个已启用的浅色主题，或是daylight主题）；若设为某个具体主题名称，则按该主题进行打印；若设为none，则不进行任何切换。当当前主题为浅色模式时，页面将按原样打印。打印功能还会隐藏侧边导航栏、提示信息、菜单、抽屉组件以及工具提示。 -
prefers-contrast: more— 所有主题都会增强线条的对比度，并将三级文本的对比度提升至二级水平。 -
prefers-reduced-motion— 此设置会停止所有动画循环并缩短动画时长；此时--motion-*相关变量的值将变为 0。
版本信息
本文所述代码来自 2026年10月5日克隆的仓库：
$ git log -1 --format='%h %ci'
56fb665 2026-10-05 21:46:52 +0900 # ThemeForge 1.0.0
$ cat ui-theme/VERSION
ThemeForge 1.0.0 3db64d9f574f
$ wc -c ui-theme/*.js ui-theme/*.css ui-theme/*.ts ui-theme/*.py 2>/dev/null
23515 ui-theme.js
5441 ui-components.js
2841 ui-theme.d.ts
16081 update.py
13255 ui-theme-base.css
51344 ui-components.css
86389 ui-theme.css
$ node --check ui-theme.js ui-components.js
(node v24.18.0) — 两个文件均通过检查；adapters/quasar.js 与 adapters/tailwind-v3.preset.js likewise。
$ python -m unittest discover -s tests
共执行了32项测试，耗时1.212秒。
全部通过（有1项被跳过）。
$ python tools/check_contrast.py --fail-on any
…
## 总结
| 主题 | 集合 | 配置档 | 检查项数 | 失败数 |
| purple | core | standard | 147 | 0 |
| midnight-gold | core | standard | 147 | 0 |
| glacier | core | standard | 147 | 0 |
| forest | core | standard | 147 | 0 |
| paper | core | standard | 147 | 0 |
| daylight | core | standard | 147 | 0 |
| electric-yellow | opt-in | standard | 147 | 0 |
| laserlloyd | opt-in | standard | 147 | 0 |
| laserlloyd-light | opt-in | standard | 147 | 0 |
| night-red | opt-in | night | 171 | 0 |
兼容目标浏览器：当前版本的 Chrome、Edge、Firefox 以及 Safari（2024年或之后发布的版本）。该主题系统使用了 :has()、color-mix() 以及 Popover API；在较旧的浏览器中，颜色显示虽不受影响，但部分组件状态与菜单功能可能会有所降级。
相关链接：ChatForge：专为 Copilot Key 设计的本地 NPU AI 助手 · StudioForge：仅依赖 GPU 运行的 LLM 服务器 · DisPatch：可自托管的 AI 聊天系统 · 我的本地 AI 代理技术栈 · 如何让 LLM 将任意项目适配至你的系统
下载
仅限个人使用免费。如果它替你省下了一下午的时间，欢迎点旁边的咖啡按钮支持一下。