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

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