dsh-client-ui-m3-theme

Material 3 theme plugin for DeepSeek Harness (dual-face package): derives the full --dsw-* color-token set from a single primary color, with separate light/dark palettes, plus a settings panel for enabling the theme and choosing the color.

中文说明

Features

• Full mapping of ~65 visible --dsw-* color tokens (surfaces, borders, text, brand, buttons, interactive states, markdown, scrollbars, status colors, component-specific surfaces, toast/tooltip).
• Separate light/dark palettes derived from one primary color:
  • dark neutral surfaces/borders carry slightly higher chroma (M3 dark-scheme practice);
  • the dark primary palette boosts chroma to compensate for lost saturation on dark backgrounds;
  • tooltip is a fixed inverted surface (bubble text is static white), so its background stays dark in both modes;
  • the five text levels (primary → secondary → tertiary → caption → dimmed) align with the shipped lightness ladder.
• Settings panel "M3 Theme":
  • enable/disable switch for the whole token layer;
  • color-source switch: browser-local color (localStorage) or machine config (settings.yaml injection);
  • one custom primary color picker;
  • priority explainer card;
  • zh/en i18n — panel and nav copy follow the UI language.
• Persistence:
  • browser pick → localStorage key dsh.m3-theme.primary (instant effect, cross-tab sync);
  • machine config → settings.yaml namespace m3-theme (registered by the host half, injected into the page as window.__DSH_M3_THEME_PRIMARY__);
  • switches → dsh.m3-theme.enabled ('0' disables the layer) and dsh.m3-theme.useLocal ('0' ignores localStorage and uses the injected value).

Primary color resolution

useLocal switch	Resolution order
ON (default)	localStorage → settings.yaml injection → built-in purple #6750a4
OFF	settings.yaml injection → built-in purple #6750a4 (localStorage ignored)

Panel picks are written only to localStorage — they never write back to settings.yaml.

Install into a DSH profile

1. Add the git dependency to the profile's package.json:

   {
     "dependencies": {
       "dsh-client-ui-m3-theme": "github:DarkskyX15/dsh-client-ui-m3-theme#v0.2.0"
     }
   }
   

   To track the branch instead: "github:DarkskyX15/dsh-client-ui-m3-theme#main".

2. Insert the entry into the profile's cordis.patch.yml:

   - insert:
       - id: ui-m3-theme
         name: dsh-client-ui-m3-theme
   

3. Reinstall and restart DSH:

   pnpm install
   

   (The host half registers the settings namespace and injects the boot color; the client bundle is scanned at startup, so restart the DSH process.)

Usage

• Settings → M3 Theme: toggle the theme, choose the color source, pick the primary color.

• External config — edit ~/.dsh/settings.yaml:

  m3-theme:
    primary: "#39c500"
  

  With the "browser-local color" switch ON, the browser pick takes precedence over this value; turn the switch OFF to use it directly.

Structure

• lib/index.js — host half: registers the m3-theme settings namespace (schema validation) and injects the boot primary via webServer.tapIndex.
• lib/client.js — browser half: window.__ModuleLoader__.load registration, token derivation (hex↔HSL, tone stepping, per-mode palettes), the settings panel, and zh/en dictionaries.
• No build step: lib/ is the shipped artifact — commit changes directly.

Development

node --check lib/client.js   # syntax check
node --check lib/index.js

The browser bundle is served by the /plugins/<id>/client.js route, which reads the file from disk on every request (cache-control: no-cache): after editing lib/client.js a page refresh is enough. Changes to lib/index.js (host half) or package.json require a DSH restart.

License

MIT