dsh-fuse-english

Page-level UI rendering plugin: describe a page in natural language → emit a structured spec fence → render a real page UI, with a pixel-level inspection loop.

English variant of KLRSL's dsh-fuse — MIT licensed.

v1.2.1 · MIT License · DSH ≥ 0.1.1-rc.2 (adapted for 0.1.2-rc.1) · Node ^22.19.0 || >=24.0.0

dsh-fuse-english is a DeepSeek Harness (DSH) plugin — and the plugin upgrade of the ui-aesthetics skill: it quantifies aesthetic rules into design tokens (theme.json) and distills code conventions into code-style.json, so the page-level UI it generates is correct by construction, and a closed-loop inspector refines the details down to the pixel.

What it does

The model gains one integrated UI design + code style capability, in three steps:

1. Generate — the model describes a page in natural language and emits a dsh-fuse-english fence (a structured JSON spec) in the body of its reply; every spec passes validate_fuse_spec first, so bad specs are rejected up front.
2. Render — the browser renders the spec into a real page UI, inline in the conversation flow; it is width-aligned with the composer (centered, 748px max) and never goes full-bleed.
3. Refine — click any element in the preview to collect getComputedStyle plus render state, correct it through the expected → observed → diff → fix loop, then emit the fence again and it re-renders. A ring buffer keeps the last 10 snapshots for undo.

Design philosophy: rules are the skeleton, semantics are the flesh, emotion is the breath. Every spec declares its emotional tone explicitly through theme (default / apple / dark), never ships placeholder shells, and keeps every spacing value on the 4/8px grid.

Features

| Feature | Description | | --- | --- | | One-shot generation | Natural language description → the agent emits a dsh-fuse-english fence → a real page UI renders | | Inline preview | Rendered inside the DSH conversation flow; 748px centered, the same width as the composer, never full-bleed | | Pixel-level inspection | Click an element in the preview → collect getComputedStyle + render state → [fuse-inspect] sent back to the model | | Render-state telemetry | viewport / overflow / clipped / primaryButtonCount — Spec valid ≠ Render correct | | Correction loop | expected (spec intent) → observed (actual render) → diff (localize the mismatch) → fix (re-emit the complete fence) | | Undo / history | A ring buffer keeps the last 10 snapshots; ↩️ in the preview card's top-right corner steps back | | Design tokens | theme.json: default / apple / dark themes, mapped to CSS variables — a new style is plug-and-play | | Design principles | Skeleton → flesh → breath; the four adaptation questions (product / audience / task / medium) are recorded in the root context | | Code style | Generated companion code must follow code-style.json (naming / formatting / syntax / CSS) | | Dual-channel rendering | Mounts directly when the host exposes the registerFenceRenderer extension point; stock DSH falls back to the DOM channel | | Dark mode | The plugin shell follows the DSH theme: dual-channel detection (body[data-ds-dark-theme] / prefers-color-scheme + MutationObserver) |

Installation

From npm (recommended)

# Swap --profile web for your own profile name
dsh plugin --profile web add dsh-fuse-english

From the English branch (git)

# Requires git; installs straight from the variant's branch
dsh plugin --profile web add github:My-DSH-plugins/dsh-fuse#english

Local bundle (development / link)

# Run from the project directory (the repo root is the package)
dsh plugin --profile web add link:.

dsh plugin registers the installed package into the profile's dsh.profile.bundles and mounts its patch automatically. Restart DSH once the install finishes (the HTML client injection takes effect at startup).

Verify after install

1. Host half — the startup log shows [dsh-fuse-english] startup complete: system prompt + validate_fuse_spec + /api/fuse/config; the system prompt contains the Fuse section (name: fuse, order: 106); the validate_fuse_spec tool registers successfully when the tools service is available.
2. Browser half — the console reports which channel is in use:
   • [dsh-fuse-english] fence-registry channel mounted (registry channel, contract host)
   • [dsh-fuse-english] fence-registry extension point missing (stock DSH) — enabling the DOM rendering channel (DOM channel)
3. Config API — GET http://localhost:<port>/api/fuse/config returns { themes, codeStyle, pageKinds, componentTypes }.

Then ask the model to "build a login page" — a rendered dsh-fuse-english preview card should appear directly in the conversation.

Safety note: fences go through a whitelist validation → render pipeline. An unknown component type rejects the entire spec; the node budget is 60 nodes / depth 8 on the host side and 200 nodes / depth 8 in the renderer.

