# ThoughtLite skin for DeepSeek Harness

**English** | [中文](README.md)

A DSH desktop skin built on the design language of [astro-theme-thought-lite](https://github.com/tuyuritio/astro-theme-thought-lite): an editorial re-skin in **monochrome, paper, serif body text**.

- Light: cream paper `#fdfcf6` + ink black `#2a2a28` (upstream original `#fffffd`, see “Deviations”)
- Dark: warm black `#0e0e0c` + off-white `#dddddb`
- Accent = text color (upstream has no second color); links are distinguished by underline rather than color
- The only colors are status colors: the four hues of the upstream GitHub Alerts (tip `#48a131` / important `#3366cc` / warning `#bf8700` / caution `#ee3838`)
- **Serif everywhere** (Noto Serif stack, shell included), code in the Maple Mono stack — upstream `body` is serif, with not a single sans-serif anywhere
- **Square corners** (2/3/4/5/6/8px), hairline borders, **no shadows** (only overlays keep upstream's `shadow-md`), 5px ink-colored scrollbar

![The real interface: serif everywhere, cream paper, user messages as ink-ruled quotation blocks, a masthead rule in the sidebar](docs/app.png)

> The image above is the real DSH interface (account info and workspace names redacted); the light/dark comparison below is rendered from the same token table, and you can also open [preview/index.html](preview/index.html) directly.

![Light / dark comparison](docs/preview.png)

---

## Installation

Any profile works (`desktop` / `web` / your own); just swap the profile name in the commands below.

**Install from GitHub (recommended)**

```powershell
dsh plugin --profile desktop add github:Jov3c/dsh-theme-thought-lite
```

**Install from npm (available once published; the plugin marketplace uses this route too)**

```powershell
dsh plugin --profile desktop add dsh-theme-thought-lite
```

**Install from a local directory (for working on the skin)**

```powershell
dsh plugin --profile desktop add link:D:\Main\dsh-theme-thought-lite
```

Then **fully quit and restart DeepSeek Harness** (closing the window doesn't count — you need to exit the process). After restarting, choose light, dark, or follow system in `Settings → General → Appearance` (设置 → 通用 → 外观) as usual.

> Not yet published to npm: this machine isn't logged in to npm, and publishing is the final manual step. See “Publishing to npm”.

- What this command does: writes the package into the profile's `dependencies`, appends `dsh-theme-thought-lite` to `dsh.profile.bundles` (because package.json declares `dsh.bundle.patch`), and inserts the plugin entry via [cordis.patch.yml](cordis.patch.yml). **No profile file needs to be edited by hand.**
- Uninstall / roll back:

  ```powershell
  dsh plugin --profile desktop remove dsh-theme-thought-lite
  ```

  Restart again to return to the native look. The skin only registers one token override layer and one `<style>`; both are removed automatically when the plugin is uninstalled, and no original files are modified.

### Manual installation (when the CLI is unavailable)

1. Add the following to `dependencies` in `%USERPROFILE%\.dsh\profiles\desktop\package.json`:
   `"dsh-theme-thought-lite": "link:D:/Main/dsh-theme-thought-lite"`,
   and append `"dsh-theme-thought-lite"` to the end of the `dsh.profile.bundles` array.
2. Run `pnpm install` in the profile directory.
3. Restart.

---

## How it works

DSH's skin extension point is **`ctx.theme.overrideTokens(source, tokens)`**, exposed by `@deepseek-ai/dsh-client-ui-theme`: a token override layer of paired light/dark values, stacked on top of the built-in theme the user currently has selected. The `ThemePresenter` in the host `ui-layout` writes each token from the snapshot to `<body>` as an **inline custom property**, so the override layer always beats the stylesheets and follows the user's appearance choice automatically.

That's why this package is a **skin, not a theme**: it doesn't hijack the choice of light or dark, it just re-skins both modes.

```
lib/client.js   ← browser half: a single overrideTokens call + one <style> (generated by src/build.mjs)
lib/index.js    ← host half: empty implementation (a browser-only plugin, isomorphic to the official ui-layout)
src/skin.mjs    ← single source of truth: upstream anchors → DSH token mapping + signature styles
```

- Tokens are applied in two layers: **static color scales** (`--dsw-static-*`, laying down a warm paper feel first and covering every reference not named individually) + **semantic aliases** (`--dsw-alias-*`, named one by one for precision).
- No layout changes, no component structure changes; signature styles apply only to the Markdown reading surface (see below).
- Everything hangs off the `ctx.effect` lifecycle; `apply()` is wrapped entirely in try/catch, so **a skin failure won't take down the GUI**.

Covers **256 tokens**, including all 190 in the `design-platform` part of the DSH design system.

---

## Design mapping

Upstream's entire palette comes down to the 7 variables in [src/styles/global.css](https://github.com/tuyuritio/astro-theme-thought-lite/blob/main/src/styles/global.css); everything else is Tailwind v4 CSS-first. Mapping principles:

| Upstream | DSH token | Treatment |
|---|---|---|
| `--background-color` `#fffffd` / `#0e0e0c` | `--dsw-alias-bg-base`, `-bg-layer-*`, `--dsw-static-neutral-bluish-00/950` | Compressed to cream `#fdfcf6` (see “Deviations”) |
| `--primary-color` `#2a2a28` / `#dddddb` | `--dsw-alias-label-primary`, `-brand-*`, `-link`, `-state-business-primary`, `-button-primary-fill` | Original value; **the accent color collapses entirely into ink** |
| `--secondary-color` `#7e7e7b` / `#9e9e9b` | `--dsw-alias-label-secondary`, `-border-*` baseline, `li::marker` | Adjusted slightly in light mode to `#73736f` (see “Deviations”) |
| `--weak-color` `#9f9f9c` / `#5d5d5a` | `--dsw-alias-label-tertiary`, `-label-dimmed` | Original value |
| `--block-color` `#eeeeee` / `#1e1e1e` | `--dsw-alias-markdown-code-block`, `-inline-code`, `-specific-bubble` | Original value (exactly upstream's code/inline-block background) |
| `--shadow-color` `#cdcdcc` / `#323231` | `--dsw-alias-border-l4`, blockquote bar, focus ring | Original value |
| `--selection-color` `#adadacc3` | `--dsw-alias-bg-document-selection`, `::selection` | Original value (same value in both upstream modes) |
| Alert hues | `--dsw-alias-state-success/warn/error-*`, file-diff | Swap hues only; semantics unchanged |
| Shiki `github-light` / `dark-plus` | `--shiki-token-*` | Upstream's `astro.config.ts` uses exactly these two themes, so write their canonical colors |
| Noto Serif stack | `--dsh-font-family-text-default` (site-wide) + `--dsw-font-markdown-*-font-family` (22 of them) | Upstream's `body` uses no sans-serif anywhere, so the shell is serif too |
| Maple Mono stack | `--ds-font-family-code`, `--dsh-font-family-code-default` | Original value |
| Corners 5px / 0.3em | `--dsw-radius-*` (2/3/4/5/6/8) | Collapsed from 4–28px to square corners |
| Flat, no shadows | `--dsw-shadow-lv1/lv2` = `none`, `lv3` = upstream `shadow-md`, `--dsw-menu-backdrop-filter: none` | Leave a shadow only for overlays; menus become solid paper |

**Signature styles** come in two categories, all attached to hooks registered in `fixtures/dsh-css-modules.json` (`verify` blocks any unregistered hook):

Reading surface `[class*="_markdown_"]`:

- `h1` 4px, `h2` 2px `currentColor` closing rules; the heading scale is enlarged to 30/24/20/17px (upstream's 36/28/24 scaled proportionally for 14px body text)
- Links inherit ink + a 32% resting underline, solid on hover, `0.05em` thickness / `0.15em` offset
- `hr` is a dashed hairline in `--secondary`
- Blockquotes are a 4px `--shadow-color` vertical bar, with no italics and no background
- Inline code `0.3em` radius + `.25em/.5em` padding; fenced blocks `.3em` radius + hairline border
- Tables go booktabs: 3px primary ink rules top and bottom, 2px under the header
- `mark` becomes a wavy underline (upstream's approach); reading surface line-height is 1.75, and headings get more space above and below

Structural surface (these are what stop the app from looking like a chat client):

- **User messages are no longer bubbles**: `[class*="_bubble"]` becomes a transparent background + a 3px ink rule on the left + 2px square corners, an editorial-style block
- **The composer is a form, not a floating card**: `[class*="_composerStack"] [class*="_input"]` gets 2px corners
- **Sidebar masthead**: a hairline rule under `[class*="_logoRow"]`, like a blog site header
- **Sidebar rows**: `[class*="_panelRow"]` becomes a tidy list (2px corners + hairline separators between rows)

### Why it won't fight with user settings

`ui-theme`'s font binding is `--dsw-font-family: var(--dsh-font-family-text, var(--dsh-font-family-text-default)), …`. The skin overrides only the **fallback stack** `--dsh-font-family-text-default`, not `--dsw-font-family`, so a font the user picks in settings always wins; same for font size — not a single value is touched.

---

## Deviations (intentional, explained one by one)

1. **Paper is compressed from `#fffffd` to cream `#fdfcf6`**: upstream's "warm white" is effectively white on paper, and native DSH is white too — together you can't see the difference. Applying the cream tint is the smallest change that makes the "paper feel" actually visible; body contrast is still ≥13:1.
2. **`label-secondary` is adjusted from `#7e7e7b` to `#73736f`**: upstream's value is only 4.07:1 on its own paper, below WCAG AA; on a cream background it has to go down to `#73736f` to hold 4.5:1 (4.63:1). All other contrast ratios are compliant (`node test/verify.mjs` computes them one by one).
3. **The focus ring uses `--secondary` rather than `--shadow-color`**: upstream uses `#cdcdcc` as a 2px focus ring, which is almost invisible on paper; switching to the same family's `--secondary` preserves usability.
4. **Scrollbar ink is reduced to 19%/35% opacity**: upstream is a 5px, 100% opaque ink track. That's very clean on a single blog page, but too heavy in an app with many scroll regions.
5. **Links keep a 32% resting underline** (solid on hover): upstream only reveals it on hover. On a blog nobody needs to ask "is this line a link"; in a conversation they do — this is a small sacrifice of purity for usability.
6. **The heading scale is enlarged proportionally from 14px body text** (30/24/20/17px): upstream is 36/28/24, but converted to DSH's 14px body it would only be 21/19/18, with no visual presence; this is the key step that makes it "feel like a blog."
7. **Structural changes (bubbles / composer / sidebar)**: upstream has no such containers at all; this is **translating upstream's editorial typographic language into a GUI**, not copying it verbatim — user messages become an ink-ruled quotation block, the sidebar gets a masthead rule, and rows become a tidy list.
8. **The brand color is not invented**: upstream has no accent color, so DSH's brand/link/primary-button colors all collapse into ink; GitHub Alert's blue was not borrowed as a brand color, because that would break the monochrome character.

---

## Fonts

Handled as “use it if installed, degrade gracefully if not”; no web fonts are downloaded (offline availability on desktop is a hard requirement):

- Body serif: `Noto Serif SC → Noto Serif → Source Han Serif SC → Songti SC → STSong → SimSun → Georgia → Times New Roman → serif`
- Code: `Maple Mono NF CN → Maple Mono NF → Maple Mono → Cascadia Code → JetBrains Mono → Consolas → Monaco`
- Shell: system UI stack (Segoe UI Variable / PingFang SC / Microsoft YaHei)

For the closest look to upstream, install [Noto Serif SC](https://fonts.google.com/noto/specimen/Noto+Serif+SC) and [Maple Mono NF CN](https://font.zeoseven.com/442/main/result.css); it works without them too (Windows falls back to SimSun for text and Cascadia/Consolas for code).

One more suggestion: serif at 14px is a bit small; `Settings → General → Font Size` (设置 → 通用 → 字号大小) at 15–16px is the most comfortable (the skin doesn't change this value for you — it's your preference).

---

## Verification

```powershell
cd D:\Main\dsh-theme-thought-lite
node src/build.mjs         # generate lib/client.js, preview, fixtures
node test/verify.mjs       # 73 checks: the package itself
node scripts/preflight.mjs # 23 checks: whether the host can load it after installation into a profile
```

`verify.mjs` actually runs the package with a fake `window.__ModuleLoader__` and a fake `ctx`, and checks:

- Module loading protocol (id / factory / exports / `inject: ["theme"]`)
- `apply()` stacks only one layer, attaches only one copy of the styles, all on `ctx.effect`; repeated apply doesn't stack duplicates
- Every override value is a non-empty `{light, dark}` string (bare strings throw at the API boundary)
- **All 190 `design-platform` tokens are covered**, with no misspelled names
- No `var()` pointing at an undefined token; build artifacts are in sync with source (not a stale build)
- **WCAG contrast for 17 foreground/background pairs × 2 modes** (body ≥7:1, secondary text/buttons/toast ≥4.5:1, status colors ≥3:1)
- The `_markdown_` / `md-code-block` / `data-ds-dark-theme` hooks the signature styles depend on still exist in the locally installed DSH version
- Manifest fields (`main`, `exports["./client"]`, `dsh.client.platform`, `dsh.bundle.patch`, the patch insertion line)

`preflight.mjs` checks again **after installation**, following the host's actual resolution path: resolves the package from the profile's `node_modules`, validates `dsh.client` with the same rules as `client-modules`, resolves `exports["./client"]`, confirms the bundle is a classic script and its registered id equals the package name (which decides whether it gets mounted at `/plugins/<id>/client.js`), confirms the host half exports `apply`, and confirms it comes last in the bundle stack (so the override layer can override the layers ahead of it).

`fixtures/dsh-tokens.json` and `fixtures/dsh-frontend.css` are the token list and frontend styles exported from the locally installed DSH (`0.2.1-rc.2`), used for version alignment. **After a DSH upgrade, re-export and rerun verify**:

```powershell
node scripts/extract-dsh-tokens.mjs <extracted ui-theme styles directory> fixtures/dsh-tokens.json
```

---

## Not working after restart?

First figure out whether it's “the server didn't load it” or “the page didn't update.” The symptoms differ, and so do the fixes.

### 1. Confirm the server side (ten seconds or so)

The host pushes the client module graph to already-open pages over an SSE channel; this exception route doesn't require a token:

```powershell
node D:\Main\dsh-theme-thought-lite\scripts\graph-probe.mjs
```

If the output contains
`"id":"dsh-theme-thought-lite","url":"plugins/??dsh-theme-thought-lite/client.js&rev=…","immediately":true`
then **the host has already compiled it into the graph**, and the problem is on the page side — read on.

### 2. Page side: the desktop shell caches the startup page

The desktop app loads the shell from its own `dsh-app://` scheme, and that HTML inlines `window.__DSH_BOOT__` (the client module graph).
It is cacheable — **a window opened before the plugin was installed may still get the old startup graph on its next launch**, so the new plugin is in the server-side graph but the page doesn't load it.

Three fixes, from lightest to heaviest:

1. Press **Ctrl+Shift+R** in the window to hard refresh (not a plain F5);
2. Make the host push a new graph: bump the bundle's modification time, and the host treats it as a rebuild and pushes it to open pages, which hot-load the skin (**no restart needed**):

   ```powershell
   (Get-Item D:\Main\dsh-theme-thought-lite\lib\client.js).LastWriteTime = Get-Date
   ```

3. Clear caches completely: quit the app, delete the
   `%APPDATA%\@deepseek-ai\dsh-desktop\Cache`, `Code Cache`, and `GPUCache` directories, then launch it again.

### 3. How to confirm at a glance that it's active

When you're not sure whether it's “actually active but I just can't see it,” compare these two real screenshots (same machine, same session, same page):

| | Skin active | Native look |
|---|---|---|
| Font | **Serif everywhere** (SimSun/Noto Serif), even the sidebar, navigation, and input | System sans-serif |
| User messages | **3px ink-ruled quotation block**, transparent background, square corners | Blue rounded bubble |
| Sidebar | **Masthead hairline** under the brand text, rows in a tidy list | No rule, rounded pill rows |
| Headings | h1 30px / h2 24px, with 4px / 2px closing rules | h1 21px / h2 19px, no rules |
| Corners | Square, panels 8px (`--dsw-radius-panel`) | Pill-level, inputs/panels 24–28px |
| Shadows | None (`--dsw-shadow-lv1/lv2: none`) | Soft shadows on every layer |
| Background | Cream paper `#fdfcf6`, sidebar `#f6f3e8` | Pure white `#ffffff` |
| Send button / primary buttons | Ink (ink is the only accent) | Blue |

These three are the easiest to confirm: **user messages go from a blue rounded bubble to an ink-ruled quotation block**, **the whole site becomes serif**, and **the background goes from pure white to cream**. For colors and typography, see [docs/preview.png](docs/preview.png) at the top (light/dark side by side).

> Local verification method: use CDP to drive headless Chrome to open a temporary web instance, capture the active state first, then remove the skin's `<style>` in the page and strip all inline tokens to capture the native state — that gives an A/B of the same page. The screenshots contain account and workspace information, so they were not committed.

### 4. Check status in the plugin list

The **`Settings → Plugins` (设置 → 插件)** list shows page-side sync failures (if the bundle fails to execute) and offers “Retry” without changing the host's enabled state. If `dsh-theme-thought-lite` is in the list with no errors, the page has loaded successfully.

---

## Publishing to npm

The repository is ready for publishing (`private` removed, `publishConfig.access=public`, `repository`/`homepage`/`bugs` filled in, `prepublishOnly` rebuilds and runs the 73 checks first); all that's left is logging in and publishing:

```powershell
cd D:\Main\dsh-theme-thought-lite
npm login                 # log in to your npm account in the browser
npm publish               # prepublishOnly builds and verifies first
```

The package name `dsh-theme-thought-lite` is currently unclaimed. Only after it's published to npm can DSH's plugin marketplace (dshmarket) index it; the package's `dsh` manifest fields and keywords are already filled in according to the marketplace's scanning conventions.

---

## Known limitations

- **Not a third option in settings**: `ui-theme`'s settings schema only accepts `light` / `dark` / `system`; third-party theme ids don't cross the settings boundary. So the skin is “an always-on override layer,” and the on/off switch is installing/uninstalling the plugin.
- **The first frame may flash native colors**: token overrides happen after the plugin mounts. `immediately: true` makes it load as early as possible, but not earlier than DSH's own pre-plugin bootstrap.
- **Doesn't cover host-drawn parts**: native window title bar/borders, tray icon, and installer are outside this token system.
- **`_markdown_` / `_bubble` / `_logoRow` etc. are parts of hashed class names**: if DSH changes these CSS-module names, the corresponding signature or structural styles break (colors are unaffected because they go through tokens). Every hook used is registered in `fixtures/dsh-css-modules.json`; `verify` blocks “using an unregistered hook”; after an upgrade, check them one by one against it.
- Upstream is GPLv3. This package **only carries design values** (colors, sizes, rules) and contains no upstream code, so it's released under MIT; if you want to redistribute this visual design, check upstream's license and attribution requirements yourself.

---

## Acknowledgements

- Design: [tuyuritio/astro-theme-thought-lite](https://github.com/tuyuritio/astro-theme-thought-lite) (GPLv3)
- Fonts: [Noto Serif](https://fonts.google.com/noto/specimen/Noto+Serif) (OFL), [Maple Mono NF CN](https://font.zeoseven.com/) (OFL)
- Integration surface: the `ctx.theme` extension point of `@deepseek-ai/dsh-client-ui-theme`