zhongguo-traditional-colors Refuses to Invent a Single Color

Inside a no-build static site that turns 742 named Chinese traditional colors into palettes, shadcn themes, and terminal configs, and the OKLab trick that keeps every name honest.

9 min read • View on GitHub • More from nevertoday

A wide view of a traditional paint shop wall receding into the distance, with hundreds of shallow labeled drawers pulled slightly ajar and a hand in the foreground holding one labeled color chip up to a hanging lamp. The single lit chip shows the project's thesis: a finite, labeled archive where colors are selected by name instead of mixed.
A finite, labeled archive. The project selects colors by name instead of mixing new ones.
Key Takeaways

The Color That Cannot Be Made Up

Most palette tools will invent a color for you. Drag a slider and the machine interpolates a pleasant in-between: a color with no name, no history, no provenance. zhongguo-traditional-colors does the opposite. Every color it recommends is a real, named traditional Chinese color, and every pairing is a citation to two entries that already exist in its library.

The project calls this a provenance contract, and it has two halves. Harmony relationships link real library entries rather than generating new ones. And when a color has to be adjusted to pass a readability check, the adjustment happens in OKLab lightness space, holding hue and chroma steady, and the code labels the result as nudged. The name survives the math.

That single rule, do not invent, is what separates this project from a shelf of color galleries. The rest of the codebase exists to keep the promise.

中华传统色演示、色卡浏览与颜色知识科普开源项目

nevertoday, Repository owner · nevertoday/zhongguo-traditional-colors

742 Drawers, One Rule

The corpus is a package, not a poster. 742 named colors, each one shipping as a high-resolution card image, a set of values (HEX, RGB, CMYK), mood keywords, and a static, indexable page. The README states the coverage plainly.

这里收录 742 张中华传统色高清色卡,已按原始 742 色清单完整覆盖。

nevertoday, Repository author, project README · README.zh-CN.md

The architecture is as plain as the data. No framework, no bundler, no build step. Modules attach to global window.* namespaces and depend on script load order: window.ZH_COLOR_CORE, window.ZH_THEME_FORGE, window.TRADITIONAL_COLOR_HARMONIES. A .nojekyll file and a CNAME are the entire deployment story. The site is served as static files.

What ships on top of that data is the real story. A heritage color list, the kind usually published as a static poster or a Markdown file, has been wired into a working toolchain.

The Math That Keeps a Name Honest

Here is the moment the promise almost breaks. A named color fails a WCAG contrast check. The naive fix is to swap in a different color, which abandons the name. The real fix lives in color-core.js, the shared kernel extracted so Theme Forge and the terminal tool could use the same math.

The file is built on the canonical Björn Ottosson OKLab matrices and WCAG relative luminance. The interesting function is ensure(textHex, bgHex, target = 4.5). If contrast is already sufficient, it returns the color untouched. If not, it walks lightness in OKLab space.

// color-core.js
function ensure(textHex, bgHex, target = 4.5) {
  const ratio = contrast(textHex, bgHex);
  if (ratio >= target) return { hex: textHex, ratio, nudged: false };

  const { L, C, H } = hexOklch(textHex);   // pin chroma and hue
  let best = textHex, bestRatio = ratio;

  for (const dir of [-1, 1]) {              // try darker, then lighter
    for (let i = 1; i <= 26; i++) {
      const l = L + dir * 0.04 * i;         // 0.04 steps
      if (l < 0 || l > 1) break;
      const candidate = oklchHex(l, C, H);
      const r = contrast(candidate, bgHex);
      if (r > bestRatio) { best = candidate; bestRatio = r; }
      if (r >= target) return { hex: candidate, ratio: r, nudged: true };
    }
  }
  return { hex: best, ratio: bestRatio, nudged: true };  // best effort
}

Two details matter. It tries both directions in the for (const dir of [-1, 1]) loop, in 0.04 steps for up to 26 iterations, and returns the first color that passes. And when it does, it sets nudged: true. Only lightness moved. Hue and chroma are pinned, so the color stays recognizably itself. The fix protects the name instead of erasing it.

The ensure() walk in OKLab space. Lightness moves in 0.04 steps while hue and chroma stay pinned, and the first passing step is stamped nudged.

The kernel handles the opposite problem too. Some colored slots are nearly gray. boostChroma(hex, minC) raises chroma while holding lightness and hue, and clamps the scale factor at 3.

// color-core.js
function boostChroma(hex, minC) {
  const { L, C, H } = hexOklch(hex);
  if (C >= minC) return { hex, boosted: false };
  const scale = Math.min(minC / C, 3);   // 限幅:近灰色放大过猛会严重出界,截断后反而偏色
  const out = oklchHex(L, C * scale, H);
  return { hex: out, boosted: true };
}

The Chinese comment on that clamp translates to: amplifying near-gray colors too much pushes them far out of gamut, and per-channel clipping then shifts the hue. The function returns a boosted flag so callers can label the result honestly. Same pattern, same discipline.

