Introduction

In the DeepSeek Harness (DSH) plugin ecosystem, mature solutions exist for design generation from scratch and UI restoration from screenshots. However, a gap remains in the “discover issue → propose fix → verify fix” audit-and-optimization closed loop. The dsh-design-audit plugin fills this gap. It focuses on measurable objective criteria and provides an end-to-end workflow: headless Chrome forensics, deterministic rule validation, paste-ready CSS fixes, and retest delta verification.

Core Design

The plugin separates measurement from criteria. collect.js handles the collection of objective evidence, such as geometry calculations and style extraction; checks.js applies deterministic thresholds from WCAG 2.2 and platform guidelines to make graded determinations. The tools do not overstep by impersonating a visual reviewer; instead, they present objective evidence and screenshot paths, leaving aesthetic judgment to manual review.

Tools and Capabilities

The plugin provides three core commands, forming a complete audit closed loop.

  1. Headless Chrome evidence capture: Uses headless Chrome to open a URL or local HTML file, with support for multi-viewport full-page screenshots. Artifacts are written to <workspace>/.design-audit/<timestamp>/.
  2. Deterministic criteria and reporting: Runs design_review to generate a graded issue list based on WCAG 2.2 and platform guidelines, and outputs per-element CSS fix suggestions. Supports HTML or Markdown reports, including readable embedded first-view screenshots and archived full-page long-screenshot links.
  3. CSS fixes and retesting: Uses design_fix to generate a paste-ready CSS patch, with automatic backup of the original file. Uses design_review compare=<before 目录> to run a retest and outputs delta verification results.

Detection Scope

The plugin covers the following measurable criteria:

  • Accessibility: contrast, focus visibility, target size (44×44px), accessible names, image alternative text (alt), form labels, page language, heading hierarchy, and landmark regions.
  • Typography: minimum font size, line height (1.4.12), line length, and font-size/font-family scale.
  • Layout and interaction: horizontal overflow, spacing baseline grid, color count, and image size reservation (CLS).
  • Animation detection:
    • CSS animation fallback: Detects whether animation/transition has a prefers-reduced-motion: reduce fallback.
    • JS-driven animation: Detects GSAP, WAAPI, rAF, and other elements that continue animating under prefers-reduced-motion: reduce. Because inline styles written by JS are not controlled by CSS animation-duration: 0.01ms, fix suggestions directly provide JS-side matchMedia or gsap.matchMedia() patterns.
  • Occlusion detection: Uses center-point hit testing. If an element is partially obscured but its center is clickable, no error is reported (conservative approach to avoid false positives).

Typical Usage

Typical steps for running the audit closed loop:

# 1. 截取证
design_capture target=... label=before

# 2. 生成报告与问题清单
design_review

# 3. 视觉复核（人工使用 read_image 或直接看报告中的首屏图）
read_image <首屏截图>

# 4. 生成并应用 CSS 补丁（会自动备份原文件）
design_fix apply=true cssFile=styles.css

# 5. 再次取证
design_capture label=after

# 6. 对比修复前后的差值
design_review compare=<before 目录>

Installation

Installation command:

dsh plugin --profile web add dsh-design-audit

This plugin is distributed as a bundle and requires DSH version >= 0.1.0-rc.6. During development, source code can be injected using dev_inject_plugin.

Notes

  • Runtime dependencies: Requires local Chrome or Edge (can be overridden with the environment variable DSH_DESIGN_BROWSER). Uses Node.js built-in modules and global WebSocket, with zero npm dependencies; Node.js ≥ 22 is required.
  • SPA support: For single-page applications (SPAs), pass the waitFor parameter to specify a landmark selector. If the element count is less than 20, a warning is issued: “Possibly only captured an empty shell”.
  • Animation sampling: Animation detection requires time-based sampling (approximately 250 ms per viewport, approximately 0.5 s for two viewports). If an animation is shorter than the sampling window and does not repeat, it may not be detected.
  • Headless Chrome preference: Headless Chrome enables prefers-reduced-motion: reduce by default. Therefore, “observed motion” is equivalent to the element ignoring the reduce preference, which is exactly the violation being sought.
  • Build cache: If the project under audit uses a bundling approach with “hashed filenames + in-process build manifest caching” (for example, Flask’s dist_url), its service must be restarted after CSS or JS changes; otherwise, the retest may show 0 fixes.
  • Out-of-scope items: The plugin does not cover aesthetic judgment, hover/focus visual states, content and information architecture, or real performance sampling. These items are explicitly listed as “not covered” in the report.