English · 简体中文

dsh-user-experience

awesome · DSH plugin

A UX walkthrough plugin for DeepSeek Harness (DSH): AI simulates target users to uncover UX problems during development—before they reach production—and provides concrete optimization suggestions.

Scope: React + TypeScript / React + JavaScript / Vue 3, CSS/layout analysis, and optional browser evidence when the current Harness session can open the application.

🎉 Listed in awesome-dsh-plugin.

Existing automated checks (axe, Lighthouse) can only verify absolute rules — contrast ratio, missing alt text. But UX issues are inherently relative: a confirmation dialog before deleting protects an occasional user but wastes the time of an operator who processes hundreds of records a day. Without knowing who it's for, a "UX issue" cannot be defined.

This plugin makes target user personas the basis of every finding. If the project has no personas yet, the plugin infers a short draft from the README and routes—there is no setup command. By having AI walk through the product as those users, it surfaces experience problems during development and gives concrete, locatable, reviewable optimization suggestions—not post-launch user feedback.

It is a pipeline, not a CLI. Speak in plain language, or just edit a front-end file. There is no /ux command to learn. The report card leads with plain language (which page, what happened, how bad), and folds file paths and rule IDs into a "technical details" block you can copy straight to an AI in one click. Verdicts need no IDs either: click a button, or just say "the second one isn't a problem" or "ignore everything below level three".

Install in Harness

In DeepSeek Harness, enter:

Install the UX plugin in DeepSeek Harness: dsh plugin --profile web add dsh-user-experience@0.4.2

Or run the command directly:

dsh plugin --profile web add dsh-user-experience@0.4.2

Name an exact version rather than @latest: pnpm 11 holds back releases published in the last 24 hours, so @latest can resolve to nothing on a fresh profile. Check the npm version list for newer releases.

After a successful install, refresh the page. A restart is not required — restart or reload the web profile only if the market says it could not hot-load the plugin. Before installing, please read the security note.

Upgrading from a github: install

dsh plugin add github:DietCokewithSugar/dsh-user-experience no longer works. This repository stopped committing lib/, so a Git checkout carries no build artifacts, and pnpm blocks the build step by default. The market reports:

安装失败: dsh-user-experience — nothing installable: the plugin(s) need a build step
(blocked by default, see allowBuilds) or ship no prebuilt artifacts

and the exported log names the Git spec:

[warn]  install: github:DietCokewithSugar/dsh-user-experience: removed uninstallable pieces
        (no dsh manifest or missing build artifacts): dsh-user-experience
[error] install: github:DietCokewithSugar/dsh-user-experience: nothing installable survived validation

Install by package name instead — note there is no github: prefix:

dsh plugin --profile web add dsh-user-experience@0.4.2

If the market still resolves the Git ref, the profile is reusing its old entry. Clean it out:

1. Delete the "dsh-user-experience": "github:DietCokewithSugar/…" line from the profile's package.json.
2. Delete that profile's node_modules and pnpm-lock.yaml. The lockfile pins the old Git resolution, so removing the dependency line alone is not enough.
3. Run the install command again.

On Windows, this locates the profile manifest:

Get-ChildItem -Path $env:APPDATA,$env:LOCALAPPDATA,$env:USERPROFILE -Recurse -Filter package.json -Depth 6 -ErrorAction SilentlyContinue | Where-Object { (Get-Content $_.FullName -Raw -ErrorAction SilentlyContinue) -match 'dsh-user-experience' } | Select-Object FullName

Screenshots

The walkthrough report explains the observed behavior and user impact in plain language:

UX report card shown in Harness after installation

Speak in plain language to start a walkthrough. If personas are missing, the plugin drafts 1–3 users and asks once before continuing:

Start a walkthrough in natural language and confirm target personas

Once you confirm that a finding is real, the card provides a task Prompt you can copy to another AI. It describes the observed phenomenon rather than prescribing code changes, tells the AI to inspect the complete project context, and explicitly allows copy changes:

Confirmed UX finding with a copy-to-AI Prompt action

After you edit front-end code, the walkthrough runs itself—no persona questions, no interruption. It speaks up only for level-one / level-two issues:

Automatic walkthrough after a code change, without interrupting coding

Multi-level evidence appears in the technical details so every visual or interaction conclusion can be reviewed:

UX report with rendered and static evidence levels

The report card and confirmation workflow can use the developer’s language (English interface below):

English UX report card with interactive evidence

---

Supported inputs and evidence