Quick Start

The model emits a dsh-fuse-english fence in the body of its reply. Blocks still tagged with the upstream dsh-fuse tag (or carried over from the original plugin's docs) keep rendering too — the old tag is accepted as a legacy alias, so this variant can sit alongside the original without fighting over the fence name.

```dsh-fuse-english
{
  "type": "login_form",
  "title": "Welcome back",
  "subtitle": "Sign in to your account to continue",
  "theme": "default",
  "context": { "product": "Web", "audience": "Individual users", "task": "Sign in quickly and get to the workspace" },
  "components": [
    { "type": "input", "label": "Username", "placeholder": "Enter your username" },
    { "type": "input", "label": "Password", "placeholder": "Enter your password", "inputType": "password" },
    { "type": "row", "items": [
      { "type": "checkbox", "label": "Remember me" },
      { "type": "link", "label": "Forgot password?" }
    ]},
    { "type": "button", "text": "Sign in", "style": "primary", "full": true, "action": "login" }
  ]
}
```

What happens next:

• Validation — validate_fuse_spec checks the spec against the whitelist (page kinds / component vocabulary / container rules / budgets); bad specs are rejected before rendering.
• Rendering — the browser fetches the design tokens from /api/fuse/config, maps the chosen theme to CSS variables, and renders a live preview card; the card is 748px centered, the same width as the composer.
• Interaction — clicking the Sign in button, which carries "action": "login", sends [fuse-action] login back, and the conversation carries the flow forward (simulate the login / show an error / navigate away).
• Disabled state — buttons without an action render as disabled.

Page-level vs. card-level: dsh-fuse-english owns page-level UI (login pages / dashboards / settings pages / table pages / landing pages / profile cards / modals / forms); small in-conversation cards still use dsh-ui. The full grammar lives in SKILL.md.

Fence Specification

Root structure

{
  "type": "<page kind>",
  "title": "<page title>",
  "theme": "default",
  "context": { ... },
  "actions": [ ... ],
  "components": [ ... ]
}

Page kinds (root type, exactly one)

| Kind | Use case | | --- | --- | | login_form | Sign-in page | | signup_form | Registration page | | dashboard | Console / data overview | | settings_page | Settings page | | table_page | Data table page | | landing_page | Marketing landing page | | profile_card | Profile card | | pricing_page | Pricing / plan comparison | | modal | Modal / overlay | | form | General-purpose form page |

Component vocabulary (whitelist)

An unknown type rejects the entire spec.

| Category | Types | | --- | --- | | Containers | page card grid row col section tabs hero nav header footer form | | Display | text badge stat list table divider avatar chart steps | | Forms | input select textarea checkbox radio button link |

Field details (per SKILL.md): grid takes cols; tabs takes items (label + content); hero takes title/subtitle/actions; nav takes items; header takes title/subtitle; footer takes text; text takes size (h1/h2/h3/body/caption/muted), content, center; badge takes label + tone (success/warn/danger/accent); stat takes label+value; list items are strings or {title,desc}; table takes columns+rows; avatar takes name/color; chart takes kind (bars/donut/line) + data [{label,value,color}]; steps takes current + steps [{title,desc}]; input takes label/placeholder/inputType/action; select takes label/options/selected/action; textarea takes label/placeholder/action; checkbox/radio take label/checked/action; button takes text/style (primary/secondary/ghost/danger)/full/small/action; link takes label/href. Container components (page/card/grid/row/col/section/form) hold child nodes in items or components.

Root fields

| Field | Required | Meaning | | --- | --- | --- | | type | Yes | The page kind, exactly one from the table above | | components | Yes | Non-empty array of whitelisted components (≤ 60 nodes, depth ≤ 8) | | theme | Yes | A theme name from theme.json — never emit a themeless spec | | title | No | Page / card title | | context | No (recommended) | The conclusions of the four adaptation questions: { product, audience, task } — the renderer does not consume it, but the model's self-review and the inspection diff do | | actions | No | Primary page actions: [{ "action": "name", "label": "…", "tone": "primary\|ghost" }] |

Interaction callbacks

• Interactive components (button / input / select / checkbox / radio) that carry "action": "name" send [fuse-action] name back when clicked.
• Components without an action render as disabled.
• Form pages: input / select / textarea are labeled through the label field; the primary action uses style="primary" — exactly one primary button per page.

Design Language

Skeleton → flesh → breath (order is law)

1. Skeleton (rules) — information architecture and layout come first: page kind, module regions and hierarchy that are clear, traceable and logically self-consistent.
2. Flesh (semantics) — content and interaction in full detail: every block carries real text, real data and real buttons — never a placeholder shell.
3. Breath (emotion) — restraint: whitespace, subtle motion, low-saturation soft tones. Emotion comes from restraint, not from piling things on.

The order may not be reversed: skeleton first, then flesh, then breath — and never pick a pile of colors before you have thought through the structure.

The four adaptation questions (answer them before writing a spec)

1. What is the product? — Website / app / automotive HMI / smart wearable / data wall / 3D spatial UI…
2. Who is it for? — Target audience, usage scenario and reading environment.
3. What is the core task? — What the user came to accomplish; every screen serves a single focus.
4. What are the medium constraints? — Responsive breakpoints / touch target sizes / viewing distance / brightness and contrast.

Use the answers to choose the theme and tune density and hierarchy, then write the fence spec; record the conclusions in the context field.

Design tokens (config/theme.json)

| Theme | Character | Best for | | --- | --- | --- | | default (default) | White background, primary #2563EB, radii 8/12/16 | General-purpose tool pages | | apple | #F5F5F7 light gray background, large radii 10/14/18, SF type feel | Consumer pages | | dark | #0F1115 background, cyan/purple accents, glow | Data walls, developer tools |

• Colors come only from tokens: primary colors.primary, accent colors.accent, neutrals neutralBg/Surface/Text/Muted, borders border; feedback colors success #2E7D32 / warning #ED6C02 / error #C62828 (restrained saturation).
• Spacing grid 4/8/16/24/32; radii 8/12/16 (default and dark); type scale 12/14/16/20/28/36/48; line height 1.7 for body / 1.25 for headings.
• The brand section is the single source of truth for the plugin's brand color (fuse = blue-violet).

Style extension (a theme is a tone, not a new system)

A new style (cute / magazine-style…) means adding a theme to theme.json: reuse the 4/8px grid and the type scale, keep colors to "≤ 3 colors + neutrals", and change only the primary color / radii / shadows — never overturn the skeleton and breath rules. It takes effect in the renderer dynamically, with no code changes.

Shell and artifact are decoupled: the plugin's own UI (preview card, toolbar, settings page) follows the DSH theme (--fs-shell-* tokens, detected via --dsw-alias-* / data-ds-dark-theme); the rendered artifact follows the fence's theme (--fs-* tokens, scoped to the card root).

Walkthrough & Refinement

Spec valid ≠ Render correct. Passing validate_fuse_spec only means the spec is legal; the rendered result can still overflow, clip, duplicate the primary button or miss the intended hierarchy.

Inspector flow

1. The user clicks an element in the preview — selecting it highlights it (yellow = selected → blue = collecting → purple = correcting → red = failed).
2. The model receives [fuse-inspect], together with:
   • the element's getComputedStyle style data;
   • render state: viewport (preview container size) / overflow (whether it overflows) / clipped (whether the element is cut off) / primaryButtonCount (number of primary action buttons).

Correction loop (expected → observed → diff → fix)

1. expected — look back at what your own spec intended: the element's intended size / spacing / hierarchy / character count;
2. observed — read the style data and the render state;
3. diff — localize the mismatch: spacing / radii / color / font size / overflow / duplicated primary button;
4. fix — emit the complete corrected dsh-fuse-english fence and re-render; do not explain the process.

The preview card's top-right corner offers ↩️ undo (the last 10 snapshots) and 🔄 manual refresh.

Technical Architecture

dsh-fuse-english/
├── index.mjs               # Host half: system-prompt section registration + validate_fuse_spec tool + /api/fuse/config
├── client.js               # Browser half: fence renderer + inspector + undo history + settings page
├── config/
│   ├── theme.json          # Design tokens: ≤3 colors / 4-8px grid / type scale / radii; brand color
│   └── code-style.json     # Code style: naming / formatting / syntax / structure / React / CSS
├── cordis.patch.yml        # DSH cordis host bundle patch
├── SKILL.md                # Fuse skill: full fence grammar + aesthetics + self-review checklist
├── tests/                  # node --test unit tests, apply smoke, jsdom client loop, settings page render
├── README.md               # This file (the canonical, English README)
└── README.en.md            # Pointer to README.md (the plugin is English-only)

Host half (index.mjs) — registers the system-prompt section (name: fuse, order: 106, sitting between bash=104 and genui=105) and injects the fence grammar, a compact theme summary and a code-style summary into every request; exposes the validate_fuse_spec validation tool; serves GET /api/fuse/config (themes / codeStyle / pageKinds / componentTypes) so the browser can pull the full token set.

Browser half (client.js) — a zero-dependency, pure-DOM renderer (loaded through __ModuleLoader__), with installShellThemeSync() built in for following the DSH theme, plus the inspector and the undo mechanism.

Dual-channel rendering — each side probes the host independently:

• Registry channel: mounts directly when the host exposes registerFenceRenderer('dsh-fuse-english', …) (the DSH 0.1.2-rc.1 contract);
• DOM channel: stock DSH has no extension point → a MutationObserver scans the conversation flow for code blocks tagged dsh-fuse-english (pre, .md-code-block, [data-lang]) and takes over rendering (with a double-render guard, so a container and the <pre> nested inside it are each claimed only once).

Width contract — rendered cards are max-width: 748px (taken from --dsh-chat-content-width), centered, aligned with the composer, and never full-bleed.

Development

# Host unit tests (validator / system-prompt section / config loading)
node --test tests/fuse.test.mjs

# apply() registration smoke test
node tests/apply-smoke.mjs

# jsdom client closed loop (fence ⇒ DOM ⇒ inspect)
node tests/test-client.mjs

# Settings page rendering
node tests/test-settings.mjs

Node ^22.19.0 || >=24.0.0 is required (see engines). Dev dependencies: jsdom, react, react-dom.

Contributing

1. Keep the whitelists in sync — index.mjs (FUSE_COMPONENT_TYPES, FUSE_PAGE_KINDS) and client.js (CONTAINER_TYPES, DISPLAY_TYPES, FORM_TYPES, PAGE_KINDS) must match.
2. Add new themes to config/theme.json only — never change renderer code.
3. Any behavior change must keep the two token sets separate: --fs-shell-* (follows the DSH theme) and --fs-* (follows the fence theme).
4. Run the full test matrix before committing; keep class names as stable as you can.

Changelog

| Version | Date | Highlights | | --- | --- | --- | | v1.2.1 | 2026-09-05 | Adapted to the DSH 0.1.2-rc.1 frontend: registerFenceRenderer contract probing (mount directly when the host exposes the extension point, fall back to the DOM channel when it is missing) + dark-mode adaptation of the plugin UI (DSH-theme following, dual-channel detection + MutationObserver); brand color (blue-violet · design/rendering) written into the brand section of theme.json as the single source of truth | | v1.2.0 | 2026-09-05 | The plugin's own management UI rebuilt around skeleton/flesh/breath: the preview card shell, toolbar and settings page are all token-driven (--fs-* variables taken from theme.json), removing the hard dsw-alias dependency; fixed a React key warning; zero class-name changes, all tests green | | v1.1.0 | 2026-09-05 | Merged "rules are the skeleton, semantics are the flesh, emotion is the breath" with a general UI/UX prompt framework: the four adaptation questions, the root context field (validator-checked shape), and a style-extension guide (a new theme in theme.json with zero code changes); the inspection loop hardened — the renderer reports render state and the system prompt guides expected→observed→diff→fix | | v1.0.2 | 2026-09-03 | Fixed a DOM-channel double-render regression (both the code-block container and the nested <pre> were claimed → the same content rendered twice); metadata and README fully aligned; peerDeps relaxed to >=0.1.1-rc.2 | | v1.0.1 | 2026-08-28 | Renderer adapted to the DSH 0.1.1-rc.2 frontend; render container width aligned with the composer (748px centered, never full-bleed) | | v1.0.0 | — | First release: the upgraded ui-aesthetics skill (design tokens + code style + fence rendering + inspector + undo history) |

Acknowledgements

This project studied and drew on the data structures, interaction logic and design values of the following open-source projects during design and implementation (no core source code was copied):

• OpenPencil — design token system (the colors / spacing / typography / radius structure of theme.json)
• dsh-annotate / dsh-web-review — style inspection and feedback loops
• Airbnb / Google / Alibaba coding standards — code style (code-style.json)

License

MIT