Then there is pickNeutral(targetL, anchorHue). NEUTRALS is built by filtering the library to colors with OKLab chroma below 0.045. The function takes the six nearest a target lightness, then sorts them by hue distance to the anchor. The result is a neutral that matches the anchor's lightness and carries a trace of its hue. The comment calls it leaving the ground a breath of the anchor color.

One Anchor, Five Outputs

The generator turns one anchor color into a five-slot palette, and its state model is deliberately small. The URL is the state, so every palette is shareable and bookmarkable. Locks are a parallel array of five booleans, so locked slots survive regeneration. Five methods (auto, analogous, complementary, triadic, neutral) each map to a label.

The search is decoupled through a custom event, color-suggestion-pick, carrying an ID in event.detail. The suggestion widget never has to know the generator exists. The spacebar generates a new palette, but only when focus is not in an input and no dialog is open. Small guards like that are the difference between a toy and a tool.

A close-up of two hands holding two labeled color cards side by side, connected by a single taut thread pinned and knotted at both ends, while a third blank card with a faint scribble sits ignored on the table. It shows a harmony relationship as a citation between two real named colors, and the synthesized color the project refuses to recommend.
Harmony as citation. The thread links two real named entries. The erased card is the invented color the project will not recommend.

From there the anchor fans out across output surfaces. Theme Forge emits shadcn semantic tokens in OKLCH for light and dark and exports a globals.css. The terminal tool maps 16 ANSI slots to real named colors, with a limited fallback for legibility, and ships configs for Ghostty, Alacritty, and kitty. Ten xxd-* agent skills bundle the data for AI-assisted workflows.

The README frames the whole thing as one journey, from finding a Chinese color to pairing it, testing it, and shipping it. The output surfaces are where that journey ends.

Where It Sits

The distinction is not that one tool has more features. It is that only one of them treats a color name as something you are not allowed to overwrite.

ToolNamed corpus with provenanceHarmonies from real entriesLabeled contrast fixTheme / token exportTerminal exportAgent skills
zhongguo-traditional-colors742 named colors, card images and values8,904 sets across 12 relationship typesOKLab nudge, flagged nudgedshadcn tokens in OKLCH, globals.css16 ANSI slots, 3 configs10 xxd-* skills
ZhongguoseNamed Chinese colorsNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sources
Nippon ColorsNamed Japanese colorsNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sources
CoolorsPalette generator, not a named corpusNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sources
Color HuntCurated palettes, not a named corpusNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sourcesNot established in available sources

Competitor cells are marked as not established wherever the available sources did not verify them. The point of the table is the shape of the difference, not a scorecard.

Who Built It

The project is the work of one maintainer, nevertoday, known as 小小东 on X. The repository lists a single contributor. The README is written in three languages, which signals an audience wider than Chinese-speaking users.

The origin material is thin. No interview, no conference talk, no documented adoption. What exists is a third-party snapshot of an X post in which the author describes adding generated color relationships and publishing the site, a 742-color Markdown file, and a relationship CSV.

这几天在疯狂优化这个开源项目 争取把中国传统色这个项目,变得更加实用 比如每个颜色: 推导出同类、邻近、互补、分裂互补、三角、四角、冷暖、明暗、灰调、中性色及主辅点缀等配色 更新的有: 1. 网站 nevertoday.github.io/zhonggu… 2. 742 色配色方案 Markdown github.com/nevertoday/zhongg… 3. 742 色配色关系 CSV github.com/nevertoday/zhongg… 下一阶段,想着优化 中华传统配色的用例展示 还有在线配色工具 补充一下这个项目的github地址:

小小东 (@xiaoxiaodong01), Author, as attributed by a third-party snapshot of an X post · TodayRss snapshot of an X post

The next phase named in that post was use-case demonstrations and an online palette tool. Both now exist in the repository. What is not verified is how many people ship with it. The README lists designers, educators, students, and frontend developers as intended users. Those are stated use cases, not documented deployments.

The Seams

One honest observation about the codebase. The shared kernel color-core.js provides HEX parsing, sRGB linearization, and OKLCH classification. But explorer.js, which powers the main gallery, reimplements all three independently. It was probably written before the kernel was extracted, and the two were never reconciled.

The consequence is concrete. They disagree about what counts as neutral.

// explorer.js: HSL hue bucketing
const isNeutral = hsl.s < 13;                        // saturation below 13%

// color-core.js: OKLCH chroma
const NEUTRALS = ALL.filter(c => c.oklch.C < 0.045); // chroma below 0.045

A color can be neutral in one tool and red in another. This is not a takedown. It is the recognizable signature of a tool that grew fast in a vanilla-JS codebase, and it is the kind of thing that is easy to fix and easy to forget. Reconciling the two color models is the obvious next cleanup.