ไธญๆ ยท English
# dsh-dream-skin ๐ฎ
**Give DeepSeek Harness a face that breathes, feels, and belongs to you.**
Native skinning ยท wallpaper ยท shareable theme packs โ a romance-engineered project built entirely on DSH's official `--dsw-*` token system.
> **TL;DR: code with atmosphere.** โจ
| ๐จ 8 original themes | ๐ผ๏ธ wallpaper + opacity/blur | ๐ one-click accent | ๐ฆ shareable theme packs |
|---|---|---|---|
> 3-line install ยท purely native (no injection, no installer patches) ยท survives DSH updates
[ไธญๆ](./README.md) ยท [Changelog](./CHANGELOG.md) ยท [Project Notes](./docs/PROJECT.md) ยท [Publishing Guide](./docs/publishing-to-npm.md)
[](https://awesome-dsh-plugin.com)
-4f83f2)
> ๐ **Now on npm!** With DSH installed, add it in one command โ no cloning needed:
> ```sh
> dsh plugin --profile web add dsh-dream-skin
> ```
> **Homage to [Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin).** But the approach is different:
> Codex injects CSS into the desktop client's renderer via CDP, whereas DSH is a **token-driven Web GUI** that ships
> first-class "third-party plugins registering themes". So this plugin is **purely native** โ no injection, no binary
> patches, and it won't break on client updates.
>
> **Not an official product.** Just a way to dress up your DeepSeek Harness workspace.
---
## ๐ธ Screenshots
> Real screenshots, not mockups. Left: DSH after applying a skin; right: the dedicated **Theme / Appearance** section in Settings.
---
## ๐ Why it earns a star (vs alternatives)
| Capability | Ours | Other DSH skinning | Codex-Dream-Skin (desktop) |
|------|:---:|:---:|:---:|
| Native token themes โ no injection, no installer patches | โ
| โ
| โ (CDP injection) |
| Custom wallpaper + opacity/blur | โ
| partial | โ
|
| **Theme-pack import/export + share links** | โ
| โ | โ
(zip packs) |
| **Per-user Accent override** | โ
| โ | partial |
| **Wallpaper 2.0 (URL / gradient / per-skin suggestion / auto-dim)** | โ
| โ | โ
|
| Local pack library + favorites + surprise-me | โ
| โ | partial |
| Validation + rollback | โ
| partial | โ
|
| **Browser Web GUI, cross-platform natively** | โ
| โ
| โ (needs desktop App) |
## โจ Features
| Capability | Description |
|------------|-------------|
| ๐จ **8 bundled presets (Mirage)** | Switch instantly under **Settings โ Theme / Appearance**, light & dark |
| ๐ผ๏ธ **Custom wallpaper** | Pick a local image (auto-compressed โค2MB), tune **opacity / blur** |
| ๐ค **Opaque inner surfaces** | Cards, inputs, message bubbles stay readable โ never washed out |
| โฉ๏ธ **Default restore** | Back to DSH's built-in appearance (follow system) in one click |
| ๐พ **Local persistence** | Skin & wallpaper stored in `localStorage`, survives reload |
## ๐ Advanced capabilities (P0)
Differentiation inspired by existing DSH skin projects plus Codex's skin UX:
| Capability | Description |
|------------|-------------|
| ๐ฆ **Theme-pack format + import/export** | A `*.dsh-theme.json` pack = format marker + version + manifest (id/name/author/scheme/accent/tokens). Import a file, one-click apply, and copy a **share link** (encoded in the URL hash) |
| ๐ **Per-user Accent** | Stack a custom brand-accent over the active skin (`overrideTokens` layer, the skin untouched): **12 one-click preset swatches**, a color picker, **randomize**, and clear |
| ๐ผ๏ธ **Wallpaper 2.0** | Local image / **image URL** / **gradient presets**, with a **per-skin suggested gradient** and **auto-dim**; **Recent** (up to 5) to switch back in one click |
| ๐งฉ **Local pack library** | Your imported theme packs in one place; **apply / favorite / remove** in a click (the 8 built-in skins live in the Skins row) |
| โ
**Clear selection feedback** | Switching skins updates the checked/bordered highlight **instantly** โ no stale white highlight box |
| ๐ฒ **Surprise me** | Randomly switch to a theme different from the current one |
| โญ **Favorites** | Star your favorite skins and switch between them fast |
| โ
**Validation + rollback** | Pack import validates format / required tokens / color legality; failures or removals fall back safely |
## โก Quick start (3 steps)
```sh
# 1. install
dsh plugin --profile web add dsh-dream-skin
# 2. restart
dsh web
# 3. open Settings โ Theme / Appearance โ pick a skin โ done.
```
> Installs the published npm package โ no cloning. If `dsh plugin add` reports a workspace error, append `-w`.
## ๐งฉ What kind of plugin is this
**A standard dual-face "everything-is-a-plugin" `dsh-plugin` โ loaded and used exactly like the official `ui-theme` package.**
DeepSeek Harness's motto is *everything is a plugin*: models, tools, sandboxes, sessions, UI, even the Agent Loop
itself are plugins. `dsh-dream-skin` ships skinning as an npm package that is **isomorphic with the official UI
packages**:
```text
โโโโโโโโโโโโโ dsh-dream-skin (standard dsh-plugin / dual-face) โโโโโโโโโโโโโโ
โ dsh.bundle โ cordis.patch.yml inserts the dream-skin entry (host half)โ
โ dsh.client โ lib/client.js (browser bundle) (browser half)โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
- **Install command = the official one**: `dsh plugin --profile web add dsh-dream-skin`
- **Uses official extension points**: `ctx.theme` (register themes), `ctx.theme.overrideTokens` (override layers),
`ctx.slots` (mount UI into a dedicated **Settings โ Theme / Appearance** section).
- **Manifest contract matches official packages**: `dsh.bundle` + `dsh.client` + `exports["./client"]`.
In other words: you are not installing a fringe script โ this is a standard skin plugin inside DSH's official plugin
system.
## ๐ผ๏ธ Preview โ the Mirage series
> Previews below are generated from each skin's **real tokens** โ what you see is what you get.
abyss |
aurora |
nebula |
ember |
midnight |
ivory |
mist |
rose |
## ๐ฒ The presets
| id | scheme | vibe |
|------|--------|------|
| `abyss` | ๐ถ๏ธ dark | DeepSeek deep-blue abyss (anchor) |
| `aurora` | ๐ dark | aurora teal-green |
| `nebula` | ๐ช dark | cosmic purple |
| `ember` | ๐ฅ dark | warm ember orange |
| `midnight` | ๐ dark | pure-black OLED |
| `ivory` | ๐ light | warm ivory / paper |
| `mist` | ๐ซ๏ธ light | cool blue fog |
| `rose` | ๐ธ light | rose pink / blush |
## ๐ฆ Install
### Option A: From npm (published, **recommended**)
```sh
dsh plugin --profile web add dsh-dream-skin
```
Then **restart** the web server:
```sh
# stop the running instance, then:
dsh web
```
Open **Settings โ Theme / Appearance** to see the **Skins**, **Accent**, **Wallpaper** / **Advanced Wallpaper**, and **Theme Packs** rows.
> The `-w` (workspace) flag is needed on a bare `add` because every profile ships a `pnpm-workspace.yaml`; pnpm treats
> the profile directory as a workspace root, so a bare add fails with `ERR_PNPM_ADDING_TO_ROOT`. If your profile already
> uses the workspace, you won't need to repeat it.
### Option B: From source / a local directory (developers)
```sh
dsh plugin --profile web add -w /path/to/dsh-dream-skin
```
## ๐ Update / Uninstall
**Update to the latest** (when installed from the npm release):
```sh
dsh plugin --profile web update dsh-dream-skin
dsh web # restart to pick it up
```
> Stuck on an old version after an update? pnpm's minimum-release-age (supply-chain) policy can hold back a
> freshly published release. In the profile dir run:
> `pnpm add dsh-dream-skin@latest --config.minimumReleaseAge=0` to force it.
**Uninstall:**
```sh
dsh plugin --profile web remove dsh-dream-skin
dsh web # restores the official appearance
```
## ๐งฉ Compatibility
| Item | Value |
|------|-------|
| DeepSeek Harness (`dsh`) | `0.1.0-rc.6` (peerDependencies pinned to `^0.1.0-rc.6`) |
| Node.js | `>=18` |
| Browser | modern Chromium / WebKit (native CSS variables & `matchMedia`) |
> When upgrading DSH, bump the peerDependencies in `package.json` accordingly.
## โ๏ธ How it works
DSH's theme system is token-based: the web shell ships `--dsw-*` design tokens, and `ThemeRuntime` lets third-party
plugins register themes that override the alias layer (`--dsw-alias-*`). This package is a standard dual-face plugin:
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ dsh-dream-skin (dual-face plugin) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโค
Host half โ lib/index.js โ Browser half โ
โ cordis.patch.yml inserts โ lib/client.js โ
โ dream-skin loader entry โ __ModuleLoader__โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโ
โ โ
profile tree loaded /plugins/dsh-dream-skin/client.js
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโ
โ โ โ
ctx.theme.register(8 skins) ctx.theme.overrideTokens(wallpaper) ctx.slots.inject('settings.general.item')
```
- **Host half** (`lib/index.js`) โ a `dsh.bundle` patch layer inserting the `dream-skin` loader entry; `apply` is a
no-op, exactly like the shipped `ui-*` packages.
- **Browser half** (`lib/client.js`):
1. registers the 8 skins via `ctx.theme.register(...)`;
2. restores the saved skin and applies it with `ctx.theme.setTheme(...)`;
3. renders the wallpaper as a `z-index:-1` fixed backdrop and stacks `ctx.theme.overrideTokens(...)` making the
main canvas (`--dsw-alias-bg-base`) and sidebar (`--dsw-specific-sidebar-fill`) translucent;
4. listens for `theme/change` and re-shades the wallpaper wash on skin / scheme switch;
5. mounts both rows into the `settings.general.item` slot.
Each skin carries its `colorScheme` (`light`/`dark`), driving `body[data-ds-dark-theme]`; the alias-token overrides
are applied as inline custom properties on `` by ui-layout's ThemePresenter.
## ๐ผ Persistence notes
- Skin & wallpaper are stored in `localStorage` (keys prefixed `dsh-dream-skin:`), **per browser**.
- Why not Host settings? The Host settings wire only exposes an allowlisted set of namespaces to browser clients
(`WEB_SETTINGS_NAMESPACES` in `dsh-host-apiproxy`), so a third-party namespace would answer `settings-not-exposed`;
the product itself keeps remote browser preferences process-local. `localStorage` matches that boundary and
survives reloads.
## ๐ ๏ธ Development / extending themes
The client bundle is written directly in the `__ModuleLoader__` format (the same shape tsdown emits for the shipped
`ui-*` packages), so **no build step** is required. `lib/client.js` may `require` only module-table entities: platform
seeds (`react`, `react/jsx-runtime`, โฆ) and registered client bundles (`@deepseek-ai/dsh-client-runtime/client`, โฆ).
- **Add a built-in skin**: append an object (`id` + `colorScheme` + `tokens`) to the `SKINS` array in `lib/client.js`;
it then appears in Settings automatically. Add a `skin.` key to both the `zh` and `en` dictionaries.
- **Ship a theme pack (recommended)**: follow [`docs/examples/sample-theme-pack.json`](./docs/examples/sample-theme-pack.json) โ
one `*.dsh-theme.json` is importable in Settings and shareable via a link, no code changes needed.
- **Add your own wallpapers**: drop images into [`wallpapers/`](./wallpapers/) (distribute only what you have rights
to), then import them via DSH's "Wallpaper" row.
- **Validate**: `npm test` (VM smoke tests covering factory eval, `apply()`, and pack import/persistence).
- **Repaint**: reference the `--dsw-alias-*` tokens (full contract in [`docs/themes-spec.md`](./docs/themes-spec.md)).
## ๐ Roadmap
- [x] v0.1: 8 themes + custom wallpaper (opacity / blur) + local persistence
- [x] Theme-pack format + import / export / share link (JSON + manifest + validation)
- [x] Per-user Accent + randomize
- [x] Wallpaper 2.0 (URL / gradient / per-skin suggestion / auto-dim)
- [x] Local pack library + one-click apply / favorites / surprise-me
- [ ] Online palette / theme-preview Studio (pure frontend, contrast checker)
- [ ] Community theme gallery (submit packs to the repo / online gallery)
- [ ] Full i18n copy & docs (zh / en / more)
- [ ] First-paint (FOUC) improvement
## ๐ค Contributing
Issues and PRs welcome! Please read the [Contributing Guide](./CONTRIBUTING.md) and follow the
[Code of Conduct](./CODE_OF_CONDUCT.md).
## โญ Support the project
If you like it: star **โญ** the repo, thumbs-up **๐** on npm, or share it with DSH friends โ it helps the project
get discovered and keeps it maintained. Want to contribute themes / an online Studio / more skins? Join in.
## ๐ Security
Found a security issue? Don't open a public issue โ see the [Security Policy](./SECURITY.md).
## ๐ License
[MIT](./LICENSE)
## ๐ Acknowledgments
- Architecture & API reference: the official DeepSeek Harness
[ui-theme](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-theme) client package.
- Concept homage: [Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin).