<h1 align="center">harness-design</h1>
<p align="center">
English | <a href="README.zh-CN.md">中文</a> | <a href="README.ja.md">日本語</a> | <a href="README.ko.md">한국어</a> | <a href="README.es.md">Español</a> | <a href="README.zh-TW.md">繁體中文</a>
</p>
A Claude Code / Cursor marketplace plugin: a **design-dna** Phase 3 verification skill with **browser-based visual verification**. After an agent generates HTML from Design DNA JSON + content, this skill collects all page resources via console/network inspection, performs section-by-section screenshot comparison against the reference website, samples animation frames, and drives a correction loop until the output is ship-ready.
## Prerequisites
- [Node.js](https://nodejs.org/) installed
- Ability to run `npx` commands
### Optional (for full verification)
- [Playwright](https://playwright.dev/) — used by `web-shader-extractor` for resource collection
- Browser MCP tools — fallback when Playwright is unavailable
### Auxiliary Skills (recommended)
These skills provide domain expertise for deep effect verification:
```bash
npx skills add https://github.com/lixiaolin94/skills --skill web-shader-extractor
npx skills add https://github.com/greensock/gsap-skills --skill gsap-scrolltrigger
npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill 3d-web-experience
```
## Installation
### Quick Install (Recommended)
```bash
npx skills add zanwei/harness-design
```
### Install to Specific Agent
```bash
# Cursor only, non-interactive, global install
npx skills add zanwei/harness-design -a cursor -g -y
# Claude Code only
npx skills add zanwei/harness-design -a claude-code -g -y
```
### Install from Local Clone
```bash
git clone https://github.com/zanwei/harness-design.git
cd harness-design
npx skills add . -y
```
Install **only** the skill folder:
```bash
npx skills add ./skills/harness-design -y
```
### Register as plugin marketplace (Claude Code)
```text
/plugin marketplace add zanwei/harness-design
```
Then install the plugin from the marketplace UI, or:
```text
/plugin install harness-design@harness-design
```
### List skill metadata
```bash
npx skills add zanwei/harness-design --list
```
## Available Skill
| Skill | Description |
|-------|-------------|
| **harness-design** | 5-pass browser-based verification, weighted scoring, screenshot evidence, fix plan vs. DNA JSON + reference URL ([SKILL.md](skills/harness-design/SKILL.md)) |
References: [rubric](skills/harness-design/references/rubric.md) · [verification checks](skills/harness-design/references/verification-checks.md) · [browser verification](skills/harness-design/references/browser-verification.md)
## Workflow
```mermaid
flowchart LR
A["Design DNA JSON<br/>Phase 2 output<br/><br/>Immutable spec"]
B["Generated HTML<br/>Phase 3 output<br/><br/>Agent-produced design"]
R["Reference URL<br/>Original website<br/><br/>Visual ground truth"]
C["Harness Report<br/>Grade A–F · screenshots<br/><br/>Ship-ready output"]
A --> B
R --> C
B -->|"Pass 0 — Resource audit"| C
B -->|"Pass 1 — Mechanical checks"| C
B -->|"Pass 2 — Visual comparison"| C
B -->|"Pass 3 — Perceptual review"| C
B -->|"Pass 4 — Effects audit"| C
C -.->|"Score < 90 → correction loop"| B
```
1. [design-dna](https://github.com/zanwei/design-dna) Phase 2 → Design DNA JSON (from reference URL)
2. design-dna Phase 3 → generated HTML
3. **harness-design** → verify against both DNA JSON and reference URL, score, correct (loop until pass or iteration cap)
The harness **does not** modify the DNA JSON.
### 5-Pass Verification
| Pass | Name | Method |
|------|------|--------|
| **0** | Resource Audit | Collect network requests, console messages, canvas-info from both pages via Playwright or browser MCP |
| **1** | Mechanical Checks | DNA JSON token matching enhanced with actual browser-rendered values (getComputedStyle) |
| **2** | Visual Comparison | Section-by-section screenshot comparison between generated and reference pages |
| **3** | Perceptual Review | Qualitative style assessment based on screenshot evidence |
| **4** | Effects Audit | Animation frame sampling, scroll-trigger verification, 3D/shader deep inspection, CPU profiling |
### Scoring Dimensions
| Dimension | Weight |
|-----------|--------|
| design_system (tokens) | 25% |
| design_style (perception) | 20% |
| visual_effects (rendering) | 20% |
| resource_integrity | 10% |
| visual_alignment | 25% |
### Auxiliary Skill Integration
| Effect Type | Auxiliary Skill | Role |
|-------------|----------------|------|
| WebGL / Canvas / Shader | `web-shader-extractor` | Resource collection scripts + shader parameter extraction |
| GSAP ScrollTrigger | `gsap-scrolltrigger` | Scroll position verification + trigger point identification |
| Three.js / R3F / 3D | `3d-web-experience` | 3D rendering verification + engine analysis |
> [!TIP]
> **Iterative correction.** If the first verification produces a grade below A, the harness automatically generates a prioritized fix plan with screenshot evidence and drives a correction loop — up to 3 iterations — before recommending accept-as-is or re-generate.
## Compatibility
Follows the [Agent Skills specification](https://github.com/anthropics/skills). Installable via `skills` CLI to all supported agents including Cursor, Claude Code, Codex, GitHub Copilot, and more.
## Contributing
For behavior changes, update `skills/harness-design/SKILL.md`, `skills/harness-design/references/`, and bump `metadata.version` in `.claude-plugin/marketplace.json` together.
## License
MIT