dsh-web-theme-packs

English | 中文

Out-of-tree Web plugin: drop folders of theme files (colors, extra CSS, fonts, images) into a scanned directory, and the plugin registers them with ThemeRuntime so the existing layout presenter applies --dsw-* tokens. Multiple packs can sit side by side; Settings → General → Theme packs switches among them. This is a standalone bundle that will move to its own repository; it is not part of the shipped dsh-web-app roster.

Codex-style skins that replace window chrome, icon sets, and layout are a different format. A DSH pack overrides semantic tokens and may add CSS/assets on top of the three-column Web client. It cannot replace React icon components or rearrange columns.

Install

From this checkout, after pnpm install at the repository root:

pnpm --filter dsh-web-theme-packs bundle
pnpm dsh plugin --profile web add ./dsh-web-theme-packs
pnpm dsh web

dsh plugin add records the bundle on the profile. Removing it is pnpm dsh plugin --profile web remove dsh-web-theme-packs.

Pack format

Each pack is a directory that contains theme.json. Default scan roots are this package's themes/ (shipped examples) and $DSH_HOME/theme-packs (created on first load). Drop a new folder into the user root; the Host watches the directory and the browser refreshes the catalog.

theme.json:

{
  "id": "aero-blue",
  "name": "Aero Blue",
  "description": "Optional one-line label",
  "colorScheme": "light",
  "tokens": {
    "--dsw-alias-bg-base": "#c5e4f7",
    "--dsw-alias-brand-primary": "#1a5f9e"
  },
  "css": "theme.css",
  "preview": "preview.svg",
  "fonts": [
    { "family": "PackSans", "file": "fonts/pack.woff2", "weight": 400 }
  ]
}

Rules:

• id matches ^[a-z][a-z0-9-]*$ and must not be light, dark, or system.
• colorScheme is the base palette (body[data-ds-dark-theme]).
• tokens keys are CSS custom properties; values are strings. Relative url(...) values are rewritten to /dsh-theme-packs/<id>/....
• css, preview, and font file paths are pack-relative (no .., no absolute paths). Missing files skip that pack and leave the others loaded.
• Extra CSS may target body[data-dsh-theme-pack="<id>"]. Relative url() values are rewritten the same way.
• Pack JSON and CSS are data. The loader never evaluates JavaScript from a pack.

Inspect the live token directory with the Cordis tools (theme.exportInspectTokens) or by reading design-platform.css. A partial token map is valid; unspecified aliases keep the built-in sheet.

Shipped examples: themes/aero-blue (light glossy blue), themes/ink-night (dark navy), and themes/misty-forest (light fog-and-pine wallpaper).

Configuration

- id: web-theme-packs
  name: dsh-web-theme-packs
  config:
    roots:
      - !!js dshHomePath('theme-packs')
    routePrefix: /dsh-theme-packs

An empty roots list (the default) scans bundled themes/ then $DSH_HOME/theme-packs. Later roots win on duplicate ids. routePrefix must start with /, must not be /, and must not end with /.

The Host serves GET {prefix}/catalog.json, GET {prefix}/events (SSE revision stream), rewritten {prefix}/{id}/theme.css, and other pack files. The selected pack id is stored in the theme-packs.active settings section; Light / Dark / System under Appearance clears it.

Model Experience

None; the plugin manages a browser preference and static assets. Nothing here reaches a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

• Packs skin tokens and optional CSS, not the layout or icon components. A Codex QQ-2007 skin that redraws chrome and skeuomorphic icons has no equivalent asset map in this client.
• Third-party token sets are not completeness-checked. An incomplete override leaves built-in aliases in place, which can mix palettes.
• Custom pack ids are outside the built-in ui-theme.preference schema. Persistence of the selected pack is this plugin's theme-packs.active field; removing the plugin drops that selection without rewriting the last Appearance preference.