TQSY114514/dsh-ui-appearance

中文 · English

An appearance customization plugin for the DeepSeek Harness WebUI — a freely re-colorable theme palette, wallpaper/video backgrounds, glassmorphism and background ambience, all previewed live and persisted automatically.

Zero core-code changes: everything goes through the official plugin mechanism (ctx.theme.overrideTokens() theme extension point and the settings.general.item slot). Uninstalling restores the stock UI completely.

Screenshots

Settings panel	Wallpaper + glassmorphism

The wallpaper in the screenshots is © MadYY (source), shown for demonstration only — users upload their own images.

Features

Theme colors — 6 color roles: accent, background, panel, input, text, border. Each role has a color picker and HEX input; text selection and the keyboard focus ring follow the accent automatically; message bubbles follow the accent too (keeping its hue when translucent).

Wallpaper background — Click to upload or drag in an image (JPG / PNG / WebP), or paste an image/video URL to load it in one click (auto-routed by extension; works with CORS-friendly hosts); it is compressed automatically and used as a full-UI wallpaper. Brightness is sampled on upload: dark wallpapers trigger a coordinated lift of surfaces, lighten the text and darken buttons for readability. Video backgrounds (MP4 / WebM, muted loop, mutually exclusive with images) are also supported and stored in IndexedDB, keeping localStorage quota free.

Glassmorphism & translucency — Panel opacity and glass-blur sliders let the sidebar, settings panel, chat area, task panels, cards and buttons melt into the wallpaper instead of sitting as solid blocks; the sidebar can stay opaque on its own. Emphasized text chips (pnpm-lock.yaml, lib/) keep a low-alpha accent tint — emphasis via hue, not solid fill — with an "emphasis tint" slider (0% = fully transparent) for independent tuning.

Background ambience — Three independent sliders: background opacity (how strong the wallpaper is), background blur (pushes it into the distance), and a scrim that auto-tints with the light/dark scheme to keep text on the image readable.

Presets to start from — Default / Midnight / Ocean / Forest / Rose / Monochrome; apply one click and keep fine-tuning, never locked in.

Scheme sharing — Export your palette as JSON (copied to clipboard), paste to import; sharing a theme is one snippet of text.

Every change applies live — no refresh, no save button.

Installation

# npm release (recommended)
dsh plugin --profile <name> add dsh-ui-appearance

# or from source (verified end to end)
git clone https://github.com/TQSY114514/dsh-ui-appearance.git
dsh plugin --profile <name> add file:<path-to-clone>

Uninstall: dsh plugin --profile <name> remove dsh-ui-appearance

Updating: after a new release, simply re-run add to upgrade to the latest version.

Both installation paths (npm registry and file: source install) are verified end to end: the host half has zero @deepseek-ai runtime dependencies, and both the browser and the Host load correctly. After cloning, pnpm install builds automatically; after code changes, re-run pnpm install && pnpm prepare and restart dsh web. Release history: CHANGELOG.md.

Usage

1. Open the WebUI, go to Settings → General in the sidebar.
2. Below the Appearance row, find "个性化外观" (Personalized appearance) and expand it.
3. Pick a preset for a quick skin, fine-tune the 6 color roles with pickers or HEX input, upload or drag in a wallpaper/video, and drag the ambience and interface sliders.
4. Done. Everything applies live — no refresh, no save.

Settings panel at a glance:

Section	Controls
Presets	Default / Midnight / Ocean / Forest / Rose / Monochrome; free to keep tuning after applying
Theme colors	6 roles × (picker + HEX): accent, background, panel, input, text, border
Background	Image upload/replace/remove, video upload/remove, load from URL (image/video), image opacity, background blur, scrim
Interface	Panel opacity, emphasis tint, keep sidebar opaque, glass blur
Color scheme	Export palette, import palette (JSON text)

Persistence & reset

• Settings live in browser localStorage (key dsh-ui-appearance.settings); they survive refresh and restart and sync across tabs.
• Removing the plugin from the profile restores the stock UI: disposal reclaims every overridden token, stylesheet and background layer.
• Note: settings follow the browser — switching browsers or clearing site data loses them; wallpapers are stored as compressed data URLs under the localStorage quota.

