oklch-terminal-themes

这是一个包含485个终端配色方案的规范数据集，已转换为OKLCH格式，源自`mbadolato/iTerm2-Color-Schemes`，并作为npm包和JSON API重新发布。该数据集设计用于Astro站点、主题选择器、Tailwind v4的`@theme`块以及任何需要干净OKLCH调色板而无需解析iTerm XML或Alacritty TOML的工具。

This is a curated dataset containing 485 terminal color schemes, converted to OKLCH format, sourced from `mbadolato/iTerm2-Color-Schemes`, and republished as an npm package and a JSON API. This dataset is designed for Astro websites, theme selectors, the `@theme` block of Tailwind v4, and any tools that require clean OKLCH color palettes without the need to parse iTerm XML or Alacritty TOML configurations.

原始信息汇总

数据集概述

oklch-terminal-themes 是一个包含 485 个终端颜色主题 的规范化数据集，所有主题已转换为 OKLCH 色彩空间。数据源自 mbadolato/iTerm2-Color-Schemes 仓库，并重新发布为 npm 包和 JSON API。

核心特性

• 主题数量：485 个终端颜色主题
• 色彩空间：OKLCH（含十六进制与 OKLCH CSS 表示）
• 设计用途：适用于 Astro 站点、主题选择器、Tailwind v4 @theme 块以及需要纯净 OKLCH 调色板的工具
• 在线演示：https://williamzujkowski.github.io/oklch-terminal-themes/

安装与使用

bash pnpm add @williamzujkowski/oklch-terminal-themes

提供三种数据集格式：

• 完整数据集：服务端/构建时使用，包含所有颜色对象的 JSON
• 精简数据集：客户端/主题选择器使用，颜色为可直接粘贴的 oklch() CSS 字符串
• 索引数据集：支持懒加载单个主题

数据结构

每个主题记录包含以下字段：

字段	说明
name	主题名称（如 "Dracula"）
slug	主题标识符（如 "dracula"）
isDark	是否为深色主题
tags	标签数组
source	数据来源（iterm2-color-schemes）
sourceUrl	上游文件的深层链接
upstreamSha	上游提交哈希
updatedAt	ISO 8601 格式更新时间
colors	20 个颜色键（background、foreground、cursor、selection 和 16 个 ANSI 插槽）
contrast	对比度数据（fgOnBg、minAnsi、minAnsiSlot）

每个颜色对象包含 hex（十六进制）、oklch（L/C/H 对象）和 oklchCss（OKLCH CSS 字符串）。

标签体系

• 亮度：dark / light
• 饱和度：vibrant / muted
• 知名度：popular（匹配知名主题家族如 Dracula、Nord、Solarized）
• 可访问性：wcag-aaa（≥7:1）、wcag-aa（≥4.5:1）、wcag-aa-large（3-4.5:1）、wcag-fail（<3:1）
• ANSI 清晰度：ansi-legible（所有非混合 ANSI 插槽对比度 ≥3:1）
• 对比度等级：high-contrast（>10:1）、low-contrast（<5:1）

构建流程

1. 获取：稀疏克隆 sources.json 中列出的每个仓库，固定到特定提交
2. 转换：通过 culori 库将十六进制转换为 OKLCH，无色相色调强制为 0，明度限制在 [0, 1]，色度限制在 [0, 0.5]
3. 分类：根据 OKLCH 明度判断 isDark，根据色度平均值和 WCAG 对比度生成标签
4. 验证：使用 Zod 模式校验，ΔE2000 < 1.0 的往返验证，以及同源重复标识符检查
5. 输出：生成 themes.json、themes-slim.json、index.json 和按标识符命名的单个 JSON 文件

许可协议

• 许可证：MIT（见 LICENSE 文件）
• 归属：原始颜色主题归属于上游仓库的作者，见 NOTICE 文件

搜集汇总

数据集介绍

构建方式

该数据集系统地整合了来自mbadolato/iTerm2-Color-Schemes等上游仓库的485个终端色彩方案，并全部转换为OKLCH色彩空间。构建流程包括通过稀疏克隆方式获取各来源数据，利用culori库将原始十六进制色值精准转换为OKLCH格式，同时将消色相色调强制归零以保障JSON兼容性。随后基于OKLCH明度判定明暗主题，依据平均色度与WCAG对比度指标自动生成标签分类，并通过Zod模式校验确保数据完整性，最终输出包含完整、精简及按名称索引的多层级JSON数据集。

特点

