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.
- zhongguo-traditional-colors treats every recommended color as a citation to a named entry, refusing to synthesize unnamed in-betweens.
- Its ensure() function fixes failing contrast by moving only OKLab lightness while pinning hue and chroma, then labels the result nudged instead of disguising it.
- A single anchor color fans out into a locked palette, a shadcn theme in OKLCH, a 16-slot ANSI terminal palette, and ten agent skills, all with no framework and no build step.
- The gallery reimplements color math the shared kernel already provides, and the two disagree about what counts as neutral.
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.
中华传统色演示、色卡浏览与颜色知识科普开源项目
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 色清单完整覆盖。
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.
- 742 named colors, each with a card image and a static page
- 8,904 harmony sets across 12 relationship types
- A five-slot palette generator with locks and shareable URLs
- A shadcn Theme Forge exporting globals.css in OKLCH
- A 16-slot ANSI terminal palette with configs for three terminals
- 10 agent skills that bundle the data
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 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.
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.
| Tool | Named corpus with provenance | Harmonies from real entries | Labeled contrast fix | Theme / token export | Terminal export | Agent skills |
|---|---|---|---|---|---|---|
| zhongguo-traditional-colors | 742 named colors, card images and values | 8,904 sets across 12 relationship types | OKLab nudge, flagged nudged | shadcn tokens in OKLCH, globals.css | 16 ANSI slots, 3 configs | 10 xxd-* skills |
| Zhongguose | Named Chinese colors | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources |
| Nippon Colors | Named Japanese colors | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources |
| Coolors | Palette generator, not a named corpus | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources |
| Color Hunt | Curated palettes, not a named corpus | Not established in available sources | Not established in available sources | Not established in available sources | Not established in available sources | Not 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地址:
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.





