dsh-theme-plugin

Chinese traditional colors as a DeepSeek Harness theme pack. 49 anchor colors × light/dark = 98 themes, each writing the full token vocabulary (98 tokens: 89 --dsw-* plus 9 --shiki-token-* syntax slots) and clearing WCAG AA on all 3136 contrast assertions. Twelve of the anchors are marked as a curated shortlist.

📖 中文文档

Install

npx -y @deepseek-ai/dsh plugin --profile web add dsh-theme-plugin@latest
npx -y @deepseek-ai/dsh --profile web          # boot → open http://127.0.0.1:3080/

This pulls the prebuilt bundle from npm — no clone, no build step. The web profile is created on first boot under ~/.dsh/profiles/web.

• Verify — the browser console logs registered 98/98 themes (49 light / 49 dark), and dsh --profile web --dump-config shows a theme-zhongguo row.
• Update — run the same add command again.
• Uninstall — dsh plugin --profile web remove dsh-theme-plugin

Usage

Open Settings → Traditional Colors and pick a theme; it applies immediately. Themes also have deep links:

http://127.0.0.1:3080/#theme=zhuqing-light      # 竹青 light
http://127.0.0.1:3080/#theme=qunqing-dark       # 群青 dark

Changing the hash switches themes live. A deep link wins over your remembered pick. The remembered pick lives in localStorage, not in settings.yaml, so it does not follow you across devices.

Four ways to find a theme

The panel references nothing but --dsw-* tokens, which is why it changes color with your pick and doubles as a preview of whatever you are about to choose.

Design: 纸 · 帘 · 印

Chinese painting does not start with color. It prepares the paper, washes over it, and signs last. These themes are built in that order, and the three characters name three layers.

纸 Paper — about 60% of the screen. The ground is not "the traditional color, lightened"; it is a different material. Four families — 素绢 raw silk, 熟宣 sized xuan, 雪青 violet-tinted silk, 赭纸 ochre paper — carry deliberately separated chroma (OKLab ≈ 0.010 / 0.019 / 0.015 / 0.024 respectively), so the four papers are told apart by eye and not only in the data. Light grounds sit at L ≈ 0.963–0.971: off-white rather than white, which is what leaves room for a raised surface above them.

帘 Veil — about 25%. The sidebar and message bubbles are the anchor color itself, undiluted by paper, held inside a band of 1.25–1.55 contrast against the paper so the wash can neither disappear nor harden into a slab. You recognize which traditional color you are in by the bubbles, not by the background.

印 Seal — the focus is the anchor itself. The primary button and the send button are the anchor pressed darker. This reverses the pack's original law, under which the primary button was filled by a curated relative of the anchor sitting a median 109° away in hue — so choosing 竹青 handed you a crimson call-to-action. That relative is still chosen, still recorded per theme as sealName / sealRel / sealWhy, and now appears only as the active-nav accent: a signature rather than a focus. The picker shows the reasoning ("茜红 · 策展印 · 冷暖对冲").

Ink — text, rules and secondary surfaces run down one ink ramp, the paper color pushed darker. Every nb-XX step of the base stylesheet becomes a tinted neutral of the same lightness, and hover offsets, elevation steps, borders and interaction alphas are copied verbatim: hue changes, relations do not. The ramp's two endpoints are the deliberate exception — those are set here rather than inherited, because the base stylesheet's are the extremes. Light and dark now share one shape: body 16.7–17.5, secondary 7.4–8.0, tertiary 4.6–5.5.

Syntax — the code block is where a programmer's eyes actually live, so the highlighter is themed too. The harness highlights through shiki's css-variables theme (nine --shiki-token-* slots), and every theme fills them: the five chromatic slots (keyword / string / constant / function / parameter) keep the hue conventions programmers already know, but each color is a real named color picked from the 742-color roster; when the anchor's hue falls within a slot's window, the anchor itself plays that slot — in 竹青 the strings are 竹青, in 群青 the constants are 群青. Comments and punctuation are ink, not color: the tertiary and secondary ink steps re-gated against the code-block ground. All nine slots clear 4.5 on that ground, and the five chromatic slots are asserted pairwise ≥ 15° apart in hue.

