dsh-theme-palette
English · 中文 · 日本語 · Español · Português · हिन्दी
Theme palette for DeepSeek Harness (web & desktop): 4 preset palettes + custom × light/dark, two independent axes.
Settings page: five palettes, strength and panel surfaces
Static render of the settings page at the real panel width (564 px content).
Compatibility
| Surface | Status |
|---|
| DSH desktop / web client | 0.2.x |
| Node.js | 22.19.0+ (on the 22.x line) or 24.0.0+ |
| Changes to host source | none |
The engines field of the package is ^22.19.0 || >=24.0.0 — the row above is the same requirement in prose.
The plugin only stacks colour tokens through ctx.theme.overrideTokens; it does not register a theme, patch the host, or touch the appearance preference.
What it does
- 4 presets + custom — Mono, Warm sand, Indigo, Moss (each adapting to light and dark independently), plus a custom palette derived from three colours;
- the whole ramp is recomputed, not swapped: OKLCH rebuild → role-based chroma → sRGB gamut clamp → contrast solved on real surfaces;
- host colour tokens: 179 for tinted palettes plus 13 plugin-owned tokens, 19 for mono (1080 setting combinations fully scanned); all 66 colour tokens the built CSS actually consumes resolve to the plugin — body, secondary, tertiary, captions, links, sidebars, cards, user bubble, primary button, scrollbars, switches, Markdown headings/bold, code blocks, and now error/success/warning states and the +/− rows of the file diff (the red/green/amber scales join the rebuild for the first time: temperature only, hue rotation capped at 8°, so the semantics never drift);
- adjustable: text tint (3), sidebar depth (3), Markdown emphasis, scrollbars, switch colour;
- custom palette (pick surface / text / accent — the text hue joins the derivation, and a clearly dark or light surface becomes that mode's canvas lightness; the engine keeps its contrast guarantees), config export/import via a
dshs1. code, high-contrast mode, and 4 UI languages;
- self-healing: if the host drops the override layer, the palette is re-applied; after repeated failures auto-restore pauses and the settings page offers a re-enable button;
- contrast promises: body text is promised 12:1 in light and 10:1 in dark (15:1 in high contrast), secondary ≥ 6.2 in light / 8.0 in dark (HC 9 / 9.6), tertiary ≥ 4.85 in light / 6.4 in dark (HC 7 / 7.6), links ≥ 4.95 in light / 4.62 in dark (HC 7; the light floors carry a colour-vision headroom; dark links also clear an APCA Lc ≥ 60 gate, 75 in HC) — measured on the surfaces the text actually lands on (the dark side needs more, because a WCAG ratio overstates readability on a dark background);
- the promised surfaces are light 00/60 and dark 950/875; dark 800 (module surface) and 850 (sub-surface) do not back body text — the report counts them apart as "out of policy" (neither pass nor fail);
- UI in 简体中文 / 繁體中文 / English / 日本語 (follows the host language, can be pinned).
Install
# from npm
cd ~/.dsh/profiles/desktop
pnpm add dsh-theme-palette
To pin a version, use pnpm add dsh-theme-palette@<version> — CHANGELOG.md marks the sections that were never published to npm, so you do not pin one of those.
From a GitHub Release tarball: pick the asset on the releases page and install it with pnpm add <path-to-tgz>.
Then restart the GUI — a running process keeps the old module. Open it from avatar → Settings → Color theme.
Configuration
| Item | Options |
|---|
| Palette | Mono · Warm sand · Indigo · Moss (thumbnails follow light/dark) |
| Strength | Quiet / Standard / Strong — how much body text follows the palette |
| Panel surfaces | Sidebar (Lighter / Same / Deeper). The right panel is never tinted — it is a full-height transparent overlay, so painting it would cover the conversation (the setting was removed in 1.9.10) |
| More options | Language, Markdown emphasis, scrollbars, switches/checks |
Every choice applies immediately and is stored in localStorage. Light/dark stays under the host’s Appearance control.
Palette engine
OKLCH(L, C, hue) ──► gamut clamp (binary search on C) ──► sRGB hex
▲
└── role chroma × intensity, then contrast solve on {canvas, card, sidebar, overlay}
- semantic aliases keep
var(--dsw-static-neutral-bluish-NN) chains, so anything following a token follows the palette;
- light surfaces use steps 00–300, dark surfaces 800–950;
- semantic colours (1.13.5): the host's red/green/amber scales keep their host lightness and only get a temperature harmonisation toward the palette hue (
harmonizeSemantic: hue rotation capped at 8°, chroma scaled to 88–92%) — error stays red, success stays green, warning stays amber, just in the palette's warm/cool key; an achromatic custom palette (pure black/white/grey) is left untouched;
- the coverage claim is testable:
tools/check-host-contract.mjs extracts every colour token the built CSS actually consumes and requires each one to be either declared by the plugin or to end its var() chain in a declared token — 1.13.4 and earlier fail this with 30 leaks (red/green/amber, danger hover, diff rows), 1.13.5 reports zero;
- text floors are enforced at build time: body ≥ 12:1 in light and ≥ 10:1 in dark (high contrast: 15:1), secondary ≥ 6.2 in light / 8.0 in dark (HC 9 / 9.6), tertiary ≥ 4.85 in light / 6.4 in dark (HC 7 / 7.6), link ≥ 4.95 in light / 4.62 in dark (HC 7), link APCA Lc ≥ 60 in dark (HC 75); sidebar and bubble text follow the ramp and measure ≥ 7 (no separate contrast gate);
- the promised surfaces are light 00/60 and dark 950/875; dark 800 (module surface) and 850 (sub-surface) do not back body text — the report counts them apart as "out of policy" (neither pass nor fail), and every surface still has to clear the AA floor of 4.5;
- the report separates three things: the declared target, the physical ceiling (what black or white can reach on that surface) and the policy exemption; 0.93 is only a solver margin, used to decide whether a target sits above the ceiling;
- 1080 configuration combos (5 palettes × 216 settings, both contrast tiers included) are checked by
node palette-dev.mjs.
Design notes, per-component rationale and the contrast tables live in docs/DESIGN.md. Release history: CHANGELOG.md.
Development
npm run report # token report for every palette (add -- --hc for the high-contrast tier)
npm run sheet # palette board → tools/sheet.html
npm run shot-sheet # screenshot the board (headless Chrome/Edge)
npm run compare -- --dir tools/out/<run> # diff against the local baseline
npm run preview -- --lang en # render the settings page
npm run contract # host token / DOM contract (strict: SKIP becomes a failure)
npm run release -- --dry # release preflight
npm run release -- --tag # publish to npm + tag
npm run release -- --ci # CI publish: tag only; Actions publishes via Trusted Publishing
npm run clean # drop local tarballs / tools/out / dist
Screenshot regression has two layers: the palette board (no auth needed) and the real desktop window via CDP (tools/shoot-desktop.mjs, needs --remote-debugging-port). See tools/README.md.
Pitfalls we hit
The five that surprised us most during the 1.7.0 audit — each one was found by a test, not by looking at screenshots.
- A white accent produced a white link (1.13:1). The contrast solver only ever walked away from the background in one direction, so an accent brighter than the background kept moving toward white.
- Picking a colour changed the page but not the panel. The component subscribed to the palette id, which never changes when a colour does — React compared the snapshots, saw no difference, and skipped the re-render.
- Sharing a configuration did not share the colours. The short code carried the modes but not the three custom colours, so importing on another machine reported success and silently kept the local values.
- "Not promised" is not "impossible". The report called the dark module surfaces "surface-limited" because it compared the body target against the deepest one (800). But 800 reaches about 10.22:1 and 850 about 15.27:1 with a white foreground — above the 10:1 target — so nothing was ever unreachable; those surfaces simply were not promised. The report now separates the declared target, the physical ceiling and the policy exemption, and counts dark 800/850 as "out of policy" instead of "physically unreachable".
- A selector we thought was dead was alive. The audit initially reported the
_markdown_ hooks as broken; the contract test against the shipped CSS proved otherwise. The finding was wrong, not the code.
Sharing
Every setting — including the three custom colours — travels in one short code. Paste it into the import box and press Preview to see exactly what it will change before applying:
dshs1.eyJ2IjoxLCJwIjoiY3VzdG9tIiwicyI6ImRlZXAiLCJ0IjoidGludGVkIiwiYyI6InRpbnRlZCIsImsiOiJhY2NlbnQiLCJtIjoib24iLCJoIjoib2ZmIiwibCI6InpoLUNOIiwieCI6eyJiZyI6IiNmNWVmZTYiLCJ0ZXh0IjoiIzFkMWExNyIsImFjY2VudCI6IiMzZjY2YTMifX0
This real example decodes to:
- palette: custom · sidebar: deep · text: tinted
- scrollbar: tinted · controls: accent · Markdown emphasis: on · high contrast: off · language: zh-CN
- three colours:
#f5efe6 (canvas) · #1d1a17 (text) · #3f66a3 (accent)
The code is generated by the production encoder and self-checked round-trip before it goes into this README — it is never hand-written.
Trade-offs
Other theme plugins in this ecosystem ship glass, wallpapers and animation. We deliberately do not:
- No glass or wallpaper. That race is won on screenshots; we would rather compete on proof.
- No theme market, no AI colour generation. Both introduce colours we cannot guarantee — the contrast solver is the asset, and feeding it unpredictable input spends it.
- No more palettes. Four presets plus a three-colour generator beats ten hand-picked ones; volume is not the moat.
- No eye-care claims. We report measured ratios on the surfaces text actually lands on, and say "out of policy" when a surface is not one we promise — a measurement, not an excuse.
License
MIT © 2026 Zuoyunlai