How it works

Capability	Mechanism
Colors	ctx.theme.overrideTokens() overrides --dsw-alias-* semantic tokens; light/dark switches re-apply automatically, derived colors are computed per mode
Background layer	A dedicated fixed-position layer above the page background and below the content, driven by CSS variables
Glassmorphism	The background layer is blurred as a whole (filter: blur, background blur + glass sliders summed); #root is untouched, so no backdrop-filter containing-block side effects
Translucency	Surface tokens are baked to rgba() per mode (role color → dark-flip derived → stock surface table), no color-mix dependency, works in every browser; coverage includes the settings panel (bg-layer-2), task panels/queue dock/goal bar (specific-tip), inline code and code blocks (markdown-*), and the command (plus) button hovers (selector / interactive-bg-hover-solid)
Emphasis & translucency	Primary buttons and emphasized text (markdown-inline-code) go translucent but keep the brand hue: buttons at accent × panel opacity, text chips at accent × 0–45% (default 22%, matching the harness's own reference-chip alpha) — emphasis via hue, not solid fill
Bubble color	Dedicated bubble settings were removed: the harness renders its only bubble background on user messages (assistant turns have none), so bubbles follow the accent (at panel opacity); stock pale blue when no accent is set
Persistence	Browser localStorage (the harness settings gateway only allows browser writes for product namespaces), schema-validated and clamped on load

Compatibility & limitations

• Translucency is baked as plain rgba(); the sliders stay smooth at all values. Glass and background blur merge into one blur of the background layer (the sum of both sliders) — no backdrop-filter, so fixed-position elements never change their containing block; low-end devices can set the blur back to 0.
• Dark wallpapers or dark background colors trigger a coordinated surface-family flip; an explicitly set text color still wins.
• Each color role is a single value shared by both modes; derived colors are computed per mode automatically.
• Images: 2 MB compressed budget, 5 MB input cap; subject to localStorage quota. Persisted data is validated and clamped against the schema on load, so hand-edited or stale localStorage can never produce invalid styles.
• Video backgrounds: H.264 (MP4) or VP8/VP9 (WebM) recommended; unsupported codecs (e.g. HEVC) degrade back to the wallpaper automatically; replacing a video cleans up the old IndexedDB record.
• Syntax-highlight text colors (shiki --shiki-token-*) are a separate syntax-language palette and do not follow the accent (IDE convention); with a white accent, chip backgrounds are white and translucent, visually near-invisible on light surfaces — normal physics, not a bug.
• Bubbles follow the accent and have no dedicated color setting: the harness renders its only bubble background on user messages, and assistant turns have no bubble at all (a rendering fact the plugin cannot split); bubbles stay stock pale blue when no accent is set.

Package layout

src/
├── index.ts                  # Host half (empty apply, zero runtime deps)
├── invariant.ts              # Runtime invariant companion
├── appearance-settings.ts    # Settings types & defaults
└── client/
    ├── index.ts              # apply(): localStorage persistence, slot registration
    ├── applier.ts            # DOM applier (token overrides, background layer, glass)
    ├── tokens.ts             # Color roles → token mapping, presets, translucent baking
    ├── color.ts / image.ts   # Color utilities / image compression
    ├── video-store.ts        # IndexedDB video storage (20 MB cap)
    ├── color-scheme.ts       # Scheme export/import (pure functions)
    ├── settings-store.ts     # Settings mirror store
    ├── locales.ts            # zh/en copy
    └── AppearanceCustomizerRow.tsx + .module.css   # Settings row UI
tests/                        # Tests (`pnpm test` runs standalone; @deepseek-ai runtime replaced by tests/stubs)
types/client.d.ts             # Hand-written client-half type declarations
cordis.patch.yml              # Bundle patch
tsdown.standalone.config.ts   # Self-contained build
vitest.config.ts              # Standalone test config (aliases to tests/stubs)
lib/                          # Build output

All @deepseek-ai/* dependencies are optional peers provided by the host at runtime; the only runtime dependency is clsx. 97 vitest tests green (runnable standalone in this repo); CI build and artifact assertions green.

License

MIT