# DSH Visual Acceptance Design Reference

> English companion to [DESIGN.md](DESIGN.md). The implemented UI and the Chinese reference remain the source for visual tokens and code-level detail.

## Purpose

The workbench is an operational UI for accepting a local Web prototype—not a marketing page and not a dashboard that turns signals into false approval. Its job is to let a person establish the target and coverage, inspect evidence, make an explicit decision, and retest under the original Matrix.

## Information hierarchy

1. **Start quickly:** Target, coverage plan, primary theme, generated Matrix summary, and one clear primary action.
2. **Declare scope when needed:** custom Matrix for additional pages or business states, including distinct Ready conditions.
3. **Inspect facts:** Run status, Ready evidence, deterministic signals, screenshots, and raw values.
4. **Make a human decision:** promote Candidate to Issue, append a Decision, and copy an approved change package.
5. **Retest carefully:** present candidate relations; never label a result as resolved until a person confirms it.

## Visual language

- Reuse DSH semantic tokens through CSS custom properties, with local fallbacks only for absent host tokens.
- Keep contrast, spacing, borders, type, and action density aligned with DSH rather than introducing a separate product theme.
- Use compact cards and progressive disclosure. Do not make a first-time user edit an eight-row state matrix before they can run a basic check.
- Visual hierarchy must clarify workflow state, not decorate it. Avoid gradients, large hero copy, score dials, and generic AI imagery.

## Responsive behavior

- **Desktop:** context and coverage remain visible while the result/evidence area supports dense inspection.
- **≤900px:** shift complex form rows to one column; preserve primary actions and state labels.
- **≤460px / 390px:** retain Quick mode as the first path; show the coverage summary before the action; stack form controls; never allow horizontal overflow or hide a primary action behind the DSH composer.

## Component rules

- **Coverage plans:** use a compact Quick / Standard / Page-breakpoint / Custom selector. Do not present six unrelated device buttons.
- **Responsive overview:** three or more results gain a Contact Sheet and grouped Candidate scopes; underlying evidence and Issues stay separate.
- **Custom Matrix:** make page, state, viewport, theme, and Ready condition editable; non-default states must not use an indiscriminate `body` Ready condition.
- **Run summary:** distinguish `running`, `completed`, `cancelled`, and `failed`. “Completed” means execution ended, not visual approval.
- **Evidence:** show screenshots and expandable raw browser signals. Signals are not Issues.
- **Issues and decisions:** creation, Decision history, approved change-package copy, and retest confirmation are visibly human actions.
- **Retest relations:** present `new-candidate`, `still-detected`, `possibly-resolved`, `regressed`, `not-verifiable`, and `needs-human-review` as relationships to inspect—not automatic verdicts.
- **Retest Diff:** show Baseline / Current / Diff with changed pixels and ratio; pixel change is a Candidate, never visual approval.
- **State recipe:** keep the six controlled actions behind progressive disclosure and warn against credentials or arbitrary scripts.

## Semantic guardrails

The following states must not be conflated:

| State | Meaning |
|---|---|
| Run completed | The execution finished. |
| Ready reached | The declared Ready condition was met. |
| Browser signal | A deterministic observation requires inspection. |
| Issue | A person decided the Candidate merits project-level tracking. |
| Resolved | A person confirmed the Issue after a retest. |

Avoid green “pass” language for any earlier state.

## Accessibility

- All controls have readable labels and keyboard focus.
- Icon-only actions expose an accessible name.
- Loading and polled Run-state changes need readable status text; error states use an alert semantics where appropriate.
- Do not rely on color alone; respect reduced motion; maintain useful focus indication.
- Touch targets and low-contrast helper text require rendered-client verification, especially in the DSH shell.

## Known limits

- The client currently uses a thin `conversation.view` integration and a host-header offset that must be retested against future DSH versions.
- Screenshots can prove visibility but do not alone prove hit-testing, keyboard behavior, or screen-reader announcement.
- This source candidate does not render reference-design comparison, OCR, real-device certification, or subjective AI visual judgement. Pixel Diff is limited to original-Matrix Retest evidence.