Supported	Parsing engine
React + TypeScript (.ts / .tsx)	TypeScript compiler API (TSX)
React + JavaScript (.js / .jsx)	Same engine; .js may contain JSX, always parsed as TSX
Vue 3 (.vue SFC)	@vue/compiler-sfc block splitting + @vue/compiler-dom template AST; <script> / <script setup> blocks reuse the TypeScript engine, with line numbers remapped to the whole .vue file
CSS / SCSS / Sass / Less / PostCSS	Conservative spacing, compact-layout, and decorative-content candidates; visual conclusions still require a rendered page
Rendered page (optional)	When browser/screenshot tools and a runnable app are available, the agent inspects relevant routes and viewports
Persona task simulation (optional)	When the task can be executed in a browser, the agent records the steps and evaluates flow redundancy

Explicitly unsupported (reported as-is, no low-quality guesses): Svelte, Vue 2 (SFC syntax is incompatible with @vue/compiler-sfc), mini-programs (.wxml), etc. See the current implementation specification for evidence, product-type, and language behavior.

• Every finding is marked static, rendered, or interactive. Browser capability is optional: without it the walkthrough continues with static evidence and never pretends to have seen the page
• Layout-density, visual-language, and primary-action findings require rendered evidence; redundant-flow findings require an interactive persona walkthrough
• No automatic code changes: the plugin gives optimization suggestions; after you confirm a finding, it generates an observation-led task Prompt for a coding AI
• This is still evidence-bounded: CSS can identify inspection leads, but actual whitespace, hierarchy, and visual quality are not asserted without a real rendered route

Features

Capability	Entry point	Description
Natural-language walkthrough	just talk	Say “check the checkout flow” or “is this page usable?”. If personas are missing, the model drafts 1–3 from the README, asks “look through these users’ eyes?”, then walks immediately after you confirm
Persona context injection	automatic	Injects the active personas and walkthrough protocol into every request for the current project (aligned with the AGENTS.md section-provider pattern)
Source and CSS walkthrough	automatic	After scope is clear, walks each persona independently and merges one report; 27 rules based on Nielsen’s heuristics, with model judgment and AST/CSS verification
Product-specific focus	automatic	Infers consumer, enterprise, ecommerce, content, finance, healthcare, developer-tool, internal-tool, or other from project docs and the scoped flow, then applies the corresponding UX priorities
Multi-level evidence	automatic	static for source/CSS, rendered for real screenshots/DOM/measurements, and interactive for a recorded persona task. Missing browser capability degrades gracefully to static
Output language	automatic / config	Uses an explicit outputLanguage override first; in auto, follows the current user's language when supplied by the agent, then the project's primary README. Report cards and AI handoff Prompts support Chinese and English
Change-triggered walkthrough	automatic	After you edit a front-end file, the turn wraps up by walking the whole component / page that file belongs to — not the changed lines. Never asks about personas or scope. Missing personas are inferred as drafts. Speaks up only for level-one / level-two issues
Report card	automatic	The first screen is plain language only: [Level one] Admin page + one sentence on what happened + what the user runs into. File paths, rule IDs and internal numbering live behind "technical details", which expands to structured YAML you can copy to an AI in one click
Finding confirmation loop	card buttons / plain speech	Click Confirmed / Not an issue, or just say "the second one isn't a problem", "those are all right", "ignore everything below level three" — no ID is ever needed; verdicts go to the session log and fully restore on replay
AI task Prompt after confirmation	card button	Once a user confirms a finding, copy a ready-to-use Prompt that describes the observed behavior, affected scenario, user impact, and acceptance goal. It does not prescribe code changes, warns that the plugin saw only part of the codebase, and allows UI copy edits
Implicit confirmation	automatic	If a finding disappears in a later walkthrough and that location was actually re-scanned, the user fixed it — so the finding was real. Nobody clicks anything, and the signal is harder than a button press
Report output	automatic	Markdown sorted by severity (level one–four on screen; P0–P3 demoted to internal identifiers), common issues (hit by ≥2 personas) first
Glossary	automatic	R-02 term verdicts persist incrementally to .ux/glossary.yml; later rounds only compare deltas

Three run modes, picked by context

Mode	Behavior	When it applies
auto	Runs to completion, reports, never interrupts or asks for confirmation	CI / headless; change-triggered walkthroughs (the agent started it, so the agent digests it)
review	Reports, then offers one batch confirmation (tick several, submit together)	A user-initiated walkthrough in plain language
interactive	Confirms one finding at a time	Opt in manually when tuning rules

Resolution order: mode in .ux/rules.local.yml → plugin config → context detection.

The five-state finding machine

State	Meaning
pending	Not judged yet
confirmed_explicit	The user clicked "Confirmed"
confirmed_implicit	Gone in a later walkthrough, and that location was genuinely re-scanned
rejected	The user clicked "Not an issue"
stale	That location was not scanned this round (or the code was deleted outright) — undecidable

Both confirmed states count as effective findings in the metrics; stale is excluded from the denominator — "scanned and found nothing" must be distinguished from "never scanned