Skip to content

oklch-terminal-themes

908 terminal color schemes converted to OKLCH and republished as an npm package and a JSON API. Each theme carries WCAG contrast data, colorblind-safety scores and a derived chart palette, so a site or tool can choose colors by what was measured. Remarque’s Palette Deck is built from it.

Metadata

Status
Active
Version
0.10.0 (2026-10-27)
Stack
TypeScript, culori, Zod, apca-w3, Astro
Started
2026-04-20
License
MIT, with per-theme upstream licenses
Source
github.com/williamzujkowski/oklch-terminal-themes
Package
npmjs.com/package/@williamzujkowski/oklch-terminal-themes
Live demo
williamzujkowski.github.io/oklch-terminal-themes

Architecture

The package is a build pipeline plus its generated output. A weekly GitHub Action re-runs the pipeline and opens a pull request if any upstream source changed. The steps are:

  • Fetch — sparse clones of every repository listed in sources.json, each pinned to a SHA in .upstream-shas.json.
  • Convert — hex to OKLCH with culori. Lightness is clamped to 0–1 and chroma to 0–0.5, and an achromatic hue is coerced to 0 so the JSON stays valid.
  • Classify — isDark from OKLCH lightness, tags from average chroma, WCAG contrast and name heuristics, plus the cvd and apca blocks.
  • Validate — a Zod schema, a within-source duplicate-slug guard and a ΔE2000 round-trip gate under 1.0. The gate measures the published values, and the README gives the current corpus maximum as 0.5439.
  • Emit — themes.json, themes-slim.json, index.json and one JSON file per theme, with static CSS, base16/base24 YAML and W3C design-token files for each.

The package is ESM only and needs Node 22 or later. Every theme has 20 color keys: background, foreground, cursor, selection and the 16 ANSI slots. Of the 908 themes, 688 are dark and 220 are light; 860 come from mbadolato/iTerm2-Color-Schemes and 17 are authored in the project itself, with the rest drawn from other upstreams.

What it measures

WCAG contrast

The contrast block holds the foreground-on-background ratio, the worst non-blend ANSI slot, and cursor and selection ratios. The WCAG tags are driven only by this block. Counted from the 0.10.0 data, 882 themes carry wcag-aa (a foreground ratio of at least 4.5), 813 of those also clear 7 and carry wcag-aaa, 16 land between 3 and 4.5, and 10 fall under 3.

APCA, as data

The apca block holds signed Lc scores computed with the apca-w3 reference implementation, for all 908 themes. Nothing in the package tags or gates on them. The README’s stated reason is that APCA is still evolving outside the W3C standards process, and its example is github-dark, which passes WCAG AA at 6.09:1 with an APCA score of only −43.5.

Colorblind safety

The cvd block simulates deuteranopia, protanopia and tritanopia with culori’s filters (Machado, Oliveira and Fernandes, 2009) in linear-light RGB, then takes the minimum pairwise ΔE2000 among the six classic ANSI hues. A theme is tagged cvd-safe only if both the deuteranopia and protanopia scores are at least 10. In 0.10.0, 24 themes are tagged cvd-safe and 884 cvd-caution. The README says plainly that most themes are decorative community palettes never designed for this, so a low pass rate is not a bug.

Dataviz blocks

Every theme has a derived dataviz block: a categorical set of 6 to 8 colors picked by farthest-point hue selection from the chromatic ANSI slots, a 7-step sequential ramp from background to accent, and a 7-step diverging ramp. Sequential and diverging colors are gamut-fitted at every step. Where a theme has too few chromatic slots to fill a categorical set, the shortfall is derived from its accent and categoricalSynthesized says how many entries are synthetic. The README counts 33 such themes.

Pairs and accents

counterpart links a theme to its canonical opposite-polarity theme, from a slug-stem heuristic plus a small curated map. In 0.10.0 there are 97 light themes with a counterpart. The field is directional and not always symmetric: tokyonight-storm points at tokyonight-day, which points back at the bare tokyonight. accent is the theme’s signature color, taken from the cursor when it is chromatic and otherwise from the most chromatic classic ANSI slot.

How Remarque consumes it

  • The bridge. remarque-theme <light-slug> derives a full Remarque palette from a theme and its counterpart, keeping the theme’s hue and chroma and solving lightness only where a contrast target fails. The accent heuristic above is the one the bridge already used.
  • The default palette. Remarque’s own tokens-palette.css is bound to the remarque-light and remarque-dark native themes. A golden gate compares every color token against what the bridge derives and fails on drift beyond ΔE2000 2.0.
  • The Palette Deck. The 15 curated pairs in deck.css are built from the dataset, pinned to the exact version 0.10.0 as a dev dependency, and audited with remarque-audit. All 97 counterpart pairs in 0.10.0 derive and pass. The dataset is an optional peer dependency, so a site that uses the prebuilt deck installs nothing extra.
  • Policy stays in Remarque. The audit gates on WCAG 2.x ratios and does not read the APCA data. The dataset exposes the numbers, and Remarque decides what to enforce.

Design Decisions

Derived fields are references where possible

accent points at an existing slot’s color rather than inventing one, and a validation script asserts the equality. Categorical entries follow the same convention, except for the synthesized ones described above. Newly derived colors, the sequential and diverging ramps, go through the same ΔE2000 round-trip gate as converted ones.

Licenses are not uniform

Most of the corpus is MIT, but some sources are Apache-2.0 or BSD-3-Clause, and the project’s own MIT license covers the pipeline and the native themes, not the upstream artwork. Each theme records its source, and the README advises checking it before redistributing a subset.

Changelog

  • 2026-04-20 — 0.1.0, first npm release.
  • 2026-07-23 — 0.2.0 adds counterpart and the Remarque Light and Dark native themes; 0.3.0 adds accent; 0.5.0 adds dataviz; 0.6.0 adds cvd and apca; 0.7.0 adds base16/base24 YAML and static CSS per theme.
  • 2026-10-03 — 0.9.0 refreshes the dataset from 644 to 742 themes.
  • 2026-10-27 — 0.10.0 refreshes it from 742 to 908 themes, removing none and recoloring five.