dsh-settings-beautify

One design language for the DSH settings surface.

简体中文

What it does

DSH's settings are composed from many plugins, and each page historically
speaks a slightly different typography and surface language — page titles in
16/18/22px, explanations in 12/13/14px, cards with 8/10/12px radii, controls
with their own heights and focus styles.

dsh-settings-beautify normalizes every settings page onto a single design
language:

• Architecture: every page is built from the same three-part hierarchy —
  标题 / Title → 解释 / Explanation → 内容 / Content (通用 General
  settings keeps its preference-row form, which is the same hierarchy in a
  compact variant).
• Typography: one size for every page title, one for every explanation,
  one for every item title and item description — regardless of which plugin
  contributed the page.
• Surfaces: consistent card radius/border/background, consistent rows,
  controls, focus rings, tabs, chips and scrollbars, all driven by DSH's own
  --dsw-* tokens, so light / dark / system themes keep working.
• Motion: subtle, tasteful hover micro-motion that respects
  prefers-reduced-motion and can be turned off.
• Extensible: any page — including pages contributed by other plugins,
  such as archived-conversation lists — opts into the same language with one
  attribute (data-dshb-scan), and the DOM normalizer handles the rest.
• Headless: the plugin adds nothing to the settings nav rail — no
  settings page of its own. Preferences are opt-in and live in
  localStorage.

It works without touching DSH's source: the plugin observes the settings
panel, marks each structural role with a stable data-dshb-* attribute (the
built-in class names are build-hashed and can't be relied on), and a scoped
stylesheet applies the language on top.

What is covered

Installation

From the plugin market

dsh-settings-beautify follows the DSH community-market package contract
(dsh.bundle.patch + dsh.client manifest), so it can be installed from the
market or with:

dsh plugin --profile  add dsh-settings-beautify

Manual install (development)

pnpm add dsh-settings-beautify        # into the profile's package set
# and ensure the bundle entry is declared, e.g. via the profile patch:
#   - insert:
#       - id: dsh-settings-beautify
#         name: dsh-settings-beautify

After install, restart DSH Desktop (or reload the web window). The design
language is applied automatically — nothing is added to the settings nav
rail.

Preferences (headless)

The plugin has no settings page of its own. Preferences are read from the
browser's localStorage under dsh-settings-beautify:prefs:

Defaults: {"enabled": true, "density": "default", "motion": true}. To tune
them, open the browser console and run:

window.DSHB.setPrefs({ density: "compact" })   // or { enabled: false }, { motion: false }

No host files or settings namespaces are touched.

The design language

The full specification — tokens, hierarchy, spacing/radius/motion scale, and
the data-dshb-* attribute contract — lives in
docs/DESIGN.md. A condensed version:

Cards: 12px radius · --dsw-alias-border-l2 · --dsw-alias-bg-layer-3 (elevated over the panel).
Controls: 8px radius, 36px min-height, brand focus ring. The title → caption
gap is a uniform 4px everywhere the language applies (--dshb-gap-title-desc,
matching DSH's row convention). Radii are tokenized (--dshb-*) so a future
version can offer alternate palettes.

Contributing pages from other plugins

The DOM normalizer auto-tags the built-in pages. For your plugin's page,
either:

1. Add data-dshb-scan to the page root (a third-party section hosted
   inside the settings dialog works the same way) — the normalizer then
   applies the same heading/prose/card/row/control rules generically,
   including the uniform 4px title → caption gap; or
2. Use the attributes directly (data-dshb-page-title,
   data-dshb-item-title, data-dshb-card, …) for full control.

See the extensibility contract.

Design notes

The plugin is intentionally headless: it only restyles the settings
surface. If you would rather have a visible control page, that is a small
follow-up change — open an issue and it can be added behind a preference.

Development

pnpm install
pnpm check             # syntax checks
pnpm test              # fixture-driven jsdom tests (135 assertions)
pnpm sync-styles       # regenerate lib/styles/settings.css from lib/client.js
pnpm capture-fixtures  # re-record test/fixtures/ from a running DSH Desktop

The tests do not hand-write a stand-in DOM. test/fixtures/.json is
captured from a running DSH Desktop — the settings panel's markup and the
stylesheets the host injects — and test/cascade.mjs recomputes the cascade in
jsdom (specificity, inheritance, var() substitution, the shorthands the tagger
reads). Every heuristic is therefore exercised against the computed styles the
real build produces, not against inline styles that would silently stop
matching it.

After a DSH upgrade: pnpm capture-fixtures, run pnpm test, and fix what the
new surface broke. The fixture is committed, so a regression is reproducible
offline without a browser.

Compatibility

• DSH 0.1.7-rc.2 (DSH Desktop, bundled web UI). Currently adapted through
  0.1.7-rc.2 against a captured fixture of that build.
• What 0.1.7-rc.2 changed underneath the plugin: the settings shell kept its
  contract (nav / content / header / options /
  [data-slot="settings.section"]), but every page below it was re-laid out —
  cards moved from 12px to 20px radius, the plugin-market page is gone
  (replaced by a searchable built-in plugin inventory), the DSH Desktop
  settings page no longer contributes a settings section, the header gained a
  second button, and tag/chip labels became a shared _tag_* primitive.
  0.3.0 removed the selectors that no longer exist and taught the tagger the
  new shapes (a preference row is now detected by its divider + padding, cards
  by their border box, chip labels by their pill radius).
• If the whole settings surface suddenly reverts to its unstyled form,
  first check whether another plugin in the same profile still imports
  host APIs that 2.0.5 removed (e.g. @deepseek-ai/dsh-typert-protocol
  stopped exporting TypertRemoteFailure in 0.1.2-rc.1) — one failing
  plugin import can take down the entire profile plugin tree and with it
  this plugin. The tagger is defensive: anything it cannot recognize is
  simply left untouched.
• The stylesheet only runs inside the settings panel scope; nothing outside
  settings is restyled.

Security

No network requests, no host APIs, no file access, no remote code. Preferences
live in localStorage. See SECURITY.md.

License

MIT — see LICENSE.