Gates — AA is a floor, and elegance lives at the ceiling, so most rules are two-sided. pnpm check re-derives every claim above from the emitted tokens: 3136 contrast rows, plus invariants for veil chroma, the single focus (both focus tokens must be the anchor's own hue and the most saturated patches on screen), syntax-slot hue separation, the anchor-on-stage rule, elevation direction, and full token coverage. It trusts nothing the generator says about itself.

Six tiers — 49 color names are not a usable set of options for someone who does not already know traditional colors, so every theme also carries a "how do I want to work today" tier. It is derived: the only inputs are the anchor's OKLab lightness, chroma and hue.

L < 0.50 ─┬─ C < 0.13 → 夜航 Night   (dark and quiet)
          └─ C ≥ 0.13 → 爆肝 Crunch  (dark and fierce)
C < 0.115 ──────────→ 禅定 Zen       (pale and quiet)
warm (h<120 or h≥315) ─┬─ L < 0.71 → 攻坚 Push  (warm and fierce)
                       └─ L ≥ 0.71 → 收工 Ship  (warm and bright)
cool ───────────────→ 心流 Flow      (cool and saturated)

The picker orders them as a programmer's day: Flow at dawn → Zen in the afternoon → Push in the evening → Crunch at midnight → Night in the small hours → Ship at daybreak → Flow again. Anchors land 心流 11 · 禅定 12 · 攻坚 8 · 爆肝 4 · 夜航 8 · 收工 6.

An earlier design gave each of five moods one representative theme, which left most rows in the picker with an empty tag — it read as missing data rather than restraint. As a partition the vocabulary stays at six words while every theme belongs to exactly one tier, so the tag has no holes and doubles as a filter. Six is this data's natural granularity: a seventh cut anywhere carves out a 1–3 theme sliver, at which point the label names a few themes rather than classifying them. The tier names are an editorial claim, but that is six claims rather than 49; pnpm check pins all four cuts with seven sentinels (群青→Flow, 碧螺春绿→Zen, 朱红→Push, 覆盆子红→Crunch, 满天星紫→Night, 黛紫→Night, 雄黄→Ship), so breaking the tree trips the gate while renaming a tier does not.

Curation — twelve of the 49 anchors carry a curated flag, reachable through Curated only. Both light and dark variants must contain no generator degradation. The list is derived in three passes: editorial seeds → one per tier (every tier must survive the narrowing, or its chip would have nothing to offer) → farthest-point sampling in OKLab up to twelve. Every top-up picks the anchor farthest from what is already chosen, so covering all six tiers costs nothing in spread.

Anchors per paper family: 素绢 12 · 熟宣 14 · 雪青 17 · 赭纸 6. Within one mode, the two closest themes still differ by ΔE 0.018 across the four signature dimensions (ground, brand, bubble, focus) against a 0.015 floor.

Theme roster

⭐ marks the twelve curated anchors the picker shows first. Display names are <name>·亮 / <name>·暗, e.g. 竹青·暗. Paper families: 素绢 raw silk, 熟宣 sized xuan paper, 雪青 violet-tinted silk, 赭纸 ochre paper. The seal column is the curated relative described above — a signature mark, not the button color.

The roster is whatever the generator emits; it is not maintained by hand.

Development

Requirements: Node.js 20+ and pnpm 10.15 (declared through packageManager). Tests use tsx, so the same command works on Node 20 and newer.

git clone https://github.com/nevertoday/dsh-theme-plugin
cd dsh-theme-plugin
pnpm install && pnpm build          # builds lib/client.js, the browser bundle
dsh plugin --profile web add -w .   # register this directory
dsh --profile web

• -w is required because the profile directory is a pnpm workspace root. add links the directory and appends the package to dsh.profile.bundles; the loader then reads lib/client.js from your working copy, so pnpm build is what makes changes visible.
• The repo ships an .npmrc with auto-install-peers=false. Without it pnpm ≥ 9 cannot install: it tries to fetch the optional @deepseek-ai/* peers, and one of them depends on a package that was never published.
• pnpm build needs tsdown; node scripts/build-esbuild.mjs is the fallback.
• Committing lib/ is optional. The primary build is currently about 640 KB plus a 934 KB sourcemap (the esbuild fallback is a little larger); both builders are held below 680 KB / 1020 KB release budgets.

DSH 0.1's client boot manifest does not carry host plugin config, so this package intentionally exposes no cordis.yml config block. User choices enter through the picker or #theme= and persist in the browser.

Gates — pnpm check (3136 contrast rows plus invariants) and pnpm test (60 tests, including a load-time lock on lib/client.js). Neither needs a running harness.

Regenerating the themes — pnpm generate reads the color data and OKLab math from the 中国传统色 repository. Point it there:

ZH_COLORS_REPO=/path/to/zhongguo-traditional-colors pnpm generate

It also looks one directory up and at a sibling checkout, so a conventional layout needs no environment variable. The two executable inputs are pinned by SHA-256 to upstream revision 3f5fc62; review and update those fingerprints before accepting an upstream change. The generator is deterministic — no clock, no randomness — so an unchanged input must reproduce byte-identical output.

License

MIT — see LICENSE.