该数据集的核心特色在于其全面而精细的元数据标注体系。每个主题记录不仅包含20个色彩键（背景、前景、光标、选区及16个ANSI插槽）的十六进制与OKLCH数值，还配套了WCAG 2.x对比度指标、ANSI可读性评估以及vibrant/muted等语义标签。尤为独特的是，数据集通过排除与背景融合的常规插槽来降低误判，确保低对比度插槽不会不合理地标记高质量主题，这一设计显著提升了色彩方案的实用评估价值。

使用方法

数据集以npm包形式发布，支持多种集成方式。构建时可通过导入themes.json获取完整数据集用于服务器端渲染，客户端主题选择器则可加载themes-slim.json以降低传输体积。对于懒加载场景，支持通过index.json按slug动态导入单个主题。CSS自定义属性与Tailwind v4的@theme块可直接调用主题变量，配合themeToCssVars工具函数，开发者能便捷地将OKLCH色彩注入现代Web应用，实现终端色彩方案的实时预览与一键复用。

背景与挑战

背景概述

oklch-terminal-themes数据集诞生于2024年，由William Zujkowski主导构建，旨在解决终端色彩方案在跨平台、跨工具使用时面临的色彩空间不一致与可访问性不足的问题。该数据集汇集了源自iTerm2-Color-Schemes等上游仓库的485套经典终端配色，并统一将其转换至OKLCH色彩空间——一种更贴近人眼感知均匀性的色彩模型。通过提供结构化的JSON格式数据与配套的npm包，该数据集为Astro站点、主题选择器、Tailwind v4等现代前端工具链提供了干净、可复用的OKLCH调色板，有力推动了终端主题在设计系统与用户界面中的标准化应用。其附带的可访问性标签与对比度计算，更是为包容性设计提供了量化参考。

当前挑战

该数据集面临的核心挑战首先来自于色彩转换的精度与一致性：将原始iTerm XML或Alacritty TOML格式中的十六进制颜色值转换至OKLCH空间时，需保证色差ΔE2000小于1.0，并妥善处理无色相颜色的JSON序列化问题。其次，数据集的维护需要应对上游配色方案的频繁更新与变更，因此构建了每周自动运行的GitHub Actions工作流，用以发现冲突与重复条目。此外，在跨源合并过程中，需要按预定优先级处理slug冲突，并保留完整的溯源信息。最后，为保障可访问性，数据集引入了基于WCAG 2.x标准的体文字比与ANSI色块对比度校验，需在色彩丰富与对比达标之间寻找微妙平衡。

常用场景

经典使用场景

在终端色彩领域，该数据集作为一套经过OKLCH色彩空间标准化的经典色彩方案集合，最常用于前端主题选择器与设计系统构建。开发者可借助其提供的485套完整终端配色方案，轻松实现主题的实时预览、切换与持久化。数据集不仅提供了原始的OKLCH值，还预计算了符合WCAG标准的对比度指标，为无障碍设计提供了量化依据。通过npm包集成，它能在Astro站点、Tailwind v4配置或任何需要纯净色彩调色板的工具中直接使用，极大简化了从设计到代码的色彩传递流程。

解决学术问题

该数据集解决了终端色彩方案在跨平台、跨工具间因色彩空间差异导致的色彩失真与对比度不可控问题。传统终端配色方案多基于sRGB或HSL，缺乏对感知均匀性（如亮度与色度）的量化描述，使得同一方案在不同显示器上呈现效果迥异。通过将所有方案转换为OKLCH色彩空间，并计算前景与背景的WCAG对比度比值，数据集为色彩渲染一致性提供了可复现的数学基础。此外，它系统性地定义了“可读性”（ansi-legible）标签，解决了非混合ANSI色槽与背景色对比度不足导致的终端界面辨识度下降问题。这一工作为色彩偏好研究、用户界面可用性评估以及色彩无障碍标准在文本终端领域的应用奠定了数据基石。

衍生相关工作

该数据集从上游项目mbadolato/iTerm2-Color-Schemes派生，继承了其丰富的社区主题资源，并通过自动化CI流程每周同步上游变更，确保数据的新鲜度与溯源性。其衍生工作包含多种工具与接口：基于Zod的验证层确保了数据结构的一致性；按需懒加载的索引机制（index.json + 分片主题JSON）支持大规模主题库的渐进式获取；对比度计算与标签分类（如wcag-aaa、ansi-legible）可直接用于自动化无障碍检测工具，如自动标记不符合对比度标准的设计稿。此外，该数据集已催生出基于OKLCH的色彩优化脚本，用于将旧有sRGB方案转换为更宽色域、更准确的显示值，进一步扩展了其在新一代色彩管理管线中的应用边界。