dsh-web-theme-packs

Readme

# dsh-web-theme-packs

English | [中文](README.zh.md)

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`](../packages/client/ui-theme/README.md) 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:

```sh
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`:

```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`](../packages/client/ui-theme/src/styles/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

```yaml
- 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.